api-ape 3.0.2 → 4.1.0

package/server/security/auth/nonce-manager.js

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Nonce Manager for api-ape Authentication
+ *
+ * Handles single-use server nonce generation, validation, and consumption.
+ *
+ * @module server/security/auth/nonce-manager
+ * @see {@link module:server/security/auth/state-machine} for the main state machine
+ */
+
+const crypto = require("crypto");
+
+/**
+ * Create nonce management functions
+ *
+ * @param {Object} deps - Dependencies
+ * @param {number} deps.nonceExpiry - Nonce expiry time in ms
+ * @param {Object} deps.AuthError - Error code enum
+ * @returns {Object} Nonce management functions
+ */
+function createNonceManager(deps) {
+  const { nonceExpiry, AuthError } = deps;
+
+  const usedNonces = new Set();
+  const pendingNonces = new Map();
+
+  /**
+   * Generate a single-use server nonce
+   * @param {number} [length=32] - Nonce length in bytes
+   * @returns {Object} Nonce info { nonce, expiresAt }
+   */
+  function generateNonce(length = 32) {
+    const nonce = crypto.randomBytes(length).toString("base64url");
+    const expiresAt = Date.now() + nonceExpiry;
+    pendingNonces.set(nonce, { expiresAt, used: false });
+    setTimeout(() => {
+      pendingNonces.delete(nonce);
+    }, nonceExpiry + 1000);
+    return { nonce, expiresAt };
+  }
+
+  /**
+   * Validate and consume a nonce
+   * @param {string} nonce - The nonce to validate
+   * @returns {boolean} True if valid
+   * @throws {Error} If nonce is expired, reused, or invalid
+   */
+  function consumeNonce(nonce) {
+    if (usedNonces.has(nonce)) {
+      const err = new Error("Nonce already used");
+      err.code = AuthError.NONCE_REUSED;
+      throw err;
+    }
+    const nonceInfo = pendingNonces.get(nonce);
+    if (!nonceInfo) {
+      const err = new Error("Invalid or expired nonce");
+      err.code = AuthError.NONCE_EXPIRED;
+      throw err;
+    }
+    if (Date.now() > nonceInfo.expiresAt) {
+      pendingNonces.delete(nonce);
+      const err = new Error("Nonce expired");
+      err.code = AuthError.NONCE_EXPIRED;
+      throw err;
+    }
+    pendingNonces.delete(nonce);
+    usedNonces.add(nonce);
+    setTimeout(() => {
+      usedNonces.delete(nonce);
+    }, nonceExpiry * 2);
+    return true;
+  }
+
+  /**
+   * Clear all pending nonces
+   */
+  function clearPendingNonces() {
+    pendingNonces.clear();
+  }
+
+  return {
+    generateNonce,
+    consumeNonce,
+    clearPendingNonces,
+  };
+}
+
+module.exports = {
+  createNonceManager,
+};

