api-ape 3.0.1 → 4.1.0

package/server/plugins/binary.js

@@ -0,0 +1,282 @@
+/**
+ * @fileoverview Binary Data Transfer Plugins for JSS
+ *
+ * This module provides plugins for handling binary data transfer in api-ape.
+ * It moves the binary handling logic from hardcoded server code into the
+ * pluggable JSS system.
+ *
+ * ## Plugin Tags
+ *
+ * | Tag | Direction       | Description                                    |
+ * |-----|-----------------|------------------------------------------------|
+ * | `I` | Server→Client   | Inline base64 for small binary (<=100 chars)   |
+ * | `L` | Server→Client   | Link to downloadable binary data (large)       |
+ * | `B` | Client→Server   | Buffer upload (resolves to Buffer)             |
+ * | `A` | Client→Server   | ArrayBuffer upload (resolves to ArrayBuffer)   |
+ * | `F` | Client→Client   | Streaming file transfer                        |
+ *
+ * ## Usage
+ *
+ * ```javascript
+ * const { registerBinaryPlugins } = require('./plugins/binary')
+ *
+ * // During server initialization
+ * registerBinaryPlugins()
+ * ```
+ *
+ * @module server/plugins/binary
+ * @see {@link module:utils/jss/plugins} for plugin system
+ * @see {@link module:server/lib/fileTransfer} for file transfer management
+ */
+
+const jss = require("../../utils/jss");
+
+/**
+ * Maximum size in base64 characters for inline binary encoding
+ * Data up to this size will be inlined as base64 in the message.
+ * Larger data will use HTTP transfer (L tag).
+ *
+ * 100 base64 chars ≈ 75 raw bytes
+ * @constant {number}
+ */
+const INLINE_BASE64_THRESHOLD = 100;
+
+/**
+ * Check if a value is binary data
+ *
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is Buffer, ArrayBuffer, or TypedArray
+ * @private
+ */
+function isBinaryData(value) {
+  if (value === null || value === undefined) return false;
+  return (
+    Buffer.isBuffer(value) ||
+    value instanceof ArrayBuffer ||
+    ArrayBuffer.isView(value)
+  );
+}
+
+/**
+ * Get the base64 encoded length for binary data
+ *
+ * @param {Buffer|ArrayBuffer|ArrayBufferView} value - Binary data
+ * @returns {number} Length when encoded as base64
+ * @private
+ */
+function getBase64Length(value) {
+  let byteLength;
+  if (Buffer.isBuffer(value)) {
+    byteLength = value.length;
+  } else if (value instanceof ArrayBuffer) {
+    byteLength = value.byteLength;
+  } else if (ArrayBuffer.isView(value)) {
+    byteLength = value.byteLength;
+  } else {
+    return Infinity; // Unknown type, use HTTP transfer
+  }
+  // Base64 encoding increases size by ~33%
+  return Math.ceil((byteLength * 4) / 3);
+}
+
+/**
+ * Register binary data plugins for server-side use
+ *
+ * Call this during server initialization to enable binary transfer
+ * functionality through the JSS plugin system.
+ *
+ * @example
+ * const { registerBinaryPlugins } = require('./plugins/binary')
+ * registerBinaryPlugins()
+ *
+ * // Now binary data in controller responses will be handled automatically
+ * // Controller: return { image: Buffer.from(...) }
+ * // Client receives: { 'image<!L>': 'hash123' }
+ */
+function registerBinaryPlugins() {
+  const { FileTransferManager } = require("../lib/fileTransfer");
+
+  /**
+   * I tag: Inline base64 for small binary data
+   *
+   * For small binary data (<=100 base64 chars / ~75 bytes):
+   * 1. Converts to base64 inline in the message
+   * 2. No HTTP transfer required - reduces latency
+   *
+   * NOTE: Must be registered BEFORE L tag so it's checked first
+   */
+  jss.custom("I", {
+    // Check if value is SMALL binary data that should be inlined
+    check: (key, value) => {
+      if (!isBinaryData(value)) return false;
+      return getBase64Length(value) <= INLINE_BASE64_THRESHOLD;
+    },
+
+    // Encode: convert to base64 string
+    encode: (path, key, value, context) => {
+      const buffer = Buffer.isBuffer(value)
+        ? value
+        : Buffer.from(
+            value instanceof ArrayBuffer
+              ? value
+              : value.buffer.slice(
+                  value.byteOffset,
+                  value.byteOffset + value.byteLength,
+                ),
+          );
+      return buffer.toString("base64");
+    },
+
+    // Decode: handled by built-in I decoder in decode.js
+    decode: (value, path, context) => Buffer.from(value, "base64"),
+
+    // No onSend needed - data is inlined, no HTTP transfer
+  });
+
+  /**
+   * L tag: Server → Client downloads
+   *
+   * When a controller returns LARGE binary data (Buffer, ArrayBuffer, TypedArray),
+   * this plugin:
+   * 1. Registers the data as a pending download
+   * 2. Replaces the value with a hash reference
+   * 3. Client fetches via HTTP GET /api/ape/data/{hash}
+   *
+   * NOTE: Small binary data is handled by I tag (inline base64)
+   */
+  jss.custom("L", {
+    // Check if value is LARGE binary data that should be sent as download
+    check: (key, value) => {
+      if (!isBinaryData(value)) return false;
+      return getBase64Length(value) > INLINE_BASE64_THRESHOLD;
+    },
+
+    // Encode: return placeholder (actual value set by onSend)
+    encode: (path, key, value, context) => "__pending__",
+
+    // Decode: on client side, the hash is returned as-is
+    // Client will fetch the actual data via HTTP
+    decode: (value, path, context) => value,
+
+    // onSend: register the binary data for HTTP download
+    onSend: (path, key, value, context) => {
+      const pathStr = path.length > 0 ? path.join(".") : "root";
+      const hash = FileTransferManager.generateHash(context.queryId, pathStr);
+
+      // Detect content type (could be enhanced with magic number detection)
+      const contentType = "application/octet-stream";
+
+      // Register for HTTP download
+      context.fileTransfer.registerDownload(
+        hash,
+        value,
+        contentType,
+        context.clientId,
+      );
+
+      return { replace: hash };
+    },
+  });
+
+  /**
+   * B tag: Client → Server Buffer uploads
+   *
+   * When a client sends binary data with <!B> tag:
+   * 1. Server registers an upload expectation
+   * 2. Client uploads via HTTP PUT /api/ape/data/{queryId}/{hash}
+   * 3. onReceive resolves with the uploaded Buffer
+   */
+  jss.custom("B", {
+    // Check: B tags come from client, we don't check server-side values
+    check: () => false,
+
+    // Encode: not used (B is client→server only)
+    encode: (path, key, value, context) => value,
+
+    // Decode: the hash value is decoded as-is, actual data set by onReceive
+    decode: (value, path, context) => value,
+
+    // onReceive: wait for the binary upload
+    onReceive: async (path, key, hash, context) => {
+      const uploadData = await context.fileTransfer.registerUpload(
+        context.queryId,
+        hash,
+        context.clientId,
+      );
+      return uploadData;
+    },
+  });
+
+  /**
+   * A tag: Client → Server ArrayBuffer uploads
+   *
+   * Same as B tag but returns ArrayBuffer instead of Buffer.
+   */
+  jss.custom("A", {
+    // Check: A tags come from client, we don't check server-side values
+    check: () => false,
+
+    // Encode: not used (A is client→server only)
+    encode: (path, key, value, context) => value,
+
+    // Decode: the hash value is decoded as-is, actual data set by onReceive
+    decode: (value, path, context) => value,
+
+    // onReceive: wait for the binary upload, convert to ArrayBuffer
+    onReceive: async (path, key, hash, context) => {
+      const uploadData = await context.fileTransfer.registerUpload(
+        context.queryId,
+        hash,
+        context.clientId,
+      );
+      // Convert Buffer to ArrayBuffer
+      return uploadData.buffer.slice(
+        uploadData.byteOffset,
+        uploadData.byteOffset + uploadData.byteLength,
+      );
+    },
+  });
+
+  /**
+   * F tag: Client → Client streaming file transfers
+   *
+   * Used for peer-to-peer file sharing between clients.
+   * The server acts as an intermediary, streaming data from
+   * sender to receiver without storing the entire file.
+   */
+  jss.custom("F", {
+    // Check: F tags come from client, we don't check server-side values
+    check: () => false,
+
+    // Encode: pass through (F tags are managed by client)
+    encode: (path, key, value, context) => value,
+
+    // Decode: pass through
+    decode: (value, path, context) => value,
+
+    // onReceive: register streaming file expectation
+    onReceive: async (path, key, hash, context) => {
+      // Register the streaming file to receive uploads
+      context.fileTransfer.registerStreamingFile(hash, context.clientId);
+      // Return the hash - actual streaming happens via HTTP
+      return hash;
+    },
+  });
+}
+
+/**
+ * Check if binary plugins are currently registered
+ *
+ * @returns {boolean} True if the L plugin is registered
+ */
+function areBinaryPluginsRegistered() {
+  const { hasPlugin } = require("../../utils/jss/plugins");
+  return hasPlugin("L");
+}
+
+module.exports = {
+  registerBinaryPlugins,
+  areBinaryPluginsRegistered,
+  isBinaryData,
+  INLINE_BASE64_THRESHOLD,
+};

