Skip to main content

DuplicityGuard

Struct DuplicityGuard 

Source
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:

  1. Verify a genesis capsule externally (GATE 1/2), build its ChainState (ChainState::genesis), and seed_genesis it.
  2. 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>

Source

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>

Source

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>

Source

pub fn with_alarm(store: S, alarm: A) -> Self

Build a guard with an explicit alarm sink (the B4/#888 routing seam).

Source

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).

Source

pub fn watermark( &self, subject_cid512: &str, ) -> Result<Option<Watermark>, AdmissionError>

The current persisted watermark for a DID, or None if unseeded.

Source

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.

Source

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)
  1. Idempotent replay — epoch == watermark.epoch with the candidate’s recomputed H512 equal 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 a Admission::Frozen acceptance must be able to learn it succeeded).
  2. Terminal watermark (B3) — if the DID’s accepted head pre-commits to nothing, no new successor is admissible; reject without consulting B1.
  3. 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 recomputed H512), 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 at epoch - 1), these duplicity verdicts are unauthenticated divergence indications, not proof the identity holder signed the divergent record — see DuplicityAlarm.
  4. Advance path — anchor then B1 (#961) — for epoch > watermark, recompute the predecessor’s H512 and require it to equal the watermark digest BEFORE B1 runs, then derive the authoritative ChainState from 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; its next_key_commitments are 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::Frozen if the new head is terminal, else Admission::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>
where S: Unpin, A: Unpin,

§

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> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn map_response_body<F>(self, f: F) -> MapResponseBody<Self, F>
where Self: Sized,

Apply a transformation to the response body. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSync for T
where T: Sync,

§

impl<T> MaybeSync for T
where T: Sync,