api-ape 3.0.1 → 4.1.0

package/client/auth/recovery/files.md

@@ -0,0 +1,23 @@
+# Client Auth Recovery Module
+
+Browser-side key recovery using Shamir Secret Sharing.
+
+## Directory Structure
+
+```
+recovery/
+├── constants.js      - Recovery error codes and factor types
+├── key-derivation.js - Per-factor key derivation (S1, S2, S3)
+└── sss-browser.js    - Shamir Secret Sharing for browser (GF256)
+```
+
+## Files
+
+### `constants.js`
+Defines KeyRecoveryError codes and FactorType enum (OAUTH, WEBAUTHN, TOTP).
+
+### `key-derivation.js`
+Derives encryption keys for each share: deriveS1Key (OAuth), deriveS2Key (WebAuthn), deriveS3Key (TOTP).
+
+### `sss-browser.js`
+Implements Shamir Secret Sharing over GF(256) for browsers. Includes Lagrange interpolation, share serialization, and Galois field arithmetic.

package/client/auth/recovery/key-derivation.js

@@ -0,0 +1,61 @@
+/**
+ * @file Factor-specific key derivation functions
+ */
+'use strict';
+
+const cryptoUtils = require('../crypto-utils');
+
+/**
+ * Derive S1 encryption key from OAuth token
+ * @param {string} oauthToken - OAuth access token
+ * @param {string} userId - User identifier
+ * @returns {Promise<Uint8Array>}
+ */
+async function deriveS1Key(oauthToken, userId) {
+  return cryptoUtils.hkdf(
+    cryptoUtils.stringToUint8Array(oauthToken),
+    cryptoUtils.stringToUint8Array(`api-ape:s1:${userId}`),
+    cryptoUtils.stringToUint8Array('S1_key'),
+    32
+  );
+}
+
+/**
+ * Derive S2 encryption key from WebAuthn data
+ * @param {Uint8Array} authenticatorData - WebAuthn data
+ * @param {string} credentialId - Credential ID
+ * @returns {Promise<Uint8Array>}
+ */
+async function deriveS2Key(authenticatorData, credentialId) {
+  return cryptoUtils.hkdf(
+    authenticatorData,
+    cryptoUtils.stringToUint8Array(credentialId),
+    cryptoUtils.stringToUint8Array('S2_key'),
+    32
+  );
+}
+
+/**
+ * Derive S3 encryption key from TOTP seed
+ * @param {string} totpSeed - TOTP seed
+ * @param {Uint8Array} salt - Salt value
+ * @returns {Promise<Uint8Array>}
+ */
+async function deriveS3Key(totpSeed, salt) {
+  return cryptoUtils.argon2id(
+    cryptoUtils.stringToUint8Array(totpSeed),
+    salt,
+    {
+      memoryCost: 65536,
+      timeCost: 3,
+      parallelism: 4,
+      hashLength: 32
+    }
+  );
+}
+
+module.exports = {
+  deriveS1Key,
+  deriveS2Key,
+  deriveS3Key,
+};

package/client/auth/recovery/sss-browser.js

