haechi 1.6.0 → 1.8.0

package/packages/crypto/index.mjs

@@ -3,6 +3,13 @@ import { dirname } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 
 const ALG = "AES-256-GCM";
+export const CRYPTO_AAD_ENCODING_V2 = "nfkc-json-v2";
+// v3 binds the envelope's freshness fields (createdAt/expiresAt) into the AAD
+// itself, so tampering them (e.g. deleting/extending expiresAt on a stored
+// envelope) fails the GCM auth tag instead of silently bypassing expiry. The
+// v2 AAD encoding is already published and MUST NOT change (legacy decrypt
+// stays on canonicalizeCryptoAad(aad) exactly as before) — v3 is additive.
+export const CRYPTO_AAD_ENCODING_V3 = "nfkc-json-v3";
 
 // Random 96-bit GCM IVs are only safe up to a bounded number of invocations per
 // key: by the birthday bound the IV-collision probability stays negligible only
@@ -151,26 +158,42 @@ export function createLocalCryptoProvider({ keyFile }) {
       readsPlaintext: true,
       networkEgress: false
     },
-    async encrypt({ plaintext, aad }) {
+    async encrypt({ plaintext, aad, expiresAt = null }) {
       const { active: { kid, key } } = await loadKeys();
       // Fail closed at the per-key random-IV invocation limit BEFORE choosing an
       // IV, so we never generate a nonce past the safe budget (NIST SP 800-38D).
       await consumeNonceBudget(kid);
       const iv = randomBytes(12);
       const cipher = createCipheriv("aes-256-gcm", key, iv);
-      const aadBytes = Buffer.from(canonicalize(aad), "utf8");
+      // Compute freshness FIRST so the AAD binds them (v3): a tampered
+      // createdAt/expiresAt on a stored envelope now fails the GCM auth tag
+      // instead of silently bypassing expiry.
+      const createdAt = new Date().toISOString();
+      const normalizedExpiresAt = expiresAt !== null && expiresAt !== undefined
+        ? normalizeEnvelopeExpiry(expiresAt)
+        : null;
+      const aadBytes = Buffer.from(
+        canonicalizeCryptoAad({ aad, createdAt, expiresAt: normalizedExpiresAt }),
+        "utf8"
+      );
       cipher.setAAD(aadBytes);
       const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
       const tag = cipher.getAuthTag();
-      return {
-        v: 1,
+      const envelope = {
+        v: 3,
         alg: ALG,
         kid,
         iv: iv.toString("base64url"),
         ct: ciphertext.toString("base64url"),
         tag: tag.toString("base64url"),
-        aadHash: sha256(aadBytes)
+        aadHash: sha256(aadBytes),
+        aadEncoding: CRYPTO_AAD_ENCODING_V3,
+        createdAt
       };
+      if (normalizedExpiresAt !== null) {
+        envelope.expiresAt = normalizedExpiresAt;
+      }
+      return envelope;
     },
     // Keyed hash over a domain-separated derived key. The raw stored key is an
     // AES-256-GCM key and must never be used for HMAC directly; every use case
@@ -189,12 +212,13 @@ export function createLocalCryptoProvider({ keyFile }) {
       if (envelope.alg && envelope.alg !== ALG) {
         throw new Error(`Unsupported local crypto algorithm: ${envelope.alg}`);
       }
+      assertEnvelopeFresh(envelope);
       const selected = envelope.kid ? byKid.get(envelope.kid) : active;
       if (!selected) {
         throw new Error(`Unknown key id in envelope: ${envelope.kid}`);
       }
       const { key } = selected;
-      const aadBytes = Buffer.from(canonicalize(aad), "utf8");
+      const aadBytes = Buffer.from(canonicalizeAadForEnvelope(envelope, aad), "utf8");
       if (envelope.aadHash && envelope.aadHash !== sha256(aadBytes)) {
         throw new Error("AAD hash mismatch");
       }
@@ -397,6 +421,77 @@ export function canonicalize(value) {
   return JSON.stringify(value);
 }
 
+export function canonicalizeCryptoAad(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalizeCryptoAad(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const seen = new Set();
+    const entries = [];
+    for (const key of Object.keys(value)) {
+      const normalizedKey = key.normalize("NFKC");
+      if (seen.has(normalizedKey)) {
+        throw new Error(`crypto AAD NFKC key collision: ${JSON.stringify(normalizedKey)}`);
+      }
+      seen.add(normalizedKey);
+      entries.push(`${JSON.stringify(normalizedKey)}:${canonicalizeCryptoAad(value[key])}`);
+    }
+    return `{${entries.sort().join(",")}}`;
+  }
+  if (typeof value === "string") {
+    return JSON.stringify(value.normalize("NFKC"));
+  }
+  return JSON.stringify(value);
+}
+
+function canonicalizeAadForEnvelope(envelope, aad) {
+  if (
+    envelope.aadEncoding &&
+    envelope.aadEncoding !== CRYPTO_AAD_ENCODING_V2 &&
+    envelope.aadEncoding !== CRYPTO_AAD_ENCODING_V3
+  ) {
+    throw new Error(`Unsupported crypto AAD encoding: ${envelope.aadEncoding}`);
+  }
+  if (envelope.aadEncoding === CRYPTO_AAD_ENCODING_V3 || envelope.v === 3) {
+    // v3: freshness fields are bound into the AAD, so a tampered
+    // createdAt/expiresAt no longer canonicalizes to the same bytes the
+    // encryptor authenticated — the GCM tag check below fails closed.
+    return canonicalizeCryptoAad({
+      aad,
+      createdAt: envelope.createdAt ?? null,
+      expiresAt: envelope.expiresAt ?? null
+    });
+  }
+  if (envelope.aadEncoding === CRYPTO_AAD_ENCODING_V2 || envelope.v === 2) {
+    // v2 (legacy, UNCHANGED): freshness fields are NOT bound into the AAD, so
+    // they remain advisory/unauthenticated for v2 envelopes by design.
+    return canonicalizeCryptoAad(aad);
+  }
+  return canonicalize(aad);
+}
+
+function normalizeEnvelopeExpiry(expiresAt) {
+  const iso = expiresAt instanceof Date ? expiresAt.toISOString() : String(expiresAt);
+  const ts = Date.parse(iso);
+  if (!Number.isFinite(ts)) {
+    throw new Error("crypto envelope expiresAt must be a valid timestamp");
+  }
+  return new Date(ts).toISOString();
+}
+
+function assertEnvelopeFresh(envelope) {
+  if (!envelope.expiresAt) {
+    return;
+  }
+  const expiresAt = Date.parse(envelope.expiresAt);
+  if (!Number.isFinite(expiresAt)) {
+    throw new Error("crypto envelope expiresAt is invalid");
+  }
+  if (Date.now() >= expiresAt) {
+    throw new Error("Crypto envelope expired");
+  }
+}
+
 function sha256(value) {
   return createHash("sha256").update(value).digest("base64url");
 }

package/packages/metrics/index.mjs

@@ -27,7 +27,8 @@ const COUNTERS = {
   haechi_upstream_error_total: "Upstream requests that failed (non-timeout).",
   haechi_response_unprotected_total: "Responses forwarded without protection (size/encoding/parse).",
   haechi_internal_error_total: "Unexpected internal proxy errors.",
-  haechi_overloaded_total: "Requests rejected by the max-in-flight backpressure ceiling (503)."
+  haechi_overloaded_total: "Requests rejected by the max-in-flight backpressure ceiling (503).",
+  haechi_usage_record_failed_total: "Usage recorder failures after a proxied request completed."
 };
 
 const HISTOGRAMS = {

package/packages/proxy/index.mjs

@@ -6,6 +6,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { once } from "node:events";
 import { inspectResponseStream } from "../stream-filter/index.mjs";
+import { recordUsageEvent } from "../usage/index.mjs";
 
 export const DEFAULT_PROXY_PORT = 11016;
 
@@ -142,6 +143,16 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
     const correlationId = randomUUID();
     const startedAt = process.hrtime.bigint();
     let routeId = "unknown";
+    let routeContext = null;
+    let usageIdentity = null;
+    let usageProfile = null;
+    let usageRequestBytes = null;
+    let usageResponseBytes = null;
+    let usageModel = null;
+    let usageDecision = "unknown";
+    let usageBlocked = false;
+    let usageUpstreamReached = false;
+    let usageUpstreamStatusCode = null;
 
     // Observability routes are exempt from the in-flight ceiling and are NOT
     // counted toward it: liveness/readiness/metrics must answer under saturation.
@@ -209,7 +220,7 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
       }
 
       assertRelativeProxyTarget(request.url);
-      const routeContext = protocolAdapter.classifyRequest(request);
+      routeContext = protocolAdapter.classifyRequest(request);
       routeId = routeContext?.routeId ?? "unknown";
       const mode = config.policy.mode ?? config.mode;
 
@@ -217,6 +228,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
       // the body, so a denied/throttled request cannot stream a large body.
       const gate = await authorizeRequest({ runtime, request, routeContext, rateLimiter, metrics, correlationId });
       if (gate.denied) {
+        usageDecision = gate.denied.error?.replace(/^haechi_/, "") ?? "denied";
+        usageBlocked = true;
         writeJson(response, gate.denied.status, {
           error: gate.denied.error,
           message: gate.denied.message
@@ -224,13 +237,17 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         return;
       }
       const { identity, profile, policyEngine, modelAllowlist } = gate;
+      usageIdentity = identity;
+      usageProfile = profile;
       const authContext = { identity, profile, policyEngine, correlationId };
 
       const body = await readBody(request, {
         maxBytes: config.limits.maxRequestBytes,
         response
       });
+      usageRequestBytes = Buffer.byteLength(body, "utf8");
       const json = parseJsonBody(body);
+      usageModel = typeof json?.model === "string" ? json.model : null;
 
       // Model allowlist runs after body read (the model field is in the body).
       if (modelAllowlist && typeof json?.model === "string" && !modelAllowlist.includes(json.model)) {
@@ -243,6 +260,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         });
         countDecision(metrics, { routeContext, mode, decision: "model_not_allowed" });
         metrics.increment("haechi_blocks_total");
+        usageDecision = "model_not_allowed";
+        usageBlocked = true;
         writeJson(response, 403, {
           error: "haechi_model_not_allowed",
           message: `Model not allowed: ${json.model}`
@@ -252,7 +271,11 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
 
       if (isStreamingRequest(json, routeContext)) {
         if (config.streaming.requestMode === "inspect") {
-          await handleInspectedStream({ runtime, request, response, routeContext, json, authContext, metrics, forwardPolicy });
+          const streamOutcome = await handleInspectedStream({ runtime, request, response, routeContext, json, authContext, metrics, forwardPolicy });
+          usageDecision = streamOutcome.decision;
+          usageBlocked = streamOutcome.blocked;
+          usageUpstreamReached = streamOutcome.upstreamReached;
+          usageUpstreamStatusCode = streamOutcome.upstreamStatusCode;
           return;
         }
 
@@ -282,6 +305,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
             forwardPolicy,
             abortController: streamAbort
           });
+          usageUpstreamReached = true;
+          usageUpstreamStatusCode = upstreamResponse.status;
           // P1-CR-003 — sanitize response headers (strip the upstream's
           // content-encoding/content-length/transfer/hop-by-hop) on this path
           // too: Node fetch() auto-decompressed the body, so the original
@@ -299,10 +324,13 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
             metrics,
             correlationId
           });
+          usageDecision = "streaming_request_pass_through";
           return;
         }
 
         countDecision(metrics, { routeContext, mode, decision: "streaming_blocked" });
+        usageDecision = "streaming_blocked";
+        usageBlocked = true;
         writeJson(response, 501, {
           error: "haechi_streaming_unsupported",
           message: "Streaming requests are blocked unless streaming.requestMode is set to pass-through or inspect"
@@ -323,6 +351,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
       if (result.blocked) {
         countDecision(metrics, { routeContext, mode, decision: "blocked" });
         metrics.increment("haechi_blocks_total");
+        usageDecision = "blocked";
+        usageBlocked = true;
         writeJson(response, 403, {
           error: "haechi_policy_block",
           summary: result.summary,
@@ -339,6 +369,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         metrics,
         forwardPolicy
       });
+      usageUpstreamReached = true;
+      usageUpstreamStatusCode = upstreamResponse.status;
 
       const forwarded = await maybeProtectResponse({
         upstreamResponse,
@@ -354,10 +386,15 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         mode,
         decision: forwarded.decision ?? "forwarded"
       });
+      usageDecision = forwarded.decision ?? "forwarded";
+      usageBlocked = forwarded.status >= 400 || forwarded.decision?.includes("blocked") || forwarded.decision === "response_blocked";
+      usageResponseBytes = Buffer.isBuffer(forwarded.body) ? forwarded.body.byteLength : null;
       response.writeHead(forwarded.status, forwarded.headers);
       response.end(forwarded.body);
     } catch (error) {
       const expected = typeof error?.statusCode === "number";
+      usageDecision = error?.errorCode ?? "proxy_error";
+      usageBlocked = true;
       if (!expected) {
         // Carry the error NAME/class + correlationId only — NEVER the payload,
         // headers, token, or any PII.
@@ -380,6 +417,25 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
       }, extraHeaders);
     } finally {
       const elapsedSeconds = Number(process.hrtime.bigint() - startedAt) / 1e9;
+      await maybeRecordUsage({
+        runtime,
+        request,
+        routeContext,
+        identity: usageIdentity,
+        profile: usageProfile,
+        correlationId,
+        requestBytes: usageRequestBytes,
+        responseBytes: usageResponseBytes,
+        model: usageModel,
+        decision: usageDecision,
+        blocked: usageBlocked,
+        upstreamReached: usageUpstreamReached,
+        upstreamStatusCode: usageUpstreamStatusCode,
+        statusCode: response.statusCode,
+        durationMs: Math.round(elapsedSeconds * 1000),
+        exemptRoute,
+        metrics
+      });
       // route label is a bounded route id (or "unknown") — never an identity/value.
       metrics.observe("haechi_request_duration_seconds", elapsedSeconds, { route: routeId });
       if (counted) {
@@ -545,6 +601,56 @@ function countDecision(metrics, { routeContext, mode, decision }) {
   });
 }
 
+async function maybeRecordUsage({
+  runtime,
+  request,
+  routeContext,
+  identity,
+  profile,
+  correlationId,
+  requestBytes,
+  responseBytes,
+  model,
+  decision,
+  blocked,
+  upstreamReached,
+  upstreamStatusCode,
+  statusCode,
+  durationMs,
+  exemptRoute,
+  metrics
+}) {
+  if (exemptRoute || !runtime.config.usage?.enabled) {
+    return;
+  }
+  try {
+    await recordUsageEvent({
+      usageRecorder: runtime.usageRecorder,
+      auditSink: runtime.auditSink,
+      audit: runtime.config.usage.audit,
+      event: {
+        correlationId,
+        routeContext,
+        identity,
+        profile,
+        method: request.method,
+        path: request.url,
+        requestBytes,
+        responseBytes,
+        statusCode,
+        outcomeDecision: decision,
+        blocked,
+        upstreamReached,
+        upstreamStatusCode,
+        model,
+        durationMs
+      }
+    });
+  } catch {
+    metrics?.increment("haechi_usage_record_failed_total");
+  }
+}
+
 // Backward-compat fallback for a hand-built runtime object without metrics: a
 // no-op collector with the same increment/observe/render contract.
 function noopMetrics() {
@@ -685,7 +791,7 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
       error: "haechi_streaming_uninspectable_route",
       message: `streaming.requestMode is "inspect" but route ${routeContext.routeId} has no known streaming format`
     });
-    return;
+    return { decision: "streaming_uninspectable_route", blocked: true, upstreamReached: false, upstreamStatusCode: null };
   }
 
   // The request body is ordinary JSON even when the response streams, so it is
@@ -708,7 +814,7 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
       summary: requestResult.summary,
       auditId: requestResult.auditEvent.id
     });
