haechi 0.3.2 → 0.5.0

package/packages/stream-filter/index.mjs

@@ -0,0 +1,194 @@
+// SSE / NDJSON streaming response inspection.
+//
+// Frames are parsed incrementally, the primary delta-text channel is run
+// through a bounded sliding buffer (cross-frame matches caught up to
+// streaming.maxMatchBytes), and all other string leaves in a frame get
+// within-frame protection. The whole stream is audited once at the end.
+
+const SSE_DONE = "[DONE]";
+
+export async function inspectResponseStream({ source, sink, streaming, protector, format }) {
+  const wireFormat = format ?? streaming?.format ?? "ndjson";
+  const deltaPath = streaming?.deltaPath ?? null;
+  const decoder = new TextDecoder("utf-8");
+  const frames = createFrameSplitter(wireFormat);
+
+  let blocked = false;
+
+  async function handleFrame(raw) {
+    const frame = { raw, body: raw.trim() };
+    const parsed = parseFrame(frame, wireFormat);
+    if (!parsed.ok) {
+      // Non-JSON frame (e.g. `data: [DONE]`, comments, keep-alives): pass
+      // through verbatim — there is nothing to inspect.
+      sink.write(frame.raw);
+      return;
+    }
+
+    const json = parsed.json;
+    let deltaText = null;
+    if (deltaPath) {
+      const found = getByPath(json, deltaPath);
+      if (typeof found === "string") {
+        deltaText = found;
+        setByPath(json, deltaPath, "");
+      }
+    }
+
+    // Within-frame protection for everything except the delta channel.
+    const extras = await protector.protectFrameExtras(json);
+    if (extras.blocked) {
+      blocked = true;
+      return;
+    }
+    const frameObject = extras.value;
+
+    if (deltaText !== null) {
+      const pushed = await protector.push(deltaText);
+      if (pushed.blocked) {
+        blocked = true;
+        return;
+      }
+      setByPath(frameObject, deltaPath, pushed.text);
+    }
+
+    sink.write(serializeFrame(frameObject, wireFormat, frame));
+  }
+
+  for await (const chunk of source) {
+    for (const frame of frames.push(decoder.decode(chunk, { stream: true }))) {
+      await handleFrame(frame);
+      if (blocked) {
+        break;
+      }
+    }
+    if (blocked) {
+      break;
+    }
+  }
+
+  if (!blocked) {
+    for (const frame of frames.end(decoder.decode())) {
+      await handleFrame(frame);
+      if (blocked) {
+        break;
+      }
+    }
+  }
+
+  if (!blocked) {
+    // Flush the held tail of the delta buffer as a synthesized final frame.
+    const flushed = await protector.flush();
+    if (flushed.blocked) {
+      blocked = true;
+    } else if (flushed.text && deltaPath) {
+      sink.write(serializeFrame(buildPathObject(deltaPath, flushed.text), wireFormat, null));
+    }
+  }
+
+  // The caller closes the sink AFTER recording the stream decision, so the
+  // audit write is durable before the client connection ends.
+  return { blocked, summary: protector.summary() };
+}
+
+function createFrameSplitter(format) {
+  const delimiter = format === "sse" ? "\n\n" : "\n";
+  let buffer = "";
+  return {
+    // Append text and return the raw text of every complete frame now
+    // available; the trailing partial is retained for the next push.
+    push(text) {
+      buffer += text;
+      const out = [];
+      let index;
+      while ((index = buffer.indexOf(delimiter)) !== -1) {
+        const raw = buffer.slice(0, index + delimiter.length);
+        buffer = buffer.slice(index + delimiter.length);
+        if (raw.trim()) {
+          out.push(raw);
+        }
+      }
+      return out;
+    },
+    // Flush any trailing partial frame at end of stream.
+    end(text) {
+      buffer += text;
+      const remainder = buffer;
+      buffer = "";
+      return remainder.trim() ? [remainder] : [];
+    }
+  };
+}
+
+function parseFrame(frame, format) {
+  if (!frame) {
+    return { ok: false };
+  }
+  let payload = frame.body;
+  if (format === "sse") {
+    const dataLines = payload
+      .split("\n")
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trim());
+    if (dataLines.length === 0) {
+      return { ok: false };
+    }
+    payload = dataLines.join("");
+    if (payload === SSE_DONE) {
+      return { ok: false };
+    }
+  }
+  try {
+    return { ok: true, json: JSON.parse(payload) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function serializeFrame(json, format, original) {
+  const body = JSON.stringify(json);
+  if (format === "sse") {
+    return `data: ${body}\n\n`;
+  }
+  // NDJSON: preserve the original trailing newline style when available.
+  return original && original.raw.endsWith("\n") ? `${body}\n` : `${body}\n`;
+}
+
+export function getByPath(value, path) {
+  let current = value;
+  for (const part of path) {
+    if (current == null) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+export function setByPath(value, path, next) {
+  let current = value;
+  for (let index = 0; index < path.length - 1; index += 1) {
+    const part = path[index];
+    if (current[part] == null || typeof current[part] !== "object") {
+      return false;
+    }
+    current = current[part];
+  }
+  if (current == null || typeof current !== "object") {
+    return false;
+  }
+  current[path[path.length - 1]] = next;
+  return true;
+}
+
+export function buildPathObject(path, leaf) {
+  const root = typeof path[0] === "number" ? [] : {};
+  let current = root;
+  for (let index = 0; index < path.length - 1; index += 1) {
+    const nextIsIndex = typeof path[index + 1] === "number";
+    current[path[index]] = nextIsIndex ? [] : {};
+    current = current[path[index]];
+  }
+  current[path[path.length - 1]] = leaf;
+  return root;
+}

package/packages/token-vault/index.mjs

@@ -3,13 +3,33 @@ import { dirname } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 
-export function createLocalTokenVault({ path, cryptoProvider, revealPolicy = "disabled", retentionDays = 30, auditSink = null }) {
+const DETERMINISTIC_DOMAIN = "haechi:token-vault:deterministic:v1";
+
+export function createLocalTokenVault({
+  path,
+  cryptoProvider,
+  revealPolicy = "disabled",
+  retentionDays = 30,
+  auditSink = null,
+  deterministic = false,
+  deterministicTypes = null
+}) {
   if (!path) {
     throw new Error("Local token vault requires path");
   }
   if (!cryptoProvider) {
     throw new Error("Local token vault requires cryptoProvider");
   }
+  if (deterministic && typeof cryptoProvider.hmac !== "function") {
+    throw new Error("Deterministic tokenization requires a cryptoProvider with hmac()");
+  }
+
+  function isDeterministicType(type) {
+    if (!deterministic) {
+      return false;
+    }
+    return !deterministicTypes || deterministicTypes.includes(type);
+  }
 
   let mutationQueue = Promise.resolve();
   async function enqueueMutation(operation) {
@@ -32,6 +52,7 @@ export function createLocalTokenVault({ path, cryptoProvider, revealPolicy = "di
       timestamp: new Date().toISOString(),
       protocol: "token-vault",
       operation,
+      identity: null,
       mode: "n/a",
       enforced: true,
       blocked: decision.endsWith("_denied"),
@@ -62,10 +83,26 @@ export function createLocalTokenVault({ path, cryptoProvider, revealPolicy = "di
       revealPolicy
     },
     async tokenize({ plaintext, type, context = {}, metadata = {} }) {
+      // Deterministic tokens are derived outside the mutation lock (HMAC reads
+      // only the key file); the same (type, value) always maps to one token.
+      const token = isDeterministicType(type)
+        ? `tok_${type}_${(await cryptoProvider.hmac({
+          data: `${type}:${plaintext}`,
+          domain: DETERMINISTIC_DOMAIN
+        })).slice(0, 32)}`
+        : `tok_${type}_${shortHash(`${plaintext}:${randomBytes(16).toString("hex")}`)}`;
+
       return enqueueMutation(async () => {
         const vault = await readVault(path);
         pruneExpiredTokens(vault);
-        const token = `tok_${type}_${shortHash(`${plaintext}:${randomBytes(16).toString("hex")}`)}`;
+
+        const existing = vault.tokens[token];
+        if (existing) {
+          existing.expiresAt = addDays(new Date(), retentionDays).toISOString();
+          await writeVault(path, vault);
+          return { token, type, reused: true };
+        }
+
         const createdAt = new Date();
         const aad = {
           purpose: "token-vault",
@@ -127,6 +164,37 @@ export function createLocalTokenVault({ path, cryptoProvider, revealPolicy = "di
         throw error;
       }
     },
+    // Request-scoped response restoration. Deliberately NOT gated by
+    // revealPolicy: that governs manual/CLI reveal, while detokenize is only
+    // reachable through the proxy's explicit detokenizeResponses opt-in and is
+    // limited to the caller-supplied token set. Audited by count, no plaintext.
+    async detokenize({ tokens }) {
+      const vault = await readVault(path);
+      const values = new Map();
+      let skipped = 0;
+
+      for (const token of tokens) {
+        const record = vault.tokens[token];
+        if (!record || (record.expiresAt && Date.parse(record.expiresAt) < Date.now())) {
+          skipped += 1;
+          continue;
+        }
+        try {
+          values.set(token, await cryptoProvider.decrypt({ envelope: record.envelope, aad: record.aad }));
+        } catch {
+          skipped += 1;
+        }
+      }
+
+      await recordVaultEvent({
+        operation: "token-vault:detokenize",
+        decision: "detokenize",
+        count: values.size,
+        reason: skipped > 0 ? `${skipped} tokens not restored` : null
+      });
+
+      return values;
+    },
     async purge({ token }) {
       return enqueueMutation(async () => {
         const vault = await readVault(path);