threadforge 0.1.0

package/src/core/ForgeContext.js

@@ -0,0 +1,2227 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import { createServer } from "node:http";
+import path from "node:path";
+import { getContract } from "../decorators/index.js";
+import { StaticMountRegistry } from "../frontend/StaticMountRegistry.js";
+import { IngressProtection } from "./Ingress.js";
+import { PrometheusMetrics } from "./Prometheus.js";
+import { RequestContext } from "./RequestContext.js";
+import { WorkerChannelManager } from "./WorkerChannelManager.js";
+// A10: Network utilities extracted to network-utils.js
+import { isPrivateNetwork, isTrustedProxy } from "./network-utils.js";
+
+// Re-export for backward compatibility (A10)
+export { isPrivateNetwork, isTrustedProxy };
+
+const MAX_BODY_SIZE = 1_048_576; // 1MB
+const MAX_WS_BUFFER = 1 * 1024 * 1024; // 1MB
+const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
+// S11: Body timeout reduced from 30s to 10s
+const BODY_TIMEOUT_MS = 10_000;
+// S1: HMAC signature max clock skew (replay protection)
+const INTERNAL_SIG_MAX_AGE_MS = 30_000;
+// P11: Route cache max size
+const ROUTE_CACHE_MAX = 10_000;
+const EXTENSION_TO_MIME = Object.freeze({
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".cjs": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".txt": "text/plain; charset=utf-8",
+  ".xml": "application/xml; charset=utf-8",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+});
+
+// O5: Log levels
+const LOG_LEVELS = { error: 0, warn: 1, info: 2, debug: 3 };
+
+export const NOT_HANDLED = Symbol("NOT_HANDLED");
+
+const BLOCKED_LIFECYCLE_METHODS = new Set(["onStart", "onStop", "onMessage", "onRequest"]);
+
+// Error messages for fatal bind errors
+const BIND_ERROR_MESSAGES = {
+  EPERM: (port) => `Permission denied binding to port ${port}. Run with elevated privileges or use a port >= 1024.`,
+  EACCES: (port) => `Access denied binding to port ${port}. Run with elevated privileges or use a port >= 1024.`,
+  EADDRNOTAVAIL: (port) => `Cannot bind to port ${port}. Address not available (restricted environment or invalid configuration).`,
+  EADDRINUSE: (port) => `Port ${port} is already in use. Stop the conflicting process or choose a different port.`,
+};
+
+/**
+ * S1: Validate HMAC-SHA256 internal signature.
+ * Replaces FORGE_INTERNAL_AUTH_BYPASS with per-request HMAC validation.
+ */
+function validateInternalSignature(req, method, path) {
+  const secret = process.env.FORGE_INTERNAL_SECRET;
+  if (!secret) {
+    // In development, allow without signature; in production, reject
+    return process.env.NODE_ENV !== 'production';
+  }
+  const sig = req.headers['x-forge-internal-sig'];
+  const ts = req.headers['x-forge-internal-ts'];
+  if (!sig || !ts) return false;
+
+  // Replay protection: reject if timestamp is >30s old
+  const timestamp = parseInt(ts, 10);
+  if (Number.isNaN(timestamp)) return false;
+  const age = Math.abs(Date.now() - timestamp);
+  if (age > INTERNAL_SIG_MAX_AGE_MS) return false;
+
+  // HMAC-SHA256(secret, "METHOD:path:timestamp")
+  const expected = createHmac('sha256', secret)
+    .update(`${method}:${path}:${ts}`)
+    .digest('hex');
+
+  // Constant-time comparison
+  try {
+    const sigBuf = Buffer.from(sig, 'hex');
+    const expectedBuf = Buffer.from(expected, 'hex');
+    if (sigBuf.length !== expectedBuf.length) return false;
+    return timingSafeEqual(sigBuf, expectedBuf);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * S2: Verify a JWT token (HMAC-SHA256) using Node built-in crypto.
+ * Returns the decoded payload if valid, or null if invalid/expired.
+ */
+function verifyJwt(token) {
+  const secret = process.env.JWT_SECRET;
+  if (!secret || !token) return null;
+
+  // Strip "Bearer " prefix if present
+  const raw = token.startsWith('Bearer ') ? token.slice(7) : token;
+  const parts = raw.split('.');
+  if (parts.length !== 3) return null;
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // SEC-C1: Validate the JWT header — enforce HS256, reject alg:none and mismatches
+  try {
+    const header = JSON.parse(Buffer.from(headerB64, 'base64url').toString());
+    if (!header || typeof header !== 'object') return null;
+    const alg = (header.alg ?? '').toUpperCase();
+    if (alg === 'NONE' || (alg !== 'HS256' && alg !== '')) return null;
+  } catch {
+    return null;
+  }
+
+  // Verify signature
+  const expectedSig = createHmac('sha256', secret)
+    .update(`${headerB64}.${payloadB64}`)
+    .digest('base64url');
+
+  // Normalize base64url — strip trailing '=' padding for comparison
+  const normalizedSig = signatureB64.replace(/=+$/, '');
+  const normalizedExpected = expectedSig.replace(/=+$/, '');
+
+  if (normalizedSig.length !== normalizedExpected.length) return null;
+  try {
+    if (!timingSafeEqual(Buffer.from(normalizedSig), Buffer.from(normalizedExpected))) return null;
+  } catch {
+    return null;
+  }
+
+  // Decode payload
+  try {
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+    // Check expiration
+    if (payload.exp && Date.now() / 1000 > payload.exp) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A9: Shared auth check for internal forge endpoints.
+ * Returns { allowed: true } or { allowed: false, error, code }.
+ *
+ * S1: When FORGE_INTERNAL_SECRET is set, the HMAC signature check
+ *     (validateInternalSignature) already validated the caller service.
+ *     This function checks *user-level* auth on the target method.
+ *
+ * Backward compat: FORGE_INTERNAL_AUTH_BYPASS=true still skips the
+ * user-auth check entirely (same behavior as before).
+ */
+function checkForgeEndpointAuth(serviceInstance, method, rctx) {
+  // Legacy bypass — skip all user-auth checks if explicitly enabled
+  const internalAuthBypass = (process.env.FORGE_INTERNAL_AUTH_BYPASS ?? 'false') === 'true';
+  if (internalAuthBypass) return { allowed: true };
+
+  const invokeContract = getContract(serviceInstance?.constructor);
+  if (!invokeContract) return { allowed: true };
+
+  const methodMeta = invokeContract.methods.get(method);
+  const routeDef = invokeContract.routes.find(r => r.handlerName === method);
+  const authRequirement = routeDef?.auth ?? methodMeta?.options?.auth ?? invokeContract.auth;
+  if (!authRequirement || authRequirement === 'none') return { allowed: true };
+
+  // SEC-C1: Validate auth — 401 for missing, verify JWT signature when JWT_SECRET set
+  if (!rctx.auth) {
+    return { allowed: false, error: "Authentication required", code: 401 };
+  }
+
+  // When JWT_SECRET is set, require valid JWT signature — presence alone is not sufficient
+  if (process.env.JWT_SECRET) {
+    if (!rctx._rawAuthToken) {
+      return { allowed: false, error: "Authentication required — JWT token missing", code: 401 };
+    }
+    const verified = verifyJwt(rctx._rawAuthToken);
+    if (!verified) {
+      return { allowed: false, error: "Invalid or expired token", code: 401 };
+    }
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * ForgeContext
+ *
+ * Injected into every Service instance. Provides:
+ *  - HTTP router
+ *  - IPC messaging helpers (direct worker-to-worker when available)
+ *  - Metrics collection
+ *  - Structured logger
+ *  - Runtime metadata (service name, thread count, worker id, etc.)
+ */
+export class ForgeContext {
+  /**
+   * @param {Object} options
+   * @param {string} options.serviceName
+   * @param {number} options.port
+   * @param {number} options.workerId
+   * @param {number} options.threadCount
+   * @param {string} options.mode
+   * @param {string} options.serviceType - 'edge', 'internal', or 'background'
+   * @param {Function} options.sendIPC - Function to send IPC messages to supervisor
+   * @param {Function} [options.localSend] - Direct dispatch for colocated services
+   * @param {Function} [options.localRequest] - Direct request for colocated services
+   * @param {Array} [options.staticMounts] - Optional static mount descriptors for this service
+   */
+  constructor(options) {
+    this.serviceName = options.serviceName;
+    this.port = options.port;
+    this.workerId = options.workerId;
+    this.threadCount = options.threadCount;
+    this.mode = options.mode;
+    this.serviceType = options.serviceType ?? "internal";
+    this._sendIPC = options.sendIPC;
+    this._localSend = options.localSend ?? null;
+    this._localRequest = options.localRequest ?? null;
+    this._ingressConfig = options.ingress ?? {};
+    this._ingressApplied = false;
+    this._forgeProxy = options.forgeProxy ?? process.env.FORGE_PROXY_URL ?? null;
+    this._serviceInstance = null; // set by worker-bootstrap after service.onStart
+
+    // Port map for HTTP-based service calls: { serviceName: port }
+    try {
+      this._servicePorts = JSON.parse(process.env.FORGE_SERVICE_PORTS || "{}");
+    } catch {
+      this._servicePorts = {};
+    }
+
+    /** @type {import('./EndpointResolver.js').EndpointResolver | null} */
+    this._endpointResolver = null;
+
+    /** @type {Router} */
+    this.router = new Router();
+
+    /** @type {Logger} */
+    this.logger = new Logger(this.serviceName, this.workerId);
+
+    /** @type {Metrics} */
+    this.metrics = new PrometheusMetrics(this.serviceName, this.workerId);
+    this._staticMounts = options.staticMounts ?? [];
+    this._staticRegistry = new StaticMountRegistry(this._staticMounts);
+
+    /** @type {Set<WebSocket>} Active WebSocket connections */
+    this._wsConnections = new Set();
+    /** @type {Map<string, number>} H-SEC-2: Per-IP WebSocket connection counts */
+    this._wsPerIpCounts = new Map();
+    /** H-SEC-2: Max WebSocket connections per IP (configurable via FORGE_WS_MAX_PER_IP) */
+    this._wsMaxPerIp = parseInt(process.env.FORGE_WS_MAX_PER_IP || '100', 10) || 100;
+    /** @type {Map<string, Function>} WebSocket route handlers */
+    this._wsHandlers = new Map();
+    /** @type {Array<{name: string, onWsUpgrade?: Function, onWsConnect?: Function, onWsMessage?: Function, onWsClose?: Function}>} */
+    this._wsPluginHooks = [];
+
+    /**
+     * Direct channel manager — handles MessagePort connections
+     * to other services, bypassing the supervisor for all
+     * inter-service communication.
+     * @type {WorkerChannelManager}
+     */
+    this.channels = new WorkerChannelManager(this.serviceName, this.workerId);
+    this.channels.init(this._sendIPC);
+
+    /** @private */
+    this._server = null;
+
+    // Compute once whether this service needs an HTTP server
+    const isEdge = this.serviceType === "edge" && this.port > 0;
+    const isMultiMachine = process.env.FORGE_REGISTRY_MODE && process.env.FORGE_REGISTRY_MODE !== "embedded";
+    let hasRemoteEndpoints = false;
+    try {
+      const eps = JSON.parse(process.env.FORGE_SERVICE_ENDPOINTS || "{}");
+      hasRemoteEndpoints = Object.values(eps).some((ep) => (Array.isArray(ep) ? ep.some((e) => e.remote) : ep?.remote));
+    } catch {}
+    this._needsHttpServer = isEdge || ((isMultiMachine || hasRemoteEndpoints) && this.port > 0);
+
+    /** @private - active request counter for graceful shutdown */
+    this._activeRequests = 0;
+
+    /** @private - message handlers for supervisor IPC request/response (legacy) */
+    this._messageHandlers = new Map();
+  }
+
+  setStaticMounts(mounts = []) {
+    this._staticMounts = mounts;
+    this._staticRegistry.setMounts(mounts);
+  }
+
+  /**
+   * Send a message to another service.
+   *
+   * Resolution order:
+   *   1. Local dispatch (colocated service in same process) — zero overhead
+   *   2. Direct UDS connection — bypasses supervisor
+   *   3. Supervisor IPC fallback — only during startup
+   */
+  async send(target, payload) {
+    // Try colocated first (direct function call, no serialization)
+    if (this._localSend?.(target, payload)) {
+      return;
+    }
+    // Fall through to UDS / supervisor IPC
+    this.channels.send(target, payload);
+  }
+
+  /**
+   * Broadcast to all workers of a target service.
+   * Note: channels.broadcast delivers to all workers including local via UDS.
+   * We only use _localSend for colocated services that share this process
+   * (no UDS needed), then broadcast to remote workers via channels.
+   */
+  async broadcast(target, payload) {
+    // Local colocated dispatch (same process, direct call)
+    const sentLocally = this._localSend?.(target, payload);
+    // UDS broadcast to all OTHER workers (channels excludes self)
+    this.channels.broadcast(target, payload);
+  }
+
+  /**
+   * Send a request to another service and await a response.
+   *
+   * If the target is colocated, this is a direct async function call
+   * with zero serialization overhead.
+   */
+  async request(target, payload, timeoutMs = 5000) {
+    // Try colocated first
+    if (this._localRequest) {
+      const result = await this._localRequest(target, payload);
+      if (result !== NOT_HANDLED) return result;
+    }
+    // Fall through to UDS / supervisor IPC
+    return this.channels.request(target, payload, timeoutMs);
+  }
+
+  /**
+   * Start the HTTP server for this service.
+   */
+  async startServer() {
+    // Auto-apply ingress protection for edge services (when no ForgeProxy)
+    if (this.serviceType === "edge" && !this._ingressApplied && !this._forgeProxy) {
+      this.ingress = new IngressProtection(this._ingressConfig ?? {});
+      this.router.use(this.ingress.middleware());
+      this._ingressApplied = true;
+    }
+
+    // ── S7: Prometheus metrics endpoint with optional auth ──
+    this.router.get("/metrics", (_req, res) => {
+      const metricsToken = process.env.FORGE_METRICS_TOKEN;
+      if (metricsToken) {
+        const auth = _req.headers['authorization'];
+        const expected = `Bearer ${metricsToken}`;
+        if (!auth || auth.length !== expected.length ||
+            !timingSafeEqual(Buffer.from(auth), Buffer.from(expected))) {
+          res.json({ error: "Unauthorized" }, 401);
+          return;
+        }
+      }
+      res.writeHead(200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+      res.end(this.metrics.expose());
+    });
+
+    // ── ForgeProxy invoke endpoint ──
+    this.router.post("/__forge/invoke", async (req, res) => {
+      const remote = req.socket?.remoteAddress ?? "";
+      if (!isPrivateNetwork(remote)) {
+        res.json({ error: "Invoke endpoint not externally accessible" }, 403);
+        return;
+      }
+
+      // S1: Validate internal HMAC signature (replaces FORGE_INTERNAL_AUTH_BYPASS)
+      if (!validateInternalSignature(req, req.method, "/__forge/invoke")) {
+        res.json({ error: "Invalid internal signature" }, 403);
+        return;
+      }
+
+      const ct = (req.headers["content-type"] ?? "").toLowerCase();
+      if (!ct.startsWith("application/json")) {
+        res.json({ error: "Content-Type must be application/json" }, 415);
+        return;
+      }
+
+      const method = req.body?.method ?? req.headers["x-forge-method"];
+      const args = req.body?.args ?? [];
+      const params = req.body?.params ?? {};
+
+      // Strip x-forge-* headers — invoke endpoint should not trust propagation
+      // headers from the network; use explicit body fields instead
+      const safeHeaders = { ...req.headers };
+      delete safeHeaders["x-forge-auth"];
+      delete safeHeaders["x-forge-tenant"];
+      delete safeHeaders["x-forge-user"];
+      delete safeHeaders["x-forge-deadline"];
+
+      const rctx = req.ctx ?? RequestContext.fromPropagation(safeHeaders);
+      rctx.service = this.serviceName;
+      rctx.method = method;
+
+      if (rctx.deadline && Date.now() >= rctx.deadline) {
+        res.writeHead(504, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "Request deadline exceeded" }));
+        return;
+      }
+
+      if (!method) {
+        res.json({ error: "Missing method" }, 400);
+        return;
+      }
+
+      if (!this._isMethodAllowed(method)) {
+        res.json({ error: `Method "${method}" is not exposed` }, 403);
+        return;
+      }
+
+      // A9: Deduplicated auth check
+      const authResult = checkForgeEndpointAuth(this._serviceInstance, method, rctx);
+      if (!authResult.allowed) {
+        res.json({ error: authResult.error }, authResult.code);
+        return;
+      }
+
+      const handler = this._serviceInstance?.[method];
+      if (typeof handler !== "function") {
+        res.json({ error: `No method "${method}"` }, 404);
+        return;
+      }
+
+      // Execute within RequestContext so all downstream calls inherit it
+      const result = await RequestContext.run(rctx, async () => {
+        try {
+          const data = args.length > 0 ? args : [params];
+          const result = await handler.call(this._serviceInstance, ...data);
+          return { result };
+        } catch (err) {
+          const code = err.statusCode ?? 500;
+          if (code >= 500) {
+            this.logger.error("Invoke handler error", { method, error: err.message });
+          }
+          return { error: code >= 500 ? "Internal server error" : err.message, _code: code };
+        }
+      });
+
+      if (result.error) {
+        res.json({ error: result.error }, result._code);
+      } else {
+        res.json(result);
+      }
+    });
+
+    // ── Internal-only invoke (same protocol, for service-to-service HTTP) ──
+    this.router.post("/__forge/internal", async (req, res) => {
+      const remote = req.socket?.remoteAddress ?? "";
+      if (!isPrivateNetwork(remote)) {
+        res.json({ error: "Internal endpoint — not externally accessible" }, 403);
+        return;
+      }
+
+      // S1: Validate internal HMAC signature
+      if (!validateInternalSignature(req, req.method, "/__forge/internal")) {
+        res.json({ error: "Invalid internal signature" }, 403);
+        return;
+      }
+
+      const method = req.body?.method;
+      const args = req.body?.args ?? [];
+
+      // Extract propagation data BEFORE stripping __forge_* fields
+      const propagation = {};
+      if (req.body && typeof req.body === "object") {
+        for (const key of Object.keys(req.body)) {
+          if (key.startsWith("__forge_")) {
+            propagation[key] = req.body[key];
+            delete req.body[key];
+          }
+        }
+      }
+
+      // Reconstruct RequestContext from extracted propagation data
+      const rctx = RequestContext.fromPropagation(propagation);
+      rctx.service = this.serviceName;
+      rctx.method = method;
+
+      if (rctx.deadline && Date.now() >= rctx.deadline) {
+        res.writeHead(504, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "Request deadline exceeded" }));
+        return;
+      }
+
+      if (!this._isMethodAllowed(method)) {
+        res.json({ error: `Method "${method}" is not exposed` }, 403);
+        return;
+      }
+
+      // A9: Deduplicated auth check
+      const authResult = checkForgeEndpointAuth(this._serviceInstance, method, rctx);
+      if (!authResult.allowed) {
+        res.json({ error: authResult.error }, authResult.code);
+        return;
+      }
+
+      const handler = this._serviceInstance?.[method];
+      if (typeof handler !== "function") {
+        res.json({ error: `No internal method "${method}"` }, 404);
+        return;
+      }
+
+      const result = await RequestContext.run(rctx, async () => {
+        try {
+          return { result: await handler.call(this._serviceInstance, ...args) };
+        } catch (err) {
+          const code = err.statusCode ?? 500;
+          if (code >= 500) {
+            this.logger.error("Internal invoke handler error", { method, error: err.message });
+          }
+          return { error: code >= 500 ? "Internal server error" : err.message, _code: code };
+        }
+      });
+
+      if (result.error) {
+        res.json({ error: result.error }, result._code);
+      } else {
+        res.json(result);
+      }
+    });
+
+    // ── Cross-machine event delivery endpoint ──
+    this.router.post("/__forge/event", async (req, res) => {
+      const remote = req.socket?.remoteAddress ?? "";
+      if (!isPrivateNetwork(remote)) {
+        res.json({ error: "Event endpoint — not externally accessible" }, 403);
+        return;
+      }
+
+      // S1: Validate internal HMAC signature
+      if (!validateInternalSignature(req, req.method, "/__forge/event")) {
+        res.json({ error: "Invalid internal signature" }, 403);
+        return;
+      }
+
+      const { from, event, data } = req.body ?? {};
+      if (!from || !event) {
+        res.json({ error: "Missing from or event" }, 400);
+        return;
+      }
+
+      // Check auth from propagation context (backward compat with FORGE_INTERNAL_AUTH_BYPASS)
+      const internalAuthBypass = (process.env.FORGE_INTERNAL_AUTH_BYPASS ?? 'false') === 'true';
+      if (internalAuthBypass && process.env.NODE_ENV === 'production') {
+        // M-SEC-4: Warn when auth bypass is used in production
+        this.logger.warn('FORGE_INTERNAL_AUTH_BYPASS is enabled in production — event auth is disabled');
+      }
+      if (!internalAuthBypass) {
+        const propagation = {};
+        if (req.body && typeof req.body === "object") {
+          for (const key of Object.keys(req.body)) {
+            if (key.startsWith("__forge_")) {
+              propagation[key] = req.body[key];
+            }
+          }
+        }
+        const rctx = RequestContext.fromPropagation(propagation);
+        if (!rctx.auth) {
+          res.json({ error: "Authentication required" }, 401);
+          return;
+        }
+        // SEC-C3: When JWT_SECRET is set, verify signature — not just auth presence
+        if (process.env.JWT_SECRET) {
+          const rawToken = propagation.__forge_auth_token ?? req.headers['authorization'];
+          const verified = rawToken ? verifyJwt(rawToken) : null;
+          if (!verified) {
+            res.json({ error: "Invalid or expired token" }, 401);
+            return;
+          }
+        }
+      }
+
+      // Dispatch as a standard forge event — autoWireSubscriptions
+      // already patches onMessage to route __forge_event payloads
+      const payload = { __forge_event: event, __forge_data: data };
+
+      try {
+        if (this._serviceInstance?.onMessage) {
+          await this._serviceInstance.onMessage(from, payload);
+        }
+        res.json({ ok: true });
+      } catch (err) {
+        this.logger.error("Event handler error", { from, event, error: err.message });
+        res.json({ error: "Internal server error" }, 500);
+      }
+    });
+
+    return new Promise((resolve, reject) => {
+      this._server = createServer((req, res) => {
+        const start = performance.now();
+
+        // H8: Validate HTTP method early
+        if (!VALID_METHODS.has(req.method)) {
+          res.writeHead(405, { "Content-Type": "application/json", "Allow": "GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS" });
+          res.end(JSON.stringify({ error: "Method Not Allowed" }));
+          return;
+        }
+
+        // H11: Strip internal forge headers from external requests BEFORE body parsing
+        // L-SEC-1: Also strip internal signature/timestamp headers for defense-in-depth
+        const remoteAddrEarly = req.socket?.remoteAddress ?? "";
+        if (!isPrivateNetwork(remoteAddrEarly)) {
+          delete req.headers["x-forge-auth"];
+          delete req.headers["x-forge-tenant"];
+          delete req.headers["x-forge-user"];
+          delete req.headers["x-forge-deadline"];
+          delete req.headers["x-forge-internal-sig"];
+          delete req.headers["x-forge-internal-ts"];
+        }
+
+        if (["POST", "PUT", "PATCH"].includes(req.method)) {
+          const ct = (req.headers["content-type"] ?? "").toLowerCase();
+          if (
+            ct &&
+            !ct.includes("application/json") &&
+            !ct.includes("text/") &&
+            !ct.includes("multipart/form-data") &&
+            !ct.includes("application/x-www-form-urlencoded")
+          ) {
+            res.writeHead(415, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Unsupported media type" }));
+            return;
+          }
+          // Early Content-Length check — reject oversized requests without reading body
+          const declaredLength = req.headers["content-length"];
+          if (declaredLength != null) {
+            const cl = parseInt(declaredLength, 10);
+            if (!Number.isNaN(cl) && cl > MAX_BODY_SIZE) {
+              res.writeHead(413, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Request body too large" }));
+              req.destroy();
+              return;
+            }
+          }
+          // P7: Collect chunks in array, single Buffer.concat at end
+          const chunks = [];
+          let bodySize = 0;
+          let rejected = false;
+          // S11: Reduced body timeout from 30s to 10s
+          const bodyTimeout = setTimeout(() => {
+            if (rejected) return;
+            rejected = true;
+            if (!res.headersSent) {
+              res.writeHead(408, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Request Timeout" }));
+            }
+            req.destroy();
+          }, BODY_TIMEOUT_MS);
+          req.on("data", (chunk) => {
+            if (rejected) return;
+            bodySize += chunk.length;
+            if (bodySize > MAX_BODY_SIZE) {
+              rejected = true;
+              clearTimeout(bodyTimeout);
+              if (!res.headersSent) {
+                res.writeHead(413, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Request body too large" }));
+              }
+              req.destroy();
+              return;
+            }
+            chunks.push(chunk);
+          });
+          req.on("end", () => {
+            clearTimeout(bodyTimeout);
+            if (rejected) return;
+            const body = Buffer.concat(chunks).toString("utf-8");
+            // Only JSON.parse when content-type is application/json or absent (backward compat)
+            if (!ct || ct.includes("application/json")) {
+              try {
+                req.body = body ? JSON.parse(body, (key, value) => {
+                  if (key === '__proto__' || key === 'constructor' || key === 'prototype') return undefined;
+                  return value;
+                }) : {};
+              } catch {
+                // For internal forge endpoints, return 400 on malformed JSON
+                const urlPath = new URL(req.url, "http://localhost").pathname;
+                if (urlPath.startsWith("/__forge/")) {
+                  if (!res.headersSent) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Invalid JSON body" }));
+                  }
+                  return;
+                }
+                // Fall back to raw string for user routes
+                req.body = body;
+              }
+            } else {
+              req.body = body;
+            }
+            this._handleRequest(req, res, start);
+          });
+        } else {
+          req.body = {};
+          this._handleRequest(req, res, start);
+        }
+      });
+
+      // ── Client error handling ──
+      this._server.on("clientError", (err, socket) => {
+        this.logger.error("Client error", { error: err.message, code: err.code });
+        if (socket && !socket.destroyed) {
+          socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+          socket.destroy();
+        }
+      });
+
+      // ── WebSocket upgrade handling ──
+      this._server.on("upgrade", (req, socket, head) => {
+        this._handleWsUpgrade(req, socket, head).catch((err) => {
+          this.logger.error("WebSocket upgrade failed", { error: err.message, path: req.url });
+          if (!socket.destroyed) {
+            try {
+              socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n");
+            } catch {}
+            socket.destroy();
+          }
+        });
+      });
+
+      // Set request timeouts to prevent slowloris attacks
+      this._server.timeout = 30000;
+      this._server.requestTimeout = 30000;
+      this._server.headersTimeout = 10000;
+
+      this._server.listen(this.port, () => {
+        // Reduce startup noise in multi-worker mode.
+        if (this.workerId === 0) {
+          this.logger.info(`Listening on port ${this.port}`);
+        }
+
+        // Auto-register with ForgeProxy if configured
+        if (this._forgeProxy) {
+          this._registerWithForgeProxy().catch((err) => {
+            this.logger.warn(`ForgeProxy registration failed: ${err.message}`);
+          });
+        }
+
+        resolve();
+      });
+
+      this._server.on("error", (err) => {
+        // Detect fatal bind errors that should not trigger restart loops
+        const isFatalBindError =
+          err.code === "EPERM" ||
+          err.code === "EACCES" ||
+          err.code === "EADDRNOTAVAIL" ||
+          err.code === "EADDRINUSE";
+
+        if (isFatalBindError) {
+          // Notify supervisor this is a fatal error — don't restart
+          if (this._sendIPC) {
+            this._sendIPC({
+              type: "forge:fatal-error",
+              error: err.code,
+              message: err.message,
+              port: this.port,
+            });
+          }
+
+          // Augment error with clear message using constant map
+          const messageGenerator = BIND_ERROR_MESSAGES[err.code];
+          err.fatalBindError = true;
+          err.userMessage = messageGenerator
+            ? messageGenerator(this.port)
+            : `Failed to bind to port ${this.port}: ${err.message}`;
+        }
+
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Route an incoming HTTP request.
+   * Creates a RequestContext that flows through the entire call chain.
+   */
+  _handleRequest(req, res, start) {
+    this._activeRequests++;
+    res.on("close", () => this._activeRequests--);
+
+    // Convenience methods on response
+    res.json = (data, statusCode = 200) => {
+      if (res.headersSent) return;
+      let body;
+      try {
+        body = JSON.stringify(data);
+      } catch {
+        body = JSON.stringify({ error: "Response serialization failed" });
+        statusCode = 500;
+      }
+      const len = Buffer.byteLength(body);
+      res.writeHead(statusCode, { "Content-Type": "application/json", "Content-Length": len });
+      res.end(body);
+    };
+
+    res.status = (code) => {
+      res.statusCode = code;
+      return res;
+    };
+
+    // ── Build RequestContext from incoming headers ──
+    // Note: internal forge headers already stripped in createServer callback (H11)
+    const remoteAddr = req.socket?.remoteAddress ?? "";
+
+    const rctx = RequestContext.fromPropagation(req.headers);
+    rctx.service = this.serviceName;
+
+    // Security headers
+    res.setHeader("X-Frame-Options", "DENY");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+    // HSTS should only be sent over HTTPS (RFC 6797 § 7.2)
+    // Only trust x-forwarded-proto from trusted proxies (FORGE_TRUSTED_PROXIES), not just any private network
+    if (req.socket?.encrypted || (isTrustedProxy(remoteAddr) && req.headers["x-forwarded-proto"] === "https")) {
+      res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+    }
+
+    // Always set the correlation ID response header
+    res.setHeader("x-correlation-id", rctx.correlationId);
+    res.setHeader("x-trace-id", rctx.traceId);
+
+    // In host mode, propagate project ID to the request context
+    rctx._projectId ??= this._projectId;
+
+    // Attach context to request for handlers to use
+    req.ctx = rctx;
+    req.auth = rctx.auth;
+    req.tenantId = rctx.tenantId;
+    req.projectId = rctx.projectId;
+    req.userId = rctx.userId;
+    req.correlationId = rctx.correlationId;
+
+    this.metrics.httpRequestStart();
+
+    const matched = this.router.match(req.method, req.url);
+
+    if (!matched) {
+      this._tryServeStatic(req, res, start)
+        .then((served) => {
+          if (served) return;
+          this.metrics.httpRequestEnd((performance.now() - start) / 1000, {
+            method: req.method,
+            route: "unmatched",
+            status: 404,
+          });
+          res.json({ error: "Not Found" }, 404);
+        })
+        .catch((err) => {
+          this.logger.error("Static serve failure", {
+            error: err.message,
+            url: req.url,
+          });
+          if (!res.headersSent) {
+            res.json({ error: "Internal server error" }, 500);
+          }
+        });
+      return;
+    }
+
+    req.params = matched.params;
+    req.query = matched.query;
+
+    // HEAD responses MUST NOT include a message body (RFC 7231 § 4.3.2)
+    if (req.method === "HEAD") {
+      const origEnd = res.end.bind(res);
+      res.end = (chunk, encoding, callback) => origEnd(null, encoding, callback);
+      res.write = () => true;
+    }
+
+    // Execute middleware chain + handler INSIDE RequestContext
+    const handlers = [...this.router.middleware, matched.handler];
+    let i = 0;
+
+    const next = (err) => {
+      if (err) {
+        this.logger.error("Request error", {
+          error: err.message,
+          url: req.url,
+          ...rctx.toLogFields(),
+        });
+        if (!res.headersSent) {
+          const status = err.statusCode || 500;
+          const message = status >= 500 ? "Internal server error" : (err.message || "Internal error");
+          res.json({ error: message }, status);
+        }
+        return;
+      }
+
+      const handler = handlers[i++];
+      if (!handler) return;
+
+      let stepCalled = false;
+      const stepNext = (stepErr) => {
+        if (stepCalled) return;
+        stepCalled = true;
+        next(stepErr);
+      };
+
+      try {
+        const result = handler(req, res, stepNext);
+        if (result && typeof result.catch === "function") {
+          result.catch(stepNext);
+        }
+      } catch (e) {
+        stepNext(e);
+      }
+    };
+
+    // Run entire handler chain within the RequestContext.
+    // AsyncLocalStorage.run() properly propagates through the entire async chain,
+    // including middleware that does `await next()` followed by post-next work.
+    RequestContext.run(rctx, () => next());
+
+    // Track metrics on response finish
+    const onFinish = () => {
+      const duration = (performance.now() - start) / 1000;
+      const labels = {
+        method: req.method,
+        route: matched.pattern,
+        status: res.statusCode,
+      };
+      if (rctx.tenantId) labels.tenant_id = rctx.tenantId;
+      if (rctx.projectId) labels.project_id = rctx.projectId;
+
+      this.metrics.httpRequestEnd(duration, labels);
+      res.removeListener("finish", onFinish);
+    };
+    res.on("finish", onFinish);
+  }
+
+  async _tryServeStatic(req, res, start) {
+    if (!this._staticMounts || this._staticMounts.length === 0) return false;
+    if (req.method !== "GET" && req.method !== "HEAD") return false;
+
+    const hostHeader = (req.headers.host ?? "").toLowerCase();
+    const host = hostHeader.includes(":") ? hostHeader.split(":")[0] : hostHeader;
+    const pathname = new URL(req.url, "http://localhost").pathname;
+    const mount = this._staticRegistry.resolve(host, pathname);
+    if (!mount) return false;
+
+    const resolved = this._resolveStaticFile(mount.dir, mount.relativePath);
+    if (!resolved.ok) {
+      this.metrics.httpRequestEnd((performance.now() - start) / 1000, {
+        method: req.method,
+        route: `static:${mount.siteId ?? "unknown"}`,
+        status: 403,
+      });
+      res.json({ error: "Forbidden" }, 403);
+      return true;
+    }
+
+    let filePath = await this._resolveExistingStaticFile(resolved.filePath);
+    if (!filePath && mount.spaFallback && !pathname.startsWith("/api/")) {
+      filePath = await this._resolveExistingStaticFile(path.resolve(mount.dir, "index.html"));
+    }
+    if (!filePath) return false;
+
+    const stat = await fs.promises.stat(filePath);
+    if (!stat.isFile()) return false;
+
+    const extension = path.extname(filePath).toLowerCase();
+    const contentType = EXTENSION_TO_MIME[extension] ?? "application/octet-stream";
+    const cacheControl = this._staticCacheControl(mount, filePath);
+    const routeLabel = `static:${mount.siteId ?? "unknown"}`;
+
+    res.setHeader("Content-Type", contentType);
+    res.setHeader("Content-Length", stat.size);
+    res.setHeader("Cache-Control", cacheControl);
+
+    const finishMetrics = () => {
+      this.metrics.httpRequestEnd((performance.now() - start) / 1000, {
+        method: req.method,
+        route: routeLabel,
+        status: res.statusCode || 200,
+      });
+      res.removeListener("finish", finishMetrics);
+    };
+    res.on("finish", finishMetrics);
+
+    if (req.method === "HEAD") {
+      res.writeHead(200);
+      res.end();
+      return true;
+    }
+
+    await new Promise((resolve, reject) => {
+      const stream = fs.createReadStream(filePath);
+      stream.on("error", reject);
+      stream.on("open", () => {
+        if (!res.headersSent) res.writeHead(200);
+      });
+      stream.on("end", resolve);
+      stream.pipe(res);
+    });
+
+    return true;
+  }
+
+  _resolveStaticFile(rootDir, requestPath) {
+    const normalizedRoot = path.resolve(rootDir);
+    let decodedPath;
+    try {
+      decodedPath = decodeURIComponent(requestPath || "/");
+    } catch {
+      return { ok: false, filePath: null };
+    }
+
+    const normalized = path.posix.normalize(decodedPath.startsWith("/") ? decodedPath : `/${decodedPath}`);
+    const absolute = path.resolve(normalizedRoot, `.${normalized}`);
+
+    if (absolute !== normalizedRoot && !absolute.startsWith(`${normalizedRoot}${path.sep}`)) {
+      return { ok: false, filePath: null };
+    }
+
+    return { ok: true, filePath: absolute };
+  }
+
+  async _resolveExistingStaticFile(filePath) {
+    try {
+      const stat = await fs.promises.stat(filePath);
+      if (stat.isFile()) return filePath;
+      if (stat.isDirectory()) {
+        const indexPath = path.join(filePath, "index.html");
+        const indexStat = await fs.promises.stat(indexPath);
+        if (indexStat.isFile()) return indexPath;
+      }
+    } catch {}
+    return null;
+  }
+
+  _staticCacheControl(mount, filePath) {
+    if (mount.cachePolicy === "none") return "no-store";
+    if (mount.cachePolicy === "immutable") return "public, max-age=31536000, immutable";
+
+    const base = path.basename(filePath);
+    if (/[.-][a-f0-9]{8,}\./i.test(base)) {
+      return "public, max-age=31536000, immutable";
+    }
+    return "public, max-age=300";
+  }
+
+  /**
+   * Wire message/request handlers to both the direct channel manager
+   * AND the supervisor fallback IPC path.
+   */
+  _wireMessageHandlers() {
+    // Direct channel path (primary — used once ports are established)
+    this.channels.onMessage = (from, payload) => {
+      if (this._onMessage) this._onMessage(from, payload);
+    };
+    this.channels.onRequest = (from, payload) => {
+      if (this._onRequest) return this._onRequest(from, payload);
+      return null;
+    };
+  }
+
+  /**
+   * Handle an incoming IPC message from the supervisor.
+   * This is the FALLBACK path — only used during startup before
+   * direct MessagePorts are established, and for supervisor-level
+   * commands (health checks, shutdown, etc.)
+   */
+  _handleIPCMessage(msg) {
+    if (!msg || !msg.type) return;
+
+    // Supervisor-level messages
+    if (msg.type === "forge:health-check") {
+      this._sendIPC({
+        type: "forge:health-response",
+        timestamp: msg.timestamp,
+        uptime: process.uptime(),
+        memory: process.memoryUsage(),
+        pid: process.pid,
+      });
+      return;
+    }
+
+    // Fallback message routing (before direct ports are ready)
+    if (msg.type === "forge:message" && this._onMessage) {
+      this._onMessage(msg.from, msg.payload);
+    }
+
+    if (msg.type === "forge:request" && this._onRequest) {
+      Promise.resolve(this._onRequest(msg.from, msg.payload))
+        .then((result) => {
+          this._sendIPC({
+            type: "forge:response",
+            requestId: msg.requestId,
+            payload: result,
+            error: null,
+          });
+        })
+        .catch((err) => {
+          this._sendIPC({
+            type: "forge:response",
+            requestId: msg.requestId,
+            payload: null,
+            error: err.message,
+          });
+        });
+    }
+
+    if (msg.type === "forge:response") {
+      const handler = this._messageHandlers.get(msg.requestId);
+      if (handler) handler(msg);
+    }
+  }
+
+  _isMethodAllowed(method) {
+    if (!method || typeof method !== "string") return false;
+    if (method.startsWith("_")) return false;
+    if (BLOCKED_LIFECYCLE_METHODS.has(method)) return false;
+
+    const ServiceClass = this._serviceInstance?.constructor;
+    if (!ServiceClass) return false;
+
+    const contract = getContract(ServiceClass);
+    if (!contract) return false;
+
+    return contract.methods.has(method);
+  }
+
+  /**
+   * Gracefully shut down.
+   */
+  async stop() {
+    // Close direct channels
+    this.channels.destroy();
+
+    // Close all active WebSocket connections and clean up timers
+    for (const ws of this._wsConnections) {
+      if (ws._closeTimer) { clearTimeout(ws._closeTimer); ws._closeTimer = null; }
+      if (ws._pingTimer) { clearInterval(ws._pingTimer); ws._pingTimer = null; }
+      if (!ws._closed) {
+        ws._closed = true;
+      }
+      if (!ws.socket.destroyed) {
+        ws.socket.destroy();
+      }
+    }
+    this._wsConnections.clear();
+
+    if (this._server) {
+      // Deregister from ForgeProxy on shutdown
+      if (this._forgeProxy) {
+        try {
+          const data = JSON.stringify({
+            service: this.serviceName,
+            host: this._getHost(),
+            port: this.port,
+          });
+          const url = new URL(`${this._forgeProxy}/deregister`);
+          await fetch(url, { method: "POST", body: data, headers: { "Content-Type": "application/json" } }).catch(
+            () => {},
+          );
+        } catch {}
+      }
+
+      return new Promise((resolve) => {
+        let drainInterval = null;
+
+        // Stop accepting new connections and terminate idle keep-alive sockets
+        this._server.close(() => {
+          if (drainInterval) clearInterval(drainInterval);
+          resolve();
+        });
+        // Force-close idle keep-alive connections (Node 18.2+)
+        if (typeof this._server.closeAllConnections === 'function') {
+          // Wait briefly for in-flight requests, then force-close
+          const drainStart = Date.now();
+          drainInterval = setInterval(() => {
+            if (this._activeRequests <= 0 || Date.now() - drainStart >= 5000) {
+              clearInterval(drainInterval);
+              drainInterval = null;
+              this._server.closeAllConnections();
+            }
+          }, 50);
+          drainInterval.unref();
+        }
+      });
+    }
+  }
+
+  // ── WebSocket Support ──
+
+  /**
+   * Register a WebSocket handler for a path.
+   *
+   *   ctx.ws('/ws', (socket, req) => {
+   *     socket.on('message', (data) => {
+   *       const msg = JSON.parse(data);
+   *       // req.ctx has the RequestContext with auth, correlationId
+   *       socket.send(JSON.stringify({ echo: msg }));
+   *     });
+   *   });
+   */
+  ws(path, handlerOrOptions, maybeHandler) {
+    let handler, options;
+    if (typeof handlerOrOptions === 'function') {
+      handler = handlerOrOptions;
+      options = {};
+    } else {
+      options = handlerOrOptions ?? {};
+      handler = maybeHandler;
+    }
+    // S8: WebSocket endpoints require auth by default
+    if (options.auth === undefined) {
+      options.auth = 'required';
+    }
+    this._wsHandlers.set(path, { handler, options });
+  }
+
+  /**
+   * Write a short HTTP response over a raw upgrade socket and close it.
+   *
+   * @param {import("node:net").Socket} socket
+   * @param {number} statusCode
+   * @param {string} reason
+   * @param {Record<string, string>} [headers]
+   */
+  _writeWsUpgradeError(socket, statusCode, reason, headers = {}) {
+    const statusText = String(reason || "Upgrade Rejected").replace(/[\r\n]/g, " ");
+    let response = `HTTP/1.1 ${statusCode} ${statusText}\r\n`;
+    for (const [key, value] of Object.entries(headers)) {
+      const safeKey = String(key).replace(/[\r\n:]/g, "");
+      const safeVal = String(value).replace(/[\r\n]/g, " ");
+      response += `${safeKey}: ${safeVal}\r\n`;
+    }
+    response += "\r\n";
+    socket.write(response);
+    socket.destroy();
+  }
+
+  /**
+   * Run websocket plugin hooks for a lifecycle stage.
+   *
+   * @param {"upgrade" | "connect" | "message" | "close"} stage
+   * @param {object} payload
+   */
+  async _runWsPluginHooks(stage, payload) {
+    const methodByStage = {
+      upgrade: "onWsUpgrade",
+      connect: "onWsConnect",
+      message: "onWsMessage",
+      close: "onWsClose",
+    };
+    const method = methodByStage[stage];
+    if (!method) return [];
+
+    const results = [];
+    for (const hook of this._wsPluginHooks) {
+      const fn = hook?.[method];
+      if (typeof fn !== "function") continue;
+      try {
+        const result = await fn(payload);
+        results.push({ plugin: hook.name, ok: true, result });
+      } catch (err) {
+        this.logger.warn(`WebSocket plugin hook failed`, {
+          plugin: hook.name,
+          stage,
+          error: err.message,
+        });
+        results.push({ plugin: hook.name, ok: false, error: err });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Handle HTTP→WebSocket upgrade.
+   * Implements RFC 6455 handshake without external dependencies.
+   */
+  async _handleWsUpgrade(req, socket, head) {
+    // H-SEC-2: Per-IP WebSocket connection limit to prevent file descriptor exhaustion
+    const wsRemoteAddr = req.socket?.remoteAddress ?? "unknown";
+    const currentCount = this._wsPerIpCounts.get(wsRemoteAddr) ?? 0;
+    if (currentCount >= this._wsMaxPerIp) {
+      socket.write("HTTP/1.1 429 Too Many Requests\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const entry = this._wsHandlers.get(url.pathname);
+
+    if (!entry) {
+      socket.destroy();
+      return;
+    }
+
+    const handler = typeof entry === 'function' ? entry : entry.handler;
+    const wsOptions = typeof entry === 'function' ? {} : (entry.options ?? {});
+
+    // S3: WebSocket Origin Validation — default deny
+    const allowedOrigins = wsOptions.allowedOrigins;
+    if (allowedOrigins && allowedOrigins.length > 0) {
+      // Explicit allowlist: check if '*' is included (opt-out of security)
+      if (!allowedOrigins.includes('*')) {
+        const origin = req.headers["origin"];
+        if (!origin || !allowedOrigins.includes(origin)) {
+          socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+          socket.destroy();
+          return;
+        }
+      }
+    } else {
+      // No allowedOrigins configured — default deny (reject cross-origin)
+      const origin = req.headers["origin"];
+      if (origin) {
+        // Compare origin host to request host
+        try {
+          const originHost = new URL(origin).host;
+          const reqHost = req.headers.host?.split(':')[0];
+          if (originHost !== reqHost && originHost !== req.headers.host) {
+            socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+            socket.destroy();
+            return;
+          }
+        } catch {
+          socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+          socket.destroy();
+          return;
+        }
+      }
+    }
+
+    // Strip internal forge headers from external WebSocket upgrades
+    let headers = req.headers;
+    const remoteAddr = req.socket?.remoteAddress ?? "";
+    if (!isPrivateNetwork(remoteAddr)) {
+      headers = { ...req.headers };
+      delete headers["x-forge-auth"];
+      delete headers["x-forge-tenant"];
+      delete headers["x-forge-user"];
+      delete headers["x-forge-deadline"];
+    }
+
+    const rctx = RequestContext.fromPropagation(headers);
+    rctx.service = this.serviceName;
+    rctx.method = `ws:${url.pathname}`;
+    req.ctx = rctx;
+    req.auth = rctx.auth;
+    req.tenantId = rctx.tenantId;
+
+    // S8: Enforce auth by default (auth defaults to 'required' from ws() method)
+    if (wsOptions.auth === 'required' && !rctx.auth) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+
+    const wsMeta = {
+      service: this.serviceName,
+      workerId: this.workerId,
+      path: url.pathname,
+      options: wsOptions,
+      requestContext: rctx,
+    };
+
+    const upgradeResults = await this._runWsPluginHooks("upgrade", {
+      req,
+      socket,
+      meta: wsMeta,
+    });
+    for (const res of upgradeResults) {
+      if (!res.ok) {
+        this._writeWsUpgradeError(socket, 503, "Service Unavailable");
+        return;
+      }
+      const decision = res.result;
+      if (decision === false || decision?.allow === false) {
+        this._writeWsUpgradeError(
+          socket,
+          decision?.statusCode ?? 403,
+          decision?.reason ?? "Forbidden",
+          decision?.headers ?? {},
+        );
+        return;
+      }
+    }
+
+    // M6: Validate Sec-WebSocket-Version (must be 13 per RFC 6455)
+    if (req.headers["sec-websocket-version"] !== "13") {
+      socket.write("HTTP/1.1 426 Upgrade Required\r\nSec-WebSocket-Version: 13\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+
+    // RFC 6455 handshake
+    const key = req.headers["sec-websocket-key"];
+    if (!key) {
+      socket.destroy();
+      return;
+    }
+
+    const accept = createHash("sha1").update(`${key}258EAFA5-E914-47DA-95CA-5AB4085B9976`).digest("base64");
+
+    const safeCorrelationId = (rctx.correlationId || '').replace(/[\r\n]/g, '');
+
+    socket.write(
+      "HTTP/1.1 101 Switching Protocols\r\n" +
+        "Upgrade: websocket\r\n" +
+        "Connection: Upgrade\r\n" +
+        `Sec-WebSocket-Accept: ${accept}\r\n` +
+        `X-Correlation-ID: ${safeCorrelationId}\r\n` +
+        "\r\n",
+    );
+
+    // Create a minimal WebSocket wrapper
+    const ws = new ForgeWebSocket(socket, rctx, wsOptions);
+
+    // H1: If _head buffer has data, prepend it so the first frame isn't lost
+    if (head && head.length > 0) {
+      ws._onData(head);
+    }
+    this._wsConnections.add(ws);
+    this.metrics.wsConnectionOpen();
+    // H-SEC-2: Track per-IP count
+    this._wsPerIpCounts.set(wsRemoteAddr, (this._wsPerIpCounts.get(wsRemoteAddr) ?? 0) + 1);
+
+    ws.on("close", () => {
+      this._wsConnections.delete(ws);
+      this.metrics.wsConnectionClose();
+      // H-SEC-2: Decrement per-IP count
+      const count = (this._wsPerIpCounts.get(wsRemoteAddr) ?? 1) - 1;
+      if (count <= 0) {
+        this._wsPerIpCounts.delete(wsRemoteAddr);
+      } else {
+        this._wsPerIpCounts.set(wsRemoteAddr, count);
+      }
+    });
+
+    ws.on("message", () => {
+      this.metrics.wsMessage("inbound");
+    });
+
+    ws.on("message", (message) => {
+      void this._runWsPluginHooks("message", {
+        ws,
+        req,
+        data: message,
+        meta: wsMeta,
+      });
+    });
+
+    ws.on("close", (code, reason) => {
+      void this._runWsPluginHooks("close", {
+        ws,
+        req,
+        code,
+        reason,
+        meta: wsMeta,
+      });
+    });
+
+    const connectResults = await this._runWsPluginHooks("connect", {
+      ws,
+      req,
+      meta: wsMeta,
+    });
+    for (const res of connectResults) {
+      if (!res.ok) {
+        try {
+          ws.close?.(1011, "Internal plugin error");
+        } catch {}
+        return;
+      }
+      const decision = res.result;
+      if (decision === false || decision?.allow === false) {
+        try {
+          ws.close?.(decision?.closeCode ?? 1008, decision?.closeReason ?? "Policy violation");
+        } catch {}
+        return;
+      }
+    }
+
+    // Run handler within RequestContext
+    RequestContext.run(rctx, () => handler(ws, req));
+  }
+
+  /**
+   * Register this service with ForgeProxy.
+   * ForgeProxy then routes external traffic to us.
+   */
+  async _registerWithForgeProxy() {
+    const contract = this._serviceInstance?.constructor?.contract;
+    const methods = contract?.expose ?? [];
+
+    const registration = {
+      service: this.serviceName,
+      host: this._getHost(),
+      port: this.port,
+      workers: this.threadCount,
+      methods,
+      health_endpoint: "/health",
+    };
+
+    const resp = await fetch(`${this._forgeProxy}/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(registration),
+    });
+
+    if (resp.ok) {
+      this.logger.info(`Registered with ForgeProxy at ${this._forgeProxy}`, {
+        methods: methods.length,
+      });
+    } else {
+      throw new Error(`ForgeProxy registration failed: ${resp.status}`);
+    }
+  }
+
+  _getHost() {
+    return process.env.FORGE_HOST ?? process.env.HOSTNAME ?? "127.0.0.1";
+  }
+}
+
+/**
+ * Simple pattern-matching HTTP router.
+ * P11: Includes a route matching cache.
+ */
+class Router {
+  constructor() {
+    /** @type {Map<string, Array>} Routes keyed by HTTP method */
+    this.routes = new Map();
+    this.middleware = [];
+    // P11: Route cache — URL→handler lookups
+    this._cache = new Map();
+  }
+
+  use(fn) {
+    this.middleware.push(fn);
+  }
+
+  get(pattern, handler) {
+    this._add("GET", pattern, handler);
+  }
+  post(pattern, handler) {
+    this._add("POST", pattern, handler);
+  }
+  put(pattern, handler) {
+    this._add("PUT", pattern, handler);
+  }
+  patch(pattern, handler) {
+    this._add("PATCH", pattern, handler);
+  }
+  delete(pattern, handler) {
+    this._add("DELETE", pattern, handler);
+  }
+
+  _add(method, pattern, handler) {
+    const paramNames = [];
+    const isWildcard = pattern.endsWith("/*");
+
+    // Count literal (non-param, non-wildcard) segments for specificity ranking
+    const segments = pattern.replace(/\/\*$/, "").split("/").filter(Boolean);
+    const literalCount = segments.filter((s) => !s.startsWith(":")).length;
+    const totalSegments = segments.length;
+
+    let base = isWildcard ? pattern.slice(0, -2) : pattern;
+    // Escape regex-special characters before replacing :param placeholders
+    const escaped = base.replace(/([.*+?^${}()|[\]\\])/g, "\\$1");
+    const regexStr = escaped.replace(/:(\w+)/g, (_, name) => {
+      paramNames.push(name);
+      return "([^/]+)";
+    });
+
+    if (paramNames.length > 10) {
+      throw new Error(`Route "${pattern}" has ${paramNames.length} params (max 10)`);
+    }
+
+    let regex;
+    if (isWildcard) {
+      regex = new RegExp(`^${regexStr}(?:/(.*))?$`);
+    } else {
+      regex = new RegExp(`^${regexStr}$`);
+    }
+
+    const route = { method, pattern, regex, paramNames, handler, isWildcard, literalCount, totalSegments };
+    if (!this.routes.has(method)) this.routes.set(method, []);
+    this.routes.get(method).push(route);
+
+    // Invalidate route cache when routes change
+    this._cache.clear();
+  }
+
+  _parseQuery(searchParams) {
+    const result = {};
+    for (const key of searchParams.keys()) {
+      if (key in result) continue; // already processed via getAll
+      const values = searchParams.getAll(key);
+      result[key] = values.length > 1 ? values : values[0];
+    }
+    return result;
+  }
+
+  _autoOptions(normalized, query) {
+    const methods = new Set();
+    for (const [method, bucket] of this.routes) {
+      for (const route of bucket) {
+        if (normalized.match(route.regex)) { methods.add(method); break; }
+      }
+    }
+    if (methods.size === 0) return null;
+
+    methods.add("OPTIONS");
+    if (methods.has("GET")) methods.add("HEAD");
+
+    const allow = [...methods].sort().join(", ");
+    return {
+      handler: (_req, res) => {
+        res.writeHead(204, { Allow: allow });
+        res.end();
+      },
+      params: {},
+      query,
+      pattern: "OPTIONS(auto)",
+    };
+  }
+
+  match(method, url) {
+    // H-SEC-1: Cache by method:pathname only (not full URL with query string).
+    // This prevents cache poisoning via unique query parameters while still
+    // providing the performance benefit of caching route matching.
+    // The query string is still passed to _matchUncached for parsing.
+    let pathname;
+    const qIdx = url.indexOf('?');
+    pathname = qIdx === -1 ? url : url.slice(0, qIdx);
+
+    const cacheKey = `${method}:${pathname}`;
+    const cached = this._cache.get(cacheKey);
+    if (cached !== undefined) {
+      // Re-parse query from original url for the cached result
+      if (cached) {
+        const query = qIdx === -1 ? {} : Object.fromEntries(new URL(url, "http://localhost").searchParams);
+        return { ...cached, query };
+      }
+      return cached;
+    }
+
+    const result = this._matchUncached(method, url);
+
+    // P11: Store in cache (evict 20% when full). Don't cache null (unmatched)
+    // to prevent attackers filling the cache with misses.
+    if (result !== null) {
+      if (this._cache.size >= ROUTE_CACHE_MAX) {
+        const deleteCount = Math.ceil(ROUTE_CACHE_MAX * 0.2);
+        const iter = this._cache.keys();
+        for (let i = 0; i < deleteCount; i++) {
+          const key = iter.next().value;
+          if (key !== undefined) this._cache.delete(key);
+        }
+      }
+      this._cache.set(cacheKey, result);
+    }
+    return result;
+  }
+
+  _matchUncached(method, url) {
+    const parsed = new URL(url, "http://localhost");
+    const pathname = parsed.pathname;
+
+    // Reject null bytes — path traversal / request smuggling vector
+    if (url.includes("\0")) return null;
+
+    // Normalize path to collapse encoded traversals (e.g. ..%2F)
+    let normalized = new URL(pathname, "http://localhost").pathname;
+    // Strip trailing slashes (except root "/")
+    if (normalized.length > 1 && normalized.endsWith('/')) {
+      normalized = normalized.slice(0, -1);
+    }
+    const query = this._parseQuery(parsed.searchParams);
+
+    // HEAD requests match GET routes (RFC 7231 § 4.3.2)
+    const isHead = method === "HEAD";
+    const effectiveMethod = isHead ? "GET" : method;
+
+    // Collect route buckets to search — only the relevant method(s)
+    const buckets = [];
+    if (this.routes.has(effectiveMethod)) buckets.push(this.routes.get(effectiveMethod));
+    if (isHead && this.routes.has("HEAD")) buckets.push(this.routes.get("HEAD"));
+
+    // Priority tiers: exact > parameterized > wildcard
+    let bestParam = null;
+    let bestParamScore = -1;
+    let bestWildcard = null;
+    let bestWildcardScore = -1;
+
+    for (const bucket of buckets) {
+      for (const route of bucket) {
+        const match = normalized.match(route.regex);
+        if (!match) continue;
+
+        const params = {};
+        let paramTraversal = false;
+        let decodeError = false;
+        route.paramNames.forEach((name, i) => {
+          let val;
+          try {
+            val = decodeURIComponent(match[i + 1]);
+          } catch {
+            decodeError = true;
+            return;
+          }
+          // Detect double-encoding by attempting further decodes (up to 2 iterations)
+          for (let d = 0; d < 2; d++) {
+            try {
+              const decoded = decodeURIComponent(val);
+              if (decoded === val) break;
+              val = decoded;
+            } catch { break; }
+          }
+          if (val.includes("..") || val.includes("\0") || val.includes("%00")) paramTraversal = true;
+          params[name] = val;
+        });
+        if (decodeError) return null;
+        if (paramTraversal) continue;
+
+        // Wildcard routes — lowest priority tier
+        if (route.isWildcard) {
+          const wildcardIndex = route.paramNames.length + 1;
+          params["*"] = match[wildcardIndex] ?? "";
+          params.wildcard = params["*"];
+
+          const score = route.literalCount * 1000 + route.totalSegments;
+          if (score > bestWildcardScore) {
+            bestWildcardScore = score;
+            bestWildcard = { handler: route.handler, params, query, pattern: route.pattern };
+          }
+          continue;
+        }
+
+        // Exact match (no params) — highest priority, return immediately
+        if (route.paramNames.length === 0) {
+          return { handler: route.handler, params, query, pattern: route.pattern };
+        }
+
+        // Parameterized route — pick the most specific
+        const score = route.literalCount * 1000 + route.totalSegments;
+        if (score > bestParamScore) {
+          bestParamScore = score;
+          bestParam = { handler: route.handler, params, query, pattern: route.pattern };
+        }
+      }
+    }
+
+    if (bestParam) return bestParam;
+    if (bestWildcard) return bestWildcard;
+
+    // Auto OPTIONS if no explicit handler matched
+    if (method === "OPTIONS") {
+      return this._autoOptions(normalized, query);
+    }
+
+    // 405 Method Not Allowed — path matches but method doesn't
+    const allowedMethods = new Set();
+    for (const [routeMethod, bucket] of this.routes) {
+      for (const route of bucket) {
+        if (normalized.match(route.regex)) { allowedMethods.add(routeMethod); break; }
+      }
+    }
+    if (allowedMethods.size > 0) {
+      allowedMethods.add("OPTIONS");
+      if (allowedMethods.has("GET")) allowedMethods.add("HEAD");
+      const allow = [...allowedMethods].sort().join(", ");
+      return {
+        handler: (_req, res) => {
+          res.writeHead(405, { "Content-Type": "application/json", "Allow": allow });
+          res.end(JSON.stringify({ error: "Method Not Allowed" }));
+        },
+        params: {},
+        query,
+        pattern: "405(auto)",
+      };
+    }
+
+    return null;
+  }
+}
+
+/**
+ * O5: Structured logger with service context and log level filtering.
+ */
+class Logger {
+  constructor(serviceName, workerId) {
+    this.serviceName = serviceName;
+    this.workerId = workerId;
+    // O5: Default log level is 'info'
+    this._level = LOG_LEVELS[process.env.FORGE_LOG_LEVEL?.toLowerCase()] ?? LOG_LEVELS.info;
+  }
+
+  /**
+   * O5: Set the log level dynamically.
+   * @param {'error'|'warn'|'info'|'debug'} level
+   */
+  setLogLevel(level) {
+    const numeric = LOG_LEVELS[level];
+    if (numeric === undefined) return;
+    this._level = numeric;
+  }
+
+  _log(level, message, meta = {}) {
+    // O5: Filter messages below current log level
+    if (LOG_LEVELS[level] > this._level) return;
+
+    const entry = {
+      ...meta,
+      timestamp: new Date().toISOString(),
+      level,
+      service: this.serviceName,
+      worker: this.workerId,
+      message,
+    };
+    const output = level === "error" ? process.stderr : process.stdout;
+    output.write(`${JSON.stringify(entry)}\n`);
+  }
+
+  debug(msg, meta) {
+    this._log("debug", msg, meta);
+  }
+  info(msg, meta) {
+    this._log("info", msg, meta);
+  }
+  warn(msg, meta) {
+    this._log("warn", msg, meta);
+  }
+  error(msg, meta) {
+    this._log("error", msg, meta);
+  }
+}
+
+/**
+ * Minimal WebSocket implementation (RFC 6455 framing).
+ * No external dependencies. Handles text frames, ping/pong, close.
+ */
+export class ForgeWebSocket extends EventEmitter {
+  constructor(socket, rctx, options = {}) {
+    super();
+    this.socket = socket;
+    this.ctx = rctx;
+    this._closed = false;
+    this._closeSent = false;
+    this._closeTimer = null;
+    // P7: Use chunk-list pattern instead of Buffer.concat on every chunk
+    this._bufferChunks = [];
+    this._bufferTotalLen = 0;
+    this._fragments = [];
+    this._fragmentOpcode = 0;
+    this._fragmentsTotalSize = 0;
+    this._totalBuffered = 0;
+    this._pingTimer = null;
+    this._lastPong = Date.now();
+
+    socket.on("data", (buf) => this._onData(buf));
+    socket.on("close", () => this._onClose());
+    socket.on("end", () => this._onClose());
+    socket.on("error", () => this._onClose());
+
+    // Start server-side ping keepalive
+    const pingInterval = options.pingInterval ?? 30000;
+    if (pingInterval > 0) {
+      this._startPingInterval(pingInterval);
+    }
+  }
+
+  send(data) {
+    if (this._closed) return;
+    const payload = typeof data === "string" ? Buffer.from(data) : data;
+    const frame = this._encodeFrame(payload, 0x01); // text frame
+    this.socket.write(frame);
+  }
+
+  sendBinary(data) {
+    if (this._closed) return;
+    const payload = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    const frame = this._encodeFrame(payload, 0x02); // binary frame
+    this.socket.write(frame);
+  }
+
+  close(code = 1000, reason = "") {
+    if (this._closed) return;
+    this._closed = true;
+    if (this._pingTimer) {
+      clearInterval(this._pingTimer);
+      this._pingTimer = null;
+    }
+    // RFC 6455 §5.5: close frame reason must be <= 123 bytes
+    let reasonBuf = reason ? Buffer.from(reason, "utf8") : Buffer.alloc(0);
+    if (reasonBuf.length > 123) reasonBuf = reasonBuf.subarray(0, 123);
+    const buf = Buffer.alloc(2 + reasonBuf.length);
+    buf.writeUInt16BE(code, 0);
+    if (reasonBuf.length > 0) reasonBuf.copy(buf, 2);
+    this.socket.write(this._encodeFrame(buf, 0x08)); // close frame
+
+    // H2: Close handshake — track _closeSent so we know if we initiated the close.
+    // When the peer's close frame arrives in _onData, the handler checks _closeSent
+    // and ends the socket immediately (completing the handshake).
+    // We always call socket.end() after sending our close frame.
+    if (!this._closeSent) {
+      this._closeSent = true;
+    }
+    this.socket.end();
+    this.emit("close", code, reason);
+  }
+
+  /**
+   * P7: Consolidate buffer chunks into a single Buffer only when needed.
+   */
+  _consolidateBuffer() {
+    if (this._bufferChunks.length === 0) return;
+    if (this._bufferChunks.length === 1) {
+      // No concat needed for single chunk
+      return;
+    }
+    const consolidated = Buffer.concat(this._bufferChunks, this._bufferTotalLen);
+    this._bufferChunks = [consolidated];
+    // _bufferTotalLen stays the same
+  }
+
+  /**
+   * Get the current buffer as a single Buffer (consolidating if needed).
+   */
+  get _buffer() {
+    if (this._bufferChunks.length === 0) return Buffer.alloc(0);
+    if (this._bufferChunks.length === 1) return this._bufferChunks[0];
+    this._consolidateBuffer();
+    return this._bufferChunks[0];
+  }
+
+  /**
+   * Set the buffer (replaces all chunks).
+   */
+  set _buffer(buf) {
+    if (buf.length === 0) {
+      this._bufferChunks = [];
+      this._bufferTotalLen = 0;
+    } else {
+      this._bufferChunks = [buf];
+      this._bufferTotalLen = buf.length;
+    }
+  }
+
+  _onData(buf) {
+    // Track total memory used per connection
+    this._totalBuffered += buf.length;
+
+    if (this._totalBuffered > MAX_WS_BUFFER) {
+      this._closed = true;
+      this._bufferChunks = [];
+      this._bufferTotalLen = 0;
+      this._fragments = [];
+      this._fragmentsTotalSize = 0;
+      this._totalBuffered = 0;
+      this.socket.destroy();
+      this.emit("close", 1009, "Message too big");
+      return;
+    }
+
+    // P7: Append chunk to list instead of Buffer.concat on every call
+    this._bufferChunks.push(buf);
+    this._bufferTotalLen += buf.length;
+
+    while (this._bufferTotalLen >= 2) {
+      // Consolidate only when we need to parse
+      this._consolidateBuffer();
+      const buffer = this._bufferChunks[0];
+
+      const fin = (buffer[0] & 0x80) !== 0;
+      const rsv = buffer[0] & 0x70; // bits 4-6
+      if (rsv !== 0) {
+        // C7: Immediate destroy — don't try to send close frame
+        this._closed = true;
+        this._bufferChunks = [];
+        this._bufferTotalLen = 0;
+        this._fragments = [];
+        this._fragmentsTotalSize = 0;
+        if (this._pingTimer) { clearInterval(this._pingTimer); this._pingTimer = null; }
+        this.socket.destroy();
+        this.emit("close", 1002, "RSV bits must be 0");
+        return;
+      }
+      const masked = (buffer[1] & 0x80) !== 0;
+
+      // RFC 6455 requires client-to-server frames to be masked
+      if (!masked) {
+        // H2: Immediate destroy — don't try to send close frame
+        this._closed = true;
+        this._bufferChunks = [];
+        this._bufferTotalLen = 0;
+        this._fragments = [];
+        this._fragmentsTotalSize = 0;
+        if (this._pingTimer) { clearInterval(this._pingTimer); this._pingTimer = null; }
+        this.socket.destroy();
+        this.emit("close", 1002, "Unmasked client frame");
+        return;
+      }
+
+      let payloadLen = buffer[1] & 0x7f;
+      let offset = 2;
+
+      if (payloadLen === 126) {
+        if (this._bufferTotalLen < 4) return; // need more data for length
+        payloadLen = buffer.readUInt16BE(2);
+        offset = 4;
+      } else if (payloadLen === 127) {
+        if (this._bufferTotalLen < 10) return; // need more data for length
+        payloadLen = Number(buffer.readBigUInt64BE(2));
+        offset = 10;
+      }
+
+      // Max payload size check to prevent memory exhaustion (1MB)
+      if (payloadLen > MAX_WS_BUFFER) {
+        this.close(1009); // 1009 = message too big
+        this._bufferChunks = [];
+        this._bufferTotalLen = 0;
+        this._fragments = [];
+        this._fragmentsTotalSize = 0;
+        return;
+      }
+
+      if (masked) offset += 4;
+
+      const totalFrameSize = offset + payloadLen;
+      if (this._bufferTotalLen < totalFrameSize) return; // incomplete frame
+
+      // We have a complete frame — parse it
+      const opcode = buffer[0] & 0x0f;
+      const maskOffset = offset - 4;
+      let mask = null;
+      if (masked) {
+        mask = buffer.slice(maskOffset, maskOffset + 4);
+      }
+
+      let payload = buffer.slice(offset, offset + payloadLen);
+      // P8: In-place XOR unmasking — no intermediate array allocation
+      if (mask) {
+        payload = Buffer.from(payload); // copy so we can modify in place
+        for (let i = 0; i < payload.length; i++) {
+          payload[i] ^= mask[i & 3];
+        }
+      }
+
+      // Consume the frame from the buffer
+      const remaining = buffer.slice(totalFrameSize);
+      if (remaining.length === 0) {
+        this._bufferChunks = [];
+        this._bufferTotalLen = 0;
+      } else {
+        this._bufferChunks = [remaining];
+        this._bufferTotalLen = remaining.length;
+      }
+      // Recompute total buffered from actual buffer + already-tracked fragment size
+      this._totalBuffered = this._bufferTotalLen + this._fragmentsTotalSize;
+
+      // Handle control frames (ping/pong/close) — always processed immediately
+      if (opcode === 0x08) {
+        // H2: If we already sent a close frame, this is the peer's response —
+        // complete the handshake by ending the socket immediately
+        if (this._closeSent) {
+          if (this._closeTimer) { clearTimeout(this._closeTimer); this._closeTimer = null; }
+          this.socket.end();
+          return;
+        }
+
+        // close — parse status code and reason from payload (RFC 6455 § 5.5.1)
+        // Set _closeSent so the responding close() call knows to end immediately
+        this._closeSent = true;
+        if (payload.length === 0) {
+          this.close(1000, '');
+        } else if (payload.length === 1) {
+          // Malformed: close payload must be 0 or >= 2 bytes
+          this.close(1002, 'Protocol error');
+        } else {
+          const code = payload.readUInt16BE(0);
+          // H10: Validate close code per RFC 6455 §7.4
+          if (code < 1000 || (code >= 1004 && code <= 1006) || (code >= 1012 && code <= 2999) || code >= 5000) {
+            this.close(1002, 'Protocol error');
+            return;
+          }
+          const reason = payload.length > 2 ? payload.slice(2).toString('utf8') : '';
+          this.close(code, reason);
+        }
+        return;
+      }
+      if (opcode === 0x09) {
+        // ping
+        this.socket.write(this._encodeFrame(payload, 0x0a)); // pong
+        this._lastPong = Date.now();
+        continue;
+      }
+      if (opcode === 0x0a) {
+        // pong
+        this._lastPong = Date.now();
+        continue;
+      }
+
+      // Handle data frames with fragmentation support
+      if (opcode !== 0x00) {
+        // Non-continuation frame — start of a new message (or single-frame message)
+        this._fragmentOpcode = opcode;
+        this._fragments = [payload];
+        this._fragmentsTotalSize = payload.length;
+      } else {
+        // Continuation frame (opcode 0x00)
+        if (this._fragments.length === 0) {
+          // Orphan continuation frame with no initial frame — protocol error
+          this.close(1002);
+          return;
+        }
+        const MAX_WS_FRAGMENTS = 1024;
+        if (this._fragments.length >= MAX_WS_FRAGMENTS) {
+          this.close(1009, "Too many fragments");
+          return;
+        }
+        this._fragmentsTotalSize += payload.length;
+        if (this._fragmentsTotalSize > MAX_WS_BUFFER) {
+          this.close(1009, "Reassembled message too large");
+          return;
+        }
+        this._fragments.push(payload);
+      }
+
+      if (fin) {
+        // Message is complete — reassemble fragments
+        const complete = this._fragments.length === 1 ? this._fragments[0] : Buffer.concat(this._fragments);
+        const messageOpcode = this._fragmentOpcode;
+        this._fragments = [];
+        this._fragmentOpcode = 0;
+        this._fragmentsTotalSize = 0;
+
+        // Check total reassembled message size
+        if (complete.length > MAX_WS_BUFFER) {
+          this.close(1009);
+          this._bufferChunks = [];
+          this._bufferTotalLen = 0;
+          return;
+        }
+
+        if (messageOpcode === 0x01) {
+          // text
+          this.emit("message", complete.toString());
+        } else if (messageOpcode === 0x02) {
+          // binary
+          this.emit("message", complete);
+        }
+      }
+    }
+
+    // Always recalculate at end to prevent drift from partial frames
+    this._totalBuffered = this._bufferTotalLen + this._fragmentsTotalSize;
+  }
+
+  _encodeFrame(payload, opcode) {
+    const len = payload.length;
+    let header;
+    if (len < 126) {
+      header = Buffer.alloc(2);
+      header[0] = 0x80 | opcode; // FIN + opcode
+      header[1] = len;
+    } else if (len < 65536) {
+      header = Buffer.alloc(4);
+      header[0] = 0x80 | opcode;
+      header[1] = 126;
+      header.writeUInt16BE(len, 2);
+    } else {
+      header = Buffer.alloc(10);
+      header[0] = 0x80 | opcode;
+      header[1] = 127;
+      header.writeBigUInt64BE(BigInt(len), 2);
+    }
+    return Buffer.concat([header, payload]);
+  }
+
+  _onClose() {
+    // Always clean up timers regardless of _closed state
+    if (this._pingTimer) {
+      clearInterval(this._pingTimer);
+      this._pingTimer = null;
+    }
+    if (this._closeTimer) {
+      clearTimeout(this._closeTimer);
+      this._closeTimer = null;
+    }
+    if (!this._closed) {
+      this._closed = true;
+      this.emit("close");
+    }
+  }
+
+  _startPingInterval(intervalMs) {
+    // M-WS-1: Reset pong timestamp to avoid false timeout from gap between
+    // socket creation and first ping check
+    this._lastPong = Date.now();
+    this._pingTimer = setInterval(() => {
+      if (this._closed) {
+        clearInterval(this._pingTimer);
+        this._pingTimer = null;
+        return;
+      }
+      // If no pong received within 2 ping intervals, close as unresponsive
+      if (Date.now() - this._lastPong > intervalMs * 2) {
+        this.close(1001, 'Ping timeout');
+        return;
+      }
+      // Send ping frame with empty payload
+      this.socket.write(this._encodeFrame(Buffer.alloc(0), 0x09));
+    }, intervalMs);
+    this._pingTimer.unref();
+  }
+}