haechi 1.1.2 → 1.2.0

package/packages/core/index.mjs

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { HARD_BLOCK_TYPES } from "../filter/index.mjs";
 
 const NO_ENFORCE_MODES = new Set(["dry-run", "report-only"]);
 
@@ -10,7 +11,7 @@ const NO_ENFORCE_MODES = new Set(["dry-run", "report-only"]);
 // limits.maxNestingDepth through createHaechi → protectJson instead.
 export const DEFAULT_MAX_NESTING_DEPTH = 256;
 
-export function createHaechi({ filterEngine, policyEngine, cryptoProvider, auditSink, tokenVault = null, mode = "dry-run", limits = {} }) {
+export function createHaechi({ filterEngine, policyEngine, cryptoProvider, auditSink, tokenVault = null, mode = "dry-run", limits = {}, precision = {} }) {
   if (!filterEngine || !policyEngine || !cryptoProvider || !auditSink) {
     throw new Error("Haechi requires filterEngine, policyEngine, cryptoProvider, and auditSink");
   }
@@ -20,6 +21,15 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
     ? limits.maxNestingDepth
     : DEFAULT_MAX_NESTING_DEPTH;
 
+  // WS2c precision controls, resolved once. `minConfidence` is the precision dial
+  // (drop a detection below the threshold) and `allowlist` is the operator FP
+  // exception set. Both are FAIL-OPEN-FOR-PROTECTION: they may only TRIM
+  // precision-risky soft-type detections and can NEVER suppress a hard-block type
+  // (secret/api_key/kr_rrn/card) — that load-bearing exemption is enforced in
+  // applyPrecisionControls, not trusted to config. Default {} = current behavior.
+  const minConfidence = Number.isFinite(precision.minConfidence) ? precision.minConfidence : 0;
+  const allowlist = compileAllowlist(precision.allowlist);
+
   async function protectJson(payload, rawContext = {}) {
     // A per-request policy engine (a named profile selected from identity)
     // overrides the default. It is a control object, NOT data: strip it before
@@ -35,7 +45,13 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
     // `context.direction` ("request" | "response") gates direction-scoped rules
     // (injection) and the response-only marker exclusion in the filter engine.
     // The proxy sets it per direction; do not drop it here.
-    const detections = await filterEngine.detect({ entries, context });
+    const rawDetections = await filterEngine.detect({ entries, context });
+    // WS2c precision controls run AFTER detect and BEFORE decide: drop a low-
+    // confidence soft-type detection (minConfidence) and suppress an allowlisted
+    // soft-type detection — never a hard-block type. `precisionAudit` carries the
+    // per-type counts of what was suppressed/dropped so the audit event records
+    // it (counts/types only, never the raw value). See applyPrecisionControls.
+    const { detections, precisionAudit } = applyPrecisionControls(rawDetections, { minConfidence, allowlist });
     const decisions = [];
 
     for (const detection of detections) {
@@ -62,7 +78,8 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
       blocked,
       payload,
       detections,
-      decisions
+      decisions,
+      precisionAudit
     });
 
     await auditSink.record(auditEvent);
@@ -70,7 +87,7 @@ export function createHaechi({ filterEngine, policyEngine, cryptoProvider, audit
     return {
       payload: protectedPayload,
       blocked,
-      summary: summarize(detections, decisions),
+      summary: summarize(detections, decisions, precisionAudit),
       auditEvent,
       issuedTokens: [...issuedTokens]
     };
@@ -274,7 +291,7 @@ export function shapeOnly(value) {
   return { type: value === null ? "null" : typeof value };
 }
 
-export function summarize(detections, decisions) {
+export function summarize(detections, decisions, precisionAudit = null) {
   const byType = {};
   const byAction = {};
 
@@ -286,11 +303,121 @@ export function summarize(detections, decisions) {
     byAction[decision.action] = (byAction[decision.action] ?? 0) + 1;
   }
 
-  return {
+  const summary = {
     detectionCount: detections.length,
     byType,
     byAction
   };
+
+  // WS2c: additively record how many detections the precision controls removed
+  // before decide — `suppressedCount`/`suppressedByType` for allowlist FP
+  // exceptions and `droppedCount`/`droppedByType` for sub-minConfidence drops.
+  // Counts and types only; the matched value is NEVER recorded (no-plaintext-in-
+  // audit). Omitted entirely when nothing was removed, so 1.1 events are byte-
+  // identical and the audit hash-chain canonicalization is unaffected.
+  if (precisionAudit && precisionAudit.suppressedCount > 0) {
+    summary.suppressedCount = precisionAudit.suppressedCount;
+    summary.suppressedByType = precisionAudit.suppressedByType;
+  }
+  if (precisionAudit && precisionAudit.droppedCount > 0) {
+    summary.droppedCount = precisionAudit.droppedCount;
+    summary.droppedByType = precisionAudit.droppedByType;
+  }
+
+  return summary;
+}
+
+// Compile the configured allowlist into fast lookup sets. An entry is either a
+// bare string (an exact matched-VALUE exception) or an object { value?, path? }
+// (value exception, JSON-path exception via the PII-safe pathText, or both —
+// when both are present BOTH must match). Returns null when there is nothing to
+// allowlist so the hot path can skip the work entirely.
+function compileAllowlist(allowlist) {
+  if (!Array.isArray(allowlist) || allowlist.length === 0) {
+    return null;
+  }
+  const values = new Set();
+  const paths = new Set();
+  const pairs = [];
+  for (const entry of allowlist) {
+    if (typeof entry === "string") {
+      values.add(entry);
+      continue;
+    }
+    const hasValue = typeof entry.value === "string";
+    const hasPath = typeof entry.path === "string";
+    if (hasValue && hasPath) {
+      pairs.push({ value: entry.value, path: entry.path });
+    } else if (hasValue) {
+      values.add(entry.value);
+    } else if (hasPath) {
+      paths.add(entry.path);
+    }
+  }
+  return { values, paths, pairs };
+}
+
+// Does this detection's matched value / JSON path match an allowlist entry? The
+// path comparison uses the PII-safe `pathText` (the same hashed path the audit
+// records), so an operator allowlists `key_<hash>.…` — never a raw key name.
+function isAllowlisted(detection, allowlist) {
+  if (!allowlist) {
+    return false;
+  }
+  const { values, paths, pairs } = allowlist;
+  if (typeof detection.value === "string" && values.has(detection.value)) {
+    return true;
+  }
+  if (typeof detection.pathText === "string" && paths.has(detection.pathText)) {
+    return true;
+  }
+  for (const pair of pairs) {
+    if (detection.value === pair.value && detection.pathText === pair.path) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// WS2c precision controls — run AFTER detect, BEFORE decide. Returns the kept
+// detections plus a precisionAudit of what was removed (counts/types only).
+//
+// HARD-BLOCK INVARIANT (load-bearing, fail-closed): a detection whose type is in
+// HARD_BLOCK_TYPES (secret/api_key/kr_rrn/card) is NEVER removed here — neither a
+// low confidence nor an allowlist entry can suppress it. minConfidence trims only
+// the precision-risky SOFT types; an allowlist entry that would suppress a hard-
+// block type is ignored and the detection still fires. This guard lives in core
+// (not trusted to config) so the invariant holds for every caller.
+export function applyPrecisionControls(detections, { minConfidence = 0, allowlist = null } = {}) {
+  const kept = [];
+  const suppressedByType = {};
+  const droppedByType = {};
+  let suppressedCount = 0;
+  let droppedCount = 0;
+
+  for (const detection of detections) {
+    const hardBlock = HARD_BLOCK_TYPES.has(detection.type);
+    // Allowlist suppression first (an operator-declared FP exception), but never
+    // for a hard-block type.
+    if (!hardBlock && isAllowlisted(detection, allowlist)) {
+      suppressedByType[detection.type] = (suppressedByType[detection.type] ?? 0) + 1;
+      suppressedCount += 1;
+      continue;
+    }
+    // minConfidence drop — only for soft types. A low-confidence hard-block
+    // detection (e.g. a card at confidence 0.75) is kept and acted on.
+    if (!hardBlock && Number.isFinite(detection.confidence) && detection.confidence < minConfidence) {
+      droppedByType[detection.type] = (droppedByType[detection.type] ?? 0) + 1;
+      droppedCount += 1;
+      continue;
+    }
+    kept.push(detection);
+  }
+
+  return {
+    detections: kept,
+    precisionAudit: { suppressedCount, suppressedByType, droppedCount, droppedByType }
+  };
 }
 
 async function transformPayload(payload, detections, decisions, { context, cryptoProvider, tokenVault, enforced, issuedTokens = null }) {
@@ -424,7 +551,7 @@ async function replacementFor(segment, detection, decision, { context, cryptoPro
   }
 }
 
-function buildAuditEvent({ context, mode, enforced, blocked, payload, detections, decisions }) {
+function buildAuditEvent({ context, mode, enforced, blocked, payload, detections, decisions, precisionAudit = null }) {
   return {
     // Reader-facing audit-event schema version (frozen as part of the 1.0 API
     // contract — see docs/current/api-stability.md). Additive-only: a new field
@@ -433,6 +560,14 @@ function buildAuditEvent({ context, mode, enforced, blocked, payload, detections
     // and so is self-consistent for hash-chain verification of new events.
     schemaVersion: "1",
     id: randomUUID(),
+    // Per-REQUEST correlation id (WS4-A). Additive top-level field: the proxy
+    // generates one randomUUID() per request and threads it into the protect
+    // context, so the request- and response-direction events of ONE request
+    // share it (and it appears in the structured error log for the same request).
+    // It is null when no context.correlationId is set, preserving the existing
+    // non-proxy protectJson() behavior and keeping the api-contract subset green.
+    // It is a UUID — never a payload/identity/PII value.
+    correlationId: context.correlationId ?? null,
     timestamp: new Date().toISOString(),
     protocol: context.protocol ?? "custom",
     operation: context.operation ?? "protect",
@@ -463,7 +598,7 @@ function buildAuditEvent({ context, mode, enforced, blocked, payload, detections
       action: decisions[index]?.action ?? "unknown",
       enforced
     })),
-    summary: summarize(detections, decisions)
+    summary: summarize(detections, decisions, precisionAudit)
   };
 }
 

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