api-ape 3.0.1 → 4.1.0

package/client/auth/crypto/kdf.js

@@ -0,0 +1,217 @@
+/**
+ * @file Key derivation functions for browser (HKDF, Argon2id, PBKDF2)
+ */
+'use strict';
+
+const {
+  CryptoError,
+  AES_KEY_LENGTH,
+  PBKDF2_ITERATIONS,
+} = require('./constants');
+const {
+  isCryptoAvailable,
+  bufferToUint8Array,
+  stringToUint8Array,
+} = require('./encoding');
+
+// Argon2 WASM module (lazy loaded)
+let _argon2Module = null;
+let _argon2Loading = null;
+
+/**
+ * Load argon2-browser module
+ * @returns {Promise<Object|null>}
+ */
+async function loadArgon2() {
+  if (_argon2Module) return _argon2Module;
+  if (_argon2Loading) return _argon2Loading;
+
+  _argon2Loading = (async () => {
+    try {
+      if (typeof window !== 'undefined' && window.argon2) {
+        _argon2Module = window.argon2;
+        return _argon2Module;
+      }
+
+      try {
+        const module = await import('argon2-browser');
+        _argon2Module = module.default || module;
+        return _argon2Module;
+      } catch {
+        return null;
+      }
+    } catch {
+      return null;
+    } finally {
+      _argon2Loading = null;
+    }
+  })();
+
+  return _argon2Loading;
+}
+
+/**
+ * Check if Argon2 is available
+ * @returns {Promise<boolean>}
+ */
+async function isArgon2Available() {
+  const argon2 = await loadArgon2();
+  return argon2 !== null;
+}
+
+/**
+ * HKDF key derivation using SHA-256
+ * @param {Uint8Array|string} inputKeyMaterial - Input key material
+ * @param {Uint8Array|string} salt - Salt value
+ * @param {Uint8Array|string} info - Context info
+ * @param {number} [length] - Output length
+ * @returns {Promise<Uint8Array>}
+ */
+async function hkdf(inputKeyMaterial, salt, info, length = AES_KEY_LENGTH) {
+  if (!isCryptoAvailable()) {
+    const err = new Error('Web Crypto API not available');
+    err.code = CryptoError.CRYPTO_NOT_AVAILABLE;
+    throw err;
+  }
+
+  const ikmArray =
+    typeof inputKeyMaterial === 'string'
+      ? stringToUint8Array(inputKeyMaterial)
+      : inputKeyMaterial;
+
+  const saltArray =
+    typeof salt === 'string'
+      ? stringToUint8Array(salt)
+      : salt || new Uint8Array(0);
+
+  const infoArray =
+    typeof info === 'string' ? stringToUint8Array(info) : info;
+
+  const ikmKey = await crypto.subtle.importKey(
+    'raw',
+    ikmArray,
+    'HKDF',
+    false,
+    ['deriveBits']
+  );
+
+  const derivedBits = await crypto.subtle.deriveBits(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: saltArray,
+      info: infoArray,
+    },
+    ikmKey,
+    length * 8
+  );
+
+  return bufferToUint8Array(derivedBits);
+}
+
+/**
+ * Derive key using Argon2id
+ * Falls back to PBKDF2 if argon2-browser not available.
+ * @param {Uint8Array|string} password - Password input
+ * @param {Uint8Array} salt - 16+ byte salt
+ * @param {Object} [options] - Argon2 options
+ * @param {number} [options.memoryCost] - Memory in KB
+ * @param {number} [options.timeCost] - Iterations
+ * @param {number} [options.parallelism] - Threads
+ * @param {number} [options.hashLength] - Output length
+ * @returns {Promise<Uint8Array>}
+ */
+async function argon2id(password, salt, options = {}) {
+  const {
+    memoryCost = 65536,
+    timeCost = 3,
+    parallelism = 4,
+    hashLength = AES_KEY_LENGTH,
+  } = options;
+
+  const passwordArray =
+    typeof password === 'string' ? stringToUint8Array(password) : password;
+
+  if (!(salt instanceof Uint8Array) || salt.length < 16) {
+    const err = new Error('Salt must be a Uint8Array of at least 16 bytes');
+    err.code = CryptoError.KDF_FAILED;
+    throw err;
+  }
+
+  const argon2 = await loadArgon2();
+
+  if (argon2) {
+    try {
+      const result = await argon2.hash({
+        pass: passwordArray,
+        salt,
+        type: argon2.ArgonType.Argon2id,
+        mem: memoryCost,
+        time: timeCost,
+        parallelism,
+        hashLen: hashLength,
+      });
+
+      return new Uint8Array(result.hash);
+    } catch (err) {
+      const newErr = new Error(`Argon2id failed: ${err.message}`);
+      newErr.code = CryptoError.KDF_FAILED;
+      throw newErr;
+    }
+  }
+
+  return pbkdf2Fallback(passwordArray, salt, PBKDF2_ITERATIONS, hashLength);
+}
+
+/**
+ * PBKDF2 fallback for environments without Argon2
+ * @param {Uint8Array|string} password - Password input
+ * @param {Uint8Array} salt - Salt value
+ * @param {number} [iterations] - PBKDF2 iterations
+ * @param {number} [keyLength] - Output key length
+ * @returns {Promise<Uint8Array>}
+ */
+async function pbkdf2Fallback(password, salt, iterations = PBKDF2_ITERATIONS, keyLength = AES_KEY_LENGTH) {
+  if (!isCryptoAvailable()) {
+    const err = new Error('Web Crypto API not available');
+    err.code = CryptoError.CRYPTO_NOT_AVAILABLE;
+    throw err;
+  }
+
+  const passwordArray =
+    typeof password === 'string' ? stringToUint8Array(password) : password;
+
+  if (!(salt instanceof Uint8Array)) {
+    const err = new Error('Salt must be a Uint8Array');
+    err.code = CryptoError.KDF_FAILED;
+    throw err;
+  }
+
+  const passwordKey = await crypto.subtle.importKey(
+    'raw',
+    passwordArray,
+    'PBKDF2',
+    false,
+    ['deriveBits']
+  );
+
+  const derivedBits = await crypto.subtle.deriveBits(
+    {
+      name: 'PBKDF2',
+      salt,
+      iterations,
+      hash: 'SHA-512',
+    },
+    passwordKey,
+    keyLength * 8
+  );
+
+  return bufferToUint8Array(derivedBits);
+}
+
+module.exports = {
+  hkdf,
+  argon2id,
+  pbkdf2Fallback,
+  isArgon2Available,
+};

