haechi 1.4.0 → 1.6.0

package/packages/audit/index.mjs

@@ -30,9 +30,73 @@ const FORBIDDEN_KEYS = new Set([
   "scopes", "labels"
 ]);
 
-export function createJsonlAuditSink({ path, anchor = null }) {
+// An audit STORE abstracts the exclusive "read-previous + persist" primitive so
+// the SAME core-owned sha256 hash chain can sit on top of a file today and a
+// shared store (e.g. Redis) in a future satellite. The contract is:
+//
+//   async transaction(fn) — runs `fn` inside an EXCLUSIVE critical section that
+//     serializes concurrent appends. `fn` receives { readLastIntegrity, persist }
+//     where readLastIntegrity() -> the last record's auditIntegrity (or null) and
+//     persist(record) durably appends the built record. transaction() returns
+//     fn's return value.
+//   async ready() — OPTIONAL health/writability probe returning { ok, reason? };
+//     the sink falls back to { ok: true } when the store omits it.
+//
+// The store deliberately knows NOTHING about anchoring, sanitization, or the
+// chain math — those stay core-owned in createAuditSink so a non-core store can
+// never fork or weaken the chain.
+
+// createFileAuditStore implements the store contract over the CURRENT JSONL
+// mechanism: a `${path}.lock` exclusive section wrapping mkdir + the critical
+// section, a tail-read for the previous integrity, and an appendFile persist.
+// The on-disk bytes are identical to the pre-seam sink.
+export function createFileAuditStore({ path }) {
   if (!path) {
-    throw new Error("JSONL audit sink requires path");
+    throw new Error("file audit store requires path");
+  }
+
+  return {
+    async transaction(fn) {
+      await mkdir(dirname(path), { recursive: true });
+      return withFileLock(`${path}.lock`, () => fn({
+        readLastIntegrity: () => readLastIntegrity(path),
+        persist: (record) => appendFile(path, `${JSON.stringify(record)}\n`, "utf8")
+      }));
+    },
+
+    // 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" };
+      }
+    }
+  };
+}
+
+// createAuditSink holds the SECURITY-CRITICAL, core-owned logic: writeQueue
+// serialization, sanitizeAudit, the sha256 chain build, the anchor stream, and
+// the capabilities object. The store only supplies the exclusive
+// read-previous + persist primitive; anchor config never leaks into it.
+export function createAuditSink({ store, anchor = null }) {
+  if (!store || typeof store.transaction !== "function") {
+    throw new Error("audit sink requires a store with a transaction(fn) method");
   }
   const anchorMode = anchor?.mode ?? "none";
   const anchorPath = anchor?.path ?? null;
@@ -81,44 +145,41 @@ export function createJsonlAuditSink({ path, anchor = null }) {
       integrity: anchorMode === "none" ? "sha256-hash-chain" : "sha256-hash-chain+anchor"
     },
     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");
-          await writeAnchor(record);
-        });
-      });
+      // The writeQueue serializes record() calls on this sink, and the store's
+      // transaction() adds the exclusive critical section; together they keep
+      // the chain strictly sequential and never forked under concurrency.
+      const write = writeQueue.then(() => store.transaction(async ({ readLastIntegrity, persist }) => {
+        const record = buildIntegrityRecord(await readLastIntegrity(), sanitizeAudit(event));
+        await persist(record);
+        await writeAnchor(record);
+        return record;
+      }));
       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" };
+      // Delegate to the store's writability probe; a store that omits it is
+      // treated as ready (the chain math has no readiness side effect of its own).
+      if (typeof store.ready === "function") {
+        return store.ready();
       }
+      return { ok: true };
     }
   };
 }
 
