haechi 0.5.0 → 0.7.0

package/packages/cli/runtime.mjs

@@ -2,13 +2,14 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { createHaechi } from "../core/index.mjs";
 import { createDefaultFilterEngine } from "../filter/index.mjs";
-import { buildPolicy, createPolicyEngine } from "../policy/index.mjs";
+import { createPolicyProfiles } from "../policy/index.mjs";
 import { createLocalCryptoProvider, initLocalKeyFile } from "../crypto/index.mjs";
 import { createJsonlAuditSink } from "../audit/index.mjs";
 import { createLocalTokenVault } from "../token-vault/index.mjs";
 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 { DEFAULT_PROXY_PORT } from "../proxy/index.mjs";
 
 export const DEFAULT_CONFIG_PATH = "haechi.config.json";
@@ -59,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",
@@ -73,6 +79,11 @@ export function defaultConfig() {
     privacy: {
       profile: null
     },
+    auth: {
+      provider: "none",
+      store: ".haechi/auth.json",
+      allowedLabelKeys: ["team", "env", "tier", "role"]
+    },
     mcp: {
       allowedMethods: ["initialize", "tools/call", "resources/read", "prompts/get"],
       protectParams: true,
@@ -111,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,
@@ -135,19 +157,25 @@ export function createRuntime(config, providers = {}) {
       ...normalized.policy,
       mode: normalized.policy.mode ?? normalized.mode
     };
-  const policy = buildPolicy(normalized.privacy.profile
-    ? applyPrivacyProfile(policySource, normalized.privacy.profile)
-    : policySource);
+  const policyProfiles = createPolicyProfiles(policySource, {
+    transform: (source) => normalized.privacy.profile
+      ? applyPrivacyProfile(source, normalized.privacy.profile)
+      : source
+  });
 
   const filterEngine = providers.filterEngine ?? createDefaultFilterEngine(normalized.filters);
   assertProvider("filterEngine", filterEngine, ["detect"]);
-  const policyEngine = providers.policyEngine ?? createPolicyEngine(policy);
+  const policyEngine = providers.policyEngine ?? policyProfiles.base.policyEngine;
   assertProvider("policyEngine", policyEngine, ["decide"]);
 
+  const authProvider = resolveAuthProvider(normalized, providers, cryptoProvider);
+
   return {
     config: normalized,
     tokenVault,
     auditSink,
+    authProvider,
+    policyProfiles,
     protocolAdapter: createProtocolAdapter(normalized.target),
     haechi: createHaechi({
       mode: normalized.mode,
@@ -202,7 +230,11 @@ export function normalizeConfig(config) {
     },
     audit: {
       ...defaultConfig().audit,
-      ...(config.audit ?? {})
+      ...(config.audit ?? {}),
+      anchor: {
+        ...defaultConfig().audit.anchor,
+        ...(config.audit?.anchor ?? {})
+      }
     },
     tokenVault: {
       ...defaultConfig().tokenVault,
@@ -212,6 +244,11 @@ export function normalizeConfig(config) {
       ...defaultConfig().privacy,
       ...(config.privacy ?? {})
     },
+    auth: {
+      ...defaultConfig().auth,
+      ...(config.auth ?? {}),
+      allowedLabelKeys: config.auth?.allowedLabelKeys ?? defaultConfig().auth.allowedLabelKeys
+    },
     mcp: {
       ...defaultConfig().mcp,
       ...(config.mcp ?? {}),
@@ -231,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");
   }
@@ -288,6 +335,17 @@ export function normalizeConfig(config) {
   if (typeof merged.limits.upstreamTimeoutMs !== "number" || merged.limits.upstreamTimeoutMs < 1) {
     throw new Error("limits.upstreamTimeoutMs must be a positive number");
   }
+  validatePolicyExtras(merged.policy);
+  if (!["none", "bearer", "external"].includes(merged.auth.provider)) {
+    throw new Error(`Invalid auth.provider: ${merged.auth.provider}`);
+  }
+  if (typeof merged.auth.store !== "string" || !merged.auth.store.trim()) {
+    throw new Error("auth.store must be a non-empty string");
+  }
+  if (!Array.isArray(merged.auth.allowedLabelKeys)
+    || !merged.auth.allowedLabelKeys.every((key) => typeof key === "string" && key.trim())) {
+    throw new Error("auth.allowedLabelKeys must be an array of non-empty strings");
+  }
   createProtocolAdapter(merged.target);
   return merged;
 }
@@ -296,6 +354,76 @@ export function isValidPort(port) {
   return Number.isInteger(port) && port >= 0 && port <= 65535;
 }
 
+function validatePolicyExtras(policy) {
+  if (policy.modelAllowlist !== undefined) {
+    assertModelAllowlist(policy.modelAllowlist, "policy.modelAllowlist");
+  }
+  if (policy.rate !== undefined) {
+    assertRate(policy.rate, "policy.rate");
+  }
+  if (policy.profiles !== undefined) {
+    if (typeof policy.profiles !== "object" || policy.profiles === null || Array.isArray(policy.profiles)) {
+      throw new Error("policy.profiles must be an object of named profiles");
+    }
+    for (const [name, profile] of Object.entries(policy.profiles)) {
+      if (typeof profile !== "object" || profile === null || Array.isArray(profile)) {
+        throw new Error(`policy.profiles.${name} must be an object`);
+      }
+      if (profile.modelAllowlist !== undefined) {
+        assertModelAllowlist(profile.modelAllowlist, `policy.profiles.${name}.modelAllowlist`);
+      }
+      if (profile.rate !== undefined) {
+        assertRate(profile.rate, `policy.profiles.${name}.rate`);
+      }
+    }
+  }
+  if (policy.profileBinding !== undefined) {
+    const binding = policy.profileBinding;
+    if (typeof binding !== "object" || binding === null || Array.isArray(binding)) {
+      throw new Error("policy.profileBinding must be an object");
+    }
+    if (typeof binding.default !== "string" || !binding.default.trim()) {
+      throw new Error("policy.profileBinding.default must be a profile name");
+    }
+    for (const field of ["byScope", "byLabel"]) {
+      if (binding[field] !== undefined
+        && (typeof binding[field] !== "object" || binding[field] === null || Array.isArray(binding[field]))) {
+        throw new Error(`policy.profileBinding.${field} must be an object`);
+      }
+    }
+  }
+}
+
+function assertModelAllowlist(value, label) {
+  if (!Array.isArray(value) || !value.every((model) => typeof model === "string" && model.trim())) {
+    throw new Error(`${label} must be an array of non-empty strings`);
+  }
+}
+
+function assertRate(value, label) {
+  if (typeof value !== "object" || value === null
+    || typeof value.requestsPerMinute !== "number" || value.requestsPerMinute < 1) {
+    throw new Error(`${label}.requestsPerMinute must be a positive number`);
+  }
+}
+
+function resolveAuthProvider(config, providers, cryptoProvider) {
+  if (config.auth.provider === "external") {
+    if (typeof providers.authProvider?.authenticate !== "function") {
+      throw new Error("auth.provider external requires createRuntime(config, { authProvider })");
+    }
+    return providers.authProvider;
+  }
+  if (providers.authProvider) {
+    // An injected provider overrides the built-in selection.
+    return providers.authProvider;
+  }
+  if (config.auth.provider === "bearer") {
+    return createBearerAuthProvider({ path: config.auth.store, cryptoProvider });
+  }
+  return null;
+}
+
 function createConfiguredCryptoProvider(config) {
   if (config.keys.provider === "external") {
     throw new Error("keys.provider external requires createRuntime(config, { cryptoProvider })");

package/packages/core/index.mjs

@@ -7,14 +7,19 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
     throw new Error("Haechi requires filterEngine, policyEngine, cryptoProvider, and auditSink");
   }
 
-  async function protectJson(payload, context = {}) {
+  async function protectJson(payload, rawContext = {}) {
+    // A per-request policy engine (a named profile selected from identity)
+    // overrides the default. It is a control object, NOT data: strip it before
+    // anything downstream (tokenize AAD, audit) sees the context.
+    const { policyEngine: contextEngine, ...context } = rawContext;
     const effectiveMode = context.mode ?? mode;
+    const engine = contextEngine ?? policyEngine;
     const entries = collectStringEntries(payload);
     const detections = await filterEngine.detect({ entries, context });
     const decisions = [];
 
     for (const detection of detections) {
-      decisions.push(await policyEngine.decide({ detection, context, mode: effectiveMode }));
+      decisions.push(await engine.decide({ detection, context, mode: effectiveMode }));
     }
 
     const enforced = !NO_ENFORCE_MODES.has(effectiveMode);
@@ -55,8 +60,12 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
   // 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 = {}) {
+  function createStreamProtector(rawContext = {}) {
+    // Strip the control-object policy engine from the data context (see
+    // protectJson) so it cannot leak into tokenize AAD or audit.
+    const { policyEngine: contextEngine, ...context } = rawContext;
     const effectiveMode = context.mode ?? mode;
+    const engine = contextEngine ?? policyEngine;
     const enforced = !NO_ENFORCE_MODES.has(effectiveMode);
     const maxMatchBytes = context.maxMatchBytes ?? 256;
     const byType = {};
@@ -76,7 +85,7 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
     async function decideAll(detections) {
       const decisions = [];
       for (const detection of detections) {
-        decisions.push(await policyEngine.decide({ detection, context, mode: effectiveMode }));
+        decisions.push(await engine.decide({ detection, context, mode: effectiveMode }));
       }
       return decisions;
     }
@@ -378,9 +387,11 @@ 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,
+    // 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,
+    profile: context.profile ?? null,
     mode,
     enforced,
     blocked,

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/packages/policy/index.mjs

@@ -130,6 +130,88 @@ export function createPolicyEngine(policy) {
   };
 }
 
+// Compiles the base policy plus every named profile into ready policy engines
+// and a resolver that maps an identity to one. A profile inherits the base
+// policy's presets/actions and overrides on top (so a profile need only state
+// what differs). `transform` (e.g. applyPrivacyProfile) is applied to each
+// compiled policy source before buildPolicy.
+export function createPolicyProfiles(policyConfig = {}, { transform } = {}) {
+  const { profiles = {}, profileBinding = null, ...baseSource } = policyConfig;
+  const apply = (source) => (transform ? transform(source) : source);
+
+  const baseEngine = createPolicyEngine(buildPolicy(apply(baseSource)));
+  const profileNames = Object.keys(profiles);
+  const engines = new Map();
+
+  for (const name of profileNames) {
+    const override = profiles[name] ?? {};
+    const merged = {
+      ...baseSource,
+      ...override,
+      // Profile presets replace the base presets when given; actions merge over
+      // the base via buildPolicy's strengthen-only rules.
+      actions: { ...(baseSource.actions ?? {}), ...(override.actions ?? {}) },
+      modelAllowlist: override.modelAllowlist ?? baseSource.modelAllowlist,
+      rate: override.rate ?? baseSource.rate
+    };
+    engines.set(name, {
+      policyEngine: createPolicyEngine(buildPolicy(apply(merged))),
+      modelAllowlist: merged.modelAllowlist ?? null,
+      rate: merged.rate ?? null
+    });
+  }
+
+  if (profileBinding) {
+    if (!profileBinding.default || !engines.has(profileBinding.default)) {
+      throw new Error("policy.profileBinding.default must name a declared profile");
+    }
+    for (const map of [profileBinding.byScope ?? {}, profileBinding.byLabel ?? {}]) {
+      for (const [key, target] of Object.entries(map)) {
+        if (!engines.has(target)) {
+          throw new Error(`policy.profileBinding maps ${key} to unknown profile: ${target}`);
+        }
+      }
+    }
+  } else if (profileNames.length > 0) {
+    throw new Error("policy.profiles requires policy.profileBinding with a default");
+  }
+
+  const base = {
+    policyEngine: baseEngine,
+    modelAllowlist: baseSource.modelAllowlist ?? null,
+    rate: baseSource.rate ?? null
+  };
+
+  return {
+    base,
+    hasProfiles: profileNames.length > 0,
+    // Resolve identity → { profile, policyEngine, modelAllowlist, rate }.
+    // Order: scope match → label match → default. Without profiles or identity,
+    // the base policy applies.
+    resolve(identity) {
+      if (!profileBinding) {
+        return { profile: null, ...base };
+      }
+      if (identity) {
+        for (const scope of identity.scopes ?? []) {
+          const name = profileBinding.byScope?.[scope];
+          if (name) {
+            return { profile: name, ...engines.get(name) };
+          }
+        }
+        for (const [key, value] of Object.entries(identity.labels ?? {})) {
+          const name = profileBinding.byLabel?.[`${key}=${value}`];
+          if (name) {
+            return { profile: name, ...engines.get(name) };
+          }
+        }
+      }
+      const fallback = profileBinding.default;
+      return { profile: fallback, ...engines.get(fallback) };
+    }
+  };
+}
+
 export function validatePolicy(policy) {
   if (!policy || typeof policy !== "object") {
     throw new Error("Policy must be an object");