haechi 1.1.2 → 1.3.0

package/packages/metrics/index.mjs

@@ -0,0 +1,181 @@
+// WS4-A telemetry seam (reliability-hardening-track §WS4 "Telemetry").
+//
+// A minimal, zero-dependency in-memory metrics collector rendering the
+// Prometheus text exposition format. It is an INJECTABLE collaborator
+// (providers.metrics in createRuntime), mirroring auditSink/rateLimiter; an
+// operator who wants a real metrics backend injects their own object exposing
+// the same { increment, observe, render } contract.
+//
+// HARD INVARIANT (the no-plaintext-in-audit invariant, extended to telemetry):
+// every metric name AND every label value is a BOUNDED ENUM — a route id, a
+// policy mode, or a decision class. It is NEVER an identity id/subject, a token,
+// a detected value, or any other unbounded/PII-bearing string. This module does
+// not — and structurally cannot — accept a payload value: callers pass only
+// pre-classified enum labels, and label values are coerced + length-capped here
+// as defence in depth so an accidental high-cardinality value cannot explode
+// the series set or leak content.
+
+// Metric catalogue: name -> { type, help }. Counters and one histogram. Keeping
+// the catalogue explicit (rather than letting callers invent metric names)
+// bounds the metric-name dimension to this fixed set.
+const COUNTERS = {
+  haechi_requests_total: "Proxy requests by route, mode, and decision class.",
+  haechi_blocks_total: "Requests blocked by a policy decision.",
+  haechi_auth_denied_total: "Requests denied at authentication.",
+  haechi_rate_limited_total: "Requests rejected by the rate limiter.",
+  haechi_upstream_timeout_total: "Upstream requests that timed out.",
+  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)."
+};
+
+const HISTOGRAMS = {
+  haechi_request_duration_seconds: "End-to-end proxy request handling duration in seconds."
+};
+
+// Default request-duration histogram buckets (seconds). Bounded, fixed set.
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+
+// Defence-in-depth label hygiene: a label value must be a short, bounded token.
+// We coerce to string, trim, cap length, and collapse anything outside a safe
+// charset to "_". This guarantees that even a caller mistake cannot place a raw
+// payload value or a long identity string into a series label.
+const MAX_LABEL_LENGTH = 64;
+
+function safeLabelValue(value) {
+  if (value === undefined || value === null) {
+    return "none";
+  }
+  const text = String(value).slice(0, MAX_LABEL_LENGTH);
+  // Allow a conservative identifier charset only (route ids, modes, decisions
+  // are all of this shape). Everything else becomes "_".
+  return text.replace(/[^A-Za-z0-9_.:/-]/g, "_") || "none";
+}
+
+function seriesKey(name, labels) {
+  const parts = Object.keys(labels)
+    .sort()
+    .map((labelName) => `${labelName}="${escapeLabel(labels[labelName])}"`);
+  return parts.length > 0 ? `${name}{${parts.join(",")}}` : name;
+}
+
+function escapeLabel(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\"");
+}
+
+export function createMetrics({ buckets = DEFAULT_BUCKETS } = {}) {
+  // counterSeries: metricName -> Map(seriesKey -> { labels, value })
+  const counterSeries = new Map();
+  // histogramSeries: metricName -> Map(seriesKey -> { labels, bucketCounts, sum, count })
+  const histogramSeries = new Map();
+  const sortedBuckets = [...buckets].sort((a, b) => a - b);
+
+  function normalizeLabels(labels = {}) {
+    const out = {};
+    for (const [key, value] of Object.entries(labels)) {
+      // Label NAMES are caller-fixed identifiers; coerce defensively anyway.
+      const labelName = String(key).replace(/[^A-Za-z0-9_]/g, "_");
+      out[labelName] = safeLabelValue(value);
+    }
+    return out;
+  }
+
+  return {
+    // Increment a known counter by `amount` (default 1), labelled by a bounded
+    // enum set. An unknown metric name is ignored (fail-soft for telemetry — a
+    // metric typo must never break a request path).
+    increment(name, labels = {}, amount = 1) {
+      if (!(name in COUNTERS)) {
+        return;
+      }
+      const safe = normalizeLabels(labels);
+      const key = seriesKey(name, safe);
+      let series = counterSeries.get(name);
+      if (!series) {
+        series = new Map();
+        counterSeries.set(name, series);
+      }
+      const existing = series.get(key);
+      if (existing) {
+        existing.value += amount;
+      } else {
+        series.set(key, { labels: safe, value: amount });
+      }
+    },
+
+    // Observe a value into a known histogram (request-duration seconds).
+    observe(name, value, labels = {}) {
+      if (!(name in HISTOGRAMS) || typeof value !== "number" || !Number.isFinite(value)) {
+        return;
+      }
+      const safe = normalizeLabels(labels);
+      const key = seriesKey(name, safe);
+      let series = histogramSeries.get(name);
+      if (!series) {
+        series = new Map();
+        histogramSeries.set(name, series);
+      }
+      let entry = series.get(key);
+      if (!entry) {
+        entry = { labels: safe, bucketCounts: new Array(sortedBuckets.length).fill(0), sum: 0, count: 0 };
+        series.set(key, entry);
+      }
+      entry.sum += value;
+      entry.count += 1;
+      for (let i = 0; i < sortedBuckets.length; i += 1) {
+        if (value <= sortedBuckets[i]) {
+          entry.bucketCounts[i] += 1;
+        }
+      }
+    },
+
+    // Render the full Prometheus text exposition. Every declared counter and
+    // histogram emits its HELP/TYPE header even with no observations, so the
+    // surface is stable for scrapers.
+    render() {
+      const lines = [];
+
+      for (const [name, help] of Object.entries(COUNTERS)) {
+        lines.push(`# HELP ${name} ${help}`);
+        lines.push(`# TYPE ${name} counter`);
+        const series = counterSeries.get(name);
+        if (series) {
+          for (const { labels, value } of series.values()) {
+            lines.push(`${seriesKey(name, labels)} ${value}`);
+          }
+        }
+      }
+
+      for (const [name, help] of Object.entries(HISTOGRAMS)) {
+        lines.push(`# HELP ${name} ${help}`);
+        lines.push(`# TYPE ${name} histogram`);
+        const series = histogramSeries.get(name);
+        if (series) {
+          for (const entry of series.values()) {
+            // bucketCounts[i] already holds the cumulative count of observations
+            // with value <= sortedBuckets[i] (observe() increments every bucket
+            // the value falls under), which is exactly the Prometheus le="..."
+            // cumulative bucket semantics — emit it directly.
+            for (let i = 0; i < sortedBuckets.length; i += 1) {
+              const labels = { ...entry.labels, le: String(sortedBuckets[i]) };
+              lines.push(`${seriesKey(`${name}_bucket`, labels)} ${entry.bucketCounts[i]}`);
+            }
+            const infLabels = { ...entry.labels, le: "+Inf" };
+            lines.push(`${seriesKey(`${name}_bucket`, infLabels)} ${entry.count}`);
+            lines.push(`${seriesKey(`${name}_sum`, entry.labels)} ${entry.sum}`);
+            lines.push(`${seriesKey(`${name}_count`, entry.labels)} ${entry.count}`);
+          }
+        }
+      }
+
+      return `${lines.join("\n")}\n`;
+    }
+  };
+}
+
+// Exported for tests / operators who want to assert the bounded metric surface.
+export const METRIC_NAMES = Object.freeze({
+  counters: Object.keys(COUNTERS),
+  histograms: Object.keys(HISTOGRAMS)
+});

