Skip to content

0012: Registry authoring, retained history and dual-authorized key transitions

Date: 2026-10-20. Status: implemented software contract, pending owner protocol adoption and operational REGISTRY-ROOT approval. Implements W09 / #10. No prior research result is reused as v1 evidence.

Authoring and retirement

hallmark.registry.sign_snapshot signs an exact reviewed RegistryBody with caller-supplied Ed25519 key objects. It generates, loads and exports no private keys. Every signer must be authorized by the external TrustPolicy, distinct, valid and sufficient for its threshold. Signatures are sorted by key ID. The exact reviewed dependency remains cryptography 50.0.2, recorded in W08's dependency review. The lock and dependency versions are unchanged.

next_snapshot and validate_successor require the next sequence, exact predecessor digest and nondecreasing issuance time. Every previous (kind,digest) entry must remain, including expired and retired entries. Its validity interval and original review reference are immutable. retired_at can change from null to a timestamp, or to an earlier timestamp, never to null or a later timestamp. This makes revocation irreversible within a retained history. New identities carry explicit review digests. These references do not prove that a review took place or admit an artifact's quality; the owner must retain its source evidence. Opaque artifact digests still require independent content resolution.

Signing by itself does not establish a valid successor or freshness. Committing to the authoring history performs both checks. An expired snapshot is rejected; expired entry intervals remain for historical receipt checks. Retirement at or before verification time rejects use even for a historically valid receipt, unchanged from decision 0010.

Rotation

RegistryTransition is a strict frozen record with schema hallmark/registry-transition/1. It binds complete old/new trust identities, their sorted unique key IDs, activation_sequence, the prior registry digest, a bounded reason identifier and a review digest. SignedTransition has schema hallmark/signed-transition/1 and separate old/new signature lists, each 1..16.

Both externally supplied policies must authorize their own threshold. Each side signs u32be(len(tag)) || tag || canonical_transition_body, using respectively hallmark/v1/sign/registry-transition/old and hallmark/v1/sign/registry-transition/new. These are signature tags, not new artifact hash domains. A shared key must authorize each role separately. The transition exposes no independent hash identity or accepted flag.

Activation must be exactly the retained checkpoint's next sequence and predecessor. The old trust minimum cannot exceed that checkpoint; the new minimum must equal the activation sequence. The key set or its threshold must change. The complete new policy digest binds other owner-reviewed changes, too; changing an allowlist, limits, required claims or binding mode invalidates the authorizations. A transition supplied with no external new policy cannot enroll its own keys.

enroll_transition verifies both authorizations, the retained previous signed snapshot and its identity, successor retention, the new snapshot's signatures and current freshness. The previous snapshot can have expired; its independently retained digest and signatures still authenticate the history. It accepts exactly one activation. Further successors use normal enrollment under the new policy; another rotation needs another independently supplied policy and transition. One-sided, skipped, replayed and substituted transitions fail.

Emergency recovery after loss or compromise of an old threshold needs owner re-enrollment from an independently retained checkpoint. There is no unsigned replacement or emergency-bypass flag.

Checkpoints and authoring history

rotate_and_store performs transition verification, checkpoint comparison and update inside one existing SQLite write transaction. On its first successful enrollment, an existing W08 checkpoint database also records the supplied external trust digest in trust_binding. This lazy format extension and checkpoint update commit together. Later enrollment requires that exact policy digest; rotation requires the old digest and replaces it with the fully authorized new digest. This prevents reusing a retired policy against the same checkpoint store. Unrelated policy changes need owner re-enrollment in a new checkpoint store. No trust is discovered from the database or bundle.

The first successful binding also changes the checkpoint's SQLite application ID from HMR1 to HMR2 in that transaction. This implementation reads both formats; older W08 readers reject HMR2 instead of silently ignoring the trust binding. An HMR2 store with a missing binding fails closed. Preserve the original backup before upgrading; reverting the package is not a valid rollback of trusted state.

hallmark.registry_history is a separate authoring database with a distinct application ID. create_history exclusively creates it from an independently pinned signed checkpoint. append_history compares the expected latest state, checks complete successor content and trust continuity, and inserts one record. It stores exact signed snapshots, their body/trust identities and any signed transition. Earlier records are never overwritten or pruned. Duplicate sequence or digest insertions fail. UPDATE/DELETE triggers reject accidental mutation; readback verifies exact inserted bytes and transition retention before commit. read_snapshot checks the body against a caller-retained state; read_transition returns a record which still needs external-policy verification.

Both databases reuse the W08 owner-controlled local POSIX path checks and SQLite transaction settings. No file is implicitly created by read/update. Stale writers, concurrent locks, suppressed writes, statement/commit failures and process exit before commit are tested. The prior checkpoint, its trust binding and prior history survive the tested failures. History and relying-party checkpoints are separate roles/stores, not a distributed transaction.

These are local integrity and crash-recovery checks, not physical power-loss tests, global transparency or protection from a malicious OS account. Database owners can remove triggers or restore whole-store backups. Keep independent checkpoints and approved policy copies. Different relying parties can still be shown different validly signed roots; compare same-sequence digests out of band.

CLI, bounds and operational authority

hallmark registry-check SNAPSHOT --trust TRUST --state STATE --now SECONDS reads canonical CBOR and an already provisioned checkpoint database. Optional --history contains every successor after the checkpoint and before SNAPSHOT, up to 1,024. Rotation instead requires --old-trust, --transition and --previous together, with no intermediate history. It does not generate keys, provision state, fetch files or install a new trust-policy file.

Inputs must be explicitly supplied regular, non-symlink local files. File opens use no-follow/nonblocking flags and bounded reads; FIFOs, directories and oversized inputs fail. Trust-policy input is capped at 64 KiB. Total encoded snapshot/history bytes obey the caller's lower ceiling and hard 64 MiB limit. Rotation counts the prior snapshot, transition and activation together and honors the lower byte/depth caps of both policies. Existing per-record bounds and enrollment's elapsed-time checks apply. No new worker/RSS enforcement is claimed. Retained authoring history grows on disk; it has bounded record reads, no automatic pruning and no background writer.

Success emits only schema hallmark/registry-check/1, registry/trust IDs, sequence and check time, after commit. Errors use the existing sanitized finite error contract and exits. This command checks registry enrollment, not receipts, hardware, classifiers, proof execution or policy quality.

The committed fixture keys are explicit deterministic public test seeds. No operational roots were created, enrolled or rotated. The owner must record key custody and signature-library approval through the private REGISTRY-ROOT process before operational enrollment; software completion does not supply that approval.