Skip to main content

Module at9p_chain

Module at9p_chain 

Source
Expand description

B1: did:at9p update-record chain validation — the successor-check (#885).

This module answers one question, purely and fail-closed: given a predecessor state (the genesis capsule or a previously-validated update-record) and a candidate update-record, is the candidate an authorized successor? It decides which key is authorized to sign the rotation and then enforces the four successor-check gates from design #879 §5.5/§7.1.

§KERI-style pre-rotation (the trust model)

did:at9p rotates keys the way KERI does: a capsule/record does not name the key that will be allowed to rotate it next — it commits to that key’s digest (next_key_commitments, the pre-rotation commitment). A rotation is an UpdateRecord that reveals the now-current keys in its new_capsule_body.subject_keys and is signed by them; the successor-check proves those revealed keys are exactly the ones the predecessor pre-committed to. Because rotation authority lives in keys that were only ever published as a hash until used, theft of a current signing key does not grant the ability to rotate the identity (design §7.1, A11).

§The four gates (validate_successor)

  1. Signer authorization — the update-record’s signing key (one of the revealed new_capsule_body.subject_keys, which is a published SET, not a positional singleton — #1188 / #1183) must have its HybridKeyPair::commitment_digest present in the predecessor’s next_key_commitments, and must actually have signed the record. This is the key-selection decision B1 owns: it tries each pre-committed revealed candidate and accepts the one that verifies, rather than trusting position 0 or a caller-supplied key.
  2. Linkage — prev_record_digest equals the predecessor’s record digest (H512 of its canonical bytes), chaining the segment back toward genesis.
  3. Monotonic epoch — strictly increasing epoch.
  4. Freshness — now < expires_at, with now supplied by the caller (this module does no clock I/O — it is a pure function so tests and the duplicity layer can drive time deterministically).

Any violation fails closed with a typed SuccessorError naming the failed gate. Success returns the candidate’s ChainState, ready to serve as the predecessor for the next link.

§What this is NOT: duplicity detection (B2, #886)

The successor-check validates a candidate against a single predecessor. It deliberately does not implement duplicity/fork detection — a second, divergent but individually valid successor at an epoch the client has already accepted (design §7.2). That watermark comparison is B2’s job, and this API is shaped to be wrapped by it: ChainState carries exactly the persistent (epoch, record_digest) pair B2 stores as its high-watermark, so B2 can compare a freshly validate_successor-accepted state against the persisted watermark and raise duplicity (hard fail + alarm) when a valid record diverges from the recorded digest at epoch <= watermark.

Structs§

ChainState
A validated point in an identity’s key-rotation chain: either the genesis capsule (ChainState::genesis) or a successfully validated update-record (the return value of validate_successor).

Enums§

SuccessorError
A typed successor-check failure. Every variant names the gate that failed; callers (and the B2 duplicity layer) can match on the specific reason.

Functions§

validate_successor
Validate that candidate is an authorized successor of predecessor as of now, enforcing every successor-check gate (design #879 §5.5) fail-closed.