Skip to main content

Module enrollment_journal

Module enrollment_journal 

Source
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) returns AppendOutcome::Replay without a write (provision_epoch is 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§

ConflictRecord
A conflict record: the refused attempt plus the reason. The reconciler halts on conflicts until an operator resolves them out-of-band.
EnrollmentIntent
One enrollment intent: enroll subject (a DID or local username, per the provisioning subsystem) at clearance label, observed at provision_epoch (caller-chosen epoch, e.g. unix seconds).
EnrollmentJournal
Append-only enrollment-intent journal. Append serialization is enforced, not assumed (review F1):
JournalRecord
One durable journal record. seq is the journal-internal sequence, assigned monotonically from 0 with no gaps (enforced on open).

Enums§

AppendOutcome
Result of an EnrollmentJournal::append call.
ConflictReason
Why an attempted append was recorded as a conflict instead of an intent.
JournalError
RecordBody
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 from resolve_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.