@petranto/byok-crypto

Zero-knowledge client-side cryptography for BYOK.cloud. All encryption and key derivation happens entirely in the browser — the server never sees plaintext keys.

Installation

npm install @petranto/byok-crypto argon2-browser

argon2-browser is a peer dependency (WASM-based Argon2 implementation).

Quick Start

import { CryptoVault } from '@petranto/byok-crypto';

// 1. Generate a salt and derive an encryption key from a passphrase
const salt = CryptoVault.generateSalt();
const key  = await CryptoVault.deriveKey('my-passphrase', salt);

// 2. Encrypt an API key
const blob = await CryptoVault.encrypt(key, 'sk-live-abc123...');

// 3. Decrypt it later
const plaintext = await CryptoVault.decrypt(key, blob);

// 4. Verification blob — lets you check a passphrase without decrypting real data
const vBlob = await CryptoVault.createVerificationBlob(key);
const ok    = await CryptoVault.verifyPassphrase(key, vBlob); // true

API

CryptoVault.generateSalt(): string

Returns a random 16-byte salt encoded as Base64.

CryptoVault.deriveKey(passphrase, salt): Promise<CryptoKey>

Derives an AES-256-GCM CryptoKey from a passphrase and Base64 salt using Argon2id (64 MB memory, 3 iterations, parallelism 1, 32-byte hash).

CryptoVault.encrypt(key, plaintext): Promise<EncryptedBlob>

Encrypts a string with AES-256-GCM using a fresh random 12-byte IV.

CryptoVault.decrypt(key, blob): Promise<string>

Decrypts an EncryptedBlob back to the original plaintext string.

CryptoVault.createVerificationBlob(key): Promise<EncryptedBlob>

Encrypts a known sentinel so the passphrase can be verified later without exposing user data.

CryptoVault.verifyPassphrase(key, blob): Promise<boolean>

Returns true if the key successfully decrypts the verification blob.

Crypto Parameters

| Parameter | Value | |---|---| | KDF | Argon2id | | Memory | 64 MB | | Iterations | 3 | | Parallelism | 1 | | Hash length | 32 bytes | | Cipher | AES-256-GCM | | IV | 12 bytes (random per encryption) | | Salt | 16 bytes (random per key derivation) | | Blob version | 3 |

Development

npm install
npm run build   # TypeScript → dist/
npm run test    # Vitest

License

MIT