suaveplan/openspec/archive/2026-05-03-restore-crypto-cli-and-allowlist/proposal.md

restore-crypto-cli-and-allowlist — keychain CLI, slsa migration, import-allowlist gate

Packages: @suaveplan/crypto-cli (new), @suaveplan/slsa (modified), @suaveplan/crypto-core (allowlist gate) Status: PROPOSED Type: new-package + refactor + conformance gate Carved from: restore-crypto-keychain-packer umbrella (2026-05-03) Depends on: slices 1, 2, and 3 must land first

Why

This terminal slice ships the three pieces that turn the crypto stack from "library that exists" into "library that consumers must use correctly":

1. @suaveplan/crypto-cli — a keychain binary with eight subcommands. Operators (and CI) drive root + server identity lifecycle through a stable command surface rather than ad-hoc scripts. Distinct exit codes per failure class let operators distinguish "wrong password" from "tampered vault" from "expired key" from "revoked key".
2. @suaveplan/slsa migration — slsa already calls crypto.ed25519.sign(secretKey, …) directly with raw bytes today. This slice migrates it to Authority.sign(DOMAIN_SLSA_BUILDER_V1, …), with the builder identity issued as a ServerIdentity under a SLSA-builder root. The DSSE envelope wire format is unchanged — the proof is a round-trip equality test against pre-change fixtures.
3. Import-allowlist conformance gate — the most important piece. scripts/openspec-conformance.ts is extended to fail with error severity when any package outside the allowlist (@suaveplan/crypto, @suaveplan/crypto-cli) imports the cryptographic primitives from crypto-core, crypto-cipher, crypto-curve, or crypto-hash-as-MAC. Encoding helpers from crypto-utils and pure-hash uses from crypto-hash remain open. The allowlist is committed as scripts/conformance/crypto-core-allowlist.yml so additions are reviewable.

Without the gate, future packages will drift back into direct primitive use exactly as slsa did. The gate is the single most important guarantee in the umbrella proposal.

What changes

New: @suaveplan/crypto-cli

Located at packages/crypto/crypto-cli/. Built on @suaveplan/cli + @suaveplan/readline + @suaveplan/crypto. Bin entry: keychain → dist/keychain.js.

Subcommands (eight):

1. keychain root init — generate root identity, write encrypted vault, emit public bundle
2. keychain server init — generate server identity under a root, emit signed public bundle, append audit log
3. keychain server roll — version-bump rotation; --idempotency-key deduped via local file ledger; appends CRL + audit
4. keychain server revoke — --idempotency-key deduped; appends CRL + audit; no re-issue
5. keychain inspect — view a packed public keychain (verifies self-signature)
6. keychain verify — verify any signed envelope against a trust anchor + CRL
7. keychain export-public — strip secrets, output portable public bundle
8. keychain restore — re-derive a vault from BIP39 mnemonic + version

Cross-cutting:

• TTY-only password input via cli's password prompt; --password flag rejected with a security pointer
• Stdin/stdout streamable; --output json|binary|text
• Distinct exit codes: 0 success, 2 usage error, 10 bad password, 11 tampered vault, 12 expired key, 13 revoked key, 14 missing trust anchor, 15 audit-log mismatch
• OTel spans + structured logger output for every command
• Co-located .md per command file (≥ 200 words, basic + advanced examples)

Modified: @suaveplan/slsa

• Replace direct crypto.ed25519.sign(secretKey, …) calls with Authority.sign(DOMAIN_SLSA_BUILDER_V1, …)
• Builder identity constructed from a ServerIdentity issued under a SLSA-builder root
• Provenance test fixtures regenerated with new construction path; DSSE envelope output unchanged (asserted by round-trip equality test)
• package.json: add @suaveplan/crypto workspace dep; remove direct @suaveplan/crypto-core signing import (retain @suaveplan/crypto-hash and @suaveplan/crypto-utils for hashing + encoding)
• New test tests/no-direct-crypto-core.test.ts pins import discipline

New: import-allowlist conformance gate

• scripts/conformance/crypto-core-allowlist.yml — committed allowlist (@suaveplan/crypto, @suaveplan/crypto-cli)
• scripts/openspec-conformance.ts — extended to scan every workspace package's src/ for imports of @suaveplan/crypto-core, @suaveplan/crypto-cipher, @suaveplan/crypto-curve, or @suaveplan/crypto-hash MAC subpaths; fails with error severity for any non-allowlisted package
• scripts/conformance/crypto-core-allowlist.test.ts — exercises positive (allowed) and negative (forbidden) cases against fixture packages

Out of scope

• HSM / threshold backends for Authority — separate crypto-authority-yubikey, crypto-authority-tpm changes
• Network-fetched CRL distribution (--fetch-crl over HTTP/OCSP)
• Trust-anchor distribution mechanism beyond two documented patterns (compiled-in pinned constant; env-var path to a trusted public bundle)
• SLSA Sigstore Rekor integration migration to share the AuditLog (flagged in umbrella as a follow-up)

Source mapping

Requirement	Source	Notes
keychain binary surface (8 commands)	umbrella ### Requirement: \keychain` binary surface` (crypto-cli/spec.md)	Verbatim
TTY-only password input	umbrella crypto-cli/spec.md	Verbatim
Distinct exit codes per failure class	umbrella crypto-cli/spec.md	Verbatim
--idempotency-key on state-changing commands	umbrella crypto-cli/spec.md	Verbatim
Per-command behaviour table	umbrella crypto-cli/spec.md	Verbatim
slsa builder identity via Authority	umbrella slsa/spec.md	Verbatim
Import-allowlist gate	umbrella crypto-core/spec.md	Verbatim

Verification approach

• 100/100/100/100 coverage on every new command file in crypto-cli
• Pre-change DSSE envelope fixtures committed; post-migration slsa round-trip equals byte-for-byte
• Allowlist gate: positive fixtures (crypto, crypto-cli import primitives → green) and negative fixtures (test fixture package importing primitives → red) exercised in tests/
• TTY mock harness driven via @suaveplan/cli's InputReader interface (no real TTY needed)

Migration impact

• Every package in genesis whose src/ reaches into crypto-core, crypto-cipher, crypto-curve, or crypto-hash-as-MAC for cryptographic operations MUST migrate to @suaveplan/crypto's Authority/Packer/Vault API or be added to the allowlist (with reviewer approval).
• After this slice, the gate enforces the discipline mechanically. The 5 packages currently importing @suaveplan/crypto for primitives (crypto-sodium, crypto-browser, slsa, bitpacker-crypto, drive-plugin-chunks, packer) are reviewed in this slice and either migrated or allowlisted with rationale.