api-ape 3.0.2 → 4.1.0

package/server/security/auth/adapters/opaque.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview OPAQUE Authentication Adapter for api-ape Server
+ *
+ * Implements OPAQUE (Oblivious Pseudo-Random Function based Asymmetric
+ * Password-Authenticated Key Exchange) for secure authentication where
+ * the server never learns the user's password.
+ *
+ * ## Protocol Flow (Registration)
+ *
+ * ```
+ * Client                           Server
+ *   |-- opaque_reg_start -------->|  (user, clientNonce, regRequest)
+ *   |<- opaque_reg_response ------|  (serverNonce, ts, regResponse)
+ *   |-- opaque_reg_finish ------->|  (regRecord)
+ *   |<- opaque_reg_ok ------------|  (success)
+ * ```
+ *
+ * ## Protocol Flow (Login)
+ *
+ * ```
+ * Client                           Server
+ *   |-- opaque_auth_start ------->|  (user, clientNonce)
+ *   |<- opaque_auth_1 ------------|  (serverNonce, ts, envelope, oprfResponse)
+ *   |-- opaque_auth_2 ----------->|  (clientAuth)
+ *   |<- opaque_auth_ok -----------|  (assignedPrincipal, serverProof, authMeta)
+ * ```
+ *
+ * @module server/security/auth/adapters/opaque
+ * @see {@link module:server/security/auth/state-machine} for auth state management
+ */
+
+const crypto = require("crypto");
+
+/**
+ * OPAQUE adapter configuration
+ * @typedef {Object} OpaqueConfig
+ * @property {Function} [getUser] - Async function to fetch user by username
+ * @property {Function} [saveUser] - Async function to save user registration
+ * @property {Function} [opaqueLib] - OPAQUE library instance (e.g., @cloudflare/opaque)
+ * @property {number} [nonceLength=32] - Server nonce length in bytes
+ * @property {number} [nonceExpiry=30000] - Nonce expiry in ms
+ * @property {string} [serverId] - Server identifier for OPAQUE context
+ */
+
+/**
+ * OPAQUE message types
+ * @enum {string}
+ */
+const OpaqueMessageType = {
+  REG_START: "opaque_reg_start",
+  REG_RESPONSE: "opaque_reg_response",
+  REG_FINISH: "opaque_reg_finish",
+  REG_OK: "opaque_reg_ok",
+  REG_FAIL: "opaque_reg_fail",
+  AUTH_START: "opaque_auth_start",
+  AUTH_1: "opaque_auth_1",
+  AUTH_2: "opaque_auth_2",
+  AUTH_OK: "opaque_auth_ok",
+  AUTH_FAIL: "opaque_auth_fail",
+};
+
+/**
+ * OPAQUE error codes
+ * @enum {string}
+ */
+const OpaqueError = {
+  USER_NOT_FOUND: "USER_NOT_FOUND",
+  USER_EXISTS: "USER_EXISTS",
+  INVALID_PROOF: "INVALID_PROOF",
+  INVALID_STATE: "INVALID_STATE",
+  NONCE_EXPIRED: "NONCE_EXPIRED",
+  NONCE_MISMATCH: "NONCE_MISMATCH",
+  MISSING_LIB: "MISSING_LIB",
+  INVALID_MESSAGE: "INVALID_MESSAGE",
+};
+
+/** @private */
+const _defaultUserStore = new Map();
+
+/** @private */
+const defaultStorage = {
+  /**
+   * @param {string} username
+   * @returns {Promise<Object|null>}
+   */
+  async getUser(username) {
+    return _defaultUserStore.get(username) || null;
+  },
+  /**
+   * @param {string} username
+   * @param {Object} userData
+   * @returns {Promise<boolean>}
+   */
+  async saveUser(username, userData) {
+    _defaultUserStore.set(username, userData);
+    return true;
+  },
+};
+
+/**
+ * Create an OPAQUE adapter instance
+ *
+ * @param {OpaqueConfig} [config={}] - Configuration options
+ * @returns {Object} OPAQUE adapter with registration and authentication methods
+ */
+function createOpaqueAdapter(config = {}) {
+  const {
+    getUser = defaultStorage.getUser,
+    saveUser = defaultStorage.saveUser,
+    opaqueLib = null,
+    nonceLength = 32,
+    nonceExpiry = 30000,
+    serverId = "api-ape-opaque-server",
+  } = config;
+
+  const pendingSessions = new Map();
+
+  /**
+   * Generate a session key for tracking pending auth
+   * @param {string} clientId - Client identifier
+   * @param {string} user - Username
+   * @returns {string} Session key
+   * @private
+   */
+  function sessionKey(clientId, user) {
+    return `${clientId}:${user}`;
+  }
+
+  /**
+   * Generate a server nonce
+   * @returns {Object} Nonce info { nonce, expiresAt }
+   * @private
+   */
+  function generateNonce() {
+    const nonce = crypto.randomBytes(nonceLength).toString("base64url");
+    const expiresAt = Date.now() + nonceExpiry;
+    return { nonce, expiresAt };
+  }
+
+  /**
+   * Create canonical binding string for OPAQUE context
+   * @param {Object} params - Binding parameters
+   * @returns {string} Canonical binding string
+   */
+  function createCanonicalBinding({ clientId, clientNonce, serverNonce, user, ts }) {
+    return `${clientId}|${clientNonce}|${serverNonce}|${user}|${ts}`;
+  }
+
+  const { createOpaqueHandlers } = require("./opaque-handlers");
+  const handlers = createOpaqueHandlers({
+    getUser,
+    saveUser,
+    opaqueLib,
+    serverId,
+    pendingSessions,
+    sessionKey,
+    generateNonce,
+    createCanonicalBinding,
+    nonceExpiry,
+    OpaqueMessageType,
+    OpaqueError,
+  });
+
+  /**
+   * Clean up pending sessions for a client
+   * @param {string} clientId - Client identifier
+   */
+  function cleanupClient(clientId) {
+    for (const [key] of pendingSessions) {
+      if (key.startsWith(clientId + ":")) {
+        pendingSessions.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Check if the adapter has an OPAQUE library configured
+   * @returns {boolean} Whether OPAQUE library is available
+   */
+  function hasOpaqueLib() {
+    return opaqueLib !== null;
+  }
+
+  return {
+    type: "opaque",
+    tier: 1,
+    MessageType: OpaqueMessageType,
+    Error: OpaqueError,
+    handleRegStart: handlers.handleRegStart,
+    handleRegFinish: handlers.handleRegFinish,
+    handleAuthStart: handlers.handleAuthStart,
+    handleAuthFinish: handlers.handleAuthFinish,
+    cleanupClient,
+    hasOpaqueLib,
+    createCanonicalBinding,
+    _pendingSessions: pendingSessions,
+    _defaultUserStore,
+  };
+}
+
+module.exports = {
+  createOpaqueAdapter,
+  OpaqueMessageType,
+  OpaqueError,
+};

package/server/security/auth/adapters/saml/constants.js

@@ -0,0 +1,52 @@
+/**
+ * @file SAML constants and error codes
+ */
+"use strict";
+
+/**
+ * SAML message types
+ * @enum {string}
+ */
+const SAMLMessageType = {
+  AUTH_START: "saml_auth_start",
+  AUTH_REDIRECT: "saml_auth_redirect",
+  AUTH_CALLBACK: "saml_auth_callback",
+  AUTH_OK: "saml_auth_ok",
+  AUTH_FAIL: "saml_auth_fail",
+  LOGOUT_START: "saml_logout_start",
+  LOGOUT_REDIRECT: "saml_logout_redirect",
+  LOGOUT_OK: "saml_logout_ok",
+};
+
+/**
+ * SAML error codes
+ * @enum {string}
+ */
+const SAMLError = {
+  INVALID_RESPONSE: "INVALID_RESPONSE",
+  SIGNATURE_INVALID: "SIGNATURE_INVALID",
+  ASSERTION_EXPIRED: "ASSERTION_EXPIRED",
+  MISSING_ASSERTION: "MISSING_ASSERTION",
+  INVALID_AUDIENCE: "INVALID_AUDIENCE",
+  MISSING_NAMEID: "MISSING_NAMEID",
+  IDP_ERROR: "IDP_ERROR",
+  CONFIG_ERROR: "CONFIG_ERROR",
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+};
+
+/**
+ * Default attribute mapping
+ */
+const DEFAULT_ATTRIBUTE_MAPPING = {
+  email: ["email", "urn:oid:0.9.2342.19200300.100.1.3", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"],
+  displayName: ["displayName", "cn", "urn:oid:2.16.840.1.113730.3.1.241", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"],
+  firstName: ["firstName", "givenName", "urn:oid:2.5.4.42", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"],
+  lastName: ["lastName", "sn", "surname", "urn:oid:2.5.4.4", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"],
+  groups: ["memberOf", "groups", "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"],
+};
+
+module.exports = {
+  SAMLMessageType,
+  SAMLError,
+  DEFAULT_ATTRIBUTE_MAPPING,
+};

package/server/security/auth/adapters/saml/files.md

@@ -0,0 +1,19 @@
+# SAML Adapter Module
+
+SAML 2.0 SSO authentication helpers.
+
+## Directory Structure
+
+```
+saml/
+├── constants.js - SAML message types and error codes
+└── helpers.js   - Request storage and ID generation
+```
+
+## Files
+
+### `constants.js`
+Defines SAMLMessageType (AUTH_REDIRECT, AUTH_OK, AUTH_FAIL, LOGOUT_*) and SAMLError codes.
+
+### `helpers.js`
+Pending request storage and request ID generation for SAML flows.

package/server/security/auth/adapters/saml/helpers.js

@@ -0,0 +1,74 @@
+/**
+ * @file SAML helper functions
+ */
+"use strict";
+
+const crypto = require("crypto");
+
+/**
+ * Create per-instance storage for mock mode
+ * @returns {Object} Storage adapter with isolated maps
+ */
+function createDefaultStorage() {
+  const pendingRequests = new Map();
+  const mockUsers = new Map();
+  return {
+    /**
+     * Save a pending SAML request
+     * @param {string} requestId - Request ID
+     * @param {Object} data - Request data
+     * @returns {Promise<boolean>} Success
+     */
+    async savePendingRequest(requestId, data) {
+      pendingRequests.set(requestId, { ...data, createdAt: Date.now() });
+      return true;
+    },
+    /**
+     * Get a pending SAML request
+     * @param {string} requestId - Request ID
+     * @returns {Promise<Object|null>} Request data or null
+     */
+    async getPendingRequest(requestId) {
+      return pendingRequests.get(requestId) || null;
+    },
+    /**
+     * Delete a pending SAML request
+     * @param {string} requestId - Request ID
+     * @returns {Promise<boolean>} Success
+     */
+    async deletePendingRequest(requestId) {
+      return pendingRequests.delete(requestId);
+    },
+    /**
+     * Register a mock user for testing
+     * @param {string} nameId - User name ID
+     * @param {Object} attributes - User attributes
+     * @returns {Promise<boolean>} Success
+     */
+    async registerMockUser(nameId, attributes) {
+      mockUsers.set(nameId, attributes);
+      return true;
+    },
+    /**
+     * Get a mock user by name ID
+     * @param {string} nameId - User name ID
+     * @returns {Promise<Object|null>} User attributes or null
+     */
+    async getMockUser(nameId) {
+      return mockUsers.get(nameId) || null;
+    },
+  };
+}
+
+/**
+ * Generate a SAML AuthnRequest ID
+ * @returns {string} Request ID
+ */
+function generateRequestId() {
+  return "_" + crypto.randomBytes(16).toString("hex");
+}
+
+module.exports = {
+  createDefaultStorage,
+  generateRequestId,
+};

package/server/security/auth/adapters/saml.js

@@ -0,0 +1,173 @@
+/**
+ * @fileoverview SAML Authentication Adapter for api-ape Server
+ *
+ * Implements SAML 2.0 Single Sign-On (SSO) for enterprise identity providers.
+ *
+ * @module server/security/auth/adapters/saml
+ */
+
+"use strict";
+
+const { SAMLMessageType, SAMLError } = require("./saml/constants");
+const { createDefaultStorage, generateRequestId } = require("./saml/helpers");
+
+/**
+ * Create a SAML authentication adapter
+ *
+ * @param {Object} config - Configuration options
+ * @param {Function} verify - Passport.js verify callback
+ * @returns {Object} SAML adapter with Passport.js Strategy interface
+ */
+function createSAMLStrategy(config = {}, verify = null) {
+  if (typeof config === "function") {
+    verify = config;
+    config = {};
+  }
+
+  const storage = createDefaultStorage();
+
+  const {
+    entryPoint = "https://idp.example.com/sso",
+    issuer = "api-ape",
+    callbackUrl = "http://localhost:3000/auth/saml/callback",
+    logoutUrl = null,
+    identifierFormat = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+    passReqToCallback = false,
+  } = config;
+
+  const strategy = { name: "saml" };
+
+  /**
+   * Handle SAML auth start - generates redirect URL
+   * @param {Object} [data={}] - Request data
+   * @param {string} [data.relayState=''] - State to preserve across redirect
+   * @returns {Promise<Object>} Response with redirect URL
+   */
+  async function handleAuthStart(data = {}) {
+    const requestId = generateRequestId();
+    const { relayState = "" } = data;
+    await storage.savePendingRequest(requestId, { relayState, issuer });
+    const redirectUrl = `${entryPoint}?SAMLRequest=${encodeURIComponent(requestId)}&RelayState=${encodeURIComponent(relayState)}`;
+    return { type: SAMLMessageType.AUTH_REDIRECT, url: redirectUrl, requestId };
+  }
+
+  /**
+   * Handle SAML callback - processes SAML response
+   * @param {Object} data - Callback data
+   * @param {string} data.SAMLResponse - SAML response
+   * @param {string} [data.RelayState] - Relay state
+   * @returns {Promise<Object>} Response with user profile or error
+   */
+  async function handleAuthCallback(data) {
+    const { SAMLResponse, RelayState } = data;
+    if (!SAMLResponse) {
+      return { type: SAMLMessageType.AUTH_FAIL, error: SAMLError.MISSING_ASSERTION, message: "No SAML response provided" };
+    }
+
+    try {
+      const nameId = SAMLResponse;
+      const mockUser = await storage.getMockUser(nameId);
+      if (!mockUser) {
+        return { type: SAMLMessageType.AUTH_FAIL, error: SAMLError.MISSING_NAMEID, message: "User not found in identity provider" };
+      }
+
+      const profile = {
+        nameID: nameId,
+        nameIDFormat: identifierFormat,
+        issuer: mockUser.issuer || entryPoint,
+        email: mockUser.email || nameId,
+        firstName: mockUser.firstName,
+        lastName: mockUser.lastName,
+        displayName: mockUser.displayName || mockUser.firstName + " " + mockUser.lastName,
+        groups: mockUser.groups || [],
+        raw: mockUser,
+      };
+
+      return { type: SAMLMessageType.AUTH_OK, userId: nameId, profile, relayState: RelayState };
+    } catch (err) {
+      return { type: SAMLMessageType.AUTH_FAIL, error: SAMLError.INVALID_RESPONSE, message: err.message || "Failed to process SAML response" };
+    }
+  }
+
+  /**
+   * Handle SAML logout start
+   * @param {Object} data - Logout data
+   * @param {string} data.nameId - User name ID
+   * @param {string} [data.sessionIndex] - Session index
+   * @returns {Promise<Object>} Response with logout redirect URL
+   */
+  async function handleLogoutStart(data) {
+    const { nameId, sessionIndex } = data;
+    if (!logoutUrl) {
+      return { type: SAMLMessageType.LOGOUT_OK, message: "Single logout not configured" };
+    }
+    const redirectUrl = `${logoutUrl}?NameID=${encodeURIComponent(nameId)}&` + (sessionIndex ? `SessionIndex=${encodeURIComponent(sessionIndex)}` : "");
+    return { type: SAMLMessageType.LOGOUT_REDIRECT, url: redirectUrl };
+  }
+
+  strategy.authenticate = function (req, options = {}) {
+    const self = this;
+    const samlResponse = req.body?.SAMLResponse || req.SAMLResponse;
+
+    if (samlResponse) {
+      handleAuthCallback({ SAMLResponse: samlResponse, RelayState: req.body?.RelayState || req.RelayState })
+        .then((result) => {
+          if (result.type === SAMLMessageType.AUTH_FAIL) {
+            return self.fail({ message: result.message, code: result.error });
+          }
+          if (verify) {
+            /** @param {Error|null} err - Error @param {Object|false} user - User @param {Object} info - Info @returns {void} */
+            const verified = (err, user, info) => {
+              if (err) return self.error(err);
+              if (!user) return self.fail(info || { message: "Verification failed" });
+              return self.success(user, info);
+            };
+            try {
+              if (passReqToCallback) verify(req, result.profile, verified);
+              else verify(result.profile, verified);
+            } catch (err) {
+              return self.error(err);
+            }
+          } else {
+            return self.success(result.profile, { userId: result.userId });
+          }
+        })
+        .catch((err) => { if (typeof self.error === "function") self.error(err); });
+    } else {
+      handleAuthStart({ relayState: options.relayState || req.relayState || "" })
+        .then((result) => { self.redirect(result.url); })
+        .catch((err) => { if (typeof self.error === "function") self.error(err); });
+    }
+  };
+
+  /**
+   * Register a test user for mock mode
+   * @param {string} nameId - User name ID
+   * @param {Object} [attributes={}] - User attributes
+   * @returns {Promise<boolean>} Success
+   */
+  async function registerTestUser(nameId, attributes = {}) {
+    return storage.registerMockUser(nameId, attributes);
+  }
+
+  /**
+   * Cleanup resources
+   * @returns {void}
+   */
+  function cleanup() {}
+
+  return {
+    name: strategy.name,
+    authenticate: strategy.authenticate,
+    handleAuthStart,
+    handleAuthCallback,
+    handleLogoutStart,
+    registerTestUser,
+    cleanup,
+    _config: { entryPoint, issuer, callbackUrl },
+  };
+}
+
+const SAMLStrategy = createSAMLStrategy;
+
+module.exports = { createSAMLStrategy, SAMLStrategy, SAMLMessageType, SAMLError };