haechi 1.2.0 → 1.3.1

package/packages/ssrf/index.mjs

@@ -18,6 +18,61 @@ import { lookup as dnsLookup } from "node:dns/promises";
 const DEFAULT_FETCH_TIMEOUT_MS = 5_000;
 const DEFAULT_MAX_BYTES = 1024 * 1024; // 1 MiB
 
+// Parse an IPv6 literal into its 16 octets (or null when it is not a valid IPv6
+// text form). This is the SOUND way to recognise an IPv4-mapped IPv6 address in
+// EVERY textual form: dotted (::ffff:127.0.0.1), HEX (::ffff:7f00:1), bracketed
+// ([::ffff:7f00:1], stripped by the caller), leading-zero (::ffff:7f00:0001),
+// mixed `::` compression, and case-insensitive ffff. We classify the last 32
+// bits as the embedded IPv4 ONLY when bytes 0..9 are zero and bytes 10..11 are
+// 0xffff (the ::ffff:0:0/96 IPv4-mapped prefix), so a genuinely public mapped
+// address (::ffff:8.8.8.8 == ::ffff:808:808) stays allowed and a non-mapped v6
+// (::ffff:0:7f00:1, NAT64 64:ff9b::…) is NOT mistaken for an embedded IPv4.
+function ipv6ToBytes(str) {
+  let s = str;
+  // A trailing dotted IPv4 quad (::ffff:127.0.0.1) — peel it off into the final
+  // two hextets so the remaining text is pure hex groups.
+  let tailV4 = null;
+  if (s.includes(".")) {
+    const idx = s.lastIndexOf(":");
+    if (idx === -1) return null;
+    const quad = s.slice(idx + 1).split(".");
+    if (quad.length !== 4) return null;
+    const oct = quad.map(Number);
+    if (oct.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+    tailV4 = oct;
+    s = `${s.slice(0, idx + 1)}0:0`; // placeholder hextets; overwritten below
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null; // at most one "::"
+  const toGroups = (g) => (g === "" ? [] : g.split(":").map((h) => (/^[0-9a-fA-F]{1,4}$/.test(h) ? parseInt(h, 16) : NaN)));
+  const head = toGroups(halves[0]);
+  const tail = halves.length === 2 ? toGroups(halves[1]) : null;
+  if (head.some(Number.isNaN) || (tail && tail.some(Number.isNaN))) return null;
+  let groups;
+  if (tail === null) {
+    if (head.length !== 8) return null;
+    groups = head;
+  } else {
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0) return null;
+    groups = [...head, ...Array(missing).fill(0), ...tail];
+  }
+  if (groups.length !== 8) return null;
+  const bytes = [];
+  for (const g of groups) bytes.push((g >> 8) & 0xff, g & 0xff);
+  if (tailV4) { bytes[12] = tailV4[0]; bytes[13] = tailV4[1]; bytes[14] = tailV4[2]; bytes[15] = tailV4[3]; }
+  return bytes;
+}
+
+// Return the embedded IPv4 dotted quad of an IPv4-mapped IPv6 address, or null.
+function mappedIpv4(bare) {
+  const b = ipv6ToBytes(bare);
+  if (!b) return null;
+  for (let i = 0; i < 10; i += 1) if (b[i] !== 0) return null; // bytes 0..9 must be zero
+  if (b[10] !== 0xff || b[11] !== 0xff) return null;           // bytes 10..11 must be 0xffff
+  return `${b[12]}.${b[13]}.${b[14]}.${b[15]}`;
+}
+
 // Block literal addresses in private/loopback/link-local ranges + cloud metadata.
 // Applied to both a literal host in the URL and every DNS-resolved address. This
 // is the canonical copy; the satellite copies must agree (parity-tested).
@@ -39,10 +94,11 @@ export function isBlockedAddress(host) {
   if (v === 6) {
     const h = bare.toLowerCase();
     if (h === "::1" || h === "::") return true;             // loopback / unspecified
-    if (h.startsWith("::ffff:")) {                          // IPv4-mapped
-      const mapped = h.slice("::ffff:".length);
-      if (isIP(mapped) === 4) return isBlockedAddress(mapped);
-    }
+    // IPv4-mapped IPv6 — normalise to the embedded IPv4 (handles dotted AND hex
+    // forms, e.g. ::ffff:127.0.0.1 and ::ffff:7f00:1) and run the v4 check, so a
+    // private/loopback/metadata target can't slip past as hex (P1-CR-002).
+    const mapped = mappedIpv4(bare);
+    if (mapped !== null) return isBlockedAddress(mapped);
     // Range-check the first hextet: fe80::/10 link-local, fc00::/7 ULA, ff00::/8 multicast.
     const firstHextet = parseInt(h.split(":")[0] || "", 16);
     if (Number.isFinite(firstHextet)) {

package/packages/stream-filter/index.mjs

@@ -4,28 +4,108 @@
 // 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.
+//
+// P1-CR-005 — a frame whose data: payload is not JSON is NOT raw-passed. A
+// CONTROL frame (the [DONE] sentinel, comment-only, empty/keepalive) has no
+// inspectable text and passes through; a non-JSON CONTENT frame is inspected as
+// text (single-shot protector.protectText, distinct from the delta buffer) so
+// plain-text PII/secrets cannot bypass protection in inspect mode.
 
 const SSE_DONE = "[DONE]";
 
 export async function inspectResponseStream({ source, sink, streaming, protector, format }) {
   const wireFormat = format ?? streaming?.format ?? "ndjson";
   const deltaPath = streaming?.deltaPath ?? null;
+  // Frame types that TERMINATE a delta sequence (declared per-adapter, e.g.
+  // Anthropic's content_block_stop/message_delta/message_stop). Before such a
+  // frame the held cross-frame buffer tail is flushed as a valid delta frame, so
+  // the residual lands in-order BEFORE the terminator — never after message_stop.
+  // Keepalives (ping) are deliberately NOT listed, so a match split across a ping
+  // is still caught by the sliding buffer.
+  const flushOnType = streaming?.flushOnType ?? null;
   const decoder = new TextDecoder("utf-8");
   const frames = createFrameSplitter(wireFormat);
 
   let blocked = false;
+  // A structural template of the last frame that carried delta text, used to
+  // re-emit a held buffer tail as a VALID delta frame (preserving its wire
+  // wrapper — Anthropic's `event:` line — plus sibling fields like type/index).
+  let lastDeltaTemplate = null;
+
+  async function flushHeldTail() {
+    const flushed = await protector.flush();
+    if (flushed.blocked) {
+      blocked = true;
+      return;
+    }
+    if (!flushed.text || !deltaPath) {
+      return;
+    }
+    if (lastDeltaTemplate) {
+      const object = structuredClone(lastDeltaTemplate.object);
+      setByPath(object, deltaPath, flushed.text);
+      sink.write(serializeFrame(object, wireFormat, lastDeltaTemplate.original));
+    } else {
+      // No prior delta frame to model — fall back to a minimal synthesized frame.
+      sink.write(serializeFrame(buildPathObject(deltaPath, flushed.text), wireFormat, null));
+    }
+  }
 
   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);
+      // P1-CR-005 — a parse-failed frame is one of two things:
+      //  (1) a CONTROL frame with no inspectable text (the SSE [DONE] sentinel,
+      //      a comment-only frame, an empty/whitespace/keepalive frame) — there
+      //      is genuinely nothing to protect, so pass it through verbatim; or
+      //  (2) a CONTENT frame whose data: payload is NOT JSON (plain text,
+      //      partial/malformed JSON, provider-specific text). That text CAN carry
+      //      PII/secrets, so it must be INSPECTED AS TEXT, not raw-passed.
+      if (parsed.control || parsed.text == null) {
+        sink.write(frame.raw);
+        return;
+      }
+      // Inspect the reconstructed data text as a single self-contained payload.
+      // protectText is DISTINCT from the delta-channel push/flush buffer, so a
+      // non-JSON frame's text never corrupts the JSON delta sliding buffer. A
+      // block-action detection fails the stream closed; otherwise re-emit the
+      // protected text (preserving the original wire wrapper / event: lines).
+      const protectedText = await protector.protectText(parsed.text);
+      if (protectedText.blocked) {
+        blocked = true;
+        return;
+      }
+      sink.write(serializeTextFrame(protectedText.text, wireFormat, frame));
       return;
     }
 
     const json = parsed.json;
+
+    // A bare PRIMITIVE JSON value (string/number/boolean/null) has no object
+    // structure for the delta/extras object path — a deltaPath setByPath on a
+    // string root would throw an uncaught TypeError on an attacker-influenceable
+    // frame. A JSON string can itself carry PII, so inspect the re-serialized
+    // value as text (same single-shot path as a non-JSON content frame).
+    if (json === null || typeof json !== "object") {
+      const protectedPrimitive = await protector.protectText(JSON.stringify(json));
+      if (protectedPrimitive.blocked) {
+        blocked = true;
+        return;
+      }
+      sink.write(serializeTextFrame(protectedPrimitive.text, wireFormat, frame));
+      return;
+    }
+
+    // A delta-terminating frame: flush the held tail (as a valid delta frame)
+    // before emitting it, so the residual is correctly ordered.
+    if (flushOnType && flushOnType.values.includes(getByPath(json, flushOnType.path))) {
+      await flushHeldTail();
+      if (blocked) {
+        return;
+      }
+    }
+
     let deltaText = null;
     if (deltaPath) {
       const found = getByPath(json, deltaPath);
@@ -50,6 +130,8 @@ export async function inspectResponseStream({ source, sink, streaming, protector
         return;
       }
       setByPath(frameObject, deltaPath, pushed.text);
+      // Snapshot this frame's structure + wire wrapper as the flush template.
+      lastDeltaTemplate = { object: structuredClone(frameObject), original: frame };
     }
 
     sink.write(serializeFrame(frameObject, wireFormat, frame));
@@ -77,13 +159,8 @@ export async function inspectResponseStream({ source, sink, streaming, protector
   }
 
   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));
-    }
+    // Flush any remaining held tail (a stream that ended on a delta frame).
+    await flushHeldTail();
   }
 
   // The caller closes the sink AFTER recording the stream decision, so the
@@ -120,40 +197,140 @@ function createFrameSplitter(format) {
   };
 }
 
