haechi 1.1.1 → 1.2.0

package/packages/filter/index.mjs

@@ -1,3 +1,11 @@
+// The hard-block detection types: a leak of one of these is a load-bearing
+// fail-closed concern, so the WS2c precision dials (filters.minConfidence,
+// filters.allowlist) may NOT suppress a detection of any of them. minConfidence
+// trims only the precision-risky SOFT types; the allowlist's per-value/per-path
+// exceptions are ignored for these types (the detection still fires). Exported
+// so the core detect→decide path enforces the same exemption set the docs pin.
+export const HARD_BLOCK_TYPES = new Set(["secret", "api_key", "kr_rrn", "card"]);
+
 const DEFAULT_RULES = [
   {
     id: "email",
@@ -9,9 +17,15 @@ const DEFAULT_RULES = [
   {
     // KR mobile numbers (01[016789] prefixes); landlines are out of scope.
     // krPhoneValid keeps a bare separator-less run from matching a timestamp/id.
+    // The leading `(?<![\w+-])` / trailing `(?![\w-])` boundaries (WS2c) stop the
+    // rule from matching a phone-shaped digit run that is a SUBSTRING of a longer
+    // hex/alnum/dashed run — e.g. the `…a716-446655440000` tail of a UUID, where
+    // the inner `16-44665544` otherwise mis-fired as a phone. The boundaries
+    // never affect a real number: a KR mobile sits on a word/space/punctuation
+    // edge and `+82` starts on the `+` (allowed before the boundary).
     id: "kr-phone",
     type: "phone",
-    pattern: "(?:\\+82[-\\s]?)?0?1[016789][-.\\s]?\\d{3,4}[-.\\s]?\\d{4}",
+    pattern: "(?<![\\w+-])(?:\\+82[-\\s]?)?0?1[016789][-.\\s]?\\d{3,4}[-.\\s]?\\d{4}(?![\\w-])",
     flags: "g",
     confidence: 0.9,
     validate: krPhoneValid
@@ -40,6 +54,76 @@ const DEFAULT_RULES = [
     confidence: 0.95
   },
   {
+    // AWS access key id: a long-lived (AKIA) or temporary (ASIA) key id is a
+    // hard-anchored prefix + EXACTLY 16 uppercase-alphanumeric chars. The fixed
+    // prefix + fixed length is what makes this high-precision (no bare base64).
+    id: "aws-access-key-id",
+    type: "api_key",
+    pattern: "\\b(?:AKIA|ASIA)[0-9A-Z]{16}\\b",
+    flags: "g",
+    confidence: 0.95
+  },
+  {
+    // GitHub token: pat (ghp_), oauth (gho_), user-to-server (ghu_), server-to-
+    // server (ghs_), refresh (ghr_). Anchored prefix + a long base64-ish body.
+    // GitHub's own format is 36 chars after the prefix; we allow >=36 (the
+    // corpus fixture is 38) and cap to keep the match bounded.
+    id: "github-token",
+    type: "secret",
+    pattern: "\\bgh[pousr]_[A-Za-z0-9]{36,255}\\b",
+    flags: "g",
+    confidence: 0.95
+  },
+  {
+    // Google API key: anchored AIza + exactly 35 chars from the URL-safe
+    // alphabet. Fixed prefix + fixed length = high precision.
+    id: "google-api-key",
+    type: "api_key",
+    pattern: "\\bAIza[0-9A-Za-z_-]{35}\\b",
+    flags: "g",
+    confidence: 0.9
+  },
+  {
+    // Slack token: bot (xoxb-), user (xoxa/xoxp-), refresh (xoxr-), legacy
+    // (xoxs-). Anchored xox[baprs]- + a >=10-char body. The corpus value is a
+    // deliberately low-entropy placeholder, so the rule anchors on the prefix +
+    // body shape, not entropy.
+    id: "slack-token",
+    type: "secret",
+    pattern: "\\bxox[baprs]-[0-9A-Za-z-]{10,}\\b",
+    flags: "g",
+    confidence: 0.9
+  },
+  {
+    // JWT: three dot-separated base64url segments where the FIRST starts with
+    // `eyJ` — the base64 of `{"`, i.e. the opening of the JSON header. Anchoring
+    // on `eyJ` + two more base64url groups keeps this from matching arbitrary
+    // dotted tokens (a bare base64 triplet without the JSON header is not a JWT).
+    id: "jwt",
+    type: "secret",
+    pattern: "\\beyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\b",
+    flags: "g",
+    confidence: 0.9
+  },
+  {
+    // PEM private key: the armored header. We match the header line itself
+    // (`-----BEGIN [...] PRIVATE KEY-----`) — its presence is the credential
+    // signal; the body is high-entropy base64 we do not need to span. Covers
+    // RSA/EC/OPENSSH/DSA/ENCRYPTED variants and the bare `PRIVATE KEY` form.
+    id: "pem-private-key",
+    type: "secret",
+    pattern: "-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----",
+    flags: "g",
+    confidence: 0.98
+  },
+  {
+    // Bearer credential. Deliberately NOT context-anchored to `Authorization:`:
+    // detection runs PER STRING LEAF, and a real payload carries the credential
+    // as its own leaf (`{"Authorization": "Bearer <token>"}` walks to the bare
+    // value `"Bearer <token>"`), so a lookbehind requiring the header key in the
+    // same string would MISS the realistic case — a recall regression on a
+    // hard-block (`secret`) type. `secret` is fail-closed: a `Bearer …` prose
+    // false positive is the accepted cost of never missing a leaked token.
     id: "bearer-token",
     type: "secret",
     pattern: "\\bBearer\\s+[A-Za-z0-9._~+/-]{16,}\\b",
@@ -50,11 +134,58 @@ const DEFAULT_RULES = [
     id: "assignment-secret",
     type: "secret",
     // Lookbehind keeps the key name out of the match so transforms replace
-    // only the secret value, not the assignment prefix.
-    pattern: "(?<=\\b(?:api[_-]?key|secret|token|password)\\s*[:=]\\s*['\\\"]?)[A-Za-z0-9._~+/-]{12,}",
+    // only the secret value, not the assignment prefix. The key vocabulary
+    // covers the common credential-assignment names (cloud secrets, OAuth
+    // client secrets, PEM/private keys, access/refresh tokens) so a
+    // `<key> = <value>` leak is caught even when the value itself has no
+    // self-describing prefix (e.g. an AWS secret access key is bare base64).
+    pattern: "(?<=\\b(?:api[_-]?key|api[_-]?secret|secret[_-]?key|secret|aws[_-]?secret[_-]?access[_-]?key|client[_-]?secret|private[_-]?key|access[_-]?token|refresh[_-]?token|token|password)\\s*[:=]\\s*['\\\"]?)[A-Za-z0-9._~+/-]{12,}",
     flags: "gi",
     confidence: 0.85
   },
+  {
+    // US SSN: AAA-GG-SSSS. The format alone collides with 9-digit ids, so a
+    // validator rejects the SSA-invalid ranges (area 000/666/900-999, group 00,
+    // serial 0000). The separators are required by the pattern — a bare 9-digit
+    // run is intentionally NOT matched (it is indistinguishable from an id).
+    id: "us-ssn",
+    type: "us_ssn",
+    pattern: "(?<![\\w-])\\d{3}-\\d{2}-\\d{4}(?![\\w-])",
+    flags: "g",
+    confidence: 0.85,
+    validate: usSsnValid
+  },
+  {
+    // IBAN: country(2 alpha) + 2 check digits + BBAN. The mod-97 checksum is
+    // what makes this high-precision — a random alnum run of the right shape
+    // almost never satisfies mod-97 == 1. Length 15-34 per ISO 13616.
+    id: "iban",
+    type: "iban",
+    pattern: "(?<![A-Z0-9])[A-Z]{2}\\d{2}[A-Z0-9]{11,30}(?![A-Z0-9])",
+    flags: "g",
+    confidence: 0.9,
+    validate: ibanValid
+  },
+  {
+    // E.164 international phone: ONLY with a leading `+` (a bare digit run is an
+    // id/timestamp, never matched here). `+` country digit (1-9) then 6-14 more.
+    id: "e164-phone",
+    type: "phone",
+    pattern: "(?<![\\w+])\\+[1-9]\\d{6,14}(?![\\w])",
+    flags: "g",
+    confidence: 0.8
+  },
+  {
+    // US national phone: ONLY with separators — `(NXX) NXX-XXXX` or
+    // `NXX-NXX-XXXX`. A separator-less 10-digit run is deliberately NOT matched
+    // (it collides with ids/timestamps; the kr-phone rule already guards bare
+    // runs). Conservative by design — phone is the highest false-positive risk.
+    id: "us-phone",
+    type: "phone",
+    pattern: "(?<![\\w-])(?:\\(\\d{3}\\)\\s?|\\d{3}-)\\d{3}-\\d{4}(?![\\w-])",
+    flags: "g",
+    confidence: 0.75
+  },
   // Indirect prompt injection heuristics. Response/tool-result direction only,
   // and the policy default for the injection type is `allow` (report-only):
   // detections are audited regardless of action, and false-positive blocks
@@ -139,8 +270,62 @@ export function detectEntry(entry, rules, context = {}) {
   // marker-shaped string is NOT Haechi output (Haechi hasn't transformed it yet),
   // so it is scanned normally — otherwise an attacker could wrap a real secret in
   // a fake `[TOKEN:…]` to evade request-side detection.
+  // Markers are pure ASCII and NFKC-stable, so their spans are computed on the
+  // ORIGINAL value exactly as before — they line up with the same-length
+  // normalized scan (Case 2 below) and are irrelevant to the whole-leaf scan
+  // (Case 3).
   const markerSpans = context?.direction === "response" ? haechiMarkerSpans(entry.value) : [];
 
+  // WS2d — Unicode evasion via NFKC normalization. A client can defeat every
+  // regex rule by sending PII/secrets in a Unicode form that folds to ASCII
+  // (full-width digits `４２４２…`, full-width `＠`, mathematical/enclosed
+  // alphanumerics). NFKC normalization maps those to their compatibility ASCII
+  // form so the rules match. The crux is OFFSET INTEGRITY: detections carry
+  // {start,end} into entry.value, but the transform slices the ORIGINAL string
+  // (packages/core transformString). Three cases keep offsets valid:
+  const value = entry.value;
+  const normalized = value.normalize("NFKC");
+  if (normalized === value) {
+    // Case 1 (~99%): nothing folded. Detect on the original exactly as before —
+    // byte-identical behavior, zero regression.
+    return removeOverlaps(scanForDetections(value, rules, context, markerSpans, entry, value));
+  }
+  if (isPositionStableNfkc(value, normalized)) {
+    // Case 2: every codepoint folded to the SAME UTF-16 length and the per-
+    // codepoint folds reconstruct the whole normalization, so each original
+    // character occupies the SAME offsets in `normalized` as in `value` (e.g.
+    // full-width→ASCII digits/letters). A match's {start,end} on `normalized` are
+    // therefore valid on the ORIGINAL value — exact-span redaction of the evaded
+    // value, with the recorded `value` taken from the original slice so
+    // tokenize/AAD/audit see the real bytes. A bare `normalized.length ===
+    // value.length` check is UNSOUND: a length-contracting codepoint before the
+    // PII compensated by a length-expanding one after it keeps the total length
+    // equal yet shifts every interior offset (redacting the wrong bytes), so such
+    // inputs must fall through to the Case 3 whole-leaf path. Validators still run
+    // on the normalized match text (Luhn/RRN need ASCII digits).
+    return removeOverlaps(scanForDetections(normalized, rules, context, markerSpans, entry, value));
+  }
+  // Case 3: the fold is NOT position-stable (a length-changing decomposition, or a
+  // compensating contraction+expansion that shifts interior offsets). Offsets on
+  // the normalized copy do NOT map back to the original, so we CANNOT do exact-span
+  // redaction.
+  // FAIL CLOSED: emit ONE detection per matched type covering the WHOLE leaf so
+  // the transform redacts/blocks the entire leaf. Over-redacting an evasion
+  // attempt is the safe failure. removeOverlaps is intentionally skipped — every
+  // detection spans the whole leaf so they all "overlap"; the transform collapses
+  // them to a single whole-leaf replacement via its cursor, and any `block` among
+  // them blocks the payload, while preserving per-type detection reporting.
+  return wholeLeafDetections(normalized, rules, context, entry, value);
+}
+
+// Run every applicable rule over `scanText` (the original value, or its
+// same-length NFKC normalization). Offsets index `scanText`, which is positionally
+// 1:1 with `originalValue` (Case 1: identical; Case 2: same UTF-16 length), so the
+// {start,end} are valid on `originalValue`. The recorded `value` is the ORIGINAL
+// slice (never the normalized form). Marker spans (response-only) are computed on
+// the original and align under both cases.
+function scanForDetections(scanText, rules, context, markerSpans, entry, originalValue) {
+  const detections = [];
   for (const rule of rules) {
     // Direction-scoped rules (e.g. injection heuristics) only run on the
     // matching traffic direction; rules without a direction run everywhere.
@@ -148,13 +333,13 @@ export function detectEntry(entry, rules, context = {}) {
       continue;
     }
     const regex = new RegExp(rule.pattern, rule.flags.includes("g") ? rule.flags : `${rule.flags}g`);
-    for (const match of entry.value.matchAll(regex)) {
-      const value = match[0];
-      if (rule.validate && !rule.validate(value)) {
+    for (const match of scanText.matchAll(regex)) {
+      const matchText = match[0];
+      if (rule.validate && !rule.validate(matchText)) {
         continue;
       }
       const start = match.index;
-      const end = match.index + value.length;
+      const end = match.index + matchText.length;
       if (overlapsAny(start, end, markerSpans)) {
         continue;
       }
@@ -167,12 +352,73 @@ export function detectEntry(entry, rules, context = {}) {
         start,
         end,
         confidence: rule.confidence,
-        value
+        value: originalValue.slice(start, end)
       });
     }
   }
+  return detections;
+}
+
+// Case 3 fail-closed scan: discover which types the NFKC-normalized text matches,
+// then emit one whole-leaf detection per distinct type (start:0, end:value.length,
+// value: the whole original leaf). The response-direction marker skip does NOT
+// apply here: a length-divergent leaf cannot BE a Haechi marker (markers are ASCII
+// and NFKC-stable), so an evasion attempt can never masquerade as one.
+function wholeLeafDetections(normalized, rules, context, entry, originalValue) {
+  const seenTypes = new Set();
+  const detections = [];
+  for (const rule of rules) {
+    if (rule.direction && rule.direction !== context?.direction) {
+      continue;
+    }
+    if (seenTypes.has(rule.type)) {
+      continue;
+    }
+    const regex = new RegExp(rule.pattern, rule.flags.includes("g") ? rule.flags : `${rule.flags}g`);
+    let matched = false;
+    for (const match of normalized.matchAll(regex)) {
+      if (!rule.validate || rule.validate(match[0])) {
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      continue;
+    }
+    seenTypes.add(rule.type);
+    detections.push({
+      type: rule.type,
+      ruleId: rule.id,
+      path: entry.path,
+      pathText: entry.pathText,
+      kind: entry.kind ?? "value",
+      start: 0,
+      end: originalValue.length,
+      confidence: rule.confidence,
+      value: originalValue
+    });
+  }
+  return detections;
+}
 
-  return removeOverlaps(detections);
+// Sound precondition for Case 2: a match's {start,end} on the NFKC-normalized
+// text map 1:1 onto the ORIGINAL value. True only when EVERY codepoint folds to
+// the same number of UTF-16 units (so no interior offset shifts) AND the per-
+// codepoint folds concatenate to the whole normalization (so no cross-boundary
+// composition moved content). The bare `normalized.length === value.length` check
+// is unsound — a contraction before the PII compensated by an expansion after it
+// keeps the total length equal while shifting every interior offset, redacting the
+// wrong bytes. Runs only on a leaf that actually folded (normalized !== value).
+function isPositionStableNfkc(value, normalized) {
+  let rebuilt = "";
+  for (const ch of value) {
+    const folded = ch.normalize("NFKC");
+    if (folded.length !== ch.length) {
+      return false;
+    }
+    rebuilt += folded;
+  }
+  return rebuilt === normalized;
 }
 
 // Spans of Haechi's own transform markers in a string, so detection can skip
@@ -291,3 +537,47 @@ function krRrnValid(value) {
   const check = (11 - (sum % 11)) % 10;
   return check === Number(digits[12]);
 }
+
+// US SSN structural validity (SSA allocation rules). The format `AAA-GG-SSSS`
+// alone collides with arbitrary 9-digit ids, so we reject the never-issued
+// ranges: area 000, 666, and 900-999; group 00; serial 0000. This is what turns
+// the loose shape into a high-precision detection.
+function usSsnValid(value) {
+  const match = /^(\d{3})-(\d{2})-(\d{4})$/.exec(value);
+  if (!match) {
+    return false;
+  }
+  const area = Number(match[1]);
+  const group = Number(match[2]);
+  const serial = Number(match[3]);
+  if (area === 0 || area === 666 || area >= 900) {
+    return false;
+  }
+  if (group === 0) {
+    return false;
+  }
+  if (serial === 0) {
+    return false;
+  }
+  return true;
+}
+
+// IBAN mod-97 checksum (ISO 7064 / ISO 13616). Move the first four chars to the
+// end, map letters to 10-35, and the resulting integer must be congruent to 1
+// mod 97. Computed digit-by-digit so the big integer never overflows. This
+// checksum is the precision guarantee — random alnum runs almost never pass.
+function ibanValid(value) {
+  const iban = value.replace(/\s/g, "").toUpperCase();
+  if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban)) {
+    return false;
+  }
+  const rearranged = iban.slice(4) + iban.slice(0, 4);
+  let remainder = 0;
+  for (const char of rearranged) {
+    const mapped = /\d/.test(char) ? char : String(char.charCodeAt(0) - 55);
+    for (const digit of mapped) {
+      remainder = (remainder * 10 + Number(digit)) % 97;
+    }
+  }
+  return remainder === 1;
+}

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)
+});