Expand description
Deployment-trust ceremony automation for the setup wizard.
Node bootstrap (directories, node root key, per-service keypairs, CA-signed service JWTs) and deployment trust are separate concerns and stay separate: this module is opt-in and additive. Nothing here runs unless the operator asks for the ceremony.
What it adds is the decision an operator would otherwise make by reading
[docs/deployment-trust-ceremony.md]: is a hardware token attached, does its
firmware confine an Ed25519 key to the token, and — when nothing is attached
— is the operator willing to accept a software root that is only fit for
development.
Hardware access sits behind TokenDetector and AgeYubikeyPlugin so the
decision logic can be exercised without a token. The decision logic itself is
pure: plan_ceremony, select_mode_for_token, validate_break_glass
and ceremony_commands take values and return values.
Structs§
- Ceremony
Inputs - Every value the four trust invocations need.
- Ceremony
Mode Record - Machine-readable record of which mode ran, written beside the artifacts.
- Ceremony
Paths - Absolute paths of every ceremony input and output.
- Ceremony
Request - Everything the plan depends on that does not come from the token itself.
- Detected
Token - A token the detector reported as attached.
- Firmware
Version - A three-part YubiKey firmware version.
- System
AgeYubikey Plugin - Drives
age-plugin-yubikey, which needs a real TTY for PIN entry. - System
Token Detector - Enumerates tokens with
ykman list.
Enums§
- Break
Glass - The recovery half of the root recipient ring.
- Ceremony
Mode - How the deployment root will be protected.
- Ceremony
Plan - What the wizard decided to do about deployment trust.
- Detection
Error - Why the wizard could not learn whether a token is attached.
- Identity
File Kind - What a candidate break-glass identity file actually is.
- Plaintext
Policy - Whether an unprotected break-glass is tolerable for the root being minted.
- Unlock
Identity - The identity that unlocks the authority bundle during the delegation step.
Constants§
- CEREMONY_
MODE_ SCHEMA - Schema of the mode record written beside the ceremony artifacts.
- DEFAULT_
PIV_ SLOT - PIV digital-signature slot: PIN is demanded for every signature.
- DEV_
GRADE_ LABEL - Human-visible grade of a software root. Deliberately shouty.
- PIV_
ED25519_ MIN_ FIRMWARE - First firmware generation that can hold an Ed25519 key in a PIV slot.
Traits§
- AgeYubikey
Plugin - Creates and exports the PIV-backed age identity on an attached token.
- Token
Detector - Enumerates attached hardware tokens.
Functions§
- ceremony_
commands - Build the ceremony as the exact sequence of trust commands it runs.
- classify_
identity_ file - Classify a candidate break-glass file without decrypting it.
- create_
ceremony_ dir - Create the ceremony directory, owner-only.
- generate_
passphrase_ encrypted_ identity - Generate a passphrase-encrypted break-glass identity, returning its recipient.
- generate_
software_ identity - Generate a native age identity at
out, returning its recipient. - missing_
tools - Names from
required_toolsthatprobereports as absent. - mode_
record - Summarise a completed selection for the emitted record.
- parse_
age_ keygen_ recipient - Pull the public recipient out of
age-keygenoutput. - parse_
age_ plugin_ recipient - Pull the
age1yubikey1…recipient out ofage-plugin-yubikeyoutput. - parse_
ykman_ list - Parse
ykman listoutput. - plan_
ceremony - Decide what to do, given a detection result.
- required_
tools - External programs a mode needs on
PATH. - select_
mode_ for_ token - Resolve a chosen token to a mode, or block when no human can drive it.
- tool_
on_ path - True when
toolresolves throughPATH. - validate_
break_ glass - Reject a recipient ring that would leave the root weaker than it looks.
- write_
registry_ public_ key - Write the raw 32-byte registry-service public key the JWT mint binds to.