package/server/security/README.md

@@ -0,0 +1,92 @@
+# Security Module
+
+## Overview
+
+This module provides security features to protect api-ape connections from common web vulnerabilities, including Cross-Site Request Forgery (CSRF) protection and duplicate request detection.
+
+**Key capabilities:**
+
+- **Origin validation** — Verify WebSocket connections originate from the same domain
+- **CSRF protection** — Automatically reject cross-origin WebSocket requests
+- **Replay protection** — Detect and reject duplicate requests within a time window
+- **Domain extraction** — Flexible matching for subdomains and complex hostnames
+
+Origin validation is **enabled by default** with no configuration required.
+
+> **Contributing?** See [`files.md`](./files.md) for directory structure and file descriptions.
+
+## How CSRF Protection Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   WebSocket Upgrade Request                 │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Headers:                                                   │
+│    Host: example.com                                        │
+│    Origin: https://example.com                              │
+│                                                             │
+│  origin.js checks:                                          │
+│    1. Extract domain from Host header                       │
+│    2. Extract domain from Origin header                     │
+│    3. Compare root domains                                  │
+│    4. Accept if match, reject if mismatch                   │
+│                                                             │
+│  ✓ Same origin: example.com === example.com → ALLOWED       │
+│  ✗ Cross origin: evil.com !== example.com → REJECTED        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Why Origin Validation Matters
+
+Without origin validation, malicious websites could:
+
+1. Open WebSocket connections to your api-ape server
+2. Execute API calls using the victim's session cookies
+3. Access or modify data on behalf of authenticated users
+
+Origin validation ensures only your own frontend can establish WebSocket connections.
+
+## Authentication
+
+The security module includes a complete authentication system with:
+
+- **OPAQUE/PAKE authentication** — Password-authenticated key exchange (server never sees raw password)
+- **Tiered security model** — Guest → Basic → Elevated → High Security
+- **State machine enforcement** — No-downgrade rule, timeout handling, rate limiting
+- **Authorization middleware** — Per-endpoint tier and permission checks
+- **Adapter pattern** — Pluggable authentication methods
+
+See [`auth/README.md`](auth/README.md) for full documentation.
+
+### Quick Example
+
+```js
+const { createAuthFramework } = require('api-ape/server/security/auth');
+const { createAuthMiddleware } = require('api-ape/server/socket/authMiddleware');
+
+const authFramework = createAuthFramework({
+  opaque: {
+    getUser: async (username) => db.users.findOne({ username }),
+    saveUser: async (username, data) => db.users.insertOne({ username, ...data })
+  }
+});
+
+const authMiddleware = createAuthMiddleware({
+  requirements: {
+    'admin/*': { tier: 2 },  // Admin requires MFA
+    'user/*': { tier: 1 },   // User requires auth
+    'public/*': { tier: 0 }  // Public allows guests
+  }
+});
+
+ape(server, { where: 'api', authFramework, authMiddleware });
+```
+
+## See Also
+
+- [`auth/README.md`](auth/README.md) — Authentication module documentation
+- [`../socket/open.js`](../socket/open.js) — Connection open handler using security
+- [`../lib/wiring.js`](../lib/wiring.js) — WebSocket connection setup
+- [OWASP CSRF Prevention](https://owasp.org/www-community/attacks/csrf) — CSRF attack documentation

package/server/security/auth/README.md

@@ -0,0 +1,319 @@
+# Authentication Module
+
+## Overview
+
+This module provides a tiered authentication system for api-ape WebSocket connections. It supports OPAQUE-based password authentication where the server never learns raw passwords, with MFA (WebAuthn/TOTP) for elevated security and extensibility for enterprise SSO adapters.
+
+**Key capabilities:**
+
+- **OPAQUE/PAKE authentication** — Password-authenticated key exchange (server never sees raw password)
+- **MFA support** — WebAuthn (FIDO2) and TOTP (RFC 6238) for Tier 2 elevation
+- **Passport.js compatible** — MFA adapters work with existing Passport.js strategies
+- **Tiered security model** — Guest → Basic → Elevated → High Security
+- **State machine enforcement** — No-downgrade rule, timeout handling, rate limiting
+- **Authorization middleware** — Per-endpoint tier and permission checks
+- **Adapter pattern** — Pluggable authentication methods (OPAQUE, WebAuthn, TOTP, LDAP, SAML, OAuth2)
+
+> **Contributing?** See the module files for implementation details.
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                     AuthFramework                                   │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │  Adapter Registry                                             │  │
+│  │  - OPAQUE (Tier 1) ✓                                         │  │
+│  │  - WebAuthn (Tier 2 MFA) ✓                                   │  │
+│  │  - TOTP (Tier 2 MFA) ✓                                       │  │
+│  │  - LDAP, SAML, OAuth2 (Tier 1, planned)                      │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │  Per-Socket State Machines                                    │  │
+│  │  - Tracks auth state per clientId                            │  │
+│  │  - Enforces tier requirements                                │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │  Message Router                                               │  │
+│  │  - Routes auth messages to appropriate adapter               │  │
+│  │  - Handles opaque_*, webauthn_*, totp_*, mfa_* messages     │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## Authentication Tiers
+
+| Tier | Name | Description |
+|------|------|-------------|
+| 0 | GUEST | Unauthenticated, public endpoints only |
+| 1 | BASIC | Identity verified via OPAQUE/SRP or enterprise SSO |
+| 2 | ELEVATED | Tier 1 + MFA (WebAuthn or TOTP) |
+| 3 | HIGH_SECURITY | Full 2-of-3 scheme for client-side key reconstruction |
+
+## Quick Start
+
+### 1. Create the Auth Framework
+
+```js
+const { createAuthFramework } = require('api-ape/server/security/auth');
+const { createAuthMiddleware } = require('api-ape/server/socket/authMiddleware');
+
+const authFramework = createAuthFramework({
+  opaque: {
+    // Provide your user storage functions
+    getUser: async (username) => db.users.findOne({ username }),
+    saveUser: async (username, data) => db.users.insertOne({ username, ...data })
+  },
+  webauthn: {
+    rpId: 'example.com',
+    rpName: 'My App',
+    // Optional: provide credential storage
+    getCredentials: async (userId) => db.webauthn.find({ userId }),
+    saveCredential: async (userId, credential) => db.webauthn.insertOne({ userId, ...credential })
+  },
+  totp: {
+    issuer: 'My App',
+    // Optional: provide secret storage
+    getSecret: async (userId) => db.totp.findOne({ userId }),
+    saveSecret: async (userId, data) => db.totp.upsertOne({ userId }, data)
+  },
+  mfaMethods: ['webauthn', 'totp'],
+  onAuthSuccess: (clientId, principal) => {
+    console.log(`${clientId} authenticated as ${principal.userId}`);
+  },
+  onMFASuccess: (clientId, principal, method) => {
+    console.log(`${clientId} elevated via ${method}`);
+  }
+});
+```
+
+### 2. Configure Authorization Rules
+
+```js
+const authMiddleware = createAuthMiddleware({
+  requirements: {
+    'admin/*': { tier: 2 },           // Admin endpoints require MFA
+    'user/*': { tier: 1 },            // User endpoints require auth
+    'public/*': { tier: 0 }           // Public endpoints allow guests
+  },
+  defaultTier: 0
+});
+```
+
+### 3. Pass to ape()
+
+```js
+const { ape } = require('api-ape');
+
+ape(server, {
+  where: 'api',
+  authFramework,      // Enable authentication
+  authMiddleware      // Enable authorization
+});
+```
+
+## Message Protocol
+
+### OPAQUE Registration (Tier 1)
+
+```
+Client                              Server
+  |-- opaque_reg_start ----------->|  { user, clientNonce, regRequest }
+  |<- opaque_reg_response ---------|  { serverNonce, ts, regResponse }
+  |-- opaque_reg_finish ---------->|  { regRecord }
+  |<- opaque_reg_ok ---------------|  { msg: "registered" }
+```
+
+### OPAQUE Authentication (Tier 1)
+
+```
+Client                              Server
+  |-- opaque_auth_start ---------->|  { user, clientNonce }
+  |<- opaque_auth_1 ---------------|  { serverNonce, ts, envelope, oprfResponse }
+  |-- opaque_auth_2 -------------->|  { clientAuth }
+  |<- opaque_auth_ok --------------|  { assignedPrincipal, serverProof, tier: 1 }
+```
+
+### WebAuthn Registration (MFA Setup)
+
+```
+Client                              Server
+  |-- webauthn_reg_start --------->|  { userId, userName }
+  |<- webauthn_reg_challenge ------|  { challenge, rp, user, pubKeyCredParams }
+  |-- webauthn_reg_finish -------->|  { challenge, attestation }
+  |<- webauthn_reg_ok -------------|  { credentialId }
+```
+
+### WebAuthn Authentication (Tier 2 Elevation)
+
+```
+Client                              Server
+  |-- webauthn_auth_start -------->|  { userId }
+  |<- webauthn_auth_challenge -----|  { challenge, allowCredentials }
+  |-- webauthn_auth_finish ------->|  { challenge, assertion }
+  |<- webauthn_auth_ok ------------|  { tier: 2 }
+```
+
+### TOTP Setup
+
+```
+Client                              Server
+  |-- totp_setup_start ----------->|  { userId }
+  |<- totp_setup_challenge --------|  { secret, otpauthUri }
+  |-- totp_setup_verify ---------->|  { code }
+  |<- totp_setup_ok ---------------|  { }
+```
+
+### TOTP Verification (Tier 2 Elevation)
+
+```
+Client                              Server
+  |-- totp_verify ---------------->|  { userId, code }
+  |<- totp_ok --------------------|  { tier: 2 }
+```
+
+### Generic MFA Challenge Flow
+
+```
+Client                              Server
+  |-- mfa_challenge -------------->|  { }
+  |<- mfa_challenge ---------------|  { methods: [{ method: "totp" }, { method: "webauthn", challenge: {...} }] }
+  |-- mfa_verify ----------------->|  { method: "totp", code: "123456" }
+  |<- mfa_elevated ----------------|  { method: "totp", tier: 2 }
+```
+
+## Passport.js Compatibility
+
+Both WebAuthn and TOTP adapters are compatible with Passport.js:
+
+```js
+const passport = require('passport');
+const { WebAuthnStrategy, TOTPStrategy } = require('api-ape/server/security/auth');
+
+// Use with Passport.js
+passport.use('webauthn', new WebAuthnStrategy({
+  rpId: 'example.com',
+  rpName: 'My App'
+}, (user, done) => {
+  // Custom verification logic
+  done(null, user);
+}));
+
+passport.use('totp', new TOTPStrategy({
+  issuer: 'My App'
+}, (user, done) => {
+  // Custom verification logic
+  done(null, user);
+}));
+```
+
+## Controller Context
+
+After authentication, controllers have access to auth state via `this`:
+
+```js
+// api/protected/data.js
+module.exports = function(query) {
+  // Check authentication
+  if (!this.isAuthenticated) {
+    throw new Error('Authentication required');
+  }
+
+  // Access user info
+  console.log('User:', this.principal.userId);
+  console.log('Roles:', this.principal.roles);
+  console.log('Tier:', this.authTier);
+
+  // Check tier requirement
+  if (!this.requiresTier(2)) {
+    throw new Error('MFA required for this operation');
+  }
+
+  return { data: 'sensitive info' };
+};
+```
+
+### Available Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `this.isAuthenticated` | `boolean` | Whether socket is authenticated (Tier ≥ 1) |
+| `this.authTier` | `number` | Current tier (0-3) |
+| `this.principal` | `object\|null` | User info: `{ userId, roles, permissions }` |
+| `this.authState` | `object\|null` | Full auth state object |
+| `this.requiresTier(n)` | `function` | Check if socket meets minimum tier |
+
+## Client Tracking
+
+Query auth state for any connected client:
+
+```js
+const client = this.clients.get(targetClientId);
+
+if (client.isAuthenticated) {
+  console.log('User:', client.authState.principal.userId);
+  console.log('Tier:', client.authTier);
+}
+```
+
+## State Machine
+
+```
+GUEST → AUTHENTICATING → AUTHENTICATED (Tier 1)
+                               │
+               ┌───────────────┼───────────────┐
+               │               │               │
+         MFA_PENDING    KEY_RECOVERY     (stay Tier 1)
+               │               │
+               ▼               ▼
+         ELEVATED (2)   HIGH_SECURITY (3)
+```
+
+**Rules:**
+
+- No downgrade after authentication
+- Higher tiers require completing lower tiers first
+- Auth timeout closes incomplete sessions
+- Rate limiting and lockout after failed attempts
+
+## Security Features
+
+| Feature | Description |
+|---------|-------------|
+| **Password protection** | OPAQUE ensures server never sees raw password |
+| **Replay prevention** | Single-use nonces with 30s expiry |
+| **No-downgrade** | Cannot return to lower tier after auth |
+| **Rate limiting** | Lockout after configurable failed attempts |
+| **Session binding** | Auth bound to `clientId + nonces + timestamp` |
+| **TOTP replay protection** | Tracks used counters to prevent code reuse |
+| **WebAuthn counter** | Validates and updates authenticator counter |
+
+## File Structure
+
+```
+auth/
+├── index.js              # Auth framework coordinator
+├── index.test.js         # Integration tests (23 tests)
+├── state-machine.js      # State transitions, tier management
+├── state-machine.test.js # State machine tests (31 tests)
+├── nonce-manager.js      # Single-use nonce handling
+├── adapters/
+│   ├── opaque.js         # OPAQUE/SRP implementation
+│   ├── opaque.test.js    # OPAQUE tests (12 tests)
+│   ├── webauthn.js       # WebAuthn/FIDO2 adapter (Passport.js compatible)
+│   ├── webauthn.test.js  # WebAuthn tests (25 tests)
+│   ├── totp.js           # TOTP RFC 6238 adapter (Passport.js compatible)
+│   └── totp.test.js      # TOTP tests (35 tests)
+└── handlers/
+    └── auth-messages.js  # Message routing
+```
+
+**Total: 114 tests passing**
+
+## See Also
+
+- [`../README.md`](../README.md) — Security module overview
+- [`../../socket/authMiddleware.js`](../../socket/authMiddleware.js) — Authorization middleware
+- [`../../socket/receiveContext.js`](../../socket/receiveContext.js) — Controller context with auth
+- [`../../../todo/Security.md`](../../../todo/Security.md) — Security architecture design
+- [`../../../todo/implementation-checklist.md`](../../../todo/implementation-checklist.md) — Implementation progress