haechi 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haechi",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Experimental developer preview for self-hosted AI context enforcement across LLM, MCP, vLLM, Ollama, and agent traffic.",
   "license": "Apache-2.0",
   "type": "module",
@@ -45,7 +45,8 @@
     "./proxy": "./packages/proxy/index.mjs",
     "./runtime": "./packages/cli/runtime.mjs",
     "./token-vault": "./packages/token-vault/index.mjs",
-    "./stream-filter": "./packages/stream-filter/index.mjs"
+    "./stream-filter": "./packages/stream-filter/index.mjs",
+    "./auth": "./packages/auth/index.mjs"
   },
   "files": [
     "README.md",
@@ -54,6 +55,7 @@
     "haechi.config.example.json",
     "packages/",
     "examples/",
+    "scripts/release-checksums.mjs",
     "docs/current/"
   ],
   "scripts": {
@@ -62,6 +64,7 @@
     "pack:dry": "npm pack --dry-run",
     "scan:stale-names": "node scripts/stale-name-scan.mjs",
     "sbom": "node scripts/generate-sbom.mjs",
+    "checksums": "node scripts/release-checksums.mjs",
     "bench:payload": "node scripts/bench-payload.mjs",
     "release:preflight": "node scripts/release-preflight.mjs",
     "release:preflight:npm": "node scripts/release-preflight.mjs --require-npm-auth",

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

@@ -0,0 +1,170 @@
+// Built-in bearer authentication and the authProvider contract.
+//
+// Tokens are never stored in plaintext: the store keeps a keyed-HMAC hash
+// (domain-separated, never a bare hash) plus PII-safe metadata. The plaintext
+// token is shown once at creation. Identity objects are PII-safe by
+// construction — subject/issuer are keyed HMACs, never raw values.
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+
+const TOKEN_DOMAIN = "haechi:auth:token:v1";
+const IDENTITY_DOMAIN = "haechi:identity:hash:v1";
+const TOKEN_PREFIX = "hae_";
+const DEFAULT_ALLOWED_LABEL_KEYS = ["team", "env", "tier", "role"];
+const VALID_IDENTITY_TYPES = new Set(["user", "service", "agent"]);
+const MAX_LABEL_VALUE_LENGTH = 64;
+
+export async function readAuthStore(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return { version: parsed.version ?? 1, tokens: parsed.tokens ?? [] };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { version: 1, tokens: [] };
+    }
+    throw error;
+  }
+}
+
+async function writeAuthStore(path, store) {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  await rename(tempPath, path);
+}
+
+export function validateLabels(labels, allowedLabelKeys = DEFAULT_ALLOWED_LABEL_KEYS) {
+  for (const [key, value] of Object.entries(labels)) {
+    if (!allowedLabelKeys.includes(key)) {
+      throw new Error(`Label key not allowed: ${key} (allowed: ${allowedLabelKeys.join(", ") || "none"})`);
+    }
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_LABEL_VALUE_LENGTH) {
+      throw new Error(`Label value for ${key} must be a non-empty string up to ${MAX_LABEL_VALUE_LENGTH} chars`);
+    }
+  }
+  return labels;
+}
+
+export async function addToken({ path, cryptoProvider, type, scopes = [], labels = {}, allowedLabelKeys = DEFAULT_ALLOWED_LABEL_KEYS }) {
+  if (!VALID_IDENTITY_TYPES.has(type)) {
+    throw new Error(`Invalid token 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 token = `${TOKEN_PREFIX}${randomBytes(32).toString("base64url")}`;
+  const tokenHash = await cryptoProvider.hmac({ data: token, domain: TOKEN_DOMAIN });
+  const record = {
+    id: `tok_auth_${randomUUID().slice(0, 8)}`,
+    tokenHash,
+    type,
+    scopes,
+    labels,
+    createdAt: new Date().toISOString(),
+    disabled: false
+  };
+
+  const store = await readAuthStore(path);
+  store.tokens.push(record);
+  await writeAuthStore(path, store);
+
+  // The plaintext token is returned to the caller for one-time display only.
+  return { token, record: publicRecord(record) };
+}
+
+export async function listTokens(path) {
+  const store = await readAuthStore(path);
+  return store.tokens.map(publicRecord);
+}
+
+export async function revokeToken({ path, id }) {
+  const store = await readAuthStore(path);
+  const record = store.tokens.find((entry) => entry.id === id);
+  if (!record) {
+    throw new Error(`Unknown token id: ${id}`);
+  }
+  const changed = !record.disabled;
+  record.disabled = true;
+  await writeAuthStore(path, store);
+  return { id, revoked: changed };
+}
+
+function publicRecord(record) {
+  // Never expose the token or its hash.
+  return {
+    id: record.id,
+    type: record.type,
+    scopes: record.scopes,
+    labels: record.labels,
+    createdAt: record.createdAt,
+    disabled: Boolean(record.disabled)
+  };
+}
+
+export async function buildIdentity(record, cryptoProvider) {
+  return {
+    id: record.id,
+    type: record.type,
+    subjectHash: await cryptoProvider.hmac({ data: record.id, domain: IDENTITY_DOMAIN }),
+    issuerHash: await cryptoProvider.hmac({ data: "bearer-local", domain: IDENTITY_DOMAIN }),
+    provider: "bearer",
+    scopes: record.scopes ?? [],
+    labels: record.labels ?? {}
+  };
+}
+
+function bearerTokenFromRequest(request) {
+  const header = request?.headers?.authorization ?? request?.headers?.Authorization;
+  if (typeof header !== "string") {
+    return null;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : null;
+}
+
+function constantTimeHashMatch(candidateHash, storedHash) {
+  const a = Buffer.from(candidateHash, "utf8");
+  const b = Buffer.from(storedHash, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+// authProvider contract: authenticate(request) -> identity | null. Fails closed
+// (null/deny) for a missing/invalid/disabled token; throws are treated as deny
+// by the caller.
+export function createBearerAuthProvider({ path, cryptoProvider }) {
+  if (!path) {
+    throw new Error("Bearer auth provider requires a store path");
+  }
+  if (typeof cryptoProvider?.hmac !== "function") {
+    throw new Error("Bearer auth provider requires a cryptoProvider with hmac()");
+  }
+  return {
+    id: "haechi.auth.bearer",
+    async authenticate(request) {
+      const token = bearerTokenFromRequest(request);
+      if (!token) {
+        return null;
+      }
+      const candidateHash = await cryptoProvider.hmac({ data: token, domain: TOKEN_DOMAIN });
+      const store = await readAuthStore(path);
+      let matched = null;
+      // Scan every record (no early return) so timing does not reveal which
+      // token matched.
+      for (const record of store.tokens) {
+        if (!record.disabled && constantTimeHashMatch(candidateHash, record.tokenHash)) {
+          matched = record;
+        }
+      }
+      if (!matched) {
+        return null;
+      }
+      return buildIdentity(matched, cryptoProvider);
+    }
+  };
+}
+
+export { DEFAULT_ALLOWED_LABEL_KEYS };

package/packages/cli/bin/haechi.mjs

@@ -5,6 +5,8 @@ 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, wrapMcpChild } from "../../mcp-stdio/index.mjs";
+import { addToken, listTokens, revokeToken } from "../../auth/index.mjs";
+import { createLocalCryptoProvider } from "../../crypto/index.mjs";
 import { spawn } from "node:child_process";
 import { DEFAULT_CONFIG_PATH, createRuntime, isValidPort, loadConfig, writeDefaultConfig } from "../runtime.mjs";
 
@@ -55,6 +57,9 @@ try {
     case "mcp-wrap":
       await mcpWrapCommand(argv);
       break;
+    case "auth":
+      await authCommand(argv);
+      break;
     case "config":
       printConfigGuide();
       break;
@@ -142,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) {
@@ -203,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,
@@ -402,6 +428,76 @@ async function pluginValidateCommand(argv) {
   }
 }
 
+async function authCommand(argv) {
+  const [sub, ...rest] = argv;
+  const options = parseOptions(rest);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  if (config.keys.provider !== "local") {
+    throw new Error("haechi auth requires keys.provider local (the bearer store is hashed with the local key)");
+  }
+  const cryptoProvider = createLocalCryptoProvider({ keyFile: config.keys.keyFile });
+  const storePath = config.auth.store;
+
+  switch (sub) {
+    case "add": {
+      if (!options.type || options.type === true) {
+        throw new Error("auth add requires --type user|service|agent");
+      }
+      const { token, record } = await addToken({
+        path: storePath,
+        cryptoProvider,
+        type: options.type,
+        scopes: asList(options.scope),
+        labels: asLabels(options.label),
+        allowedLabelKeys: config.auth.allowedLabelKeys
+      });
+      writeJson({
+        ok: true,
+        command: "auth add",
+        id: record.id,
+        type: record.type,
+        scopes: record.scopes,
+        labels: record.labels,
+        token,
+        warning: "This token is shown only once. Store it now; it is not recoverable."
+      });
+      return;
+    }
+    case "list":
+      writeJson({ ok: true, command: "auth list", tokens: await listTokens(storePath) });
+      return;
+    case "revoke": {
+      const [id] = rest;
+      if (!id || id.startsWith("--")) {
+        throw new Error("auth revoke requires a token id");
+      }
+      writeJson({ ok: true, command: "auth revoke", result: await revokeToken({ path: storePath, id }) });
+      return;
+    }
+    default:
+      throw new Error("auth requires a subcommand: add | list | revoke");
+  }
+}
+
+function asList(value) {
+  if (!value || value === true) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+function asLabels(value) {
+  const labels = {};
+  for (const entry of asList(value)) {
+    const index = entry.indexOf("=");
+    if (index === -1) {
+      throw new Error(`Invalid --label (expected key=value): ${entry}`);
+    }
+    labels[entry.slice(0, index)] = entry.slice(index + 1);
+  }
+  return labels;
+}
+
 async function mcpStdioCommand(argv) {
   const options = parseOptions(argv);
   const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
@@ -442,12 +538,17 @@ function parseOptions(argv) {
     }
     const key = arg.slice(2);
     const next = argv[index + 1];
-    if (!next || next.startsWith("--")) {
-      options[key] = true;
-      continue;
+    const value = (!next || next.startsWith("--")) ? true : next;
+    if (value !== true) {
+      index += 1;
+    }
+    // Repeated flags accumulate into an array (e.g. --scope a --scope b);
+    // a single occurrence stays scalar for backward compatibility.
+    if (Object.prototype.hasOwnProperty.call(options, key)) {
+      options[key] = Array.isArray(options[key]) ? [...options[key], value] : [options[key], value];
+    } else {
+      options[key] = value;
     }
-    options[key] = next;
-    index += 1;
   }
   return options;
 }
@@ -486,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]",
@@ -534,6 +635,11 @@ const COMMAND_HELP = {
     summary: "Wrap an MCP server with bidirectional stdio protection.",
     detail: "Spawns <command>, applies the method allowlist + params protection client→server, and result protection + injection heuristics server→client. Drop-in for MCP client configs."
   },
+  auth: {
+    usage: "haechi auth add --type user|service|agent [--scope k:v ...] [--label k=v ...]\n  haechi auth list [--config haechi.config.json]\n  haechi auth revoke <id> [--config haechi.config.json]",
+    summary: "Manage built-in bearer tokens (separate store, hashed).",
+    detail: "Tokens are stored hashed in auth.store (default .haechi/auth.json, 0600). `add` prints the plaintext token once — it cannot be recovered. `list` never reveals tokens; `revoke` disables one by id."
+  },
   config: {
     usage: "haechi config",
     summary: "Print the configuration guide (keys, defaults, common setups)."
@@ -551,7 +657,7 @@ function printHelp(topic) {
     "init", "protect", "report", "status", "audit-verify", "proxy",
     "policy-sign", "policy-verify",
     "token-reveal", "token-purge", "token-export",
-    "plugin-validate", "mcp-stdio", "mcp-wrap", "config"
+    "plugin-validate", "mcp-stdio", "mcp-wrap", "auth", "config"
   ];
   const lines = order.map((name) => `  ${name.padEnd(16)}${COMMAND_HELP[name].summary}`);
   console.log(`Haechi — self-hosted AI context enforcement (developer preview)
@@ -613,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