package/packages/privacy-profiles/index.mjs

@@ -12,7 +12,11 @@ const PROFILES = {
         email: "redact",
         card: "block",
         api_key: "block",
-        secret: "block"
+        secret: "block",
+        // A Japan My Number leak is as sensitive as a national ID and is a
+        // checksummed true-positive — block it in every profile so a non-JP
+        // deployment that happens to process JP data is still covered.
+        jp_mynumber: "block"
       }
     },
     transfer: {
@@ -31,7 +35,17 @@ const PROFILES = {
         card: "block",
         api_key: "block",
         secret: "block",
-        kr_rrn: "block"
+        kr_rrn: "block",
+        // EU national IDs — France NIR, Spain DNI/NIE, UK National Insurance
+        // Number, Italy codice fiscale, Germany tax ID, Netherlands BSN — are
+        // GDPR special-category-adjacent identifiers; block them.
+        fr_nir: "block",
+        es_dni: "block",
+        uk_nino: "block",
+        it_codice_fiscale: "block",
+        de_steuer_id: "block",
+        nl_bsn: "block",
+        jp_mynumber: "block"
       }
     },
     transfer: {
@@ -39,6 +53,37 @@ const PROFILES = {
       note: "Treat model/tool transfer as processor/subprocessor transfer and document SCC/TIA evidence outside Haechi."
     }
   },
