haechi 0.3.2

package/packages/audit/index.mjs

@@ -0,0 +1,262 @@
+import { createReadStream } from "node:fs";
+import { appendFile, mkdir, open, stat, unlink } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+import { setTimeout as delay } from "node:timers/promises";
+
+const FORBIDDEN_KEYS = new Set(["value", "plaintext", "payload", "content", "message", "prompt", "secret"]);
+
+export function createJsonlAuditSink({ path }) {
+  if (!path) {
+    throw new Error("JSONL audit sink requires path");
+  }
+
+  let writeQueue = Promise.resolve();
+
+  return {
+    id: "haechi.audit.jsonl",
+    version: "0.1.0",
+    capabilities: {
+      writesAudit: true,
+      writesPlaintext: false,
+      integrity: "sha256-hash-chain"
+    },
+    async record(event) {
+      const write = writeQueue.then(async () => {
+        await mkdir(dirname(path), { recursive: true });
+        await withFileLock(`${path}.lock`, async () => {
+          const record = await buildIntegrityRecord(path, sanitizeAudit(event));
+          await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+        });
+      });
+      writeQueue = write.catch(() => {});
+      await write;
+    }
+  };
+}
+
+export async function readAuditSummary(path) {
+  const summary = {
+    events: 0,
+    blocked: 0,
+    detections: 0,
+    byType: {},
+    byAction: {}
+  };
+
+  try {
+    const lines = createInterface({
+      input: createReadStream(path, { encoding: "utf8" }),
+      crlfDelay: Infinity
+    });
+
+    for await (const line of lines) {
+      if (!line.trim()) {
+        continue;
+      }
+      const event = JSON.parse(line);
+      summary.events += 1;
+      if (event.blocked) {
+        summary.blocked += 1;
+      }
+      summary.detections += event.summary?.detectionCount ?? 0;
+      mergeCounts(summary.byType, event.summary?.byType);
+      mergeCounts(summary.byAction, event.summary?.byAction);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  return summary;
+}
+
+export function sanitizeAudit(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeAudit(item));
+  }
+
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value)
+      .filter(([key]) => !FORBIDDEN_KEYS.has(key))
+      .map(([key, item]) => [key, sanitizeAudit(item)]));
+  }
+
+  return value;
+}
+
+export async function verifyAuditChain(path) {
+  const lines = createInterface({
+    input: createReadStream(path, { encoding: "utf8" }),
+    crlfDelay: Infinity
+  });
+
+  let expectedPreviousHash = null;
+  let expectedSequence = 1;
+  let records = 0;
+
+  for await (const line of lines) {
+    if (!line.trim()) {
+      continue;
+    }
+    const record = JSON.parse(line);
+    const integrity = record.auditIntegrity;
+    if (!integrity) {
+      return { valid: false, records, reason: "missing auditIntegrity" };
+    }
+    if (integrity.sequence !== expectedSequence) {
+      return { valid: false, records, reason: "sequence mismatch" };
+    }
+    if ((integrity.previousHash ?? null) !== expectedPreviousHash) {
+      return { valid: false, records, reason: "previous hash mismatch" };
+    }
+
+    const { eventHash, ...unsignedIntegrity } = integrity;
+    const expectedHash = sha256(canonicalize({
+      ...record,
+      auditIntegrity: unsignedIntegrity
+    }));
+    if (eventHash !== expectedHash) {
+      return { valid: false, records, reason: "event hash mismatch" };
+    }
+
+    expectedPreviousHash = eventHash;
+    expectedSequence += 1;
+    records += 1;
+  }
+
+  return { valid: true, records };
+}
+
+async function buildIntegrityRecord(path, event) {
+  const previous = await readLastIntegrity(path);
+  const sequence = previous ? previous.sequence + 1 : 1;
+  const unsigned = {
+    ...event,
+    auditIntegrity: {
+      alg: "sha256",
+      canonicalization: "json-stable-v1",
+      sequence,
+      previousHash: previous?.eventHash ?? null
+    }
+  };
+
+  return {
+    ...unsigned,
+    auditIntegrity: {
+      ...unsigned.auditIntegrity,
+      eventHash: sha256(canonicalize(unsigned))
+    }
+  };
+}
+
+// Reads only the tail of the audit file so chained appends stay O(1) instead
+// of re-reading the whole log on every record.
+async function readLastIntegrity(path) {
+  let handle;
+  try {
+    handle = await open(path, "r");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+
+  try {
+    const { size } = await handle.stat();
+    if (size === 0) {
+      return null;
+    }
+
+    let chunkSize = 65536;
+    while (true) {
+      const start = Math.max(0, size - chunkSize);
+      const length = size - start;
+      const buffer = Buffer.alloc(length);
+      await handle.read(buffer, 0, length, start);
+      const lines = buffer.toString("utf8").split(/\r?\n/).filter((line) => line.trim());
+
+      // The last line is only known to be complete when the chunk covers the
+      // whole file or contains a newline before it.
+      if (lines.length > 0 && (start === 0 || lines.length > 1)) {
+        const last = JSON.parse(lines.at(-1));
+        return last.auditIntegrity ?? null;
+      }
+      if (start === 0) {
+        return null;
+      }
+      chunkSize *= 2;
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+function mergeCounts(target, source = {}) {
+  for (const [key, count] of Object.entries(source)) {
+    target[key] = (target[key] ?? 0) + count;
+  }
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalize(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("base64url");
+}
+
+async function withFileLock(lockPath, operation) {
+  const handle = await acquireLock(lockPath);
+  try {
+    return await operation();
+  } finally {
+    await handle.close();
+    await unlink(lockPath).catch((error) => {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    });
+  }
+}
+
+const STALE_LOCK_MS = 30000;
+
+async function acquireLock(lockPath) {
+  const deadline = Date.now() + 5000;
+  while (true) {
+    try {
+      return await open(lockPath, "wx", 0o600);
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      if (await isStaleLock(lockPath)) {
+        await unlink(lockPath).catch(() => {});
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`Timed out acquiring audit lock: ${lockPath}`);
+      }
+      await delay(10);
+    }
+  }
+}
+
+async function isStaleLock(lockPath) {
+  try {
+    const info = await stat(lockPath);
+    return Date.now() - info.mtimeMs > STALE_LOCK_MS;
+  } catch {
+    return false;
+  }
+}

package/packages/cli/bin/haechi.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { readAuditSummary } from "../../audit/index.mjs";
+import { DEFAULT_PROXY_PORT, createHaechiProxy } from "../../proxy/index.mjs";
+import { signPolicyBundleFile, verifyPolicyBundleFile } from "../../policy-bundle/index.mjs";
+import { validatePluginManifestFile } from "../../plugin/index.mjs";
+import { runMcpStdioFilter } from "../../mcp-stdio/index.mjs";
+import { DEFAULT_CONFIG_PATH, createRuntime, isValidPort, loadConfig, writeDefaultConfig } from "../runtime.mjs";
+
+const [command, ...argv] = process.argv.slice(2);
+
+try {
+  switch (command) {
+    case "init":
+      await initCommand(argv);
+      break;
+    case "protect":
+      await protectCommand(argv);
+      break;
+    case "report":
+      await reportCommand(argv);
+      break;
+    case "proxy":
+      await proxyCommand(argv);
+      break;
+    case "policy-sign":
+      await policySignCommand(argv);
+      break;
+    case "policy-verify":
+      await policyVerifyCommand(argv);
+      break;
+    case "token-reveal":
+      await tokenRevealCommand(argv);
+      break;
+    case "token-purge":
+      await tokenPurgeCommand(argv);
+      break;
+    case "token-export":
+      await tokenExportCommand(argv);
+      break;
+    case "plugin-validate":
+      await pluginValidateCommand(argv);
+      break;
+    case "mcp-stdio":
+      await mcpStdioCommand(argv);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      printHelp();
+      break;
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+} catch (error) {
+  console.error(`haechi: ${error.message}`);
+  process.exitCode = process.exitCode || 1;
+}
+
+async function initCommand(argv) {
+  const options = parseOptions(argv);
+  const configPath = options.config ?? DEFAULT_CONFIG_PATH;
+  const result = await writeDefaultConfig(configPath, { force: Boolean(options.force) });
+  writeJson({
+    ok: true,
+    command: "init",
+    configPath: result.configPath,
+    created: result.created,
+    keyFile: result.config.keys.keyFile,
+    auditPath: result.config.audit.path,
+    mode: result.config.mode,
+    warnings: [
+      "The generated .haechi/dev.keys.json file is for local development only.",
+      "Haechi 0.3.x does not include a production KMS/HSM/Vault key provider."
+    ]
+  });
+}
+
+async function protectCommand(argv) {
+  const [inputPath, ...rest] = argv;
+  if (!inputPath || inputPath.startsWith("--")) {
+    throw new Error("protect requires an input JSON file path");
+  }
+
+  const options = parseOptions(rest);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  const runtime = createRuntime(config);
+  const input = JSON.parse(await readFile(inputPath, "utf8"));
+  const effectiveMode = config.policy.mode ?? config.mode;
+  const result = await runtime.haechi.protectJson(input, {
+    protocol: config.target.type,
+    operation: "cli protect",
+    mode: effectiveMode
+  });
+
+  const enforced = !["dry-run", "report-only"].includes(effectiveMode);
+  writeJson({
+    ok: !result.blocked,
+    mode: effectiveMode,
+    enforced,
+    blocked: result.blocked,
+    auditId: result.auditEvent.id,
+    summary: result.summary,
+    payload: result.payload,
+    warnings: enforced ? [] : [
+      `policy mode is ${effectiveMode}: detections were audited but the payload was NOT modified or blocked. Set policy.mode to "enforce" to protect payloads.`
+    ]
+  });
+
+  if (result.blocked) {
+    process.exitCode = 3;
+  }
+}
+
+async function reportCommand(argv) {
+  const options = parseOptions(argv);
+  const auditPath = options.audit ?? options.path ?? ".haechi/audit.jsonl";
+  writeJson({
+    ok: true,
+    auditPath,
+    summary: await readAuditSummary(auditPath)
+  });
+}
+
+async function proxyCommand(argv) {
+  const options = parseOptions(argv);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  const runtime = createRuntime(config);
+  const port = parsePort(options.port ?? config.proxy.port);
+  const host = options.host ?? config.proxy.host;
+  const allowRemoteBind = Boolean(options["allow-remote-bind"]);
+  const proxy = createHaechiProxy({ runtime, port, host, allowRemoteBind });
+  const address = await proxy.listen();
+
+  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}`);
+  if (allowRemoteBind) {
+    console.error("warning: --allow-remote-bind exposes the proxy beyond loopback. 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 (!config.responseProtection.enabled) {
+    console.error("warning: responseProtection.enabled is false. Upstream responses are forwarded without inspection.");
+  }
+
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, async () => {
+      await proxy.close();
+      process.exit(0);
+    });
+  }
+}
+
+async function policySignCommand(argv) {
+  const [policyPath, ...rest] = argv;
+  if (!policyPath || policyPath.startsWith("--")) {
+    throw new Error("policy-sign requires a policy JSON file path");
+  }
+  const options = parseOptions(rest);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  const outPath = options.out ?? "policy.bundle.json";
+  const bundle = await signPolicyBundleFile({
+    policyPath,
+    keyFile: config.keys.keyFile,
+    outPath
+  });
+  writeJson({
+    ok: true,
+    command: "policy-sign",
+    outPath,
+    kid: bundle.kid,
+    signedAt: bundle.signedAt
+  });
+}
+
+async function policyVerifyCommand(argv) {
+  const [bundlePath, ...rest] = argv;
+  if (!bundlePath || bundlePath.startsWith("--")) {
+    throw new Error("policy-verify requires a policy bundle JSON file path");
+  }
+  const options = parseOptions(rest);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  writeJson({
+    ok: true,
+    command: "policy-verify",
+    bundlePath,
+    result: await verifyPolicyBundleFile({
+      bundlePath,
+      keyFile: config.keys.keyFile
+    })
+  });
+}
+
+async function tokenRevealCommand(argv) {
+  const [token, ...rest] = argv;
+  if (!token || token.startsWith("--")) {
+    throw new Error("token-reveal requires a token");
+  }
+  const options = parseOptions(rest);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  if (options["allow-dev-reveal"]) {
+    config.tokenVault.revealPolicy = "local-dev";
+  }
+  const runtime = createRuntime(config);
+  const result = await runtime.tokenVault.reveal({ token });
+  writeJson({
+    ok: true,
+    token: result.token,
+    type: result.type,
+    plaintext: result.plaintext
+  });
+}
+
+async function tokenPurgeCommand(argv) {
+  const options = parseOptions(argv);
+
+  if (options.expired) {
+    const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+    const runtime = createRuntime(config);
+    if (typeof runtime.tokenVault.purgeExpired !== "function") {
+      throw new Error("Configured token vault provider does not support purgeExpired");
+    }
+    writeJson({
+      ok: true,
+      command: "token-purge",
+      result: await runtime.tokenVault.purgeExpired()
+    });
+    return;
+  }
+
+  const [token] = argv;
+  if (!token || token.startsWith("--")) {
+    throw new Error("token-purge requires a token or --expired");
+  }
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  const runtime = createRuntime(config);
+  writeJson({
+    ok: true,
+    command: "token-purge",
+    result: await runtime.tokenVault.purge({ token })
+  });
+}
+
+async function tokenExportCommand(argv) {
+  const options = parseOptions(argv);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  const runtime = createRuntime(config);
+  writeJson({
+    ok: true,
+    command: "token-export",
+    tokens: await runtime.tokenVault.exportMetadata({
+      type: typeof options.type === "string" ? options.type : null
+    })
+  });
+}
+
+async function pluginValidateCommand(argv) {
+  const [manifestPath] = argv;
+  if (!manifestPath || manifestPath.startsWith("--")) {
+    throw new Error("plugin-validate requires a plugin manifest JSON file path");
+  }
+  const result = await validatePluginManifestFile(manifestPath);
+  writeJson({
+    ok: result.valid,
+    command: "plugin-validate",
+    manifestPath,
+    result
+  });
+  if (!result.valid) {
+    process.exitCode = 2;
+  }
+}
+
+async function mcpStdioCommand(argv) {
+  const options = parseOptions(argv);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  const runtime = createRuntime(config);
+  await runMcpStdioFilter({ runtime });
+}
+
+function parseOptions(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      options[key] = true;
+      continue;
+    }
+    options[key] = next;
+    index += 1;
+  }
+  return options;
+}
+
+function writeJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function parsePort(value) {
+  if (typeof value === "boolean") {
+    throw new Error("proxy port must be an integer from 0 to 65535");
+  }
+  if (typeof value === "string" && !/^\d+$/.test(value.trim())) {
+    throw new Error("proxy port must be an integer from 0 to 65535");
+  }
+  const port = typeof value === "number" ? value : Number(value);
+  if (!isValidPort(port)) {
+    throw new Error("proxy port must be an integer from 0 to 65535");
+  }
+  return port;
+}
+
+function printHelp() {
+  console.log(`Haechi MVP CLI
+
+Usage:
+  haechi init [--config haechi.config.json] [--force]
+  haechi protect <input.json> [--config haechi.config.json]
+  haechi report [--audit .haechi/audit.jsonl]
+  haechi proxy [--config haechi.config.json] [--host 127.0.0.1] [--port ${DEFAULT_PROXY_PORT}] [--allow-remote-bind]
+  haechi policy-sign <policy.json> [--config haechi.config.json] [--out policy.bundle.json]
+  haechi policy-verify <policy.bundle.json> [--config haechi.config.json]
+  haechi token-reveal <token> [--config haechi.config.json] [--allow-dev-reveal]
+  haechi token-purge <token> [--config haechi.config.json]
+  haechi token-purge --expired [--config haechi.config.json]
+  haechi token-export [--config haechi.config.json] [--type email]
+  haechi plugin-validate <plugin-manifest.json>
+  haechi mcp-stdio [--config haechi.config.json]
+
+The default policy mode is dry-run. Change policy.mode to enforce to mutate or block payloads.
+`);
+}