api-ape 3.0.1 → 4.1.0

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

@@ -0,0 +1,95 @@
+# Authentication Adapters Files
+
+This directory contains protocol-specific authentication adapters. Each adapter implements a specific authentication protocol and is registered with the auth framework.
+
+## Guidelines
+
+- **Session isolation** — Pending sessions are keyed by `clientId:username` for concurrent auth support
+- **Nonce binding** — Server nonces bind auth transcript to specific connection parameters
+- **Cleanup on disconnect** — Call `cleanupClient()` when socket disconnects
+
+## Directory Structure
+
+```
+adapters/
+├── opaque.js          # OPAQUE adapter factory and enums
+├── opaque-handlers.js # OPAQUE message handlers
+├── ldap.js            # LDAP/AD adapter (Passport.js compatible)
+├── saml.js            # SAML 2.0 SSO adapter (Passport.js compatible)
+├── oauth2.js          # OAuth2 adapter (Passport.js compatible)
+├── webauthn.js        # WebAuthn/FIDO2 adapter (Passport.js compatible)
+└── totp.js            # TOTP RFC 6238 adapter (Passport.js compatible)
+```
+
+## Files
+
+### `opaque.js`
+
+OPAQUE protocol adapter for zero-knowledge password authentication:
+
+- Server never learns the user's raw password
+- `createOpaqueAdapter(config)` — Creates adapter with user storage functions
+- Exports `OpaqueMessageType` and `OpaqueError` enums
+- Supports optional `@cloudflare/opaque` library for cryptographic operations
+
+### `opaque-handlers.js`
+
+OPAQUE message handler implementations:
+
+- Registration flow: `handleRegStart`, `handleRegFinish`
+- Auth flow: `handleAuthStart`, `handleAuthFinish`
+- Manages pending sessions with automatic expiry cleanup
+- Creates user principal on successful authentication
+
+### `webauthn.js`
+
+WebAuthn/FIDO2 adapter for hardware security key MFA (Tier 2):
+
+- `createWebAuthnStrategy(config, verify)` — Passport.js-compatible factory
+- Registration flow: `handleRegStart`, `handleRegFinish`
+- Auth flow: `handleAuthStart`, `handleAuthFinish`
+- Exports `WebAuthnMessageType` and `WebAuthnError` enums
+- Counter validation prevents authenticator cloning
+- Mock mode for testing (real verification requires `@simplewebauthn/server`)
+
+### `ldap.js`
+
+LDAP/Active Directory adapter for enterprise authentication (Tier 1):
+
+- `createLDAPStrategy(config, verify)` — Passport.js-compatible factory
+- Simple bind and search-then-bind modes
+- Group membership extraction for role mapping
+- Exports `LDAPMessageType` and `LDAPError` enums
+- Mock mode for testing (real bind requires `ldapjs`)
+
+### `saml.js`
+
+SAML 2.0 SSO adapter for enterprise identity providers (Tier 1):
+
+- `createSAMLStrategy(config, verify)` — Passport.js-compatible factory
+- SP-initiated and IdP-initiated SSO support
+- Handles `handleAuthStart`, `handleAuthCallback`, `handleLogoutStart`
+- Exports `SAMLMessageType` and `SAMLError` enums
+- Mock mode for testing (real validation requires `passport-saml`)
+
+### `oauth2.js`
+
+OAuth2 Authorization Code adapter for identity providers (Tier 1):
+
+- `createOAuth2Strategy(config, verify)` — Passport.js-compatible factory
+- PKCE support for enhanced security
+- Handles `handleAuthStart`, `handleAuthCallback`, `handleTokenRefresh`
+- Exports `OAuth2MessageType` and `OAuth2Error` enums
+- State parameter for CSRF protection
+- Mock mode for testing (real token exchange requires HTTP client)
+
+### `totp.js`
+
+TOTP RFC 6238 adapter for authenticator app MFA (Tier 2):
+
+- `createTOTPStrategy(config, verify)` — Passport.js-compatible factory
+- Setup flow: `handleSetupStart`, `handleSetupVerify`
+- Verify flow: `handleVerify`, `handleDisable`
+- Exports `TOTPMessageType` and `TOTPError` enums
+- Built-in base32 encoding, HMAC-SHA1 code generation
+- Counter tracking prevents code replay within window

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

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview LDAP Constants
+ * @module server/security/auth/adapters/ldap/constants
+ */
+
+"use strict";
+
+/**
+ * LDAP message types
+ * @enum {string}
+ */
+const LDAPMessageType = {
+  AUTH: "ldap_auth",
+  AUTH_OK: "ldap_auth_ok",
+  AUTH_FAIL: "ldap_auth_fail",
+};
+
+/**
+ * LDAP error codes
+ * @enum {string}
+ */
+const LDAPError = {
+  INVALID_CREDENTIALS: "INVALID_CREDENTIALS",
+  USER_NOT_FOUND: "USER_NOT_FOUND",
+  CONNECTION_ERROR: "CONNECTION_ERROR",
+  BIND_ERROR: "BIND_ERROR",
+  SEARCH_ERROR: "SEARCH_ERROR",
+  TIMEOUT: "TIMEOUT",
+  TLS_ERROR: "TLS_ERROR",
+  MISSING_CREDENTIALS: "MISSING_CREDENTIALS",
+  SERVER_UNAVAILABLE: "SERVER_UNAVAILABLE",
+};
+
+module.exports = {
+  LDAPMessageType,
+  LDAPError,
+};

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

