Extend @suaveplan/crypto-vault — vault orchestration layer

Package: @suaveplan/crypto-vault Status: PROPOSED Type: feature (additive — no breaking changes)

Spec delta: ./specs/crypto-vault/spec.md

Why

@suaveplan/crypto-vault ships rich primitives (BIP39 / Argon2id / 2SKD / HKDF / SecureBuffer / OpaqueKeyHandle / SRP) but no high-level orchestration helpers — the layer that bundles "generate a root keychain + encrypt it into a vault file + write the signed public-key file" into one call. Upstream ../suaveplan/packages/universal/keys/src/lib/keys-common.ts shipped that orchestration as part of the now-split @suaveplan/keys umbrella; on genesis it has no home yet.

@suaveplan/server-keys (in-flight; full-parity port of 18 operator CLI bins) is blocked on this layer: 7 of its bins (create-root-keys, create-server-keys, roll-server-keys, view-keys, view-vault, view-public-key-file, plus the orchestration half of the chain bins) call createRootKeys / createServerKeys / rollServerKeys / openVault / packVault / viewPublicKeys / saveVaultToStorage / savePublicKeysToStorage / getDataFromStorage. The 3 *WithChain variants already shipped in @suaveplan/crypto-keys (factory layer) demonstrate the pattern; this proposal adds the non-chain siblings to crypto-vault so server-keys can ship at parity.

The wire format is genesis-native, not byte-compatible with upstream vaults (upstream used the deprecated BitPacker(schema) layer; genesis uses the v1 derivation grammar encodePublicKeychain + AEAD regime-2 secret blob + regime-3 application data payload). Cross-version interop is explicitly out of scope — operators rotating from upstream to genesis use a one-shot migration command (in a separate follow-up package), not in-place vault parsing.

What changes

All additive — no existing crypto-vault export changes shape. New module src/orchestration/ exports 9 functions + supporting types.

9 new functions

createRootKeys(password, options?): Promise<RootKeysResult> — generates a fresh root Keychain via @suaveplan/crypto generateKeychain, derives an Argon2id KEK from password, encrypts the full keychain into vault bytes (AEAD regime-2 secret blob), extracts public keys + canonical bytes via encodePublicKeychain. Returns { keychain, vaultBytes, publicKeyBytes, publicKeys }.
createServerKeys(rootKeys, serverPassword, options?): Promise<ServerKeysResult> — generates a child keychain derived from rootKeys.keychain.master.private (HD-key path), encrypts it under serverPassword. Returns { keychain, vaultBytes, publicKeyBytes, publicKeys, version }.
rollServerKeys(rootKeys, currentVersion, serverPassword, options?): Promise<ServerKeysResult> — deterministic re-derivation at version = currentVersion + 1 using the same root master key + serverPassword. Re-encryption produces a fresh vault; the underlying private material is reproducible from (rootMasterKey, version, serverPassword).
openVault(vaultBytes, password): Promise<Keychain> — Argon2id-derive KEK from password, AEAD-decrypt vaultBytes to recover the full Keychain. Wrong password raises CryptoVaultError(VAULT_DECRYPT_FAILED); tampered bytes raise the same.
packVault(keychain, password, options?): Promise<Uint8Array> — inverse of openVault. Used by callers that already have a Keychain instance (e.g. after a rotation) and need to re-encrypt it.
viewPublicKeys(publicKeyBytes, optionalSignKey?): Promise<PublicKeychain> — decode the signed public-key file. If optionalSignKey is provided, verify the embedded signature; mismatch raises CryptoVaultError(PUBLIC_KEY_SIGNATURE_INVALID).
saveVaultToStorage(storage, key, vaultBytes): Promise<void> — convenience wrapper over @suaveplan/storage's AbstractStorage.put(key, vaultBytes). Idempotent.
savePublicKeysToStorage(storage, key, publicKeyBytes): Promise<void> — same shape, for public-key files.
getDataFromStorage(storage, key): Promise<Uint8Array> — convenience wrapper over AbstractStorage.get(key). Raises CryptoVaultError(STORAGE_KEY_NOT_FOUND) when absent (translates whatever the storage backend throws).

Supporting types

RootKeysResult, ServerKeysResult (interfaces declaring the return shapes)
CreateRootKeysOptions, CreateServerKeysOptions, RollServerKeysOptions, PackVaultOptions (option bags — all optional; defaults for KDF parameters, algorithm choice, derivation path)

New error codes (additive — registered alongside existing `CRYPTO_VAULT_*` codes)

CRYPTO_VAULT_DECRYPT_FAILED — vault decryption failed (wrong password or tampered bytes)
CRYPTO_VAULT_PUBLIC_KEY_SIGNATURE_INVALID — viewPublicKeys signature check failed
CRYPTO_VAULT_STORAGE_KEY_NOT_FOUND — getDataFromStorage key absent
CRYPTO_VAULT_INVALID_VERSION — rollServerKeys received currentVersion < 0

Subpath export

./orchestration/orchestration — new entry in package.json's exports map.

Dependency additions

@suaveplan/crypto: workspace:^ (already used; ensure declared) — generateKeychain, encodePublicKeychain, decodePublicKeychain, extractPublicKeys, regime-2 seal/open helpers
@suaveplan/storage: workspace:^ (new dep) — AbstractStorage interface for the storage-aware helpers

Out of scope

Byte-compat with upstream @suaveplan/keys vault format. Upstream used BitPacker(fullKeychainSchema); genesis uses the v1 derivation grammar. A migration command from old → new format belongs in a separate @suaveplan/keys-migration package.
VaultManager event-emitter class (upstream vault/vault.ts 451-LOC orchestrator with open/unlock/lock FSM). Belongs in a follow-up extension; the 9 functions here are the primitives VaultManager would compose if/when it lands.
VaultStreams (chunked streaming vault decryption). Belongs in a separate package once a real consumer exists.
Hardware-fingerprint binding for keychains. Out of scope (application policy).

Source mapping

Capability	Upstream source	Notes
Public-API surface (9 functions)	`../suaveplan/packages/universal/keys/src/lib/keys-common.ts` L1-L469	re-implemented on top of genesis v1 grammar (NOT byte-compat)
Argon2id KDF parameter defaults	`../suaveplan/enterprise/keys.md`	uses existing `DEFAULT_ARGON2ID_PARAMS` from `crypto-vault`
`CRYPTO_VAULT_*` code additions	genesis-original	matches existing crypto-vault error registry shape

Impact

Affected dependents

@suaveplan/server-keys (in-flight) — this proposal unblocks 7 of its 18 bins. No other current consumers.

Genesis crypto-vault is foundation-tier: changes ripple through its existing consumers (@suaveplan/vault, @suaveplan/crypto-vault itself). The orchestration module is additive — no existing exports change — so dependent tests should not regress. The pre-archive bunx turbo test --filter=...@suaveplan/crypto-vault sweep will confirm.

6.9 KiB Raw Permalink Blame History