+  "asia-pdpa": {
+    id: "asia-pdpa",
+    region: "ASIA",
+    regulations: ["Singapore PDPA", "India DPDP Act"],
+    policy: {
+      actions: {
+        // Asia national IDs — Singapore NRIC/FIN and India Aadhaar — are sensitive
+        // identifiers under the Singapore PDPA / India DPDP Act; block them. The
+        // other checksummed national IDs are also blocked so a mixed-region payload
+        // is covered, matching the cross-profile convention.
+        sg_nric: "block",
+        in_aadhaar: "block",
+        jp_mynumber: "block",
+        kr_rrn: "block",
+        fr_nir: "block",
+        es_dni: "block",
+        it_codice_fiscale: "block",
+        de_steuer_id: "block",
+        nl_bsn: "block",
+        phone: "mask",
+        email: "redact",
+        card: "block",
+        api_key: "block",
+        secret: "block"
+      }
+    },
+    transfer: {
+      requiresAssessment: true,
+      note: "Document the PDPA/DPDP handling basis, purpose limitation, and cross-border transfer notice before production use."
+    }
+  },
   "us-general": {
     id: "us-general",
     region: "US",
@@ -49,13 +94,37 @@ const PROFILES = {
         phone: "mask",
         card: "block",
         api_key: "block",
-        secret: "block"
+        secret: "block",
+        jp_mynumber: "block"
       }
     },
     transfer: {
       requiresAssessment: false,
       note: "Classify sector rules separately before using protected health, payment, or children's data."
     }
+  },
+  "jp-appi": {
+    id: "jp-appi",
+    region: "JP",
+    regulations: ["APPI"],
+    policy: {
+      actions: {
+        // My Number (個人番号) is a special-care personal-information identifier
+        // under the My Number Act; block it. The EU/KR IDs are also blocked so a
+        // mixed-region payload is covered, matching the cross-profile convention.
+        jp_mynumber: "block",
+        phone: "mask",
+        email: "redact",
+        card: "block",
+        api_key: "block",
+        secret: "block",
+        kr_rrn: "block"
+      }
+    },
+    transfer: {
+      requiresAssessment: true,
+      note: "Document the My Number Act handling basis, purpose limitation, and cross-border transfer notice before production use."
+    }
   }
 };
 

package/packages/protocol-adapters/index.mjs

@@ -8,6 +8,28 @@ const SSE_RESPONSES = { format: "sse", deltaPath: null };
 const SSE_LLAMA_LEGACY = { format: "sse", deltaPath: ["content"] };
 const NDJSON_OLLAMA_CHAT = { format: "ndjson", deltaPath: ["message", "content"] };
 const NDJSON_OLLAMA_GENERATE = { format: "ndjson", deltaPath: ["response"] };
