50 lines
4.3 KiB
Markdown
50 lines
4.3 KiB
Markdown
# 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`)
|