Skip to main content

Module at9p_duplicity

Module at9p_duplicity 

Source
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 predecessor must 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.epoch with a different digest is a same-epoch fork (DuplicityKind::SameEpochFork);
  • any candidate at epoch < watermark.epoch is 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::terminal is 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§

AcceptedAt9pState
Typed, re-verifiable current did:at9p state exposed to identity-bound resolver/admission consumers.
DuplicityAlarm
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.
DuplicityGuard
The duplicity-detecting wrapper around B1 (#886, R6) with B3 (#887) commitment-lifecycle semantics folded in.
InMemoryWatermarkStore
In-memory WatermarkStore — a Mutex<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.
NoopAlarmSink
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.
WalDuplicityAlarmSink
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§

AcceptedAt9pHead
Complete record retained as the accepted head.
AcceptedAt9pProvenance
Provenance of the durable accepted head. This identifies which verified record supplies AcceptedAt9pState::current without claiming live key possession, endpoint reachability, admission, or global latest consensus.
Admission
Outcome of admitting a candidate successor through the duplicity guard.
AdmissionError
Why an admission failed. Every variant fails closed.
ConditionalAdvance
DuplicityKind
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§

DuplicityAlarmSink
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.
WatermarkStore
Persistence seam for the complete accepted state and its per-DID duplicity watermark (#886/#1004).

Functions§

record_digest
Recompute a record’s H512 digest — the value stored as the watermark’s record_digest. Exposed so callers reconstructing a watermark from a persisted record (e.g. on restart) key it the same way the guard does.