@discretion/core 0.1.0

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

@@ -0,0 +1,116 @@
+/**
+ * Gulf states: Saudi Arabia, UAE, Qatar, Kuwait.
+ *
+ * SA National ID / Iqama: ten digits, first digit 1 (citizen) or 2
+ * (resident), Luhn-closed → HIGH.
+ * AE Emirates ID: 784-YYYY-NNNNNNN-C, fifteen digits beginning 784 (the
+ * UAE's ISO 3166 numeric code) with a plausible birth year, Luhn-closed →
+ * HIGH.
+ * QA QID: eleven digits, first digit 2 or 3 (century), digits 2–3 a
+ * plausible birth year — NO public checksum → MEDIUM, stated.
+ * KW Civil ID: twelve digits: century+YYMMDD then serials, closed by
+ * weights 2,1,6,3,7,9,10,5,8,4,3 mod 11, check = 11 − remainder
+ * (remainders 0 and 1 unissuable) → HIGH.
+ */
+
+import { luhnValid, toDigits, weightedMod } 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-sa',
+  entityType: 'NATIONAL_ID',
+  regions: ['SA'],
+  pattern: /\b[12]\d{9}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Saudi National ID / Iqama: leading 1 or 2, Luhn-closed.',
+  validate(ctx): ValidationResult {
+    const g = guard(ctx);
+    if (g !== null) return invalid(g);
+    if (!luhnValid(ctx.match[0])) return invalid('Luhn checksum failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'saudi-id', country: 'SA', resident: ctx.match[0][0] === '2' },
+      validator: 'luhn',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-ae-emirates-id',
+  entityType: 'NATIONAL_ID',
+  regions: ['AE'],
+  pattern: /\b784[- ]?(\d{4})[- ]?(\d{7})[- ]?(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Emirates ID: 784 prefix, plausible birth year, Luhn-closed.',
+  validate(ctx): ValidationResult {
+    const year = Number(ctx.match[1]);
+    if (year < 1900 || year > 2029) return invalid('implausible birth year');
+    const digits = `784${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}`;
+    if (!luhnValid(digits)) return invalid('Luhn checksum failed');
+    return valid({
+      canonical: digits,
+      metadata: { scheme: 'emirates-id', country: 'AE' },
+      validator: 'luhn',
+    });
+  },
+});
+
+registerDetector({
+  id: 'national-id-qa-qid',
+  entityType: 'NATIONAL_ID',
+  regions: ['QA'],
+  pattern: /\b[23]\d{10}\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Qatari QID: century digit and birth-year structure (no public checksum).',
+  validate(ctx): ValidationResult {
+    const g = guard(ctx);
+    if (g !== null) return invalid(g);
+    const value = ctx.match[0];
+    // Digits 2-3 are the two-digit birth year; nothing further is checkable.
+    return valid({
+      canonical: value,
+      metadata: { scheme: 'qid', country: 'QA' },
+      validator: 'qid-structure',
+    });
+  },
+});
+
+const KW_WEIGHTS = [2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 3];
+
+registerDetector({
+  id: 'national-id-kw-civil-id',
+  entityType: 'NATIONAL_ID',
+  regions: ['KW'],
+  pattern: /\b[123]\d{11}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Kuwaiti Civil ID with its weighted mod-11 check digit.',
+  validate(ctx): ValidationResult {
+    const g = guard(ctx);
+    if (g !== null) return invalid(g);
+    const value = ctx.match[0];
+    const month = Number(value.slice(3, 5));
+    if (month < 1 || month > 12) return invalid('month out of range');
+    const day = Number(value.slice(5, 7));
+    if (day < 1 || day > 31) return invalid('day out of range');
+    const d = toDigits(value)!;
+    const remainder = weightedMod(d.slice(0, 11), KW_WEIGHTS, 11)!;
+    const check = 11 - remainder;
+    if (check >= 10) return invalid('unissuable remainder');
+    if (check !== d[11]) return invalid('Civil ID check failed');
+    return valid({
+      canonical: value,
+      metadata: { scheme: 'civil-id', country: 'KW' },
+      validator: 'civilid-mod11',
+    });
+  },
+});

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

@@ -0,0 +1,42 @@
+/**
+ * Hong Kong: HKID — one or two prefix letters, six digits, and a check
+ * character (0–9 or A). Values: letters A=10…Z=35; a single-letter id is
+ * computed as if preceded by a space valued 36. Weights 9,8 for the prefix,
+ * 7..2 for the digits, 1 for the check (A counts as 10); the total must be
+ * divisible by 11.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+const letterValue = (ch: string): number => ch.charCodeAt(0) - 65 + 10;
+
+registerDetector({
+  id: 'national-id-hk-hkid',
+  entityType: 'NATIONAL_ID',
+  regions: ['HK'],
+  pattern: /\b([A-Z]{1,2})(\d{6})[([]?([0-9A])[)\]]?(?![\w])/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Hong Kong HKID with its mod-11 check character (bracketed writing accepted).',
+  validate(ctx): ValidationResult {
+    const prefix = ctx.match[1]!;
+    const digits = ctx.match[2]!;
+    const check = ctx.match[3]!;
+
+    let sum = 0;
+    if (prefix.length === 2) {
+      sum += letterValue(prefix[0]!) * 9 + letterValue(prefix[1]!) * 8;
+    } else {
+      sum += 36 * 9 + letterValue(prefix[0]!) * 8;
+    }
+    for (let i = 0; i < 6; i++) sum += Number(digits[i]) * (7 - i);
+    sum += check === 'A' ? 10 : Number(check);
+    if (sum % 11 !== 0) return invalid('mod-11 check failed');
+    return valid({
+      canonical: `${prefix}${digits}${check}`,
+      metadata: { scheme: 'hkid', country: 'HK' },
+      validator: 'hkid-mod11',
+    });
+  },
+});

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

@@ -0,0 +1,32 @@
+/**
+ * Croatia: OIB — eleven digits closed by ISO 7064 MOD 11,10, straight from
+ * the shared library.
+ */
+
+import { mod11_10Valid } 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-hr-oib',
+  entityType: 'NATIONAL_ID',
+  regions: ['HR'],
+  pattern: /\b\d{11}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Croatian OIB: ISO 7064 MOD 11,10.',
+  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 value = ctx.match[0];
+    if (!mod11_10Valid(value.slice(0, 10), value[10]!)) return invalid('MOD 11,10 failed');
+    return valid({
+      canonical: value,
+      metadata: { scheme: 'oib', country: 'HR' },
+      validator: 'iso7064-11-10',
+    });
+  },
+});

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

