api-ape 3.0.2 → 4.1.0

package/server/socket/authMiddleware.js

@@ -0,0 +1,299 @@
+/**
+ * @fileoverview Authorization Middleware for api-ape Server
+ *
+ * Provides authorization checks for incoming messages based on
+ * authentication tier and permissions.
+ *
+ * ## Usage
+ *
+ * The middleware can be configured with endpoint-specific requirements:
+ *
+ * ```javascript
+ * const authz = createAuthMiddleware({
+ *   requirements: {
+ *     'admin/users': { tier: 2, permissions: ['admin:users'] },
+ *     'chat/send': { tier: 1, permissions: ['chat:send'] },
+ *     'public/status': { tier: 0 } // guest allowed
+ *   },
+ *   defaultTier: 0 // default for unlisted endpoints
+ * });
+ * ```
+ *
+ * @module server/socket/authMiddleware
+ * @see {@link module:server/security/auth} for authentication framework
+ */
+
+const { AuthTier } = require("../security/auth");
+
+/**
+ * Authorization error response
+ * @typedef {Object} AuthzError
+ * @property {string} type - Always "authz_fail"
+ * @property {string} reason - Error reason code
+ * @property {string} [required] - What was required
+ * @property {number} [requiredTier] - Required tier
+ * @property {number} [currentTier] - Current tier
+ */
+
+/**
+ * Endpoint authorization requirement
+ * @typedef {Object} EndpointRequirement
+ * @property {number} [tier=0] - Minimum required tier
+ * @property {string[]} [permissions=[]] - Required permissions (any)
+ * @property {string[]} [roles=[]] - Required roles (any)
+ * @property {boolean} [requireAll=false] - Require all permissions/roles (not just any)
+ */
+
+/**
+ * Authorization middleware configuration
+ * @typedef {Object} AuthMiddlewareConfig
+ * @property {Object<string, EndpointRequirement>} [requirements={}] - Per-endpoint requirements
+ * @property {number} [defaultTier=0] - Default tier for unlisted endpoints
+ * @property {boolean} [requireAuthByDefault=false] - Require auth for unlisted endpoints
+ * @property {Function} [onAuthzFail] - Callback on authorization failure
+ */
+
+/**
+ * Create authorization middleware
+ *
+ * @param {AuthMiddlewareConfig} [config={}] - Configuration options
+ * @returns {Object} Authorization middleware
+ *
+ * @example
+ * const authz = createAuthMiddleware({
+ *   requirements: {
+ *     'admin/*': { tier: 2 },
+ *     'user/profile': { tier: 1 },
+ *     'public/*': { tier: 0 }
+ *   },
+ *   defaultTier: 1
+ * });
+ *
+ * // Check authorization:
+ * const result = authz.check(socketAuth, 'admin/users');
+ * if (!result.allowed) {
+ *   send(queryId, 'authz_fail', result, null);
+ *   return;
+ * }
+ */
+function createAuthMiddleware(config = {}) {
+  const {
+    requirements = {},
+    defaultTier = 0,
+    requireAuthByDefault = false,
+    onAuthzFail = () => {},
+  } = config;
+
+  /**
+   * Find requirement for an endpoint, supporting wildcards
+   *
+   * @param {string} endpoint - Endpoint path
+   * @returns {EndpointRequirement|null} Requirement or null
+   */
+  function findRequirement(endpoint) {
+    if (requirements[endpoint]) {
+      return requirements[endpoint];
+    }
+
+    const parts = endpoint.split("/");
+    for (let i = parts.length - 1; i >= 0; i--) {
+      const wildcardPath = parts.slice(0, i).join("/") + "/*";
+      if (requirements[wildcardPath]) {
+        return requirements[wildcardPath];
+      }
+    }
+
+    if (requirements["*"]) {
+      return requirements["*"];
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if principal has required permission
+   *
+   * @param {Object} principal - Authenticated principal
+   * @param {string} permission - Required permission
+   * @returns {boolean} Whether principal has permission
+   */
+  function hasPermission(principal, permission) {
+    if (!principal || !principal.permissions) return false;
+
+    if (principal.permissions[permission] === true) {
+      return true;
+    }
+
+    const parts = permission.split(":");
+    for (let i = parts.length - 1; i > 0; i--) {
+      const wildcardPerm = parts.slice(0, i).join(":") + ":*";
+      if (principal.permissions[wildcardPerm] === true) {
+        return true;
+      }
+    }
+
+    if (principal.permissions["*"] === true) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if principal has required role
+   *
+   * @param {Object} principal - Authenticated principal
+   * @param {string} role - Required role
+   * @returns {boolean} Whether principal has role
+   */
+  function hasRole(principal, role) {
+    if (!principal || !principal.roles) return false;
+    return principal.roles.includes(role) || principal.roles.includes("*");
+  }
+
+  /**
+   * Check authorization for an endpoint
+   *
+   * @param {Object} socketAuth - Socket auth manager
+   * @param {string} endpoint - Endpoint being accessed
+   * @param {Object} [context={}] - Additional context
+   * @returns {Object} Authorization result { allowed, reason, ... }
+   */
+  function check(socketAuth, endpoint, context = {}) {
+    const state = socketAuth.getState();
+    const requirement = findRequirement(endpoint);
+
+    let requiredTier = defaultTier;
+    let requiredPermissions = [];
+    let requiredRoles = [];
+    let requireAll = false;
+
+    if (requirement) {
+      requiredTier = requirement.tier ?? defaultTier;
+      requiredPermissions = requirement.permissions || [];
+      requiredRoles = requirement.roles || [];
+      requireAll = requirement.requireAll || false;
+    } else if (requireAuthByDefault) {
+      requiredTier = AuthTier.BASIC;
+    }
+
+    if (state.tier < requiredTier) {
+      const result = {
+        allowed: false,
+        reason: "INSUFFICIENT_TIER",
+        requiredTier,
+        currentTier: state.tier,
+        endpoint,
+      };
+      onAuthzFail(endpoint, result, context);
+      return result;
+    }
+
+    if (requiredPermissions.length > 0) {
+      const hasRequired = requireAll
+        ? requiredPermissions.every((p) => hasPermission(state.principal, p))
+        : requiredPermissions.some((p) => hasPermission(state.principal, p));
+
+      if (!hasRequired) {
+        const result = {
+          allowed: false,
+          reason: "MISSING_PERMISSION",
+          required: requiredPermissions,
+          endpoint,
+        };
+        onAuthzFail(endpoint, result, context);
+        return result;
+      }
+    }
+
+    if (requiredRoles.length > 0) {
+      const hasRequired = requireAll
+        ? requiredRoles.every((r) => hasRole(state.principal, r))
+        : requiredRoles.some((r) => hasRole(state.principal, r));
+
+      if (!hasRequired) {
+        const result = {
+          allowed: false,
+          reason: "MISSING_ROLE",
+          required: requiredRoles,
+          endpoint,
+        };
+        onAuthzFail(endpoint, result, context);
+        return result;
+      }
+    }
+
+    return {
+      allowed: true,
+      tier: state.tier,
+      principal: state.principal,
+      endpoint,
+    };
+  }
+
+  /**
+   * Create an authz_fail response
+   *
+   * @param {Object} checkResult - Result from check()
+   * @returns {Object} Response suitable for sending to client
+   */
+  function createFailResponse(checkResult) {
+    return {
+      type: "authz_fail",
+      reason: checkResult.reason,
+      required: checkResult.required || checkResult.requiredTier,
+      currentTier: checkResult.currentTier,
+    };
+  }
+
+  /**
+   * Set requirement for an endpoint
+   *
+   * @param {string} endpoint - Endpoint path
+   * @param {EndpointRequirement} requirement - Requirement config
+   */
+  function setRequirement(endpoint, requirement) {
+    requirements[endpoint] = requirement;
+  }
+
+  /**
+   * Remove requirement for an endpoint
+   *
+   * @param {string} endpoint - Endpoint path
+   */
+  function removeRequirement(endpoint) {
+    delete requirements[endpoint];
+  }
+
+  /**
+   * Get all configured requirements
+   * @returns {Object<string, EndpointRequirement>} Requirements map
+   */
+  function getRequirements() {
+    return { ...requirements };
+  }
+
+  return {
+    check,
+    createFailResponse,
+    setRequirement,
+    removeRequirement,
+    getRequirements,
+    findRequirement,
+    hasPermission,
+    hasRole,
+  };
+}
+
+/**
+ * Default authorization middleware instance
+ *
+ * Created with default settings (tier 0 required for all endpoints).
+ * Can be replaced or configured in the main server setup.
+ */
+const defaultAuthMiddleware = createAuthMiddleware();
+
+module.exports = {
+  createAuthMiddleware,
+  defaultAuthMiddleware,
+};

package/server/socket/files.md

@@ -0,0 +1,86 @@
+# Socket Module Files
+
+This module handles WebSocket message processing for api-ape servers. It manages the complete lifecycle of messages flowing between clients and controllers—from initial connection validation through message parsing, controller invocation, and response serialization.
+
+## Guidelines
+
+- **JSS encoding** — Always use `utils/jss` for message parsing/serialization; never raw `JSON.parse/stringify`
+- **QueryId correlation** — Every response must include the original `queryId` for client-side Promise resolution
+- **Binary tag system** — Use `tagUtils.js` for all binary data detection; don't implement custom tag parsing
+- **Controller context** — Controllers receive `this` with `clientId`, `broadcast`, `send`, and embedded data
+- **Error handling** — Catch all controller errors and send error responses; never let exceptions crash the connection
+- **Security first** — All connections must pass `open.js` validation before processing messages
+
+## Directory Structure
+
+```
+socket/
+├── authMiddleware.js  # Authorization middleware for endpoint access control
+├── open.js            # Connection validation & security check
+├── receive.js         # Incoming message handler
+├── receiveContext.js  # Controller context factory
+├── send.js            # Outgoing message handler
+└── tagUtils.js        # Binary data tag parsing utilities
+```
+
+## Files
+
+### `authMiddleware.js`
+
+Authorization middleware for endpoint access control:
+
+- Checks auth tier requirements before controller invocation
+- Supports wildcard endpoint patterns (`admin/*`, `*`)
+- Permission and role-based authorization with `requireAll` option
+- Configurable per-endpoint requirements via `setRequirement()`
+- Creates standard `authz_fail` responses for unauthorized requests
+
+### `open.js`
+
+Connection open handler called when a new WebSocket connection is established:
+
+- Validates the connection origin against the host (CSRF protection)
+- Delegates to `security/origin.js` for origin verification
+- Returns `true` if connection is allowed, `false` to reject
+
+### `receive.js`
+
+Incoming message handler that processes client requests:
+
+- Parses incoming WebSocket messages (JSS encoded JSON)
+- Handles `subscribe` and `unsubscribe` messages for pub/sub channels
+- Extracts `type`, `data`, and `queryId` from the message
+- Detects binary upload tags (`<!B>`, `<!A>`, `<!F>`) in the message
+- Coordinates with `fileTransfer` to wait for HTTP uploads
+- Injects uploaded binary data into the message at the tagged paths
+- Invokes the appropriate controller with the complete message
+- Handles errors and sends error responses back to the client
+
+### `send.js`
+
+Outgoing message handler that serializes and sends responses:
+
+- Serializes controller return values using JSS encoding
+- Detects Buffer/ArrayBuffer values in responses
+- Replaces binary data with `<!L>` (link) tags for client download
+- Registers binary data with `fileTransfer` for HTTP download
+- Sends the serialized response with matching `queryId`
+
+### `receiveContext.js`
+
+Controller context factory that creates the `this` binding for controllers:
+
+- Extracts session ID from request cookies
+- Provides `broadcast()` and `broadcastOthers()` for messaging all clients
+- Provides `publish()` for pub/sub channel messaging
+- Exposes `clientId`, `sessionId`, and `clients` Map
+- When auth is configured, adds `isAuthenticated`, `authTier`, `principal`, and `requiresTier()`
+
+### `tagUtils.js`
+
+Utilities for parsing and processing binary data tags:
+
+- `findUploadTags(obj)` — Find all `<!B>` and `<!A>` tags with their paths
+- `findFileTags(obj)` — Find all `<!F>` tags for streaming transfers
+- `cleanUploadTags(obj)` — Remove tag suffixes from object keys
+- `setValueAtPath(obj, path, value)` — Inject values at dot-notation paths

package/server/socket/open.js

@@ -1,10 +1,156 @@
-const originSecurity = require( '../security/origin')
+/**
+ * @fileoverview Socket Open Handler - Connection Validation Gateway
+ *
+ * This module provides the entry point handler for new WebSocket connections.
+ * It acts as a security gateway, validating the connection origin and enforcing
+ * security policies before allowing the connection to proceed.
+ *
+ * ## Purpose
+ *
+ * When a new WebSocket connection is initiated, this handler:
+ * 1. Receives the socket and HTTP upgrade request
+ * 2. Delegates to origin security validation
+ * 3. Returns whether the connection should be accepted or rejected
+ *
+ * ## Security Flow
+ *
+ * ```
+ * Client Connect → open() → originSecurity() → Accept/Reject
+ *                              ↓
+ *                    - Validates Origin header
+ *                    - Checks domain allowlist
+ *                    - Prevents CSRF attacks
+ * ```
+ *
+ * ## Integration
+ *
+ * This handler is called by the wiring layer when a new WebSocket
+ * connection is received. It's the first line of defense against
+ * unauthorized or malicious connections.
+ *
+ * @module server/socket/open
+ * @see {@link module:server/security/origin} - Origin validation implementation
+ * @see {@link module:server/lib/wiring} - Wiring layer that calls this handler
+ *
+ * @example
+ * // Used internally by wiring layer
+ * const open = require('./socket/open')
+ *
+ * wss.on('connection', (socket, req) => {
+ *     const isValid = open(socket, req, (error) => {
+ *         console.error('Connection rejected:', error)
+ *     })
+ *
+ *     if (!isValid) {
+ *         socket.close(1008, 'Security policy violation')
+ *         return
+ *     }
+ *
+ *     // Connection accepted, continue with setup...
+ * })
+ *
+ * @example
+ * // Error callback receives security violation details
+ * open(socket, req, (error) => {
+ *     console.error('Security violation:', error.message)
+ *     // Log for security monitoring
+ *     securityLog.warn({
+ *         type: 'connection_rejected',
+ *         origin: req.headers.origin,
+ *         ip: req.socket.remoteAddress,
+ *         reason: error.message
+ *     })
+ * })
+ */
 
-module.exports = function open(socket, req, onError){
+const originSecurity = require("../security/origin");
 
-    const isSecure = originSecurity(socket, req, onError)
-    if ( ! isSecure) {
-       return false;
-    }
-    return true
-}
+/**
+ * Handle socket open event and validate connection security.
+ *
+ * This function is the first handler called when a new WebSocket
+ * connection is established. It validates the connection against
+ * security policies (primarily origin validation) and returns
+ * whether the connection should be accepted.
+ *
+ * ## Security Checks
+ *
+ * - **Origin Validation**: Ensures the Origin header matches allowed domains
+ * - **CSRF Prevention**: Blocks cross-origin requests from untrusted sources
+ * - **Protocol Compliance**: Validates WebSocket upgrade request format
+ *
+ * ## Failure Handling
+ *
+ * When validation fails:
+ * 1. The onError callback is invoked with error details
+ * 2. The function returns `false`
+ * 3. The caller is responsible for closing the socket
+ *
+ * ## Success Flow
+ *
+ * When validation succeeds:
+ * 1. The function returns `true`
+ * 2. The caller can proceed with connection setup
+ * 3. No error callback is invoked
+ *
+ * @function open
+ * @param {Object} socket - WebSocket instance (from WebSocketServer)
+ * @param {http.IncomingMessage} req - HTTP upgrade request object
+ * @param {function(Error): void} onError - Callback invoked on security failure
+ * @returns {boolean} True if connection is valid and secure, false otherwise
+ *
+ * @example
+ * // Basic usage in connection handler
+ * const isSecure = open(socket, req, (err) => {
+ *     console.error('Connection failed security check:', err)
+ * })
+ *
+ * if (!isSecure) {
+ *     return // Connection will be terminated
+ * }
+ *
+ * // Safe to proceed with connection setup
+ * setupConnection(socket, req)
+ *
+ * @example
+ * // With detailed error handling
+ * const isSecure = open(socket, req, (error) => {
+ *     // Log security event
+ *     logger.security('connection_rejected', {
+ *         origin: req.headers.origin,
+ *         host: req.headers.host,
+ *         ip: req.socket.remoteAddress,
+ *         userAgent: req.headers['user-agent'],
+ *         error: error.message
+ *     })
+ *
+ *     // Optionally notify security monitoring
+ *     if (isRateLimitExceeded(req.socket.remoteAddress)) {
+ *         alertSecurityTeam('Possible attack detected')
+ *     }
+ * })
+ *
+ * @example
+ * // In wiring layer integration
+ * function handleConnection(socket, req) {
+ *     // First, validate security
+ *     if (!open(socket, req, handleSecurityError)) {
+ *         socket.close(1008, 'Policy violation')
+ *         return null
+ *     }
+ *
+ *     // Connection is secure, create session
+ *     const session = createSession(socket, req)
+ *     return session
+ * }
+ */
+module.exports = function open(socket, req, onError) {
+  // Delegate to origin security for validation
+  const isSecure = originSecurity(socket, req, onError);
+
+  if (!isSecure) {
+    return false;
+  }
+
+  return true;
+};