@debros/orama 0.122.4-nightly

package/src/vault/client.ts

@@ -0,0 +1,197 @@
+import { AuthClient } from './auth';
+import type { GuardianClient } from './transport/guardian';
+import { withTimeout, withRetry } from './transport/fanout';
+import { split, combine } from './crypto/shamir';
+import type { Share } from './crypto/shamir';
+import { adaptiveThreshold, writeQuorum } from './quorum';
+import type {
+  VaultConfig,
+  StoreResult,
+  RetrieveResult,
+  ListResult,
+  DeleteResult,
+  GuardianResult,
+} from './types';
+
+const PULL_TIMEOUT_MS = 10_000;
+
+/**
+ * High-level client for the orama-vault distributed secrets store.
+ *
+ * Handles:
+ * - Authentication with guardian nodes
+ * - Shamir split/combine for data distribution
+ * - Quorum-based writes and reads
+ * - V2 CRUD operations (store, retrieve, list, delete)
+ */
+export class VaultClient {
+  private config: VaultConfig;
+  private auth: AuthClient;
+
+  constructor(config: VaultConfig) {
+    this.config = config;
+    this.auth = new AuthClient(config.identityHex, config.timeoutMs);
+  }
+
+  /**
+   * Store a secret across guardian nodes using Shamir splitting.
+   *
+   * @param name - Secret name (alphanumeric, _, -, max 128 chars)
+   * @param data - Secret data to store
+   * @param version - Monotonic version number (must be > previous)
+   */
+  async store(name: string, data: Uint8Array, version: number): Promise<StoreResult> {
+    const guardians = this.config.guardians;
+    const n = guardians.length;
+    const k = adaptiveThreshold(n);
+
+    // Shamir split the data
+    const shares = split(data, n, k);
+
+    // Authenticate and push to all guardians
+    const authed = await this.auth.authenticateAll(guardians);
+
+    const results = await Promise.allSettled(
+      authed.map(async ({ client, endpoint }, _i) => {
+        // Find the share for this guardian's index
+        const guardianIdx = guardians.indexOf(endpoint);
+        const share = shares[guardianIdx];
+        if (!share) throw new Error('share index out of bounds');
+
+        // Encode share as [x:1byte][y:rest]
+        const shareBytes = new Uint8Array(1 + share.y.length);
+        shareBytes[0] = share.x;
+        shareBytes.set(share.y, 1);
+
+        return withRetry(() => client.putSecret(name, shareBytes, version));
+      }),
+    );
+
+    // Wipe shares
+    for (const share of shares) {
+      share.y.fill(0);
+    }
+
+    const guardianResults: GuardianResult[] = authed.map(({ endpoint }, i) => {
+      const ep = `${endpoint.address}:${endpoint.port}`;
+      const r = results[i]!;
+      if (r.status === 'fulfilled') {
+        return { endpoint: ep, success: true };
+      }
+      return { endpoint: ep, success: false, error: (r.reason as Error).message };
+    });
+
+    const ackCount = results.filter((r) => r.status === 'fulfilled').length;
+    const failCount = results.filter((r) => r.status === 'rejected').length;
+    const w = writeQuorum(n);
+
+    return {
+      ackCount,
+      totalContacted: authed.length,
+      failCount,
+      quorumMet: ackCount >= w,
+      guardianResults,
+    };
+  }
+
+  /**
+   * Retrieve and reconstruct a secret from guardian nodes.
+   *
+   * @param name - Secret name
+   */
+  async retrieve(name: string): Promise<RetrieveResult> {
+    const guardians = this.config.guardians;
+    const n = guardians.length;
+    const k = adaptiveThreshold(n);
+
+    // Authenticate and pull from all guardians
+    const authed = await this.auth.authenticateAll(guardians);
+
+    const pullResults = await Promise.allSettled(
+      authed.map(async ({ client }) => {
+        const resp = await withTimeout(client.getSecret(name), PULL_TIMEOUT_MS);
+        const shareBytes = resp.share;
+        if (shareBytes.length < 2) throw new Error('Share too short');
+        return {
+          x: shareBytes[0]!,
+          y: shareBytes.slice(1),
+        } as Share;
+      }),
+    );
+
+    const shares: Share[] = [];
+    for (const r of pullResults) {
+      if (r.status === 'fulfilled') {
+        shares.push(r.value);
+      }
+    }
+
+    if (shares.length < k) {
+      throw new Error(
+        `Not enough shares: collected ${shares.length} of ${k} required (contacted ${authed.length} guardians)`,
+      );
+    }
+
+    // Reconstruct
+    const data = combine(shares);
+
+    // Wipe collected shares
+    for (const share of shares) {
+      share.y.fill(0);
+    }
+
+    return {
+      data,
+      sharesCollected: shares.length,
+    };
+  }
+
+  /**
+   * List all secrets for this identity.
+   * Queries the first reachable guardian (metadata is replicated).
+   */
+  async list(): Promise<ListResult> {
+    const guardians = this.config.guardians;
+    const authed = await this.auth.authenticateAll(guardians);
+
+    if (authed.length === 0) {
+      throw new Error('No guardians reachable');
+    }
+
+    // Query first authenticated guardian
+    const resp = await authed[0]!.client.listSecrets();
+    return { secrets: resp.secrets };
+  }
+
+  /**
+   * Delete a secret from all guardian nodes.
+   *
+   * @param name - Secret name to delete
+   */
+  async delete(name: string): Promise<DeleteResult> {
+    const guardians = this.config.guardians;
+    const n = guardians.length;
+
+    const authed = await this.auth.authenticateAll(guardians);
+
+    const results = await Promise.allSettled(
+      authed.map(async ({ client }) => {
+        return withRetry(() => client.deleteSecret(name));
+      }),
+    );
+
+    const ackCount = results.filter((r) => r.status === 'fulfilled').length;
+    const w = writeQuorum(n);
+
+    return {
+      ackCount,
+      totalContacted: authed.length,
+      quorumMet: ackCount >= w,
+    };
+  }
+
+  /** Clear all cached auth sessions. */
+  clearSessions(): void {
+    this.auth.clearSessions();
+  }
+}

