Expand description
Enrollment-intent journal (#698 Phase 2) — the durable, append-only record of intent to enroll a provisioned subject into the MAC clearance table.
Design: docs/mac-architecture.md “Enrollment lifecycle (#698 Phase 2)”.
Provisioning code (hosted-account mint, OIDC JIT first login) appends one
intent record per newly provisioned subject. A later single-writer
reconciler folds acknowledged intents into an unsigned CompiledPolicy
for the offline trust sign-mac-boot-policy ceremony; the Policy
authority key never comes online.
Semantics (fail closed, mirroring the hosted-mint reservation):
- Idempotency: keyed intents (hosted:
transaction_id; JIT: the atomically-bound(issuer, subject)pair) replay as a no-op — same key AND same(subject, label)returnsAppendOutcome::Replaywithout a write (provision_epochis observational and excluded from the match). - Ambiguous retry ⇒ conflict: same key with a different payload, a subject already journaled under a different key, or a keyless retry of an already-journaled subject appends a conflict record. The reconciler refuses to enroll either copy until an operator disambiguates. There is no silent second intent.
- Durability (audit-journal pattern,
mac/audit.rs): each append is written, the file is fsynced, then the directory is fsynced before the intent is considered committed. A record is never acknowledged before it survives a crash.
The store is a single JSON-lines file under a journal directory. This is
deliberately the same local, fsync-ordered pattern as mac/audit.rs
rather than the deployment records store: the OAuth service already owns
the PDS root filesystem, and the reconciler is the single writer/reader —
no second backend (and its selection ambiguity) is introduced in the
provisioning hot path. Append serialization is enforced (process-global
cached writer per directory under one mutex in-process; non-blocking
exclusive flock cross-process — fail closed, never interleave); keep
the journal on a local filesystem.
Structs§
- Conflict
Record - A conflict record: the refused attempt plus the reason. The reconciler halts on conflicts until an operator resolves them out-of-band.
- Enrollment
Intent - One enrollment intent: enroll
subject(a DID or local username, per the provisioning subsystem) at clearancelabel, observed atprovision_epoch(caller-chosen epoch, e.g. unix seconds). - Enrollment
Journal - Append-only enrollment-intent journal. Append serialization is enforced, not assumed (review F1):
- Journal
Record - One durable journal record.
seqis the journal-internal sequence, assigned monotonically from 0 with no gaps (enforced on open).
Enums§
- Append
Outcome - Result of an
EnrollmentJournal::appendcall. - Conflict
Reason - Why an attempted append was recorded as a conflict instead of an intent.
- Journal
Error - Record
Body - The body of a journal record: a committed intent or a conflict.
Constants§
- DEFAULT_
ENROLLMENT_ CLEARANCE - Clearance label recorded for intents appended by the provisioning hooks.
- JOURNAL_
FILE_ NAME - Journal file name within the journal directory.
- LOCK_
FILE_ NAME - Cross-process writer lock file within the journal directory.
Functions§
- close_
cached_ writer - Drop the cached writer for
dir, releasing its flock. Used at shutdown and to hand the journal to another writer role (e.g. the reconciler opening the same directory after the OAuth writer is done). Returns true if a cached writer existed. - global_
journal_ dir - The process-global journal directory, if startup wiring installed one.
- hosted_
idempotency_ key - Idempotency key for a hosted-account mint: the signup transaction id the allocation reservation already binds to.
- hosted_
local_ idempotency_ key - Idempotency key for the LOCAL-USERNAME alias of a hosted-account mint:
same signup transaction as
hosted_idempotency_key, distinct subject. - hosted_
signup_ intents - The enrollment intents one hosted signup journals (#698 Phase 2): the hosted DID and the account’s local username, both at the default label.
- jit_
idempotency_ key - Idempotency key for OIDC JIT provisioning: the atomically-bound
(issuer, subject)pair fromresolve_or_bind_external_idp. Unit separator keeps the pair unambiguous even if either field contains:. - record_
intent - Convenience for the provisioning hooks: append one intent through the
process-global cached writer for
dir, serialized against every other in-process caller. The cached instance keeps its replay/conflict indexes in memory (no re-read per call); durability across restarts still comes from the journal file itself, re-validated on the first open. - set_
global_ journal_ dir - Install the process-global journal directory. Write-once; a second call fails rather than silently redirecting intents.