Expand description
B2 (#886): KERI-style duplicity detection — the duplicity-check layer
that wraps B1’s validate_successor (#885) — and B3 (#887): the
empty/exhausted next_key_commitments commitment-lifecycle semantics.
B1 answers “is this candidate an authorized successor of this one
predecessor?” purely and locally. That is necessary but not sufficient
for did:at9p trust: an attacker holding stolen pre-committed keys, or an
equivocating identity holder, can mint a second, individually-valid
successor that diverges from the honest chain (design #879 §7.2, threats
A7/A12). B1 accepts each fork in isolation; only a client that remembers what
it already accepted can tell they are a fork.
§The watermark (R6 — the #879 BLOCKING-finding remediation)
This layer persists, per DID, a high-watermark of exactly the pair design #879 §7.2/R6 mandates:
(epoch, H512(accepted record))— the epoch and the accepted record digest, never the bare epoch.
A bare-epoch watermark is the exact bug the BLOCKING review found: an
attacker’s epoch N+1 exceeds a naive watermark N while silently replacing
the honest key state, and “accept the max epoch” would actively select the
attacker’s fork. Carrying the digest makes divergence detectable and makes
max-epoch selection impossible by construction:
- a candidate that advances the chain must chain through the persisted
watermark digest (its
predecessormust be the watermark head) — a higher-epoch record that chains through a different head is a fork, not progress (DuplicityKind::HigherEpochFork); - a candidate at
epoch == watermark.epochwith a different digest is a same-epoch fork (DuplicityKind::SameEpochFork); - any candidate at
epoch < watermark.epochis a branch reaching an already-passed epoch (DuplicityKind::BelowWatermarkFork) — we hold only the high-watermark, not full history, so a record below it is never preferred and never silently dropped: it fails closed.
Every one of those is duplicity: hard fail-closed for that DID plus an
operator alarm — never a mere “lower-epoch reject”, never a fork selection.
The watermark advances only on a non-divergent, honestly-anchored
successor. Non-advancing verdicts are classified from the candidate’s own
digest/epoch without running B1 (see DuplicityKind on why the alarm is an
unauthenticated divergence indication).
§B3 (#887): empty / exhausted commitment semantics
next_key_commitments governs whether an identity can ever rotate again:
- Empty at genesis = declared-immutable identity. Legal and useful (design
§7.1): the chain is frozen at genesis by construction and no update-record is
ever a valid successor. B1 already enforces this ([
SuccessorError:: ImmutableIdentity]); here it is formalized as a terminal watermark —Watermark::terminalis set the moment such a state is recorded, and this layer refuses to admit any successor against a terminal watermark without even re-running B1. - A rotation to empty commitments = exhausted / frozen-forever. A holder MAY publish a final rotation whose new capsule commits to no further keys. That final rotation is accepted (it is a valid successor of its predecessor); the resulting state is terminal, and the identity is frozen at that epoch forever. This is a feature, not an error (design §7.1): there is no recovery path, because a recovery path is a backdoor.
Both collapse onto the same terminal-watermark mechanism: an identity whose accepted head pre-commits to nothing admits no successor, ever.
§B4 (#888): durable alarm routing
This layer only raises the duplicity signal, as a typed DuplicityAlarm
delivered to a pluggable DuplicityAlarmSink. WalDuplicityAlarmSink
provides the production route: an fsync-on-write, hybrid-signed,
hash-chained journal with a signed head checkpoint, plus a structured
operator alarm through tracing / OTel. Detection and response remain
decoupled; callers that intentionally do not need durable routing may still
select NoopAlarmSink explicitly.
§Tamper-evidence (issue #888 acceptance: “durably recorded, tamper-evident”)
Every WAL entry AND the head checkpoint are signed with the same pinned
hybrid composite (EdDSA + ML-DSA-65) the at9p record path and the S7
mac::audit store use ([hyprstream_crypto::cose_sign::sign_composite],
require_pq = true). This is what makes the “tamper-evident” claim true
against a local writer that does not hold the signing key:
- altering any entry breaks its BLAKE3 chain link and its signature;
- rewriting the WAL to a shorter/forged valid chain is impossible without forging every replaced entry’s hybrid signature;
- truncating the tail leaves the earlier entries individually valid, but the signed checkpoint still anchors the true head — and the checkpoint cannot be rolled back to the truncated head without forging its hybrid signature.
Residual limit (honest, mirrors WalAuditStore in mac::audit): the
checkpoint is a local anchor. An attacker who can delete BOTH the journal
and the checkpoint entirely re-baselines to an empty log — total erasure is
not distinguishable from “no alarms yet” without an off-host anchor
(replicating the signed head to a second host / OTel). That off-host anchor
is deliberately out of scope here. What this store does guarantee: no
tampering, reordering, middle-deletion, or tail-truncation goes undetected
unless the attacker also holds the node’s audit signing key.
§Wiring (finding remediation)
Because WalDuplicityAlarmSink::open requires the node’s signing keys, the
durable route is a real construction path
(DuplicityGuard::with_durable_alarm), not a latent option: a production
guard built that way routes every real DuplicityGuard::admit_successor
detection to the signed, durable sink by construction. The NoopAlarmSink
default (DuplicityGuard::new) is the explicit test / opt-out path,
never the accidental production one. (The live mesh PEP that drives
admit_successor in the running daemon is a separate epic step and is not
claimed live here.)
§Persistence seam (#886/#1004)
WatermarkStore persists the complete accepted head/body together with
its watermark and terminal state. InMemoryWatermarkStore supports unit
tests; the running PDS implements the same contract with one synchronous
atomic RocksDB value, so recovery cannot pair a new watermark with an old
body (or vice versa).
Structs§
- Accepted
At9p State - Typed, re-verifiable current
did:at9pstate exposed to identity-bound resolver/admission consumers. - Duplicity
Alarm - A typed duplicity signal handed to the
DuplicityAlarmSink. Carries both sides of the divergence (the persisted watermark and the divergent record) so the routing layer (B4, #888) has everything it needs to audit or notify without re-deriving state. - Duplicity
Guard - The duplicity-detecting wrapper around B1 (#886, R6) with B3 (#887) commitment-lifecycle semantics folded in.
- InMemory
Watermark Store - In-memory
WatermarkStore— aMutex<HashMap<..>>. Suitable for tests and single-process use; not durable across restarts. Production wires this trait to the signed, checkpointed RocksDB store owned by the PDS service. - Noop
Alarm Sink - Explicit no-op sink for tests or deployments that route alarms elsewhere.
Detection still fails closed, but this sink provides no durable/operator
signal; production callers should use
WalDuplicityAlarmSink. - WalDuplicity
Alarm Sink - Durable, tamper-evident B4 duplicity-alarm sink.
- Watermark
- The persistent per-DID duplicity high-watermark: design #879 §7.2/R6’s
(epoch, H512(accepted record))pair, plus the terminal flag that carries B3 (#887) commitment-lifecycle state.
Enums§
- Accepted
At9p Head - Complete record retained as the accepted head.
- Accepted
At9p Provenance - Provenance of the durable accepted head. This identifies which verified
record supplies
AcceptedAt9pState::currentwithout claiming live key possession, endpoint reachability, admission, or global latest consensus. - Admission
- Outcome of admitting a candidate successor through the duplicity guard.
- Admission
Error - Why an admission failed. Every variant fails closed.
- Conditional
Advance - Duplicity
Kind - Which of the three fork shapes tripped duplicity detection. B4 (#888) can use this to grade the operator response; all three are equally fail-closed here.
Traits§
- Duplicity
Alarm Sink - Sink for
DuplicityAlarms (B4/#888 seam). Detection raises; routing the signal to the S7 audit store and/or an operator notification path is B4’s job. The guard has already committed to rejecting before this is called; durable implementations may synchronously fsync so returning from admission means the alarm is crash-durable. - Watermark
Store - Persistence seam for the complete accepted state and its per-DID duplicity watermark (#886/#1004).
Functions§
- record_
digest - Recompute a record’s
H512digest — the value stored as the watermark’srecord_digest. Exposed so callers reconstructing a watermark from a persisted record (e.g. on restart) key it the same way the guard does.