haechi 0.8.0 → 1.0.0

package/haechi.config.example.json

@@ -15,7 +15,8 @@
     "failureMode": "fail-closed",
     "allowNonJson": false,
     "allowCompressed": false,
-    "maxBytes": 1048576
+    "maxBytes": 1048576,
+    "scanNumbers": false
   },
   "streaming": {
     "requestMode": "block",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haechi",
-  "version": "0.8.0",
+  "version": "1.0.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",
@@ -72,8 +72,9 @@
     "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",
+    "check:peer-ranges": "node scripts/check-satellite-peer-ranges.mjs",
+    "release:preflight": "node scripts/release-preflight.mjs && node scripts/check-satellite-peer-ranges.mjs",
+    "release:preflight:npm": "node scripts/release-preflight.mjs --require-npm-auth && node scripts/check-satellite-peer-ranges.mjs",
     "haechi": "node packages/cli/bin/haechi.mjs",
     "demo:init": "node packages/cli/bin/haechi.mjs init --force",
     "demo:protect": "node packages/cli/bin/haechi.mjs protect examples/llm-prompt-filtering/input.json --config haechi.config.json",

package/packages/audit/index.mjs

@@ -5,7 +5,30 @@ import { dirname } from "node:path";
 import { createInterface } from "node:readline";
 import { setTimeout as delay } from "node:timers/promises";
 
-const FORBIDDEN_KEYS = new Set(["value", "plaintext", "payload", "content", "message", "prompt", "secret"]);
+const FORBIDDEN_KEYS = new Set([
+  "value", "plaintext", "payload", "content", "message", "prompt", "secret",
+  // OIDC-broker / OAuth token, secret, and authorization-flow parameter keys.
+  // These are never part of a current audit event shape; the membership is a
+  // defense-in-depth guard so a future audit field can never leak a token,
+  // client secret, or flow parameter through the core sink. `sub`/`email` are
+  // intentionally NOT listed — they can be legitimate non-secret field names
+  // elsewhere, and the broker already self-guards them via its own allowlist
+  // projection.
+  "access_token", "id_token", "refresh_token", "code", "code_verifier",
+  "client_secret", "state", "nonce",
+  // Plugin/claims surface (1.0): a dynamically-loaded auth plugin's lifecycle
+  // events carry only ids/hashes/counts, but this additive membership is
+  // defense-in-depth so a future plugin event can never leak a raw claim, the
+  // received credential/authorization, the signer's signature, or the entry
+  // source into the chained log.
+  "claims", "subject", "issuer", "credential", "authorization", "signature", "entry",
+  // The frozen 1.0 audit-identity contract is exactly {id,type,subjectHash,
+  // issuerHash,provider} — scopes/labels are NOT part of it. This additive
+  // guard ensures that even if a future code path passes an un-projected
+  // identity object, scopes/labels (which can carry attacker-controlled plugin
+  // claim values) can never enter the hash-chained audit record.
+  "scopes", "labels"
+]);
 
 export function createJsonlAuditSink({ path, anchor = null }) {
   if (!path) {

package/packages/auth/index.mjs

@@ -212,4 +212,177 @@ export function createBearerAuthProvider({ path, cryptoProvider }) {
   };
 }
 
+// Conformance suite for any authProvider — the CORRECTNESS gate the plugin
+// loader runs before wiring a (sandboxed) auth plugin. It is NOT a malice screen
+// (a signed plugin can detect a fixed test and behave, so vectors are randomized
+// per run and the host re-validates PII-safety per call); it asserts the
+// enumerated security behaviors of the authProvider contract:
+//   - missing credential -> null
+//   - malformed credential -> null
+//   - expired / not-yet-valid credential (clock via injected now) -> null
+//   - an internal throw surfaces to the caller as null (never propagates)
+//   - a returned identity MUST carry subjectHash AND issuerHash, and MUST NOT
+//     contain any field whose value equals the raw input subject or issuer
+//   - deny is DETERMINISTIC for identical input
+//   - a valid credential -> a well-formed PII-safe identity
+//
+// vectors lets a caller supply the request builders / raw values; by default a
+// randomized-per-run vector set is generated so a plugin cannot hardcode the
+// test. Mirrors assertCryptoProviderConformance's check/assert/failures shape.
+export async function assertAuthProviderConformance(provider, { now = Date.now(), vectors } = {}) {
+  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?.authenticate !== "function") {
+    throw new Error("authProvider must implement authenticate()");
+  }
+
+  const v = vectors ?? randomAuthVectors(now);
+
+  // A contract-conformant authProvider must never throw into the caller. We wrap
+  // every call so a throw becomes an explicit failure in the relevant check
+  // rather than aborting the whole suite — except the dedicated throw-vector
+  // check below, which asserts the provider itself swallowed the throw.
+  const callRaw = (request) => provider.authenticate(request);
+  const callSafe = async (request) => {
+    try {
+      return await provider.authenticate(request);
+    } catch (error) {
+      return { __threw: true, error };
+    }
+  };
+
+  await check("missing credential -> null", async () => {
+    const result = await callSafe(v.missing.request);
+    assert(!result?.__threw, "authenticate threw on a missing credential (must return null)");
+    assert(result === null, "missing credential must deny with null");
+  });
+
+  await check("malformed credential -> null", async () => {
+    const result = await callSafe(v.malformed.request);
+    assert(!result?.__threw, "authenticate threw on a malformed credential (must return null)");
+    assert(result === null, "malformed credential must deny with null");
+  });
+
+  await check("expired credential -> null", async () => {
+    const result = await callSafe(v.expired.request);
+    assert(!result?.__threw, "authenticate threw on an expired credential (must return null)");
+    assert(result === null, "expired credential must deny with null");
+  });
+
+  await check("not-yet-valid credential -> null", async () => {
+    const result = await callSafe(v.notYetValid.request);
+    assert(!result?.__threw, "authenticate threw on a not-yet-valid credential (must return null)");
+    assert(result === null, "not-yet-valid credential must deny with null");
+  });
+
+  await check("an internal throw surfaces to the caller as null (never propagates)", async () => {
+    let propagated = false;
+    let result;
+    try {
+      result = await callRaw(v.throwing.request);
+    } catch {
+      propagated = true;
+    }
+    assert(!propagated, "authenticate propagated an internal throw (must catch and deny with null)");
+    assert(result === null, "an internal error must deny with null, not a non-null identity");
+  });
+
+  await check("deny is deterministic for identical input", async () => {
+    const a = await callSafe(v.malformed.request);
+    const b = await callSafe(v.malformed.request);
+    assert(!a?.__threw && !b?.__threw, "authenticate threw while checking determinism");
+    assert(a === b, "deny is not deterministic for identical input (expected null both times)");
+    assert(a === null, "expected a deterministic null deny");
+  });
+
+  await check("valid credential -> a well-formed, PII-safe identity", async () => {
+    const identity = await callSafe(v.valid.request);
+    assert(!identity?.__threw, "authenticate threw on a valid credential");
+    assert(identity && typeof identity === "object", "a valid credential must return an identity object");
+    assert(typeof identity.subjectHash === "string" && identity.subjectHash.length > 0,
+      "identity must carry a non-empty subjectHash");
+    assert(typeof identity.issuerHash === "string" && identity.issuerHash.length > 0,
+      "identity must carry a non-empty issuerHash");
+    // PII-safety: no field value may equal the raw input subject or issuer.
+    assertNoRawPii(identity, v.valid.subject, v.valid.issuer, assert);
+
+    // Determinism for the accept path too: identical valid input -> identical
+    // identity (a non-deterministic identity breaks audit correlation).
+    const again = await callSafe(v.valid.request);
+    assert(!again?.__threw, "authenticate threw on a repeated valid credential");
+    assert(JSON.stringify(again) === JSON.stringify(identity),
+      "accept is not deterministic for identical valid input");
+  });
+
+  if (failures.length > 0) {
+    return { ok: false, failures };
+  }
+  return { ok: true, failures: [] };
+}
+
+// Recursively assert no value in the identity equals the raw subject/issuer. The
+// keyed-HMAC subjectHash/issuerHash are derived from these, so an equality
+// against the raw value would mean a PII leak (or an un-hashed passthrough).
+function assertNoRawPii(value, subject, issuer, assert, path = "identity") {
+  if (typeof value === "string") {
+    assert(value !== subject, `${path} contains the raw subject (PII leak)`);
+    assert(value !== issuer, `${path} contains the raw issuer (PII leak)`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => assertNoRawPii(item, subject, issuer, assert, `${path}[${i}]`));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) {
+      assertNoRawPii(item, subject, issuer, assert, `${path}.${key}`);
+    }
+  }
+}
+
+function randomAuthVectors(now) {
+  const nowMs = typeof now === "number" ? now : Date.parse(now);
+  // Per-run random so a plugin cannot hardcode the expected test values.
+  const nonce = randomBytes(8).toString("hex");
+  const subject = `subj-${randomBytes(6).toString("hex")}`;
+  const issuer = `iss-${randomBytes(6).toString("hex")}`;
+  const validToken = `valid.${nonce}.${randomBytes(8).toString("hex")}`;
+  const expiredToken = `expired.${nonce}.${randomBytes(8).toString("hex")}`;
+  const notYetToken = `notyet.${nonce}.${randomBytes(8).toString("hex")}`;
+  const malformedToken = `~malformed~${nonce}`;
+  const throwToken = `throw.${nonce}`;
+
+  const bearer = (token) => ({ headers: { authorization: `Bearer ${token}` } });
+  // The valid credential encodes the random subject/issuer so any provider that
+  // echoes/leaks them into the returned identity is caught by assertNoRawPii.
+  // The credential is structured as "valid.<nonce>.<randHex>.<subject>.<issuer>"
+  // so a provider COULD extract them — but it MUST then keyed-hash them (not echo
+  // them raw) for the PII-safety assertion to pass. This makes the default-vector
+  // PII check non-vacuous: a leaking provider fails without custom vectors.
+  const validTokenWithPii = `${validToken}.${subject}.${issuer}`;
+  return {
+    nowMs,
+    subject,
+    issuer,
+    missing: { request: { headers: {} } },
+    malformed: { request: bearer(malformedToken), token: malformedToken },
+    expired: { request: bearer(expiredToken), token: expiredToken },
+    notYetValid: { request: bearer(notYetToken), token: notYetToken },
+    throwing: { request: bearer(throwToken), token: throwToken },
+    valid: { request: bearer(validTokenWithPii), token: validTokenWithPii, subject, issuer }
+  };
+}
+
 export { DEFAULT_ALLOWED_LABEL_KEYS };