package/client/auth/crypto-utils.js

@@ -0,0 +1,118 @@
+/**
+ * @file Browser Cryptographic Utilities for Key Recovery
+ *
+ * Provides AEAD encryption, key derivation (HKDF), and password-based
+ * key derivation (Argon2id) using Web Crypto API and argon2-browser.
+ *
+ * API compatible with server/security/auth/mfa/crypto-utils.js
+ *
+ * @module client/auth/crypto-utils
+ */
+'use strict';
+
+const {
+  CryptoError,
+  AES_KEY_LENGTH,
+  GCM_NONCE_LENGTH,
+  GCM_TAG_LENGTH,
+  PBKDF2_ITERATIONS,
+} = require('./crypto/constants');
+
+const {
+  isCryptoAvailable,
+  stringToUint8Array,
+  uint8ArrayToString,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+  randomBytes,
+  timingSafeEqual,
+} = require('./crypto/encoding');
+
+const {
+  aeadEncrypt,
+  aeadDecrypt,
+  packEncrypted,
+  unpackEncrypted,
+  encryptAndPack,
+  unpackAndDecrypt,
+} = require('./crypto/aead');
+
+const {
+  hkdf,
+  argon2id,
+  pbkdf2Fallback,
+  isArgon2Available,
+} = require('./crypto/kdf');
+
+/**
+ * Generate a random salt for KDF
+ * @param {number} [length] - Salt length in bytes
+ * @returns {Uint8Array}
+ */
+function generateSalt(length = 16) {
+  return randomBytes(length);
+}
+
+/**
+ * Generate a random encryption key
+ * @param {number} [length] - Key length in bytes
+ * @returns {Uint8Array}
+ */
+function generateKey(length = AES_KEY_LENGTH) {
+  return randomBytes(length);
+}
+
+/**
+ * Derive a key from a master key for a specific purpose
+ * @param {Uint8Array} masterKey - Master key material
+ * @param {string} purpose - Key purpose identifier
+ * @param {number} [version] - Key version
+ * @returns {Promise<Uint8Array>}
+ */
+async function deriveKeyForPurpose(masterKey, purpose, version = 1) {
+  const info = `api-ape:key-recovery:${purpose}:v${version}`;
+  return hkdf(masterKey, '', info, AES_KEY_LENGTH);
+}
+
+module.exports = {
+  // AEAD
+  aeadEncrypt,
+  aeadDecrypt,
+
+  // Packing
+  packEncrypted,
+  unpackEncrypted,
+  encryptAndPack,
+  unpackAndDecrypt,
+
+  // KDF
+  hkdf,
+  argon2id,
+  pbkdf2Fallback,
+  isArgon2Available,
+
+  // Utilities
+  generateSalt,
+  generateKey,
+  randomBytes,
+  timingSafeEqual,
+  deriveKeyForPurpose,
+
+  // Encoding utilities
+  stringToUint8Array,
+  uint8ArrayToString,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+
+  // Constants
+  AES_KEY_LENGTH,
+  GCM_NONCE_LENGTH,
+  GCM_TAG_LENGTH,
+  PBKDF2_ITERATIONS,
+
+  // Errors
+  CryptoError,
+
+  // Environment checks
+  isCryptoAvailable,
+};