-    return;
+    return { decision: "blocked", blocked: true, upstreamReached: false, upstreamStatusCode: null };
   }
 
   const upstreamResponse = await forward({
@@ -749,6 +855,12 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
     metrics?.increment("haechi_blocks_total");
   }
   response.end();
+  return {
+    decision: blocked ? "stream_blocked" : "stream_inspected",
+    blocked,
+    upstreamReached: true,
+    upstreamStatusCode: upstreamResponse.status
+  };
 }
 
 // P1-CR-003 — the SINGLE centralized response-header sanitizer used on EVERY

package/packages/token-vault/index.mjs

@@ -229,6 +229,7 @@ export function createTokenVault({
         }
 
         const createdAt = new Date();
+        const expiresAt = addDays(createdAt, retentionDays).toISOString();
         const aad = {
           purpose: "token-vault",
           token,
@@ -238,9 +239,9 @@ export function createTokenVault({
         view.set(token, {
           type,
           createdAt: createdAt.toISOString(),
-          expiresAt: addDays(createdAt, retentionDays).toISOString(),
+          expiresAt,
           metadata: sanitizeMetadata(metadata),
-          envelope: await cryptoProvider.encrypt({ plaintext, aad }),
+          envelope: await cryptoProvider.encrypt({ plaintext, aad, expiresAt }),
           aad
         });
         return { token, type };

package/packages/usage/index.mjs

@@ -0,0 +1,177 @@
+import { createHash, randomUUID } from "node:crypto";
+
+export const USAGE_EVENT_SCHEMA_VERSION = "1";
+
+const SAFE_TOKEN = /^[A-Za-z0-9_.:/-]{1,64}$/;
+
+export function createNoopUsageRecorder() {
+  return Object.freeze({
+    id: "haechi.usage.noop",
+    async record() {
+      return { recorded: false };
+    }
+  });
+}
+
+export function createNoopQuotaProvider() {
+  return Object.freeze({
+    id: "haechi.quota.noop",
+    async check() {
+      return { allowed: true, reason: "not_configured" };
+    }
+  });
+}
+
+export function coerceUsageRecorder(provider) {
+  if (typeof provider === "function") {
+    return { id: "haechi.usage.function", record: provider };
+  }
+  if (provider && typeof provider.record === "function") {
+    return provider;
+  }
+  throw new Error("usageRecorder must be a function or an object with record(event)");
+}
+
+export function coerceQuotaProvider(provider) {
+  if (typeof provider === "function") {
+    return { id: "haechi.quota.function", check: provider };
+  }
+  if (provider && typeof provider.check === "function") {
+    return provider;
+  }
+  throw new Error("quotaProvider must be a function or an object with check(context)");
+}
+
+export function normalizeQuotaDecision(result) {
+  if (result === true) {
+    return { allowed: true, reason: "allowed" };
+  }
+  if (result === false) {
+    return { allowed: false, reason: "denied" };
+  }
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    throw new Error("quotaProvider.check() must return boolean or { allowed, reason? }");
+  }
+  if (typeof result.allowed !== "boolean") {
+    throw new Error("quotaProvider.check() result.allowed must be boolean");
+  }
+  return {
+    allowed: result.allowed,
+    reason: safeToken(result.reason, result.allowed ? "allowed" : "denied"),
+    retryAfterSeconds: safePositiveInteger(result.retryAfterSeconds)
+  };
+}
+
+export function projectUsageIdentity(identity) {
+  if (!identity) {
+    return null;
+  }
+  return {
+    id: safeToken(identity.id, "unknown"),
+    type: safeToken(identity.type, "unknown"),
+    subjectHash: safeHash(identity.subjectHash),
+    issuerHash: safeHash(identity.issuerHash),
+    provider: safeToken(identity.provider, "unknown")
+  };
+}
+
+export function buildUsageEvent({
+  correlationId = null,
+  timestamp = new Date().toISOString(),
+  routeContext = null,
+  identity = null,
+  profile = null,
+  method = null,
+  path = null,
+  requestBytes = null,
+  responseBytes = null,
+  statusCode = null,
+  outcomeDecision = "unknown",
+  blocked = false,
+  upstreamReached = false,
+  upstreamStatusCode = null,
+  model = null,
+  durationMs = null
+} = {}) {
+  const routeId = safeToken(routeContext?.routeId, "unknown");
+  const outcome = safeToken(outcomeDecision, "unknown");
+  const modelText = typeof model === "string" && model.length > 0 ? model : null;
+  return {
+    schemaVersion: USAGE_EVENT_SCHEMA_VERSION,
+    id: randomUUID(),
+    eventType: "usage_recorded",
+    correlationId: typeof correlationId === "string" ? correlationId : null,
+    timestamp,
+    protocol: safeToken(routeContext?.protocol, "proxy"),
+    operation: `usage:${safeToken(routeContext?.protocol, "proxy")}:${routeId}`,
+    identity: projectUsageIdentity(identity),
+    profile: profile === null || profile === undefined ? null : safeToken(profile, "unknown"),
+    decision: "usage_recorded",
+    reason: "request_completed",
+    routeId,
+    method: safeToken(method, "UNKNOWN"),
+    pathHash: typeof path === "string" ? shortHash(path) : null,
+    outcome: {
+      decision: outcome,
+      blocked: Boolean(blocked),
+      statusCode: safeStatusCode(statusCode)
+    },
+    upstream: {
+      reached: Boolean(upstreamReached),
+      statusCode: safeStatusCode(upstreamStatusCode)
+    },
+    request: {
+      bytes: safeNonNegativeInteger(requestBytes),
+      modelHash: modelText ? shortHash(modelText) : null,
+      modelPresent: Boolean(modelText)
+    },
+    response: {
+      bytes: safeNonNegativeInteger(responseBytes)
+    },
+    durationMs: safeNonNegativeInteger(durationMs),
+    summary: {
+      detectionCount: 0,
+      byType: {},
+      byAction: {
+        usage_recorded: 1
+      }
+    }
+  };
+}
+
+export async function recordUsageEvent({ usageRecorder, auditSink = null, audit = true, event }) {
+  const normalized = buildUsageEvent(event);
+  await usageRecorder.record(normalized);
+  if (audit && typeof auditSink?.record === "function") {
+    await auditSink.record(normalized);
+  }
+  return normalized;
+}
+
+function safeToken(value, fallback) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const trimmed = value.trim();
+  return SAFE_TOKEN.test(trimmed) ? trimmed : fallback;
+}
+
+function safeHash(value) {
+  return typeof value === "string" && /^[a-f0-9]{16,128}$/i.test(value) ? value : "unknown";
+}
+
+function safeStatusCode(value) {
+  return Number.isInteger(value) && value >= 100 && value <= 599 ? value : null;
+}
+
+function safePositiveInteger(value) {
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function safeNonNegativeInteger(value) {
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function shortHash(value) {
+  return createHash("sha256").update(String(value)).digest("hex").slice(0, 12);
+}