haechi 1.2.0 → 1.3.0

package/packages/filter/index.mjs

@@ -1,10 +1,51 @@
+import { isUtf8 } from "node:buffer";
+
 // 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"]);
+//
+// Hard-block types are sensitive AND have a STRONG enough anchor that a match is
+// effectively a true positive by construction, so the precision dials
+// (filters.minConfidence / filters.allowlist) can never suppress them:
+//   - kr_rrn / card        — checksum + constrained format
+//   - fr_nir (mod-97 over a long structured 15-digit run) and es_dni (mod-23 plus
+//     a required check LETTER suffix) — a random same-shaped value almost never
+//     passes, and the shapes are rare in ordinary payloads.
+//   - it_codice_fiscale — a 16-char MIXED alpha+digit shape with a mod-26 check
+//     CHARACTER. The non-numeric structural anchor (the rigid letter/digit layout)
+//     makes a benign 16-char `[A-Z]{6}\d{2}[A-Z]…` run in an ordinary payload
+//     implausible (measured collision ~3.8% over an already-rare shape), so a match
+//     is effectively a true positive.
+//   - sg_nric — a LETTER prefix ([STFGM]) + 7 digits + a CHECK LETTER. Two
+//     non-numeric anchors (prefix letter + checksum letter) over a rare shape
+//     (measured collision ~3.9% over the prefix+letter shape) make a benign FP
+//     implausible. Both anchored, un-allowlistable.
+// DELIBERATELY DIAL-ELIGIBLE (NOT hard-block) — bare-digit runs whose only guard is
+// a single numeric checksum over a COMMON digit length, so a benign id/counter FP is
+// plausible and the operator needs the allowlist/minConfidence escape hatch (the
+// jp_mynumber precedent). They still detect + (per profile) block by default:
+//   - jp_mynumber — a bare 12-digit run + a SINGLE mod-11 check digit (measured
+//     ~9% of random 12-digit numbers pass), and 12-digit ids/counters are common.
+//   - uk_nino — NO checksum exists (format + invalid-prefix exclusions only), the
+//     largest FP surface.
+//   - in_aadhaar — a bare 12-digit run + the Verhoeff checksum (measured ~9.9% of
+//     random 12-digit runs pass, the same order as jp_mynumber's mod-11). Aadhaar
+//     is extremely sensitive, but Verhoeff over the COMMON 12-digit shape is exactly
+//     the jp_mynumber footgun (a 12-digit id/counter is common), so it stays
+//     allowlist-clearable rather than un-suppressable.
+//   - de_steuer_id — a bare 11-digit run + ISO 7064 MOD 11,10 plus a structural
+//     "exactly one repeated digit" test. The combined guard is strong (measured
+//     ~0.37% collision), BUT there is NO non-numeric anchor and 11-digit ids are
+//     common in payloads, so per the jp_mynumber discipline (a bare-digit shape over
+//     a common length) it stays DIAL-ELIGIBLE so an operator can clear an 11-digit-id
+//     FP. It still detects + blocks by default.
+//   - nl_bsn — a bare 9-digit run + the "11-proef" weighted mod-11 (measured ~9.1%
+//     of random 9-digit runs pass). 9 bare digits is VERY common, so this is the
+//     clearest dial-eligible case.
+export const HARD_BLOCK_TYPES = new Set(["secret", "api_key", "kr_rrn", "card", "fr_nir", "es_dni", "it_codice_fiscale", "sg_nric"]);
 
 const DEFAULT_RULES = [
   {
@@ -94,6 +135,76 @@ const DEFAULT_RULES = [
     flags: "g",
     confidence: 0.9
   },
+  {
+    // Anthropic API key: `sk-ant-` + a long body. Ordered BEFORE the OpenAI rule
+    // below so a Claude key is attributed to its own rule (both emit `secret`, so
+    // removeOverlaps collapsing the shared span to either is type-identical — the
+    // ordering is for ruleId attribution, not for the scored type). The HYPHEN
+    // after `sk` is load-bearing: it keeps this OFF the underscore-based Stripe/
+    // OpenAI-platform `sk_` rule (openai-like-key, `api_key`), so the two never
+    // collide on the same span.
+    id: "anthropic-api-key",
+    type: "secret",
+    pattern: "\\bsk-ant-[A-Za-z0-9_-]{16,}\\b",
+    flags: "g",
+    confidence: 0.95
+  },
+  {
+    // OpenAI API key: `sk-` (and project keys `sk-proj-`) + a long base62-ish
+    // body. The HYPHEN is the disambiguator from Stripe/OpenAI-platform `sk_`
+    // (underscore — handled by openai-like-key as `api_key`); this rule never
+    // matches an underscore form, so the two prefixes do not overlap. A >=20-char
+    // body keeps a bare `sk-foo` slug from firing. The Anthropic `sk-ant-` rule
+    // above is a stricter sibling that runs first.
+    id: "openai-api-key",
+    type: "secret",
+    pattern: "\\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\\b",
+    flags: "g",
+    confidence: 0.9
+  },
+  {
+    // Google OAuth client secret: anchored `GOCSPX-` + exactly 28 chars from the
+    // URL-safe alphabet. Fixed prefix + fixed length = high precision (this is the
+    // OAuth client secret, distinct from the `AIza` API key above).
+    id: "google-oauth-client-secret",
+    type: "secret",
+    pattern: "\\bGOCSPX-[A-Za-z0-9_-]{28}\\b",
+    flags: "g",
+    confidence: 0.95
+  },
+  {
+    // SendGrid API key: `SG.` + 22 URL-safe chars + `.` + 43 URL-safe chars. The
+    // two fixed-length dotted segments after the `SG.` prefix are what make this
+    // high-precision — a bare `SG.`-prefixed string of the wrong shape is rejected.
+    id: "sendgrid-api-key",
+    type: "api_key",
+    pattern: "\\bSG\\.[A-Za-z0-9_-]{22}\\.[A-Za-z0-9_-]{43}\\b",
+    flags: "g",
+    confidence: 0.95
+  },
+  {
+    // Twilio Account SID (AC…) / API Key SID (SK…): the fixed `AC`/`SK` prefix +
+    // EXACTLY 32 HEX chars. The hex-only body (not base62) is the precision guard:
+    // a random alphanumeric run of the same length carries non-hex letters and is
+    // rejected, and the `SK` form does not collide with the underscore/hyphen
+    // `sk_`/`sk-` rules. Twilio's bare 32-hex AUTH TOKEN is deliberately NOT a
+    // standalone rule (a prefix-less 32-hex run is indistinguishable from an MD5
+    // hash / id) — it is caught via the `<key> = <value>` assignment vocabulary.
+    id: "twilio-sid",
+    type: "api_key",
+    pattern: "\\b(?:AC|SK)[0-9a-fA-F]{32}\\b",
+    flags: "g",
+    confidence: 0.9
+  },
+  {
+    // npm access token: anchored `npm_` + exactly 36 base62 chars. Fixed prefix +
+    // fixed length = high precision.
+    id: "npm-token",
+    type: "secret",
+    pattern: "\\bnpm_[A-Za-z0-9]{36}\\b",
+    flags: "g",
+    confidence: 0.95
+  },
   {
     // JWT: three dot-separated base64url segments where the FIRST starts with
     // `eyJ` — the base64 of `{"`, i.e. the opening of the JSON header. Anchoring
@@ -139,7 +250,12 @@ const DEFAULT_RULES = [
     // 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,}",
+    // `accountkey` catches the Azure Storage connection-string `AccountKey=<88-
+    // char base64>=` segment — an un-anchored 88-char base64 rule would false-fire
+    // on any blob, so the `AccountKey=` assignment context is the precision anchor.
+    // `auth[_-]?token` catches the Twilio auth token (a bare 32-hex run with no
+    // self-describing prefix) when it is leaked as a `<key> = <value>` pair.
+    pattern: "(?<=\\b(?:api[_-]?key|api[_-]?secret|secret[_-]?key|secret|aws[_-]?secret[_-]?access[_-]?key|client[_-]?secret|private[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|accountkey|token|password)\\s*[:=]\\s*['\\\"]?)[A-Za-z0-9._~+/-]{12,}",
     flags: "gi",
     confidence: 0.85
   },
@@ -166,6 +282,136 @@ const DEFAULT_RULES = [
     confidence: 0.9,
     validate: ibanValid
   },
+  {
+    // Japan My Number (個人番号): EXACTLY 12 digits with the official mod-11
+    // weighted check digit over the first 11. A bare 12-digit run is ambiguous
+    // (an id/timestamp), so jpMyNumberValid is the precision guard — only a run
+    // whose 12th digit equals the prescribed check digit fires. The leading/
+    // trailing boundaries (`(?<![\d-])`/`(?![\d-])`) stop the rule from matching
+    // a 12-digit window inside a longer digit/dashed run. NOT hard-block: a single
+    // mod-11 check digit only rejects ~10/11 of random 12-digit runs, and such
+    // runs are common (ids/counters), so a benign FP is plausible and the operator
+    // keeps the allowlist escape hatch (it still detects + blocks by default).
+    id: "jp-mynumber",
+    type: "jp_mynumber",
+    pattern: "(?<![\\d-])\\d{12}(?![\\d-])",
+    flags: "g",
+    confidence: 0.9,
+    validate: jpMyNumberValid
+  },
+  {
+    // France NIR / INSEE social-security: 15 chars where the department field may
+    // carry the Corsica `2A`/`2B` letters, validated by the control key
+    // `97 - (first13 mod 97) == last2` (Corsica 2A→19, 2B→18 before the mod).
+    // The control key is the precision guard — a wrong key is rejected. The
+    // department alpha is optional so the pure-numeric form also matches. Anchored
+    // on word boundaries; hard-block (checksummed).
+    id: "fr-nir",
+    type: "fr_nir",
+    pattern: "(?<![\\w-])[12]\\d{2}(?:0[1-9]|1[0-2]|20)(?:\\d{2}|2[AB])\\d{6}\\d{2}(?![\\w-])",
+    flags: "g",
+    confidence: 0.9,
+    validate: frNirValid
+  },
+  {
+    // Spain DNI/NIE: 8 digits (DNI) or a leading X/Y/Z + 7 digits (NIE) + a check
+    // letter from the mod-23 table (NIE maps X/Y/Z→0/1/2 before the mod). The
+    // check letter is the precision guard — a wrong letter is rejected. The
+    // letters that can never appear (I/O/U) are excluded from the suffix class so
+    // an ordinary `<8-digit><letter>` token rarely even reaches the validator.
+    // Hard-block (checksummed).
+    id: "es-dni-nie",
+    type: "es_dni",
+    pattern: "(?<![\\w-])[XYZ]?\\d{7,8}[A-HJ-NP-TV-Z](?![\\w-])",
+    flags: "gi",
+    confidence: 0.85,
+    validate: esDniValid
+  },
+  {
+    // Italy Codice Fiscale: 16 chars in the rigid layout
+    // [A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z] (surname, name, year, month-letter,
+    // day, place code, check character). The 16th char is the official check
+    // character: sum the odd/even-position table values over the first 15 chars
+    // and map (sum mod 26) to a letter. The mixed alpha+digit structure + the
+    // mod-26 check character are the precision guard. Hard-block (strong
+    // non-numeric anchor over a rare shape).
+    id: "it-codice-fiscale",
+    type: "it_codice_fiscale",
+    pattern: "(?<![A-Z0-9])[A-Z]{6}\\d{2}[A-Z]\\d{2}[A-Z]\\d{3}[A-Z](?![A-Z0-9])",
+    flags: "gi",
+    confidence: 0.9,
+    validate: itCodiceFiscaleValid
+  },
+  {
+    // Singapore NRIC/FIN: a series LETTER ([STFGM]) + 7 digits + a CHECK LETTER.
+    // The check letter is a weighted sum (weights 2,7,6,5,4,3,2) plus a per-prefix
+    // offset (T/G +4, M +3), mod 11, looked up in the per-series letter table. The
+    // prefix letter + check letter are the precision guard. Hard-block (two
+    // non-numeric anchors over a rare shape).
+    id: "sg-nric",
+    type: "sg_nric",
+    pattern: "(?<![A-Z0-9])[STFGMstfgm]\\d{7}[A-Za-z](?![A-Z0-9])",
+    flags: "g",
+    confidence: 0.9,
+    validate: sgNricValid
+  },
+  {
+    // India Aadhaar: 12 digits (never starting 0 or 1) with the Verhoeff checksum
+    // over all 12. A bare 12-digit run is ambiguous (an id/timestamp), so the
+    // Verhoeff check is the precision guard. NOT hard-block: Verhoeff over the
+    // COMMON 12-digit shape passes ~1/10 of random runs (the jp_mynumber footgun),
+    // so it stays dial-eligible (still detects + blocks by default). The leading/
+    // trailing boundaries stop the rule from matching a 12-digit window inside a
+    // longer digit/dashed run.
+    id: "in-aadhaar",
+    type: "in_aadhaar",
+    pattern: "(?<![\\d-])[2-9]\\d{11}(?![\\d-])",
+    flags: "g",
+    confidence: 0.85,
+    validate: inAadhaarValid
+  },
+  {
+    // Germany tax ID (Steuer-Identifikationsnummer): 11 digits with the ISO 7064
+    // MOD 11,10 check digit over the first 10, plus the structural rule that the
+    // first 10 digits contain exactly one repeated digit (one value appears 2 or 3
+    // times, the rest once). The combined guard is strong, but it is a BARE-DIGIT
+    // run with no non-numeric anchor over a common 11-digit length, so per the
+    // jp_mynumber discipline it stays dial-eligible (the operator can clear an
+    // 11-digit-id FP).
+    id: "de-steuer-id",
+    type: "de_steuer_id",
+    pattern: "(?<![\\d-])\\d{11}(?![\\d-])",
+    flags: "g",
+    confidence: 0.85,
+    validate: deSteuerIdValid
+  },
+  {
+    // Netherlands BSN (Burgerservicenummer): 9 digits validated by the "11-proef"
+    // weighted mod-11 (Σ digit_i · weight_i ≡ 0 mod 11, with the last weight -1).
+    // 9 bare digits is VERY common, so the 11-proef passes ~1/11 of random runs —
+    // the clearest dial-eligible case (still detects + blocks by default; the
+    // operator keeps the allowlist escape hatch).
+    id: "nl-bsn",
+    type: "nl_bsn",
+    pattern: "(?<![\\d-])\\d{9}(?![\\d-])",
+    flags: "g",
+    confidence: 0.8,
+    validate: nlBsnValid
+  },
+  {
+    // UK National Insurance Number: two prefix letters + 6 digits + a suffix
+    // A-D. There is NO checksum, so this is FORMAT-ONLY and stays OUT of
+    // HARD_BLOCK_TYPES (dial-eligible). The pattern bakes in the documented
+    // invalid-prefix exclusions: 1st letter never D/F/I/Q/U/V, 2nd letter never
+    // D/F/I/O/Q/U/V, and the disallowed pairs BG/GB/NK/KN/TN/NT/ZZ are rejected
+    // by ukNinoValid (a negative-set the regex can't express cleanly).
+    id: "uk-nino",
+    type: "uk_nino",
+    pattern: "(?<![\\w-])[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z]\\d{6}[A-D](?![\\w-])",
+    flags: "g",
+    confidence: 0.7,
+    validate: ukNinoValid
+  },
   {
     // 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.
@@ -232,8 +478,13 @@ const DEFAULT_RULES = [
   }
 ];
 
-export function createDefaultFilterEngine({ customRules = [] } = {}) {
+export function createDefaultFilterEngine({ customRules = [], decodeAndRescan = false } = {}) {
   const rules = DEFAULT_RULES.concat(customRules.map(normalizeCustomRule));
+  // The opt-in base64/percent decode-and-rescan pass (WS2d residual). Default OFF
+  // => byte-identical to prior behavior. Held in the engine CLOSURE, NOT threaded
+  // through the protect `context`: the request context is data and must not carry
+  // this control flag (it would pollute tokenize AAD / audit).
+  const decodeOptions = { decodeAndRescan: decodeAndRescan === true };
 
   return {
     id: "haechi.filter.default",
@@ -243,12 +494,32 @@ export function createDefaultFilterEngine({ customRules = [] } = {}) {
       networkEgress: false
     },
     async detect({ entries, context }) {
-      return entries.flatMap((entry) => detectEntry(entry, rules, context));
+      return entries.flatMap((entry) => detectEntry(entry, rules, context, decodeOptions));
     }
   };
 }
 
-export function detectEntry(entry, rules, context = {}) {
+export function detectEntry(entry, rules, context = {}, options = {}) {
+  const baseDetections = scanEntry(entry, rules, context);
+  // WS2d residual — opt-in (default OFF) base64/percent decode-and-rescan. After
+  // the normal NFKC scan above, if the flag is on, attempt to decode the leaf and
+  // rescan the decoded text. A decoded hit has NO valid offset in the encoded leaf
+  // (decoding remaps everything), so it fails closed to a WHOLE-LEAF detection of
+  // the original encoded leaf — and only fires for a validator-backed/hard-block
+  // hit so random base64 never false-positives. See decodeAndRescanEntry.
+  if (options?.decodeAndRescan === true) {
+    const decoded = decodeAndRescanEntry(entry, rules, context);
+    if (decoded.length > 0) {
+      return baseDetections.concat(decoded);
+    }
+  }
+  return baseDetections;
+}
+
+// The original per-leaf NFKC scan (WS2d), unchanged. Extracted from detectEntry so
+// the opt-in decode-and-rescan pass wraps it without touching the byte-identical
+// default path.
+function scanEntry(entry, rules, context = {}) {
   const detections = [];
   // On the RESPONSE direction, a bare JSON NUMBER leaf is inference-server
   // metadata (a nanosecond `*_duration`, a token count, a numeric id/timestamp) —
@@ -364,13 +635,19 @@ function scanForDetections(scanText, rules, context, markerSpans, entry, origina
 // 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) {
+function wholeLeafDetections(normalized, rules, context, entry, originalValue, ruleFilter = null) {
   const seenTypes = new Set();
   const detections = [];
   for (const rule of rules) {
     if (rule.direction && rule.direction !== context?.direction) {
       continue;
     }
+    // The decode-and-rescan caller passes a precision filter so only validator-
+    // backed / hard-block rules can fire on decoded text (random base64 guard).
+    // The Case-3 NFKC caller passes nothing → every rule is eligible (unchanged).
+    if (ruleFilter && !ruleFilter(rule)) {
+      continue;
+    }
     if (seenTypes.has(rule.type)) {
       continue;
     }
@@ -401,6 +678,132 @@ function wholeLeafDetections(normalized, rules, context, entry, originalValue) {
   return detections;
 }
 
+// WS2d residual — opt-in base64/percent decode-and-rescan (default OFF). An
+// always-on decode is false-positive-prone (random base64 decodes to bytes that
+// can shape-match a soft rule), so this is gated behind `filters.decodeAndRescan`
+// AND a precision guard: a decoded hit only fires when it is VALIDATOR-BACKED or a
+// HARD-BLOCK type (a Luhn-passing card, a checksum kr_rrn/us_ssn, an IBAN mod-97,
+// or a secret/api_key on its anchored rule). A decoded soft-type-without-validator
+// match (a bare phone-shaped run in random decoded bytes) does NOT fire — requiring
+// validators keeps precision ~100% (random base64 Luhn-passing as a 16-digit card
+// is astronomically unlikely).
+//
+// OFFSET HANDLING (fail closed): a detection found in the DECODED text has no valid
+// offset in the original encoded leaf (decoding remaps everything), so we emit a
+// WHOLE-LEAF detection per matched type (start:0, end:leaf.length, value: the whole
+// original encoded leaf) — exactly the WS2d Case-3 path. The transform then
+// redacts/blocks the entire encoded leaf. We never map a decoded offset back.
+function decodeAndRescanEntry(entry, rules, context) {
+  // Only string leaves carry an encoded value; a number/boolean leaf cannot be a
+  // base64/percent blob (and the response-direction number skip already applies in
+  // the base scan).
+  if (entry.kind === "number") {
+    return [];
+  }
+  const decoded = decodeLeaf(entry.value);
+  if (decoded === null) {
+    return [];
+  }
+  // Reuse the Case-3 whole-leaf path, but restricted to precision-eligible rules so
+  // random base64 never false-positives. `decoded` supplies the scan text; the
+  // recorded detection still spans the ORIGINAL encoded leaf (entry.value).
+  return wholeLeafDetections(decoded, rules, context, entry, entry.value, isDecodeEligibleRule);
+}
+
+// A decoded whole-leaf detection only fires for a "meaningful" hit: a hard-block
+// type (secret/api_key/kr_rrn/card) on its anchored rule, OR a checksum-validated
+// type. The `phone` type is excluded even though kr-phone carries a `validate`
+// helper — that helper is a trunk-prefix heuristic, not a checksum, so a phone-
+// shaped run in random decoded bytes must NOT fire (the spec's named exclusion).
+function isDecodeEligibleRule(rule) {
+  if (HARD_BLOCK_TYPES.has(rule.type)) {
+    return true;
+  }
+  return typeof rule.validate === "function" && rule.type !== "phone";
+}
+
+// Attempt to decode a string leaf to UTF-8 text, returning the decoded string or
+// null when the leaf does not look like (or does not cleanly round-trip as) an
+// encoded value. Two encodings, each precision-guarded so a benign value is skipped
+// rather than mis-decoded:
+//   - base64 / base64url: the leaf must LOOK like base64 (no spaces, the base64 or
+//     base64url alphabet, a valid length for that variant) within bounds, decode to
+//     VALID UTF-8, and RE-ENCODE back to exactly the leaf (rejects the bytes that
+//     Buffer.from leniently accepts but are not the canonical encoding of the leaf).
+//   - percent-encoding: only when the leaf actually contains a `%XX` escape;
+//     decodeURIComponent in a try/catch (a malformed escape → skip, never throws).
+// base64 is tried first (a `%`-bearing string is not base64), then percent.
+const DECODE_MIN_LEN = 16;
+const DECODE_MAX_LEN = 8192;
+const BASE64_STD = /^[A-Za-z0-9+/]+={0,2}$/;
+const BASE64_URL = /^[A-Za-z0-9_-]+$/;
+
+function decodeLeaf(value) {
+  if (typeof value !== "string" || value.length < DECODE_MIN_LEN || value.length > DECODE_MAX_LEN) {
+    return null;
+  }
+  const base64 = decodeBase64Leaf(value);
+  if (base64 !== null) {
+    return base64;
+  }
+  return decodePercentLeaf(value);
+}
+
+function decodeBase64Leaf(value) {
+  // Standard base64: length must be a multiple of 4. base64url: length mod 4 may be
+  // 0, 2, or 3 (1 is impossible for any byte run) and the alphabet is `-_` not `+/`.
+  // A `%` or whitespace disqualifies it (handled by the anchored alphabet regexes).
+  let encoding = null;
+  if (BASE64_STD.test(value) && value.length % 4 === 0) {
+    encoding = "base64";
+  } else if (BASE64_URL.test(value) && value.length % 4 !== 1) {
+    encoding = "base64url";
+  } else {
+    return null;
+  }
+  let bytes;
+  try {
+    bytes = Buffer.from(value, encoding);
+  } catch {
+    return null;
+  }
+  if (bytes.length === 0) {
+    return null;
+  }
+  // Round-trip guard: Buffer.from is lenient (it ignores stray chars / bad padding),
+  // so a non-canonical string can "decode". Re-encoding the bytes must reproduce the
+  // EXACT leaf — otherwise the leaf was not really this base64 value.
+  if (bytes.toString(encoding) !== value) {
+    return null;
+  }
+  // The decoded bytes must be valid UTF-8 text; a card/RRN/secret is text. Random
+  // base64 usually decodes to non-UTF-8 bytes, which we skip here (a cheap, strong
+  // false-positive filter before we even run the rules).
+  if (!isUtf8(bytes)) {
+    return null;
+  }
+  return bytes.toString("utf8");
+}
+
+function decodePercentLeaf(value) {
+  // Only attempt when there is an actual `%XX` escape — otherwise decodeURIComponent
+  // is a no-op and we would needlessly rescan an identical string.
+  if (!/%[0-9A-Fa-f]{2}/.test(value)) {
+    return null;
+  }
+  let decoded;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    // Malformed percent-escape (e.g. a bare `%` or `%zz`) → skip, never throw.
+    return null;
+  }
+  if (decoded === value) {
+    return null;
+  }
+  return decoded;
+}
+
 // 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-
@@ -581,3 +984,273 @@ function ibanValid(value) {
   }
   return remainder === 1;
 }
+
+// Japan My Number (個人番号) check digit. The official scheme: over the first 11
+// digits, P = 11 - (Σ n_i · Q_i mod 11), where n_i is the i-th digit FROM THE
+// RIGHT of the 11-digit prefix and Q_i = i+1 for 1≤i≤6, i-5 for 7≤i≤11. When the
+// remainder is 0 or 1 the check digit is 0. The 12th digit must equal P. This
+// check digit is the precision guarantee — a random 12-digit id passes only 1
+// time in 10, and the corpus hard-negative (a valid-shape, wrong-check value)
+// proves the rejection.
+function jpMyNumberValid(value) {
+  const digits = value.replace(/\D/g, "");
+  if (digits.length !== 12) {
+    return false;
+  }
+  let sum = 0;
+  for (let n = 1; n <= 11; n += 1) {
+    const digit = Number(digits[11 - n]);
+    const weight = n <= 6 ? n + 1 : n - 5;
+    sum += digit * weight;
+  }
+  const remainder = sum % 11;
+  const check = remainder <= 1 ? 0 : 11 - remainder;
+  return check === Number(digits[11]);
+}
+
+// France NIR / INSEE social-security control key. The first 13 chars are the
+// body (sex, birth year/month, department, commune, order); the last 2 are the
+// control key, which must equal `97 - (body mod 97)`. The Corsica department is
+// written 2A/2B; the official rule substitutes 2A→19 and 2B→18 in the body
+// BEFORE the mod (the rest of the body is numeric). The control key is the
+// precision guarantee — a wrong key is rejected (corpus hard-negative).
+function frNirValid(value) {
+  const compact = value.replace(/[\s.-]/g, "").toUpperCase();
+  if (!/^[12]\d{2}(?:\d{2}|0[1-9]|1[0-2]|20)(?:\d{2}|2[AB])\d{6}\d{2}$/.test(compact)) {
+    return false;
+  }
+  const bodyRaw = compact.slice(0, 13);
+  const control = Number(compact.slice(13));
+  // Corsica substitution: 2A→19, 2B→18 (only the department field can be alpha).
+  const body = bodyRaw.replace("2A", "19").replace("2B", "18");
+  if (!/^\d{13}$/.test(body)) {
+    return false;
+  }
+  let remainder = 0;
+  for (const char of body) {
+    remainder = (remainder * 10 + Number(char)) % 97;
+  }
+  const key = 97 - remainder;
+  return key === control;
+}
+
+// Spain DNI/NIE check letter (mod-23 table). DNI is 8 digits + a letter; NIE is
+// a leading X/Y/Z (mapped to 0/1/2) + 7 digits + a letter. The letter is
+// `table[number mod 23]` where table = "TRWAGMYFPDXBNJZSQVHLCKE". The letter is
+// the precision guarantee — a structurally valid but wrong letter is rejected
+// (corpus hard-negative).
+const ES_DNI_TABLE = "TRWAGMYFPDXBNJZSQVHLCKE";
+const ES_NIE_PREFIX = { X: "0", Y: "1", Z: "2" };
+function esDniValid(value) {
+  const compact = value.replace(/[\s-]/g, "").toUpperCase();
+  let body;
+  let letter;
+  if (/^\d{8}[A-Z]$/.test(compact)) {
+    body = compact.slice(0, 8);
+    letter = compact[8];
+  } else if (/^[XYZ]\d{7}[A-Z]$/.test(compact)) {
+    body = ES_NIE_PREFIX[compact[0]] + compact.slice(1, 8);
+    letter = compact[8];
+  } else {
+    return false;
+  }
+  return ES_DNI_TABLE[Number(body) % 23] === letter;
+}
+
+// Italy Codice Fiscale check character. Over the first 15 chars: odd positions
+// (1st, 3rd, … counting from 1) use the ODD table, even positions use the EVEN
+// table; sum the mapped values and the (sum mod 26)-th letter (A=0) must equal the
+// 16th char. The mixed alpha+digit structure + the mod-26 check character are the
+// precision guard — a structurally valid but wrong check char is rejected (corpus
+// hard-negative). Hard-block.
+const IT_CF_ODD = {
+  "0": 1, "1": 0, "2": 5, "3": 7, "4": 9, "5": 13, "6": 15, "7": 17, "8": 19, "9": 21,
+  A: 1, B: 0, C: 5, D: 7, E: 9, F: 13, G: 15, H: 17, I: 19, J: 21, K: 2, L: 4, M: 18, N: 20,
+  O: 11, P: 3, Q: 6, R: 8, S: 12, T: 14, U: 16, V: 10, W: 22, X: 25, Y: 24, Z: 23
+};
+const IT_CF_EVEN = {
+  "0": 0, "1": 1, "2": 2, "3": 3, "4": 4, "5": 5, "6": 6, "7": 7, "8": 8, "9": 9,
+  A: 0, B: 1, C: 2, D: 3, E: 4, F: 5, G: 6, H: 7, I: 8, J: 9, K: 10, L: 11, M: 12, N: 13,
+  O: 14, P: 15, Q: 16, R: 17, S: 18, T: 19, U: 20, V: 21, W: 22, X: 23, Y: 24, Z: 25
+};
+const IT_CF_REMAINDER = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function itCodiceFiscaleValid(value) {
+  const cf = value.replace(/\s/g, "").toUpperCase();
+  if (!/^[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]$/.test(cf)) {
+    return false;
+  }
+  let sum = 0;
+  for (let index = 0; index < 15; index += 1) {
+    const char = cf[index];
+    // Position 1 (index 0) is ODD; alternate from there.
+    sum += index % 2 === 0 ? IT_CF_ODD[char] : IT_CF_EVEN[char];
+  }
+  return IT_CF_REMAINDER[sum % 26] === cf[15];
+}
+
+// Singapore NRIC/FIN check letter. Weighted sum (weights 2,7,6,5,4,3,2) over the
+// 7 digits, plus a per-prefix offset (T/G +4, M +3), mod 11, mapped through the
+// per-series letter table. S/T (citizen/PR), F/G (foreigner FIN), and M (post-2022
+// FIN) each have their own table. The prefix letter + check letter are the
+// precision guard — a wrong letter is rejected (corpus hard-negative). Hard-block.
+const SG_NRIC_WEIGHTS = [2, 7, 6, 5, 4, 3, 2];
+const SG_NRIC_TABLE_ST = ["J", "Z", "I", "H", "G", "F", "E", "D", "C", "B", "A"];
+const SG_NRIC_TABLE_FG = ["X", "W", "U", "T", "R", "Q", "P", "N", "M", "L", "K"];
+const SG_NRIC_TABLE_M = ["K", "L", "J", "N", "P", "Q", "R", "T", "U", "W", "X"];
+function sgNricValid(value) {
+  const v = value.replace(/\s/g, "").toUpperCase();
+  if (!/^[STFGM]\d{7}[A-Z]$/.test(v)) {
+    return false;
+  }
+  const prefix = v[0];
+  let sum = 0;
+  for (let index = 0; index < 7; index += 1) {
+    sum += Number(v[index + 1]) * SG_NRIC_WEIGHTS[index];
+  }
+  if (prefix === "T" || prefix === "G") {
+    sum += 4;
+  } else if (prefix === "M") {
+    sum += 3;
+  }
+  const remainder = sum % 11;
+  let table;
+  if (prefix === "S" || prefix === "T") {
+    table = SG_NRIC_TABLE_ST;
+  } else if (prefix === "F" || prefix === "G") {
+    table = SG_NRIC_TABLE_FG;
+  } else {
+    table = SG_NRIC_TABLE_M;
+  }
+  return table[remainder] === v[8];
+}
+
+// India Aadhaar Verhoeff checksum. The Verhoeff scheme runs the dihedral-group
+// multiplication (VERHOEFF_D) over each digit permuted by position (VERHOEFF_P)
+// from the right; the running value must be 0 for a valid full number. Aadhaar is
+// 12 digits and never starts 0 or 1. The Verhoeff check is the precision guard — a
+// wrong check digit is rejected (corpus hard-negative). Dial-eligible: Verhoeff
+// over a common 12-digit shape passes ~1/10 of random runs (the jp_mynumber
+// footgun), so it stays allowlist-clearable.
+const VERHOEFF_D = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+  [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+  [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+  [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
+  [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+  [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
+  [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+  [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+  [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
+];
+const VERHOEFF_P = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+  [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+  [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+  [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
+  [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+  [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
+  [7, 0, 4, 6, 9, 1, 3, 2, 5, 8]
+];
+function verhoeffValid(digits) {
+  let check = 0;
+  const reversed = digits.split("").reverse();
+  for (let index = 0; index < reversed.length; index += 1) {
+    check = VERHOEFF_D[check][VERHOEFF_P[index % 8][Number(reversed[index])]];
+  }
+  return check === 0;
+}
+function inAadhaarValid(value) {
+  const digits = value.replace(/[\s-]/g, "");
+  if (!/^[2-9]\d{11}$/.test(digits)) {
+    return false;
+  }
+  return verhoeffValid(digits);
+}
+
+// Germany tax ID (Steuer-Identifikationsnummer). Two guards: (1) the structural
+// rule that the first 10 digits contain exactly one repeated digit (one value
+// appears 2 or 3 times, the rest once), and (2) the ISO 7064 MOD 11,10 check digit
+// over the first 10 must equal the 11th. Dial-eligible: a bare 11-digit run with no
+// non-numeric anchor over a common length (the jp_mynumber discipline), even though
+// the combined guard is strong.
+function deSteuerIdStructural(first10) {
+  const counts = new Map();
+  for (const char of first10) {
+    counts.set(char, (counts.get(char) ?? 0) + 1);
+  }
+  const repeats = [...counts.values()].filter((count) => count >= 2);
+  // Exactly one digit repeats, and it repeats 2 or 3 times (never more).
+  return repeats.length === 1 && repeats[0] <= 3;
+}
+function deSteuerIdCheckDigit(first10) {
+  let product = 10;
+  for (let index = 0; index < 10; index += 1) {
+    let sum = (Number(first10[index]) + product) % 10;
+    if (sum === 0) {
+      sum = 10;
+    }
+    product = (sum * 2) % 11;
+  }
+  let check = 11 - product;
+  if (check === 10) {
+    check = 0;
+  }
+  return check;
+}
+function deSteuerIdValid(value) {
+  const digits = value.replace(/[\s/]/g, "");
+  if (!/^\d{11}$/.test(digits)) {
+    return false;
+  }
+  const first10 = digits.slice(0, 10);
+  if (!deSteuerIdStructural(first10)) {
+    return false;
+  }
+  return deSteuerIdCheckDigit(first10) === Number(digits[10]);
+}
+
+// Netherlands BSN "11-proef": Σ (digit_i · weight_i) ≡ 0 mod 11 over the 9 digits,
+// where the weights run 9,8,…,2 for the first eight and -1 for the last. The
+// all-zero number is rejected. Dial-eligible: 9 bare digits is very common, so the
+// 11-proef passes ~1/11 of random runs (the clearest jp_mynumber-style footgun).
+function nlBsnValid(value) {
+  const digits = value.replace(/[\s.]/g, "");
+  if (!/^\d{9}$/.test(digits)) {
+    return false;
+  }
+  if (/^0{9}$/.test(digits)) {
+    return false;
+  }
+  let sum = 0;
+  for (let index = 0; index < 8; index += 1) {
+    sum += Number(digits[index]) * (9 - index);
+  }
+  sum += Number(digits[8]) * -1;
+  return sum % 11 === 0;
+}
+
+// UK National Insurance Number — FORMAT-ONLY (no checksum exists), which is why
+// uk_nino stays OUT of HARD_BLOCK_TYPES (dial-eligible). The regex already
+// excludes the disallowed individual letters; this validator rejects the
+// documented invalid PREFIX PAIRS (BG, GB, NK, KN, TN, NT, ZZ) that the regex
+// cannot express as a negative set, plus the `O`-as-second-letter case (belt-and-
+// braces with the regex class). The administrative `TN`/`NT` and the temporary
+// `OO`/the suspended `BG` etc. are never issued, so excluding them lifts precision.
+const UK_NINO_INVALID_PREFIXES = new Set(["BG", "GB", "NK", "KN", "TN", "NT", "ZZ"]);
+function ukNinoValid(value) {
+  const compact = value.replace(/\s/g, "").toUpperCase();
+  if (!/^[A-Z]{2}\d{6}[A-D]$/.test(compact)) {
+    return false;
+  }
+  const prefix = compact.slice(0, 2);
+  if (UK_NINO_INVALID_PREFIXES.has(prefix)) {
+    return false;
+  }
+  // First letter never D/F/I/Q/U/V; second letter never D/F/I/O/Q/U/V.
+  if (/[DFIQUV]/.test(prefix[0]) || /[DFIOQUV]/.test(prefix[1])) {
+    return false;
+  }
+  return true;
+}