+// Anthropic Messages API streams event-typed SSE frames; the incremental text
+// channel is `delta.text` inside a `content_block_delta` frame. Other frame
+// types (message_start, ping, etc.) don't carry deltaPath, so they get
+// within-frame protection but no cross-frame buffering. The stream-filter
+// preserves each frame's `event:` line on re-serialize. `flushOnType` lists the
+// frame types that END a delta sequence: before one of them the held cross-frame
+// buffer tail is flushed as a valid `content_block_delta`, so the residual lands
+// IN ORDER (before content_block_stop/message_stop) rather than after the stream
+// terminates. `ping` is intentionally absent — a match split across a keepalive
+// must still be caught by the sliding buffer. Legacy /v1/complete streams a
+// `completion` delta (no block framing, so no flushOnType needed).
+const SSE_ANTHROPIC_MESSAGES = {
+  format: "sse",
+  deltaPath: ["delta", "text"],
+  flushOnType: { path: ["type"], values: ["content_block_stop", "message_delta", "message_stop"] }
+};
+const SSE_ANTHROPIC_COMPLETE = { format: "sse", deltaPath: ["completion"] };
+// Google Gemini streams :streamGenerateContent as DATA-ONLY SSE (no `event:`
+// lines, like OpenAI). Each `data:` frame is a FULL GenerateContentResponse;
+// the incremental text channel is just deeper. Because frames are data-only,
+// the held cross-frame tail can flush at end-of-stream — no flushOnType needed.
+const SSE_GEMINI = { format: "sse", deltaPath: ["candidates", 0, "content", "parts", 0, "text"] };
 
 const ADAPTERS = {
   "openai-compatible": {
@@ -50,6 +72,47 @@ const ADAPTERS = {
       route("/api/embed", "embed"),
       route("/api/embeddings", "embeddings")
     ]
+  },
+  "anthropic": {
+    id: "anthropic",
+    protocol: "anthropic",
+    routes: [
+      // Anthropic Messages API. PII can sit in the top-level `system` string/blocks
+      // or any `messages[].content` string or content-block text/input — the core
+      // tree walk (collectStringEntries) covers every string leaf, so no custom
+      // extraction is needed. Streams via content_block_delta `delta.text`.
+      route("/v1/messages", "messages", { streaming: SSE_ANTHROPIC_MESSAGES }),
+      // count_tokens is a utility, but it carries prompt content, so protect it.
+      route("/v1/messages/count_tokens", "count-tokens", { protectRequest: true }),
+      // Legacy text completions: `prompt` is a top-level string; streams a `completion` delta.
+      route("/v1/complete", "complete", { streaming: SSE_ANTHROPIC_COMPLETE })
+    ]
+  },
+  "gemini": {
+    id: "gemini",
+    protocol: "gemini",
+    routes: [
+      // Google Gemini API. Endpoints are MODEL-IN-PATH with a `:method` suffix:
+      // POST /v1beta/models/{model}:generateContent (and /v1, and arbitrary
+      // model names like gemini-2.0-flash). The route key is therefore the
+      // `:method` SUFFIX, not a fixed path — declared via `methodSuffix`, which
+      // matchRoute checks only AFTER exact-path matches (so existing adapters
+      // are unaffected). PII can sit in systemInstruction.parts[].text and any
+      // contents[].parts[].text; the core tree walk (collectStringEntries)
+      // covers every string leaf, so no custom extraction is needed.
+      suffixRoute("generateContent", "generate-content"),
+      // Streaming variant: data-only SSE, full GenerateContentResponse per frame;
+      // delta text lives at candidates[0].content.parts[0].text. The :stream*
+      // endpoint ALWAYS streams (the intent is in the path, not a body flag), so
+      // mark it streamingDefault — there is no `stream:false` body field for
+      // Gemini, so isStreamingRequest always classifies it as streaming.
+      suffixRoute("streamGenerateContent", "stream-generate-content", { streamingDefault: true, streaming: SSE_GEMINI }),
+      // countTokens carries prompt content (contents/systemInstruction), so protect it.
+      suffixRoute("countTokens", "count-tokens", { protectRequest: true }),
+      // Embedding endpoints: request carries text to embed; protect it.
+      suffixRoute("embedContent", "embed", { protectRequest: true }),
+      suffixRoute("batchEmbedContents", "batch-embed", { protectRequest: true })
+    ]
   }
 };
 
@@ -121,10 +184,45 @@ function route(path, operation, options = {}) {
   };
 }
 
+// A SUFFIX route matches by a `:method` suffix instead of an exact pathname —
+// for model-in-path APIs (Gemini) where the path embeds an arbitrary model name
+// and a version prefix (e.g. /v1beta/models/gemini-2.0-flash:generateContent).
+// `path` stays null (there is no fixed path); `methodSuffix` carries the bare
+// method name and matchRoute matches when the pathname ends with `:${suffix}`.
+// matchRoute tries exact-path routes FIRST, so this never changes existing
+// exact-match behavior for openai/anthropic/ollama/llama-cpp.
+function suffixRoute(methodSuffix, operation, options = {}) {
+  return {
+    id: operation,
+    path: null,
+    methodSuffix,
+    operation,
+    protectRequest: options.protectRequest ?? true,
+    protectResponse: options.protectResponse ?? true,
+    streamingDefault: options.streamingDefault ?? false,
+    streaming: options.streaming ?? null
+  };
+}
+
 function pathFromRequestUrl(url) {
   return new URL(url, "http://haechi.local").pathname;
 }
 
 function matchRoute(routes, pathname) {
-  return routes.find((candidate) => candidate.path === pathname);
+  // 1) EXACT pathname match (unchanged) — the only matcher for openai/anthropic/
+  //    ollama/llama-cpp, so their classification is byte-for-byte identical.
+  const exact = routes.find((candidate) => candidate.path === pathname);
+  if (exact) {
+    return exact;
+  }
+  // 2) ADDITIVE: `:method`-SUFFIX match for model-in-path APIs (Gemini). A path
+  //    like /v1beta/models/gemini-2.0-flash:generateContent matches the route
+  //    whose methodSuffix the pathname ends with (`...:generateContent`). The
+  //    `:` guard prevents a bare substring (e.g. a model literally named
+  //    "generateContent") from matching without the method delimiter.
+  return routes.find(
+    (candidate) =>
+      typeof candidate.methodSuffix === "string" &&
+      pathname.endsWith(`:${candidate.methodSuffix}`)
+  );
 }