suaveplan/openspec/archive/2026-05-03-restore-crypto-keychain-packer-umbrella/specs/crypto-cli/spec.md

Capability Spec Delta: crypto-cli (restore-crypto-keychain-packer)

Package: @suaveplan/crypto-cli Status: PROPOSED

Every requirement below carries a **Verified by:** line at authoring time.

ADDED Requirements

Requirement: keychain binary surface

The package SHALL ship a keychain binary (declared in package.json bin) implementing eight subcommands: root init, server init, server roll, server revoke, inspect, verify, export-public, restore. The CLI is built on @suaveplan/cli (argument parser, command router, prompts, output formatters) and @suaveplan/readline (TTY input). All cryptographic work goes through @suaveplan/crypto; the CLI never imports @suaveplan/crypto-core directly.

Every subcommand supports --output json|binary|text (default text), reads/writes from stdin/stdout when paths are -, and emits OTel spans for the operation.

Scenario: every documented subcommand exists and is invokable

• WHEN keychain --help is run
• THEN the output lists exactly the eight subcommands above with one-line descriptions

Scenario: stdin/stdout streaming via -

• WHEN keychain inspect - is run with a packed public bundle on stdin
• THEN the inspector reads the bundle from stdin and writes the parsed report to stdout, exit code 0

Verified by: tests/cli-surface.test.ts::"help lists all eight subcommands" AND tests/cli-surface.test.ts::"inspect reads from stdin via -" AND src/commands/<command>.test.ts::"<command> emits an OTel span" (one per subcommand)

---

Requirement: TTY-only password input

The package SHALL accept passwords only through (a) the cli-package password prompt (TTY echo *), or (b) the KEYCHAIN_PASSWORD environment variable. A --password flag MUST be rejected at argument-parse time with CryptoError code CLI.PASSWORD_FLAG_FORBIDDEN and an exit code of 2 (usage error). The error message points the user at the two supported input paths.

This is a credential-handling rule: shell history is a documented credential leak path.

Scenario: --password flag is rejected

• WHEN keychain root init --password=hunter2 is invoked
• THEN the binary exits with code 2 and stderr names the forbidden flag and lists the two allowed alternatives

Scenario: env-var input works

• WHEN KEYCHAIN_PASSWORD=hunter2 keychain root init --output json is invoked in a non-interactive shell
• THEN the binary uses the env-var value, exit code 0

Scenario: TTY prompt works

• WHEN the CLI is driven via a fake InputReader (per cli package) and a password is supplied at the prompt
• THEN the binary uses the supplied password, exit code 0; the password is never echoed (the test asserts no plaintext appears in the captured TTY transcript)

Verified by: tests/no-password-flag.test.ts::"--password flag exits with code 2 and security pointer" AND tests/tty-mock.test.ts::"env-var KEYCHAIN_PASSWORD is consumed" AND tests/tty-mock.test.ts::"TTY password prompt does not echo plaintext"

---

Requirement: Distinct exit codes per failure class

The package SHALL exit with distinct, documented exit codes per failure class so operators can branch on them in scripts:

Code	Meaning
0	success
2	usage error (bad flag, missing argument, --password rejected)
10	bad password (VAULT.BAD_PASSWORD)
11	tampered vault (VAULT.TAMPERED)
12	expired key (KEYCHAIN.EXPIRED)
13	revoked key (AUTHORITY.REVOKED / CRL hit)
14	missing trust anchor (TRUST_ANCHOR.MISSING)
15	audit-log mismatch (AUDIT.TAMPERED)
16	replay rejected (PACKER.REPLAY_TOO_OLD / PACKER.REPLAY_NONCE_SEEN)

Every other failure exits with code 1.

Scenario: each documented exit code is reachable

• WHEN the CLI is driven into each documented failure class
• THEN the exit code matches the table above

Verified by: tests/exit-codes.test.ts::"each documented exit code is produced by its failure class"

---

Requirement: Idempotency on state-changing commands

The package SHALL accept --idempotency-key <key> on server roll and server revoke. The CLI maintains a local idempotency ledger at $XDG_STATE_HOME/suaveplan/keychain/idempotency.json (or platform equivalent). A repeated call with the same key returns the cached result without re-issuing or re-revoking; the cached result includes the original exit code.

The ledger entries expire after 24 hours; expired keys are treated as fresh.

Scenario: repeated roll with same idempotency key is a no-op

• WHEN keychain server roll --idempotency-key abc is invoked twice in succession
• THEN the first call succeeds and produces a new server identity; the second call exits 0 with the same output and does not append a second roll entry to the audit log

Verified by: src/commands/server-roll.test.ts::"idempotency key replays the cached result"

---

Requirement: Per-command behaviour

Each subcommand SHALL have documented inputs, outputs, and side effects. The full table MUST be captured in src/commands/COMMANDS.md and asserted by per-command tests. Every subcommand MUST be invokable with the same flags documented here without runtime drift.

Subcommand	Inputs	Output	Side effects
root init	--user-id, password (TTY/env), --mnemonic (optional)	encrypted vault + public bundle	writes vault to --vault-path, public bundle to --public-path; appends audit log if --audit-log is supplied
server init	root vault path, root password, --user-id, server password	server vault + signed public bundle	writes server vault, server public bundle, appends audit log, no CRL change
server roll	root vault, root password, server vault, server password, --idempotency-key	new server vault + new public bundle (version+1)	writes new files, appends CRL entry for prior version, appends audit log
server revoke	root vault, root password, server identity ref, --reason, --idempotency-key	CRL entry + audit-log entry	appends CRL, appends audit log; no new server identity
inspect	packed public bundle (path or -)	parsed report (text/json)	none (read-only)
verify	envelope (path or -), --trust-anchor, --crl	OK / failure with code	none (read-only)
export-public	vault path + password	public-only bundle	writes public bundle
restore	mnemonic (TTY/env), --user-id, --version, password	restored vault	writes restored vault

Scenario: each subcommand round-trips with itself

• WHEN root init produces a vault, then inspect reads its public bundle, then verify checks an envelope produced under that root, then export-public re-emits the public bundle
• THEN all four steps succeed end-to-end and the public bundles produced by root init and export-public are byte-equal

Verified by: tests/end-to-end.test.ts::"root-init → inspect → verify → export-public round-trips" AND src/commands/<command>.test.ts::"<command> happy path" AND src/commands/<command>.test.ts::"<command> failure modes" (one per command)