@discretion/core 0.1.0

package/src/detect/detectors/natid/seasia.ts

@@ -0,0 +1,174 @@
+/**
+ * South and Southeast Asia: Pakistan, Bangladesh, Malaysia, Indonesia,
+ * Thailand, Vietnam, Philippines.
+ *
+ * Only Thailand's national ID carries a public checksum (weights 13..2,
+ * check = (11 − sum mod 11) mod 10) → HIGH. The rest validate published
+ * STRUCTURE — hyphenation, date fields, province/place codes — at MEDIUM,
+ * each stating what is and is not checkable:
+ *  • PK CNIC 5-7-1 hyphenated; final digit encodes gender.
+ *  • BD NID: only the 17-digit form (leading birth year) is claimed; the
+ *    10- and 13-digit forms are bare digit runs and are left to Stage 3.
+ *  • MY MyKad YYMMDD-PB-###G with the place-of-birth code gate (00 and
+ *    17–20 unassigned).
+ *  • ID NIK: province 11–94, DDMMYY with the +40 female day offset.
+ *  • VN CCCD: twelve digits, province 001–096, century digit.
+ *  • PH PhilSys PCN: sixteen digits in 4-4-4-4 only.
+ */
+
+import { toDigits, weightedModBy } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+registerDetector({
+  id: 'national-id-pk-cnic',
+  entityType: 'NATIONAL_ID',
+  regions: ['PK'],
+  pattern: /\b([1-9]\d{4})-(\d{7})-(\d)\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Pakistani CNIC in its hyphenated writing (no public checksum).',
+  validate(ctx): ValidationResult {
+    return valid({
+      canonical: `${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}`,
+      metadata: { scheme: 'cnic', country: 'PK', male: Number(ctx.match[3]) % 2 === 1 },
+      validator: 'cnic-structure',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-bd-nid',
+  entityType: 'NATIONAL_ID',
+  regions: ['BD'],
+  pattern: /\b(19\d{2}|20\d{2})\d{13}\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Bangladeshi 17-digit NID (birth-year prefix); shorter forms left to context.',
+  validate(ctx): ValidationResult {
+    const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+    if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer number');
+    const after = ctx.text.slice(ctx.end, ctx.end + 2);
+    if (/^\d/.test(after)) return invalid('fragment of a longer number');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'nid', country: 'BD' },
+      validator: 'nid-structure',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-my-mykad',
+  entityType: 'NATIONAL_ID',
+  regions: ['MY'],
+  pattern: /\b(\d{2})(\d{2})(\d{2})-(\d{2})-(\d{4})\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Malaysian MyKad: birth date plus place-of-birth code gate (no checksum).',
+  validate(ctx): ValidationResult {
+    const month = Number(ctx.match[2]);
+    if (month < 1 || month > 12) return invalid('month out of range');
+    const day = Number(ctx.match[3]);
+    if (day < 1 || day > 31) return invalid('day out of range');
+    const pb = Number(ctx.match[4]);
+    if (pb === 0 || (pb >= 17 && pb <= 20)) return invalid('unassigned place-of-birth code');
+    return valid({
+      canonical: ctx.match[0].replace(/-/g, ''),
+      metadata: { scheme: 'mykad', country: 'MY' },
+      validator: 'mykad-structure',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-id-nik',
+  entityType: 'NATIONAL_ID',
+  regions: ['ID'],
+  pattern: /\b([1-9]\d)(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{4})\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Indonesian NIK: province and date structure with the +40 female offset.',
+  validate(ctx): ValidationResult {
+    const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+    if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer number');
+    const after = ctx.text.slice(ctx.end, ctx.end + 2);
+    if (/^\d/.test(after)) return invalid('fragment of a longer number');
+
+    const province = Number(ctx.match[1]);
+    if (province < 11 || province > 94) return invalid('province out of range');
+    const day = Number(ctx.match[4]);
+    const female = day >= 41 && day <= 71;
+    if (!(day >= 1 && day <= 31) && !female) return invalid('day out of range');
+    const month = Number(ctx.match[5]);
+    if (month < 1 || month > 12) return invalid('month out of range');
+    if (ctx.match[7] === '0000') return invalid('serial 0000 never issued');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'nik', country: 'ID', female },
+      validator: 'nik-structure',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-th',
+  entityType: 'NATIONAL_ID',
+  regions: ['TH'],
+  pattern: /\b([1-8])[ -]?(\d{4})[ -]?(\d{5})[ -]?(\d{2})[ -]?(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Thai National ID with the descending-weight mod-11 check.',
+  validate(ctx): ValidationResult {
+    const digits = toDigits(`${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}${ctx.match[4]}${ctx.match[5]}`)!;
+    const remainder = weightedModBy(digits.slice(0, 12), (i) => 13 - i, 11)!;
+    const check = (11 - remainder) % 10;
+    if (check !== digits[12]) return invalid('Thai ID check failed');
+    return valid({
+      canonical: digits.join(''),
+      metadata: { scheme: 'thai-id', country: 'TH' },
+      validator: 'thai-mod11',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-vn-cccd',
+  entityType: 'NATIONAL_ID',
+  regions: ['VN'],
+  pattern: /\b(0\d{2})(\d)(\d{2})(\d{6})\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Vietnamese CCCD: province 001-096 and century digit (no public checksum).',
+  validate(ctx): ValidationResult {
+    const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+    if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer number');
+    const after = ctx.text.slice(ctx.end, ctx.end + 2);
+    if (/^\d/.test(after)) return invalid('fragment of a longer number');
+
+    const province = Number(ctx.match[1]);
+    if (province < 1 || province > 96) return invalid('province out of range');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'cccd', country: 'VN' },
+      validator: 'cccd-structure',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-ph-psn',
+  entityType: 'NATIONAL_ID',
+  regions: ['PH'],
+  pattern: /\b(\d{4})-(\d{4})-(\d{4})-(\d{4})\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Philippine PhilSys card number in its 4-4-4-4 writing (no public checksum).',
+  validate(ctx): ValidationResult {
+    const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+    if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer number');
+    const after = ctx.text.slice(ctx.end, ctx.end + 2);
+    if (/^\d/.test(after) || /^-\d/.test(after)) return invalid('fragment of a longer number');
+    const all = ctx.match[0].replace(/-/g, '');
+    if (/^(.)\1+$/.test(all)) return invalid('repdigit');
+    return valid({
+      canonical: all,
+      metadata: { scheme: 'psn', country: 'PH' },
+      validator: 'psn-structure',
+    });
+  },
+});

package/src/detect/detectors/natid/sg.ts

@@ -0,0 +1,39 @@
+/**
+ * Singapore: NRIC/FIN — S/T/F/G/M + seven digits + check letter.
+ * Weights 2,7,6,5,4,3,2; T and G add 4 to the sum, M adds 3; the letter
+ * comes from the series table: S/T → JZIHGFEDCBA, F/G → XWUTRQPNMLK,
+ * M → KLJNPQRTUWX, indexed by sum mod 11.
+ */
+
+import { toDigits, weightedSum } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+const NRIC_WEIGHTS = [2, 7, 6, 5, 4, 3, 2];
+const TABLE_ST = 'JZIHGFEDCBA';
+const TABLE_FG = 'XWUTRQPNMLK';
+const TABLE_M = 'KLJNPQRTUWX';
+
+registerDetector({
+  id: 'national-id-sg-nric',
+  entityType: 'NATIONAL_ID',
+  regions: ['SG'],
+  pattern: /\b([STFGM])(\d{7})([A-Z])\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Singaporean NRIC/FIN with the series-offset check letter.',
+  validate(ctx): ValidationResult {
+    const series = ctx.match[1]!;
+    let sum = weightedSum(toDigits(ctx.match[2]!)!, NRIC_WEIGHTS)!;
+    if (series === 'T' || series === 'G') sum += 4;
+    if (series === 'M') sum += 3;
+    const index = sum % 11;
+    const table = series === 'S' || series === 'T' ? TABLE_ST : series === 'M' ? TABLE_M : TABLE_FG;
+    if (ctx.match[3] !== table[index]) return invalid('check letter failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'nric', country: 'SG', series },
+      validator: 'nric-mod11',
+    });
+  },
+});

package/src/detect/detectors/natid/si.ts

@@ -0,0 +1,42 @@
+/**
+ * Slovenia: EMŠO — thirteen digits (shared with the other ex-Yugoslav
+ * unique master citizen numbers): DDMMYYY RR NNN C, check with weights
+ * 7,6,5,4,3,2 repeated over the twelve payload digits, k = 11 − (sum mod
+ * 11), with k ≥ 10 folding to 0.
+ */
+
+import { toDigits, cyclicWeightedMod } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+registerDetector({
+  id: 'national-id-si-emso',
+  entityType: 'NATIONAL_ID',
+  regions: ['SI'],
+  pattern: /\b(\d{2})(\d{2})(\d{3})(\d{2})(\d{3})(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Slovenian EMŠO with the 7-6-5-4-3-2 cyclic mod-11 check.',
+  validate(ctx): ValidationResult {
+    const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+    if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer number');
+    const after = ctx.text.slice(ctx.end, ctx.end + 2);
+    if (/^\d/.test(after) || /^-\d/.test(after)) return invalid('fragment of a longer number');
+
+    const day = Number(ctx.match[1]);
+    if (day < 1 || day > 31) return invalid('day out of range');
+    const month = Number(ctx.match[2]);
+    if (month < 1 || month > 12) return invalid('month out of range');
+
+    const digits = toDigits(ctx.match[0])!;
+    const sum = cyclicWeightedMod(digits.slice(0, 12), [7, 6, 5, 4, 3, 2], 11)!;
+    let k = 11 - sum;
+    if (k >= 10) k = 0;
+    if (k !== digits[12]) return invalid('EMŠO checksum failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'emso', country: 'SI' },
+      validator: 'emso-mod11',
+    });
+  },
+});

package/src/detect/detectors/natid/tr.ts

@@ -0,0 +1,76 @@
+/**
+ * Turkey: TCKN and VKN.
+ *
+ * TCKN — SPEC.md spells the algorithm out verbatim: eleven digits, first
+ * nonzero, d10 = ((d1+d3+d5+d7+d9)·7 − (d2+d4+d6+d8)) mod 10, and
+ * d11 = (d1+…+d10) mod 10. Both are enforced exactly.
+ *
+ * VKN (tax number) — ten digits with the published transform: for each of
+ * the first nine digits (1-based position p), tmp = (d + 10 − p) mod 10;
+ * contribute tmp === 9 ? 9 : (tmp · 2^(10−p)) mod 9; the check digit is
+ * (10 − sum mod 10) mod 10.
+ */
+
+import { toDigits } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function guard(ctx: ValidationContext): string | null {
+  const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+  if (/[\d-]/.test(before ?? '')) return 'fragment of a longer number';
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^\d/.test(after) || /^-\d/.test(after)) return 'fragment of a longer number';
+  return null;
+}
+
+registerDetector({
+  id: 'national-id-tr-tckn',
+  entityType: 'NATIONAL_ID',
+  regions: ['TR'],
+  pattern: /\b[1-9]\d{10}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Turkish TCKN with both check digits per the published algorithm.',
+  validate(ctx): ValidationResult {
+    const g = guard(ctx);
+    if (g !== null) return invalid(g);
+    const d = toDigits(ctx.match[0])!;
+    const odd = d[0]! + d[2]! + d[4]! + d[6]! + d[8]!;
+    const even = d[1]! + d[3]! + d[5]! + d[7]!;
+    const d10 = (((odd * 7 - even) % 10) + 10) % 10;
+    if (d10 !== d[9]) return invalid('tenth-digit check failed');
+    const d11 = d.slice(0, 10).reduce((a, b) => a + b, 0) % 10;
+    if (d11 !== d[10]) return invalid('eleventh-digit check failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'tckn', country: 'TR' },
+      validator: 'tckn-dual-check',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-tr-vkn',
+  entityType: 'TAX_ID',
+  regions: ['TR'],
+  pattern: /\b\d{10}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Turkish VKN tax numbers with the published transform check.',
+  validate(ctx): ValidationResult {
+    const g = guard(ctx);
+    if (g !== null) return invalid(g);
+    const d = toDigits(ctx.match[0])!;
+    let sum = 0;
+    for (let p = 1; p <= 9; p++) {
+      const tmp = (d[p - 1]! + 10 - p) % 10;
+      sum += tmp === 9 ? 9 : (tmp * 2 ** (10 - p)) % 9;
+    }
+    const check = (10 - (sum % 10)) % 10;
+    if (check !== d[9]) return invalid('VKN check digit failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'vkn', country: 'TR' },
+      validator: 'vkn-transform',
+    });
+  },
+});

package/src/detect/detectors/natid/tw.ts

@@ -0,0 +1,41 @@
+/**
+ * Taiwan: National ID — a region letter, a gender digit (1/2; 8/9 for the
+ * new resident-certificate format), then eight digits. The letter maps to a
+ * two-digit code via the published table; tens digit ×1, ones ×9, then the
+ * eight payload digits weighted 8..1 (wait — 8,7,6,5,4,3,2,1) plus the
+ * check digit ×1 must sum ≡ 0 (mod 10).
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+/** The published letter→code table (not alphabetical for I, O, W–Z). */
+const LETTER_CODES: Readonly<Record<string, number>> = {
+  A: 10, B: 11, C: 12, D: 13, E: 14, F: 15, G: 16, H: 17, I: 34, J: 18,
+  K: 19, L: 20, M: 21, N: 22, O: 35, P: 23, Q: 24, R: 25, S: 26, T: 27,
+  U: 28, V: 29, W: 32, X: 30, Y: 31, Z: 33,
+};
+
+registerDetector({
+  id: 'national-id-tw',
+  entityType: 'NATIONAL_ID',
+  regions: ['TW'],
+  pattern: /\b([A-Z])([1289])(\d{7})(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Taiwanese National ID with the letter-code mod-10 check.',
+  validate(ctx): ValidationResult {
+    const code = LETTER_CODES[ctx.match[1]!]!;
+    const digits = `${ctx.match[2]}${ctx.match[3]}`;
+    let sum = Math.floor(code / 10) + (code % 10) * 9;
+    const weights = [8, 7, 6, 5, 4, 3, 2, 1];
+    for (let i = 0; i < 8; i++) sum += Number(digits[i]) * weights[i]!;
+    sum += Number(ctx.match[4]);
+    if (sum % 10 !== 0) return invalid('mod-10 check failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'tw-id', country: 'TW' },
+      validator: 'tw-mod10',
+    });
+  },
+});

package/src/detect/detectors/natid/ua.ts

@@ -0,0 +1,38 @@
+/**
+ * Ukraine: RNOKPP (РНОКПП, the individual tax number) — ten digits, weights
+ * −1,5,7,9,4,6,10,5,7 over the first nine, check = (sum mod 11) mod 10.
+ * The negative first weight is genuine, not a transcription error.
+ */
+
+import { toDigits } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+const RNOKPP_WEIGHTS = [-1, 5, 7, 9, 4, 6, 10, 5, 7];
+
+registerDetector({
+  id: 'national-id-ua-rnokpp',
+  entityType: 'TAX_ID',
+  regions: ['UA'],
+  pattern: /\b\d{10}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Ukrainian RNOKPP with its negative-first-weight mod-11 check.',
+  validate(ctx): ValidationResult {
+    const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+    if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer number');
+    const after = ctx.text.slice(ctx.end, ctx.end + 2);
+    if (/^\d/.test(after) || /^-\d/.test(after)) return invalid('fragment of a longer number');
+
+    const d = toDigits(ctx.match[0])!;
+    let sum = 0;
+    for (let i = 0; i < 9; i++) sum += d[i]! * RNOKPP_WEIGHTS[i]!;
+    const check = ((sum % 11) + 11) % 11 % 10;
+    if (check !== d[9]) return invalid('RNOKPP check failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'rnokpp', country: 'UA' },
+      validator: 'rnokpp-mod11',
+    });
+  },
+});

package/src/detect/detectors/natid/us.ts

@@ -0,0 +1,118 @@
+/**
+ * United States: SSN, ITIN, EIN.
+ *
+ * None of the three carries a checksum, so per SPEC.md the validators are
+ * the published ISSUANCE RULES and confidence stays MEDIUM:
+ *  • SSN — area not 000/666/900–999, group not 00, serial not 0000. Only
+ *    the delimited 3-2-4 writing is matched: a bare nine-digit run is any
+ *    number in the world (and the ABA detector owns the checksummed ones).
+ *    The famous Woolworth wallet-card number 078-05-1120 and the
+ *    advertising range 987-65-432x are detected but non-sensitive.
+ *  • ITIN — SSN shape, area 900–999 with the IRS-assigned group ranges.
+ *  • EIN — XX-XXXXXXX with a real IRS campus/e-file prefix.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+const KNOWN_TEST_SSNS = new Set(['078051120', '219099999']);
+
+function fragmentGuard(ctx: ValidationContext): string | null {
+  const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+  if (/[\d-]/.test(before ?? '')) return 'fragment of a longer number';
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^\d/.test(after) || /^-\d/.test(after)) return 'fragment of a longer number';
+  return null;
+}
+
+registerDetector({
+  id: 'national-id-us-ssn',
+  entityType: 'NATIONAL_ID',
+  regions: ['US'],
+  pattern: /\b(\d{3})[- ](\d{2})[- ](\d{4})\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'US Social Security Numbers (delimited form), issuance rules enforced.',
+  validate(ctx): ValidationResult {
+    const guard = fragmentGuard(ctx);
+    if (guard !== null) return invalid(guard);
+    const area = Number(ctx.match[1]);
+    const group = Number(ctx.match[2]);
+    const serial = Number(ctx.match[3]);
+    const digits = `${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}`;
+
+    // The famous non-issuable specimens LIVE in the excluded ranges (the
+    // SSA advertising block is area 987), so they are recognized before the
+    // issuance gates — detected, never masked.
+    const advertising = area === 987 && group === 65 && serial >= 4320 && serial <= 4329;
+    if (KNOWN_TEST_SSNS.has(digits) || advertising) {
+      return valid({
+        canonical: digits,
+        sensitive: false,
+        metadata: { scheme: 'ssn', country: 'US' },
+        validator: 'ssn-issuance-rules',
+      });
+    }
+
+    if (area === 0 || area === 666 || area >= 900) return invalid('invalid area');
+    if (group === 0) return invalid('invalid group');
+    if (serial === 0) return invalid('invalid serial');
+    return valid({
+      canonical: digits,
+      metadata: { scheme: 'ssn', country: 'US' },
+      validator: 'ssn-issuance-rules',
+    });
+  },
+});
+
+/** IRS-assigned ITIN group ranges (the middle pair). */
+function itinGroupValid(group: number): boolean {
+  return (group >= 70 && group <= 88) || (group >= 90 && group <= 92) || (group >= 94 && group <= 99);
+}
+
+registerDetector({
+  id: 'national-id-us-itin',
+  entityType: 'TAX_ID',
+  regions: ['US'],
+  pattern: /\b(9\d{2})[- ](\d{2})[- ](\d{4})\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'US ITINs: area 9xx with IRS-assigned group ranges.',
+  validate(ctx): ValidationResult {
+    const guard = fragmentGuard(ctx);
+    if (guard !== null) return invalid(guard);
+    if (!itinGroupValid(Number(ctx.match[2]))) return invalid('not an ITIN group range');
+    if (Number(ctx.match[3]) === 0) return invalid('invalid serial');
+    return valid({
+      canonical: `${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}`,
+      metadata: { scheme: 'itin', country: 'US' },
+      validator: 'itin-group-ranges',
+    });
+  },
+});
+
+/** Valid EIN campus/e-file prefixes. */
+const EIN_PREFIXES = new Set([
+  '01','02','03','04','05','06','10','11','12','13','14','15','16','20','21','22','23','24','25','26','27',
+  '30','31','32','33','34','35','36','37','38','39','40','41','42','43','44','45','46','47','48',
+  '50','51','52','53','54','55','56','57','58','59','60','61','62','63','64','65','66','67','68',
+  '71','72','73','74','75','76','77','80','81','82','83','84','85','86','87','88','90','91','92','93','94','95','98','99',
+]);
+
+registerDetector({
+  id: 'national-id-us-ein',
+  entityType: 'TAX_ID',
+  regions: ['US'],
+  pattern: /\b(\d{2})-(\d{7})\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'US Employer Identification Numbers with valid IRS prefixes.',
+  validate(ctx): ValidationResult {
+    const guard = fragmentGuard(ctx);
+    if (guard !== null) return invalid(guard);
+    if (!EIN_PREFIXES.has(ctx.match[1]!)) return invalid('not an IRS prefix');
+    return valid({
+      canonical: `${ctx.match[1]}${ctx.match[2]}`,
+      metadata: { scheme: 'ein', country: 'US' },
+      validator: 'ein-prefix-table',
+    });
+  },
+});

package/src/detect/detectors/natid/za.ts

@@ -0,0 +1,42 @@
+/**
+ * South Africa: ID number — thirteen digits: YYMMDD SSSS C A Z, validated
+ * as SPEC.md specifies ("Luhn + date validity"): a real calendar date, the
+ * citizenship digit 0/1/2, and Luhn over all thirteen digits. Bijective →
+ * hard mutation property (a date-field mutation may fail either gate;
+ * both are rejections).
+ */
+
+import { luhnValid } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+registerDetector({
+  id: 'national-id-za',
+  entityType: 'NATIONAL_ID',
+  regions: ['ZA'],
+  pattern: /\b(\d{2})(\d{2})(\d{2})(\d{4})(\d)(\d)(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'South African ID numbers: date validity, citizenship digit, Luhn.',
+  validate(ctx): ValidationResult {
+    const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+    if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer number');
+    const after = ctx.text.slice(ctx.end, ctx.end + 2);
+    if (/^\d/.test(after) || /^-\d/.test(after)) return invalid('fragment of a longer number');
+
+    const month = Number(ctx.match[2]);
+    if (month < 1 || month > 12) return invalid('month out of range');
+    const day = Number(ctx.match[3]);
+    if (day < 1 || day > 31) return invalid('day out of range');
+    const citizenship = Number(ctx.match[5]);
+    if (citizenship > 2) return invalid('citizenship digit out of range');
+
+    const digits = ctx.match[0];
+    if (!luhnValid(digits)) return invalid('Luhn checksum failed');
+    return valid({
+      canonical: digits,
+      metadata: { scheme: 'za-id', country: 'ZA', citizen: citizenship === 0 },
+      validator: 'luhn-date',
+    });
+  },
+});