@@ -0,0 +1,36 @@
+/**
+ * Hungary: Személyi szám — eleven digits: a 1–8 gender/century digit,
+ * YYMMDD, a 3-digit serial, and a positional check: Σ dᵢ·(i+1) over the
+ * first ten (1-based weights 1..10), mod 11; remainder 10 unissuable.
+ */
+
+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-hu-szemelyi',
+  entityType: 'NATIONAL_ID',
+  regions: ['HU'],
+  pattern: /\b([1-8])(\d{2})(\d{2})(\d{2})[- ]?(\d{4})\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Hungarian személyi szám with its positional mod-11 check.',
+  validate(ctx): ValidationResult {
+    const month = Number(ctx.match[3]);
+    if (month < 1 || month > 12) return invalid('month out of range');
+    const day = Number(ctx.match[4]);
+    if (day < 1 || day > 31) return invalid('day out of range');
+
+    const eleven = `${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}${ctx.match[4]}${ctx.match[5]}`;
+    const digits = toDigits(eleven)!;
+    const remainder = weightedModBy(digits.slice(0, 10), (i) => i + 1, 11)!;
+    if (remainder === 10) return invalid('remainder 10 never issued');
+    if (remainder !== digits[10]) return invalid('checksum failed');
+    return valid({
+      canonical: eleven,
+      metadata: { scheme: 'szemelyi-szam', country: 'HU' },
+      validator: 'szemelyi-mod11',
+    });
+  },
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Ireland: PPS Number — 7 digits + 1–2 letters with a real mod-23 check.
+ *
+ * Check: Σ(digitᵢ × weight 8..2) + 9 × value(second letter, if any, A=1…),
+ * mod 23, mapped 0→'W', 1→'A' … 22→'V'. The second letter (post-2013
+ * format, only 'A' or 'H' issued) participates in the sum. HIGH.
+ */
+
+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 PPS_WEIGHTS = [8, 7, 6, 5, 4, 3, 2];
+const MOD23 = 'WABCDEFGHIJKLMNOPQRSTUV';
+
+registerDetector({
+  id: 'national-id-ie-pps',
+  entityType: 'NATIONAL_ID',
+  regions: ['IE'],
+  pattern: /\b(\d{7})([A-W])([AH])?\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Irish PPS Numbers with the mod-23 check letter verified.',
+  validate(ctx): ValidationResult {
+    const digits = toDigits(ctx.match[1]!)!;
+    let sum = weightedSum(digits, PPS_WEIGHTS)!;
+    const second = ctx.match[3];
+    if (second !== undefined) sum += 9 * (second.charCodeAt(0) - 64);
+    const expected = MOD23[sum % 23]!;
+    if (ctx.match[2] !== expected) return invalid('mod-23 check letter failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'pps', country: 'IE' },
+      validator: 'pps-mod23',
+    });
+  },
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Israel: Teudat Zehut — nine digits closed by the Luhn variant SPEC.md
+ * references: double every second digit from the LEFT, sum the digit sums,
+ * divisible by 10. On a nine-digit number that parity coincides exactly
+ * with standard right-anchored Luhn, so the shared library applies —
+ * verified by the tests rather than assumed. Short older numbers are
+ * written zero-padded to nine.
+ */
+
+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-il-teudat-zehut',
+  entityType: 'NATIONAL_ID',
+  regions: ['IL'],
+  pattern: /\b\d{9}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Israeli Teudat Zehut: nine digits under the left-anchored Luhn variant.',
+  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 value = ctx.match[0];
+    if (value === '000000000') return invalid('all zeros');
+    if (!luhnValid(value)) return invalid('checksum failed');
+    return valid({
+      canonical: value,
+      metadata: { scheme: 'teudat-zehut', country: 'IL' },
+      validator: 'luhn',
+    });
+  },
+});

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

