# @suaveplan/crypto-vault - Cryptographic foundation for the Vaulted password-manager ecosystem: BIP39 mnemonics, Argon2id-based HD key derivation, two-secret key derivation (2SKD), SRP-6a authentication, hierarchical key tree (AUK -> personal keyset -> vault key -> item key), and SecureBuffer with eager zeroization. ## Summary Cryptographic foundation for the Vaulted password-manager ecosystem. Provides BIP39 mnemonic generation, OWASP-grade Argon2id derivation, two-secret key derivation (2SKD: password + Secret Key + email → AUK), SRP-6a authentication primitives, and a hierarchical key tree (AUK → personal keyset → vault key → item key) — all held in `SecureBuffer` instances that zeroize on lock. ## Documentation tree - [argon2id](./src/argon2id/argon2id.md) — _(no submodules)_ - [argon2id](./src/argon2id/argon2id.md) — _(no submodules)_ - [bip39](./src/bip39/bip39.md) — _(no submodules)_ - [bip39](./src/bip39/bip39.md) — _(no submodules)_ - [codes](./src/errors/codes.md) — `codes.ts` is the canonical, frozen registry of every error code emitted by `@suaveplan/crypto-vault`. The registry exi… - [crypto-vault-error](./src/errors/crypto-vault-error.md) — `CryptoVaultError` is the umbrella error class for `@suaveplan/crypto-vault`. Every failure mode in the package — inval… - [handle](./src/handle/opaque-handle.md) — _(no submodules)_ - [opaque-handle](./src/handle/opaque-handle.md) — _(no submodules)_ - [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_ - [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_ - [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_ - [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_ - [orchestration](./src/orchestration/orchestration.md) — High-level orchestration helpers that bundle keychain generation, password-AEAD encryption, signed public-key file prod… - [internals](./src/orchestration/internals.md) — Internal building blocks for the orchestration surface. - [orchestration](./src/orchestration/orchestration.md) — High-level orchestration helpers that bundle keychain generation, password-AEAD encryption, signed public-key file prod… - [otel](./src/otel/instruments.md) — _(no submodules)_ - [instruments](./src/otel/instruments.md) — _(no submodules)_ - [schemas](./src/schemas/schemas.md) — _(no submodules)_ - [schemas](./src/schemas/schemas.md) — _(no submodules)_ - [secure](./src/secure/secure-buffer.md) — _(no submodules)_ - [secure-buffer](./src/secure/secure-buffer.md) — _(no submodules)_ - [srp-client](./src/srp/srp-client.md) — `srp-client.ts` implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505… - [srp-group](./src/srp/srp-group.md) — `srp-group.ts` exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as `bigint` constants. The SRP-6a cli… - [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_ - [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_ - [types](./src/types/types.md) — _(no submodules)_ - [types](./src/types/types.md) — _(no submodules)_ - [argon2id](./src/argon2id/argon2id.md) — _(no submodules)_- [bip39](./src/bip39/bip39.md) — _(no submodules)_- [bip39](./src/bip39/bip39.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes.ts` is the canonical, frozen registry of every error code emitted by `@suaveplan/crypto-vault`. The registry exi… - [crypto-vault-error](./src/errors/crypto-vault-error.md) — `CryptoVaultError` is the umbrella error class for `@suaveplan/crypto-vault`. Every failure mode in the package — inval… - [handle](./src/handle/opaque-handle.md) — _(no submodules)_- [opaque-handle](./src/handle/opaque-handle.md) — _(no submodules)_- [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_- [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_- [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_- [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_- [otel](./src/otel/instruments.md) — _(no submodules)_- [instruments](./src/otel/instruments.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [secure](./src/secure/secure-buffer.md) — _(no submodules)_- [secure-buffer](./src/secure/secure-buffer.md) — _(no submodules)_- [srp-client](./src/srp/srp-client.md) — `srp-client.ts` implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505… - [srp-group](./src/srp/srp-group.md) — `srp-group.ts` exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as `bigint` constants. The SRP-6a cli… - [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_- [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [argon2id](./src/argon2id/argon2id.md) — _(no submodules)_- [bip39](./src/bip39/bip39.md) — _(no submodules)_- [bip39](./src/bip39/bip39.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes.ts` is the canonical, frozen registry of every error code emitted by `@suaveplan/crypto-vault`. The registry exi… - [crypto-vault-error](./src/errors/crypto-vault-error.md) — `CryptoVaultError` is the umbrella error class for `@suaveplan/crypto-vault`. Every failure mode in the package — inval… - [handle](./src/handle/opaque-handle.md) — _(no submodules)_- [opaque-handle](./src/handle/opaque-handle.md) — _(no submodules)_- [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_- [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_- [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_- [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_- [otel](./src/otel/instruments.md) — _(no submodules)_- [instruments](./src/otel/instruments.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [secure](./src/secure/secure-buffer.md) — _(no submodules)_- [secure-buffer](./src/secure/secure-buffer.md) — _(no submodules)_- [srp-client](./src/srp/srp-client.md) — `srp-client.ts` implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505… - [srp-group](./src/srp/srp-group.md) — `srp-group.ts` exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as `bigint` constants. The SRP-6a cli… - [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_- [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [argon2id](./src/argon2id/argon2id.md) — _(no submodules)_- [bip39](./src/bip39/bip39.md) — _(no submodules)_- [bip39](./src/bip39/bip39.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes.ts` is the canonical, frozen registry of every error code emitted by `@suaveplan/crypto-vault`. The registry exi… - [crypto-vault-error](./src/errors/crypto-vault-error.md) — `CryptoVaultError` is the umbrella error class for `@suaveplan/crypto-vault`. Every failure mode in the package — inval… - [handle](./src/handle/opaque-handle.md) — _(no submodules)_- [opaque-handle](./src/handle/opaque-handle.md) — _(no submodules)_- [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_- [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_- [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_- [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_- [otel](./src/otel/instruments.md) — _(no submodules)_- [instruments](./src/otel/instruments.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_- [secure](./src/secure/secure-buffer.md) — _(no submodules)_- [secure-buffer](./src/secure/secure-buffer.md) — _(no submodules)_- [srp-client](./src/srp/srp-client.md) — `srp-client.ts` implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505… - [srp-group](./src/srp/srp-group.md) — `srp-group.ts` exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as `bigint` constants. The SRP-6a cli… - [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_- [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_- [argon2id](./src/argon2id/argon2id.md) — _(no submodules)_- [bip39](./src/bip39/bip39.md) — _(no submodules)_ - [bip39](./src/bip39/bip39.md) — _(no submodules)_- [codes](./src/errors/codes.md) — `codes.ts` is the canonical, frozen registry of every error code emitted by `@suaveplan/crypto-vault`. The registry exi… - [crypto-vault-error](./src/errors/crypto-vault-error.md) — `CryptoVaultError` is the umbrella error class for `@suaveplan/crypto-vault`. Every failure mode in the package — inval… - [handle](./src/handle/opaque-handle.md) — _(no submodules)_ - [opaque-handle](./src/handle/opaque-handle.md) — _(no submodules)_- [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_ - [hd-key](./src/hd-key/hd-key.md) — _(no submodules)_- [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_ - [key-hierarchy](./src/key-hierarchy/key-hierarchy.md) — _(no submodules)_- [otel](./src/otel/instruments.md) — _(no submodules)_ - [instruments](./src/otel/instruments.md) — _(no submodules)_- [schemas](./src/schemas/schemas.md) — _(no submodules)_ - [schemas](./src/schemas/schemas.md) — _(no submodules)_- [secure](./src/secure/secure-buffer.md) — _(no submodules)_ - [secure-buffer](./src/secure/secure-buffer.md) — _(no submodules)_- [srp-client](./src/srp/srp-client.md) — `srp-client.ts` implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505… - [srp-group](./src/srp/srp-group.md) — `srp-group.ts` exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as `bigint` constants. The SRP-6a cli… - [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_ - [twoskd](./src/twoskd/twoskd.md) — _(no submodules)_- [types](./src/types/types.md) — _(no submodules)_ - [types](./src/types/types.md) — _(no submodules)_ ## Install ```bash bun add @suaveplan/crypto-vault ``` ## Quick start ```ts import { DEFAULT_ARGON2ID_PARAMS, deriveAuk, deriveItemKey, derivePersonalKeyset, deriveVaultKey, generateMnemonic, SecureBuffer, SrpClient, zeroizeAll, } from "@suaveplan/crypto-vault"; // 1. Generate a backup phrase. const mnemonic = generateMnemonic(128); // 2. Derive the AUK from the user's secrets. const salt = crypto.getRandomValues(new Uint8Array(16)); const auk = await deriveAuk( "correct horse battery staple", "A3-7PMW82-XJZS9-NQDLV-EYKBR", "alice@example.com", salt, DEFAULT_ARGON2ID_PARAMS ); // 3. Fan out into the hierarchy. const personal = derivePersonalKeyset(auk); const vaultKey = deriveVaultKey(personal, "vault-1"); const itemKey = deriveItemKey(vaultKey, "login-bank"); // 4. Authenticate via SRP-6a. const client = new SrpClient(); const x = client.derivePrivateKey("alice@example.com", "pw", salt); const v = client.deriveVerifier(x); // 5. Lock — sweep every live SecureBuffer. const wrapped = new SecureBuffer(itemKey); zeroizeAll(); console.log(wrapped.isClosed); // true ``` ## Modules - [`bip39/`](./src/bip39/bip39.md) — BIP39 mnemonic generation, conversion, and validation (English word list). - [`argon2id/`](./src/argon2id/argon2id.md) — OWASP-safe Argon2id derivation wrapper around `@suaveplan/crypto-hash`. - [`hd-key/`](./src/hd-key/hd-key.md) — BIP39 seed and BIP32-shaped HD key derivation. - [`twoskd/`](./src/twoskd/twoskd.md) — Two-Secret Key Derivation (`password ⊕ secretKey ⊕ email → AUK`). - [`key-hierarchy/`](./src/key-hierarchy/key-hierarchy.md) — HKDF-driven AUK → personal keyset → vault key → item key tree. - [`srp/srp-client`](./src/srp/srp-client.md) — RFC 5054 SRP-6a client. - [`srp/srp-group`](./src/srp/srp-group.md) — RFC 5054 2048-bit MODP group parameters. - [`secure/`](./src/secure/secure-buffer.md) — `SecureBuffer` envelope with eager zeroization, clone isolation, and global `zeroizeAll()`. - [`handle/`](./src/handle/opaque-handle.md) — `OpaqueKeyHandle` for the vault layer to hold key references without seeing raw bytes. - [`errors/codes`](./src/errors/codes.md) — frozen error-code registry. - [`errors/crypto-vault-error`](./src/errors/crypto-vault-error.md) — `CryptoVaultError` umbrella class. - [`schemas/`](./src/schemas/schemas.md) — Zod schemas for every public shape (`Argon2idParams`, `PersonalKeyset`, etc.). - [`types/`](./src/types/types.md) — shared types (`Argon2idParams`, `Auk`, `PersonalKeyset`, …). - [`otel/`](./src/otel/instruments.md) — lazy OpenTelemetry instrument set. ## Security model - Plaintext key material lives only inside `SecureBuffer` instances; the buffers' `toString` and `toJSON` mask the bytes. - `zeroizeAll()` walks every reachable `SecureBuffer` via a `WeakRef` registry and overwrites its bytes with zeros. - Argon2id parameters below the OWASP minimums (memoryKB ≥ 64 MiB, iterations ≥ 3, parallelism ≥ 1) are rejected at runtime. - All MAC / proof comparisons are constant-time (`@suaveplan/crypto-utils`'s `constantTimeEqual`). - SRP-6a uses SHA-256 over the RFC 5054 2048-bit safe-prime group with full server-proof verification. ## License MIT