haechi 1.1.2 → 1.3.0

package/examples/local-proxy-demo/live-demo.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Live end-to-end demo against a REAL upstream model (vLLM / Ollama / any
+// OpenAI-compatible server). Unlike demo.mjs (which uses a deterministic stub),
+// this proves protection against an actual model: it asks the model to repeat the
+// phone number it was given, and the model can only return the *masked* form —
+// the real number never reached it.
+//
+//   HAECHI_LIVE_UPSTREAM=http://127.0.0.1:8000 \
+//   HAECHI_LIVE_MODEL="Qwen/Qwen3.6-35B-A3B-FP8" \
+//   node examples/local-proxy-demo/live-demo.mjs
+//
+// Defaults: type=vllm-openai. HAECHI_LIVE_TYPE and HAECHI_LIVE_MODEL override.
+// Zero dependencies — only node: builtins + the in-repo haechi packages.
+
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createRuntime } from "../../packages/cli/runtime.mjs";
+import { createHaechiProxy } from "../../packages/proxy/index.mjs";
+import { initLocalKeyFile } from "../../packages/crypto/index.mjs";
+
+const B = "\x1b[1m", D = "\x1b[2m", G = "\x1b[32m", Y = "\x1b[33m", C = "\x1b[36m", R = "\x1b[31m", X = "\x1b[0m";
+const rule = () => console.log(D + "─".repeat(64) + X);
+const scene = (n, t) => { console.log(); rule(); console.log(`${B}${C}  ${n}. ${t}${X}`); rule(); };
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const UPSTREAM = process.env.HAECHI_LIVE_UPSTREAM;
+const TYPE = process.env.HAECHI_LIVE_TYPE || "vllm-openai";
+const MODEL = process.env.HAECHI_LIVE_MODEL || "Qwen/Qwen3.6-35B-A3B-FP8";
+if (!UPSTREAM) {
+  console.error("Set HAECHI_LIVE_UPSTREAM (e.g. http://127.0.0.1:8000) to a reachable OpenAI-compatible server.");
+  console.error("For a no-backend reproducible run, use:  npm run demo");
+  process.exit(2);
+}
+
+async function chat(base, content, extra = {}) {
+  const t0 = Date.now();
+  const res = await fetch(`${base}/v1/chat/completions`, {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ model: MODEL, max_tokens: 128, temperature: 0,
+      // Qwen3 reasoning models: ask for a direct answer (no chain-of-thought) so
+      // the demo gets a terse content reply. Ignored by non-reasoning servers.
+      chat_template_kwargs: { enable_thinking: false },
+      messages: [{ role: "user", content }], ...extra })
+  });
+  const body = await res.json();
+  return { status: res.status, ms: Date.now() - t0, text: body.choices?.[0]?.message?.content ?? body.error?.message ?? "(no content)" };
+}
+
+async function main() {
+  console.log(`\n${B}🛡  Haechi — LIVE end-to-end demo${X}  ${D}(real model: ${MODEL} via ${TYPE}, enforce mode)${X}`);
+
+  const dir = await mkdtemp(join(tmpdir(), "haechi-live-"));
+  const keyFile = join(dir, ".haechi", "dev.keys.json");
+  const auditPath = join(dir, ".haechi", "audit.jsonl");
+  await initLocalKeyFile(keyFile, { force: true });
+
+  const runtime = createRuntime({
+    mode: "enforce",
+    target: { type: TYPE, upstream: UPSTREAM },
+    policy: { mode: "enforce", presets: ["llm-redact"], actions: { email: "tokenize", phone: "mask", secret: "redact", api_key: "redact", card: "block" } },
+    tokenVault: { detokenizeResponses: true },
+    responseProtection: { enabled: true, mode: "enforce", failureMode: "fail-closed" },
+    keys: { keyFile }, audit: { path: auditPath }
+  });
+  const proxy = createHaechiProxy({ runtime, port: 0 });
+  const addr = await proxy.listen();
+  const base = `http://127.0.0.1:${addr.port}`;
+
+  // ── Scene 1 ────────────────────────────────────────────────────────────────
+  scene(1, "Ask a REAL model to repeat the phone number you give it");
+  const prompt = "Reply in one short line: repeat the phone number you were given. Phone: 010-1234-5678, email minji.kim@example.com";
+  console.log(`${Y}you send →${X} ${prompt}`);
+  await pause(700);
+  const r1 = await chat(base, prompt);
+
+  scene(2, "Haechi detected + protected the prompt BEFORE it left your machine");
+  const events = (await readFile(auditPath, "utf8")).trim().split("\n").map((l) => JSON.parse(l));
+  const ev = events.find((e) => Array.isArray(e.detections) && e.detections.length) ?? events[0];
+  console.log(`${D}detections:${X} ${(ev.detections ?? []).map((d) => `${G}${d.type}→${d.action}${X}`).join("  ")}`);
+  console.log(`${D}the model only ever saw:${X} email → ${C}[TOKEN:…]${X},  phone → ${C}01*********78${X}`);
+  await pause(700);
+
+  scene(3, "The real model replies — it can only return the MASKED phone");
+  console.log(`${G}${MODEL.split("/").pop()} →${X} ${B}${r1.text}${X}   ${D}(${r1.ms} ms)${X}`);
+  console.log(`${D}  your real number 010-1234-5678 never reached the model — it cannot reveal it.${X}`);
+  await pause(700);
+
+  // ── Scene 4 ────────────────────────────────────────────────────────────────
+  scene(4, "The audit log — hash-chained, and never any plaintext");
+  const auditRaw = await readFile(auditPath, "utf8");
+  console.log(`${D}leaks the real email/phone?${X} ${/minji\.kim@example|010-1234-5678/.test(auditRaw) ? R + "YES" + X : G + "no — clean" + X}`);
+  await pause(700);
+
+  // ── Scene 5 ────────────────────────────────────────────────────────────────
+  scene(5, "Day-2 operability — live readiness + Prometheus metrics");
+  const ready = await (await fetch(`${base}/__haechi/ready`)).json();
+  console.log(`${D}/__haechi/ready →${X} ${ready.ready ? G + "ready" : R + "not ready"}${X}`);
+  const metrics = await (await fetch(`${base}/__haechi/metrics`)).text();
+  for (const line of metrics.split("\n").filter((l) => /^haechi_requests_total\{/.test(l)).slice(0, 3)) {
+    console.log(`${D}metric:${X} ${line}`);
+  }
+  await pause(700);
+
+  // ── Scene 6 ────────────────────────────────────────────────────────────────
+  scene(6, "A card number is blocked before it ever reaches the model");
+  const r2 = await chat(base, "charge card 4242 4242 4242 4242 now");
+  console.log(`${Y}you send →${X} "charge card 4242 4242 4242 4242 now"`);
+  console.log(`${G}proxy →${X} HTTP ${r2.status} ${r2.status === 403 ? R + B + "BLOCKED" + X : ""} ${D}(no upstream call made)${X}`);
+
+  console.log();
+  rule();
+  console.log(`${B}${G}  ✓ live${X}  ${D}— a real model, and your PII never left the gateway in the clear.${X}`);
+  rule();
+  console.log();
+
+  await proxy.close();
+}
+
+main().then(() => process.exit(0)).catch((e) => { console.error("live demo failed:", e); process.exit(1); });

package/examples/local-proxy-demo/live-demo.tape

@@ -0,0 +1,25 @@
+# VHS tape for the Haechi LIVE demo (real upstream model).
+# Regenerate the README GIF with:
+#   HAECHI_LIVE_UPSTREAM is set below via Env so it stays out of the recording.
+#   vhs examples/local-proxy-demo/live-demo.tape    (run from the repo root)
+
+Output docs/assets/haechi-demo.gif
+
+Set Shell "bash"
+Set FontSize 15
+Set Width 1180
+Set Height 840
+Set Padding 18
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 55ms
+
+# Point these at a reachable OpenAI-compatible server before recording. Using Env
+# (not the typed command) keeps the upstream URL out of the captured GIF.
+Env HAECHI_LIVE_UPSTREAM "http://127.0.0.1:8000"
+Env HAECHI_LIVE_MODEL "Qwen/Qwen3.6-35B-A3B-FP8"
+
+Sleep 500ms
+Type "node examples/local-proxy-demo/live-demo.mjs"
+Sleep 600ms
+Enter
+Sleep 9s

package/haechi.config.example.json

@@ -1,4 +1,5 @@
 {
+  "configVersion": 1,
   "mode": "dry-run",
   "target": {
     "type": "llm-http",
@@ -7,7 +8,9 @@
   },
   "proxy": {
     "host": "127.0.0.1",
-    "port": 11016
+    "port": 11016,
+    "tls": null,
+    "trustForwardedProto": false
   },
   "responseProtection": {
     "enabled": false,
@@ -25,7 +28,12 @@
   },
   "limits": {
     "maxRequestBytes": 1048576,
-    "upstreamTimeoutMs": 120000
+    "maxNestingDepth": 256,
+    "upstreamTimeoutMs": 120000,
+    "maxInFlight": 0,
+    "shutdownGraceMs": 10000,
+    "requestTimeoutMs": null,
+    "headersTimeoutMs": null
   },
   "policy": {
     "mode": "dry-run",
@@ -40,7 +48,10 @@
     }
   },
   "filters": {
-    "customRules": []
+    "customRules": [],
+    "minConfidence": 0,
+    "allowlist": [],
+    "decodeAndRescan": false
   },
   "keys": {
     "provider": "local",
@@ -67,6 +78,12 @@
   "privacy": {
     "profile": null
   },
+  "logging": {
+    "format": "text"
+  },
+  "metrics": {
+    "enabled": true
+  },
   "auth": {
     "provider": "none",
     "store": ".haechi/auth.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haechi",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Self-hosted AI context enforcement across LLM, MCP, vLLM, Ollama, and agent traffic — a stable, zero-dependency security gateway.",
   "license": "Apache-2.0",
   "type": "module",
@@ -51,7 +51,8 @@
     "./token-vault": "./packages/token-vault/index.mjs",
     "./stream-filter": "./packages/stream-filter/index.mjs",
     "./auth": "./packages/auth/index.mjs",
-    "./ssrf": "./packages/ssrf/index.mjs"
+    "./ssrf": "./packages/ssrf/index.mjs",
+    "./metrics": "./packages/metrics/index.mjs"
   },
   "files": [
     "README.md",
@@ -74,10 +75,14 @@
     "sbom": "node scripts/generate-sbom.mjs",
     "checksums": "node scripts/release-checksums.mjs",
     "bench:payload": "node scripts/bench-payload.mjs",
+    "bench:detection": "node scripts/bench-detection.mjs",
+    "bench:throughput": "node scripts/bench-throughput.mjs",
+    "scan:detection": "node scripts/bench-detection.mjs --gate",
     "check:peer-ranges": "node scripts/check-satellite-peer-ranges.mjs",
     "release:preflight": "node scripts/release-preflight.mjs && node scripts/check-satellite-peer-ranges.mjs",
     "release:preflight:npm": "node scripts/release-preflight.mjs --require-npm-auth && node scripts/check-satellite-peer-ranges.mjs",
     "haechi": "node packages/cli/bin/haechi.mjs",
+    "demo": "node examples/local-proxy-demo/demo.mjs",
     "demo:init": "node packages/cli/bin/haechi.mjs init --force",
     "demo:protect": "node packages/cli/bin/haechi.mjs protect examples/llm-prompt-filtering/input.json --config haechi.config.json",
     "demo:report": "node packages/cli/bin/haechi.mjs report --audit .haechi/audit.jsonl"

package/packages/audit/index.mjs

@@ -1,5 +1,5 @@
-import { createReadStream } from "node:fs";
-import { appendFile, mkdir, open, stat, unlink } from "node:fs/promises";
+import { createReadStream, constants as fsConstants } from "node:fs";
+import { access, appendFile, mkdir, open, stat, unlink } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { dirname } from "node:path";
 import { createInterface } from "node:readline";
@@ -91,6 +91,30 @@ export function createJsonlAuditSink({ path, anchor = null }) {
       });
       writeQueue = write.catch(() => {});
       await write;
+    },
+
+    // WS4-A readiness probe: a CHEAP writability check used by /__haechi/ready.
+    // A security gateway that cannot append to its audit log is NOT ready
+    // (fail-closed), so this confirms the audit directory exists and is writable
+    // WITHOUT writing an event (no audit-chain side effect). It returns the bare
+    // boolean and an enum reason — never a path value or any payload/PII.
+    async ready() {
+      try {
+        const dir = dirname(path);
+        await mkdir(dir, { recursive: true });
+        await access(dir, fsConstants.W_OK);
+        // If the audit file already exists, confirm it is writable too.
+        try {
+          await access(path, fsConstants.W_OK);
+        } catch (error) {
+          if (error.code !== "ENOENT") {
+            return { ok: false, reason: "audit_file_not_writable" };
+          }
+        }
+        return { ok: true };
+      } catch {
+        return { ok: false, reason: "audit_dir_not_writable" };
+      }
     }
   };
 }

