api-ape 3.0.2 → 4.1.0

package/server/security/extractRootDomain.js

@@ -1,21 +1,149 @@
 /**
- * Extract root domain from a URL
- * e.g., "https://sub.example.com:3000/path" -> "example.com"
+ * @fileoverview Root Domain Extraction Utility
+ *
+ * This module provides a utility function to extract the root domain from a URL
+ * or hostname. This is useful for security checks like CORS origin validation,
+ * where you need to compare domains regardless of subdomains or ports.
+ *
+ * The function handles various input formats:
+ * - Full URLs: `https://sub.example.com:3000/path` → `example.com`
+ * - Hostnames with port: `api.example.com:8080` → `example.com`
+ * - Simple hostnames: `www.example.com` → `example.com`
+ * - Already root domains: `example.com` → `example.com`
+ *
+ * @module server/security/extractRootDomain
+ * @see {@link module:server/security/origin} - Origin security validation
+ *
+ * @example
+ * const extractRootDomain = require('./extractRootDomain')
+ *
+ * // Full URL with subdomain and port
+ * extractRootDomain('https://api.example.com:3000/v1/users')
+ * // Returns: 'example.com'
+ *
+ * // Hostname with subdomain
+ * extractRootDomain('www.mysite.org')
+ * // Returns: 'mysite.org'
+ *
+ * // Already a root domain
+ * extractRootDomain('example.com')
+ * // Returns: 'example.com'
  */
