haechi 0.3.2 → 0.5.0

package/packages/cli/bin/haechi.mjs

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
-import { readAuditSummary } from "../../audit/index.mjs";
+import { readFile, stat } from "node:fs/promises";
+import { readAuditSummary, verifyAuditChain } 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 { runMcpStdioFilter, wrapMcpChild } from "../../mcp-stdio/index.mjs";
+import { spawn } from "node:child_process";
 import { DEFAULT_CONFIG_PATH, createRuntime, isValidPort, loadConfig, writeDefaultConfig } from "../runtime.mjs";
 
 const [command, ...argv] = process.argv.slice(2);
 
+async function main(command, argv) {
 try {
   switch (command) {
     case "init":
@@ -20,6 +22,12 @@ try {
     case "report":
       await reportCommand(argv);
       break;
+    case "audit-verify":
+      await auditVerifyCommand(argv);
+      break;
+    case "status":
+      await statusCommand(argv);
+      break;
     case "proxy":
       await proxyCommand(argv);
       break;
@@ -44,19 +52,26 @@ try {
     case "mcp-stdio":
       await mcpStdioCommand(argv);
       break;
+    case "mcp-wrap":
+      await mcpWrapCommand(argv);
+      break;
+    case "config":
+      printConfigGuide();
+      break;
     case "help":
     case "--help":
     case "-h":
     case undefined:
-      printHelp();
+      printHelp(argv[0]);
       break;
     default:
-      throw new Error(`Unknown command: ${command}`);
+      throw new Error(`Unknown command: ${command}. Run 'haechi help' for usage.`);
   }
 } catch (error) {
   console.error(`haechi: ${error.message}`);
   process.exitCode = process.exitCode || 1;
 }
+}
 
 async function initCommand(argv) {
   const options = parseOptions(argv);
@@ -91,6 +106,7 @@ async function protectCommand(argv) {
   const result = await runtime.haechi.protectJson(input, {
     protocol: config.target.type,
     operation: "cli protect",
+    direction: "request",
     mode: effectiveMode
   });
 
@@ -123,6 +139,117 @@ async function reportCommand(argv) {
   });
 }
 
+async function auditVerifyCommand(argv) {
+  const options = parseOptions(argv);
+  let auditPath = options.audit ?? options.path;
+  if (!auditPath) {
+    try {
+      auditPath = (await loadConfig(options.config ?? DEFAULT_CONFIG_PATH)).audit.path;
+    } catch {
+      auditPath = ".haechi/audit.jsonl";
+    }
+  }
+
+  const result = await verifyAuditChain(auditPath);
+  writeJson({
+    ok: result.valid,
+    command: "audit-verify",
+    auditPath,
+    result
+  });
+  if (!result.valid) {
+    process.exitCode = 4;
+  }
+}
+
+async function statusCommand(argv) {
+  const options = parseOptions(argv);
+  const configPath = options.config ?? DEFAULT_CONFIG_PATH;
+  const config = await loadConfig(configPath);
+  const effectiveMode = config.policy.mode ?? config.mode;
+  const enforced = !["dry-run", "report-only"].includes(effectiveMode);
+  const warnings = [];
+
+  if (!enforced) {
+    warnings.push(`policy mode is ${effectiveMode}: payloads are inspected and audited but NOT modified or blocked`);
+  }
+  if (!config.responseProtection.enabled) {
+    warnings.push("responseProtection.enabled is false: upstream responses are forwarded without inspection");
+  }
+  if (config.streaming.requestMode === "pass-through") {
+    warnings.push("streaming.requestMode is pass-through: streaming payloads are not protected");
+  }
+  if (config.tokenVault.revealPolicy !== "disabled") {
+    warnings.push(`tokenVault.revealPolicy is ${config.tokenVault.revealPolicy}: manual token reveal is enabled`);
+  }
+  if (config.tokenVault.detokenizeResponses && !config.responseProtection.enabled) {
+    warnings.push("tokenVault.detokenizeResponses is true but responseProtection.enabled is false: detokenization never runs");
+  }
+
+  const keys = {
+    provider: config.keys.provider,
+    keyFile: config.keys.keyFile,
+    exists: false,
+    permissions: null
+  };
+  try {
+    const info = await stat(config.keys.keyFile);
+    keys.exists = true;
+    keys.permissions = `0${(info.mode & 0o777).toString(8)}`;
+    if ((info.mode & 0o077) !== 0) {
+      warnings.push(`key file ${config.keys.keyFile} is group/world accessible (${keys.permissions}); expected 0600`);
+    }
+  } catch {
+    warnings.push(`key file ${config.keys.keyFile} does not exist; run haechi init`);
+  }
+
+  const audit = { path: config.audit.path, exists: false, chain: null };
+  try {
+    await stat(config.audit.path);
+    audit.exists = true;
+    audit.chain = await verifyAuditChain(config.audit.path);
+    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.
+  }
+
+  writeJson({
+    ok: true,
+    command: "status",
+    configPath,
+    protection: {
+      policyMode: effectiveMode,
+      enforced,
+      responseProtection: {
+        enabled: config.responseProtection.enabled,
+        mode: config.responseProtection.mode,
+        failureMode: config.responseProtection.failureMode
+      },
+      streamingRequestMode: config.streaming.requestMode,
+      streamingResponseMode: config.streaming.responseMode
+    },
+    target: {
+      type: config.target.type,
+      adapter: config.target.adapter,
+      upstream: config.target.upstream
+    },
+    proxy: config.proxy,
+    tokenVault: {
+      revealPolicy: config.tokenVault.revealPolicy,
+      retentionDays: config.tokenVault.retentionDays,
+      deterministic: config.tokenVault.deterministic,
+      deterministicTypes: config.tokenVault.deterministicTypes,
+      detokenizeResponses: config.tokenVault.detokenizeResponses
+    },
+    privacyProfile: config.privacy.profile,
+    keys,
+    audit,
+    warnings
+  });
+}
+
 async function proxyCommand(argv) {
   const options = parseOptions(argv);
   const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
@@ -282,6 +409,30 @@ async function mcpStdioCommand(argv) {
   await runMcpStdioFilter({ runtime });
 }
 
+async function mcpWrapCommand(argv) {
+  const separator = argv.indexOf("--");
+  if (separator === -1 || !argv[separator + 1]) {
+    throw new Error("mcp-wrap requires a child command after --, e.g. haechi mcp-wrap -- npx some-mcp-server");
+  }
+  const options = parseOptions(argv.slice(0, separator));
+  const command = argv[separator + 1];
+  const commandArgs = argv.slice(separator + 2);
+
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  const runtime = createRuntime(config);
+
+  const child = spawn(command, commandArgs, {
+    stdio: ["pipe", "pipe", "inherit"]
+  });
+
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => child.kill(signal));
+  }
+
+  const { code } = await wrapMcpChild({ runtime, child });
+  process.exitCode = code;
+}
+
 function parseOptions(argv) {
   const options = {};
   for (let index = 0; index < argv.length; index += 1) {
@@ -319,23 +470,161 @@ function parsePort(value) {
   return port;
 }
 
-function printHelp() {
-  console.log(`Haechi MVP CLI
+const COMMAND_HELP = {
+  init: {
+    usage: "haechi init [--config haechi.config.json] [--force]",
+    summary: "Create a local key, sample config, and audit path.",
+    detail: "Writes haechi.config.json and .haechi/dev.keys.json (0600). --force rotates the key (prior keys are retired, not deleted) and overwrites the config."
+  },
+  protect: {
+    usage: "haechi protect <input.json> [--config haechi.config.json]",
+    summary: "Inspect and protect a JSON payload, printing the result.",
+    detail: "Reads input.json, applies the policy, and prints the protected payload, audit id, and warnings. Exit 3 if the payload is blocked."
+  },
+  report: {
+    usage: "haechi report [--audit .haechi/audit.jsonl]",
+    summary: "Summarize audit events without raw payloads."
+  },
+  "audit-verify": {
+    usage: "haechi audit-verify [--audit .haechi/audit.jsonl] [--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."
+  },
+  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."
+  },
+  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'."
+  },
+  "policy-sign": {
+    usage: "haechi policy-sign <policy.json> [--config haechi.config.json] [--out policy.bundle.json]",
+    summary: "Sign a policy file into a verifiable bundle."
+  },
+  "policy-verify": {
+    usage: "haechi policy-verify <policy.bundle.json> [--config haechi.config.json]",
+    summary: "Verify a signed policy bundle against the configured key."
+  },
+  "token-reveal": {
+    usage: "haechi token-reveal <token> [--config haechi.config.json] [--allow-dev-reveal]",
+    summary: "Reveal a tokenized value (governed by tokenVault.revealPolicy; audited).",
+    detail: "Fails unless revealPolicy is local-dev or --allow-dev-reveal is passed."
+  },
+  "token-purge": {
+    usage: "haechi token-purge <token> [--config haechi.config.json]\n  haechi token-purge --expired [--config haechi.config.json]",
+    summary: "Purge a specific token, or all expired tokens with --expired."
+  },
+  "token-export": {
+    usage: "haechi token-export [--config haechi.config.json] [--type email]",
+    summary: "Export token metadata (never plaintext), optionally filtered by type."
+  },
+  "plugin-validate": {
+    usage: "haechi plugin-validate <plugin-manifest.json>",
+    summary: "Validate a plugin manifest (manifest-only; dynamic runtime is rejected)."
+  },
+  "mcp-stdio": {
+    usage: "haechi mcp-stdio [--config haechi.config.json]",
+    summary: "Filter MCP JSON-RPC traffic on stdin/stdout (one direction)."
+  },
+  "mcp-wrap": {
+    usage: "haechi mcp-wrap [--config haechi.config.json] -- <command> [args...]",
+    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."
+  },
+  config: {
+    usage: "haechi config",
+    summary: "Print the configuration guide (keys, defaults, common setups)."
+  }
+};
+
+function printHelp(topic) {
+  if (topic && COMMAND_HELP[topic]) {
+    const entry = COMMAND_HELP[topic];
+    console.log(`haechi ${topic} — ${entry.summary}\n\nUsage:\n  ${entry.usage}${entry.detail ? `\n\n${entry.detail}` : ""}`);
+    return;
+  }
+
+  const order = [
+    "init", "protect", "report", "status", "audit-verify", "proxy",
+    "policy-sign", "policy-verify",
+    "token-reveal", "token-purge", "token-export",
+    "plugin-validate", "mcp-stdio", "mcp-wrap", "config"
+  ];
+  const lines = order.map((name) => `  ${name.padEnd(16)}${COMMAND_HELP[name].summary}`);
+  console.log(`Haechi — self-hosted AI context enforcement (developer preview)
 
 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.
+  haechi <command> [options]
+  haechi help <command>     show usage for one command
+
+Commands:
+${lines.join("\n")}
+
+Getting started:
+  haechi init               write config + local key
+  haechi status             see what is protected
+  haechi config             configuration guide
+
+The default policy mode is dry-run (detect + audit only). Set policy.mode to
+"enforce" to transform or block. Run 'haechi config' for all settings.
+`);
+}
+
+function printConfigGuide() {
+  console.log(`Haechi configuration guide
+
+Config file: haechi.config.json (override with --config <path>); template at
+haechi.config.example.json. All values are validated fail-closed — unknown or
+malformed settings refuse to start. 'haechi status' prints the EFFECTIVE state.
+
+Enforcement
+  mode / policy.mode        dry-run | report-only | enforce   (default dry-run)
+                            dry-run/report-only detect + audit only.
+                            policy.mode overrides mode.
+
+Upstream + proxy
+  target.type               llm-http | openai-compatible | vllm-openai |
+                            ollama | llama-cpp                 (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)
+
+Response + streaming
+  responseProtection.enabled  inspect upstream responses        (default false)
+  responseProtection.failureMode  fail-closed | allow           (default fail-closed)
+  streaming.requestMode     block | pass-through | inspect       (default block)
+                            inspect = stream-filter SSE/NDJSON responses
+  streaming.maxMatchBytes   cross-frame match window             (default 256)
+  limits.upstreamTimeoutMs  upstream timeout in ms              (default 120000)
+
+Detection policy
+  policy.presets            korean-pii, secrets-only, llm-redact,
+                            strict-block, mcp-basic, local-inference, local-only
+  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)
+
+Tokenization (model sees token, caller sees plaintext)
+  tokenVault.revealPolicy   disabled | local-dev               (manual reveal gate)
+  tokenVault.deterministic  same value -> same token           (default false)
+  tokenVault.detokenizeResponses  restore request-issued tokens in the response
+                            (needs responseProtection.enabled)
+
+Privacy + MCP
+  privacy.profile           kr-pipa | eu-gdpr | us-general | null
+  mcp.allowedMethods        client-callable method allowlist
+
+Binding beyond loopback (0.0.0.0):
+  haechi proxy --host 0.0.0.0 --allow-remote-bind
+  There is NO client auth yet (planned 0.6). Use only behind network controls:
+  bind 0.0.0.0 in a container and map -p 127.0.0.1:${DEFAULT_PROXY_PORT}:${DEFAULT_PROXY_PORT}, or front
+  it with a firewall/VPN/authenticating reverse proxy.
+
+Full reference: docs/current/configuration.md
 `);
 }
+
+await main(command, argv);

package/packages/cli/runtime.mjs

@@ -34,7 +34,9 @@ export function defaultConfig() {
       maxBytes: 1048576
     },
     streaming: {
-      requestMode: "block"
+      requestMode: "block",
+      responseMode: "enforce",
+      maxMatchBytes: 256
     },
     limits: {
       maxRequestBytes: 1048576,
@@ -63,7 +65,10 @@ export function defaultConfig() {
       provider: "local",
       path: ".haechi/token-vault.json",
       revealPolicy: "disabled",
-      retentionDays: 30
+      retentionDays: 30,
+      deterministic: false,
+      deterministicTypes: null,
+      detokenizeResponses: false
     },
     privacy: {
       profile: null
@@ -113,6 +118,8 @@ export function createRuntime(config, providers = {}) {
     cryptoProvider,
     revealPolicy: normalized.tokenVault.revealPolicy,
     retentionDays: normalized.tokenVault.retentionDays,
+    deterministic: normalized.tokenVault.deterministic,
+    deterministicTypes: normalized.tokenVault.deterministicTypes,
     auditSink
   });
   assertProvider("tokenVault", tokenVault, ["tokenize", "reveal", "purge"]);
@@ -233,6 +240,18 @@ export function normalizeConfig(config) {
   if (typeof merged.tokenVault.retentionDays !== "number" || merged.tokenVault.retentionDays < 1) {
     throw new Error("tokenVault.retentionDays must be a positive number");
   }
+  if (typeof merged.tokenVault.deterministic !== "boolean") {
+    throw new Error("tokenVault.deterministic must be boolean");
+  }
+  if (merged.tokenVault.deterministicTypes !== null
+    && (!Array.isArray(merged.tokenVault.deterministicTypes)
+      || merged.tokenVault.deterministicTypes.length === 0
+      || !merged.tokenVault.deterministicTypes.every((type) => typeof type === "string" && type.trim()))) {
+    throw new Error("tokenVault.deterministicTypes must be null or a non-empty array of type strings");
+  }
+  if (typeof merged.tokenVault.detokenizeResponses !== "boolean") {
+    throw new Error("tokenVault.detokenizeResponses must be boolean");
+  }
   if (!Array.isArray(merged.mcp.allowedMethods) || merged.mcp.allowedMethods.length === 0) {
     throw new Error("mcp.allowedMethods must be a non-empty array");
   }
@@ -254,9 +273,15 @@ export function normalizeConfig(config) {
   if (typeof merged.responseProtection.maxBytes !== "number" || merged.responseProtection.maxBytes < 1) {
     throw new Error("responseProtection.maxBytes must be a positive number");
   }
-  if (!["block", "pass-through"].includes(merged.streaming.requestMode)) {
+  if (!["block", "pass-through", "inspect"].includes(merged.streaming.requestMode)) {
     throw new Error(`Invalid streaming.requestMode: ${merged.streaming.requestMode}`);
   }
+  if (!["dry-run", "report-only", "enforce"].includes(merged.streaming.responseMode)) {
+    throw new Error(`Invalid streaming.responseMode: ${merged.streaming.responseMode}`);
+  }
+  if (typeof merged.streaming.maxMatchBytes !== "number" || merged.streaming.maxMatchBytes < 1) {
+    throw new Error("streaming.maxMatchBytes must be a positive number");
+  }
   if (typeof merged.limits.maxRequestBytes !== "number" || merged.limits.maxRequestBytes < 1) {
     throw new Error("limits.maxRequestBytes must be a positive number");
   }

package/packages/core/index.mjs

@@ -19,11 +19,15 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
 
     const enforced = !NO_ENFORCE_MODES.has(effectiveMode);
     const blocked = enforced && decisions.some((decision) => decision.action === "block");
+    // Tokens issued or reused while protecting THIS payload; the proxy uses
+    // this request-scoped set to restore only these tokens in the response.
+    const issuedTokens = new Set();
     const protectedPayload = blocked ? null : await transformPayload(payload, detections, decisions, {
       context,
       cryptoProvider,
       tokenVault,
-      enforced
+      enforced,
+      issuedTokens
     });
 
     const auditEvent = buildAuditEvent({
@@ -42,11 +46,121 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
       payload: protectedPayload,
       blocked,
       summary: summarize(detections, decisions),
-      auditEvent
+      auditEvent,
+      issuedTokens: [...issuedTokens]
+    };
+  }
+
+  // Stateful protector for an incremental text stream (SSE/NDJSON deltas).
+  // Holds a bounded raw tail so a detection split across chunk boundaries is
+  // caught before the leading part is emitted. maxMatchBytes bounds the
+  // guarantee: a single match longer than it may still split across frames.
+  function createStreamProtector(context = {}) {
+    const effectiveMode = context.mode ?? mode;
+    const enforced = !NO_ENFORCE_MODES.has(effectiveMode);
+    const maxMatchBytes = context.maxMatchBytes ?? 256;
+    const byType = {};
+    const byAction = {};
+    let detectionCount = 0;
+    let pending = "";
+
+    function tally(detections, decisions) {
+      detections.forEach((detection, index) => {
+        byType[detection.type] = (byType[detection.type] ?? 0) + 1;
+        const action = decisions[index]?.action ?? "unknown";
+        byAction[action] = (byAction[action] ?? 0) + 1;
+        detectionCount += 1;
+      });
+    }
+
+    async function decideAll(detections) {
+      const decisions = [];
+      for (const detection of detections) {
+        decisions.push(await policyEngine.decide({ detection, context, mode: effectiveMode }));
+      }
+      return decisions;
+    }
+
+    // Transform a complete, committed text segment.
+    async function transformSegment(text) {
+      const detections = await filterEngine.detect({
+        entries: collectStringEntries(text),
+        context
+      });
+      const decisions = await decideAll(detections);
+      tally(detections, decisions);
+      const blocked = enforced && decisions.some((decision) => decision.action === "block");
+      if (blocked) {
+        return { text: "", blocked: true };
+      }
+      if (!enforced || detections.length === 0) {
+        return { text, blocked: false };
+      }
+      const items = detections.map((detection, index) => ({ detection, decision: decisions[index] }));
+      const transformed = await transformString(text, items, { context, cryptoProvider, tokenVault, issuedTokens: null });
+      return { text: transformed, blocked: false };
+    }
+
+    return {
+      // Protect string leaves of a parsed frame OTHER than the incremental
+      // delta text (e.g. tool-call arguments). Returns the mutated object.
+      async protectFrameExtras(value) {
+        const detections = await filterEngine.detect({
+          entries: collectStringEntries(value),
+          context
+        });
+        if (detections.length === 0) {
+          return { value, blocked: false };
+        }
+        const decisions = await decideAll(detections);
+        tally(detections, decisions);
+        const blocked = enforced && decisions.some((decision) => decision.action === "block");
+        if (blocked) {
+          return { value: null, blocked: true };
+        }
+        if (!enforced) {
+          return { value, blocked: false };
+        }
+        const transformed = await transformPayload(value, detections, decisions, {
+          context, cryptoProvider, tokenVault, enforced
+        });
+        return { value: transformed, blocked: false };
+      },
+      // Append incremental text; return the portion safe to emit now.
+      async push(text) {
+        pending += text;
+        const detections = await filterEngine.detect({
+          entries: collectStringEntries(pending),
+          context
+        });
+        let commit = Math.max(0, pending.length - maxMatchBytes);
+        const straddlers = detections.filter((detection) => detection.end > commit);
+        if (straddlers.length > 0) {
+          commit = Math.min(commit, ...straddlers.map((detection) => detection.start));
+        }
+        if (commit <= 0) {
+          return { text: "", blocked: false };
+        }
+        const head = pending.slice(0, commit);
+        pending = pending.slice(commit);
+        return transformSegment(head);
+      },
+      // Drain the held tail at end of stream (no more cross-frame risk).
+      async flush() {
+        const tail = pending;
+        pending = "";
+        if (!tail) {
+          return { text: "", blocked: false };
+        }
+        return transformSegment(tail);
+      },
+      summary() {
+        return { detectionCount, byType, byAction };
+      }
     };
   }
 
-  return { protectJson };
+  return { protectJson, createStreamProtector };
 }
 
 export function collectStringEntries(value, path = []) {
@@ -127,7 +241,7 @@ export function summarize(detections, decisions) {
   };
 }
 
-async function transformPayload(payload, detections, decisions, { context, cryptoProvider, tokenVault, enforced }) {
+async function transformPayload(payload, detections, decisions, { context, cryptoProvider, tokenVault, enforced, issuedTokens = null }) {
   if (!enforced || detections.length === 0) {
     return structuredClone(payload);
   }
@@ -155,7 +269,7 @@ async function transformPayload(payload, detections, decisions, { context, crypt
       if (typeof original !== "number") {
         continue;
       }
-      const transformed = await transformString(String(original), items, { context, cryptoProvider, tokenVault });
+      const transformed = await transformString(String(original), items, { context, cryptoProvider, tokenVault, issuedTokens });
       if (transformed !== String(original)) {
         setByPath(output, path, transformed);
       }
@@ -164,7 +278,7 @@ async function transformPayload(payload, detections, decisions, { context, crypt
     if (typeof original !== "string") {
       continue;
     }
-    const transformed = await transformString(original, items, { context, cryptoProvider, tokenVault });
+    const transformed = await transformString(original, items, { context, cryptoProvider, tokenVault, issuedTokens });
     setByPath(output, path, transformed);
   }
 
@@ -179,7 +293,7 @@ async function transformPayload(payload, detections, decisions, { context, crypt
       || !Object.prototype.hasOwnProperty.call(parent, originalKey)) {
       continue;
     }
-    const transformedKey = await transformString(String(originalKey), items, { context, cryptoProvider, tokenVault });
+    const transformedKey = await transformString(String(originalKey), items, { context, cryptoProvider, tokenVault, issuedTokens });
     if (transformedKey === originalKey) {
       continue;
     }
@@ -197,7 +311,7 @@ async function transformPayload(payload, detections, decisions, { context, crypt
   return output;
 }
 
-async function transformString(value, items, { context, cryptoProvider, tokenVault }) {
+async function transformString(value, items, { context, cryptoProvider, tokenVault, issuedTokens = null }) {
   const sorted = items
     .filter(({ decision }) => decision.action !== "allow" && decision.action !== "block")
     .sort((left, right) => left.detection.start - right.detection.start);
@@ -212,7 +326,7 @@ async function transformString(value, items, { context, cryptoProvider, tokenVau
 
     output += value.slice(cursor, detection.start);
     const segment = value.slice(detection.start, detection.end);
-    output += await replacementFor(segment, detection, decision, { context, cryptoProvider, tokenVault });
+    output += await replacementFor(segment, detection, decision, { context, cryptoProvider, tokenVault, issuedTokens });
     cursor = detection.end;
   }
 
@@ -220,7 +334,7 @@ async function transformString(value, items, { context, cryptoProvider, tokenVau
   return output;
 }
 
-async function replacementFor(segment, detection, decision, { context, cryptoProvider, tokenVault }) {
+async function replacementFor(segment, detection, decision, { context, cryptoProvider, tokenVault, issuedTokens = null }) {
   switch (decision.action) {
     case "redact":
       return `[REDACTED:${detection.type}]`;
@@ -237,6 +351,7 @@ async function replacementFor(segment, detection, decision, { context, cryptoPro
             ruleId: detection.ruleId
           }
         });
+        issuedTokens?.add(result.token);
         return `[TOKEN:${result.token}]`;
       }
       return `[TOKEN:${detection.type}:${shortHash(segment)}]`;
@@ -263,6 +378,9 @@ function buildAuditEvent({ context, mode, enforced, blocked, payload, detections
     timestamp: new Date().toISOString(),
     protocol: context.protocol ?? "custom",
     operation: context.operation ?? "protect",
+    // Reserved for 0.6 auth: hard null so unvalidated identity objects cannot
+    // reach the audit log before the PII-safe hashing contract exists.
+    identity: null,
     mode,
     enforced,
     blocked,