package/packages/cli/bin/haechi.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFile, stat } from "node:fs/promises";
 import { readAuditSummary, verifyAuditChain } from "../../audit/index.mjs";
-import { DEFAULT_PROXY_PORT, createHaechiProxy } from "../../proxy/index.mjs";
+import { DEFAULT_PROXY_PORT, HAECHI_VERSION, createHaechiProxy } from "../../proxy/index.mjs";
 import { signPolicyBundleFile, verifyPolicyBundleFile } from "../../policy-bundle/index.mjs";
 import { validatePluginManifestFile } from "../../plugin/index.mjs";
 import { runMcpStdioFilter, wrapMcpChild } from "../../mcp-stdio/index.mjs";
@@ -283,25 +283,69 @@ async function proxyCommand(argv) {
   const port = parsePort(options.port ?? config.proxy.port);
   const host = options.host ?? config.proxy.host;
   const allowRemoteBind = Boolean(options["allow-remote-bind"]);
+  // proxy.tls / proxy.trustForwardedProto come from the normalized config (the
+  // TLS material is loaded from file paths at load time); createHaechiProxy reads
+  // them from runtime.config.proxy, so the CLI does not re-pass them. The bind
+  // guard inside createHaechiProxy throws fail-closed for a remote bind without
+  // TLS and without trustForwardedProto.
   const proxy = createHaechiProxy({ runtime, port, host, allowRemoteBind });
   const address = await proxy.listen();
+  const scheme = address.tls ? "https" : "http";
 
   const effectiveMode = config.policy.mode ?? config.mode;
-  console.log(`Haechi proxy listening on http://${address.host}:${address.port}`);
-  console.log(`Upstream: ${config.target.upstream}`);
-  console.log(`Mode: ${effectiveMode}`);
+  const jsonLogs = config.logging?.format === "json";
+  // Structured startup/shutdown logs honor logging.format. JSON mode emits one
+  // line per event carrying only non-secret operational fields (host/port/mode/
+  // version/warning codes) — never a payload, token, or PII value.
+  const logEvent = (level, event, fields = {}) => {
+    if (jsonLogs) {
+      const stream = level === "warn" ? process.stderr : process.stdout;
+      stream.write(`${JSON.stringify({ level, event, ...fields })}\n`);
+    }
+  };
+
+  if (jsonLogs) {
+    logEvent("info", "proxy_listening", {
+      host: address.host,
+      port: address.port,
+      scheme,
+      tls: Boolean(address.tls),
+      upstream: config.target.upstream,
+      mode: effectiveMode,
+      version: HAECHI_VERSION
+    });
+  } else {
+    console.log(`Haechi proxy listening on ${scheme}://${address.host}:${address.port}`);
+    console.log(`Upstream: ${config.target.upstream}`);
+    console.log(`Mode: ${effectiveMode}`);
+  }
   if (allowRemoteBind) {
-    console.error("warning: --allow-remote-bind exposes the proxy beyond loopback. Put Haechi behind explicit network access controls.");
+    if (jsonLogs) {
+      logEvent("warn", "remote_bind_enabled", { tls: Boolean(address.tls), trustForwardedProto: Boolean(config.proxy?.trustForwardedProto) });
+    } else if (address.tls) {
+      console.error("warning: --allow-remote-bind exposes the proxy beyond loopback (TLS terminated by Haechi). Put Haechi behind explicit network access controls.");
+    } else {
+      console.error("warning: --allow-remote-bind exposes the proxy beyond loopback behind a trusted TLS-terminating reverse proxy (proxy.trustForwardedProto). Requests without X-Forwarded-Proto: https are refused. Put Haechi behind explicit network access controls.");
+    }
   }
   if (effectiveMode !== "enforce") {
-    console.error(`warning: policy mode is ${effectiveMode}. Payloads are inspected and audited but NOT modified or blocked. Set policy.mode to "enforce" to protect traffic.`);
+    if (jsonLogs) {
+      logEvent("warn", "non_enforce_mode", { mode: effectiveMode });
+    } else {
+      console.error(`warning: policy mode is ${effectiveMode}. Payloads are inspected and audited but NOT modified or blocked. Set policy.mode to "enforce" to protect traffic.`);
+    }
   }
   if (!config.responseProtection.enabled) {
-    console.error("warning: responseProtection.enabled is false. Upstream responses are forwarded without inspection.");
+    if (jsonLogs) {
+      logEvent("warn", "response_protection_disabled");
+    } else {
+      console.error("warning: responseProtection.enabled is false. Upstream responses are forwarded without inspection.");
+    }
   }
 
   for (const signal of ["SIGINT", "SIGTERM"]) {
     process.once(signal, async () => {
+      logEvent("info", "proxy_shutdown", { signal });
       await proxy.close();
       process.exit(0);
     });
@@ -599,7 +643,7 @@ const COMMAND_HELP = {
   proxy: {
     usage: `haechi proxy [--config haechi.config.json] [--host 127.0.0.1] [--port ${DEFAULT_PROXY_PORT}] [--allow-remote-bind]`,
     summary: "Run the local HTTP JSON proxy in front of an upstream LLM.",
-    detail: "Binds loopback by default; --allow-remote-bind is required (and must be a CLI flag, not config) to bind non-loopback hosts. There is no client auth yet — see 'haechi config'."
+    detail: "Binds loopback (plain http) by default; --allow-remote-bind is required (and must be a CLI flag, not config) to bind non-loopback hosts. A remote bind additionally requires TLS: set proxy.tls ({ keyFile, certFile } or { pfxFile, passphrase? }) so Haechi serves https, OR set proxy.trustForwardedProto: true when a trusted reverse proxy terminates TLS in front of Haechi (Haechi then refuses any request without X-Forwarded-Proto: https). Configure client auth via auth.provider — see 'haechi config'."
   },
   "policy-sign": {
     usage: "haechi policy-sign <policy.json> [--config haechi.config.json] [--out policy.bundle.json]",
@@ -693,7 +737,8 @@ Enforcement
 
 Upstream + proxy
   target.type               llm-http | openai-compatible | vllm-openai |
-                            ollama | llama-cpp                 (unknown = fail)
+                            ollama | llama-cpp | anthropic |
+                            gemini                             (unknown = fail)
   target.upstream           the only upstream the proxy forwards to
   proxy.host / proxy.port   127.0.0.1 / ${DEFAULT_PROXY_PORT}
                             non-loopback host needs --allow-remote-bind (CLI flag)
@@ -712,6 +757,8 @@ Detection policy
   policy.defaultAction      allow | redact | mask | tokenize | encrypt | block
   policy.actions            per-type overrides; merges may strengthen, not weaken
   filters.customRules       extra regex rules (ReDoS-screened)
+  filters.minConfidence     [0,1] drop soft detections below this (not hard-block)
+  filters.allowlist         FP exceptions [value|{value?,path?}] (not hard-block)
 
 Tokenization (model sees token, caller sees plaintext)
   tokenVault.revealPolicy   disabled | local-dev               (manual reveal gate)
@@ -731,7 +778,7 @@ Audit integrity
   audit.anchor.everyRecords anchor cadence                      (default 1)
 
 Privacy + MCP
-  privacy.profile           kr-pipa | eu-gdpr | us-general | null
+  privacy.profile           kr-pipa | eu-gdpr | asia-pdpa | us-general | jp-appi | null
   mcp.allowedMethods        client-callable method allowlist
 
 Binding beyond loopback (0.0.0.0):