api-ape 3.0.2 → 4.1.0

package/server/security/auth/mfa/sss.js

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Shamir Secret Sharing (SSS) Utilities
+ *
+ * Implements threshold secret sharing using GF(256) arithmetic.
+ *
+ * @module server/security/auth/mfa/sss
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const { SSSError } = require("./sss/constants");
+const { gfMul, gfDiv, gfAdd, evaluatePolynomial, lagrangeInterpolate } = require("./sss/gf256");
+const { serializeShare, deserializeShare, verifyShareFormat } = require("./sss/serialization");
+
+/**
+ * Split a secret into n shares with threshold k
+ *
+ * @param {Buffer|Uint8Array|string} secret - Secret to split
+ * @param {number} threshold - Minimum shares needed to reconstruct
+ * @param {number} totalShares - Total shares to generate
+ * @returns {Array} Array of shares with index and data
+ * @throws {Error} If parameters are invalid
+ */
+function split(secret, threshold, totalShares) {
+  if (threshold < 2) {
+    const err = new Error(`Threshold must be at least 2, got ${threshold}`);
+    err.code = SSSError.INVALID_THRESHOLD;
+    throw err;
+  }
+  if (totalShares < threshold) {
+    const err = new Error(`Total shares (${totalShares}) must be >= threshold (${threshold})`);
+    err.code = SSSError.INVALID_SHARE_COUNT;
+    throw err;
+  }
+  if (totalShares > 255) {
+    const err = new Error(`Total shares (${totalShares}) must be <= 255 for GF(256)`);
+    err.code = SSSError.INVALID_SHARE_COUNT;
+    throw err;
+  }
+
+  let secretBuffer;
+  if (typeof secret === "string") secretBuffer = Buffer.from(secret, "utf8");
+  else if (secret instanceof Uint8Array) secretBuffer = Buffer.from(secret);
+  else if (Buffer.isBuffer(secret)) secretBuffer = secret;
+  else {
+    const err = new Error("Secret must be a Buffer, Uint8Array, or string");
+    err.code = SSSError.INVALID_SECRET;
+    throw err;
+  }
+
+  if (secretBuffer.length === 0) {
+    const err = new Error("Secret cannot be empty");
+    err.code = SSSError.INVALID_SECRET;
+    throw err;
+  }
+
+  const coeffCount = threshold - 1;
+  const randomBytes = crypto.randomBytes(secretBuffer.length * coeffCount);
+
+  const shares = [];
+  for (let i = 0; i < totalShares; i++) {
+    shares.push({ index: i + 1, data: Buffer.alloc(secretBuffer.length) });
+  }
+
+  for (let byteIdx = 0; byteIdx < secretBuffer.length; byteIdx++) {
+    const coefficients = new Uint8Array(threshold);
+    coefficients[0] = secretBuffer[byteIdx];
+    for (let c = 1; c < threshold; c++) {
+      coefficients[c] = randomBytes[byteIdx * coeffCount + (c - 1)];
+    }
+    for (let shareIdx = 0; shareIdx < totalShares; shareIdx++) {
+      shares[shareIdx].data[byteIdx] = evaluatePolynomial(coefficients, shares[shareIdx].index);
+    }
+  }
+  return shares;
+}
+
+/**
+ * Combine shares to reconstruct the original secret
+ *
+ * @param {Array} shares - Array of share objects
+ * @returns {Buffer} Reconstructed secret
+ * @throws {Error} If shares are insufficient or malformed
+ */
+function combine(shares) {
+  if (!Array.isArray(shares) || shares.length === 0) {
+    const err = new Error("Shares must be a non-empty array");
+    err.code = SSSError.INSUFFICIENT_SHARES;
+    throw err;
+  }
+  if (shares.length < 2) {
+    const err = new Error("At least 2 shares are required");
+    err.code = SSSError.INSUFFICIENT_SHARES;
+    throw err;
+  }
+
+  const secretLength = shares[0].data?.length;
+  if (!secretLength) {
+    const err = new Error("Invalid share format: missing data");
+    err.code = SSSError.INVALID_SHARE_FORMAT;
+    throw err;
+  }
+
+  const seenIndices = new Set();
+  for (const share of shares) {
+    if (typeof share.index !== "number" || share.index < 1 || share.index > 255) {
+      const err = new Error(`Invalid share index: ${share.index}. Must be 1-255`);
+      err.code = SSSError.INVALID_SHARE_FORMAT;
+      throw err;
+    }
+    if (!Buffer.isBuffer(share.data) && !(share.data instanceof Uint8Array)) {
+      const err = new Error("Share data must be a Buffer or Uint8Array");
+      err.code = SSSError.INVALID_SHARE_FORMAT;
+      throw err;
+    }
+    if (share.data.length !== secretLength) {
+      const err = new Error(`Share data length mismatch: expected ${secretLength}, got ${share.data.length}`);
+      err.code = SSSError.SHARE_INDEX_MISMATCH;
+      throw err;
+    }
+    if (seenIndices.has(share.index)) {
+      const err = new Error(`Duplicate share index: ${share.index}`);
+      err.code = SSSError.DUPLICATE_SHARE_INDEX;
+      throw err;
+    }
+    seenIndices.add(share.index);
+  }
+
+  const secret = Buffer.alloc(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;
+}
+
+/**
+ * Generate a new random secret
+ *
+ * @param {number} length - Length in bytes (default: 32)
+ * @returns {Buffer} Random secret
+ */
+function generateSecret(length = 32) {
+  return crypto.randomBytes(length);
+}
+
+module.exports = {
+  split,
+  combine,
+  serializeShare,
+  deserializeShare,
+  verifyShareFormat,
+  generateSecret,
+  SSSError,
+  _gfMul: gfMul,
+  _gfDiv: gfDiv,
+  _gfAdd: gfAdd,
+  _evaluatePolynomial: evaluatePolynomial,
+  _lagrangeInterpolate: lagrangeInterpolate,
+};

package/server/security/auth/mfa/two-of-three/constants.js

@@ -0,0 +1,58 @@
+/**
+ * @file Two-of-three message types, errors, and default configuration
+ */
+"use strict";
+
+/**
+ * Message types for two-of-three protocol
+ * @enum {string}
+ */
+const TwoOfThreeMessageType = {
+  ENROLLMENT_START: "key_recovery_enrollment_start",
+  ENROLLMENT_CHALLENGE: "key_recovery_enrollment_challenge",
+  ENROLLMENT_FINISH: "key_recovery_enrollment_finish",
+  ENROLLMENT_OK: "key_recovery_enrollment_ok",
+  ENROLLMENT_FAIL: "key_recovery_enrollment_fail",
+  RECOVERY_START: "key_recovery_start",
+  RECOVERY_SHARES: "key_recovery_shares",
+  RECOVERY_COMPLETE: "key_recovery_complete",
+  RECOVERY_OK: "key_recovery_ok",
+  RECOVERY_FAIL: "key_recovery_fail",
+  ROTATION_START: "key_recovery_rotation_start",
+  ROTATION_OK: "key_recovery_rotation_ok",
+  ROTATION_FAIL: "key_recovery_rotation_fail",
+};
+
+/**
+ * Error codes for two-of-three operations
+ * @enum {string}
+ */
+const TwoOfThreeError = {
+  INSUFFICIENT_FACTORS: "INSUFFICIENT_FACTORS",
+  INVALID_FACTOR: "INVALID_FACTOR",
+  SHARE_DECRYPTION_FAILED: "SHARE_DECRYPTION_FAILED",
+  RECONSTRUCTION_FAILED: "RECONSTRUCTION_FAILED",
+  NOT_ENROLLED: "NOT_ENROLLED",
+  ALREADY_ENROLLED: "ALREADY_ENROLLED",
+  ENROLLMENT_EXPIRED: "ENROLLMENT_EXPIRED",
+  INVALID_FLOW: "INVALID_FLOW",
+  REVOKED_SHARE: "REVOKED_SHARE",
+  INVALID_PROOF: "INVALID_PROOF",
+  PENDING_ENROLLMENT: "PENDING_ENROLLMENT",
+};
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG = {
+  requiredFactors: 2,
+  allowedFlows: ["oauth+totp", "oauth+webauthn", "webauthn+totp"],
+  enrollmentTimeout: 300000,
+  secretLength: 32,
+};
+
+module.exports = {
+  TwoOfThreeMessageType,
+  TwoOfThreeError,
+  DEFAULT_CONFIG,
+};

package/server/security/auth/mfa/two-of-three/files.md

@@ -0,0 +1,23 @@
+# Two-of-Three Module
+
+2-of-3 key recovery adapter components.
+
+## Directory Structure
+
+```
+two-of-three/
+├── constants.js - Message types, error codes, default config
+├── handlers.js  - Enrollment and recovery handler factories
+└── helpers.js   - Cleanup and utility functions
+```
+
+## Files
+
+### `constants.js`
+Defines TwoOfThreeMessageType, TwoOfThreeError, and DEFAULT_CONFIG.
+
+### `handlers.js`
+Factory functions for enrollment start/finish, recovery start/complete, and rotation handlers.
+
+### `helpers.js`
+Pending state cleanup and expiry management utilities.

package/server/security/auth/mfa/two-of-three/handlers.js

@@ -0,0 +1,241 @@
+/**
+ * @file Two-of-three enrollment, recovery, and rotation handlers
+ */
+"use strict";
+
+const crypto = require("crypto");
+const { serializeShare, generateSecret } = require("../sss");
+const { generateSalt } = require("../crypto-utils");
+const { ShareId, FactorType } = require("../ledger");
+const { TwoOfThreeMessageType, TwoOfThreeError } = require("./constants");
+const { generateChallenge, computeProofHash, getEnrollmentKey } = require("./helpers");
+
+/**
+ * Create enrollment handlers
+ * @param {Object} ctx - Context with ledger, maps, and config
+ * @returns {Object} Enrollment handler functions
+ */
+function createEnrollmentHandlers(ctx) {
+  const { ledger, pendingEnrollments, enrollmentTimeout, secretLength, cleanupExpired } = ctx;
+
+  /**
+   * Handle enrollment start
+   * @param {Object} params - Parameters
+   * @param {string} params.clientId - Client ID
+   * @param {string} params.userId - User ID
+   * @returns {Promise<Object>} Enrollment challenge
+   */
+  async function handleEnrollmentStart({ clientId, userId }) {
+    cleanupExpired();
+
+    if (await ledger.isEnrolled(userId)) {
+      const err = new Error(`User ${userId} is already enrolled`);
+      err.code = TwoOfThreeError.ALREADY_ENROLLED;
+      throw err;
+    }
+
+    const key = getEnrollmentKey(clientId, userId);
+    if (pendingEnrollments.has(key)) {
+      const err = new Error("Enrollment already in progress");
+      err.code = TwoOfThreeError.PENDING_ENROLLMENT;
+      throw err;
+    }
+
+    const kUser = generateSecret(secretLength);
+    const shares = require("../sss").split(kUser, 2, 3);
+    const challenge = generateChallenge();
+    const s3Salt = generateSalt(16);
+
+    pendingEnrollments.set(key, { userId, challenge, kUser, shares, s3Salt, expiresAt: Date.now() + enrollmentTimeout });
+    setTimeout(() => pendingEnrollments.delete(key), enrollmentTimeout + 1000);
+
+    return {
+      type: TwoOfThreeMessageType.ENROLLMENT_CHALLENGE,
+      challenge,
+      s3Salt: s3Salt.toString("base64"),
+      factorRequirements: {
+        S1: { factor: "oauth", description: "OAuth/OPAQUE authentication" },
+        S2: { factor: "webauthn", description: "WebAuthn credential" },
+        S3: { factor: "totp", description: "TOTP authenticator" },
+      },
+      shares: { S1: serializeShare(shares[0]), S2: serializeShare(shares[1]), S3: serializeShare(shares[2]) },
+    };
+  }
+
+  /**
+   * Handle enrollment finish
+   * @param {Object} params - Parameters
+   * @param {string} params.clientId - Client ID
+   * @param {string} params.userId - User ID
+   * @param {Object} params.encryptedShares - Encrypted shares
+   * @returns {Promise<Object>} Enrollment result
+   */
+  async function handleEnrollmentFinish({ clientId, userId, encryptedShares }) {
+    cleanupExpired();
+
+    const key = getEnrollmentKey(clientId, userId);
+    const pending = pendingEnrollments.get(key);
+
+    if (!pending) {
+      const err = new Error("No pending enrollment found or enrollment expired");
+      err.code = TwoOfThreeError.ENROLLMENT_EXPIRED;
+      throw err;
+    }
+
+    if (pending.expiresAt < Date.now()) {
+      pendingEnrollments.delete(key);
+      const err = new Error("Enrollment has expired");
+      err.code = TwoOfThreeError.ENROLLMENT_EXPIRED;
+      throw err;
+    }
+
+    if (!encryptedShares?.S1 || !encryptedShares?.S3) {
+      const err = new Error("Missing encrypted shares (S1 and S3 required)");
+      err.code = TwoOfThreeError.INVALID_FACTOR;
+      throw err;
+    }
+
+    const proofHash = computeProofHash(pending.kUser);
+
+    await ledger.storeShares(userId, {
+      [ShareId.S1]: { factor: FactorType.OAUTH, data: Buffer.from(encryptedShares.S1, "base64") },
+      [ShareId.S3]: { factor: FactorType.TOTP, data: Buffer.from(encryptedShares.S3, "base64") },
+    }, { proofHash });
+
+    pendingEnrollments.delete(key);
+
+    return {
+      type: TwoOfThreeMessageType.ENROLLMENT_OK,
+      userId,
+      shares: {
+        S1: { stored: true, factor: FactorType.OAUTH },
+        S2: { stored: false, factor: FactorType.WEBAUTHN, note: "Client-stored" },
+        S3: { stored: true, factor: FactorType.TOTP },
+      },
+    };
+  }
+
+  return { handleEnrollmentStart, handleEnrollmentFinish };
+}
+
+/**
+ * Create recovery handlers
+ * @param {Object} ctx - Context with ledger, maps, and config
+ * @returns {Object} Recovery handler functions
+ */
+function createRecoveryHandlers(ctx) {
+  const { ledger, pendingRecoveries, enrollmentTimeout, cleanupExpired } = ctx;
+
+  /**
+   * Handle recovery start
+   * @param {Object} params - Parameters
+   * @param {string} params.clientId - Client ID
+   * @param {string} params.userId - User ID
+   * @returns {Promise<Object>} Recovery shares and challenge
+   */
+  async function handleRecoveryStart({ clientId, userId }) {
+    cleanupExpired();
+
+    if (!(await ledger.isEnrolled(userId))) {
+      const err = new Error(`User ${userId} is not enrolled in key recovery`);
+      err.code = TwoOfThreeError.NOT_ENROLLED;
+      throw err;
+    }
+
+    const { shares, metadata } = await ledger.fetchShares(userId, [ShareId.S1, ShareId.S3]);
+    const challenge = generateChallenge();
+    const key = getEnrollmentKey(clientId, userId);
+    pendingRecoveries.set(key, { userId, challenge, expiresAt: Date.now() + enrollmentTimeout });
+
+    return {
+      type: TwoOfThreeMessageType.RECOVERY_SHARES,
+      challenge,
+      encShares: { S1: shares[ShareId.S1]?.toString("base64") || null, S3: shares[ShareId.S3]?.toString("base64") || null },
+      metadata: { S1: metadata[ShareId.S1], S2: metadata[ShareId.S2], S3: metadata[ShareId.S3] },
+    };
+  }
+
+  /**
+   * Handle recovery complete
+   * @param {Object} params - Parameters
+   * @param {string} params.clientId - Client ID
+   * @param {string} params.userId - User ID
+   * @param {string} params.proof - Recovery proof
+   * @returns {Promise<Object>} Recovery result
+   */
+  async function handleRecoveryComplete({ clientId, userId, proof }) {
+    cleanupExpired();
+
+    const key = getEnrollmentKey(clientId, userId);
+    const pending = pendingRecoveries.get(key);
+
+    if (!pending) {
+      const err = new Error("No pending recovery found");
+      err.code = TwoOfThreeError.INVALID_FLOW;
+      throw err;
+    }
+
+    if (proof) {
+      const storedProofHash = await ledger.getProofHash(userId);
+      if (storedProofHash) {
+        const expectedProof = crypto.createHmac("sha256", storedProofHash).update(pending.challenge).digest("base64");
+        if (proof !== expectedProof) {
+          const err = new Error("Invalid recovery proof");
+          err.code = TwoOfThreeError.INVALID_PROOF;
+          throw err;
+        }
+      }
+    }
+
+    pendingRecoveries.delete(key);
+    return { type: TwoOfThreeMessageType.RECOVERY_OK, userId, tier: 3 };
+  }
+
+  return { handleRecoveryStart, handleRecoveryComplete };
+}
+
+/**
+ * Create rotation handler
+ * @param {Object} ctx - Context with ledger
+ * @returns {Object} Rotation handler function
+ */
+function createRotationHandler(ctx) {
+  const { ledger } = ctx;
+
+  /**
+   * Handle share rotation
+   * @param {Object} params - Parameters
+   * @param {string} params.userId - User ID
+   * @param {string} params.shareId - Share ID
+   * @param {string} params.encryptedShare - Encrypted share data
+   * @param {string} params.reason - Rotation reason
+   * @returns {Promise<Object>} Rotation result
+   */
+  async function handleRotation({ userId, shareId, encryptedShare, reason = "rotation" }) {
+    if (!Object.values(ShareId).includes(shareId)) {
+      const err = new Error(`Invalid share ID: ${shareId}`);
+      err.code = TwoOfThreeError.INVALID_FACTOR;
+      throw err;
+    }
+
+    if (!(await ledger.isEnrolled(userId))) {
+      const err = new Error(`User ${userId} is not enrolled`);
+      err.code = TwoOfThreeError.NOT_ENROLLED;
+      throw err;
+    }
+
+    const metadata = await ledger.getShareMetadata(userId, shareId);
+
+    if (shareId === ShareId.S2) {
+      const result = await ledger.updateS2Metadata(userId, metadata.version + 1);
+      return { type: TwoOfThreeMessageType.ROTATION_OK, shareId, oldVersion: result.oldVersion, newVersion: result.newVersion };
+    }
+
+    const result = await ledger.rotateShare(userId, shareId, { factor: metadata.factor, data: Buffer.from(encryptedShare, "base64") }, reason);
+    return { type: TwoOfThreeMessageType.ROTATION_OK, shareId, oldVersion: result.oldVersion, newVersion: result.newVersion };
+  }
+
+  return { handleRotation };
+}
+
+module.exports = { createEnrollmentHandlers, createRecoveryHandlers, createRotationHandler };

package/server/security/auth/mfa/two-of-three/helpers.js

@@ -0,0 +1,71 @@
+/**
+ * @file Two-of-three helper functions
+ */
+"use strict";
+
+const crypto = require("crypto");
+const { timingSafeEqual } = require("../crypto-utils");
+
+/**
+ * Generate challenge nonce
+ * @returns {string} Base64url challenge
+ */
+function generateChallenge() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+/**
+ * Compute proof hash for K_user verification
+ * @param {Buffer} kUser - The user's key
+ * @returns {Buffer} SHA-256 hash of K_user
+ */
+function computeProofHash(kUser) {
+  return crypto.createHash("sha256").update(kUser).digest();
+}
+
+/**
+ * Verify proof of K_user possession
+ * @param {Buffer} kUser - Claimed K_user
+ * @param {Buffer} storedProofHash - Stored proof hash
+ * @returns {boolean} True if proof is valid
+ */
+function verifyProof(kUser, storedProofHash) {
+  const computedHash = computeProofHash(kUser);
+  return timingSafeEqual(computedHash, storedProofHash);
+}
+
+/**
+ * Get enrollment key for pending operations
+ * @param {string} clientId - Client identifier
+ * @param {string} userId - User identifier
+ * @returns {string} Combined key
+ */
+function getEnrollmentKey(clientId, userId) {
+  return `${clientId}:${userId}`;
+}
+
+/**
+ * Create a pending operation cleanup function
+ * @param {Map} pendingEnrollments - Pending enrollments map
+ * @param {Map} pendingRecoveries - Pending recoveries map
+ * @returns {Function} Cleanup function
+ */
+function createCleanupExpired(pendingEnrollments, pendingRecoveries) {
+  return function cleanupExpired() {
+    const now = Date.now();
+    for (const [key, pending] of pendingEnrollments) {
+      if (pending.expiresAt < now) pendingEnrollments.delete(key);
+    }
+    for (const [key, pending] of pendingRecoveries) {
+      if (pending.expiresAt < now) pendingRecoveries.delete(key);
+    }
+  };
+}
+
+module.exports = {
+  generateChallenge,
+  computeProofHash,
+  verifyProof,
+  getEnrollmentKey,
+  createCleanupExpired,
+};

package/server/security/auth/mfa/two-of-three.js

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Two-of-Three Authentication Adapter
+ *
+ * Implements 2-of-3 SSS key recovery for Tier 3 (HIGH_SECURITY).
+ * Compatible with Passport.js strategy interface.
+ *
+ * @module server/security/auth/mfa/two-of-three
+ */
+
+"use strict";
+
+const { createLedger } = require("./ledger");
+const { TwoOfThreeMessageType, TwoOfThreeError, DEFAULT_CONFIG } = require("./two-of-three/constants");
+const { createCleanupExpired } = require("./two-of-three/helpers");
+const { createEnrollmentHandlers, createRecoveryHandlers, createRotationHandler } = require("./two-of-three/handlers");
+
+/**
+ * Create a Two-of-Three Strategy
+ *
+ * @param {Object|Function} options - Config or verify callback
+ * @param {Function} verify - Verify callback (Passport.js style)
+ * @returns {Object} Two-of-three adapter/strategy
+ */
+function createTwoOfThreeStrategy(options, verify) {
+  let config = {};
+  let verifyCallback = null;
+
+  if (typeof options === "function") {
+    verifyCallback = options;
+  } else {
+    config = options || {};
+    verifyCallback = verify;
+  }
+
+  const {
+    requiredFactors = DEFAULT_CONFIG.requiredFactors,
+    allowedFlows = DEFAULT_CONFIG.allowedFlows,
+    enrollmentTimeout = DEFAULT_CONFIG.enrollmentTimeout,
+    secretLength = DEFAULT_CONFIG.secretLength,
+    passReqToCallback = false,
+    getRecord, saveRecord, deleteRecord,
+    auditEnabled = true, onAuditEvent,
+  } = config;
+
+  const ledger = createLedger({ getRecord, saveRecord, deleteRecord, auditEnabled, onAuditEvent });
+  const pendingEnrollments = new Map();
+  const pendingRecoveries = new Map();
+  const cleanupExpired = createCleanupExpired(pendingEnrollments, pendingRecoveries);
+
+  const ctx = { ledger, pendingEnrollments, pendingRecoveries, enrollmentTimeout, secretLength, cleanupExpired };
+  const { handleEnrollmentStart, handleEnrollmentFinish } = createEnrollmentHandlers(ctx);
+  const { handleRecoveryStart, handleRecoveryComplete } = createRecoveryHandlers(ctx);
+  const { handleRotation } = createRotationHandler(ctx);
+
+  /**
+   * Passport.js authenticate method
+   * @param {Object} req - Request object with recovery data
+   * @param {Object} authOptions - Authentication options
+   */
+  function authenticate(req, authOptions = {}) {
+    const self = this;
+    const { userId, factors, proof } = req.body || req;
+
+    if (!factors || Object.keys(factors).length < requiredFactors) {
+      return self.fail({ message: `At least ${requiredFactors} factors required`, code: TwoOfThreeError.INSUFFICIENT_FACTORS });
+    }
+
+    const factorKeys = Object.keys(factors).sort().join("+");
+    const normalizedFlow = factorKeys.toLowerCase();
+    if (!allowedFlows.some((f) => f === normalizedFlow || f.split("+").sort().join("+") === normalizedFlow)) {
+      return self.fail({ message: `Flow ${normalizedFlow} not allowed`, code: TwoOfThreeError.INVALID_FLOW });
+    }
+
+    if (verifyCallback) {
+      /**
+       * Passport.js verify callback handler
+       * @param {Error|null} err - Error if verification failed
+       * @param {Object|false} user - User object if verified, false if not
+       * @param {Object} info - Additional info about verification
+       * @returns {void}
+       */
+      const verified = (err, user, info) => {
+        if (err) return self.error(err);
+        if (!user) return self.fail(info);
+        return self.success(user, info);
+      };
+
+      if (passReqToCallback) return verifyCallback(req, { userId, factors, proof }, verified);
+      return verifyCallback({ userId, factors, proof }, verified);
+    }
+
+    self.success({ userId, tier: 3 }, { factors: Object.keys(factors) });
+  }
+
+  /**
+   * Clean up pending operations for a client
+   * @param {string} clientId - Client ID
+   * @returns {void}
+   */
+  function cleanupClient(clientId) {
+    for (const key of pendingEnrollments.keys()) {
+      if (key.startsWith(`${clientId}:`)) pendingEnrollments.delete(key);
+    }
+    for (const key of pendingRecoveries.keys()) {
+      if (key.startsWith(`${clientId}:`)) pendingRecoveries.delete(key);
+    }
+  }
+
+  return {
+    name: "two-of-three",
+    authenticate,
+    type: "two-of-three",
+    tier: 3,
+    MessageType: TwoOfThreeMessageType,
+    Error: TwoOfThreeError,
+    handleEnrollmentStart,
+    handleEnrollmentFinish,
+    handleRecoveryStart,
+    handleRecoveryComplete,
+    handleRotation,
+    isEnrolled: (userId) => ledger.isEnrolled(userId),
+    cleanupClient,
+    getShareVersions: (userId) => ledger.getVersions(userId),
+    ledger,
+    _pendingEnrollments: pendingEnrollments,
+    _pendingRecoveries: pendingRecoveries,
+  };
+}
+
+module.exports = {
+  createTwoOfThreeStrategy,
+  Strategy: createTwoOfThreeStrategy,
+  TwoOfThreeMessageType,
+  TwoOfThreeError,
+  DEFAULT_CONFIG,
+};