haechi 1.1.2 → 1.3.0

package/packages/proxy/index.mjs

@@ -1,29 +1,207 @@
 import { createServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
 import { createHash, randomUUID } from "node:crypto";
 import { isUtf8 } from "node:buffer";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { inspectResponseStream } from "../stream-filter/index.mjs";
 
 export const DEFAULT_PROXY_PORT = 11016;
 
-export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "127.0.0.1", allowRemoteBind = false }) {
-  assertSafeProxyBind({ host, allowRemoteBind });
+// The published package version, read once from the package's own manifest.
+// package.json IS in the published tarball, and packages/proxy/index.mjs sits
+// two levels below the repo root, so this URL resolves in both the dev tree and
+// the packed tarball. Falls back to "unknown" rather than throwing — a version
+// read must never break proxy startup.
+export const HAECHI_VERSION = readPackageVersion();
+
+function readPackageVersion() {
+  try {
+    const pkgUrl = new URL("../../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// A tlsContext is usable iff it can actually terminate TLS: (key && cert) or pfx.
+// This is the SINGLE source of truth for both the bind guard and server
+// selection — the SAME shape the haechi-dashboard satellite uses, so the proxy
+// and the dashboard share one TLS-material predicate. A non-null tlsContext that
+// fails this check must fail closed (never green-light a remote bind that then
+// builds a plaintext http server).
+export function hasUsableTlsMaterial(ctx) {
+  if (!ctx || typeof ctx !== "object" || Array.isArray(ctx)) {
+    return false;
+  }
+  const hasKeyCert = Boolean(ctx.key) && Boolean(ctx.cert);
+  const hasPfx = Boolean(ctx.pfx);
+  return hasKeyCert || hasPfx;
+}
+
+// Structured logger honoring config.logging.format. In "json" mode it emits a
+// single JSON line carrying a correlationId and an error NAME/class — NEVER a
+// request/response payload, headers, token, or any PII. In "text" mode it
+// preserves the prior human-readable console output.
+function createLogger(format = "text") {
+  const json = format === "json";
+  return {
+    error(event, fields = {}) {
+      if (json) {
+        process.stderr.write(`${JSON.stringify({ level: "error", event, ...fields })}\n`);
+      } else {
+        const parts = Object.entries(fields)
+          .filter(([, value]) => value !== undefined && value !== null)
+          .map(([key, value]) => `${key}=${value}`);
+        process.stderr.write(`haechi ${event}${parts.length ? `: ${parts.join(" ")}` : ""}\n`);
+      }
+    }
+  };
+}
+
+export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "127.0.0.1", allowRemoteBind = false, tlsContext, trustForwardedProto }) {
   const { haechi, config, protocolAdapter } = runtime;
-  const rateLimiter = createRateLimiter();
 
-  const server = createServer(async (request, response) => {
+  // WS6 TLS hardening. The tlsContext / trustForwardedProto source of truth is
+  // the normalized config (proxy.tls is loaded into a tlsContext at startup;
+  // proxy.trustForwardedProto is a boolean), but an explicit argument overrides
+  // it (so a hand-built runtime / a test can drive these directly). hasUsableTls
+  // is the same predicate the dashboard satellite uses.
+  const resolvedTlsContext = tlsContext !== undefined ? tlsContext : (config.proxy?.tls ?? null);
+  const resolvedTrustForwardedProto = trustForwardedProto !== undefined
+    ? trustForwardedProto
+    : Boolean(config.proxy?.trustForwardedProto);
+  const usableTls = hasUsableTlsMaterial(resolvedTlsContext);
+
+  // Bind guard, two layers. (1) the loopback/remote-bind gate (shared with the
+  // dashboard). (2) WS6: a remote bind ADDITIONALLY requires a usable tlsContext
+  // OR an explicit trustForwardedProto acknowledgement (a trusted reverse proxy
+  // terminates TLS in front of Haechi). Otherwise it THROWS at startup — the
+  // proxy must NEVER serve bearer tokens + payloads in plaintext on a remote
+  // bind. Loopback dev is unaffected (plain http, no TLS).
+  assertSafeProxyBind({ host, allowRemoteBind });
+  assertSafeProxyTransport({
+    host,
+    allowRemoteBind,
+    hasUsableTls: usableTls,
+    trustForwardedProto: resolvedTrustForwardedProto
+  });
+
+  // When the remote bind rests on trustForwardedProto (plain http behind a
+  // trusted TLS hop) we REJECT any protected-route request whose
+  // X-Forwarded-Proto is not https — a plaintext request that bypassed the hop.
+  // This is only meaningful for a non-loopback, plain-http, trust-forwarded
+  // listener; a loopback dev server or an https-terminating server never gates.
+  const enforceForwardedProto = !isLoopbackHost(host)
+    && allowRemoteBind
+    && !usableTls
+    && resolvedTrustForwardedProto;
+  // The runtime owns the rate limiter (an injectable collaborator). Fall back to
+  // a local per-process default so a hand-built runtime object without a
+  // rateLimiter still works (backward-compatible). The default and the runtime's
+  // default share the same allow(key, limit) -> boolean fixed-window contract.
+  const rateLimiter = runtime.rateLimiter ?? createRateLimiter();
+  // The metrics collector is owned by the runtime (injectable). Fall back to a
+  // no-op so a hand-built runtime object without metrics still works.
+  const metrics = runtime.metrics ?? noopMetrics();
+  const logger = createLogger(config.logging?.format ?? "text");
+
+  // WS4-B backpressure: a configurable global max-in-flight ceiling. 0 (default)
+  // disables it, preserving 1.1 behavior. When > 0 and the live count is at the
+  // ceiling, a NEW non-exempt request is rejected 503 + Retry-After BEFORE auth
+  // and body-read. The /__haechi/* observability routes are EXEMPT so metrics +
+  // liveness can be scraped under saturation.
+  const maxInFlight = config.limits.maxInFlight ?? 0;
+  const retryAfterSeconds = Math.max(1, Math.ceil((config.limits.shutdownGraceMs ?? 10000) / 1000));
+  // Live in-flight request count for the drain-tracking AND the ceiling. A
+  // bounded integer — never identity/value bearing.
+  let inFlight = 0;
+  // Resolves once in-flight drains to zero during a graceful close().
+  let drained = null;
+  let resolveDrained = null;
+
+  const requestHandler = async (request, response) => {
+    // Per-REQUEST correlation id: generated here, threaded into every protect
+    // context (so the audit events of one request share it) AND into the error
+    // log. A UUID — never a payload/identity/PII value.
+    const correlationId = randomUUID();
+    const startedAt = process.hrtime.bigint();
+    let routeId = "unknown";
+
+    // Observability routes are exempt from the in-flight ceiling and are NOT
+    // counted toward it: liveness/readiness/metrics must answer under saturation.
+    const exemptRoute = isObservabilityRoute(request);
+
+    // Backpressure: reject at the ceiling BEFORE doing any work. Counted in
+    // metrics by a bounded enum decision; the body is never read.
+    if (!exemptRoute && maxInFlight > 0 && inFlight >= maxInFlight) {
+      metrics.increment("haechi_overloaded_total");
+      response.writeHead(503, {
+        "content-type": "application/json",
+        "retry-after": String(retryAfterSeconds)
+      });
+      response.end(`${JSON.stringify({ error: "haechi_overloaded", message: "Server at max in-flight capacity; retry later" }, null, 2)}\n`);
+      return;
+    }
+
+    // Track in-flight for graceful drain + the ceiling. Decrement in finally so a
+    // throw/early-return can never leak the count (which would wedge close()).
+    let counted = false;
+    if (!exemptRoute) {
+      inFlight += 1;
+      counted = true;
+    }
     try {
+      // WS6 forwarded-proto enforcement. When this is a non-loopback plain-http
+      // listener resting on trustForwardedProto (a trusted reverse proxy
+      // terminates TLS in front of Haechi), a request whose X-Forwarded-Proto is
+      // not "https" arrived over plaintext that BYPASSED the TLS hop — reject it
+      // fail-closed BEFORE auth and body-read, so a protected route never serves
+      // tokens/payloads over an unverified-plaintext hop. The /__haechi/* liveness
+      // routes are EXEMPT (they leak nothing) so a health check / metrics scrape
+      // from the loopback sidecar still answers.
+      if (enforceForwardedProto && !exemptRoute && !isForwardedHttps(request)) {
+        writeJson(response, 403, {
+          error: "haechi_forwarded_proto_required",
+          message: "This proxy runs behind a trusted TLS-terminating hop (proxy.trustForwardedProto). A request without X-Forwarded-Proto: https bypassed the hop and is refused."
+        });
+        return;
+      }
+      // Health + telemetry endpoints are unauthenticated and checked BEFORE auth
+      // and body-read. They live under the reserved /__haechi/* prefix.
+      if (request.method === "GET" && request.url === "/__haechi/live") {
+        // Cheap process liveness. Always 200 while the event loop is serving.
+        writeJson(response, 200, { ok: true, version: HAECHI_VERSION });
+        return;
+      }
+      if (request.method === "GET" && request.url === "/__haechi/ready") {
+        await handleReady({ runtime, response });
+        return;
+      }
       if (request.method === "GET" && request.url === "/__haechi/health") {
-        // Intentionally unauthenticated; exposes only the mode.
-        writeJson(response, 200, { ok: true, mode: config.mode });
+        // Back-compat: keep the original shape (ok + mode) and add version.
+        writeJson(response, 200, { ok: true, mode: config.mode, version: HAECHI_VERSION });
+        return;
+      }
+      if (request.method === "GET" && request.url === "/__haechi/metrics") {
+        if (!config.metrics?.enabled) {
+          writeJson(response, 404, { error: "haechi_metrics_disabled", message: "Metrics endpoint is disabled (metrics.enabled: false)" });
+          return;
+        }
+        response.writeHead(200, { "content-type": "text/plain; version=0.0.4; charset=utf-8" });
+        response.end(metrics.render());
         return;
       }
 
       assertRelativeProxyTarget(request.url);
       const routeContext = protocolAdapter.classifyRequest(request);
+      routeId = routeContext?.routeId ?? "unknown";
+      const mode = config.policy.mode ?? config.mode;
 
       // Authenticate, resolve the policy profile, and rate-limit BEFORE reading
       // the body, so a denied/throttled request cannot stream a large body.
-      const gate = await authorizeRequest({ runtime, request, routeContext, rateLimiter });
+      const gate = await authorizeRequest({ runtime, request, routeContext, rateLimiter, metrics, correlationId });
       if (gate.denied) {
         writeJson(response, gate.denied.status, {
           error: gate.denied.error,
@@ -32,7 +210,7 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         return;
       }
       const { identity, profile, policyEngine, modelAllowlist } = gate;
-      const authContext = { identity, profile, policyEngine };
+      const authContext = { identity, profile, policyEngine, correlationId };
 
       const body = await readBody(request, {
         maxBytes: config.limits.maxRequestBytes
@@ -42,12 +220,14 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
       // Model allowlist runs after body read (the model field is in the body).
       if (modelAllowlist && typeof json?.model === "string" && !modelAllowlist.includes(json.model)) {
         await recordProxyDecision({
-          runtime, routeContext, identity, profile,
+          runtime, routeContext, identity, profile, correlationId,
           decision: "model_not_allowed",
           reason: `model:${json.model}`,
           enforced: true,
           blocked: true
         });
+        countDecision(metrics, { routeContext, mode, decision: "model_not_allowed" });
+        metrics.increment("haechi_blocks_total");
         writeJson(response, 403, {
           error: "haechi_model_not_allowed",
           message: `Model not allowed: ${json.model}`
@@ -57,7 +237,7 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
 
       if (isStreamingRequest(json, routeContext)) {
         if (config.streaming.requestMode === "inspect") {
-          await handleInspectedStream({ runtime, request, response, routeContext, json, authContext });
+          await handleInspectedStream({ runtime, request, response, routeContext, json, authContext, metrics });
           return;
         }
 
@@ -67,16 +247,19 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
             routeContext,
             identity,
             profile,
+            correlationId,
             decision: "streaming_request_pass_through",
             reason: "streaming_request_pass_through",
             enforced: false,
             blocked: false
           });
+          countDecision(metrics, { routeContext, mode, decision: "forwarded" });
           const upstreamResponse = await forward({
             upstream: config.target.upstream,
             request,
             body,
-            timeoutMs: config.limits.upstreamTimeoutMs
+            timeoutMs: config.limits.upstreamTimeoutMs,
+            metrics
           });
           const { body: rawBody } = await readUpstreamBody(upstreamResponse);
           response.writeHead(upstreamResponse.status, Object.fromEntries(upstreamResponse.headers.entries()));
@@ -84,6 +267,7 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
           return;
         }
 
+        countDecision(metrics, { routeContext, mode, decision: "streaming_blocked" });
         writeJson(response, 501, {
           error: "haechi_streaming_unsupported",
           message: "Streaming requests are blocked unless streaming.requestMode is set to pass-through or inspect"
@@ -97,11 +281,13 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
           ...authContext,
           operation: `request:${routeContext.operation}`,
           direction: "request",
-          mode: config.policy.mode ?? config.mode
+          mode
         })
         : { payload: json, blocked: false };
 
       if (result.blocked) {
+        countDecision(metrics, { routeContext, mode, decision: "blocked" });
+        metrics.increment("haechi_blocks_total");
         writeJson(response, 403, {
           error: "haechi_policy_block",
           summary: result.summary,
@@ -114,7 +300,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         upstream: config.target.upstream,
         request,
         body: JSON.stringify(result.payload),
-        timeoutMs: config.limits.upstreamTimeoutMs
+        timeoutMs: config.limits.upstreamTimeoutMs,
+        metrics
       });
 
       const forwarded = await maybeProtectResponse({
@@ -122,58 +309,234 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         routeContext,
         runtime,
         authContext,
-        issuedTokens: result.issuedTokens ?? []
+        issuedTokens: result.issuedTokens ?? [],
+        metrics
       });
 
+      countDecision(metrics, {
+        routeContext,
+        mode,
+        decision: forwarded.decision ?? "forwarded"
+      });
       response.writeHead(forwarded.status, forwarded.headers);
       response.end(forwarded.body);
     } catch (error) {
       const expected = typeof error?.statusCode === "number";
       if (!expected) {
-        console.error(`haechi proxy internal error: ${error?.stack ?? error?.message ?? error}`);
+        // Carry the error NAME/class + correlationId only — NEVER the payload,
+        // headers, token, or any PII.
+        logger.error("proxy_internal_error", {
+          correlationId,
+          errorName: error?.name ?? "Error",
+          statusCode: error?.statusCode ?? 500
+        });
+        metrics.increment("haechi_internal_error_total");
       }
       writeJson(response, error.statusCode ?? 500, {
         error: error.errorCode ?? "haechi_proxy_error",
         message: expected ? error.message : "Internal proxy error"
       });
+    } finally {
+      const elapsedSeconds = Number(process.hrtime.bigint() - startedAt) / 1e9;
+      // route label is a bounded route id (or "unknown") — never an identity/value.
+      metrics.observe("haechi_request_duration_seconds", elapsedSeconds, { route: routeId });
+      if (counted) {
+        inFlight -= 1;
+        // If a graceful close() is awaiting drain and we just hit zero, resolve it.
+        if (resolveDrained && inFlight <= 0) {
+          resolveDrained();
+        }
+      }
     }
-  });
+  };
+
+  // Server selection: a usable tlsContext → an https listener terminating TLS in
+  // this process; otherwise plain http (unchanged for loopback/dev). The bind
+  // guard above already guarantees a non-loopback bind without usable TLS carries
+  // an explicit trustForwardedProto acknowledgement, so a plain-http server is
+  // only ever exposed remotely behind a trusted TLS hop (and gated below).
+  const server = usableTls
+    ? createHttpsServer(resolvedTlsContext, requestHandler)
+    : createServer(requestHandler);
+  const servesHttps = usableTls;
+
+  // WS4-B tuned timeouts. Only override Node's server defaults when a value is
+  // configured (null = leave Node's default untouched, so behavior is unchanged
+  // unless an operator opts in). requestTimeout caps the whole request; a value
+  // of 0 disables the timeout (Node semantics) — validated upstream.
+  if (config.limits.requestTimeoutMs !== null && config.limits.requestTimeoutMs !== undefined) {
+    server.requestTimeout = config.limits.requestTimeoutMs;
+  }
+  if (config.limits.headersTimeoutMs !== null && config.limits.headersTimeoutMs !== undefined) {
+    server.headersTimeout = config.limits.headersTimeoutMs;
+  }
 
   return {
     server,
+    // Whether THIS listener terminates TLS (https) — the CLI/log line reflects
+    // the right scheme, and a caller can assert the selected transport.
+    servesHttps,
     listen() {
       return new Promise((resolve) => {
         server.listen(port, host, () => {
           const address = server.address();
-          resolve({ host: address.address, port: address.port });
+          resolve({ host: address.address, port: address.port, tls: servesHttps });
         });
       });
     },
+    // WS4-B graceful drain. Stop accepting new connections, immediately close
+    // idle keep-alive sockets, and wait for in-flight requests to drain. After a
+    // configurable grace period (limits.shutdownGraceMs) force-close any lingering
+    // socket so a stuck keep-alive cannot hold shutdown open forever. The grace
+    // timer is .unref()-ed and cleared on a clean drain so `node --test` never
+    // hangs on a leaked timer.
     close() {
+      const graceMs = config.limits.shutdownGraceMs ?? 10000;
       return new Promise((resolve, reject) => {
-        server.close((error) => error ? reject(error) : resolve());
+        let settled = false;
+        let graceTimer = null;
+
+        const finish = (error) => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          if (graceTimer) {
+            clearTimeout(graceTimer);
+            graceTimer = null;
+          }
+          resolveDrained = null;
+          drained = null;
+          if (error) {
+            reject(error);
+          } else {
+            resolve();
+          }
+        };
+
+        // Stop accepting new connections; the callback fires once all
+        // connections are closed (idle ones we close now, in-flight ones once
+        // they drain or the grace timer force-closes them).
+        server.close((error) => finish(error));
+
+        // Close idle keep-alive sockets immediately so they don't keep the
+        // server open waiting for a request that will never come.
+        if (typeof server.closeIdleConnections === "function") {
+          server.closeIdleConnections();
+        }
+
+        // If nothing is in flight, the close callback will fire promptly; still
+        // arm a drain resolver in case requests are mid-flight.
+        if (inFlight <= 0) {
+          // No in-flight work; closeIdleConnections handled keep-alive, so
+          // server.close() resolves on its own. Nothing more to wait for.
+          return;
+        }
+
+        // Wait for in-flight requests to drain, then force-close stragglers
+        // (the force close covers a request whose socket lingers after we stop).
+        drained = new Promise((res) => { resolveDrained = res; });
+        drained.then(() => {
+          if (typeof server.closeAllConnections === "function") {
+            server.closeAllConnections();
+          }
+        });
+
+        // Grace cap: after graceMs force every remaining connection closed so a
+        // lingering keep-alive socket cannot hold shutdown open forever. unref()
+        // so this timer alone never keeps the event loop (and `node --test`) alive.
+        graceTimer = setTimeout(() => {
+          if (typeof server.closeAllConnections === "function") {
+            server.closeAllConnections();
+          }
+        }, graceMs);
+        if (typeof graceTimer.unref === "function") {
+          graceTimer.unref();
+        }
       });
     }
   };
 }
 
+// True for the reserved /__haechi/* observability routes (live/ready/health/
+// metrics). These are EXEMPT from the in-flight ceiling so liveness + metrics
+// stay scrapable under saturation, and they do not count toward drain tracking.
+function isObservabilityRoute(request) {
+  return request.method === "GET" && typeof request.url === "string" && request.url.startsWith("/__haechi/");
+}
+
+// Readiness probe (WS4-A). FAIL-CLOSED: a gateway that cannot write its audit
+// log is NOT ready (503). Runs the audit sink's optional ready()/healthCheck()
+// — if the sink lacks one, audit is treated as ready. The checks object carries
+// only booleans/enums; never a path, payload, or PII value.
+async function handleReady({ runtime, response }) {
+  const checks = {};
+  let ready = true;
+
+  const probe = runtime.auditSink?.ready ?? runtime.auditSink?.healthCheck;
+  if (typeof probe === "function") {
+    try {
+      const result = await probe.call(runtime.auditSink);
+      checks.auditWritable = result === true || result?.ok === true;
+    } catch {
+      checks.auditWritable = false;
+    }
+  } else {
+    // No probe method on the sink → cannot disprove writability; treat as ready.
+    checks.auditWritable = true;
+  }
+  if (checks.auditWritable !== true) {
+    ready = false;
+  }
+
+  writeJson(response, ready ? 200 : 503, { ready, version: HAECHI_VERSION, checks });
+}
+
+// Increment the request counter with a bounded enum label set. route is a route
+// id, mode is the policy mode, decision is a fixed decision class — NEVER an
+// identity/token/detected value (no-PII-in-telemetry invariant).
+function countDecision(metrics, { routeContext, mode, decision }) {
+  metrics?.increment("haechi_requests_total", {
+    route: routeContext?.routeId ?? "unknown",
+    mode: mode ?? "unknown",
+    decision
+  });
+}
+
+// Backward-compat fallback for a hand-built runtime object without metrics: a
+// no-op collector with the same increment/observe/render contract.
+function noopMetrics() {
+  return {
+    increment() {},
+    observe() {},
+    render() {
+      return "";
+    }
+  };
+}
+
 // Authenticate → resolve policy profile → rate-limit. Returns the request's
 // identity/profile/policyEngine/modelAllowlist, or a denial. Auth is required
 // exactly when an authProvider is configured (auth.provider !== "none").
-async function authorizeRequest({ runtime, request, routeContext, rateLimiter }) {
-  const { authProvider, policyProfiles } = runtime;
+async function authorizeRequest({ runtime, request, routeContext, rateLimiter, metrics, correlationId }) {
+  const { authProvider, policyProfiles, config } = runtime;
+  const mode = config.policy.mode ?? config.mode;
   let identity = null;
 
   if (authProvider) {
     try {
       identity = await authProvider.authenticate(request);
     } catch {
-      await recordAuthDenied({ runtime, routeContext, reason: "provider_error" });
+      await recordAuthDenied({ runtime, routeContext, reason: "provider_error", correlationId });
+      countDecision(metrics, { routeContext, mode, decision: "auth_denied" });
+      metrics.increment("haechi_auth_denied_total");
       return { denied: { status: 401, error: "haechi_auth_denied", message: "Authentication failed" } };
     }
     if (!identity) {
       const reason = hasBearerHeader(request) ? "invalid_token" : "no_token";
-      await recordAuthDenied({ runtime, routeContext, reason });
+      await recordAuthDenied({ runtime, routeContext, reason, correlationId });
+      countDecision(metrics, { routeContext, mode, decision: "auth_denied" });
+      metrics.increment("haechi_auth_denied_total");
       return { denied: { status: 401, error: "haechi_auth_denied", message: "Authentication required" } };
     }
   }
@@ -182,14 +545,22 @@ async function authorizeRequest({ runtime, request, routeContext, rateLimiter })
 
   if (resolved.rate && resolved.rate.requestsPerMinute) {
     const key = identity?.id ?? "anonymous";
-    if (!rateLimiter.allow(key, resolved.rate.requestsPerMinute)) {
+    // allow() may return a boolean OR a Promise<boolean>: the built-in default is
+    // synchronous, but a shared-store (e.g. Redis-backed) limiter is inherently
+    // async. We await unconditionally — `await <boolean>` returns the boolean
+    // unchanged, so the sync default keeps working, while `!somePromise` (always
+    // false, because a Promise is truthy) can no longer let an async limiter
+    // silently fail open. See haechi-ratelimit-redis (shared-store satellite).
+    if (!(await rateLimiter.allow(key, resolved.rate.requestsPerMinute))) {
       await recordProxyDecision({
-        runtime, routeContext, identity, profile: resolved.profile,
+        runtime, routeContext, identity, profile: resolved.profile, correlationId,
         decision: "rate_limited",
         reason: `rate:${resolved.rate.requestsPerMinute}`,
         enforced: true,
         blocked: true
       });
+      countDecision(metrics, { routeContext, mode, decision: "rate_limited" });
+      metrics.increment("haechi_rate_limited_total");
       return { denied: { status: 429, error: "haechi_rate_limited", message: "Rate limit exceeded" } };
     }
   }
@@ -208,13 +579,36 @@ function hasBearerHeader(request) {
 }
 
 function createRateLimiter() {
-  // In-memory fixed-window counter. Per-process: resets on restart, not shared
-  // across replicas — acceptable for a single-process self-hosted preview.
+  // Backward-compat fallback ONLY: the canonical default lives in the runtime
+  // (createRuntime owns providers.rateLimiter). This path runs when a hand-built
+  // runtime object lacks rateLimiter. In-memory fixed-window counter, per-process
+  // (resets on restart, not shared across replicas). The window Map is bounded by
+  // a lazy, amortized sweep — NO timer — so aged-out one-shot identities do not
+  // accumulate unboundedly (mirrors runtime's createRateLimiter).
   const windows = new Map();
   const windowMs = 60000;
+  const sweepThreshold = 1024;
+  const sweepBudget = 256;
+
+  function sweepExpired(now) {
+    let scanned = 0;
+    for (const [key, slot] of windows) {
+      if (scanned >= sweepBudget) {
+        break;
+      }
+      scanned += 1;
+      if (now - slot.windowStart >= windowMs) {
+        windows.delete(key);
+      }
+    }
+  }
+
   return {
     allow(key, limit) {
       const now = Date.now();
+      if (windows.size >= sweepThreshold) {
+        sweepExpired(now);
+      }
       const slot = windows.get(key);
       if (!slot || now - slot.windowStart >= windowMs) {
         windows.set(key, { windowStart: now, count: 1 });
@@ -229,9 +623,9 @@ function createRateLimiter() {
   };
 }
 
-async function recordAuthDenied({ runtime, routeContext, reason }) {
+async function recordAuthDenied({ runtime, routeContext, reason, correlationId = null }) {
   await recordProxyDecision({
-    runtime, routeContext, identity: null, profile: null,
+    runtime, routeContext, identity: null, profile: null, correlationId,
     decision: "auth_denied",
     reason,
     enforced: true,
@@ -239,8 +633,9 @@ async function recordAuthDenied({ runtime, routeContext, reason }) {
   });
 }
 
-async function handleInspectedStream({ runtime, request, response, routeContext, json, authContext = {} }) {
+async function handleInspectedStream({ runtime, request, response, routeContext, json, authContext = {}, metrics = null }) {
   const { haechi, config } = runtime;
+  const requestMode = config.policy.mode ?? config.mode;
 
   // Inspection needs to know the wire format and delta channel for this route.
   if (!routeContext.streaming) {
@@ -264,6 +659,8 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
     : { payload: json, blocked: false };
 
   if (requestResult.blocked) {
+    countDecision(metrics, { routeContext, mode: requestMode, decision: "blocked" });
+    metrics?.increment("haechi_blocks_total");
     writeJson(response, 403, {
       error: "haechi_policy_block",
       summary: requestResult.summary,
@@ -276,7 +673,8 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
     upstream: config.target.upstream,
     request,
     body: JSON.stringify(requestResult.payload),
-    timeoutMs: config.limits.upstreamTimeoutMs
+    timeoutMs: config.limits.upstreamTimeoutMs,
+    metrics
   });
 
   const streamMode = config.streaming.responseMode ?? config.responseProtection.mode ?? config.policy.mode ?? config.mode;
@@ -300,8 +698,13 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
 
   await recordStreamDecision({
     runtime, routeContext, blocked, summary, mode: streamMode,
-    identity: authContext.identity ?? null, profile: authContext.profile ?? null
+    identity: authContext.identity ?? null, profile: authContext.profile ?? null,
+    correlationId: authContext.correlationId ?? null
   });
+  countDecision(metrics, { routeContext, mode: streamMode, decision: blocked ? "stream_blocked" : "stream_inspected" });
+  if (blocked) {
+    metrics?.increment("haechi_blocks_total");
+  }
   response.end();
 }
 
@@ -324,12 +727,13 @@ async function* emptyAsyncIterable() {
   // No upstream body to inspect.
 }
 
-async function recordStreamDecision({ runtime, routeContext, blocked, summary, mode, identity = null, profile = null }) {
+async function recordStreamDecision({ runtime, routeContext, blocked, summary, mode, identity = null, profile = null, correlationId = null }) {
   if (typeof runtime.auditSink?.record !== "function") {
     return;
   }
   await runtime.auditSink.record({
     id: randomUUID(),
+    correlationId,
     timestamp: new Date().toISOString(),
     protocol: routeContext?.protocol ?? "proxy",
     operation: `response-stream:${routeContext?.operation ?? "unknown"}`,
@@ -346,7 +750,7 @@ async function recordStreamDecision({ runtime, routeContext, blocked, summary, m
   });
 }
 
-async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, authContext = {}, issuedTokens = [] }) {
+async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, authContext = {}, issuedTokens = [], metrics = null }) {
   const headers = Object.fromEntries(upstreamResponse.headers.entries());
 
   if (!runtime.config.responseProtection.enabled || !routeContext.protectResponse) {
@@ -354,7 +758,8 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
     return {
       status: upstreamResponse.status,
       headers,
-      body: rawBody
+      body: rawBody,
+      decision: "forwarded"
     };
   }
 
@@ -372,6 +777,8 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
       responsePolicy,
       routeContext,
       runtime,
+      correlationId: authContext.correlationId ?? null,
+      metrics,
       hardDeny: true
     });
   }
@@ -388,6 +795,8 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
       responsePolicy,
       routeContext,
       runtime,
+      correlationId: authContext.correlationId ?? null,
+      metrics,
       hardDeny: true
     });
   }
@@ -401,7 +810,9 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
       rawBody,
       responsePolicy,
       routeContext,
-      runtime
+      runtime,
+      correlationId: authContext.correlationId ?? null,
+      metrics
     });
   }
 
@@ -414,7 +825,9 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
       rawBody,
       responsePolicy,
       routeContext,
-      runtime
+      runtime,
+      correlationId: authContext.correlationId ?? null,
+      metrics
     });
   }
 
@@ -430,7 +843,9 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
       rawBody,
       responsePolicy,
       routeContext,
-      runtime
+      runtime,
+      correlationId: authContext.correlationId ?? null,
+      metrics
     });
   }
 
@@ -446,7 +861,9 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
   });
 
   if (result.blocked) {
+    metrics?.increment("haechi_blocks_total");
     return {
+      decision: "response_blocked",
       status: 502,
       headers: { "content-type": "application/json" },
       body: Buffer.from(`${JSON.stringify({
@@ -474,6 +891,7 @@ async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, a
   }
 
   return {
+    decision: "forwarded",
     status: upstreamResponse.status,
     headers: transformedJsonHeaders(headers),
     body: Buffer.from(`${JSON.stringify(responsePayload)}\n`)
@@ -498,7 +916,7 @@ function restoreTokens(value, tokenValues) {
   return value;
 }
 
-async function forward({ upstream, request, body, timeoutMs = null }) {
+async function forward({ upstream, request, body, timeoutMs = null, metrics = null }) {
   const target = buildUpstreamUrl({ upstream, requestUrl: request.url });
   try {
     return await fetch(target, {
@@ -509,12 +927,14 @@ async function forward({ upstream, request, body, timeoutMs = null }) {
     });
   } catch (error) {
     if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+      metrics?.increment("haechi_upstream_timeout_total");
       throw proxyError({
         statusCode: 504,
         errorCode: "haechi_upstream_timeout",
         message: `Upstream did not respond within limits.upstreamTimeoutMs (${timeoutMs})`
       });
     }
+    metrics?.increment("haechi_upstream_error_total");
     throw proxyError({
       statusCode: 502,
       errorCode: "haechi_upstream_unreachable",
@@ -637,27 +1057,39 @@ async function unprotectedResponseDecision({
   responsePolicy,
   routeContext,
   runtime,
+  metrics = null,
+  correlationId = null,
   hardDeny = false
 }) {
   const allowed = responsePolicy.failureMode === "allow" && !hardDeny;
+  const decision = allowed ? "response_unprotected_allowed" : "response_unprotected_blocked";
   await recordProxyDecision({
     runtime,
     routeContext,
-    decision: allowed ? "response_unprotected_allowed" : "response_unprotected_blocked",
+    correlationId,
+    decision,
     reason,
     enforced: !allowed,
     blocked: !allowed
   });
+  // A forwarded-without-protection (or blocked-because-unprotectable) response is
+  // an operability signal. The label is the bounded reason enum, never a value.
+  metrics?.increment("haechi_response_unprotected_total");
 
   if (allowed) {
     return {
+      decision,
       status: upstreamResponse.status,
       headers,
       body: rawBody
     };
   }
 
+  if (!hardDeny) {
+    metrics?.increment("haechi_blocks_total");
+  }
   return {
+    decision,
     status: 502,
     headers: { "content-type": "application/json" },
     body: Buffer.from(`${JSON.stringify({
@@ -738,13 +1170,16 @@ async function cancelReader(reader) {
   }
 }
 
-async function recordProxyDecision({ runtime, routeContext, decision, reason, enforced, blocked, identity = null, profile = null }) {
+async function recordProxyDecision({ runtime, routeContext, decision, reason, enforced, blocked, identity = null, profile = null, correlationId = null }) {
   if (typeof runtime.auditSink?.record !== "function") {
     return;
   }
 
   await runtime.auditSink.record({
     id: randomUUID(),
+    // Per-request correlation id so a proxy-decision event shares the id of the
+    // protect events of the same request. A UUID — never a payload/PII value.
+    correlationId,
     timestamp: new Date().toISOString(),
     protocol: routeContext?.protocol ?? "proxy",
     operation: routeContext ? `proxy:${routeContext.protocol}:${routeContext.routeId ?? "unknown"}` : "proxy",
@@ -804,6 +1239,27 @@ function shortHash(value) {
   return createHash("sha256").update(value).digest("hex").slice(0, 12);
 }
 
+// X-Forwarded-Proto enforcement helper. Node lowercases header names; a comma-
+// joined multi-value header (e.g. "https, http" from a chain of proxies) is
+// trusted only when the FIRST hop — the one closest to the client, set by the
+// trusted terminator — is https. Any other value (http, missing, malformed)
+// fails closed.
+function isForwardedHttps(request) {
+  const raw = request?.headers?.["x-forwarded-proto"];
+  if (typeof raw !== "string" || raw.length === 0) {
+    return false;
+  }
+  const first = raw.split(",")[0].trim().toLowerCase();
+  return first === "https";
+}
+
+// Loopback / remote-bind gate. Loopback always binds (plain http for dev). A
+// non-loopback bind is refused UNLESS allowRemoteBind is set. This is the SHARED
+// primitive the haechi-dashboard satellite reuses, so its contract is preserved
+// unchanged: { host, allowRemoteBind } and nothing more. The WS6 TLS fail-closed
+// rule is layered ON TOP of this in assertSafeProxyTransport (the proxy's own
+// requirement that a remote bind carry TLS), mirroring how the dashboard layers
+// its own tlsContext precedence after calling assertSafeProxyBind.
 export function assertSafeProxyBind({ host = "127.0.0.1", allowRemoteBind = false } = {}) {
   if (allowRemoteBind || isLoopbackHost(host)) {
     return;
@@ -812,6 +1268,35 @@ export function assertSafeProxyBind({ host = "127.0.0.1", allowRemoteBind = fals
   throw new Error(`Refusing to bind Haechi proxy to non-loopback host ${host}. Use --allow-remote-bind only for explicitly secured environments.`);
 }
 
+// WS6 fail-closed TLS requirement for a REMOTE bind. After the loopback/remote
+// gate above, a non-loopback (allowRemoteBind) listener must ALSO carry usable
+// TLS material (Haechi terminates TLS) OR an explicit trustForwardedProto
+// acknowledgement (a trusted reverse proxy terminates TLS in front of Haechi).
+// Neither → THROW: never serve bearer tokens + payloads in plaintext on a remote
+// bind. Loopback dev is exempt (plain http, no TLS needed). Separate from
+// assertSafeProxyBind so the dashboard satellite's reuse of that primitive is
+// unaffected.
+export function assertSafeProxyTransport({
+  host = "127.0.0.1",
+  allowRemoteBind = false,
+  hasUsableTls = false,
+  trustForwardedProto = false
+} = {}) {
+  if (isLoopbackHost(host) || !allowRemoteBind) {
+    // Loopback (or an already-refused remote bind) needs no TLS check here.
+    return;
+  }
+  if (!hasUsableTls && !trustForwardedProto) {
+    throw new Error(
+      `Refusing to bind Haechi proxy to non-loopback host ${host} without TLS. ` +
+        `A remote bind would expose bearer tokens and payloads in plaintext. ` +
+        `Set proxy.tls (a keyFile+certFile or pfxFile so Haechi terminates TLS), ` +
+        `or set proxy.trustForwardedProto: true only when a trusted reverse proxy ` +
+        `terminates TLS in front of Haechi (Haechi will then require X-Forwarded-Proto: https).`
+    );
+  }
+}
+
 function isLoopbackHost(host) {
   const normalized = String(host).trim().toLowerCase();
   return normalized === "localhost"