pub struct DuplicityGuard<S: WatermarkStore, A: DuplicityAlarmSink> { /* private fields */ }Expand description
The duplicity-detecting wrapper around B1 (#886, R6) with B3 (#887) commitment-lifecycle semantics folded in.
Holds the WatermarkStore (persistence seam) and the DuplicityAlarmSink
(B4/#888 routing seam). Usage:
- Verify a genesis capsule externally (GATE 1/2), build its
ChainState(ChainState::genesis), andseed_genesisit. - For each candidate update-record, resolve its predecessor state and call
admit_successor. B1 runs first; the watermark reconciliation runs second and can only ever reject a B1-valid record (duplicity) or advance on honest progress — never select a fork.
Implementations§
Source§impl<S: WatermarkStore> DuplicityGuard<S, NoopAlarmSink>
impl<S: WatermarkStore> DuplicityGuard<S, NoopAlarmSink>
Sourcepub fn new(store: S) -> Self
pub fn new(store: S) -> Self
Build a guard whose alarm routing is explicitly disabled — the test /
opt-out path. This installs NoopAlarmSink, so a real detection is
classified and fail-closed but produces no durable, tamper-evident
record. Production MUST NOT use this: build the guard with
with_durable_alarm (the signed WAL
route) or with_alarm with an equivalent durable
sink, so callers opt out of durable routing deliberately rather than
keeping it off by accident.
Source§impl<S: WatermarkStore> DuplicityGuard<S, WalDuplicityAlarmSink>
impl<S: WatermarkStore> DuplicityGuard<S, WalDuplicityAlarmSink>
Sourcepub fn with_durable_alarm(
store: S,
wal_path: impl AsRef<Path>,
ed_sk: SigningKey,
pq_sk: MlDsaSigningKey,
) -> Result<Self>
pub fn with_durable_alarm( store: S, wal_path: impl AsRef<Path>, ed_sk: SigningKey, pq_sk: MlDsaSigningKey, ) -> Result<Self>
The production construction path: build a guard that routes every
admit_successor duplicity detection to a
durable, hybrid-signed, tamper-evident WalDuplicityAlarmSink at
wal_path, signed with the node’s audit keys (ed_sk / pq_sk).
Opening the sink verifies (or baselines) the existing journal, so a
corrupt/forged/truncated log fails closed before the guard is usable. Use
this — not new — anywhere a real did:at9p chain is
admitted, so a fork is always durably recorded and surfaced to an operator
(issue #888 acceptance).
Source§impl<S: WatermarkStore, A: DuplicityAlarmSink> DuplicityGuard<S, A>
impl<S: WatermarkStore, A: DuplicityAlarmSink> DuplicityGuard<S, A>
Sourcepub fn with_alarm(store: S, alarm: A) -> Self
pub fn with_alarm(store: S, alarm: A) -> Self
Build a guard with an explicit alarm sink (the B4/#888 routing seam).
Sourcepub fn seed_genesis(
&self,
genesis: &VerifiedCapsule,
) -> Result<(), AdmissionError>
pub fn seed_genesis( &self, genesis: &VerifiedCapsule, ) -> Result<(), AdmissionError>
Seed complete accepted state for a DID from its unforgeable
VerifiedCapsule GATE witness (epoch 0).
Anti-rollback (FIX in #959): refuses to overwrite a watermark that
is already-advanced (epoch > 0) or that anchors a different genesis
digest — a stray or hostile re-seed must never move the anti-rollback
anchor backward. The only overwrite permitted is an idempotent re-seed
of the exact same genesis (epoch 0, identical record_digest), which is
a no-op success. The per-DID admission lock is held across the
read-then-conditional-advance so this check is race-free against a
concurrent admit_successor.
If the genesis pre-commits to no next keys, the seeded watermark is
terminal immediately — a declared-immutable identity (B3, #887).
Callers must seed only from a genesis they have themselves verified
(H512(bytes) == cid512 + self-signature).
Sourcepub fn watermark(
&self,
subject_cid512: &str,
) -> Result<Option<Watermark>, AdmissionError>
pub fn watermark( &self, subject_cid512: &str, ) -> Result<Option<Watermark>, AdmissionError>
The current persisted watermark for a DID, or None if unseeded.
Sourcepub fn accepted_state(
&self,
subject_cid512: &str,
) -> Result<Option<AcceptedAt9pState>, AdmissionError>
pub fn accepted_state( &self, subject_cid512: &str, ) -> Result<Option<AcceptedAt9pState>, AdmissionError>
Complete accepted current state, including current authorized body and provenance. This is state acceptance only, never reach/liveness or live possession/admission authority.
Sourcepub fn admit_successor(
&self,
candidate: &UpdateRecord,
now: &str,
) -> Result<Admission, AdmissionError>
pub fn admit_successor( &self, candidate: &UpdateRecord, now: &str, ) -> Result<Admission, AdmissionError>
Admit candidate as a successor of predecessor as of now, enforcing
B1 and duplicity detection (R6) and B3 terminal semantics,
fail-closed throughout.
§Predecessor anchoring (#961 — the provenance boundary)
The predecessor is loaded from the complete durable accepted state, not
supplied by the caller. The guard recomputes the predecessor’s
H512 and anchors it against the persisted Watermark::record_digest
before B1 runs, then derives the authoritative ChainState from the
anchored record. This proves the next_key_commitments B1’s
signer-authorization gate keys off belong to the anchored head — an
attacker who only knows the honest digest cannot authorize a pre-rotated
evil key, because the commitments are read from the record’s bytes (whose
hash must match the watermark), never from a caller claim. Caller-supplied
unverified ChainState is no longer expressible in the API.
§Concurrency (FIX in #959)
The whole classify-then-advance read-modify-write is serialized per-DID
by a held admission lock, so two concurrent divergent epoch-(N+1)
successors of the same head result in exactly one
Admission::Advanced (the winner, which advances the watermark) and the
other(s) classified as a fork (DuplicityKind::SameEpochFork once the
watermark has moved to epoch N+1) — never two Advanced.
§Order of checks (each fails closed before the next)
- Idempotent replay —
epoch == watermark.epochwith the candidate’s recomputedH512equal to the watermark digest is a byte-identical re-presentation of the accepted head →Admission::AlreadyKnown, even when that head is terminal (a caller retrying a lost response after aAdmission::Frozenacceptance must be able to learn it succeeded). - Terminal watermark (B3) — if the DID’s accepted head pre-commits to nothing, no new successor is admissible; reject without consulting B1.
- Position vs watermark (by the candidate’s OWN digest) — for any
remaining candidate at
epoch <= watermark.epoch, the verdict depends only on the candidate (its epoch and its recomputedH512), never on a caller-supplied predecessor. So B1 is not run and no predecessor commitments are consulted, which is the #961 invariant in the small: the guard never trusts a predecessor field to classify a non-advancing record. Because B1 cannot run here (complete current-head persistence does not retain the committing predecessor atepoch - 1), these duplicity verdicts are unauthenticated divergence indications, not proof the identity holder signed the divergent record — seeDuplicityAlarm.epoch < watermark→DuplicityKind::BelowWatermarkFork;epoch == watermark(digest necessarily differs after step 1) →DuplicityKind::SameEpochFork.
- Advance path — anchor then B1 (#961) — for
epoch > watermark, recompute the predecessor’sH512and require it to equal the watermark digest BEFORE B1 runs, then derive the authoritativeChainStatefrom the anchored record. A predecessor that does not hash to the watermark is a foreign fork head (or a forgery attempt that cannot pair evil commitments with the honest digest) →DuplicityKind::HigherEpochFork; itsnext_key_commitmentsare never seen by B1. With the predecessor proven to be the head, B1 (validate_successor) decides the final gate; on success the watermark advances —Admission::Frozenif the new head is terminal, elseAdmission::Advanced.
A duplicity verdict raises the alarm on the sink and returns
AdmissionError::Duplicity; the watermark is left unchanged (a fork
never moves the honest watermark).
Auto Trait Implementations§
impl<S, A> !Freeze for DuplicityGuard<S, A>
impl<S, A> !RefUnwindSafe for DuplicityGuard<S, A>
impl<S, A> Send for DuplicityGuard<S, A>
impl<S, A> Sync for DuplicityGuard<S, A>
impl<S, A> Unpin for DuplicityGuard<S, A>
impl<S, A> UnsafeUnpin for DuplicityGuard<S, A>where
S: UnsafeUnpin,
A: UnsafeUnpin,
impl<S, A> !UnwindSafe for DuplicityGuard<S, A>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more