haechi 0.6.0 → 0.8.0

package/packages/audit/index.mjs

@@ -7,20 +7,55 @@ import { setTimeout as delay } from "node:timers/promises";
 
 const FORBIDDEN_KEYS = new Set(["value", "plaintext", "payload", "content", "message", "prompt", "secret"]);
 
-export function createJsonlAuditSink({ path }) {
+export function createJsonlAuditSink({ path, anchor = null }) {
   if (!path) {
     throw new Error("JSONL audit sink requires path");
   }
+  const anchorMode = anchor?.mode ?? "none";
+  const anchorPath = anchor?.path ?? null;
+  const everyRecords = anchor?.everyRecords ?? 1;
+  if (!["none", "file", "stdout"].includes(anchorMode)) {
+    throw new Error(`Invalid audit anchor mode: ${anchorMode}`);
+  }
+  if (anchorMode === "file" && !anchorPath) {
+    throw new Error("audit anchor mode 'file' requires an anchor path");
+  }
+  // The sink is a public export reachable via auditSink injection, so it
+  // validates everyRecords itself rather than trusting normalizeConfig.
+  if (!Number.isInteger(everyRecords) || everyRecords < 1) {
+    throw new Error("audit anchor everyRecords must be a positive integer");
+  }
 
   let writeQueue = Promise.resolve();
 
+  async function writeAnchor(record) {
+    const { sequence, eventHash } = record.auditIntegrity;
+    // Tamper-evidence against tail truncation: the chain head is appended to a
+    // separate append-only stream, so deleting trailing records leaves the
+    // chain shorter than the last anchored sequence.
+    if (anchorMode === "none" || sequence % everyRecords !== 0) {
+      return;
+    }
+    const line = `${JSON.stringify({ sequence, eventHash, timestamp: record.timestamp })}\n`;
+    if (anchorMode === "stdout") {
+      process.stdout.write(line);
+    } else {
+      await mkdir(dirname(anchorPath), { recursive: true });
+      // 0600 on creation, like the key/lock files. Note this only matters for
+      // confidentiality of the timeline — tamper-evidence still requires the
+      // anchor to live on append-only/separate media (see docs).
+      await appendFile(anchorPath, line, { mode: 0o600 });
+    }
+  }
+
   return {
     id: "haechi.audit.jsonl",
     version: "0.1.0",
     capabilities: {
       writesAudit: true,
       writesPlaintext: false,
-      integrity: "sha256-hash-chain"
+      appendOnly: true,
+      integrity: anchorMode === "none" ? "sha256-hash-chain" : "sha256-hash-chain+anchor"
     },
     async record(event) {
       const write = writeQueue.then(async () => {
@@ -28,6 +63,7 @@ export function createJsonlAuditSink({ path }) {
         await withFileLock(`${path}.lock`, async () => {
           const record = await buildIntegrityRecord(path, sanitizeAudit(event));
           await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+          await writeAnchor(record);
         });
       });
       writeQueue = write.catch(() => {});
@@ -87,7 +123,12 @@ export function sanitizeAudit(value) {
   return value;
 }
 
-export async function verifyAuditChain(path) {
+export async function verifyAuditChain(path, { anchorPath = null } = {}) {
+  // The anchor stream (if provided) records the chain head at past points; a
+  // chain shorter than the last anchor, or a hash that disagrees with an
+  // anchor, is tail truncation / tampering the chain alone cannot catch.
+  const anchors = anchorPath ? await readAnchors(anchorPath) : null;
+
   const lines = createInterface({
     input: createReadStream(path, { encoding: "utf8" }),
     crlfDelay: Infinity
@@ -122,14 +163,66 @@ export async function verifyAuditChain(path) {
       return { valid: false, records, reason: "event hash mismatch" };
     }
 
+    if (anchors && anchors.bySequence.has(expectedSequence)
+      && anchors.bySequence.get(expectedSequence) !== eventHash) {
+      return { valid: false, records, reason: `anchor hash mismatch at sequence ${expectedSequence}` };
+    }
+
     expectedPreviousHash = eventHash;
     expectedSequence += 1;
     records += 1;
   }
 
-  // headHash anchors the chain externally: publishing it out-of-band is the
-  // only defense against tail truncation, which the chain alone cannot detect.
-  return { valid: true, records, headHash: expectedPreviousHash };
+  if (anchors && anchors.lastSequence > records) {
+    return {
+      valid: false,
+      records,
+      reason: `tail truncation: chain has ${records} records but anchor attests sequence ${anchors.lastSequence}`
+    };
+  }
+
+  // headHash anchors the chain externally. With anchorPath, truncation back to
+  // the last anchor is now detected; the residual gap is records written after
+  // the last anchor.
+  const result = { valid: true, records, headHash: expectedPreviousHash };
+  if (anchors) {
+    result.anchored = { count: anchors.bySequence.size, lastSequence: anchors.lastSequence };
+  }
+  return result;
+}
+
+async function readAnchors(anchorPath) {
+  const bySequence = new Map();
+  let lastSequence = 0;
+  try {
+    const lines = createInterface({
+      input: createReadStream(anchorPath, { encoding: "utf8" }),
+      crlfDelay: Infinity
+    });
+    for await (const line of lines) {
+      if (!line.trim()) {
+        continue;
+      }
+      // A crash can leave a partial trailing anchor line; tolerate it (skip)
+      // rather than failing the whole verification. The chain check plus the
+      // remaining valid anchors still bound truncation detection.
+      let anchor;
+      try {
+        anchor = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (typeof anchor.sequence === "number" && typeof anchor.eventHash === "string") {
+        bySequence.set(anchor.sequence, anchor.eventHash);
+        lastSequence = Math.max(lastSequence, anchor.sequence);
+      }
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  return { bySequence, lastSequence };
 }
 
 async function buildIntegrityRecord(path, event) {

package/packages/auth/index.mjs

@@ -117,6 +117,51 @@ export async function buildIdentity(record, cryptoProvider) {
   };
 }
 
+// PII-safe identity builder for EXTERNAL auth providers (e.g. the haechi-auth-jwt
+// satellite). Core owns identity construction so the keyed-HMAC domain and the
+// identity shape stay authoritative here — a satellite supplies raw claims and
+// never sees or stores the IDENTITY_DOMAIN. subject/issuer become keyed HMACs;
+// the raw values are never returned. Throws (fail-closed) on a missing
+// cryptoProvider.hmac, an empty subject/issuer, an invalid type, bad scopes, or
+// a disallowed label.
+export async function buildExternalIdentity(
+  { provider, subject, issuer, type = "user", scopes = [], labels = {}, allowedLabelKeys = DEFAULT_ALLOWED_LABEL_KEYS },
+  cryptoProvider
+) {
+  if (typeof cryptoProvider?.hmac !== "function") {
+    throw new Error("buildExternalIdentity requires a cryptoProvider with hmac()");
+  }
+  if (!provider || typeof provider !== "string") {
+    throw new Error("identity requires a non-empty provider string");
+  }
+  if (!subject || typeof subject !== "string") {
+    throw new Error("identity requires a non-empty subject");
+  }
+  if (!issuer || typeof issuer !== "string") {
+    throw new Error("identity requires a non-empty issuer");
+  }
+  if (!VALID_IDENTITY_TYPES.has(type)) {
+    throw new Error(`Invalid identity type: ${type} (expected user | service | agent)`);
+  }
+  if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string" && scope.trim())) {
+    throw new Error("scopes must be an array of non-empty strings");
+  }
+  validateLabels(labels, allowedLabelKeys);
+
+  const subjectHash = await cryptoProvider.hmac({ data: subject, domain: IDENTITY_DOMAIN });
+  const issuerHash = await cryptoProvider.hmac({ data: issuer, domain: IDENTITY_DOMAIN });
+  return {
+    // Non-PII, stable per subject: derived from the keyed subject hash.
+    id: `${provider}:${subjectHash.slice(0, 16)}`,
+    type,
+    subjectHash,
+    issuerHash,
+    provider,
+    scopes,
+    labels
+  };
+}
+
 function bearerTokenFromRequest(request) {
   const header = request?.headers?.authorization ?? request?.headers?.Authorization;
   if (typeof header !== "string") {

package/packages/cli/bin/haechi.mjs

@@ -147,19 +147,27 @@ async function reportCommand(argv) {
 async function auditVerifyCommand(argv) {
   const options = parseOptions(argv);
   let auditPath = options.audit ?? options.path;
-  if (!auditPath) {
+  let anchorPath = typeof options.anchor === "string" ? options.anchor : null;
+  if (!auditPath || (options.anchor === true && !anchorPath)) {
     try {
-      auditPath = (await loadConfig(options.config ?? DEFAULT_CONFIG_PATH)).audit.path;
+      const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+      auditPath = auditPath ?? config.audit.path;
+      // --anchor with no value (or no flag at all) falls back to the configured
+      // anchor path when anchoring is enabled.
+      if (!anchorPath && config.audit.anchor.mode === "file") {
+        anchorPath = config.audit.anchor.path;
+      }
     } catch {
-      auditPath = ".haechi/audit.jsonl";
+      auditPath = auditPath ?? ".haechi/audit.jsonl";
     }
   }
 
-  const result = await verifyAuditChain(auditPath);
+  const result = await verifyAuditChain(auditPath, { anchorPath });
   writeJson({
     ok: result.valid,
     command: "audit-verify",
     auditPath,
+    anchorPath,
     result
   });
   if (!result.valid) {
@@ -208,17 +216,30 @@ async function statusCommand(argv) {
     warnings.push(`key file ${config.keys.keyFile} does not exist; run haechi init`);
   }
 
-  const audit = { path: config.audit.path, exists: false, chain: null };
+  const anchorEnabled = config.audit.anchor.mode === "file";
+  const audit = {
+    path: config.audit.path,
+    exists: false,
+    chain: null,
+    anchor: { mode: config.audit.anchor.mode, path: anchorEnabled ? config.audit.anchor.path : null }
+  };
   try {
     await stat(config.audit.path);
     audit.exists = true;
-    audit.chain = await verifyAuditChain(config.audit.path);
+    audit.chain = await verifyAuditChain(config.audit.path, {
+      anchorPath: anchorEnabled ? config.audit.anchor.path : null
+    });
     if (!audit.chain.valid) {
       warnings.push(`audit chain verification failed: ${audit.chain.reason}`);
     }
   } catch {
     // No audit file yet is a normal pre-first-run state, not a warning.
   }
+  if (config.audit.anchor.mode === "none") {
+    warnings.push("audit.anchor.mode is none: tail truncation of the audit log cannot be detected");
+  } else if (config.audit.anchor.mode === "file") {
+    warnings.push("audit.anchor: real tail-truncation defense requires the anchor on append-only or separate media; on the same writable filesystem an attacker can truncate both files together");
+  }
 
   writeJson({
     ok: true,
@@ -566,9 +587,9 @@ const COMMAND_HELP = {
     summary: "Summarize audit events without raw payloads."
   },
   "audit-verify": {
-    usage: "haechi audit-verify [--audit .haechi/audit.jsonl] [--config haechi.config.json]",
+    usage: "haechi audit-verify [--audit .haechi/audit.jsonl] [--anchor [path]] [--config haechi.config.json]",
     summary: "Verify the audit hash chain; print validity, record count, and head hash.",
-    detail: "Exit 4 on a broken chain. The head hash is the value to anchor externally against tail truncation."
+    detail: "Exit 4 on a broken chain. With --anchor (or audit.anchor.mode: file in config) it cross-checks the anchor stream and detects tail truncation back to the last anchor. The anchor only adds real defense when kept on append-only or separate media — on the same writable filesystem an attacker can truncate both files together."
   },
   status: {
     usage: "haechi status [--config haechi.config.json]",
@@ -698,6 +719,17 @@ Tokenization (model sees token, caller sees plaintext)
   tokenVault.detokenizeResponses  restore request-issued tokens in the response
                             (needs responseProtection.enabled)
 
+Audit integrity
+  audit.anchor.mode         none | file | stdout                (default none)
+                            file/stdout anchor the chain head so tail
+                            truncation is detected (haechi audit-verify --anchor).
+                            Real defense needs the anchor on append-only or
+                            separate media; same-filesystem anchors can be
+                            truncated together. stdout mode is for long-running
+                            commands (proxy), not JSON-emitting ones.
+  audit.anchor.path         .haechi/audit.anchor.jsonl          (mode: file)
+  audit.anchor.everyRecords anchor cadence                      (default 1)
+
 Privacy + MCP
   privacy.profile           kr-pipa | eu-gdpr | us-general | null
   mcp.allowedMethods        client-callable method allowlist

package/packages/cli/runtime.mjs

@@ -60,7 +60,12 @@ export function defaultConfig() {
     },
     audit: {
       sink: "jsonl",
-      path: ".haechi/audit.jsonl"
+      path: ".haechi/audit.jsonl",
+      anchor: {
+        mode: "none",
+        path: ".haechi/audit.anchor.jsonl",
+        everyRecords: 1
+      }
     },
     tokenVault: {
       provider: "local",
@@ -117,7 +122,18 @@ export function createRuntime(config, providers = {}) {
   const normalized = normalizeConfig(config);
   const cryptoProvider = providers.cryptoProvider ?? createConfiguredCryptoProvider(normalized);
   assertProvider("cryptoProvider", cryptoProvider, ["encrypt", "decrypt"]);
-  const auditSink = providers.auditSink ?? createJsonlAuditSink({ path: normalized.audit.path });
+  // hmac is only required by features that use it (bearer auth, deterministic
+  // tokenization). An encrypt-only external provider is valid otherwise; fail
+  // closed at construction rather than deep in a request if a needing feature
+  // is configured without it.
+  if (typeof cryptoProvider.hmac !== "function"
+    && (normalized.auth.provider === "bearer" || normalized.tokenVault.deterministic)) {
+    throw new Error("cryptoProvider must implement hmac() for bearer auth / deterministic tokenization");
+  }
+  const auditSink = providers.auditSink ?? createJsonlAuditSink({
+    path: normalized.audit.path,
+    anchor: normalized.audit.anchor
+  });
   assertProvider("auditSink", auditSink, ["record"]);
   const tokenVault = providers.tokenVault ?? createLocalTokenVault({
     path: normalized.tokenVault.path,
@@ -214,7 +230,11 @@ export function normalizeConfig(config) {
     },
     audit: {
       ...defaultConfig().audit,
-      ...(config.audit ?? {})
+      ...(config.audit ?? {}),
+      anchor: {
+        ...defaultConfig().audit.anchor,
+        ...(config.audit?.anchor ?? {})
+      }
     },
     tokenVault: {
       ...defaultConfig().tokenVault,
@@ -248,6 +268,16 @@ export function normalizeConfig(config) {
   if (merged.audit.sink !== "jsonl") {
     throw new Error("Current implementation only supports jsonl audit sink");
   }
+  if (!["none", "file", "stdout"].includes(merged.audit.anchor.mode)) {
+    throw new Error(`Invalid audit.anchor.mode: ${merged.audit.anchor.mode}`);
+  }
+  if (merged.audit.anchor.mode === "file"
+    && (typeof merged.audit.anchor.path !== "string" || !merged.audit.anchor.path.trim())) {
+    throw new Error("audit.anchor.mode 'file' requires audit.anchor.path");
+  }
+  if (!Number.isInteger(merged.audit.anchor.everyRecords) || merged.audit.anchor.everyRecords < 1) {
+    throw new Error("audit.anchor.everyRecords must be a positive integer");
+  }
   if (merged.tokenVault.provider !== "local") {
     throw new Error("0.2 only supports local token vault provider");
   }

package/packages/crypto/index.mjs

@@ -139,6 +139,113 @@ export async function initLocalKeyFile(keyFile, { force = false } = {}) {
   return { created: true, keyFile, rotated: retiredKeys.length > 0 };
 }
 
+// Conformance suite for any cryptoProvider used via keys.provider: external.
+// Adapter authors (e.g. a KMS satellite) run this to self-test against the
+// contract. encrypt/decrypt are always required; hmac is required for
+// tokenization, auth, deterministic tokens, and policy bundles — pass
+// { requireHmac: false } for an encrypt-only provider.
+export async function assertCryptoProviderConformance(provider, { requireHmac = true } = {}) {
+  const failures = [];
+  const check = async (name, fn) => {
+    try {
+      await fn();
+    } catch (error) {
+      failures.push(`${name}: ${error.message}`);
+    }
+  };
+  const assert = (condition, message) => {
+    if (!condition) {
+      throw new Error(message);
+    }
+  };
+
+  if (typeof provider?.encrypt !== "function" || typeof provider?.decrypt !== "function") {
+    throw new Error("cryptoProvider must implement encrypt() and decrypt()");
+  }
+
+  const plaintext = `conformance-${randomBytes(8).toString("hex")}@example.com`;
+  const aad = { purpose: "conformance", path: "messages[0].content", type: "email" };
+
+  const other = `conformance-${randomBytes(8).toString("hex")}@example.org`;
+
+  await check("encrypt/decrypt round-trip", async () => {
+    const envelope = await provider.encrypt({ plaintext, aad });
+    assert(envelope && typeof envelope === "object", "encrypt must return an envelope object");
+    assert(envelope.kid, "envelope must carry a key id (kid)");
+    assert(envelope.aadHash, "envelope must carry an aadHash");
+    const back = await provider.decrypt({ envelope, aad });
+    assert(back === plaintext, "decrypt did not return the original plaintext");
+    // A second, distinct plaintext rules out a decrypt that returns a fixed value.
+    const back2 = await provider.decrypt({ envelope: await provider.encrypt({ plaintext: other, aad }), aad });
+    assert(back2 === other, "decrypt did not return the second plaintext (fixed/garbage output)");
+  });
+
+  await check("decrypt rejects a different AAD", async () => {
+    const envelope = await provider.encrypt({ plaintext, aad });
+    let rejected = false;
+    try {
+      await provider.decrypt({ envelope, aad: { ...aad, type: "phone" } });
+    } catch {
+      rejected = true;
+    }
+    assert(rejected, "decrypt accepted a mismatched AAD (no AAD binding)");
+  });
+
+  await check("decrypt rejects tampered ciphertext (real AEAD authentication)", async () => {
+    const envelope = await provider.encrypt({ plaintext, aad });
+    if (typeof envelope.ct !== "string" || envelope.ct.length === 0) {
+      return; // provider uses a non-ct envelope shape; the AAD check above still applies
+    }
+    // Flip a byte of the ciphertext; a real AEAD provider fails the auth tag.
+    const buf = Buffer.from(envelope.ct, "base64url");
+    buf[0] ^= 0xff;
+    let rejected = false;
+    try {
+      await provider.decrypt({ envelope: { ...envelope, ct: buf.toString("base64url") }, aad });
+    } catch {
+      rejected = true;
+    }
+    assert(rejected, "decrypt accepted tampered ciphertext (no AEAD authentication)");
+  });
+
+  if (requireHmac) {
+    if (typeof provider.hmac !== "function") {
+      failures.push("hmac: provider does not implement hmac() (required for tokenization/auth/bundles)");
+    } else {
+      await check("hmac is deterministic and data-dependent", async () => {
+        const a = await provider.hmac({ data: "x", domain: "haechi:conformance:v1" });
+        const b = await provider.hmac({ data: "x", domain: "haechi:conformance:v1" });
+        assert(typeof a === "string" && a.length > 0, "hmac must return a non-empty string");
+        assert(a === b, "hmac is not deterministic for the same (data, domain)");
+        // Different data MUST give different output — else tokens/identities collide.
+        const c = await provider.hmac({ data: "y", domain: "haechi:conformance:v1" });
+        assert(a !== c, "hmac ignores the data argument (same output for different data)");
+      });
+      await check("hmac separates domains", async () => {
+        const a = await provider.hmac({ data: "x", domain: "haechi:conformance:a" });
+        const b = await provider.hmac({ data: "x", domain: "haechi:conformance:b" });
+        assert(a !== b, "hmac does not separate domains (same output for different domains)");
+      });
+      await check("hmac requires a domain", async () => {
+        for (const badDomain of ["", undefined, null]) {
+          let rejected = false;
+          try {
+            await provider.hmac({ data: "x", domain: badDomain });
+          } catch {
+            rejected = true;
+          }
+          assert(rejected, `hmac accepted an invalid domain (${JSON.stringify(badDomain)})`);
+        }
+      });
+    }
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`cryptoProvider conformance failed:\n- ${failures.join("\n- ")}`);
+  }
+  return { ok: true };
+}
+
 export function canonicalize(value) {
   if (Array.isArray(value)) {
     return `[${value.map((item) => canonicalize(item)).join(",")}]`;

package/scripts/release-checksums.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Generate or verify a SHA256SUMS manifest for release artifacts.
+//
+//   node scripts/release-checksums.mjs <file...>           # print "<hash>  <name>" lines
+//   node scripts/release-checksums.mjs --check SHA256SUMS  # verify files against a manifest
+//
+// Standard `<sha256-hex>  <basename>` format (two spaces), so `sha256sum -c`
+// and `shasum -a 256 -c` interoperate with what this prints.
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export async function sha256File(path) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) {
+    hash.update(chunk);
+  }
+  return hash.digest("hex");
+}
+
+export function formatManifestLine(hashHex, name) {
+  return `${hashHex}  ${name}`;
+}
+
+export function parseManifest(text) {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const match = /^([a-f0-9]{64})\s+(.+)$/.exec(line);
+      if (!match) {
+        throw new Error(`Malformed SHA256SUMS line: ${line}`);
+      }
+      return { hash: match[1], name: match[2] };
+    });
+}
+
+export async function generateManifest(files) {
+  const lines = [];
+  for (const file of files) {
+    lines.push(formatManifestLine(await sha256File(file), basename(file)));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export async function verifyManifest(manifestPath) {
+  const baseDir = dirname(manifestPath);
+  const entries = parseManifest(await readFile(manifestPath, "utf8"));
+  const results = [];
+  for (const entry of entries) {
+    // A manifest is untrusted input: never hash a path that escapes the
+    // manifest's own directory (no absolute paths, no `../` traversal).
+    const rel = relative(baseDir, join(baseDir, entry.name));
+    if (isAbsolute(entry.name) || rel.startsWith("..")) {
+      results.push({ name: entry.name, ok: false, reason: "unsafe path" });
+      continue;
+    }
+    let actual = null;
+    try {
+      actual = await sha256File(join(baseDir, entry.name));
+    } catch (error) {
+      results.push({ name: entry.name, ok: false, reason: error.code === "ENOENT" ? "missing" : error.message });
+      continue;
+    }
+    results.push({ name: entry.name, ok: actual === entry.hash, reason: actual === entry.hash ? null : "hash mismatch" });
+  }
+  return { ok: results.every((r) => r.ok), results };
+}
+
+async function main(argv) {
+  if (argv[0] === "--check") {
+    const manifestPath = argv[1];
+    if (!manifestPath) {
+      throw new Error("--check requires a SHA256SUMS path");
+    }
+    const { ok, results } = await verifyManifest(manifestPath);
+    for (const r of results) {
+      process.stderr.write(`${r.ok ? "OK  " : "FAIL"} ${r.name}${r.reason ? ` (${r.reason})` : ""}\n`);
+    }
+    process.exitCode = ok ? 0 : 1;
+    return;
+  }
+  if (argv.length === 0) {
+    throw new Error("usage: release-checksums.mjs <file...> | --check SHA256SUMS");
+  }
+  process.stdout.write(await generateManifest(argv));
+}
+
+// Run only as a CLI (not when imported by tests). fileURLToPath handles
+// Windows paths and URL encoding that a raw `file://` compare would miss.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`release-checksums: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}