@@ -0,0 +1,189 @@
+/**
+ * @file Shamir Secret Sharing for browser (GF(256))
+ */
+'use strict';
+
+const { KeyRecoveryError } = require('./constants');
+
+/**
+ * Pre-computed log and exp tables for GF(256)
+ * @type {Object}
+ */
+const GF256 = (function initGF256() {
+  const exp = new Uint8Array(512);
+  const log = new Uint8Array(256);
+
+  let x = 1;
+  for (let i = 0; i < 255; i++) {
+    exp[i] = x;
+    exp[i + 255] = x;
+    log[x] = i;
+    x = x ^ ((x << 1) ^ (x & 0x80 ? 0x11b : 0));
+  }
+  log[0] = 0;
+  exp[510] = exp[0];
+
+  return { exp, log };
+})();
+
+/**
+ * Multiply in GF(256)
+ * @param {number} a - First operand
+ * @param {number} b - Second operand
+ * @returns {number}
+ */
+function gfMul(a, b) {
+  if (a === 0 || b === 0) return 0;
+  return GF256.exp[GF256.log[a] + GF256.log[b]];
+}
+
+/**
+ * Divide in GF(256)
+ * @param {number} a - Dividend
+ * @param {number} b - Divisor
+ * @returns {number}
+ */
+function gfDiv(a, b) {
+  if (b === 0) throw new Error('Division by zero in GF(256)');
+  if (a === 0) return 0;
+  return GF256.exp[GF256.log[a] + 255 - GF256.log[b]];
+}
+
+/**
+ * Add in GF(256) (XOR)
+ * @param {number} a - First operand
+ * @param {number} b - Second operand
+ * @returns {number}
+ */
+function gfAdd(a, b) {
+  return a ^ b;
+}
+
+/**
+ * Lagrange interpolation to find f(0)
+ * @param {Array} points - Array of point objects
+ * @returns {number}
+ */
+function lagrangeInterpolate(points) {
+  let result = 0;
+
+  for (let i = 0; i < points.length; i++) {
+    let numerator = 1;
+    let denominator = 1;
+
+    for (let j = 0; j < points.length; j++) {
+      if (i !== j) {
+        numerator = gfMul(numerator, points[j].x);
+        denominator = gfMul(denominator, gfAdd(points[i].x, points[j].x));
+      }
+    }
+
+    const basis = gfMul(points[i].y, gfDiv(numerator, denominator));
+    result = gfAdd(result, basis);
+  }
+
+  return result;
+}
+
+/**
+ * Combine shares to reconstruct secret
+ * @param {Array} shares - Share objects
+ * @returns {Uint8Array}
+ */
+function combineShares(shares) {
+  if (!Array.isArray(shares) || shares.length < 2) {
+    const err = new Error('At least 2 shares required');
+    err.code = KeyRecoveryError.INSUFFICIENT_FACTORS;
+    throw err;
+  }
+
+  const secretLength = shares[0].data.length;
+  const secret = new Uint8Array(secretLength);
+
+  for (let byteIdx = 0; byteIdx < secretLength; byteIdx++) {
+    const points = shares.map(share => ({
+      x: share.index,
+      y: share.data[byteIdx]
+    }));
+    secret[byteIdx] = lagrangeInterpolate(points);
+  }
+
+  return secret;
+}
+
+/**
+ * Deserialize share from base64url
+ * @param {string} serialized - Serialized share
+ * @returns {Object}
+ */
+function deserializeShare(serialized) {
+  if (typeof serialized !== 'string' || serialized.length === 0) {
+    const err = new Error('Invalid serialized share');
+    err.code = KeyRecoveryError.INVALID_FACTOR;
+    throw err;
+  }
+
+  const base64 = serialized.replace(/-/g, '+').replace(/_/g, '/');
+  const binary = atob(base64);
+  const packed = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    packed[i] = binary.charCodeAt(i);
+  }
+
+  if (packed.length < 2) {
+    const err = new Error('Serialized share too short');
+    err.code = KeyRecoveryError.INVALID_FACTOR;
+    throw err;
+  }
+
+  return {
+    index: packed[0],
+    data: packed.slice(1)
+  };
+}
+
+/**
+ * Serialize share to base64url
+ * @param {Object} share - Share to serialize
+ * @param {number} share.index - Share index
+ * @param {Uint8Array} share.data - Share data
+ * @returns {string}
+ */
+function serializeShare(share) {
+  const packed = new Uint8Array(1 + share.data.length);
+  packed[0] = share.index;
+  packed.set(share.data, 1);
+
+  let binary = '';
+  for (let i = 0; i < packed.length; i++) {
+    binary += String.fromCharCode(packed[i]);
+  }
+
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Evaluate polynomial at x using Horner's method
+ * @param {Uint8Array} coefficients - Polynomial coefficients
+ * @param {number} x - Point to evaluate
+ * @returns {number}
+ */
+function evaluatePolynomial(coefficients, x) {
+  let result = 0;
+  for (let i = coefficients.length - 1; i >= 0; i--) {
+    result = gfAdd(gfMul(result, x), coefficients[i]);
+  }
+  return result;
+}
+
+module.exports = {
+  combineShares,
+  deserializeShare,
+  serializeShare,
+  evaluatePolynomial,
+  lagrangeInterpolate,
+  gfMul,
+  gfDiv,
+  gfAdd,
+  GF256,
+};

package/client/auth/share-storage.js

@@ -0,0 +1,205 @@
+/**
+ * @file IndexedDB Storage for S2 Share (WebAuthn-gated)
+ *
+ * Stores the encrypted S2 share and wrapped L_key locally in the browser.
+ * S2 is encrypted with L_key, which is derived from WebAuthn authenticator data.
+ *
+ * @module client/auth/share-storage
+ */
+'use strict';
+
+const {
+  DB_NAME,
+  DB_VERSION,
+  STORE_SHARES,
+  STORE_KEYS,
+  STORE_METADATA,
+} = require('./storage/constants');
+
+const { openDatabase, clearDatabase } = require('./storage/db');
+
+const {
+  saveShare,
+  getShare,
+  getAllShares,
+  deleteShare,
+  getShareVersion,
+} = require('./storage/shares');
+
+const {
+  saveWrappedKey,
+  getWrappedKey,
+  getAllWrappedKeys,
+  deleteWrappedKey,
+} = require('./storage/keys');
+
+/**
+ * Save enrollment metadata for a user
+ * @param {string} userId - User identifier
+ * @param {Object} [metadata] - Enrollment metadata
+ * @returns {Promise<void>}
+ */
+async function saveMetadata(userId, metadata = {}) {
+  if (!userId || typeof userId !== 'string') {
+    throw new Error('userId is required and must be a string');
+  }
+
+  const db = await openDatabase();
+
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_METADATA, 'readwrite');
+    const store = tx.objectStore(STORE_METADATA);
+
+    const now = Date.now();
+    const record = {
+      userId,
+      enrolledAt: metadata.enrolledAt || now,
+      lastRecoveryAt: metadata.lastRecoveryAt || null,
+      shareCount: metadata.shareCount || 0,
+      ...metadata,
+      updatedAt: now
+    };
+
+    store.put(record);
+
+    tx.oncomplete = () => { db.close(); resolve(); };
+    tx.onerror = () => { db.close(); reject(tx.error); };
+  });
+}
+
+/**
+ * Get enrollment metadata for a user
+ * @param {string} userId - User identifier
+ * @returns {Promise<Object|null>}
+ */
+async function getMetadata(userId) {
+  if (!userId || typeof userId !== 'string') {
+    throw new Error('userId is required and must be a string');
+  }
+
+  const db = await openDatabase();
+
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_METADATA, 'readonly');
+    const store = tx.objectStore(STORE_METADATA);
+
+    const request = store.get(userId);
+
+    request.onsuccess = () => resolve(request.result || null);
+    request.onerror = () => reject(request.error);
+
+    tx.oncomplete = () => db.close();
+  });
+}
+
+/**
+ * Delete all data for a user
+ * @param {string} userId - User identifier
+ * @returns {Promise<Object>} Count of deleted items
+ */
+async function deleteAllUserData(userId) {
+  if (!userId || typeof userId !== 'string') {
+    throw new Error('userId is required and must be a string');
+  }
+
+  const db = await openDatabase();
+
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction([STORE_SHARES, STORE_KEYS, STORE_METADATA], 'readwrite');
+
+    let sharesDeleted = 0;
+    let keysDeleted = 0;
+
+    const sharesStore = tx.objectStore(STORE_SHARES);
+    const sharesIndex = sharesStore.index('userId');
+    const sharesCursor = sharesIndex.openCursor(userId);
+
+    sharesCursor.onsuccess = (event) => {
+      const cursor = event.target.result;
+      if (cursor) {
+        sharesStore.delete(cursor.primaryKey);
+        sharesDeleted++;
+        cursor.continue();
+      }
+    };
+
+    const keysStore = tx.objectStore(STORE_KEYS);
+    const keysIndex = keysStore.index('userId');
+    const keysCursor = keysIndex.openCursor(userId);
+
+    keysCursor.onsuccess = (event) => {
+      const cursor = event.target.result;
+      if (cursor) {
+        keysStore.delete(cursor.primaryKey);
+        keysDeleted++;
+        cursor.continue();
+      }
+    };
+
+    const metadataStore = tx.objectStore(STORE_METADATA);
+    metadataStore.delete(userId);
+
+    tx.oncomplete = () => { db.close(); resolve({ shares: sharesDeleted, keys: keysDeleted }); };
+    tx.onerror = () => { db.close(); reject(tx.error); };
+  });
+}
+
+/**
+ * Check if a user has enrolled
+ * @param {string} userId - User identifier
+ * @returns {Promise<boolean>}
+ */
+async function isEnrolled(userId) {
+  const metadata = await getMetadata(userId);
+  return metadata !== null && metadata.enrolledAt !== undefined;
+}
+
+/**
+ * Create a storage instance with bound userId
+ * @param {string} userId - User identifier
+ * @returns {Object} Storage API bound to userId
+ */
+function createUserStorage(userId) {
+  if (!userId || typeof userId !== 'string') {
+    throw new Error('userId is required and must be a string');
+  }
+
+  return {
+    userId,
+    saveShare: (shareId, encryptedShare, version) => saveShare(userId, shareId, encryptedShare, version),
+    getShare: (shareId) => getShare(userId, shareId),
+    getAllShares: () => getAllShares(userId),
+    deleteShare: (shareId) => deleteShare(userId, shareId),
+    getShareVersion: (shareId) => getShareVersion(userId, shareId),
+    saveWrappedKey: (keyId, wrappedKey) => saveWrappedKey(userId, keyId, wrappedKey),
+    getAllWrappedKeys: () => getAllWrappedKeys(userId),
+    saveMetadata: (metadata) => saveMetadata(userId, metadata),
+    getMetadata: () => getMetadata(userId),
+    isEnrolled: () => isEnrolled(userId),
+    deleteAll: () => deleteAllUserData(userId)
+  };
+}
+
+module.exports = {
+  openDatabase,
+  clearDatabase,
+  saveShare,
+  getShare,
+  getAllShares,
+  deleteShare,
+  getShareVersion,
+  saveWrappedKey,
+  getWrappedKey,
+  getAllWrappedKeys,
+  deleteWrappedKey,
+  saveMetadata,
+  getMetadata,
+  deleteAllUserData,
+  isEnrolled,
+  createUserStorage,
+  DB_NAME,
+  DB_VERSION,
+  STORE_SHARES,
+  STORE_KEYS,
+  STORE_METADATA
+};