@@ -0,0 +1,67 @@
+/**
+ * India: Aadhaar and PAN.
+ *
+ * Aadhaar — twelve digits, first digit 2–9 (0 and 1 are never issued),
+ * closed by Verhoeff from the shared library (the algorithm Aadhaar chose
+ * precisely because it catches every single error and transposition) →
+ * HIGH, hard mutation property.
+ *
+ * PAN — AAAPA1234A: the fourth letter is the holder-type code (P person,
+ * C company, H HUF, F firm, A AOP, T trust, B BOI, L local authority,
+ * J artificial juridical person, G government) and the fifth the name
+ * initial. The final letter is a check whose algorithm the Income Tax
+ * Department has never published, so PAN validates structurally at MEDIUM
+ * and says so.
+ */
+
+import { verhoeffValid } 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-in-aadhaar',
+  entityType: 'NATIONAL_ID',
+  regions: ['IN'],
+  pattern: /\b[2-9]\d{3}[ -]?\d{4}[ -]?\d{4}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Indian Aadhaar numbers, Verhoeff-verified (SPEC.md names the algorithm).',
+  validate(ctx): ValidationResult {
+    const g = guard(ctx);
+    if (g !== null) return invalid(g);
+    const digits = ctx.match[0].replace(/[ -]/g, '');
+    if (!verhoeffValid(digits)) return invalid('Verhoeff checksum failed');
+    return valid({
+      canonical: digits,
+      metadata: { scheme: 'aadhaar', country: 'IN' },
+      validator: 'verhoeff',
+    });
+  },
+});
+
+const PAN_HOLDER_TYPES = new Set([...'PCHFATBLJG']);
+
+registerDetector({
+  id: 'national-id-in-pan',
+  entityType: 'TAX_ID',
+  regions: ['IN'],
+  pattern: /\b([A-Z]{3})([A-Z])([A-Z])(\d{4})([A-Z])\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Indian PAN: holder-type letter validated; the check letter is unpublished, hence MEDIUM.',
+  validate(ctx): ValidationResult {
+    if (!PAN_HOLDER_TYPES.has(ctx.match[2]!)) return invalid('fourth letter is not a holder type');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'pan', country: 'IN', holderType: ctx.match[2] },
+      validator: 'pan-structure',
+    });
+  },
+});

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

@@ -0,0 +1,54 @@
+/**
+ * National identifier family. One file per COUNTRY, each registering that
+ * country's schemes — adding a new country (or a new scheme to an existing
+ * country) touches exactly one file here plus its side-effect import below,
+ * which is the SPEC.md extensibility requirement.
+ */
+import './us.js';
+import './ca.js';
+import './gb.js';
+import './ie.js';
+import './de.js';
+import './fr.js';
+import './es.js';
+import './it.js';
+import './nl.js';
+import './be.js';
+import './pl.js';
+import './se.js';
+import './no.js';
+import './dk.js';
+import './fi.js';
+import './is.js';
+import './pt.js';
+import './gr.js';
+import './cz.js';
+import './hu.js';
+import './ro.js';
+import './bg.js';
+import './hr.js';
+import './si.js';
+import './tr.js';
+import './ru.js';
+import './ua.js';
+import './kz.js';
+import './il.js';
+import './gulf.js';
+import './in.js';
+import './cn.js';
+import './tw.js';
+import './jp.js';
+import './kr.js';
+import './sg.js';
+import './hk.js';
+import './seasia.js';
+import './au.js';
+import './nz.js';
+import './br.js';
+import './mx.js';
+import './ar.js';
+import './cl.js';
+import './co.js';
+import './pe.js';
+import './za.js';
+import './africa.js';

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