package/server/security/auth/state-machine-mfa.js

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview MFA Elevation Module for api-ape Server
+ *
+ * Provides MFA (Multi-Factor Authentication) elevation functions
+ * and Key Recovery (2-of-3 Tier 3) elevation for the authentication state machine.
+ *
+ * @module server/security/auth/state-machine-mfa
+ * @see {@link module:server/security/auth/state-machine} for the main state machine
+ */
+
+/**
+ * Create MFA elevation functions
+ *
+ * @param {Object} deps - Dependencies
+ * @param {Function} deps.getState - Get current state function
+ * @param {Function} deps.getTier - Get current tier function
+ * @param {Function} deps.transition - State transition function
+ * @param {Function} deps.generateNonce - Nonce generator
+ * @param {Function} deps.getPrincipal - Get principal function
+ * @param {Function} deps.setPrincipal - Set principal function
+ * @param {Object} deps.AuthState - State enum
+ * @param {Object} deps.AuthTier - Tier enum
+ * @param {Object} deps.AuthError - Error enum
+ * @returns {Object} MFA functions
+ */
+function createMFAFunctions(deps) {
+  const {
+    getState,
+    getTier,
+    transition,
+    generateNonce,
+    getPrincipal,
+    setPrincipal,
+    AuthState,
+    AuthTier,
+    AuthError,
+  } = deps;
+
+  // Track pending key recovery challenges
+  let pendingKeyRecovery = null;
+
+  /**
+   * Start MFA elevation flow
+   *
+   * @param {string[]} methods - Available MFA methods
+   * @throws {Error} If not at Tier 1
+   * @returns {Object} MFA challenge info
+   */
+  function startMFA(methods) {
+    const state = getState();
+    if (state.state !== AuthState.AUTHENTICATED) {
+      const err = new Error("Must be authenticated before MFA");
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+
+    transition(AuthState.MFA_PENDING);
+
+    return {
+      state: AuthState.MFA_PENDING,
+      methods,
+      challenge: generateNonce(),
+    };
+  }
+
+  /**
+   * Complete MFA elevation
+   *
+   * @param {string} method - MFA method used
+   * @returns {Object} Elevation result
+   */
+  function completeMFA(method) {
+    const state = getState();
+    if (state.state !== AuthState.MFA_PENDING) {
+      const err = new Error("Not in MFA pending state");
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+
+    transition(AuthState.ELEVATED);
+
+    const principal = getPrincipal();
+    principal.elevatedAt = Date.now();
+    principal.mfaMethod = method;
+    setPrincipal(principal);
+
+    return {
+      state: AuthState.ELEVATED,
+      tier: getTier(),
+      principal,
+    };
+  }
+
+  /**
+   * Get current auth state snapshot
+   * @returns {Object} Current state info
+   */
+  function getStateSnapshot() {
+    const state = getState();
+    const principal = getPrincipal();
+    const tier = getTier();
+    return {
+      state: state.state,
+      tier,
+      principal: principal ? { ...principal } : null,
+      isAuthenticated: tier >= AuthTier.BASIC,
+      isElevated: tier >= AuthTier.ELEVATED,
+      isHighSecurity: tier >= AuthTier.HIGH_SECURITY,
+      keyRecoveryPending: pendingKeyRecovery !== null,
+    };
+  }
+
+  // ============================================================
+  // Key Recovery (2-of-3 Tier 3) Functions
+  // ============================================================
+
+  /**
+   * Start key recovery elevation flow
+   * Requires ELEVATED tier (Tier 2)
+   *
+   * @param {Object} options - Key recovery options
+   * @param {string[]} options.factors - Available factors ['oauth', 'webauthn', 'totp']
+   * @returns {Object} Key recovery challenge info
+   * @throws {Error} If not at ELEVATED tier
+   */
+  function startKeyRecovery(options = {}) {
+    const state = getState();
+
+    // Can start from AUTHENTICATED or ELEVATED
+    if (state.state !== AuthState.ELEVATED && state.state !== AuthState.AUTHENTICATED) {
+      const err = new Error("Must be authenticated or elevated before key recovery");
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+
+    // If starting from AUTHENTICATED, automatically elevate for key recovery
+    // This handles direct Tier 1 -> Tier 3 path
+    if (state.state === AuthState.AUTHENTICATED) {
+      // Key recovery can start from AUTHENTICATED per VALID_TRANSITIONS
+    }
+
+    transition(AuthState.KEY_RECOVERY_PENDING);
+
+    const challenge = generateNonce();
+    pendingKeyRecovery = {
+      challenge,
+      startedAt: Date.now(),
+      factors: options.factors || ['oauth', 'webauthn', 'totp'],
+      verifiedFactors: [],
+    };
+
+    return {
+      state: AuthState.KEY_RECOVERY_PENDING,
+      challenge,
+      factors: pendingKeyRecovery.factors,
+    };
+  }
+
+  /**
+   * Complete key recovery with proof
+   *
+   * @param {Object} params - Completion parameters
+   * @param {string} params.proof - HMAC proof that client reconstructed K_user
+   * @param {string[]} params.usedFactors - The two factors used for recovery
+   * @returns {Object} Elevation result
+   * @throws {Error} If not in KEY_RECOVERY_PENDING state or proof invalid
+   */
+  function completeKeyRecovery(params) {
+    const { proof, usedFactors } = params;
+
+    const state = getState();
+    if (state.state !== AuthState.KEY_RECOVERY_PENDING) {
+      const err = new Error("Not in key recovery pending state");
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+
+    if (!pendingKeyRecovery) {
+      const err = new Error("No pending key recovery challenge");
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+
+    if (!proof || typeof proof !== 'string') {
+      const err = new Error("Invalid key recovery proof");
+      err.code = AuthError.INVALID_PROOF;
+      throw err;
+    }
+
+    if (!Array.isArray(usedFactors) || usedFactors.length !== 2) {
+      const err = new Error("Must use exactly 2 factors for key recovery");
+      err.code = AuthError.INVALID_PROOF;
+      throw err;
+    }
+
+    // Note: Actual proof verification happens in the two-of-three adapter
+    // The state machine just manages the state transitions
+
+    transition(AuthState.HIGH_SECURITY);
+
+    const principal = getPrincipal();
+    principal.highSecurityAt = Date.now();
+    principal.keyRecoveryFactors = usedFactors;
+    principal.tier = AuthTier.HIGH_SECURITY;
+    setPrincipal(principal);
+
+    // Clear pending recovery
+    pendingKeyRecovery = null;
+
+    return {
+      state: AuthState.HIGH_SECURITY,
+      tier: getTier(),
+      principal,
+    };
+  }
+
+  /**
+   * Cancel pending key recovery
+   * Returns to ELEVATED state
+   *
+   * @returns {Object} New state info
+   */
+  function cancelKeyRecovery() {
+    const state = getState();
+    if (state.state !== AuthState.KEY_RECOVERY_PENDING) {
+      const err = new Error("No key recovery in progress");
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+
+    transition(AuthState.ELEVATED);
+    pendingKeyRecovery = null;
+
+    return {
+      state: AuthState.ELEVATED,
+      tier: getTier(),
+    };
+  }
+
+  /**
+   * Get pending key recovery status
+   * @returns {Object|null} Pending recovery info or null
+   */
+  function getKeyRecoveryStatus() {
+    if (!pendingKeyRecovery) return null;
+
+    return {
+      challenge: pendingKeyRecovery.challenge,
+      factors: pendingKeyRecovery.factors,
+      startedAt: pendingKeyRecovery.startedAt,
+      verifiedFactors: pendingKeyRecovery.verifiedFactors,
+    };
+  }
+
+  return {
+    startMFA,
+    completeMFA,
+    getStateSnapshot,
+    // Key recovery functions
+    startKeyRecovery,
+    completeKeyRecovery,
+    cancelKeyRecovery,
+    getKeyRecoveryStatus,
+  };
+}
+
+module.exports = {
+  createMFAFunctions,
+};

package/server/security/auth/state-machine.js

@@ -0,0 +1,257 @@
+/**
+ * @fileoverview Authentication State Machine for api-ape Server
+ *
+ * Manages authentication state transitions for WebSocket connections.
+ * Enforces the tiered authentication model with no-downgrade rules.
+ *
+ * @module server/security/auth/state-machine
+ */
+
+/** @enum {string} */
+const AuthState = {
+  GUEST: "GUEST",
+  AUTHENTICATING: "AUTHENTICATING",
+  AUTHENTICATED: "AUTHENTICATED",
+  MFA_PENDING: "MFA_PENDING",
+  ELEVATED: "ELEVATED",
+  KEY_RECOVERY_PENDING: "KEY_RECOVERY_PENDING",
+  HIGH_SECURITY: "HIGH_SECURITY",
+};
+
+/** @enum {number} */
+const AuthTier = { GUEST: 0, BASIC: 1, ELEVATED: 2, HIGH_SECURITY: 3 };
+
+const STATE_TO_TIER = {
+  [AuthState.GUEST]: AuthTier.GUEST,
+  [AuthState.AUTHENTICATING]: AuthTier.GUEST,
+  [AuthState.AUTHENTICATED]: AuthTier.BASIC,
+  [AuthState.MFA_PENDING]: AuthTier.BASIC,
+  [AuthState.ELEVATED]: AuthTier.ELEVATED,
+  [AuthState.KEY_RECOVERY_PENDING]: AuthTier.ELEVATED,
+  [AuthState.HIGH_SECURITY]: AuthTier.HIGH_SECURITY,
+};
+
+const VALID_TRANSITIONS = {
+  [AuthState.GUEST]: [AuthState.AUTHENTICATING],
+  [AuthState.AUTHENTICATING]: [AuthState.GUEST, AuthState.AUTHENTICATED],
+  [AuthState.AUTHENTICATED]: [AuthState.MFA_PENDING, AuthState.KEY_RECOVERY_PENDING],
+  [AuthState.MFA_PENDING]: [AuthState.AUTHENTICATED, AuthState.ELEVATED],
+  [AuthState.ELEVATED]: [AuthState.KEY_RECOVERY_PENDING],
+  [AuthState.KEY_RECOVERY_PENDING]: [AuthState.ELEVATED, AuthState.HIGH_SECURITY],
+  [AuthState.HIGH_SECURITY]: [],
+};
+
+/** @enum {string} */
+const AuthError = {
+  INVALID_TRANSITION: "INVALID_TRANSITION",
+  AUTH_IN_PROGRESS: "AUTH_IN_PROGRESS",
+  ALREADY_AUTHENTICATED: "ALREADY_AUTHENTICATED",
+  AUTH_TIMEOUT: "AUTH_TIMEOUT",
+  INVALID_PROOF: "INVALID_PROOF",
+  NONCE_EXPIRED: "NONCE_EXPIRED",
+  NONCE_REUSED: "NONCE_REUSED",
+  RATE_LIMITED: "RATE_LIMITED",
+  USER_NOT_FOUND: "USER_NOT_FOUND",
+  NO_DOWNGRADE: "NO_DOWNGRADE",
+};
+
+const DEFAULT_CONFIG = {
+  authTimeout: 60000,
+  maxAttempts: 5,
+  lockoutDuration: 300000,
+  nonceExpiry: 30000,
+};
+
+/**
+ * Create an authentication state manager for a socket
+ * @param {Object} [config={}] - Configuration options
+ * @returns {Object} Auth state manager
+ */
+function createAuthStateMachine(config = {}) {
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+  let state = AuthState.GUEST;
+  let principal = null;
+  let attempts = 0;
+  let lockoutUntil = 0;
+  let authTimeoutTimer = null;
+
+  const { createNonceManager } = require("./nonce-manager");
+  const nonceManager = createNonceManager({ nonceExpiry: cfg.nonceExpiry, AuthError });
+
+  /** @returns {number} */
+  function getTier() { return STATE_TO_TIER[state]; }
+
+  /**
+   * @param {string} from
+   * @param {string} to
+   * @returns {boolean}
+   */
+  function isValidTransition(from, to) {
+    return (VALID_TRANSITIONS[from] || []).includes(to);
+  }
+
+  /**
+   * @param {string} newState
+   * @returns {string}
+   */
+  function transition(newState) {
+    if (!isValidTransition(state, newState)) {
+      const err = new Error(`Invalid transition: ${state} -> ${newState}`);
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+    const oldTier = getTier();
+    const newTier = STATE_TO_TIER[newState];
+    if (newTier < oldTier && newState !== AuthState.GUEST) {
+      const err = new Error(`Cannot downgrade from tier ${oldTier} to ${newTier}`);
+      err.code = AuthError.NO_DOWNGRADE;
+      throw err;
+    }
+    const oldState = state;
+    state = newState;
+    return oldState;
+  }
+
+  /** @returns {boolean} */
+  function isLockedOut() {
+    if (lockoutUntil === 0) return false;
+    if (Date.now() >= lockoutUntil) { lockoutUntil = 0; attempts = 0; return false; }
+    return true;
+  }
+
+  /** @returns {Object} */
+  function recordFailedAttempt() {
+    attempts++;
+    if (attempts >= cfg.maxAttempts) lockoutUntil = Date.now() + cfg.lockoutDuration;
+    return {
+      attempts,
+      maxAttempts: cfg.maxAttempts,
+      lockedOut: isLockedOut(),
+      lockoutRemaining: lockoutUntil > 0 ? lockoutUntil - Date.now() : 0,
+    };
+  }
+
+  /** Reset attempt counter (called on successful auth) */
+  function resetAttempts() { attempts = 0; lockoutUntil = 0; }
+
+  /**
+   * @param {string} method
+   * @returns {Object}
+   */
+  function startAuth(method) {
+    if (isLockedOut()) {
+      const err = new Error("Too many authentication attempts");
+      err.code = AuthError.RATE_LIMITED;
+      err.lockoutRemaining = lockoutUntil - Date.now();
+      throw err;
+    }
+    if (state === AuthState.AUTHENTICATING) {
+      const err = new Error("Authentication already in progress");
+      err.code = AuthError.AUTH_IN_PROGRESS;
+      throw err;
+    }
+    if (getTier() >= AuthTier.BASIC) {
+      const err = new Error("Already authenticated");
+      err.code = AuthError.ALREADY_AUTHENTICATED;
+      throw err;
+    }
+    transition(AuthState.AUTHENTICATING);
+    authTimeoutTimer = setTimeout(() => {
+      if (state === AuthState.AUTHENTICATING) transition(AuthState.GUEST);
+    }, cfg.authTimeout);
+    return { state, method };
+  }
+
+  /**
+   * @param {Object} principalData
+   * @returns {Object}
+   */
+  function completeAuth(principalData) {
+    if (state !== AuthState.AUTHENTICATING) {
+      const err = new Error("Not in authenticating state");
+      err.code = AuthError.INVALID_TRANSITION;
+      throw err;
+    }
+    if (authTimeoutTimer) { clearTimeout(authTimeoutTimer); authTimeoutTimer = null; }
+    principal = {
+      userId: principalData.userId,
+      roles: principalData.roles || [],
+      permissions: principalData.permissions || {},
+      authenticatedAt: Date.now(),
+    };
+    transition(AuthState.AUTHENTICATED);
+    resetAttempts();
+    return { state, tier: getTier(), principal };
+  }
+
+  /**
+   * @param {string} reason
+   * @returns {Object}
+   */
+  function failAuth(reason) {
+    if (authTimeoutTimer) { clearTimeout(authTimeoutTimer); authTimeoutTimer = null; }
+    if (state === AuthState.AUTHENTICATING) transition(AuthState.GUEST);
+    return { state, reason, ...recordFailedAttempt() };
+  }
+
+  const { createMFAFunctions } = require("./state-machine-mfa");
+  const mfaFunctions = createMFAFunctions({
+    getState: () => ({ state }),
+    getTier,
+    transition,
+    generateNonce: nonceManager.generateNonce,
+    getPrincipal: () => principal,
+    setPrincipal: (p) => { principal = p; },
+    AuthState,
+    AuthTier,
+    AuthError,
+  });
+
+  /** @returns {Object} */
+  function getState() {
+    return {
+      state,
+      tier: getTier(),
+      principal: principal ? { ...principal } : null,
+      isAuthenticated: getTier() >= AuthTier.BASIC,
+      isElevated: getTier() >= AuthTier.ELEVATED,
+      isHighSecurity: getTier() >= AuthTier.HIGH_SECURITY,
+    };
+  }
+
+  /** Clean up resources (call on socket close) */
+  function cleanup() {
+    if (authTimeoutTimer) { clearTimeout(authTimeoutTimer); authTimeoutTimer = null; }
+    nonceManager.clearPendingNonces();
+  }
+
+  return {
+    getState,
+    getTier,
+    startAuth,
+    completeAuth,
+    failAuth,
+    startMFA: mfaFunctions.startMFA,
+    completeMFA: mfaFunctions.completeMFA,
+    // Key recovery (2-of-3 Tier 3) functions
+    startKeyRecovery: mfaFunctions.startKeyRecovery,
+    completeKeyRecovery: mfaFunctions.completeKeyRecovery,
+    cancelKeyRecovery: mfaFunctions.cancelKeyRecovery,
+    getKeyRecoveryStatus: mfaFunctions.getKeyRecoveryStatus,
+    generateNonce: nonceManager.generateNonce,
+    consumeNonce: nonceManager.consumeNonce,
+    isLockedOut,
+    cleanup,
+    AuthState,
+    AuthTier,
+    AuthError,
+  };
+}
+
+module.exports = {
+  createAuthStateMachine,
+  AuthState,
+  AuthTier,
+  AuthError,
+  DEFAULT_CONFIG,
+};