package/src/vault/crypto/aes.ts

@@ -0,0 +1,271 @@
+/**
+ * AES-256-GCM Encryption
+ *
+ * Implements authenticated encryption using AES-256 in Galois/Counter Mode.
+ * Uses @noble/ciphers for platform-agnostic, audited cryptographic operations.
+ *
+ * Features:
+ * - Authenticated encryption (confidentiality + integrity)
+ * - 256-bit keys for strong security
+ * - 96-bit nonces (randomly generated)
+ * - 128-bit authentication tags
+ *
+ * Security considerations:
+ * - Never reuse a nonce with the same key
+ * - Nonces are randomly generated and prepended to ciphertext
+ * - Authentication tags are verified before decryption
+ */
+
+import { gcm } from '@noble/ciphers/aes';
+import { randomBytes } from '@noble/ciphers/webcrypto';
+import { bytesToHex, hexToBytes, concatBytes } from '@noble/hashes/utils';
+
+/**
+ * Size constants
+ */
+export const KEY_SIZE = 32; // 256 bits
+export const NONCE_SIZE = 12; // 96 bits (recommended for GCM)
+export const TAG_SIZE = 16; // 128 bits
+
+/**
+ * Encrypted data structure
+ */
+export interface EncryptedData {
+  /** Ciphertext including authentication tag */
+  ciphertext: Uint8Array;
+  /** Nonce used for encryption */
+  nonce: Uint8Array;
+  /** Additional authenticated data (optional) */
+  aad?: Uint8Array;
+}
+
+/**
+ * Serialized encrypted data (nonce prepended to ciphertext)
+ */
+export interface SerializedEncryptedData {
+  /** Combined nonce + ciphertext + tag */
+  data: Uint8Array;
+  /** Additional authenticated data (optional) */
+  aad?: Uint8Array;
+}
+
+/**
+ * Encrypts data using AES-256-GCM
+ */
+export function encrypt(
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  aad?: Uint8Array
+): EncryptedData {
+  validateKey(key);
+
+  const nonce = randomBytes(NONCE_SIZE);
+  const cipher = gcm(key, nonce, aad);
+  const ciphertext = cipher.encrypt(plaintext);
+
+  return {
+    ciphertext,
+    nonce,
+    aad,
+  };
+}
+
+/**
+ * Decrypts data using AES-256-GCM
+ */
+export function decrypt(encryptedData: EncryptedData, key: Uint8Array): Uint8Array {
+  validateKey(key);
+  validateNonce(encryptedData.nonce);
+
+  const cipher = gcm(key, encryptedData.nonce, encryptedData.aad);
+
+  try {
+    return cipher.decrypt(encryptedData.ciphertext);
+  } catch (error) {
+    throw new Error('Decryption failed: invalid ciphertext or authentication tag');
+  }
+}
+
+/**
+ * Encrypts a string message
+ */
+export function encryptString(
+  message: string,
+  key: Uint8Array,
+  aad?: Uint8Array
+): EncryptedData {
+  const plaintext = new TextEncoder().encode(message);
+  try {
+    return encrypt(plaintext, key, aad);
+  } finally {
+    plaintext.fill(0);
+  }
+}
+
+/**
+ * Decrypts to a string message
+ */
+export function decryptString(encryptedData: EncryptedData, key: Uint8Array): string {
+  const plaintext = decrypt(encryptedData, key);
+  try {
+    return new TextDecoder().decode(plaintext);
+  } finally {
+    plaintext.fill(0);
+  }
+}
+
+/**
+ * Serializes encrypted data (prepends nonce to ciphertext)
+ */
+export function serialize(encryptedData: EncryptedData): SerializedEncryptedData {
+  const data = concatBytes(encryptedData.nonce, encryptedData.ciphertext);
+
+  return {
+    data,
+    aad: encryptedData.aad,
+  };
+}
+
+/**
+ * Deserializes encrypted data
+ */
+export function deserialize(serialized: SerializedEncryptedData): EncryptedData {
+  if (serialized.data.length < NONCE_SIZE + TAG_SIZE) {
+    throw new Error('Invalid serialized data: too short');
+  }
+
+  const nonce = serialized.data.slice(0, NONCE_SIZE);
+  const ciphertext = serialized.data.slice(NONCE_SIZE);
+
+  return {
+    ciphertext,
+    nonce,
+    aad: serialized.aad,
+  };
+}
+
+/**
+ * Encrypts and serializes data in one step
+ */
+export function encryptAndSerialize(
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  aad?: Uint8Array
+): SerializedEncryptedData {
+  const encrypted = encrypt(plaintext, key, aad);
+  return serialize(encrypted);
+}
+
+/**
+ * Deserializes and decrypts data in one step
+ */
+export function deserializeAndDecrypt(
+  serialized: SerializedEncryptedData,
+  key: Uint8Array
+): Uint8Array {
+  const encrypted = deserialize(serialized);
+  return decrypt(encrypted, key);
+}
+
+/**
+ * Converts encrypted data to hex string
+ */
+export function toHex(encryptedData: EncryptedData): string {
+  const serialized = serialize(encryptedData);
+  return bytesToHex(serialized.data);
+}
+
+/**
+ * Parses encrypted data from hex string
+ */
+export function fromHex(hex: string, aad?: Uint8Array): EncryptedData {
+  const normalized = hex.startsWith('0x') ? hex.slice(2) : hex;
+  const data = hexToBytes(normalized);
+
+  return deserialize({ data, aad });
+}
+
+/**
+ * Converts encrypted data to base64 string
+ */
+export function toBase64(encryptedData: EncryptedData): string {
+  const serialized = serialize(encryptedData);
+
+  if (typeof btoa === 'function') {
+    return btoa(String.fromCharCode(...serialized.data));
+  } else {
+    return Buffer.from(serialized.data).toString('base64');
+  }
+}
+
+/**
+ * Parses encrypted data from base64 string
+ */
+export function fromBase64(base64: string, aad?: Uint8Array): EncryptedData {
+  let data: Uint8Array;
+
+  if (typeof atob === 'function') {
+    const binary = atob(base64);
+    data = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      data[i] = binary.charCodeAt(i);
+    }
+  } else {
+    data = new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+
+  return deserialize({ data, aad });
+}
+
+function validateKey(key: Uint8Array): void {
+  if (!(key instanceof Uint8Array)) {
+    throw new Error('Key must be a Uint8Array');
+  }
+
+  if (key.length !== KEY_SIZE) {
+    throw new Error(`Invalid key length: expected ${KEY_SIZE}, got ${key.length}`);
+  }
+}
+
+function validateNonce(nonce: Uint8Array): void {
+  if (!(nonce instanceof Uint8Array)) {
+    throw new Error('Nonce must be a Uint8Array');
+  }
+
+  if (nonce.length !== NONCE_SIZE) {
+    throw new Error(`Invalid nonce length: expected ${NONCE_SIZE}, got ${nonce.length}`);
+  }
+}
+
+/**
+ * Generates a random encryption key
+ */
+export function generateKey(): Uint8Array {
+  return randomBytes(KEY_SIZE);
+}
+
+/**
+ * Generates a random nonce
+ */
+export function generateNonce(): Uint8Array {
+  return randomBytes(NONCE_SIZE);
+}
+
+/**
+ * Securely clears a key from memory
+ */
+export function clearKey(key: Uint8Array): void {
+  key.fill(0);
+}
+
+/**
+ * Checks if encrypted data appears valid (basic structure check)
+ */
+export function isValidEncryptedData(data: EncryptedData): boolean {
+  return (
+    data.nonce instanceof Uint8Array &&
+    data.nonce.length === NONCE_SIZE &&
+    data.ciphertext instanceof Uint8Array &&
+    data.ciphertext.length >= TAG_SIZE
+  );
+}