+// Parse a frame. On success: { ok:true, json }. On failure the caller needs to
+// know WHICH kind of failure it is (P1-CR-005):
+//   - { ok:false, control:true }          → a CONTROL frame (no inspectable
+//                                             text: [DONE], comment-only, empty/
+//                                             whitespace/keepalive) → pass raw.
+//   - { ok:false, control:false, text }   → a CONTENT frame whose data: payload
+//                                             is non-JSON → inspect `text` as text.
+// Recognize an SSE `data:` field line LENIENTLY — allowing (non-spec) leading
+// whitespace before the field name — and return its payload (one leading space
+// after the colon stripped per the SSE spec), or null if the line is not a data
+// field. SECURITY (P1-CR-005 follow-up): recognition MUST be identical in the
+// parser (which inspects/redacts) and the serializers (which re-emit). If the
+// serializer used a stricter `line.startsWith("data:")` it would fail to match a
+// `  data: <pii>` line, emit it VERBATIM, and leak the original plaintext while
+// separately appending the redacted copy. Both sides use this one helper.
+const SSE_DATA_LINE = /^[ \t]*data:/;
+function sseDataPayload(line) {
+  const match = /^[ \t]*data:(.*)$/.exec(line);
+  return match ? match[1].replace(/^ /, "") : null;
+}
+
 function parseFrame(frame, format) {
   if (!frame) {
-    return { ok: false };
+    return { ok: false, control: true, text: null };
   }
   let payload = frame.body;
   if (format === "sse") {
+    // An empty/whitespace/comment-only/keepalive frame has no data: line → a
+    // CONTROL frame with nothing to inspect.
+    if (payload === "") {
+      return { ok: false, control: true, text: null };
+    }
     const dataLines = payload
       .split("\n")
-      .filter((line) => line.startsWith("data:"))
-      .map((line) => line.slice(5).trim());
+      .map(sseDataPayload)
+      .filter((value) => value !== null);
     if (dataLines.length === 0) {
-      return { ok: false };
+      // Comment-only (`:` lines) or field-only (event:/id:/retry:) frame.
+      return { ok: false, control: true, text: null };
     }
-    payload = dataLines.join("");
+    // P2-CR-013 — the SSE model joins multiple data: lines with a NEWLINE, not
+    // "". Newlines are valid JSON whitespace between tokens / inside a string, so
+    // a multi-line JSON event still JSON.parses; a multi-line plain-text event is
+    // reconstructed with its newlines before text inspection.
+    payload = dataLines.join("\n");
     if (payload === SSE_DONE) {
-      return { ok: false };
+      // The [DONE] sentinel: a CONTROL frame, never inspected.
+      return { ok: false, control: true, text: null };
     }
+  } else if (payload === "") {
+    // NDJSON: an empty/whitespace line is a CONTROL/keepalive frame.
+    return { ok: false, control: true, text: null };
   }
   try {
     return { ok: true, json: JSON.parse(payload) };
   } catch {
-    return { ok: false };
+    // Non-JSON CONTENT: surface the reconstructed payload text for inspection.
+    return { ok: false, control: false, text: payload };
   }
 }
 
 function serializeFrame(json, format, original) {
   const body = JSON.stringify(json);
   if (format === "sse") {
+    // Preserve the original SSE field lines (`event:`, `id:`, `retry:`, `:`
+    // comments) and substitute only the data payload. Event-typed streams
+    // (Anthropic Messages) dispatch on the `event:` line, so dropping it would
+    // make the stream unconsumable. OpenAI-style frames carry only a `data:`
+    // line, so the output is byte-identical to `data: ${body}\n\n`.
+    if (original && typeof original.raw === "string") {
+      const lines = original.raw.replace(/\n+$/, "").split("\n");
+      const out = [];
+      let dataWritten = false;
+      for (const line of lines) {
+        if (SSE_DATA_LINE.test(line)) {
+          // Collapse any (multi-line) data payload into the single new body. Use
+          // the SAME lenient match as the parser so a `  data:` line is replaced,
+          // never emitted verbatim (which would leak the original plaintext).
+          if (!dataWritten) {
+            out.push(`data: ${body}`);
+            dataWritten = true;
+          }
+        } else {
+          out.push(line);
+        }
+      }
+      if (!dataWritten) {
+        out.push(`data: ${body}`);
+      }
+      return `${out.join("\n")}\n\n`;
+    }
     return `data: ${body}\n\n`;
   }
   // NDJSON: preserve the original trailing newline style when available.
   return original && original.raw.endsWith("\n") ? `${body}\n` : `${body}\n`;
 }
 
