@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 — (no submodules)
- argon2id — (no submodules)
bip39 — (no submodules)
- bip39 — (no submodules)
codes — codes.ts is the canonical, frozen registry of every error code emitted by @suaveplan/crypto-vault. The registry exi…
crypto-vault-error — CryptoVaultError is the umbrella error class for @suaveplan/crypto-vault. Every failure mode in the package — inval…
handle — (no submodules)
- opaque-handle — (no submodules)
hd-key — (no submodules)
- hd-key — (no submodules)
key-hierarchy — (no submodules)
- key-hierarchy — (no submodules)
orchestration — High-level orchestration helpers that bundle keychain generation, password-AEAD encryption, signed public-key file prod…
- internals — Internal building blocks for the orchestration surface.
- orchestration — High-level orchestration helpers that bundle keychain generation, password-AEAD encryption, signed public-key file prod…
otel — (no submodules)
- instruments — (no submodules)
schemas — (no submodules)
- schemas — (no submodules)
secure — (no submodules)
- secure-buffer — (no submodules)
srp-client — srp-client.ts implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505…
srp-group — srp-group.ts exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as bigint constants. The SRP-6a cli…
twoskd — (no submodules)
- twoskd — (no submodules)
types — (no submodules)
- types — (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 — CryptoVaultError is the umbrella error class for @suaveplan/crypto-vault. Every failure mode in the package — inval…
handle — (no submodules)- opaque-handle — (no submodules)- hd-key — (no submodules)- hd-key — (no submodules)- key-hierarchy — (no submodules)- key-hierarchy — (no submodules)- otel — (no submodules)- instruments — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- secure — (no submodules)- secure-buffer — (no submodules)- srp-client — srp-client.ts implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505…
srp-group — srp-group.ts exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as bigint constants. The SRP-6a cli…
twoskd — (no submodules)- twoskd — (no submodules)- types — (no submodules)- types — (no submodules)- argon2id — (no submodules)- bip39 — (no submodules)- bip39 — (no submodules)- codes — codes.ts is the canonical, frozen registry of every error code emitted by @suaveplan/crypto-vault. The registry exi…
crypto-vault-error — CryptoVaultError is the umbrella error class for @suaveplan/crypto-vault. Every failure mode in the package — inval…
handle — (no submodules)- opaque-handle — (no submodules)- hd-key — (no submodules)- hd-key — (no submodules)- key-hierarchy — (no submodules)- key-hierarchy — (no submodules)- otel — (no submodules)- instruments — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- secure — (no submodules)- secure-buffer — (no submodules)- srp-client — srp-client.ts implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505…
srp-group — srp-group.ts exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as bigint constants. The SRP-6a cli…
twoskd — (no submodules)- twoskd — (no submodules)- types — (no submodules)- types — (no submodules)- argon2id — (no submodules)- bip39 — (no submodules)- bip39 — (no submodules)- codes — codes.ts is the canonical, frozen registry of every error code emitted by @suaveplan/crypto-vault. The registry exi…
crypto-vault-error — CryptoVaultError is the umbrella error class for @suaveplan/crypto-vault. Every failure mode in the package — inval…
handle — (no submodules)- opaque-handle — (no submodules)- hd-key — (no submodules)- hd-key — (no submodules)- key-hierarchy — (no submodules)- key-hierarchy — (no submodules)- otel — (no submodules)- instruments — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- secure — (no submodules)- secure-buffer — (no submodules)- srp-client — srp-client.ts implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505…
srp-group — srp-group.ts exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as bigint constants. The SRP-6a cli…
twoskd — (no submodules)- twoskd — (no submodules)- types — (no submodules)- types — (no submodules)- argon2id — (no submodules)- bip39 — (no submodules) - bip39 — (no submodules)- codes — codes.ts is the canonical, frozen registry of every error code emitted by @suaveplan/crypto-vault. The registry exi…
crypto-vault-error — CryptoVaultError is the umbrella error class for @suaveplan/crypto-vault. Every failure mode in the package — inval…
handle — (no submodules) - opaque-handle — (no submodules)- hd-key — (no submodules) - hd-key — (no submodules)- key-hierarchy — (no submodules) - key-hierarchy — (no submodules)- otel — (no submodules) - instruments — (no submodules)- schemas — (no submodules) - schemas — (no submodules)- secure — (no submodules) - secure-buffer — (no submodules)- srp-client — srp-client.ts implements the client side of the SRP-6a zero-knowledge password-authenticated key exchange per RFC 505…
srp-group — srp-group.ts exports the canonical 2048-bit MODP group from RFC 5054 Appendix A as bigint constants. The SRP-6a cli…
twoskd — (no submodules) - twoskd — (no submodules)- types — (no submodules) - types — (no submodules)

Install

bun add @suaveplan/crypto-vault

Quick start

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/ — BIP39 mnemonic generation, conversion, and validation (English word list).
argon2id/ — OWASP-safe Argon2id derivation wrapper around @suaveplan/crypto-hash.
hd-key/ — BIP39 seed and BIP32-shaped HD key derivation.
twoskd/ — Two-Secret Key Derivation (password ⊕ secretKey ⊕ email → AUK).
key-hierarchy/ — HKDF-driven AUK → personal keyset → vault key → item key tree.
srp/srp-client — RFC 5054 SRP-6a client.
srp/srp-group — RFC 5054 2048-bit MODP group parameters.
secure/ — SecureBuffer envelope with eager zeroization, clone isolation, and global zeroizeAll().
handle/ — OpaqueKeyHandle for the vault layer to hold key references without seeing raw bytes.
errors/codes — frozen error-code registry.
errors/crypto-vault-error — CryptoVaultError umbrella class.
schemas/ — Zod schemas for every public shape (Argon2idParams, PersonalKeyset, etc.).
types/ — shared types (Argon2idParams, Auk, PersonalKeyset, …).
otel/ — 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

16 KiB Raw Permalink Blame History