package/src/vault/crypto/hkdf.ts

@@ -0,0 +1,42 @@
+/**
+ * HKDF Key Derivation
+ *
+ * Derives deterministic sub-keys from a master secret using HKDF-SHA256 (RFC 5869).
+ */
+
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+
+/** Default output length in bytes (256 bits) */
+const DEFAULT_KEY_LENGTH = 32;
+
+/** Maximum allowed output length (255 * SHA-256 output = 8160 bytes) */
+const MAX_KEY_LENGTH = 255 * 32;
+
+/**
+ * Derives a sub-key from input key material using HKDF-SHA256.
+ *
+ * @param ikm - Input key material (e.g., wallet private key). MUST be high-entropy.
+ * @param salt - Domain separation salt. Can be a string or bytes.
+ * @param info - Context-specific info. Can be a string or bytes.
+ * @param length - Output key length in bytes (default: 32).
+ * @returns Derived key as Uint8Array. Caller MUST zero this after use.
+ */
+export function deriveKeyHKDF(
+  ikm: Uint8Array,
+  salt: string | Uint8Array,
+  info: string | Uint8Array,
+  length: number = DEFAULT_KEY_LENGTH,
+): Uint8Array {
+  if (!ikm || ikm.length === 0) {
+    throw new Error('HKDF: input key material must not be empty');
+  }
+  if (length <= 0 || length > MAX_KEY_LENGTH) {
+    throw new Error(`HKDF: output length must be between 1 and ${MAX_KEY_LENGTH}`);
+  }
+
+  const saltBytes = typeof salt === 'string' ? new TextEncoder().encode(salt) : salt;
+  const infoBytes = typeof info === 'string' ? new TextEncoder().encode(info) : info;
+
+  return hkdf(sha256, ikm, saltBytes, infoBytes, length);
+}

