Change: enterprise-crypto-family

Why

The original enterprise-crypto change planned a single monolithic package. After a full audit of the existing main branch crypto package and the downstream packages that consume it, the surface is too wide for one package: hashing/KDFs have no engine concept, AEAD/signing/agreement benefit from swappable engine implementations (noble default, libsodium for interop, WebCrypto for hardware AES in-browser), and keypair lifecycle and vault belong in their own focused packages. Splitting now, before anything ships on genesis, costs nothing — the first published version is right.

What Changes

New packages (6)

@suaveplan/hash — pure-noble hashing substrate: SHA-256/384/512, HMAC, HKDF, PBKDF2, Argon2id. No engine concept. Zero WASM. Depended on by @suaveplan/crypto and usable standalone.
@suaveplan/crypto — the main crypto facade. Engine interfaces (AeadEngine, SignEngine, AgreeEngine, SealedBoxEngine), noble defaults for every interface, public façade functions (aeadEncrypt, aeadDecrypt, sign, verify, agree, sealedBox.*), and primitives (constantTimeEqual, randomBytes via injectable ByteSource, zeroize). Depends on @suaveplan/hash.
@suaveplan/crypto-sodium — opt-in libsodium engine. Implements every engine interface from @suaveplan/crypto via libsodium-wrappers-sumo. Adds sodium-exclusive APIs not in any interface: cryptoKdf, cryptoAuth, cryptoPwhashStr/Verify, ristretto255. Handles await sodium.ready once at import.
@suaveplan/crypto-browser — opt-in WebCrypto engine. Implements every engine interface via crypto.subtle. Adds browser-exclusive APIs: rsa.*, aesKw, ecdsaP384/P521, ecdhP384/P521, nonExtractableKey. Hardware AES-GCM acceleration in supporting browsers.
@suaveplan/crypto-keys — keypair lifecycle built on top of @suaveplan/crypto. generateKeypair, validateKeypair, keychain store, persistence adapters (in-memory, serialized). Engine-agnostic.
@suaveplan/crypto-vault — vault and BIP39 mnemonic system. Derives keys via Argon2id/PBKDF2 (from @suaveplan/hash), chain-signer pattern, event emission via @suaveplan/events. Supersedes @suaveplan/keys on main.

Supersedes

openspec/changes/enterprise-crypto — the single-package plan is replaced by this family. The original enterprise-crypto change is archived.

Breaking changes

None on genesis (nothing has shipped yet).

Capabilities

New Capabilities

hash-primitives: SHA-2 digests, HMAC, HKDF, PBKDF2, Argon2id — all via @noble/hashes. Lives in @suaveplan/hash.
crypto-engine-interfaces: AeadEngine, SignEngine, AgreeEngine, SealedBoxEngine, AuthBoxEngine — the pluggable engine contracts exported by @suaveplan/crypto.
crypto-noble-defaults: noble implementations of every engine interface, wired as defaults in @suaveplan/crypto.
crypto-primitives: constantTimeEqual, randomBytes (injectable ByteSource), zeroize, Rng→ByteSource rename to resolve conflict with @suaveplan/types's Rng.
crypto-sodium-engine: libsodium implementations of all engine interfaces plus sodium-exclusive primitives.
crypto-browser-engine: WebCrypto implementations of all engine interfaces plus browser-exclusive primitives.
crypto-keys: keypair generation, validation, and storage lifecycle.
crypto-vault: mnemonic derivation, vault unlock, chain-signer, event emission.

Modified Capabilities

None — no existing genesis specs exist for these capabilities yet.

Impact

Dependencies added to catalog: @noble/hashes, @noble/ciphers, @noble/curves (already planned), libsodium-wrappers-sumo, @types/libsodium-wrappers-sumo
Dependency order: hash → crypto → crypto-sodium + crypto-browser (parallel) → crypto-keys → crypto-vault
@suaveplan/types Rng preserved — crypto renames its own byte-producer type to ByteSource to eliminate the name collision without touching @suaveplan/types
Downstream unblocked: @suaveplan/jwt-tenant, @suaveplan/auth, @suaveplan/network encryption, @suaveplan/slsa, every package that currently imports from main's @suaveplan/crypto
Non-goals: streaming AEAD (needs @suaveplan/streams), post-quantum algorithms, HSM/TPM, JOSE/JWT (belongs in @suaveplan/jwt-tenant)

4.3 KiB Raw Permalink Blame History