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)
- 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 itsHybridKeyPair::commitment_digestpresent in the predecessor’snext_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. - Linkage —
prev_record_digestequals the predecessor’s record digest (H512of its canonical bytes), chaining the segment back toward genesis. - Monotonic epoch — strictly increasing epoch.
- Freshness —
now < expires_at, withnowsupplied 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§
- Chain
State - 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 ofvalidate_successor).
Enums§
- Successor
Error - 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
candidateis an authorized successor ofpredecessoras ofnow, enforcing everysuccessor-checkgate (design #879 §5.5) fail-closed.