@@ -0,0 +1,42 @@
+/**
+ * Iceland: Kennitala — DDMMYY-NNCX where C is a mod-11 check over the first
+ * eight digits (weights 3,2,7,6,5,4,3,2; remainder result 10 unissuable)
+ * and X is the century digit (9 → 1900s, 0 → 2000s, 8 → 1800s). Company
+ * kennitölur add 40 to the day and are accepted as such.
+ */
+
+import { toDigits, weightedMod } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+const KT_WEIGHTS = [3, 2, 7, 6, 5, 4, 3, 2];
+
+registerDetector({
+  id: 'national-id-is-kennitala',
+  entityType: 'NATIONAL_ID',
+  regions: ['IS'],
+  pattern: /\b(\d{2})(\d{2})(\d{2})-?(\d{2})(\d)(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Icelandic kennitala with its mod-11 check digit; company numbers included.',
+  validate(ctx): ValidationResult {
+    const day = Number(ctx.match[1]);
+    const company = day >= 41 && day <= 71;
+    if (!(day >= 1 && day <= 31) && !company) return invalid('day out of range');
+    const month = Number(ctx.match[2]);
+    if (month < 1 || month > 12) return invalid('month out of range');
+    const century = ctx.match[6]!;
+    if (century !== '8' && century !== '9' && century !== '0') return invalid('not a century digit');
+
+    const eight = toDigits(`${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}${ctx.match[4]}`)!;
+    let check = 11 - weightedMod(eight, KT_WEIGHTS, 11)!;
+    if (check === 11) check = 0;
+    if (check === 10 || check !== Number(ctx.match[5])) return invalid('mod-11 check failed');
+
+    return valid({
+      canonical: `${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}${ctx.match[4]}${ctx.match[5]}${century}`,
+      metadata: { scheme: 'kennitala', country: 'IS', company },
+      validator: 'kennitala-mod11',
+    });
+  },
+});

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

@@ -0,0 +1,65 @@
+/**
+ * Italy: Codice Fiscale — 16 characters closed by the full CIN algorithm.
+ *
+ * Odd positions (1st, 3rd, … 1-based) use the published odd-value table,
+ * even positions the even table; the sum mod 26 indexes A–Z for the check
+ * letter. The month letter must be one of ABCDEHLMPRST and the day field
+ * 01–31 or 41–71 (women add 40). Both tables are transcribed in full from
+ * the Agenzia delle Entrate specification.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+const ODD: Readonly<Record<string, number>> = {
+  '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 EVEN: Readonly<Record<string, number>> = {
+  '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 MONTH_LETTERS = new Set([...'ABCDEHLMPRST']);
+
+/** The published CIN check letter for the first fifteen characters. */
+export function codiceFiscaleCin(fifteen: string): string | null {
+  let sum = 0;
+  for (let i = 0; i < 15; i++) {
+    const ch = fifteen[i]!;
+    const table = i % 2 === 0 ? ODD : EVEN; // i is 0-based; 1-based odd = 0-based even index
+    const v = table[ch];
+    if (v === undefined) return null;
+    sum += v;
+  }
+  return String.fromCharCode(65 + (sum % 26));
+}
+
+registerDetector({
+  id: 'national-id-it-codice-fiscale',
+  entityType: 'NATIONAL_ID',
+  regions: ['IT'],
+  pattern: /\b([A-Z]{6})(\d{2})([A-Z])(\d{2})([A-Z]\d{3})([A-Z])\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Italian Codice Fiscale with the full CIN check-letter algorithm.',
+  validate(ctx): ValidationResult {
+    const month = ctx.match[3]!;
+    if (!MONTH_LETTERS.has(month)) return invalid('not a month letter');
+    const day = Number(ctx.match[4]);
+    const dayValid = (day >= 1 && day <= 31) || (day >= 41 && day <= 71);
+    if (!dayValid) return invalid('day field out of range');
+
+    const value = ctx.match[0];
+    const expected = codiceFiscaleCin(value.slice(0, 15));
+    if (expected === null || value[15] !== expected) return invalid('CIN check letter failed');
+
+    return valid({
+      canonical: value,
+      metadata: { scheme: 'codice-fiscale', country: 'IT', female: day >= 41 },
+      validator: 'cin',
+    });
+  },
+});

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

@@ -0,0 +1,48 @@
+/**
+ * Japan: My Number (個人番号) — twelve digits. Check: over the eleven
+ * payload digits counted 1..11 from the RIGHT, weight = n+1 for n ≤ 6 and
+ * n−5 for n ≥ 7; remainder = sum mod 11; check digit = 0 when the
+ * remainder ≤ 1, else 11 − remainder.
+ */
+
+import { toDigits } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+/** The check digit for the eleven payload digits (left to right). */
+export function myNumberCheckDigit(payload: readonly number[]): number {
+  let sum = 0;
+  for (let n = 1; n <= 11; n++) {
+    const digit = payload[11 - n]!; // n-th from the right
+    const weight = n <= 6 ? n + 1 : n - 5;
+    sum += digit * weight;
+  }
+  const remainder = sum % 11;
+  return remainder <= 1 ? 0 : 11 - remainder;
+}
+
+registerDetector({
+  id: 'national-id-jp-my-number',
+  entityType: 'NATIONAL_ID',
+  regions: ['JP'],
+  pattern: /\b(\d{4})[ -]?(\d{4})[ -]?(\d{4})\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Japanese My Number with its positional 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 digits = toDigits(ctx.match[0].replace(/[ -]/g, ''))!;
+    if (myNumberCheckDigit(digits.slice(0, 11)) !== digits[11]) {
+      return invalid('My Number check failed');
+    }
+    return valid({
+      canonical: digits.join(''),
+      metadata: { scheme: 'my-number', country: 'JP' },
+      validator: 'mynumber-mod11',
+    });
+  },
+});

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