@@ -0,0 +1,19 @@
+# LDAP Adapter Module
+
+LDAP/Active Directory authentication helpers.
+
+## Directory Structure
+
+```
+ldap/
+├── constants.js - LDAP message types and error codes
+└── helpers.js   - Storage and mock LDAP client
+```
+
+## Files
+
+### `constants.js`
+Defines LDAPMessageType (AUTH, AUTH_OK, AUTH_FAIL) and LDAPError codes.
+
+### `helpers.js`
+Creates mock LDAP client for testing with bind, search, and unbind operations.

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

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview LDAP Helpers
+ * @module server/security/auth/adapters/ldap/helpers
+ */
+
+"use strict";
+
+/**
+ * Create per-instance storage for mock mode
+ * @returns {Object} Storage adapter with isolated user map
+ */
+function createDefaultStorage() {
+  const userStore = new Map();
+  return {
+    /**
+     * Get user by username
+     * @param {string} username - Username to look up
+     * @returns {Promise<Object|null>} User object or null
+     */
+    async getUser(username) {
+      return userStore.get(username) || null;
+    },
+    /**
+     * Save user (for mock registration)
+     * @param {string} username - Username
+     * @param {Object} userData - User data including password hash
+     * @returns {Promise<boolean>} Success
+     */
+    async saveUser(username, userData) {
+      userStore.set(username, userData);
+      return true;
+    },
+  };
+}
+
+/**
+ * Create mock LDAP client for testing
+ * @param {Object} storage - Storage adapter
+ * @returns {Object} Mock LDAP client
+ */
+function createMockLDAPClient(storage) {
+  return {
+    /**
+     * Mock bind operation
+     * @param {string} dn - Distinguished name
+     * @param {string} password - Password
+     * @returns {Promise<void>}
+     */
+    async bind(dn, password) {
+      const match = dn.match(/uid=([^,]+)/i) || dn.match(/cn=([^,]+)/i);
+      const username = match ? match[1] : dn;
+
+      const user = await storage.getUser(username);
+      if (!user) {
+        const err = new Error("User not found");
+        err.code = "LDAP_NO_SUCH_OBJECT";
+        throw err;
+      }
+      if (user.password !== password) {
+        const err = new Error("Invalid credentials");
+        err.code = "LDAP_INVALID_CREDENTIALS";
+        throw err;
+      }
+    },
+
+    /**
+     * Mock search operation
+     * @param {string} base - Search base DN
+     * @param {Object} options - Search options
+     * @returns {Promise<Object[]>} Search results
+     */
+    async search(base, options) {
+      const results = [];
+      const filter = options.filter || "";
+
+      const match = filter.match(/\(uid=([^)]+)\)/i) || filter.match(/\(cn=([^)]+)\)/i);
+      if (match) {
+        const username = match[1];
+        const user = await storage.getUser(username);
+        if (user) {
+          results.push({
+            dn: `uid=${username},${base}`,
+            uid: username,
+            cn: user.cn || username,
+            mail: user.mail || `${username}@example.com`,
+            memberOf: user.memberOf || [],
+            ...user.attributes,
+          });
+        }
+      }
+      return results;
+    },
+
+    /**
+     * Mock unbind operation
+     * @returns {Promise<void>}
+     */
+    async unbind() {},
+
+    /**
+     * Mock destroy operation
+     * @returns {void}
+     */
+    destroy() {},
+  };
+}
+
+module.exports = {
+  createDefaultStorage,
+  createMockLDAPClient,
+};

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

