haechi 1.1.2 → 1.3.0

package/packages/cli/runtime.mjs

@@ -1,4 +1,5 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { createHaechi } from "../core/index.mjs";
 import { createDefaultFilterEngine } from "../filter/index.mjs";
@@ -8,10 +9,11 @@ import { createJsonlAuditSink } from "../audit/index.mjs";
 import { createLocalTokenVault } from "../token-vault/index.mjs";
 import { loadVerifiedPolicyBundleFileSync } from "../policy-bundle/index.mjs";
 import { createProtocolAdapter } from "../protocol-adapters/index.mjs";
+import { createMetrics } from "../metrics/index.mjs";
 import { applyPrivacyProfile, getPrivacyProfile } from "../privacy-profiles/index.mjs";
 import { createBearerAuthProvider } from "../auth/index.mjs";
 import { createSandboxedAuthProviderSync, createProcessIsolatedAuthProviderSync } from "../plugin/index.mjs";
-import { DEFAULT_PROXY_PORT } from "../proxy/index.mjs";
+import { DEFAULT_PROXY_PORT, hasUsableTlsMaterial } from "../proxy/index.mjs";
 
 // Capability keys an operator may allowlist for a plugin. Mirrors the plugin
 // manifest's declared-capability set plus the authProvider-specific