+// Thin back-compat wrapper: the original file-backed sink is now createAuditSink
+// over createFileAuditStore. Its returned shape (id, version, capabilities,
+// record, ready) and on-disk bytes are unchanged, so existing call sites
+// (runtime.mjs injection, tests) keep working untouched.
+export function createJsonlAuditSink({ path, anchor = null }) {
+  if (!path) {
+    throw new Error("JSONL audit sink requires path");
+  }
+  return createAuditSink({ store: createFileAuditStore({ path }), anchor });
+}
+
 export async function readAuditSummary(path) {
   const summary = {
     events: 0,
@@ -272,8 +333,13 @@ async function readAnchors(anchorPath) {
   return { bySequence, lastSequence };
 }
 
-async function buildIntegrityRecord(path, event) {
-  const previous = await readLastIntegrity(path);
+// PURE chain math: given the previous record's auditIntegrity (or null) and a
+// sanitized event, deterministically computes the next chained record. No fs,
+// no IO — the store supplies `previousIntegrity` (via its read-previous
+// primitive) so the SAME computation backs a file or a shared store. Exported
+// for store/satellite tests.
+export function buildIntegrityRecord(previousIntegrity, event) {
+  const previous = previousIntegrity ?? null;
   const sequence = previous ? previous.sequence + 1 : 1;
   const unsigned = {
     ...event,

package/packages/cli/bin/haechi.mjs

@@ -8,7 +8,7 @@ import { signPolicyBundleFile, verifyPolicyBundleFile } from "../../policy-bundl
 import { PluginLoadError, signPluginManifest, validatePluginManifestFile, verifySignedPlugin } from "../../plugin/index.mjs";
 import { runMcpStdioFilter, wrapMcpChild } from "../../mcp-stdio/index.mjs";
 import { addToken, listTokens, revokeToken } from "../../auth/index.mjs";
-import { createLocalCryptoProvider } from "../../crypto/index.mjs";
+import { createLocalCryptoProvider, readNonceBudget } from "../../crypto/index.mjs";
 import { spawn } from "node:child_process";
 import { DEFAULT_CONFIG_PATH, createRuntime, isValidPort, loadConfig, writeDefaultConfig } from "../runtime.mjs";
 
@@ -227,6 +227,34 @@ async function statusCommand(argv) {
     warnings.push(`key file ${config.keys.keyFile} does not exist; run haechi init`);
   }
 
+  // Surface the local AES-GCM nonce budget so an operator can rotate BEFORE the
+  // fail-closed limit (the in-band signal; the runtime also warns at 50% on
+  // stderr). Only the local provider has a software budget — an external
+  // cryptoProvider (KMS) owns its own nonce discipline.
+  keys.nonceBudget = null;
+  if (keys.exists && config.keys.provider === "local") {
+    try {
+      const budget = await readNonceBudget(config.keys.keyFile);
+      const usedPercent = Math.round(budget.usedFraction * 1000) / 10;
+      keys.nonceBudget = {
+        kid: budget.kid,
+        used: budget.used,
+        limit: budget.limit,
+        remaining: budget.remaining,
+        usedPercent,
+        exhausted: budget.exhausted
+      };
+      if (budget.exhausted) {
+        warnings.push(`crypto key ${budget.kid} has EXHAUSTED its safe encryption budget (${budget.limit}); encryption is failing closed — rotate now with 'haechi init --force'`);
+      } else if (budget.used >= budget.warnThreshold) {
+        warnings.push(`crypto key ${budget.kid} has used ${usedPercent}% of its safe encryption budget; plan a rotation ('haechi init --force')`);
+      }
+    } catch {
+      // A malformed/active-key-less file is already surfaced by init/encrypt;
+      // do not double-warn from the status read.
+    }
+  }
+
   const anchorEnabled = config.audit.anchor.mode === "file";
   const audit = {
     path: config.audit.path,
@@ -983,7 +1011,7 @@ const COMMAND_HELP = {
   status: {
     usage: "haechi status [--config haechi.config.json]",
     summary: "Show what is and is not protected under the current config.",
-    detail: "Prints effective policy mode, response/streaming protection, target, token vault governance, key file permissions, audit chain status, and a consolidated warnings list."
+    detail: "Prints effective policy mode, response/streaming protection, target, token vault governance, key file permissions, the local key's AES-GCM nonce budget (used %), audit chain status, and a consolidated warnings list."
   },
   proxy: {
     usage: `haechi proxy [--config haechi.config.json] [--host 127.0.0.1] [--port ${DEFAULT_PROXY_PORT}] [--allow-remote-bind]`,

package/packages/crypto/index.mjs

@@ -4,6 +4,22 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 
 const ALG = "AES-256-GCM";
 
+// Random 96-bit GCM IVs are only safe up to a bounded number of invocations per
+// key: by the birthday bound the IV-collision probability stays negligible only
+// below ~2^32 encryptions under ONE key (NIST SP 800-38D §8.3 caps random-IV
+// invocations at 2^32). A nonce collision under AES-GCM is catastrophic (it
+// leaks the XOR of the two plaintexts and enables forgery), so the local
+// provider FAILS CLOSED at the limit rather than risk reuse — the operator must
+// rotate (`haechi init --force`). The count is persisted per-kid in the key file
+// (see reserveNonceWindow) so it survives restarts; rotation resets it.
+const MAX_ENCRYPTIONS_PER_KEY = 2 ** 32;
+const NONCE_WARN_THRESHOLD = 2 ** 31; // warn once at 50% of the budget
+// Invocations are reserved a window at a time and the window is persisted BEFORE
+// it is consumed, so a crash/restart can only OVER-count (skip an unused tail of
+// a window) — never under-count into reuse. A large window keeps the per-encrypt
+// overhead at ~one key-file write per million encryptions.
+const NONCE_RESERVE_WINDOW = 2 ** 20;
+
 // Single source of truth for parsing + validating an on-disk local key file.
 // Both the provider's loadKeys() and initLocalKeyFile() (existing-file path)
 // go through here so the 32-byte key invariant is enforced once. Throws a
@@ -50,6 +66,84 @@ export function createLocalCryptoProvider({ keyFile }) {
     return cachedKeys;
   }
 
+  // Per-process view of the active key's reserved nonce window:
+  // { kid, base, granted, used } where base is the key file's `usage` at the
+  // window start and (base + used) is the next invocation index. null until the
+  // first encrypt reserves a window.
+  let reservation = null;
+  let nonceWarned = false;
+  // Set if the key file cannot be written (e.g. read-only mount): the budget
+  // then degrades to PER-PROCESS enforcement and counts forward in memory.
+  let persistDisabled = false;
+
+  // Reserve the next window of invocations for `activeKid` by advancing the
+  // persisted `usage` BEFORE consuming it (fail-closed at the per-key limit).
+  // Read-modify-write the key file in place, preserving every other field. The
+  // local provider is the single-writer reference provider; concurrent writers
+  // sharing one key file are out of scope (production custody uses a KMS
+  // satellite) — a documented residual, not silent reuse, since reuse needs an
+  // actual IV collision and over-counting only wastes budget. If the key file is
+  // not writable, fall back to per-process counting (warned once) rather than
+  // breaking encryption on a hardened read-only mount.
+  async function reserveNonceWindow(activeKid) {
+    let current;
+    let raw = null;
+    let entry = null;
+    if (persistDisabled && reservation && reservation.kid === activeKid) {
+      // No persistence: continue counting forward from the last window in memory.
+      current = reservation.base + reservation.granted;
+    } else {
+      raw = JSON.parse(await readFile(keyFile, "utf8"));
+      entry = raw.keys?.find((k) => k.kid === activeKid);
+      if (!entry) {
+        throw new Error(`Active key ${activeKid} not found while reserving nonce budget`);
+      }
+      current = entry.usage ?? 0;
+    }
+    if (current >= MAX_ENCRYPTIONS_PER_KEY) {
+      throw new Error(
+        `local AES-256-GCM key ${activeKid} reached its safe encryption limit (${MAX_ENCRYPTIONS_PER_KEY}); rotate the key with 'haechi init --force' before encrypting more`
+      );
+    }
+    const granted = Math.min(NONCE_RESERVE_WINDOW, MAX_ENCRYPTIONS_PER_KEY - current);
+    if (!persistDisabled && entry) {
+      try {
+        entry.usage = current + granted;
+        await writeFile(keyFile, `${JSON.stringify(raw, null, 2)}\n`, { mode: 0o600 });
+      } catch (error) {
+        persistDisabled = true;
+        process.emitWarning(
+          `local AES-256-GCM nonce budget for key ${activeKid} cannot be persisted (${error?.code ?? error?.message}); enforcing the PER-PROCESS limit only — cross-restart protection is OFF, so rotate keys on a schedule`,
+          { code: "HAECHI_NONCE_BUDGET_NOPERSIST" }
+        );
+      }
+    }
+    reservation = { kid: activeKid, base: current, granted, used: 0 };
+  }
+
+  // Account one GCM encryption against the active key's nonce budget, reserving
+  // a fresh window when the current one is exhausted. Returns nothing; throws
+  // fail-closed at the limit. MUST be called before generating the IV.
+  async function consumeNonceBudget(activeKid) {
+    if (!reservation || reservation.kid !== activeKid || reservation.used >= reservation.granted) {
+      await reserveNonceWindow(activeKid);
+    }
+    const index = reservation.base + reservation.used; // 0-based invocation count
+    if (index >= MAX_ENCRYPTIONS_PER_KEY) {
+      throw new Error(
+        `local AES-256-GCM key ${activeKid} reached its safe encryption limit (${MAX_ENCRYPTIONS_PER_KEY}); rotate the key with 'haechi init --force' before encrypting more`
+      );
+    }
+    reservation.used += 1;
+    if (!nonceWarned && index >= NONCE_WARN_THRESHOLD) {
+      nonceWarned = true;
+      process.emitWarning(
+        `local AES-256-GCM key ${activeKid} has used ${index} of ${MAX_ENCRYPTIONS_PER_KEY} safe encryptions; plan a key rotation ('haechi init --force')`,
+        { code: "HAECHI_NONCE_BUDGET" }
+      );
+    }
+  }
+
   return {
     id: "haechi.crypto.local-aes-gcm",
     version: "0.1.0",
@@ -59,6 +153,9 @@ export function createLocalCryptoProvider({ keyFile }) {
     },
     async encrypt({ plaintext, aad }) {
       const { active: { kid, key } } = await loadKeys();
+      // Fail closed at the per-key random-IV invocation limit BEFORE choosing an
+      // IV, so we never generate a nonce past the safe budget (NIST SP 800-38D).
+      await consumeNonceBudget(kid);
       const iv = randomBytes(12);
       const cipher = createCipheriv("aes-256-gcm", key, iv);
       const aadBytes = Buffer.from(canonicalize(aad), "utf8");
@@ -268,6 +365,28 @@ export async function assertCryptoProviderConformance(provider, { requireHmac =
   return { ok: true };
 }
 
+// Read the active key's nonce-budget status for operator visibility (e.g.
+// `haechi status`). `used` reflects the PERSISTED reservation (advanced a window
+// at a time), so it is a slight SAFE over-estimate of actual encryptions — never
+// an under-estimate. Throws if the file has no usable active key.
+export async function readNonceBudget(keyFile) {
+  const raw = JSON.parse(await readFile(keyFile, "utf8"));
+  const activeEntry = raw.keys?.find((key) => key.status === "active") ?? raw.keys?.[0];
+  if (!activeEntry) {
+    throw new Error("No active key found while reading nonce budget");
+  }
+  const used = activeEntry.usage ?? 0;
+  return {
+    kid: activeEntry.kid,
+    used,
+    limit: MAX_ENCRYPTIONS_PER_KEY,
+    remaining: Math.max(0, MAX_ENCRYPTIONS_PER_KEY - used),
+    usedFraction: used / MAX_ENCRYPTIONS_PER_KEY,
+    warnThreshold: NONCE_WARN_THRESHOLD,
+    exhausted: used >= MAX_ENCRYPTIONS_PER_KEY
+  };
+}
+
 export function canonicalize(value) {
   if (Array.isArray(value)) {
     return `[${value.map((item) => canonicalize(item)).join(",")}]`;