@@ -0,0 +1,41 @@
+/**
+ * South Korea: RRN (주민등록번호) — YYMMDD-SCCCCCK: the seventh digit
+ * encodes sex and century (1–8; 5–8 for foreign residents), and the check
+ * is weights 2,3,4,5,6,7,8,9,2,3,4,5 with check = (11 − sum mod 11) mod
+ * 10. RRNs issued from October 2020 randomized the regional digits but
+ * KEPT the check digit for the pre-existing stock; new issues no longer
+ * compute it, so numbers failing the check with a plausible date are NOT
+ * emitted (precision wins — a wrong RRN hit is a phone number or a date).
+ */
+
+import { toDigits, weightedMod } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationResult } from '../../types.js';
+
+const RRN_WEIGHTS = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5];
+
+registerDetector({
+  id: 'national-id-kr-rrn',
+  entityType: 'NATIONAL_ID',
+  regions: ['KR'],
+  pattern: /\b(\d{2})(\d{2})(\d{2})-([1-8])(\d{5})(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Korean RRN with its weighted mod-11 check digit.',
+  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 digits = toDigits(`${ctx.match[1]}${ctx.match[2]}${ctx.match[3]}${ctx.match[4]}${ctx.match[5]}${ctx.match[6]}`)!;
+    const remainder = weightedMod(digits.slice(0, 12), RRN_WEIGHTS, 11)!;
+    const check = (11 - remainder) % 10;
+    if (check !== digits[12]) return invalid('RRN check failed');
+    return valid({
+      canonical: digits.join(''),
+      metadata: { scheme: 'rrn', country: 'KR' },
+      validator: 'rrn-mod11',
+    });
+  },
+});

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

@@ -0,0 +1,44 @@
+/**
+ * Kazakhstan: IIN (ЖСН/ИИН) — twelve digits: YYMMDD, a century/sex digit
+ * (1–6), four serial digits, and a two-phase mod-11 check: weights 1..11;
+ * if the remainder is 10, reweigh with the rotated vector 3,4,…,11,1,2;
+ * a second 10 makes the number unissuable.
+ */
+
+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-kz-iin',
+  entityType: 'NATIONAL_ID',
+  regions: ['KZ'],
+  pattern: /\b(\d{2})(\d{2})(\d{2})([1-6])(\d{4})(\d)\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Kazakh IIN with the two-phase rotated 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 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 d = toDigits(ctx.match[0])!;
+    let check = weightedModBy(d.slice(0, 11), (i) => i + 1, 11)!;
+    if (check === 10) {
+      check = weightedModBy(d.slice(0, 11), (i) => ((i + 2) % 11) + 1, 11)!;
+      if (check === 10) return invalid('unissuable (double remainder 10)');
+    }
+    if (check !== d[11]) return invalid('IIN check failed');
+    return valid({
+      canonical: ctx.match[0],
+      metadata: { scheme: 'iin', country: 'KZ' },
+      validator: 'iin-two-phase-mod11',
+    });
+  },
+});