package/client/auth/storage/constants.js

@@ -0,0 +1,18 @@
+/**
+ * @file IndexedDB storage constants
+ */
+'use strict';
+
+const DB_NAME = 'KeyRecoveryStore';
+const DB_VERSION = 1;
+const STORE_SHARES = 'shares';
+const STORE_KEYS = 'keys';
+const STORE_METADATA = 'metadata';
+
+module.exports = {
+  DB_NAME,
+  DB_VERSION,
+  STORE_SHARES,
+  STORE_KEYS,
+  STORE_METADATA,
+};

package/client/auth/storage/db.js

@@ -0,0 +1,132 @@
+/**
+ * @file IndexedDB database initialization and transaction helpers
+ */
+'use strict';
+
+const {
+  DB_NAME,
+  DB_VERSION,
+  STORE_SHARES,
+  STORE_KEYS,
+  STORE_METADATA,
+} = require('./constants');
+
+/**
+ * Open the IndexedDB database
+ * @returns {Promise<IDBDatabase>}
+ */
+function openDatabase() {
+  return new Promise((resolve, reject) => {
+    if (typeof indexedDB === 'undefined') {
+      reject(new Error('IndexedDB not available'));
+      return;
+    }
+
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+    request.onerror = () => {
+      reject(new Error(`Failed to open database: ${request.error?.message || 'Unknown error'}`));
+    };
+
+    request.onsuccess = () => {
+      resolve(request.result);
+    };
+
+    request.onupgradeneeded = (event) => {
+      const db = event.target.result;
+
+      if (!db.objectStoreNames.contains(STORE_SHARES)) {
+        const sharesStore = db.createObjectStore(STORE_SHARES, { keyPath: 'id', autoIncrement: true });
+        sharesStore.createIndex('userId', 'userId', { unique: false });
+        sharesStore.createIndex('shareId', 'shareId', { unique: true });
+        sharesStore.createIndex('userShare', ['userId', 'shareId'], { unique: true });
+      }
+
+      if (!db.objectStoreNames.contains(STORE_KEYS)) {
+        const keysStore = db.createObjectStore(STORE_KEYS, { keyPath: 'id', autoIncrement: true });
+        keysStore.createIndex('userId', 'userId', { unique: false });
+        keysStore.createIndex('keyId', 'keyId', { unique: true });
+      }
+
+      if (!db.objectStoreNames.contains(STORE_METADATA)) {
+        db.createObjectStore(STORE_METADATA, { keyPath: 'userId' });
+      }
+    };
+  });
+}
+
+/**
+ * Execute a transaction on the database
+ * @param {string|Array} storeNames - Store name(s)
+ * @param {string} mode - Transaction mode
+ * @param {Function} operation - Operation function
+ * @returns {Promise<*>}
+ */
+async function withTransaction(storeNames, mode, operation) {
+  const db = await openDatabase();
+
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(storeNames, mode);
+
+    tx.onerror = () => {
+      reject(new Error(`Transaction failed: ${tx.error?.message || 'Unknown error'}`));
+    };
+
+    tx.oncomplete = () => {
+      db.close();
+    };
+
+    try {
+      const result = operation(tx);
+
+      if (result && typeof result.then === 'function') {
+        result.then(resolve).catch(reject);
+      } else {
+        tx.oncomplete = () => {
+          db.close();
+          resolve(result);
+        };
+      }
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+/**
+ * Wrap an IDBRequest in a Promise
+ * @param {IDBRequest} request - Request to wrap
+ * @returns {Promise<*>}
+ */
+function promisifyRequest(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+/**
+ * Clear the entire database
+ * @returns {Promise<void>}
+ */
+function clearDatabase() {
+  return new Promise((resolve, reject) => {
+    if (typeof indexedDB === 'undefined') {
+      reject(new Error('IndexedDB not available'));
+      return;
+    }
+
+    const request = indexedDB.deleteDatabase(DB_NAME);
+
+    request.onsuccess = () => resolve();
+    request.onerror = () => reject(request.error);
+    request.onblocked = () => reject(new Error('Database deletion blocked'));
+  });
+}
+
+module.exports = {
+  openDatabase,
+  withTransaction,
+  promisifyRequest,
+  clearDatabase,
+};

package/client/auth/storage/files.md

@@ -0,0 +1,27 @@
+# Client Auth Storage Module
+
+IndexedDB storage for encrypted shares and keys.
+
+## Directory Structure
+
+```
+storage/
+├── constants.js - Storage constants (DB name, store names)
+├── db.js        - IndexedDB connection management
+├── keys.js      - Wrapped key storage operations
+└── shares.js    - Encrypted share storage operations
+```
+
+## Files
+
+### `constants.js`
+Defines StorageError codes, database name, and object store names.
+
+### `db.js`
+Manages IndexedDB connection lifecycle with version upgrades and cleanup.
+
+### `shares.js`
+CRUD operations for encrypted shares in IndexedDB with versioning.
+
+### `keys.js`
+Storage for WebAuthn-wrapped keys to decrypt S2 share.