Expand description
C4 (#1170): the sealed op-log head — cross-process source of truth for the
active #atproto ES256 generation. Closes #1123.
Plan t1124 §3.4: under --ipc, discovery/registry/oauth agree on the active
generation with no event-delivery mechanism — every process reads ONE
sealed head that the rotator (OAuth) writes after each promotion. The
process-local OnceLock stays the rotator’s own working state; it is no
longer the source of truth for other processes.
§Credentials (split, least-privilege)
The head is signed by a dedicated Ed25519 keypair — NOT a key derived
from the CA root. The private key (oplog-head-key) is a secret held only
by the rotator; the public verifying key (atproto-oplog-head-pubkey) is
published to the shared state dir and loaded by readers. A process that can
verify a head therefore cannot forge one (F3). Readers never touch
ca-key (which is PolicyService-only under systemd IPC).
§Head state directory (F4)
The head is a signed, public artifact — it carries no secrecy, so it does
NOT live in the read-only per-unit credentials directory. It lives in a
dedicated shared writable state dir (resolve_oplog_state_dir),
env-overridable so a systemd --ipc deployment can point it at a shared
StateDirectory=. Where that shared storage is provisioned is deployment
plumbing (#808); this module takes the path, never assumes secrets_dir.
§Consistency guarantee (implemented)
A reader is NOT guaranteed to observe a rotation instantaneously (bounded
by one rotation tick + filesystem visibility). The fail-closed contract:
the reader verifies the head’s node signature, rejects a seq
regression against both the highest generation it has observed in memory
and the rotator’s durable high-water mark, and resolves the signing key
by kid from the key-material store. A retired key is never presented as
active; replaying only an older-but-valid head is rejected even after a
reader restart. As with any node-local checkpoint, coordinated rollback of
the head and its high-water mark is outside this file-level guarantee.
§Dependency honesty — C2 (#1168) is not built
seal_op_log_head is rename-atomic at the file level. C2 must harden
the full rotation ordering — re-sign repo head → durably write head →
seal DidOp → publish — as one crash-atomic unit, so no crash leaves a
head naming a key whose repo head was not durably re-signed. Full
crash-injection at every boundary is C2’s job; the writer verifies every
prior head before carrying its seq/prev forward (F5). This is NOT the
DidOp format (C1 #1167) and does not encode rotation-key custody (epic
#1158 Q2 / one-way door #4); the projection carries its own version.
Structs§
- Active
Generation - The active
#atprotogeneration, as resolved by a reader. - Fixed
Generation Source - A single immutable generation — preserves the old
PdsPublisher::new(store, did, signing_key)call sites behind the source abstraction. - Sealed
Head Es256 Source - Cross-process reader of the sealed op-log head. Holds NO private key
material — it loads the head-signing verifying key from the shared state
dir, so a process that can verify a head cannot forge one (F3). It tracks
the highest
seqit has accepted and rejects any regression (F2). - Sealed
OpLog Head - The on-disk sealed head: an authenticated, ordered projection of “which
#atprotoES256 generation is active right now.”
Constants§
- HEAD_
SIGNING_ KEY_ NAME - Secret seed for the head-signing Ed25519 key (rotator only).
- HEAD_
VERIFYING_ KEY_ FILENAME - Public verifying key for the head signature (all readers).
- OPLOG_
STATE_ DIR_ ENV - Env override for the shared head state dir (#808 systemd seam).
- PROJECTION_
VERSION - Projection format version (NOT the DidOp format — C1 #1167 owns that).
- SEALED_
HEAD_ FILENAME - The sealed head file.
- SEALED_
HEAD_ MAX_ SEQ_ FILENAME - Durable sequence high-water mark, written by the rotator after each head.
Traits§
- Active
Generation Source - Source of truth for the active
#atprotogeneration.
Functions§
- advance_
sealed_ head - Resolve the head state dir + dedicated head key, publish the verifying key, and seal the current ES256 active generation in one call. This is the rotator’s full “advance the sealed head” step (boot + each rotation tick).
- load_
head_ verifying_ key - Load the head-signing verifying key from the shared state dir (readers).
- load_
or_ init_ head_ signing_ key - Load or initialize the dedicated head-signing Ed25519 key (rotator only).
- publish_
head_ verifying_ key - Publish the head-signing verifying key to the shared state dir (public).
- resolve_
oplog_ state_ dir - Resolve the shared, writable head state dir.
- seal_
op_ log_ head - Write the sealed op-log head after a promotion (or at boot). The public
operation remains async for its rotator call sites, while the ES256 store
snapshot uses its synchronous
parking_lotread guard. This is the C2 (#1168) seam: rename-atomic at the file level; the full crash-atomic rotation ordering is C2’s guarantee (see module docs).