package/client/auth/files.md

@@ -0,0 +1,52 @@
+# Client Authentication SDK Files
+
+This directory contains the client-side SDK for key recovery and authentication.
+
+## Guidelines
+
+- **Browser-compatible** - Uses Web Crypto API and IndexedDB
+- **Secure storage** - S2 share encrypted with WebAuthn-derived key
+- **API compatible** - Crypto utilities match server-side interface
+
+## Directory Structure
+
+```
+auth/
+├── crypto-utils.js       # Browser crypto utilities (Web Crypto API)
+├── key-recovery.js       # Key recovery client SDK
+├── key-recovery.test.js  # Client SDK tests
+├── share-storage.js      # IndexedDB share storage
+└── share-storage.test.js # Storage tests
+```
+
+## Files
+
+### `crypto-utils.js`
+
+Browser-compatible cryptographic utilities:
+
+- `aeadEncrypt/aeadDecrypt` - AES-256-GCM encryption with AEAD
+- `hkdf` - RFC 5869 key derivation using Web Crypto API
+- `argon2id` - Password-based KDF with PBKDF2 fallback
+- `packEncrypted/unpackEncrypted` - Pack/unpack for storage
+- API compatible with `server/security/auth/mfa/crypto-utils.js`
+
+### `key-recovery.js`
+
+Client SDK for 2-of-3 key recovery (Tier 3):
+
+- `KeyRecoveryClient` - Main client class
+- `enroll()` - Generate K_user, split shares, encrypt, store S2 locally
+- `recover()` - Fetch encrypted shares, decrypt, combine to reconstruct
+- `rotateShare()` - Handle share rotation after device loss
+- GF(256) Shamir Secret Sharing implementation for browser
+
+### `share-storage.js`
+
+IndexedDB storage for S2 share (WebAuthn-gated):
+
+- `saveShare/getShare` - Store/retrieve encrypted shares
+- `saveWrappedKey/getWrappedKey` - Store/retrieve wrapped L_keys
+- `saveMetadata/getMetadata` - Store enrollment metadata
+- `createUserStorage()` - Convenience factory with bound userId
+- Database schema: shares, keys, metadata stores

package/client/auth/key-recovery.js