@@ -28,8 +30,17 @@ const KNOWN_PLUGIN_CAPABILITIES = new Set([
 
 export const DEFAULT_CONFIG_PATH = "haechi.config.json";
 
+// Current config schema version. A versioned anchor so a FUTURE breaking schema
+// change has something to compare against. Additive: a config WITHOUT the field
+// is treated as the current version; an unknown/newer value fails closed (a
+// config written by a newer Haechi may use semantics this build does not
+// understand — refuse rather than silently mis-interpret it). See
+// docs/current/config-version.md.
+export const CONFIG_VERSION = 1;
+
 export function defaultConfig() {
   return {
+    configVersion: CONFIG_VERSION,
     mode: "dry-run",
     target: {
       type: "llm-http",
@@ -38,7 +49,17 @@ export function defaultConfig() {
     },
     proxy: {
       host: "127.0.0.1",
-      port: DEFAULT_PROXY_PORT
+      port: DEFAULT_PROXY_PORT,
+      // WS6 TLS hardening (additive; defaults preserve 1.1 loopback-plain-http
+      // behavior). proxy.tls null = no TLS material; a non-null object is file
+      // PATHS loaded at startup into a tlsContext: { keyFile, certFile } or
+      // { pfxFile, passphrase? }. A remote (non-loopback) bind REQUIRES either a
+      // usable tlsContext OR trustForwardedProto (see assertSafeProxyBind).
+      // proxy.trustForwardedProto false = the operator has NOT acknowledged a
+      // fronting TLS terminator; true = a trusted reverse proxy terminates TLS in
+      // front of Haechi (Haechi then enforces X-Forwarded-Proto: https).
+      tls: null,
+      trustForwardedProto: false
     },
     responseProtection: {
       enabled: false,
@@ -57,7 +78,16 @@ export function defaultConfig() {
     limits: {
       maxRequestBytes: 1048576,
       maxNestingDepth: 256,
-      upstreamTimeoutMs: 120000
+      upstreamTimeoutMs: 120000,
+      // WS4-B resilience (additive; defaults preserve 1.1 behavior).
+      // maxInFlight 0 = backpressure disabled (no ceiling). shutdownGraceMs is
+      // the graceful-drain grace period before in-flight requests/keep-alive
+      // sockets are force-closed on close(). requestTimeoutMs/headersTimeoutMs
+      // are null = leave Node's server defaults untouched; set a number to tune.
+      maxInFlight: 0,
+      shutdownGraceMs: 10000,
+      requestTimeoutMs: null,
+      headersTimeoutMs: null
     },
     policy: {
       mode: "dry-run",
@@ -68,7 +98,18 @@ export function defaultConfig() {
       }
     },
     filters: {
-      customRules: []
+      customRules: [],
+      // WS2c precision dials. minConfidence 0 = current behavior (gate nothing);
+      // allowlist [] = no operator FP exceptions. Both additive; neither can
+      // suppress a hard-block type (secret/api_key/kr_rrn/card) — see core.
+      minConfidence: 0,
+      allowlist: [],
+      // WS2d residual — opt-in base64/percent decode-and-rescan. Default false =
+      // byte-identical to prior behavior (no decode). When true, a string leaf
+      // that looks base64/percent-encoded is decoded and rescanned; a decoded
+      // hit fails closed to a WHOLE-LEAF detection and only fires for a validator-
+      // backed / hard-block match (precision guard against random-base64 FPs).
+      decodeAndRescan: false
     },
     keys: {
       provider: "local",
@@ -95,6 +136,19 @@ export function defaultConfig() {
     privacy: {
       profile: null
     },
+    // WS4-A operability. Additive; defaults preserve 1.1 behavior.
+    // logging.format "text" = the current human-readable lines; "json" = a single
+    // JSON line per event (startup/shutdown/error) carrying a correlationId but
+    // NEVER a payload/header/token/PII value.
+    logging: {
+      format: "text"
+    },
+    // metrics.enabled gates the /__haechi/metrics route. Default true; when false
+    // the route returns 404. The metric surface is a bounded enum — no per-identity
+    // or per-value label cardinality (see packages/metrics/index.mjs).
+    metrics: {
+      enabled: true
+    },
     auth: {
       provider: "none",
       store: ".haechi/auth.json",
@@ -117,7 +171,88 @@ export function defaultConfig() {
 
 export async function loadConfig(configPath = DEFAULT_CONFIG_PATH) {
   const raw = JSON.parse(await readFile(configPath, "utf8"));
-  return normalizeConfig(raw);
+  const overlaid = applyEnvOverlay(raw, process.env);
+  return normalizeConfig(overlaid);
+}
+
+// WS4-B env-var configuration overlay. A FIXED ALLOWLIST of NON-SECRET
+// operational keys may be overridden from the environment for container/12-factor
+// deploys; env WINS over the file for these. Applied AFTER reading the file and
+// BEFORE normalizeConfig, so the overlaid value goes through the same fail-closed
+// validation. An invalid env value (bad port, unknown mode) THROWS — it is never
+// silently ignored — naming the offending variable.
+//
+// SECURITY: secrets/keys/tokens are DELIBERATELY NOT overlayable. There is no
+// HAECHI_* key for keys.*, the auth store/tokens, or any path-to-key — those stay
+// in the config file or are supplied via injected providers. Adding a secret to
+// this allowlist would invite leaking it through a process environment.
+const ENV_OVERLAY = [
+  {
+    env: "HAECHI_PROXY_PORT",
+    apply(config, value) {
+      const port = Number(value);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`HAECHI_PROXY_PORT must be an integer from 0 to 65535 (got: ${JSON.stringify(value)})`);
+      }
+      config.proxy = { ...(config.proxy ?? {}), port };
+    }
+  },
+  {
+    env: "HAECHI_PROXY_HOST",
+    apply(config, value) {
+      if (typeof value !== "string" || !value.trim()) {
+        throw new Error("HAECHI_PROXY_HOST must be a non-empty string");
+      }
+      config.proxy = { ...(config.proxy ?? {}), host: value };
+    }
+  },
+  {
+    env: "HAECHI_UPSTREAM",
+    apply(config, value) {
+      if (typeof value !== "string" || !value.trim()) {
+        throw new Error("HAECHI_UPSTREAM must be a non-empty URL string");
+      }
+      try {
+        // eslint-disable-next-line no-new
+        new URL(value);
+      } catch {
+        throw new Error(`HAECHI_UPSTREAM must be a valid URL (got: ${JSON.stringify(value)})`);
+      }
+      config.target = { ...(config.target ?? {}), upstream: value };
+    }
+  },
+  {
+    env: "HAECHI_MODE",
+    apply(config, value) {
+      if (!["dry-run", "report-only", "enforce"].includes(value)) {
+        throw new Error(`HAECHI_MODE must be one of dry-run|report-only|enforce (got: ${JSON.stringify(value)})`);
+      }
+      config.mode = value;
+    }
+  },
+  {
+    env: "HAECHI_LOG_FORMAT",
+    apply(config, value) {
+      if (!["text", "json"].includes(value)) {
+        throw new Error(`HAECHI_LOG_FORMAT must be "text" or "json" (got: ${JSON.stringify(value)})`);
+      }
+      config.logging = { ...(config.logging ?? {}), format: value };
+    }
+  }
+];
+
+export function applyEnvOverlay(rawConfig, env = process.env) {
+  // Clone shallowly so we don't mutate the caller's object; nested objects we
+  // touch are themselves shallow-cloned in each apply().
+  const config = { ...rawConfig };
+  for (const { env: key, apply } of ENV_OVERLAY) {
+    const value = env[key];
+    if (value === undefined) {
+      continue;
+    }
+    apply(config, value);
+  }
+  return config;
 }
 
 export async function writeDefaultConfig(configPath = DEFAULT_CONFIG_PATH, { force = false } = {}) {
@@ -194,12 +329,30 @@ export function createRuntime(config, providers = {}) {
 
   const authProvider = resolveAuthProvider(normalized, providers, cryptoProvider, auditSink);
 
+  // The proxy's per-identity request rate limiter is an injectable collaborator,
+  // mirroring cryptoProvider/auditSink/tokenVault. The default is a per-process
+  // in-memory fixed-window counter; a multi-replica operator injects a
+  // shared-store implementation. Fail closed at construction if it lacks allow().
+  const rateLimiter = providers.rateLimiter ?? createRateLimiter();
+  assertProvider("rateLimiter", rateLimiter, ["allow"]);
+
+  // WS4-A telemetry seam. The metrics collector is an injectable collaborator,
+  // mirroring auditSink/rateLimiter. The default is a zero-dep in-memory
+  // Prometheus-text collector; a multi-replica operator injects a shared/remote
+  // collector exposing the same increment/observe/render contract. The proxy
+  // reads runtime.metrics. The metric surface is a bounded enum — never an
+  // identity/value label (no-PII-in-telemetry invariant; see metrics module).
+  const metrics = providers.metrics ?? createMetrics();
+  assertProvider("metrics", metrics, ["increment", "observe", "render"]);
+
   return {
     config: normalized,
     tokenVault,
     auditSink,
     authProvider,
     policyProfiles,
+    rateLimiter,
+    metrics,
     protocolAdapter: createProtocolAdapter(normalized.target),
     haechi: createHaechi({
       mode: normalized.mode,
@@ -210,7 +363,14 @@ export function createRuntime(config, providers = {}) {
       auditSink,
       // Bound recursion depth so a deeply-nested payload fails closed (4xx)
       // rather than overflowing the stack (uncaught 500).
-      limits: { maxNestingDepth: normalized.limits.maxNestingDepth }
+      limits: { maxNestingDepth: normalized.limits.maxNestingDepth },
+      // WS2c precision controls (additive; defaults preserve 1.1 behavior). The
+      // detect→decide path drops sub-minConfidence soft detections and suppresses
+      // allowlisted soft detections — never a hard-block type (enforced in core).
+      precision: {
+        minConfidence: normalized.filters.minConfidence,
+        allowlist: normalized.filters.allowlist
+      }
     })
   };
 }
@@ -219,14 +379,14 @@ export function normalizeConfig(config) {
   const merged = {
     ...defaultConfig(),
     ...config,
+    // A config that omits configVersion (e.g. a 1.1 file written before the
+    // stamp existed) is treated as the current version, not undefined.
+    configVersion: config.configVersion ?? CONFIG_VERSION,
     target: {
       ...defaultConfig().target,
       ...(config.target ?? {})
     },
-    proxy: {
-      ...defaultConfig().proxy,
-      ...(config.proxy ?? {})
-    },
+    proxy: normalizeProxy(config.proxy),
     responseProtection: {
       ...defaultConfig().responseProtection,
       ...(config.responseProtection ?? {})
@@ -271,6 +431,14 @@ export function normalizeConfig(config) {
       ...defaultConfig().privacy,
       ...(config.privacy ?? {})
     },
+    logging: {
+      ...defaultConfig().logging,
+      ...(config.logging ?? {})
+    },
+    metrics: {
+      ...defaultConfig().metrics,
+      ...(config.metrics ?? {})
+    },
     auth: {
       ...defaultConfig().auth,
       ...(config.auth ?? {}),
@@ -296,6 +464,18 @@ export function normalizeConfig(config) {
   if (!isValidPort(merged.proxy.port)) {
     throw new Error("proxy.port must be an integer from 0 to 65535");
   }
+  if (typeof merged.proxy.trustForwardedProto !== "boolean") {
+    throw new Error("proxy.trustForwardedProto must be boolean");
+  }
+  // proxy.tls has already been resolved by normalizeProxy into either null or a
+  // usable tlsContext ({ key, cert } or { pfx, passphrase? }). A non-null value
+  // that is not usable TLS material is a fail-closed error (it would otherwise
+  // green-light a remote bind that then serves plaintext). normalizeProxy throws
+  // first for a malformed shape / unreadable file; this is the belt-and-braces
+  // material assertion mirroring the dashboard's tlsContext check.
+  if (merged.proxy.tls !== null && !hasUsableTlsMaterial(merged.proxy.tls)) {
+    throw new Error("proxy.tls must resolve to usable TLS material ((key && cert) or pfx)");
+  }
   if (merged.audit.sink !== "jsonl") {
     throw new Error("Current implementation only supports jsonl audit sink");
   }
@@ -345,6 +525,12 @@ export function normalizeConfig(config) {
   if (merged.privacy.profile) {
     getPrivacyProfile(merged.privacy.profile);
   }
+  if (!["text", "json"].includes(merged.logging.format)) {
+    throw new Error(`Invalid logging.format: ${merged.logging.format} (expected "text" or "json")`);
+  }
+  if (typeof merged.metrics.enabled !== "boolean") {
+    throw new Error("metrics.enabled must be boolean");
+  }
   if (!["fail-closed", "allow"].includes(merged.responseProtection.failureMode)) {
     throw new Error(`Invalid responseProtection.failureMode: ${merged.responseProtection.failureMode}`);
   }
@@ -372,7 +558,33 @@ export function normalizeConfig(config) {
   if (typeof merged.limits.upstreamTimeoutMs !== "number" || merged.limits.upstreamTimeoutMs < 1) {
     throw new Error("limits.upstreamTimeoutMs must be a positive number");
   }
+  // WS4-B resilience limits, fail-closed. maxInFlight 0 disables the ceiling.
+  if (!Number.isInteger(merged.limits.maxInFlight) || merged.limits.maxInFlight < 0) {
+    throw new Error("limits.maxInFlight must be a non-negative integer (0 disables the in-flight ceiling)");
+  }
+  if (!Number.isInteger(merged.limits.shutdownGraceMs) || merged.limits.shutdownGraceMs < 0) {
+    throw new Error("limits.shutdownGraceMs must be a non-negative integer (milliseconds)");
+  }
+  // requestTimeoutMs/headersTimeoutMs: null leaves Node's server default; a set
+  // value must be a non-negative integer (0 disables that timeout, Node semantics).
+  for (const field of ["requestTimeoutMs", "headersTimeoutMs"]) {
+    const value = merged.limits[field];
+    if (value !== null && value !== undefined
+      && (!Number.isInteger(value) || value < 0)) {
+      throw new Error(`limits.${field} must be null or a non-negative integer (milliseconds; 0 disables the timeout)`);
+    }
+  }
+  // configVersion: a versioned anchor for future schema changes. Fail closed on a
+  // newer/unknown version (a config a newer Haechi wrote may use semantics this
+  // build does not understand) and on a non-positive-integer value.
+  if (!Number.isInteger(merged.configVersion) || merged.configVersion < 1) {
+    throw new Error("configVersion must be a positive integer");
+  }
+  if (merged.configVersion > CONFIG_VERSION) {
+    throw new Error(`Unsupported configVersion ${merged.configVersion}: this Haechi build understands configVersion <= ${CONFIG_VERSION}. Upgrade Haechi or lower configVersion (see docs/current/config-version.md).`);
+  }
   validatePolicyExtras(merged.policy);
+  validateFilters(merged.filters);
   if (!["none", "bearer", "external", "plugin"].includes(merged.auth.provider)) {
     throw new Error(`Invalid auth.provider: ${merged.auth.provider}`);
   }
@@ -394,6 +606,129 @@ export function isValidPort(port) {
   return Number.isInteger(port) && port >= 0 && port <= 65535;
 }
 
+// WS6 proxy normalization. Shallow-merges proxy over the default and resolves
+// proxy.tls from FILE PATHS into a tlsContext loaded at startup. proxy.tls may be:
+//   - null (default): no TLS material.
+//   - { keyFile, certFile }: PEM key+cert file paths → { key, cert }.
+//   - { pfxFile, passphrase? }: a PKCS#12 file path → { pfx, passphrase? }.
+// Fail-closed, enumerated throws: an unknown shape, a missing required field, an
+// unreadable file, or a mix of pfx and key/cert all throw at config time rather
+// than degrading to a plaintext listener later. The loaded buffers ARE the
+// tlsContext handed to https.createServer; node:fs.readFileSync is a builtin
+// (zero runtime dependency).
+function normalizeProxy(proxy) {
+  const merged = {
+    ...defaultConfig().proxy,
+    ...(proxy ?? {})
+  };
+  merged.tls = resolveProxyTls(merged.tls);
+  return merged;
+}
+
+function resolveProxyTls(tls) {
+  if (tls === undefined || tls === null) {
+    return null;
+  }
+  if (typeof tls !== "object" || Array.isArray(tls)) {
+    throw new Error("proxy.tls must be null or an object ({ keyFile, certFile } or { pfxFile, passphrase? })");
+  }
+  // Already a loaded tlsContext (a hand-built config passing { key, cert } / { pfx }
+  // directly, e.g. a test or an embedder) — accept it as-is; the material check in
+  // normalizeConfig still gates it. Only resolve the FILE-PATH form below.
+  const hasFilePaths = tls.keyFile !== undefined || tls.certFile !== undefined || tls.pfxFile !== undefined;
+  const hasInlineMaterial = tls.key !== undefined || tls.cert !== undefined || tls.pfx !== undefined;
+  if (hasInlineMaterial && !hasFilePaths) {
+    return tls;
+  }
+
+  const usingPfx = tls.pfxFile !== undefined;
+  const usingKeyCert = tls.keyFile !== undefined || tls.certFile !== undefined;
+  if (usingPfx && usingKeyCert) {
+    throw new Error("proxy.tls must use either { keyFile, certFile } or { pfxFile }, not both");
+  }
+  if (!usingPfx && !usingKeyCert) {
+    throw new Error("proxy.tls must set { keyFile, certFile } or { pfxFile }");
+  }
+
+  if (usingPfx) {
+    if (typeof tls.pfxFile !== "string" || !tls.pfxFile.trim()) {
+      throw new Error("proxy.tls.pfxFile must be a non-empty string path");
+    }
+    if (tls.passphrase !== undefined && typeof tls.passphrase !== "string") {
+      throw new Error("proxy.tls.passphrase must be a string when set");
+    }
+    const context = { pfx: readTlsFile(tls.pfxFile, "proxy.tls.pfxFile") };
+    if (tls.passphrase !== undefined) {
+      context.passphrase = tls.passphrase;
+    }
+    return context;
+  }
+
+  if (typeof tls.keyFile !== "string" || !tls.keyFile.trim()) {
+    throw new Error("proxy.tls.keyFile must be a non-empty string path");
+  }
+  if (typeof tls.certFile !== "string" || !tls.certFile.trim()) {
+    throw new Error("proxy.tls.certFile must be a non-empty string path");
+  }
+  return {
+    key: readTlsFile(tls.keyFile, "proxy.tls.keyFile"),
+    cert: readTlsFile(tls.certFile, "proxy.tls.certFile")
+  };
+}
+
+function readTlsFile(path, label) {
+  try {
+    return readFileSync(path);
+  } catch (error) {
+    throw new Error(`${label} could not be read: ${error.code ?? error.message}`);
+  }
+}
+
+// Fail-closed validation of the WS2c precision controls. minConfidence is a
+// number in [0,1]; allowlist is an array of exact-value strings and/or
+// { value?, path? } objects (at least one of value/path must be a non-empty
+// string). A malformed config throws rather than silently degrading.
+function validateFilters(filters) {
+  if (filters.minConfidence !== undefined) {
+    if (typeof filters.minConfidence !== "number" || Number.isNaN(filters.minConfidence)
+      || filters.minConfidence < 0 || filters.minConfidence > 1) {
+      throw new Error("filters.minConfidence must be a number in [0, 1]");
+    }
+  }
+  if (filters.allowlist !== undefined) {
+    if (!Array.isArray(filters.allowlist)) {
+      throw new Error("filters.allowlist must be an array");
+    }
+    for (const entry of filters.allowlist) {
+      if (typeof entry === "string") {
+        if (!entry) {
+          throw new Error("filters.allowlist string entries must be non-empty");
+        }
+        continue;
+      }
+      if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new Error("filters.allowlist entries must be a string or a { value?, path? } object");
+      }
+      const hasValue = entry.value !== undefined;
+      const hasPath = entry.path !== undefined;
+      if (!hasValue && !hasPath) {
+        throw new Error("filters.allowlist object entries must set value and/or path");
+      }
+      if (hasValue && (typeof entry.value !== "string" || !entry.value)) {
+        throw new Error("filters.allowlist entry.value must be a non-empty string");
+      }
+      if (hasPath && (typeof entry.path !== "string" || !entry.path)) {
+        throw new Error("filters.allowlist entry.path must be a non-empty string");
+      }
+    }
+  }
+  // WS2d residual — opt-in base64/percent decode-and-rescan. Strict boolean,
+  // fail-closed: a non-boolean throws rather than silently coercing.
+  if (filters.decodeAndRescan !== undefined && typeof filters.decodeAndRescan !== "boolean") {
+    throw new Error("filters.decodeAndRescan must be a boolean");
+  }
+}
+
 function validatePolicyExtras(policy) {
   if (policy.modelAllowlist !== undefined) {
     assertModelAllowlist(policy.modelAllowlist, "policy.modelAllowlist");
@@ -667,6 +1002,63 @@ function createConfiguredCryptoProvider(config) {
   return createLocalCryptoProvider({ keyFile: config.keys.keyFile });
 }
 
+// Default rate limiter: an in-memory fixed-window counter keyed by identity.
+// Per-process — it resets on restart and is NOT shared across replicas, so a
+// multi-replica operator injects a shared-store implementation via
+// createRuntime(config, { rateLimiter }) (see shared-responsibility.md §4).
+//
+// The window Map is self-bounding via a lazy, amortized sweep — NO timer (a
+// setInterval would keep the event loop alive and hang `node --test`). On
+// allow(), when the Map crosses a size threshold we evict a bounded number of
+// fully-expired entries (now - windowStart >= windowMs). A one-shot identity's
+// slot therefore does not linger forever once it ages past its window. The
+// allow(key, limit) -> boolean contract and the fixed-window 429 semantics are
+// unchanged; only stale bookkeeping is reclaimed.
+export function createRateLimiter({ windowMs = 60000, sweepThreshold = 1024, sweepBudget = 256 } = {}) {
+  const windows = new Map();
+
+  function sweepExpired(now) {
+    // Bounded amortized eviction: scan at most sweepBudget entries per call (Map
+    // iteration is insertion-ordered, so the oldest keys are visited first) and
+    // drop any whose window has fully elapsed. Amortized O(1) per allow().
+    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();
+      // Reclaim aged-out one-shot identities before they accumulate unbounded.
+      if (windows.size >= sweepThreshold) {
+        sweepExpired(now);
+      }
+      const slot = windows.get(key);
+      if (!slot || now - slot.windowStart >= windowMs) {
+        windows.set(key, { windowStart: now, count: 1 });
+        return true;
+      }
+      if (slot.count >= limit) {
+        return false;
+      }
+      slot.count += 1;
+      return true;
+    },
+    // Test-only introspection of the live window count. Innocuous: it exposes a
+    // bare integer, never any key/identity value.
+    _size() {
+      return windows.size;
+    }
+  };
+}
+
 function assertProvider(name, provider, methods) {
   for (const method of methods) {
     if (typeof provider?.[method] !== "function") {