@@ -0,0 +1,353 @@
+/**
+ * @fileoverview LDAP Authentication Adapter for api-ape Server
+ *
+ * Implements LDAP/Active Directory authentication for enterprise integration.
+ * This is a Tier 1 adapter providing primary identity verification.
+ *
+ * ## Protocol Flow
+ *
+ * ```
+ * Client                           Server
+ *   |-- ldap_auth ---------------->|  (username, password)
+ *   |<- ldap_auth_ok / _fail ------|  (principal / error)
+ * ```
+ *
+ * ## Features
+ *
+ * - Simple bind authentication
+ * - Search-then-bind for flexible user lookup
+ * - Group membership extraction for role mapping
+ * - Connection pooling support
+ * - TLS/STARTTLS support
+ * - Passport.js Strategy interface compatibility
+ *
+ * @module server/security/auth/adapters/ldap
+ * @see {@link module:server/security/auth} for the auth framework
+ */
+
+"use strict";
+
+const { LDAPMessageType, LDAPError } = require("./ldap/constants");
+const { createDefaultStorage, createMockLDAPClient } = require("./ldap/helpers");
+
+/**
+ * Create an LDAP authentication adapter
+ *
+ * @param {LDAPConfig} [config={}] - Configuration options
+ * @param {Function} [verify] - Passport.js verify callback
+ * @returns {Object} LDAP adapter with Passport.js Strategy interface
+ *
+ * @example
+ * // Basic usage
+ * const ldap = createLDAPStrategy({
+ *   url: 'ldap://ldap.example.com',
+ *   baseDN: 'ou=users,dc=example,dc=com'
+ * });
+ *
+ * // With verify callback (Passport.js style)
+ * const ldap = createLDAPStrategy({
+ *   url: 'ldaps://ldap.example.com',
+ *   baseDN: 'ou=users,dc=example,dc=com',
+ *   bindDN: 'cn=admin,dc=example,dc=com',
+ *   bindPassword: 'secret'
+ * }, (profile, done) => {
+ *   User.findOrCreate({ ldapId: profile.dn }, done);
+ * });
+ */
+function createLDAPStrategy(config = {}, verify = null) {
+  // Handle Passport.js style: (verify) or (config, verify)
+  if (typeof config === "function") {
+    verify = config;
+    config = {};
+  }
+
+  // Create per-instance storage for isolation
+  const instanceStorage = createDefaultStorage();
+
+  const {
+    url = "ldap://localhost:389",
+    baseDN = "dc=example,dc=com",
+    bindDN = null,
+    bindPassword = null,
+    searchFilter = "(uid={{username}})",
+    usernameField = "uid",
+    groupSearchBase = null,
+    groupSearchFilter = "(member={{dn}})",
+    groupAttribute = "cn",
+    tlsOptions = null,
+    timeout = 5000,
+    connectTimeout = 10000,
+    passReqToCallback = false,
+    ldapClient = null,
+    getUser = instanceStorage.getUser,
+    saveUser = instanceStorage.saveUser,
+  } = config;
+
+  const storage = { getUser, saveUser };
+
+  // Create or use provided LDAP client
+  const client = ldapClient || createMockLDAPClient(storage);
+
+  // Passport.js Strategy interface
+  const strategy = {
+    name: "ldap",
+  };
+
+  /**
+   * Perform user search
+   * @private
+   * @param {string} username - Username to search for
+   * @returns {Promise<Object|null>} User entry or null
+   */
+  async function searchUser(username) {
+    const filter = searchFilter.replace(/\{\{username\}\}/g, username);
+    const results = await client.search(baseDN, {
+      filter,
+      scope: "sub",
+      attributes: ["dn", usernameField, "cn", "mail", "memberOf"],
+    });
+    return results.length > 0 ? results[0] : null;
+  }
+
+  /**
+   * Get group memberships for a user
+   * @private
+   * @param {string} userDN - User's distinguished name
+   * @returns {Promise<string[]>} Array of group names
+   */
+  async function getGroups(userDN) {
+    if (!groupSearchBase) return [];
+
+    const bases = Array.isArray(groupSearchBase) ? groupSearchBase : [groupSearchBase];
+    const groups = [];
+
+    for (const base of bases) {
+      const filter = groupSearchFilter.replace(/\{\{dn\}\}/g, userDN);
+      const results = await client.search(base, {
+        filter,
+        scope: "sub",
+        attributes: [groupAttribute],
+      });
+      for (const entry of results) {
+        if (entry[groupAttribute]) {
+          groups.push(entry[groupAttribute]);
+        }
+      }
+    }
+
+    return groups;
+  }
+
+  /**
+   * Handle LDAP authentication message
+   *
+   * @param {Object} data - Message data
+   * @param {string} data.username - Username
+   * @param {string} data.password - Password
+   * @returns {Promise<Object>} Response message
+   */
+  async function handleAuth(data) {
+    const { username, password } = data;
+
+    if (!username || !password) {
+      return {
+        type: LDAPMessageType.AUTH_FAIL,
+        error: LDAPError.MISSING_CREDENTIALS,
+        message: "Username and password are required",
+      };
+    }
+
+    try {
+      let userEntry;
+      let userDN;
+
+      // Search-then-bind mode (more flexible)
+      if (bindDN) {
+        // First bind as service account
+        await client.bind(bindDN, bindPassword);
+
+        // Search for user
+        userEntry = await searchUser(username);
+        if (!userEntry) {
+          return {
+            type: LDAPMessageType.AUTH_FAIL,
+            error: LDAPError.USER_NOT_FOUND,
+            message: "User not found",
+          };
+        }
+        userDN = userEntry.dn;
+
+        // Rebind as user to verify password
+        await client.bind(userDN, password);
+      } else {
+        // Simple bind mode - construct DN from username
+        userDN = `${usernameField}=${username},${baseDN}`;
+        await client.bind(userDN, password);
+
+        // Optionally search for additional user info
+        userEntry = await searchUser(username);
+      }
+
+      // Get group memberships
+      const groups = userEntry ? await getGroups(userEntry.dn || userDN) : [];
+
+      // Build profile
+      const profile = {
+        dn: userDN,
+        username: userEntry?.[usernameField] || username,
+        displayName: userEntry?.cn || username,
+        email: userEntry?.mail,
+        groups,
+        memberOf: userEntry?.memberOf || [],
+        raw: userEntry,
+      };
+
+      return {
+        type: LDAPMessageType.AUTH_OK,
+        userId: username,
+        profile,
+        groups,
+      };
+    } catch (err) {
+      // Map LDAP errors to our error codes
+      let errorCode = LDAPError.BIND_ERROR;
+      let message = err.message || "Authentication failed";
+
+      if (err.code === "LDAP_INVALID_CREDENTIALS" || err.message?.includes("Invalid credentials")) {
+        errorCode = LDAPError.INVALID_CREDENTIALS;
+        message = "Invalid username or password";
+      } else if (err.code === "LDAP_NO_SUCH_OBJECT" || err.message?.includes("not found")) {
+        errorCode = LDAPError.USER_NOT_FOUND;
+        message = "User not found";
+      } else if (err.code === "ETIMEDOUT" || err.code === "ECONNREFUSED") {
+        errorCode = LDAPError.CONNECTION_ERROR;
+        message = "Could not connect to LDAP server";
+      } else if (err.code === "ENOTFOUND") {
+        errorCode = LDAPError.SERVER_UNAVAILABLE;
+        message = "LDAP server unavailable";
+      }
+
+      return {
+        type: LDAPMessageType.AUTH_FAIL,
+        error: errorCode,
+        message,
+      };
+    }
+  }
+
+  /**
+   * Passport.js authenticate method
+   *
+   * @param {Object} req - Request object with username/password
+   * @param {Object} [options] - Authentication options
+   */
+  strategy.authenticate = function (req, options = {}) {
+    const self = this;
+    const username = req.username || req.body?.username;
+    const password = req.password || req.body?.password;
+
+    if (!username || !password) {
+      return self.fail({ message: "Missing credentials" }, 400);
+    }
+
+    handleAuth({ username, password })
+      .then((result) => {
+        if (result.type === LDAPMessageType.AUTH_FAIL) {
+          return self.fail({ message: result.message, code: result.error });
+        }
+
+        // Call verify callback if provided (Passport.js pattern)
+        if (verify) {
+          /**
+           * Passport.js verified callback
+           * @param {Error|null} err - Error if verification failed
+           * @param {Object|false} user - User object or false
+           * @param {Object} [info] - Additional 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 {
+          // No verify callback, return profile directly
+          return self.success(result.profile, { userId: result.userId });
+        }
+      })
+      .catch((err) => {
+        if (typeof self.error === "function") {
+          self.error(err);
+        }
+      });
+  };
+
+  /**
+   * Register a test user (for mock mode)
+   *
+   * @param {string} username - Username
+   * @param {string} password - Password
+   * @param {Object} [attributes={}] - Additional attributes
+   * @returns {Promise<boolean>} Success
+   */
+  async function registerTestUser(username, password, attributes = {}) {
+    return storage.saveUser(username, {
+      password,
+      cn: attributes.cn || username,
+      mail: attributes.mail || `${username}@example.com`,
+      memberOf: attributes.memberOf || [],
+      attributes,
+    });
+  }
+
+  /**
+   * Cleanup resources
+   */
+  function cleanup() {
+    if (client.destroy) {
+      client.destroy();
+    }
+  }
+
+  return {
+    // Passport.js Strategy interface
+    name: strategy.name,
+    authenticate: strategy.authenticate,
+
+    // Direct message handlers
+    handleAuth,
+
+    // Test utilities
+    registerTestUser,
+
+    // Lifecycle
+    cleanup,
+
+    // Config access (for framework integration)
+    _config: {
+      url,
+      baseDN,
+      usernameField,
+    },
+  };
+}
+
+// Passport.js style alias
+const LDAPStrategy = createLDAPStrategy;
+
+module.exports = {
+  createLDAPStrategy,
+  LDAPStrategy,
+  LDAPMessageType,
+  LDAPError,
+};

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

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview OAuth2 Constants
+ * @module server/security/auth/adapters/oauth2/constants
+ */
+
+"use strict";
+
+/**
+ * OAuth2 message types
+ * @enum {string}
+ */
+const OAuth2MessageType = {
+  AUTH_START: "oauth2_auth_start",
+  AUTH_REDIRECT: "oauth2_auth_redirect",
+  AUTH_CALLBACK: "oauth2_callback",
+  AUTH_OK: "oauth2_auth_ok",
+  AUTH_FAIL: "oauth2_auth_fail",
+  TOKEN_REFRESH: "oauth2_token_refresh",
+  TOKEN_REFRESHED: "oauth2_token_refreshed",
+};
+
+/**
+ * OAuth2 error codes
+ * @enum {string}
+ */
+const OAuth2Error = {
+  INVALID_CODE: "INVALID_CODE",
+  INVALID_STATE: "INVALID_STATE",
+  INVALID_TOKEN: "INVALID_TOKEN",
+  TOKEN_EXPIRED: "TOKEN_EXPIRED",
+  SCOPE_ERROR: "SCOPE_ERROR",
+  PROVIDER_ERROR: "PROVIDER_ERROR",
+  CONFIG_ERROR: "CONFIG_ERROR",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  MISSING_CODE: "MISSING_CODE",
+};
+
+module.exports = {
+  OAuth2MessageType,
+  OAuth2Error,
+};

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

@@ -0,0 +1,19 @@
+# OAuth2 Adapter Module
+
+OAuth2 Authorization Code flow helpers.
+
+## Directory Structure
+
+```
+oauth2/
+├── constants.js - OAuth2 message types and error codes
+└── helpers.js   - State management and PKCE utilities
+```
+
+## Files
+
+### `constants.js`
+Defines OAuth2MessageType (AUTH_START, AUTH_REDIRECT, AUTH_CALLBACK, etc.) and OAuth2Error codes.
+
+### `helpers.js`
+State storage, PKCE code verifier/challenge generation, and mock token management.