+// P1-CR-005 — re-serialize a parse-failed CONTENT frame after its data text has
+// been inspected/transformed. Unlike serializeFrame (which JSON.stringifies an
+// object), this carries through ARBITRARY text. For SSE it preserves the
+// original non-data field lines (event:/id:/retry:/`:` comments) and re-emits the
+// protected text as data: lines — one per text line, per the SSE spec, so a
+// multi-line payload round-trips correctly. For NDJSON the frame body IS the
+// text, so emit the protected text plus a newline.
+function serializeTextFrame(text, format, original) {
+  if (format !== "sse") {
+    return `${text}\n`;
+  }
+  const dataLines = text.split("\n").map((line) => `data: ${line}`);
+  if (original && typeof original.raw === "string") {
+    const lines = original.raw.replace(/\n+$/, "").split("\n");
+    const out = [];
+    let dataWritten = false;
+    for (const line of lines) {
+      if (SSE_DATA_LINE.test(line)) {
+        // Replace the (possibly multi-line) data block with the protected lines.
+        // Lenient match (same as the parser) so a `  data:` line is replaced, not
+        // emitted verbatim (which would leak the original plaintext PII).
+        if (!dataWritten) {
+          out.push(...dataLines);
+          dataWritten = true;
+        }
+      } else {
+        out.push(line);
+      }
+    }
+    if (!dataWritten) {
+      out.push(...dataLines);
+    }
+    return `${out.join("\n")}\n\n`;
+  }
+  return `${dataLines.join("\n")}\n\n`;
+}
+
 export function getByPath(value, path) {
   let current = value;
   for (const part of path) {