Skip to main content

Module op_log

Module op_log 

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

ActiveGeneration
The active #atproto generation, as resolved by a reader.
FixedGenerationSource
A single immutable generation — preserves the old PdsPublisher::new(store, did, signing_key) call sites behind the source abstraction.
SealedHeadEs256Source
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 seq it has accepted and rejects any regression (F2).
SealedOpLogHead
The on-disk sealed head: an authenticated, ordered projection of “which #atproto ES256 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§

ActiveGenerationSource
Source of truth for the active #atproto generation.

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