package/packages/cli/runtime.mjs

@@ -10,8 +10,22 @@ import { loadVerifiedPolicyBundleFileSync } from "../policy-bundle/index.mjs";
 import { createProtocolAdapter } from "../protocol-adapters/index.mjs";
 import { applyPrivacyProfile, getPrivacyProfile } from "../privacy-profiles/index.mjs";
 import { createBearerAuthProvider } from "../auth/index.mjs";
+import { createSandboxedAuthProviderSync } from "../plugin/index.mjs";
 import { DEFAULT_PROXY_PORT } from "../proxy/index.mjs";
 
+// Capability keys an operator may allowlist for a plugin. Mirrors the plugin
+// manifest's declared-capability set plus the authProvider-specific
+// readsCredentials. Inlined (not imported) to keep the dependency one-way.
+const KNOWN_PLUGIN_CAPABILITIES = new Set([
+  "readsPlaintext",
+  "writesPlaintext",
+  "networkEgress",
+  "fileWrite",
+  "auditWrite",
+  "externalSecrets",
+  "readsCredentials"
+]);
+
 export const DEFAULT_CONFIG_PATH = "haechi.config.json";
 
 export function defaultConfig() {
@@ -32,7 +46,8 @@ export function defaultConfig() {
       failureMode: "fail-closed",
       allowNonJson: false,
       allowCompressed: false,
-      maxBytes: 1048576
+      maxBytes: 1048576,
+      scanNumbers: false
     },
     streaming: {
       requestMode: "block",
@@ -84,6 +99,12 @@ export function defaultConfig() {
       store: ".haechi/auth.json",
       allowedLabelKeys: ["team", "env", "tier", "role"]
     },
+    // Top-level kill-switch for dynamic plugin loading (1.0 §2.2). Default true;
+    // an operator sets `plugins.enabled: false` to force-refuse construction of
+    // any sandboxed plugin (a live force-drop, since revocation is next-load).
+    plugins: {
+      enabled: true
+    },
     mcp: {
       allowedMethods: ["initialize", "tools/call", "resources/read", "prompts/get"],
       protectParams: true,
@@ -127,8 +148,10 @@ export function createRuntime(config, providers = {}) {
   // 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");
+    && (normalized.auth.provider === "bearer"
+      || normalized.auth.provider === "plugin"
+      || normalized.tokenVault.deterministic)) {
+    throw new Error("cryptoProvider must implement hmac() for bearer/plugin auth / deterministic tokenization");
   }
   const auditSink = providers.auditSink ?? createJsonlAuditSink({
     path: normalized.audit.path,
@@ -168,7 +191,7 @@ export function createRuntime(config, providers = {}) {
   const policyEngine = providers.policyEngine ?? policyProfiles.base.policyEngine;
   assertProvider("policyEngine", policyEngine, ["decide"]);
 
-  const authProvider = resolveAuthProvider(normalized, providers, cryptoProvider);
+  const authProvider = resolveAuthProvider(normalized, providers, cryptoProvider, auditSink);
 
   return {
     config: normalized,
@@ -249,6 +272,10 @@ export function normalizeConfig(config) {
       ...(config.auth ?? {}),
       allowedLabelKeys: config.auth?.allowedLabelKeys ?? defaultConfig().auth.allowedLabelKeys
     },
+    plugins: {
+      ...defaultConfig().plugins,
+      ...(config.plugins ?? {})
+    },
     mcp: {
       ...defaultConfig().mcp,
       ...(config.mcp ?? {}),
@@ -320,6 +347,9 @@ 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 (typeof merged.responseProtection.scanNumbers !== "boolean") {
+    throw new Error("responseProtection.scanNumbers must be boolean");
+  }
   if (!["block", "pass-through", "inspect"].includes(merged.streaming.requestMode)) {
     throw new Error(`Invalid streaming.requestMode: ${merged.streaming.requestMode}`);
   }
@@ -336,7 +366,7 @@ export function normalizeConfig(config) {
     throw new Error("limits.upstreamTimeoutMs must be a positive number");
   }
   validatePolicyExtras(merged.policy);
-  if (!["none", "bearer", "external"].includes(merged.auth.provider)) {
+  if (!["none", "bearer", "external", "plugin"].includes(merged.auth.provider)) {
     throw new Error(`Invalid auth.provider: ${merged.auth.provider}`);
   }
   if (typeof merged.auth.store !== "string" || !merged.auth.store.trim()) {
@@ -346,6 +376,9 @@ export function normalizeConfig(config) {
     || !merged.auth.allowedLabelKeys.every((key) => typeof key === "string" && key.trim())) {
     throw new Error("auth.allowedLabelKeys must be an array of non-empty strings");
   }
+  if (merged.auth.provider === "plugin") {
+    validatePluginAuthConfig(merged);
+  }
   createProtocolAdapter(merged.target);
   return merged;
 }
@@ -407,7 +440,124 @@ function assertRate(value, label) {
   }
 }
 
-function resolveAuthProvider(config, providers, cryptoProvider) {
+// Enumerated, fail-closed validation of auth.provider:"plugin" (1.0 §2.3). Every
+// rule throws a distinct error so a bad option is attributable. Mirrors the
+// keys/tokenVault rigor — no silent degradation.
+function validatePluginAuthConfig(merged) {
+  // Kill-switch: refuse to construct any plugin when plugins.enabled is false.
+  if (typeof merged.plugins?.enabled !== "boolean") {
+    throw new Error("plugins.enabled must be boolean");
+  }
+  if (merged.plugins.enabled === false) {
+    throw new Error("plugins are disabled (plugins.enabled: false); refusing to construct a plugin authProvider");
+  }
+
+  const plugin = merged.auth.plugin;
+  if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) {
+    throw new Error("auth.provider 'plugin' requires an auth.plugin object");
+  }
+  if (typeof plugin.manifestPath !== "string" || !plugin.manifestPath.trim()) {
+    throw new Error("auth.plugin.manifestPath must be a non-empty string");
+  }
+
+  // trustAnchors: a non-empty array of {keyId, publicKey} OR a non-empty object
+  // map keyId -> publicKey/anchor.
+  const anchors = plugin.trustAnchors;
+  if (Array.isArray(anchors)) {
+    if (anchors.length === 0) {
+      throw new Error("auth.plugin.trustAnchors must be a non-empty array");
+    }
+    for (const anchor of anchors) {
+      if (!anchor || typeof anchor !== "object"
+        || typeof anchor.keyId !== "string" || !anchor.keyId.trim()
+        || anchor.publicKey === undefined || anchor.publicKey === null) {
+        throw new Error("each auth.plugin.trustAnchors entry must be { keyId, publicKey }");
+      }
+    }
+  } else if (anchors && typeof anchors === "object") {
+    const keys = Object.keys(anchors);
+    if (keys.length === 0) {
+      throw new Error("auth.plugin.trustAnchors must be a non-empty object");
+    }
+    for (const keyId of keys) {
+      if (anchors[keyId] === undefined || anchors[keyId] === null) {
+        throw new Error(`auth.plugin.trustAnchors.${keyId} must be a public key`);
+      }
+    }
+  } else {
+    throw new Error("auth.plugin.trustAnchors must be a non-empty array or object of { keyId, publicKey }");
+  }
+
+  // allowCapabilities: an array of known capability keys, including readsCredentials.
+  if (!Array.isArray(plugin.allowCapabilities) || plugin.allowCapabilities.length === 0) {
+    throw new Error("auth.plugin.allowCapabilities must be a non-empty array of capability keys");
+  }
+  for (const capability of plugin.allowCapabilities) {
+    if (typeof capability !== "string" || !KNOWN_PLUGIN_CAPABILITIES.has(capability)) {
+      throw new Error(`auth.plugin.allowCapabilities contains an unknown capability: ${capability}`);
+    }
+  }
+  if (!plugin.allowCapabilities.includes("readsCredentials")) {
+    throw new Error("auth.plugin.allowCapabilities must include readsCredentials for an authProvider");
+  }
+
+  if (!Number.isInteger(plugin.timeoutMs) || plugin.timeoutMs <= 0) {
+    throw new Error("auth.plugin.timeoutMs must be a positive integer");
+  }
+
+  const limits = plugin.resourceLimits;
+  if (!limits || typeof limits !== "object" || Array.isArray(limits)
+    || !Number.isInteger(limits.maxOldGenerationSizeMb) || limits.maxOldGenerationSizeMb <= 0) {
+    throw new Error("auth.plugin.resourceLimits.maxOldGenerationSizeMb must be a positive integer");
+  }
+
+  if (plugin.maxPendingCalls !== undefined
+    && (!Number.isInteger(plugin.maxPendingCalls) || plugin.maxPendingCalls < 1)) {
+    throw new Error("auth.plugin.maxPendingCalls must be a positive integer");
+  }
+  if (plugin.maxMessageBytes !== undefined
+    && (!Number.isInteger(plugin.maxMessageBytes) || plugin.maxMessageBytes < 1)) {
+    throw new Error("auth.plugin.maxMessageBytes must be a positive integer");
+  }
+
+  if (plugin.pin !== undefined && plugin.pin !== null) {
+    if (typeof plugin.pin !== "object" || Array.isArray(plugin.pin)) {
+      throw new Error("auth.plugin.pin must be an object");
+    }
+    for (const field of ["version", "entrySha256", "manifestSha256"]) {
+      if (plugin.pin[field] !== undefined && plugin.pin[field] !== null
+        && (typeof plugin.pin[field] !== "string" || !plugin.pin[field].trim())) {
+        throw new Error(`auth.plugin.pin.${field} must be a non-empty string`);
+      }
+    }
+  }
+
+  if (plugin.revoked !== undefined && plugin.revoked !== null) {
+    if (typeof plugin.revoked !== "object" || Array.isArray(plugin.revoked)) {
+      throw new Error("auth.plugin.revoked must be an object");
+    }
+    for (const field of ["signerKeyIds", "entrySha256"]) {
+      if (plugin.revoked[field] !== undefined
+        && (!Array.isArray(plugin.revoked[field])
+          || !plugin.revoked[field].every((v) => typeof v === "string" && v.trim()))) {
+        throw new Error(`auth.plugin.revoked.${field} must be an array of non-empty strings`);
+      }
+    }
+  }
+
+  if (plugin.versionFloor !== undefined && plugin.versionFloor !== null) {
+    if (typeof plugin.versionFloor !== "object" || Array.isArray(plugin.versionFloor)) {
+      throw new Error("auth.plugin.versionFloor must be an object mapping pluginId -> version");
+    }
+    for (const [id, floor] of Object.entries(plugin.versionFloor)) {
+      if (typeof floor !== "string" || !floor.trim()) {
+        throw new Error(`auth.plugin.versionFloor.${id} must be a non-empty version string`);
+      }
+    }
+  }
+}
+
+function resolveAuthProvider(config, providers, cryptoProvider, auditSink) {
   if (config.auth.provider === "external") {
     if (typeof providers.authProvider?.authenticate !== "function") {
       throw new Error("auth.provider external requires createRuntime(config, { authProvider })");
@@ -421,9 +571,42 @@ function resolveAuthProvider(config, providers, cryptoProvider) {
   if (config.auth.provider === "bearer") {
     return createBearerAuthProvider({ path: config.auth.store, cryptoProvider });
   }
+  if (config.auth.provider === "plugin") {
+    const plugin = config.auth.plugin;
+    return createSandboxedAuthProviderSync({
+      manifestPath: plugin.manifestPath,
+      trustAnchors: normalizeTrustAnchors(plugin.trustAnchors),
+      allowCapabilities: plugin.allowCapabilities,
+      pin: plugin.pin ?? null,
+      revoked: plugin.revoked ?? {},
+      versionFloor: plugin.versionFloor ?? {},
+      timeoutMs: plugin.timeoutMs,
+      maxPendingCalls: plugin.maxPendingCalls,
+      maxMessageBytes: plugin.maxMessageBytes,
+      resourceLimits: plugin.resourceLimits,
+      coreVersion: plugin.coreVersion ?? null,
+      cryptoProvider,
+      auditSink,
+      allowedLabelKeys: config.auth.allowedLabelKeys
+    });
+  }
   return null;
 }
 
+// The config form is a non-empty array of { keyId, publicKey } OR an object map.
+// verifySignedPlugin resolves the anchor by signerKeyId against an object map, so
+// normalize an array form into that map here.
+function normalizeTrustAnchors(anchors) {
+  if (Array.isArray(anchors)) {
+    const map = {};
+    for (const anchor of anchors) {
+      map[anchor.keyId] = anchor.publicKey;
+    }
+    return map;
+  }
+  return anchors;
+}
+
 function createConfiguredCryptoProvider(config) {
   if (config.keys.provider === "external") {
     throw new Error("keys.provider external requires createRuntime(config, { cryptoProvider })");

package/packages/core/index.mjs

@@ -15,6 +15,10 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
     const effectiveMode = context.mode ?? mode;
     const engine = contextEngine ?? policyEngine;
     const entries = collectStringEntries(payload);
+    // `context` is threaded into detection as-is and is LOAD-BEARING: e.g.
+    // `context.direction` ("request" | "response") gates direction-scoped rules
+    // (injection) and the response-only marker exclusion in the filter engine.
+    // The proxy sets it per direction; do not drop it here.
     const detections = await filterEngine.detect({ entries, context });
     const decisions = [];
 
@@ -383,14 +387,29 @@ async function replacementFor(segment, detection, decision, { context, cryptoPro
 
 function buildAuditEvent({ context, mode, enforced, blocked, payload, detections, decisions }) {
   return {
+    // Reader-facing audit-event schema version (frozen as part of the 1.0 API
+    // contract — see docs/current/api-stability.md). Additive-only: a new field
+    // bumps nothing here; only a canonicalization change is a MAJOR schema bump
+    // (a new value + a reader migration). It is part of the canonicalized object
+    // and so is self-consistent for hash-chain verification of new events.
+    schemaVersion: "1",
     id: randomUUID(),
     timestamp: new Date().toISOString(),
     protocol: context.protocol ?? "custom",
     operation: context.operation ?? "protect",
-    // PII-safe identity built by the auth layer (subject/issuer are keyed
-    // HMACs); null when no auth is configured. `profile` is the resolved
-    // policy profile name (or null).
-    identity: context.identity ?? null,
+    // PII-safe identity — projected to the five frozen 1.0 audit-identity keys
+    // (id, type, subjectHash, issuerHash, provider). scopes/labels are available
+    // to the live policy engine via context.identity but are NOT part of the
+    // frozen audit schema (§2.1) and must never be persisted to the hash-chained
+    // log (an untrusted plugin's attacker-controlled label/scope value would
+    // otherwise enter the immutable audit record via this path).
+    identity: context.identity ? {
+      id: context.identity.id,
+      type: context.identity.type,
+      subjectHash: context.identity.subjectHash,
+      issuerHash: context.identity.issuerHash,
+      provider: context.identity.provider
+    } : null,
     profile: context.profile ?? null,
     mode,
     enforced,

package/packages/filter/index.mjs

@@ -7,11 +7,14 @@ const DEFAULT_RULES = [
     confidence: 0.95
   },
   {
+    // KR mobile numbers (01[016789] prefixes); landlines are out of scope.
+    // krPhoneValid keeps a bare separator-less run from matching a timestamp/id.
     id: "kr-phone",
     type: "phone",
     pattern: "(?:\\+82[-\\s]?)?0?1[016789][-.\\s]?\\d{3,4}[-.\\s]?\\d{4}",
     flags: "g",
-    confidence: 0.9
+    confidence: 0.9,
+    validate: krPhoneValid
   },
   {
     id: "kr-rrn-like",
@@ -116,6 +119,27 @@ export function createDefaultFilterEngine({ customRules = [] } = {}) {
 
 export function detectEntry(entry, rules, context = {}) {
   const detections = [];
+  // On the RESPONSE direction, a bare JSON NUMBER leaf is inference-server
+  // metadata (a nanosecond `*_duration`, a token count, a numeric id/timestamp) —
+  // never a model-leaked card/phone/RRN. Scanning it only yields false positives:
+  // a long Luhn-passing duration matches `card`, a 13-digit one matches `kr_rrn`.
+  // The REQUEST direction still scans numbers (a client CAN send a card as a
+  // number); model-leaked PII lands in generated TEXT (string leaves), which are
+  // still inspected. (Accepted residual: a hostile model could exfiltrate a value
+  // as a bare response number — response inspection is a secondary defense.) A
+  // strict deployment can opt back in with `responseProtection.scanNumbers: true`
+  // (threaded as context.scanNumbers), accepting the metadata false positives.
+  if (context?.direction === "response" && entry.kind === "number" && !context?.scanNumbers) {
+    return detections;
+  }
+  // On the RESPONSE direction only, skip Haechi's own transform markers so they
+  // aren't re-detected: a tokenized round-trip echoes `[TOKEN:tok_…]` back, which
+  // reads like a `token:<secret>` assignment — without this, Haechi blocks its
+  // own token. This is response-only on purpose: a REQUEST that contains a
+  // marker-shaped string is NOT Haechi output (Haechi hasn't transformed it yet),
+  // so it is scanned normally — otherwise an attacker could wrap a real secret in
+  // a fake `[TOKEN:…]` to evade request-side detection.
+  const markerSpans = context?.direction === "response" ? haechiMarkerSpans(entry.value) : [];
 
   for (const rule of rules) {
     // Direction-scoped rules (e.g. injection heuristics) only run on the
@@ -129,14 +153,19 @@ export function detectEntry(entry, rules, context = {}) {
       if (rule.validate && !rule.validate(value)) {
         continue;
       }
+      const start = match.index;
+      const end = match.index + value.length;
+      if (overlapsAny(start, end, markerSpans)) {
+        continue;
+      }
       detections.push({
         type: rule.type,
         ruleId: rule.id,
         path: entry.path,
         pathText: entry.pathText,
         kind: entry.kind ?? "value",
-        start: match.index,
-        end: match.index + value.length,
+        start,
+        end,
         confidence: rule.confidence,
         value
       });
@@ -146,6 +175,32 @@ export function detectEntry(entry, rules, context = {}) {
   return removeOverlaps(detections);
 }
 
+// Spans of Haechi's own transform markers in a string, so detection can skip
+// them: `[TOKEN:…]`, `[HAECHI_ENC:…]`, `[REDACTED:…]`.
+function haechiMarkerSpans(text) {
+  const spans = [];
+  for (const m of text.matchAll(/\[(?:TOKEN|HAECHI_ENC|REDACTED):[^\]]*\]/g)) {
+    spans.push([m.index, m.index + m[0].length]);
+  }
+  return spans;
+}
+
+function overlapsAny(start, end, spans) {
+  return spans.some(([s, e]) => start < e && end > s);
+}
+
+// A bare digit run with no separators and no +82 country code is only treated as
+// a KR phone number when it starts with the trunk prefix 0 (e.g. 01012345678);
+// otherwise an ambiguous 10-digit value (a unix timestamp, an id, a counter)
+// merely looks phone-shaped. Separated/prefixed forms (010-1234-5678,
+// +82 10 1234 5678) always pass.
+function krPhoneValid(match) {
+  if (/[-.\s+]/.test(match)) {
+    return true;
+  }
+  return match.startsWith("0");
+}
+
 function normalizeCustomRule(rule) {
   if (!rule.id || !rule.type || !rule.pattern) {
     throw new Error("Custom filter rule requires id, type, and pattern");