package/src/vault/crypto/index.ts

@@ -0,0 +1,27 @@
+export {
+  encrypt,
+  decrypt,
+  encryptString,
+  decryptString,
+  serialize,
+  deserialize,
+  encryptAndSerialize,
+  deserializeAndDecrypt,
+  toHex,
+  fromHex,
+  toBase64,
+  fromBase64,
+  generateKey,
+  generateNonce,
+  clearKey,
+  isValidEncryptedData,
+  KEY_SIZE,
+  NONCE_SIZE,
+  TAG_SIZE,
+} from './aes';
+export type { EncryptedData, SerializedEncryptedData } from './aes';
+
+export { deriveKeyHKDF } from './hkdf';
+
+export { split as shamirSplit, combine as shamirCombine } from './shamir';
+export type { Share as ShamirShare } from './shamir';

package/src/vault/crypto/shamir.ts

@@ -0,0 +1,173 @@
+/**
+ * Shamir's Secret Sharing over GF(2^8)
+ *
+ * Information-theoretic secret splitting: any K shares reconstruct the secret,
+ * K-1 shares reveal zero information.
+ *
+ * Uses GF(2^8) with irreducible polynomial x^8 + x^4 + x^3 + x + 1 (0x11B),
+ * same as AES. This is the standard choice for byte-level SSS.
+ */
+
+import { randomBytes } from '@noble/ciphers/webcrypto';
+
+// ── GF(2^8) Arithmetic ─────────────────────────────────────────────────────
+
+const IRREDUCIBLE = 0x11b;
+
+/** Exponential table: exp[log[a] + log[b]] = a * b */
+const EXP_TABLE = new Uint8Array(512);
+
+/** Logarithm table: log[a] for a in 1..255 (log[0] is undefined) */
+const LOG_TABLE = new Uint8Array(256);
+
+// Build log/exp tables using generator 3
+(function buildTables() {
+  let x = 1;
+  for (let i = 0; i < 255; i++) {
+    EXP_TABLE[i] = x;
+    LOG_TABLE[x] = i;
+    x = x ^ (x << 1); // multiply by generator (3 is primitive in this field)
+    if (x >= 256) x ^= IRREDUCIBLE;
+  }
+  // Extend exp table for easy modular arithmetic (avoid mod 255)
+  for (let i = 255; i < 512; i++) {
+    EXP_TABLE[i] = EXP_TABLE[i - 255]!;
+  }
+})();
+
+/** GF(2^8) addition: XOR */
+function gfAdd(a: number, b: number): number {
+  return a ^ b;
+}
+
+/** GF(2^8) multiplication via log/exp tables */
+function gfMul(a: number, b: number): number {
+  if (a === 0 || b === 0) return 0;
+  return EXP_TABLE[LOG_TABLE[a]! + LOG_TABLE[b]!]!;
+}
+
+/** GF(2^8) multiplicative inverse */
+function gfInv(a: number): number {
+  if (a === 0) throw new Error('GF(2^8): division by zero');
+  return EXP_TABLE[255 - LOG_TABLE[a]!]!;
+}
+
+/** GF(2^8) division: a / b */
+function gfDiv(a: number, b: number): number {
+  if (b === 0) throw new Error('GF(2^8): division by zero');
+  if (a === 0) return 0;
+  return EXP_TABLE[(LOG_TABLE[a]! - LOG_TABLE[b]! + 255) % 255]!;
+}
+
+// ── Share Type ──────────────────────────────────────────────────────────────
+
+/** A single Shamir share */
+export interface Share {
+  /** Share index (1..N, never 0) */
+  x: number;
+  /** Share data (same length as secret) */
+  y: Uint8Array;
+}
+
+// ── Split ───────────────────────────────────────────────────────────────────
+
+/**
+ * Splits a secret into N shares with threshold K.
+ *
+ * @param secret - Secret bytes to split (any length)
+ * @param n - Total number of shares to create (2..255)
+ * @param k - Minimum shares needed for reconstruction (2..n)
+ * @returns Array of N shares
+ */
+export function split(secret: Uint8Array, n: number, k: number): Share[] {
+  if (k < 2) throw new Error('Threshold K must be at least 2');
+  if (n < k) throw new Error('Share count N must be >= threshold K');
+  if (n > 255) throw new Error('Maximum 255 shares (GF(2^8) limit)');
+  if (secret.length === 0) throw new Error('Secret must not be empty');
+
+  const coefficients = new Array<Uint8Array>(secret.length);
+  for (let i = 0; i < secret.length; i++) {
+    const poly = new Uint8Array(k);
+    poly[0] = secret[i]!;
+    const rand = randomBytes(k - 1);
+    poly.set(rand, 1);
+    coefficients[i] = poly;
+  }
+
+  const shares: Share[] = [];
+  for (let xi = 1; xi <= n; xi++) {
+    const y = new Uint8Array(secret.length);
+    for (let byteIdx = 0; byteIdx < secret.length; byteIdx++) {
+      y[byteIdx] = evaluatePolynomial(coefficients[byteIdx]!, xi);
+    }
+    shares.push({ x: xi, y });
+  }
+
+  for (const poly of coefficients) {
+    poly.fill(0);
+  }
+
+  return shares;
+}
+
+function evaluatePolynomial(coeffs: Uint8Array, x: number): number {
+  let result = 0;
+  for (let i = coeffs.length - 1; i >= 0; i--) {
+    result = gfAdd(gfMul(result, x), coeffs[i]!);
+  }
+  return result;
+}
+
+// ── Combine ─────────────────────────────────────────────────────────────────
+
+/**
+ * Reconstructs a secret from K or more shares using Lagrange interpolation.
+ *
+ * @param shares - Array of K or more shares (must all have same y.length)
+ * @returns Reconstructed secret
+ */
+export function combine(shares: Share[]): Uint8Array {
+  if (shares.length < 2) throw new Error('Need at least 2 shares');
+
+  const secretLength = shares[0]!.y.length;
+  for (const share of shares) {
+    if (share.y.length !== secretLength) {
+      throw new Error('All shares must have the same data length');
+    }
+    if (share.x === 0) {
+      throw new Error('Share index must not be 0');
+    }
+  }
+
+  const xValues = new Set(shares.map(s => s.x));
+  if (xValues.size !== shares.length) {
+    throw new Error('Duplicate share indices');
+  }
+
+  const secret = new Uint8Array(secretLength);
+
+  for (let byteIdx = 0; byteIdx < secretLength; byteIdx++) {
+    let value = 0;
+
+    for (let i = 0; i < shares.length; i++) {
+      const xi = shares[i]!.x;
+      const yi = shares[i]!.y[byteIdx]!;
+
+      let basis = 1;
+      for (let j = 0; j < shares.length; j++) {
+        if (i === j) continue;
+        const xj = shares[j]!.x;
+        basis = gfMul(basis, gfDiv(xj, gfAdd(xi, xj)));
+      }
+
+      value = gfAdd(value, gfMul(yi, basis));
+    }
+
+    secret[byteIdx] = value;
+  }
+
+  return secret;
+}
+
+/** @internal Exported for cross-platform test vector validation */
+export const _gf = { add: gfAdd, mul: gfMul, inv: gfInv, div: gfDiv, EXP_TABLE, LOG_TABLE } as const;