+
+/**
+ * Extracts the root domain from a URL or hostname.
+ *
+ * The root domain is the registrable domain (e.g., `example.com`) without
+ * any subdomains (e.g., `www`, `api`, `staging`).
+ *
+ * Algorithm:
+ * 1. If input contains `://`, parse as full URL and extract hostname
+ * 2. Otherwise, treat as hostname and remove port if present
+ * 3. Split hostname by `.` and take the last two segments
+ *
+ * **Country Code TLD Handling**:
+ * - Handles common ccTLDs like `.co.uk`, `.com.au`, `.me.uk`
+ * - Detection: If TLD is 2 chars AND SLD is a known pattern (co, com, net, org, me, ac, gov)
+ * - Example: `api.example.co.uk` → `example.co.uk` (not `co.uk`)
+ *
+ * **Limitations**:
+ * - For complex cases (e.g., `.pvt.k12.ma.us`), consider using
+ *   a proper public suffix list library
+ *
+ * @function extractRootDomain
+ * @param {string} url - Full URL or hostname to extract root domain from
+ * @returns {string} The root domain, or empty string if input is falsy
+ *
+ * @example
+ * // Full URL with subdomain
+ * extractRootDomain('https://sub.example.com:3000/path')
+ * // Returns: 'example.com'
+ *
+ * @example
+ * // Hostname with port
+ * extractRootDomain('api.example.com:8080')
+ * // Returns: 'example.com'
+ *
+ * @example
+ * // Simple subdomain
+ * extractRootDomain('www.example.com')
+ * // Returns: 'example.com'
+ *
+ * @example
+ * // Already root domain
+ * extractRootDomain('example.com')
+ * // Returns: 'example.com'
+ *
+ * @example
+ * // Two-part domain
+ * extractRootDomain('localhost')
+ * // Returns: 'localhost'
+ *
+ * @example
+ * // Null/undefined input
+ * extractRootDomain(null)
+ * // Returns: ''
+ *
+ * @example
+ * // Invalid URL falls back gracefully
+ * extractRootDomain('not-a-valid-url')
+ * // Returns: 'not-a-valid-url'
+ */
+// Common second-level domains used with country code TLDs
+const CCTLD_SLDS = new Set(["co", "com", "net", "org", "me", "ac", "gov", "edu"]);
+
+/**
+ * Check if a domain uses a country code TLD pattern
+ * @param {string[]} parts - Domain parts split by '.'
+ * @returns {boolean} True if this looks like a ccTLD domain
+ * @private
+ */
+function isCcTLD(parts) {
+  if (parts.length < 3) return false;
+  const tld = parts[parts.length - 1];
+  const sld = parts[parts.length - 2];
+  // TLD must be 2 chars (country code) AND SLD is a known pattern
+  return tld.length === 2 && CCTLD_SLDS.has(sld.toLowerCase());
+}
+
 module.exports = function extractRootDomain(url) {
-    if (!url) return ''
-    try {
-        // Handle full URLs
-        if (url.includes('://')) {
-            const hostname = new URL(url).hostname
-            const parts = hostname.split('.')
-            return parts.length > 2 ? parts.slice(-2).join('.') : hostname
+  // Handle null/undefined/empty input
+  if (!url) return "";
+
+  try {
+    // Check if this is a full URL (has protocol)
+    if (url.includes("://")) {
+      // Parse as URL to extract hostname
+      const hostname = new URL(url).hostname;
+      const parts = hostname.split(".");
+
+      if (parts.length > 2) {
+        // Check for country code TLD (e.g., .co.uk, .com.au, .me.uk)
+        if (isCcTLD(parts)) {
+          // Include the third-level domain for ccTLDs
+          return parts.slice(-3).join(".");
         }
-        // Handle hostname:port format
-        const hostname = url.split(':')[0]
-        const parts = hostname.split('.')
-        return parts.length > 2 ? parts.slice(-2).join('.') : hostname
-    } catch {
-        return url.split(':')[0]
+        return parts.slice(-2).join(".");
+      }
+      return hostname;
     }
-}
+
+    // Handle hostname:port format (no protocol)
+    // Remove port by splitting on ':' and taking first part
+    const hostname = url.split(":")[0];
+    const parts = hostname.split(".");
+
+    if (parts.length > 2) {
+      // Check for country code TLD (e.g., .co.uk, .com.au, .me.uk)
+      if (isCcTLD(parts)) {
+        return parts.slice(-3).join(".");
+      }
+      return parts.slice(-2).join(".");
+    }
+    return hostname;
+  } catch {
+    // If URL parsing fails, try to extract hostname from raw string
+    // This handles malformed URLs gracefully
+    return url.split(":")[0];
+  }
+};

package/server/security/files.md

@@ -0,0 +1,51 @@
+# Security Module Files
+
+This module provides security features to protect api-ape connections from common web vulnerabilities, including CSRF protection and duplicate request detection. Origin validation is enabled by default.
+
+## Guidelines
+
+- **Origin validation is critical** — Changes to `origin.js` affect all connection security; test thoroughly
+- **Domain matching** — Use `extractRootDomain.js` for domain comparisons; don't implement custom logic
+- **Subdomain support** — Origin checks must work with subdomains (e.g., `app.example.com` vs `example.com`)
+- **No configuration required** — Security features should work out-of-the-box with sensible defaults
+- **Fail secure** — When in doubt, reject the connection; false positives are better than security holes
+- **Localhost exceptions** — Development on localhost should work without origin issues
+
+## Directory Structure
+
+```
+security/
+├── extractRootDomain.js   # Domain extraction for origin validation
+├── origin.js              # Origin verification (CSRF protection)
+└── reply.js               # Duplicate request protection
+```
+
+## Files
+
+### `origin.js`
+
+Origin validation to prevent Cross-Site Request Forgery (CSRF) attacks:
+
+- Validates the `Origin` header against the `Host` header
+- Ensures WebSocket connections only come from the same origin
+- Automatically rejects cross-origin requests
+- Works with both Express.js and raw Node.js servers
+- Returns `true` if valid, `false` to reject connection
+
+### `extractRootDomain.js`
+
+Extracts the root domain from a hostname for flexible origin matching:
+
+- Handles subdomains (e.g., `app.example.com` → `example.com`)
+- Handles IP addresses and localhost
+- Handles ports in host strings (strips them for comparison)
+- Used by `origin.js` for domain comparison
+
+### `reply.js`
+
+Duplicate request protection to prevent replay attacks:
+
+- Tracks recently processed `queryId` values
+- Rejects duplicate requests within a configurable time window
+- Prevents attackers from replaying captured WebSocket messages
+- Automatically cleans up expired entries

package/server/security/origin.js

@@ -1,25 +1,207 @@
-const extractRootDomain = require('./extractRootDomain')
+/**
+ * @fileoverview Origin Security Check for api-ape WebSocket Connections
+ *
+ * This module provides Cross-Site Request Forgery (CSRF) protection for
+ * WebSocket connections by validating that the request's Origin header
+ * matches the server's Host header.
+ *
+ * ## Why Origin Validation Matters
+ *
+ * WebSocket connections bypass the Same-Origin Policy that protects regular
+ * HTTP requests. Without origin validation, a malicious website could:
+ *
+ * 1. Connect to your WebSocket server from any domain
+ * 2. Send requests using the victim's cookies/credentials
+ * 3. Access data or perform actions as the authenticated user
+ *
+ * ## How It Works
+ *
+ * ```
+ * Browser Request:
+ *   Origin: https://evil.com
+ *   Host: api.example.com
+ *
+ * Validation:
+ *   extractRootDomain('https://evil.com') → 'evil.com'
+ *   extractRootDomain('api.example.com')  → 'example.com'
+ *   'evil.com' !== 'example.com' → REJECT
+ * ```
+ *
+ * ## Allowed Scenarios
+ *
+ * | Origin               | Host                  | Result  | Reason                    |
+ * |----------------------|-----------------------|---------|---------------------------|
+ * | https://example.com  | api.example.com       | ✓ Allow | Same root domain          |
+ * | https://app.example.com | example.com        | ✓ Allow | Same root domain          |
+ * | (none)               | example.com           | ✓ Allow | No origin = same-origin   |
+ * | https://evil.com     | example.com           | ✗ Reject| Different domains         |
+ * | https://example.com.evil.com | example.com   | ✗ Reject| Fake subdomain attack     |
+ *
+ * ## Subdomains
+ *
+ * The validation uses root domain comparison (via `extractRootDomain`),
+ * which means subdomains of the same root are allowed:
+ * - `app.example.com` and `api.example.com` share root `example.com`
+ * - Both are allowed to connect to each other
+ *
+ * @module server/security/origin
+ * @see {@link module:server/security/extractRootDomain} for domain extraction
+ * @see {@link module:server/socket/open} for usage in connection handling
+ *
+ * @example <caption>Basic Usage in Connection Handler</caption>
+ * const originSecurity = require('./security/origin')
+ *
+ * function handleConnection(socket, req) {
+ *   const isSecure = originSecurity(socket, req, (err) => {
+ *     console.error('Security error:', err)
+ *   })
+ *
+ *   if (!isSecure) {
+ *     return // Connection was rejected
+ *   }
+ *
+ *   // Continue with connection setup...
+ * }
+ *
+ * @example <caption>Integration with api-ape</caption>
+ * // This is called internally by socket/open.js
+ * const isOk = originSecurity(socket, req, onError)
+ *
+ * if (!isOk) {
+ *   // Socket was destroyed, client removed
+ *   return
+ * }
+ *
+ * // Proceed with message handling
+ */
 
-// Helper to get header that works with both Express and raw Node http
+const extractRootDomain = require("./extractRootDomain");
+
+/**
+ * Get a header value from an HTTP request
+ *
+ * Handles both Express-style requests (with `.header()` method) and
+ * raw Node.js http.IncomingMessage requests (with `.headers` object).
+ *
+ * @param {http.IncomingMessage|express.Request} req - HTTP request object
+ * @param {string} name - Header name (case-insensitive for raw requests)
+ * @returns {string|undefined} Header value, or undefined if not present
+ * @private
+ *
+ * @example
+ * // Express request
+ * getHeader(expressReq, 'Origin')  // Uses req.header('Origin')
+ *
+ * // Raw Node.js request
+ * getHeader(httpReq, 'Origin')     // Uses req.headers['origin']
+ */
 function getHeader(req, name) {
-  // Express-style
-  if (typeof req.header === 'function') {
-    return req.header(name)
+  // Express-style request with .header() method
+  if (typeof req.header === "function") {
+    return req.header(name);
   }
-  // Raw Node.js http request
-  return req.headers[name.toLowerCase()]
+  // Raw Node.js http request - headers are lowercase
+  return req.headers[name.toLowerCase()];
 }
 
+/**
+ * Verify that request origin matches host to prevent CSRF attacks
+ *
+ * Compares the `Origin` header (where the request came from) with the
+ * `Host` header (the server being accessed). If they don't match,
+ * the connection is rejected and the socket is destroyed.
+ *
+ * ## Security Notes
+ *
+ * - **Missing Origin**: Allowed, as same-origin requests may omit Origin
+ * - **Matching Root Domain**: Both headers are reduced to root domains,
+ *   so `app.example.com` and `api.example.com` both match `example.com`
+ * - **Socket Destruction**: Rejected connections have their socket destroyed
+ *   to immediately terminate the connection
+ *
+ * ## When Connections Are Rejected
+ *
+ * - Origin domain doesn't match Host domain
+ * - Potential subdomain spoofing (e.g., `example.com.evil.com`)
+ *
+ * ## When Connections Are Allowed
+ *
+ * - No Origin header (browser same-origin requests)
+ * - Origin root domain matches Host root domain
+ *
+ * @param {WebSocket} socket - WebSocket instance (must have `.destroy()` method)
+ * @param {http.IncomingMessage} req - HTTP upgrade request
+ * @param {Function} [onError=console.error] - Error callback for logging rejections
+ * @returns {boolean} True if origin is valid and connection should proceed,
+ *                    false if connection was rejected and destroyed
+ *
+ * @example <caption>Basic Validation</caption>
+ * const isValid = originSecurity(socket, req)
+ *
+ * if (!isValid) {
+ *   // Socket was destroyed, connection rejected
+ *   return
+ * }
+ *
+ * // Origin is valid, proceed
+ * setupMessageHandlers(socket)
+ *
+ * @example <caption>With Custom Error Handler</caption>
+ * const isValid = originSecurity(socket, req, (errorMessage) => {
+ *   logger.security.warn(errorMessage, {
+ *     ip: req.socket.remoteAddress,
+ *     origin: req.headers.origin,
+ *     host: req.headers.host
+ *   })
+ * })
+ *
+ * @example <caption>Scenarios</caption>
+ * // Scenario 1: Same domain - ALLOWED
+ * // Origin: https://example.com, Host: example.com
+ * // extractRootDomain → both 'example.com' → Match ✓
+ *
+ * // Scenario 2: Subdomain - ALLOWED
+ * // Origin: https://app.example.com, Host: api.example.com
+ * // extractRootDomain → both 'example.com' → Match ✓
+ *
+ * // Scenario 3: Different domain - REJECTED
+ * // Origin: https://evil.com, Host: example.com
+ * // extractRootDomain → 'evil.com' vs 'example.com' → No match ✗
+ *
+ * // Scenario 4: No origin - ALLOWED
+ * // Origin: (not present), Host: example.com
+ * // Empty origin doesn't trigger check ✓
+ *
+ * // Scenario 5: Spoofed subdomain - REJECTED
+ * // Origin: https://example.com.evil.com, Host: example.com
+ * // extractRootDomain → 'evil.com' vs 'example.com' → No match ✗
+ */
 module.exports = function (socket, req, onError) {
-  onError = onError || console.error
-  const origin = extractRootDomain(getHeader(req, 'Origin') || "")
-  const host = extractRootDomain(getHeader(req, 'Host'))
+  // Default error handler to console.error if not provided
+  onError = onError || console.error;
+
+  // Extract root domains for comparison
+  const origin = extractRootDomain(getHeader(req, "Origin") || "");
+  const host = extractRootDomain(getHeader(req, "Host"));
+
+  // Check for origin mismatch (only if Origin header is present)
   if (origin && origin !== host) {
-    onError("REJECTING socket from " + getHeader(req, 'Origin') + " miss-match with " + getHeader(req, 'Host'))
+    // Log the rejection
+    onError(
+      "REJECTING socket from " +
+        getHeader(req, "Origin") +
+        " mismatch with " +
+        getHeader(req, "Host"),
+    );
+
+    // Destroy the socket to terminate the connection
     if (socket && socket.destroy) {
-      socket.destroy()
+      socket.destroy();
     }
-    return false
+
+    return false;
   }
-  return true
-}
+
+  // Origin is valid (or not present)
+  return true;
+};