@@ -0,0 +1,288 @@
+/**
+ * @file Client SDK for 2-of-3 Key Recovery
+ *
+ * Provides client-side key reconstruction using Shamir Secret Sharing.
+ * Works with server-side two-of-three adapter for HIGH_SECURITY (Tier 3).
+ *
+ * @module client/auth/key-recovery
+ */
+'use strict';
+
+const cryptoUtils = require('./crypto-utils');
+const shareStorage = require('./share-storage');
+const { KeyRecoveryError, FactorType } = require('./recovery/constants');
+const { combineShares, deserializeShare, serializeShare, evaluatePolynomial } = require('./recovery/sss-browser');
+const { deriveS1Key, deriveS2Key, deriveS3Key } = require('./recovery/key-derivation');
+
+/**
+ * Client SDK for 2-of-3 key recovery
+ */
+class KeyRecoveryClient {
+  /**
+   * Create a KeyRecoveryClient
+   * @param {Object} options - Client options
+   * @param {Function} options.sendMessage - Server message function
+   * @param {string} [options.rpId] - WebAuthn relying party ID
+   */
+  constructor(options = {}) {
+    if (!options.sendMessage || typeof options.sendMessage !== 'function') {
+      throw new Error('sendMessage function is required');
+    }
+    this.sendMessage = options.sendMessage;
+    this.rpId = options.rpId || (typeof location !== 'undefined' ? location.hostname : 'localhost');
+    this._pendingEnrollment = null;
+    this._pendingRecovery = null;
+  }
+
+  /**
+   * Check if user is enrolled
+   * @param {string} userId - User identifier
+   * @returns {Promise<boolean>}
+   */
+  async isEnrolled(userId) {
+    return shareStorage.isEnrolled(userId);
+  }
+
+  /**
+   * Enroll in key recovery
+   * @param {Object} params - Enrollment parameters
+   * @param {string} params.userId - User identifier
+   * @param {string} params.oauthToken - OAuth token
+   * @param {string} params.totpSeed - TOTP seed
+   * @param {Uint8Array} params.webauthnAuthData - WebAuthn data
+   * @param {string} params.webauthnCredentialId - Credential ID
+   * @returns {Promise<Object>}
+   */
+  async enroll(params) {
+    const { userId, oauthToken, totpSeed, webauthnAuthData, webauthnCredentialId } = params;
+
+    if (!userId) throw new Error('userId is required');
+    if (!oauthToken) throw new Error('oauthToken is required');
+    if (!totpSeed) throw new Error('totpSeed is required');
+    if (!webauthnAuthData) throw new Error('webauthnAuthData is required');
+    if (!webauthnCredentialId) throw new Error('webauthnCredentialId is required');
+
+    const enrolled = await this.isEnrolled(userId);
+    if (enrolled) {
+      const err = new Error('User already enrolled');
+      err.code = KeyRecoveryError.ALREADY_ENROLLED;
+      throw err;
+    }
+
+    try {
+      const kUser = cryptoUtils.generateKey(32);
+      const shares = this._splitSecret(kUser, 2, 3);
+
+      const s1Salt = cryptoUtils.generateSalt(16);
+      const s3Salt = cryptoUtils.generateSalt(16);
+
+      const [s1Key, s2Key, s3Key] = await Promise.all([
+        deriveS1Key(oauthToken, userId),
+        deriveS2Key(webauthnAuthData, webauthnCredentialId),
+        deriveS3Key(totpSeed, s3Salt)
+      ]);
+
+      const [encS1, encS2, encS3] = await Promise.all([
+        cryptoUtils.encryptAndPack(s1Key, shares[0].data, `s1:${userId}`),
+        cryptoUtils.encryptAndPack(s2Key, shares[1].data, `s2:${userId}`),
+        cryptoUtils.encryptAndPack(s3Key, shares[2].data, `s3:${userId}`)
+      ]);
+
+      const storage = shareStorage.createUserStorage(userId);
+      await storage.saveShare('S2', cryptoUtils.uint8ArrayToBase64(encS2), 1);
+      await storage.saveWrappedKey(webauthnCredentialId, cryptoUtils.uint8ArrayToBase64(s2Key));
+      await storage.saveMetadata({
+        enrolledAt: Date.now(),
+        shareCount: 3,
+        s3Salt: cryptoUtils.uint8ArrayToBase64(s3Salt)
+      });
+
+      const proof = await this._generateProof(kUser, userId);
+
+      const response = await this.sendMessage({
+        type: 'key_recovery_enrollment_finish',
+        userId,
+        encShares: {
+          S1: cryptoUtils.uint8ArrayToBase64(encS1),
+          S1_salt: cryptoUtils.uint8ArrayToBase64(s1Salt),
+          S3: cryptoUtils.uint8ArrayToBase64(encS3),
+          S3_salt: cryptoUtils.uint8ArrayToBase64(s3Salt)
+        },
+        shareIndices: { S1: shares[0].index, S2: shares[1].index, S3: shares[2].index },
+        proof
+      });
+
+      if (response.type === 'error') {
+        await storage.deleteAll();
+        const err = new Error(response.message || 'Enrollment failed');
+        err.code = KeyRecoveryError.SERVER_ERROR;
+        throw err;
+      }
+
+      return { kUser, proof };
+    } catch (err) {
+      try { await shareStorage.deleteAllUserData(userId); } catch { /* ignore */ }
+      throw err;
+    }
+  }
+
+  /**
+   * Recover K_user using 2 of 3 factors
+   * @param {Object} params - Recovery parameters
+   * @param {string} params.userId - User identifier
+   * @param {Array<string>} params.factors - Factor types to use
+   * @param {Object} params.factorData - Data for each factor
+   * @returns {Promise<Uint8Array>}
+   */
+  async recover(params) {
+    const { userId, factors, factorData = {} } = params;
+
+    if (!userId) throw new Error('userId is required');
+
+    // Check enrollment
+    const enrolled = await this.isEnrolled(userId);
+    if (!enrolled) {
+      const err = new Error('User not enrolled');
+      err.code = KeyRecoveryError.NOT_ENROLLED;
+      throw err;
+    }
+
+    // Validate factors array
+    if (!Array.isArray(factors) || factors.length !== 2) {
+      const err = new Error('Exactly 2 factors required');
+      err.code = KeyRecoveryError.INSUFFICIENT_FACTORS;
+      throw err;
+    }
+
+    // Validate factor types
+    const validFactors = Object.values(FactorType);
+    for (const factor of factors) {
+      if (!validFactors.includes(factor)) {
+        const err = new Error(`Unknown factor: ${factor}`);
+        err.code = KeyRecoveryError.INVALID_FACTOR;
+        throw err;
+      }
+    }
+
+    const response = await this.sendMessage({ type: 'key_recovery_start', userId });
+
+    if (response.type !== 'key_recovery_shares') {
+      const err = new Error(response.message || 'Recovery failed');
+      err.code = KeyRecoveryError.SERVER_ERROR;
+      throw err;
+    }
+
+    const decryptedShares = [];
+
+    if (factors.includes(FactorType.OAUTH) && response.encShares?.S1) {
+      const s1Key = await deriveS1Key(factorData.oauthToken, userId);
+      const encData = cryptoUtils.base64ToUint8Array(response.encShares.S1);
+      const shareData = await cryptoUtils.unpackAndDecrypt(s1Key, encData, `s1:${userId}`);
+      decryptedShares.push({ index: response.encShares.S1_index || 1, data: shareData });
+    }
+
+    if (factors.includes(FactorType.WEBAUTHN)) {
+      const storage = shareStorage.createUserStorage(userId);
+      const share = await storage.getShare('S2');
+      if (share) {
+        const s2Key = await deriveS2Key(factorData.webauthnAuthData, factorData.webauthnCredentialId);
+        const encData = cryptoUtils.base64ToUint8Array(share.encryptedShare);
+        const shareData = await cryptoUtils.unpackAndDecrypt(s2Key, encData, `s2:${userId}`);
+        decryptedShares.push({ index: response.encShares?.S2_index || 2, data: shareData });
+      }
+    }
+
+    if (factors.includes(FactorType.TOTP) && response.encShares?.S3) {
+      const metadata = await shareStorage.getMetadata(userId);
+      const s3Salt = metadata?.s3Salt ? cryptoUtils.base64ToUint8Array(metadata.s3Salt) : cryptoUtils.generateSalt(16);
+      const s3Key = await deriveS3Key(factorData.totpSeed, s3Salt);
+      const encData = cryptoUtils.base64ToUint8Array(response.encShares.S3);
+      const shareData = await cryptoUtils.unpackAndDecrypt(s3Key, encData, `s3:${userId}`);
+      decryptedShares.push({ index: response.encShares.S3_index || 3, data: shareData });
+    }
+
+    if (decryptedShares.length < 2) {
+      const err = new Error('Could not decrypt enough shares');
+      err.code = KeyRecoveryError.DECRYPTION_FAILED;
+      throw err;
+    }
+
+    const kUser = combineShares(decryptedShares.slice(0, 2));
+    const proof = await this._generateProof(kUser, userId);
+
+    await this.sendMessage({ type: 'key_recovery_complete', userId, proof });
+    return kUser;
+  }
+
+  /**
+   * Unenroll from key recovery
+   * @param {string} userId - User identifier
+   * @returns {Promise<void>}
+   */
+  async unenroll(userId) {
+    await shareStorage.deleteAllUserData(userId);
+    await this.sendMessage({ type: 'key_recovery_unenroll', userId });
+  }
+
+  /**
+   * Split secret using SSS
+   * @private
+   * @param {Uint8Array} secret - Secret to split
+   * @param {number} threshold - Threshold
+   * @param {number} totalShares - Total shares
+   * @returns {Array}
+   */
+  _splitSecret(secret, threshold, totalShares) {
+    const shares = [];
+    for (let i = 0; i < totalShares; i++) {
+      shares.push({ index: i + 1, data: new Uint8Array(secret.length) });
+    }
+
+    for (let byteIdx = 0; byteIdx < secret.length; byteIdx++) {
+      const coefficients = new Uint8Array(threshold);
+      coefficients[0] = secret[byteIdx];
+      for (let c = 1; c < threshold; c++) {
+        coefficients[c] = cryptoUtils.randomBytes(1)[0];
+      }
+      for (let shareIdx = 0; shareIdx < totalShares; shareIdx++) {
+        shares[shareIdx].data[byteIdx] = evaluatePolynomial(coefficients, shares[shareIdx].index);
+      }
+    }
+
+    return shares;
+  }
+
+  /**
+   * Generate K_user proof
+   * @private
+   * @param {Uint8Array} kUser - User key
+   * @param {string} userId - User identifier
+   * @returns {Promise<string>}
+   */
+  async _generateProof(kUser, userId) {
+    const key = await crypto.subtle.importKey('raw', kUser, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const data = cryptoUtils.stringToUint8Array(`api-ape:key-recovery:proof:${userId}`);
+    const signature = await crypto.subtle.sign('HMAC', key, data);
+    return cryptoUtils.uint8ArrayToBase64(new Uint8Array(signature));
+  }
+}
+
+const { gfMul, gfDiv, gfAdd, lagrangeInterpolate } = require('./recovery/sss-browser');
+
+module.exports = {
+  KeyRecoveryClient,
+  KeyRecoveryError,
+  FactorType,
+  deriveS1Key,
+  deriveS2Key,
+  deriveS3Key,
+  combineShares,
+  deserializeShare,
+  serializeShare,
+
+  // Expose for testing
+  _gfMul: gfMul,
+  _gfDiv: gfDiv,
+  _gfAdd: gfAdd,
+  _lagrangeInterpolate: lagrangeInterpolate,
+};

package/client/auth/recovery/constants.js

@@ -0,0 +1,37 @@
+/**
+ * @file Key recovery error codes and factor types
+ */
+'use strict';
+
+/**
+ * Error codes for key recovery operations
+ * @enum {string}
+ */
+const KeyRecoveryError = {
+  NOT_ENROLLED: 'NOT_ENROLLED',
+  ALREADY_ENROLLED: 'ALREADY_ENROLLED',
+  INSUFFICIENT_FACTORS: 'INSUFFICIENT_FACTORS',
+  INVALID_FACTOR: 'INVALID_FACTOR',
+  DECRYPTION_FAILED: 'DECRYPTION_FAILED',
+  RECONSTRUCTION_FAILED: 'RECONSTRUCTION_FAILED',
+  SERVER_ERROR: 'SERVER_ERROR',
+  WEBAUTHN_FAILED: 'WEBAUTHN_FAILED',
+  SHARE_MISMATCH: 'SHARE_MISMATCH',
+  PROOF_FAILED: 'PROOF_FAILED',
+  STORAGE_ERROR: 'STORAGE_ERROR',
+};
+
+/**
+ * Factor types for authentication
+ * @enum {string}
+ */
+const FactorType = {
+  OAUTH: 'oauth',
+  WEBAUTHN: 'webauthn',
+  TOTP: 'totp',
+};
+
+module.exports = {
+  KeyRecoveryError,
+  FactorType,
+};