Expand description
JWT signing key rotation — multi-slot drain/active/lead lifecycle.
Keys live in three ordered slots: lead — pre-published (nbf in the future); clients see it in JWKS but no tokens use it yet active — current issuance key drain — old active, still valid for token verification until its exp passes
The background task checks every 6 h:
- lead.nbf <= now → promote lead → active, old active → drain
- drain exp + drain_days * 86400 < now → remove drain
- lead is None and active.exp - now < lead_days * 86400 → generate new lead, persist
Structs§
- Es256
KeySlot - Es256
KeySlots - Es256
Signing KeyStore - KeySlot
- KeySlots
- MlDsa
KeySlot - MlDsa
KeySlots - MlDsa
Signing KeyStore - Rotation
Stores - Additional stores to rotate alongside the primary Ed25519 store.
- Signing
KeyStore
Functions§
- global_
ed25519_ key_ store - Get or initialize the process-wide Ed25519 rotation store.
- global_
ed25519_ verifying_ keys - Get or initialize the global published-Ed25519 verifying-key handle.
- global_
es256_ key_ store - Get or initialize the global ES256 signing key store.
- global_
ml_ dsa_ key_ store - Get or initialize the global ML-DSA signing key store.
- global_
ml_ dsa_ verifying_ keys - Get or initialize the global ML-DSA verifying keys Arc.
- initialize_
composite_ key_ set - Restore exact persisted associations and atomically publish the complete signing/verifying/JWKS authority. Component stores are used only to resolve identities recorded in the ledger; they are never cross-paired.
- load_
or_ init_ es256_ key_ store - load_
or_ init_ key_ store - Load all three JWT key slots from
secrets_dir. - load_
or_ init_ ml_ dsa_ key_ store - load_
or_ init_ root_ identity_ key_ store - Load the root-DID identity rotation set, seeding the first active slot from the already-provisioned node identity key.
- refresh_
composite_ key_ set - Publish the post-rotation lifecycle as one atomic exact-pair snapshot.
- refresh_
ed25519_ verifying_ keys - Refresh the global published-Ed25519 verifying keys from a signing-key store snapshot (all current drain/active/lead slots).
- refresh_
ml_ dsa_ verifying_ keys - Refresh the published ML-DSA component-key snapshot.
- restore_
composite_ verifying_ key_ set - Restore the public exact-pair ledger in verifier-only service processes.
- rotate_
es256_ keys - Returns
trueif the active key was promoted (lead → active). An installed in-process promotion hook is invoked before the candidate becomes visible. - rotate_
jwt_ keys - Returns
truewhen every signer slot this cycle touched finished fully restored (or promoted).falsemeans a promotion rollback failed: the durable state is only partially restored, the old active signer stays recoverable in its drain-slot copy, and callers must not treat the cycle as a clean success. A later tick retries the queued lead. - rotate_
ml_ dsa_ keys - Returns
truewhen every signer slot this cycle touched finished fully restored (or promoted).falsemeans a promotion rollback failed: the durable state is only partially restored, the old active signer stays recoverable in its drain-slot copy, and callers must not treat the cycle as a clean success. A later tick retries the queued lead. - rotation_
state_ dir - Resolve the directory JWT rotation state is persisted to.
- spawn_
root_ identity_ rotation_ task - Rotate only the root-DID Ed25519 identity set.
- spawn_
rotation_ task
Type Aliases§
- Published
Ed25519 Keys - Live, shared handle to the node’s published Ed25519 rotation-slot verifying
keys (drain/active/lead). This is the SAME Ed25519 key set the
/oauth/jwksendpoint publishes — the keys that sign rotation-issued at+JWTs (WIT, S6 grant / token-exchange, and any issuance path using the active slot). It is public-key material only; no signing keys are ever exposed through it.