@discretion/core 0.1.0

package/src/detect/detectors/documents/usNpi.ts

@@ -0,0 +1,50 @@
+/**
+ * US_NPI — National Provider Identifier.
+ *
+ * SPEC.md: "US_NPI — Luhn with prefix." Ten digits, closed by Luhn computed
+ * over the NPI PREFIXED with the constant 80840 (the ISO 7812 issuer prefix
+ * assigned to the NPI system). Omitting the prefix is the classic
+ * implementation bug: it produces a different check digit and silently
+ * rejects every real NPI, so the prefix is applied here and pinned by tests
+ * against published specimen NPIs.
+ *
+ * Issued NPIs begin with 1 or 2 (3 and 4 are reserved for future use), which
+ * is enforced: it removes most of the arbitrary 10-digit runs that pass Luhn
+ * by chance.
+ */
+
+import { luhnValid } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+/** ISO 7812 issuer identifier for the NPI system. */
+const NPI_PREFIX = '80840';
+
+function validateNpi(ctx: ValidationContext): 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 npi = ctx.match[0];
+  const first = npi[0]!;
+  if (first !== '1' && first !== '2') return invalid('NPIs begin with 1 or 2');
+  if (!luhnValid(`${NPI_PREFIX}${npi}`)) return invalid('Luhn checksum (with 80840 prefix) failed');
+
+  return valid({
+    canonical: npi,
+    metadata: { scheme: 'npi', country: 'US' },
+    validator: 'luhn-80840',
+  });
+}
+
+registerDetector({
+  id: 'us-npi',
+  entityType: 'US_NPI',
+  regions: ['US'],
+  pattern: /\b\d{10}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'US National Provider Identifiers: Luhn over the 80840-prefixed number.',
+  validate: validateNpi,
+});

package/src/detect/detectors/documents/vin.ts

@@ -0,0 +1,67 @@
+/**
+ * VIN — ISO 3779 vehicle identification number with its check digit.
+ *
+ * 17 characters, no I/O/Q anywhere (they are excluded to avoid confusion
+ * with 1/0). Position 9 is a check digit computed by transliterating each
+ * character to a value, weighting by position, and taking mod 11 — where a
+ * remainder of 10 is written 'X'.
+ *
+ * The check is mandatory in North America and, while technically optional
+ * elsewhere, is populated by essentially every manufacturer; requiring it
+ * keeps 17-character part numbers and order references out.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+/** ISO 3779 transliteration; I, O and Q are absent by design. */
+const VALUES: Readonly<Record<string, number>> = {
+  A: 1, B: 2, C: 3, D: 4, E: 5, F: 6, G: 7, H: 8,
+  J: 1, K: 2, L: 3, M: 4, N: 5, P: 7, R: 9,
+  S: 2, T: 3, U: 4, V: 5, W: 6, X: 7, Y: 8, Z: 9,
+  '0': 0, '1': 1, '2': 2, '3': 3, '4': 4, '5': 5, '6': 6, '7': 7, '8': 8, '9': 9,
+};
+
+const WEIGHTS: readonly number[] = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];
+
+/** The ISO 3779 check character for a 17-character VIN. */
+export function vinCheckChar(vin: string): string | null {
+  if (vin.length !== 17) return null;
+  let sum = 0;
+  for (let i = 0; i < 17; i++) {
+    const v = VALUES[vin[i]!];
+    if (v === undefined) return null;
+    sum += v * WEIGHTS[i]!;
+  }
+  const remainder = sum % 11;
+  return remainder === 10 ? 'X' : String(remainder);
+}
+
+function validateVin(ctx: ValidationContext): ValidationResult {
+  const vin = ctx.match[0].toUpperCase();
+  if (/[IOQ]/.test(vin)) return invalid('VIN alphabet excludes I, O and Q');
+
+  const expected = vinCheckChar(vin);
+  if (expected === null) return invalid('character outside the VIN alphabet');
+  if (vin[8] !== expected) return invalid('check digit failed');
+
+  return valid({
+    canonical: vin,
+    metadata: {
+      wmi: vin.slice(0, 3), // world manufacturer identifier
+      modelYearCode: vin[9],
+    },
+    validator: 'iso3779',
+  });
+}
+
+registerDetector({
+  id: 'vin',
+  entityType: 'VIN',
+  regions: [GLOBAL_REGION],
+  pattern: /\b[A-HJ-NPR-Z0-9]{17}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Vehicle identification numbers with the ISO 3779 check digit verified.',
+  validate: validateVin,
+});

package/src/detect/detectors/financial/creditCard.ts

@@ -0,0 +1,167 @@
+/**
+ * CREDIT_CARD — Luhn required, plus issuer BIN identification.
+ *
+ * SPEC.md names the issuer set: Visa, Mastercard, Amex, Discover, JCB,
+ * UnionPay, Diners, Maestro, Troy, Mir, RuPay, Elo, Verve. "Known test card
+ * numbers matched but classified as non-sensitive."
+ *
+ * BIN resolution is LONGEST-PREFIX-FIRST: 622126–622925 (six digits,
+ * Discover's UnionPay-processed block) beats 62 (UnionPay); 6521–6522
+ * (RuPay) beats 65 (Discover); 6011 (Discover) beats 60 (RuPay). Contested
+ * short prefixes are classified per the mainstream network documentation;
+ * issuer is metadata for substitution and display — Luhn plus per-issuer
+ * length is what gates validity.
+ *
+ * A Luhn-valid digit run with NO recognizable issuer prefix is REJECTED, not
+ * emitted at low confidence. Luhn alone has a 10% pass rate on arbitrary
+ * digit runs, and IMEIs, tracking numbers and account numbers are all
+ * Luhn-closed — issuer identification is the precision gate that keeps them
+ * out. (A 15-digit IMEI starting 35 falls in JCB's 3528–3589 window, but
+ * JCB issues only 16–19 digit PANs, so the length gate rejects it.)
+ */
+
+import { luhnValid } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+interface BinRule {
+  readonly lo: number; // inclusive numeric prefix bound
+  readonly hi: number; // inclusive
+  readonly digits: number; // how many leading digits the bounds cover
+  readonly issuer: string;
+}
+
+/** Ordered within each prefix length; longer prefixes always win. */
+const BIN_RULES: readonly BinRule[] = [
+  // 6-digit rules
+  { lo: 622126, hi: 622925, digits: 6, issuer: 'discover' },
+  { lo: 506099, hi: 506198, digits: 6, issuer: 'verve' },
+  { lo: 507865, hi: 507964, digits: 6, issuer: 'verve' },
+  { lo: 650002, hi: 650027, digits: 6, issuer: 'verve' },
+  { lo: 401178, hi: 401179, digits: 6, issuer: 'elo' },
+  { lo: 431274, hi: 431274, digits: 6, issuer: 'elo' },
+  { lo: 438935, hi: 438935, digits: 6, issuer: 'elo' },
+  { lo: 451416, hi: 451416, digits: 6, issuer: 'elo' },
+  { lo: 457393, hi: 457393, digits: 6, issuer: 'elo' },
+  { lo: 457631, hi: 457632, digits: 6, issuer: 'elo' },
+  { lo: 504175, hi: 504175, digits: 6, issuer: 'elo' },
+  { lo: 506699, hi: 506778, digits: 6, issuer: 'elo' },
+  { lo: 509000, hi: 509999, digits: 6, issuer: 'elo' },
+  { lo: 627780, hi: 627780, digits: 6, issuer: 'elo' },
+  { lo: 636297, hi: 636297, digits: 6, issuer: 'elo' },
+  { lo: 636368, hi: 636368, digits: 6, issuer: 'elo' },
+  { lo: 650031, hi: 650051, digits: 6, issuer: 'elo' },
+  { lo: 650405, hi: 650439, digits: 6, issuer: 'elo' },
+  { lo: 650485, hi: 650538, digits: 6, issuer: 'elo' },
+  { lo: 650541, hi: 650598, digits: 6, issuer: 'elo' },
+  { lo: 650700, hi: 650727, digits: 6, issuer: 'elo' },
+  { lo: 650901, hi: 650978, digits: 6, issuer: 'elo' },
+  { lo: 651652, hi: 651679, digits: 6, issuer: 'elo' },
+  { lo: 655000, hi: 655058, digits: 6, issuer: 'elo' },
+  // 4-digit rules
+  { lo: 9792, hi: 9792, digits: 4, issuer: 'troy' },
+  { lo: 2200, hi: 2204, digits: 4, issuer: 'mir' },
+  { lo: 3528, hi: 3589, digits: 4, issuer: 'jcb' },
+  { lo: 2221, hi: 2720, digits: 4, issuer: 'mastercard' },
+  { lo: 6011, hi: 6011, digits: 4, issuer: 'discover' },
+  { lo: 6521, hi: 6522, digits: 4, issuer: 'rupay' },
+  { lo: 3095, hi: 3095, digits: 4, issuer: 'diners' },
+  // 3-digit rules
+  { lo: 300, hi: 305, digits: 3, issuer: 'diners' },
+  { lo: 644, hi: 649, digits: 3, issuer: 'discover' },
+  { lo: 508, hi: 508, digits: 3, issuer: 'rupay' },
+  // 2-digit rules
+  { lo: 34, hi: 34, digits: 2, issuer: 'amex' },
+  { lo: 37, hi: 37, digits: 2, issuer: 'amex' },
+  { lo: 36, hi: 36, digits: 2, issuer: 'diners' },
+  { lo: 38, hi: 39, digits: 2, issuer: 'diners' },
+  { lo: 51, hi: 55, digits: 2, issuer: 'mastercard' },
+  { lo: 65, hi: 65, digits: 2, issuer: 'discover' },
+  { lo: 62, hi: 62, digits: 2, issuer: 'unionpay' },
+  { lo: 60, hi: 60, digits: 2, issuer: 'rupay' },
+  { lo: 81, hi: 82, digits: 2, issuer: 'rupay' },
+  { lo: 50, hi: 50, digits: 2, issuer: 'maestro' },
+  { lo: 56, hi: 59, digits: 2, issuer: 'maestro' },
+  { lo: 61, hi: 61, digits: 2, issuer: 'maestro' },
+  { lo: 63, hi: 64, digits: 2, issuer: 'maestro' },
+  { lo: 66, hi: 69, digits: 2, issuer: 'maestro' },
+  // 1-digit rules
+  { lo: 4, hi: 4, digits: 1, issuer: 'visa' },
+];
+
+/** Permitted PAN lengths per issuer. */
+const ISSUER_LENGTHS: Readonly<Record<string, readonly number[]>> = {
+  visa: [13, 16, 19],
+  mastercard: [16],
+  amex: [15],
+  discover: [16, 17, 18, 19],
+  jcb: [16, 17, 18, 19],
+  unionpay: [16, 17, 18, 19],
+  diners: [14, 15, 16, 17, 18, 19],
+  maestro: [12, 13, 14, 15, 16, 17, 18, 19],
+  troy: [16],
+  mir: [16, 17, 18, 19],
+  rupay: [16],
+  elo: [16],
+  verve: [16, 18, 19],
+};
+
+/** Universally published test PANs: detected, never masked. */
+const TEST_CARDS: ReadonlySet<string> = new Set([
+  '4111111111111111', '4012888888881881', '4222222222222', '4000056655665556',
+  '4917610000000000',
+  '5555555555554444', '5105105105105100', '5200828282828210', '2223003122003222',
+  '378282246310005', '371449635398431', '378734493671000',
+  '6011111111111117', '6011000990139424', '6011981111111113',
+  '3530111333300000', '3566002020360505',
+  '30569309025904', '38520000023237',
+  '6200000000000005', '6200000000000047',
+  '2200000000000053',
+]);
+
+function resolveIssuer(pan: string): string | null {
+  for (const rule of BIN_RULES) {
+    if (pan.length < rule.digits) continue;
+    const prefix = Number(pan.slice(0, rule.digits));
+    if (prefix >= rule.lo && prefix <= rule.hi) return rule.issuer;
+  }
+  return null;
+}
+
+function validateCreditCard(ctx: ValidationContext): ValidationResult {
+  // Digit runs adjacent to more digits (or digit-separator continuations)
+  // are fragments of something longer.
+  const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+  if (/\d/.test(before ?? '')) return invalid('fragment of a longer digit run');
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^\d/.test(after) || /^[ -]\d/.test(after)) return invalid('fragment of a longer digit run');
+
+  const pan = ctx.match[0].replace(/[ -]/g, '');
+  if (!/^\d{12,19}$/.test(pan)) return invalid('not 12-19 digits');
+
+  const issuer = resolveIssuer(pan);
+  if (issuer === null) return invalid('no recognizable issuer prefix');
+  if (!ISSUER_LENGTHS[issuer]!.includes(pan.length)) {
+    return invalid('length not issued by this network');
+  }
+  if (!luhnValid(pan)) return invalid('Luhn checksum failed');
+
+  return valid({
+    canonical: pan,
+    sensitive: !TEST_CARDS.has(pan),
+    metadata: { issuer },
+    validator: 'luhn-bin',
+  });
+}
+
+registerDetector({
+  id: 'credit-card',
+  entityType: 'CREDIT_CARD',
+  regions: [GLOBAL_REGION],
+  // 12–19 digits with optional single space/hyphen separators.
+  pattern: /\b\d(?:[ -]?\d){11,18}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Payment card numbers: Luhn plus issuer BIN identification; test PANs non-sensitive.',
+  validate: validateCreditCard,
+});

package/src/detect/detectors/financial/iban.ts

@@ -0,0 +1,82 @@
+/**
+ * IBAN — mod-97 checksum plus the full per-country structure registry.
+ *
+ * Order of proof: country exists in the registry → length matches that
+ * country → BBAN matches that country's structure → mod-97 closes. Each
+ * gate alone is insufficient: mod-97 without structure accepts transposed
+ * letter/digit segments; structure without mod-97 accepts any typo.
+ *
+ * SPAN TRIMMING. IBANs are written in groups of four ("GB82 WEST 1234 …"),
+ * so the candidate pattern must cross spaces — which lets it absorb the
+ * word after the IBAN. The validator counts alphanumerics up to the
+ * country's expected length and cuts there, but ONLY at a separator
+ * boundary: if the next character is alphanumeric the token simply
+ * continues (an account-number-like blob), and that is a rejection, not a
+ * trim.
+ */
+
+import { ibanMod97Valid } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+import { DOCUMENTATION_IBANS, IBAN_REGISTRY } from './ibanRegistry.js';
+
+function validateIban(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+
+  const country = raw.slice(0, 2).toUpperCase();
+  const spec = IBAN_REGISTRY.get(country);
+  if (spec === undefined) return invalid('not an IBAN country code');
+
+  // Walk the raw match, collecting alphanumerics up to the expected length
+  // and remembering where in the raw text the last one sits.
+  let collected = '';
+  let endInRaw = 0;
+  for (let i = 0; i < raw.length && collected.length < spec.length; i++) {
+    const ch = raw[i]!;
+    if (/[A-Za-z0-9]/.test(ch)) {
+      collected += ch;
+      endInRaw = i + 1;
+    } else if (ch !== ' ') {
+      break; // only spaces may separate IBAN groups
+    }
+  }
+  if (collected.length < spec.length) return invalid('too short for this country');
+
+  // The character after the cut must not continue the token.
+  const nextInRaw = raw[endInRaw];
+  if (nextInRaw !== undefined && /[A-Za-z0-9]/.test(nextInRaw)) {
+    return invalid('embedded in a longer alphanumeric run');
+  }
+  const afterMatch = ctx.text[ctx.start + raw.length];
+  if (endInRaw === raw.length && afterMatch !== undefined && /[A-Za-z0-9]/.test(afterMatch)) {
+    return invalid('embedded in a longer alphanumeric run');
+  }
+
+  const iban = collected.toUpperCase();
+  if (!/^[A-Z]{2}[0-9]{2}/.test(iban)) return invalid('malformed check digits');
+  const bban = iban.slice(4);
+  if (!spec.bban.test(bban)) return invalid('BBAN structure mismatch for country');
+  if (!ibanMod97Valid(iban)) return invalid('mod-97 checksum failed');
+
+  return valid({
+    canonical: iban,
+    sensitive: !DOCUMENTATION_IBANS.has(iban),
+    metadata: { country },
+    validator: 'iban-mod97-structure',
+    span: { start: ctx.start, end: ctx.start + endInRaw },
+  });
+}
+
+registerDetector({
+  id: 'iban',
+  entityType: 'IBAN',
+  regions: [GLOBAL_REGION],
+  // Two letters, two digits, then grouped or compact alphanumerics. The 10
+  // minimum keeps three-word capitalized prose ("IN 2019 THE…") from ever
+  // reaching the validator.
+  pattern: /\b[A-Za-z]{2}\d{2}(?: ?[A-Za-z0-9]){10,32}/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'IBANs validated against the full registry: country, length, structure, mod-97.',
+  validate: validateIban,
+});

package/src/detect/detectors/financial/ibanRegistry.ts

@@ -0,0 +1,112 @@
+/**
+ * The IBAN registry: per-country length and BBAN structure.
+ *
+ * SPEC.md: "IBAN — mod-97 checksum plus per-country length and structure
+ * table covering all IBAN-registry countries."
+ *
+ * Structure is encoded as segments — "4a6n8c" reads: 4 letters, 6 digits,
+ * 8 alphanumerics — with adjacent same-type runs merged from the official
+ * SWIFT registry notation (4!a etc.). One encoding drives BOTH the
+ * validator's regex and the test generator's synthesis, so they can never
+ * drift apart. Segment types: n = 0-9, a = A-Z, c = A-Z0-9.
+ *
+ * Entries reflect the SWIFT IBAN Registry (release 98, 2024): 88 countries
+ * and territories. Countries using another state's IBAN (Åland → FI, the
+ * French overseas collectivities → FR) are covered by that state's entry.
+ */
+
+export interface IbanSegment {
+  readonly type: 'n' | 'a' | 'c';
+  readonly length: number;
+}
+
+export interface IbanSpec {
+  /** Total IBAN length including country code and check digits. */
+  readonly length: number;
+  readonly segments: readonly IbanSegment[];
+  /** Compiled BBAN validation regex (anchored). */
+  readonly bban: RegExp;
+}
+
+const SEGMENT_CLASS: Record<IbanSegment['type'], string> = {
+  n: '[0-9]',
+  a: '[A-Z]',
+  c: '[A-Z0-9]',
+};
+
+function parseSegments(encoded: string): IbanSegment[] {
+  const out: IbanSegment[] = [];
+  const re = /(\d+)([nac])/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(encoded)) !== null) {
+    out.push({ type: m[2] as IbanSegment['type'], length: Number(m[1]) });
+  }
+  return out;
+}
+
+function buildSpec(length: number, encoded: string): IbanSpec {
+  const segments = parseSegments(encoded);
+  const bbanLength = segments.reduce((sum, s) => sum + s.length, 0);
+  if (bbanLength !== length - 4) {
+    // Impossible unless the table below is mistyped; fail at module load.
+    throw new Error(`IBAN registry entry inconsistent: ${encoded} for length ${length}`);
+  }
+  const source = `^${segments.map((s) => `${SEGMENT_CLASS[s.type]}{${s.length}}`).join('')}$`;
+  return { length, segments, bban: new RegExp(source) };
+}
+
+/** country code → [total length, BBAN segment encoding]. */
+const RAW: Readonly<Record<string, readonly [number, string]>> = {
+  AD: [24, '8n12c'], AE: [23, '19n'], AL: [28, '8n16c'], AT: [20, '16n'],
+  AZ: [28, '4a20c'], BA: [20, '16n'], BE: [16, '12n'], BG: [22, '4a6n8c'],
+  BH: [22, '4a14c'], BI: [27, '23n'], BR: [29, '23n1a1c'], BY: [28, '4c4n16c'],
+  CH: [21, '5n12c'], CR: [22, '18n'], CY: [28, '8n16c'], CZ: [24, '20n'],
+  DE: [22, '18n'], DJ: [27, '23n'], DK: [18, '14n'], DO: [28, '4c20n'],
+  EE: [20, '16n'], EG: [29, '25n'], ES: [24, '20n'], FI: [18, '14n'],
+  FK: [18, '2a12n'], FO: [18, '14n'], FR: [27, '10n11c2n'], GB: [22, '4a14n'],
+  GE: [22, '2a16n'], GI: [23, '4a15c'], GL: [18, '14n'], GR: [27, '7n16c'],
+  GT: [28, '4c20c'], HN: [28, '4a20n'], HR: [21, '17n'], HU: [28, '24n'],
+  IE: [22, '4a14n'], IL: [23, '19n'], IQ: [23, '4a15n'], IS: [26, '22n'],
+  IT: [27, '1a10n12c'], JO: [30, '4a4n18c'], KW: [30, '4a22c'], KZ: [20, '3n13c'],
+  LB: [28, '4n20c'], LC: [32, '4a24c'], LI: [21, '5n12c'], LT: [20, '16n'],
+  LU: [20, '3n13c'], LV: [21, '4a13c'], LY: [25, '21n'], MC: [27, '10n11c2n'],
+  MD: [24, '20c'], ME: [22, '18n'], MK: [19, '3n10c2n'], MN: [20, '16n'],
+  MR: [27, '23n'], MT: [31, '4a5n18c'], MU: [30, '4a19n3a'], NI: [28, '4a20n'],
+  NL: [18, '4a10n'], NO: [15, '11n'], OM: [23, '3n16c'], PK: [24, '4a16c'],
+  PL: [28, '24n'], PS: [29, '4a21c'], PT: [25, '21n'], QA: [29, '4a21c'],
+  RO: [24, '4a16c'], RS: [22, '18n'], RU: [33, '14n15c'], SA: [24, '2n18c'],
+  SC: [31, '4a20n3a'], SD: [18, '14n'], SE: [24, '20n'], SI: [19, '15n'],
+  SK: [24, '20n'], SM: [27, '1a10n12c'], SO: [23, '19n'], ST: [25, '21n'],
+  SV: [28, '4a20n'], TL: [23, '19n'], TN: [24, '20n'], TR: [26, '5n17c'],
+  UA: [29, '6n19c'], VA: [22, '18n'], VG: [24, '4a16n'], XK: [20, '16n'],
+};
+
+/** The compiled registry, one spec per IBAN country. */
+export const IBAN_REGISTRY: ReadonlyMap<string, IbanSpec> = new Map(
+  Object.entries(RAW).map(([code, [length, encoded]]) => [code, buildSpec(length, encoded)]),
+);
+
+/**
+ * IBANs published as documentation specimens (SWIFT registry examples and
+ * the ubiquitous tutorial values). Detected, classified non-sensitive.
+ */
+export const DOCUMENTATION_IBANS: ReadonlySet<string> = new Set([
+  'GB82WEST12345698765432',
+  'GB29NWBK60161331926819',
+  'DE89370400440532013000',
+  'DE75512108001245126199',
+  'FR1420041010050500013M02606',
+  'FR7630006000011234567890189',
+  'NL91ABNA0417164300',
+  'BE68539007547034',
+  'ES9121000418450200051332',
+  'IT60X0542811101000000123456',
+  'CH9300762011623852957',
+  'AT611904300234573201',
+  'TR330006100519786457841326',
+  'PL61109010140000071219812874',
+  'SE4550000000058398257466',
+  'DK5000400440116243',
+  'NO9386011117947',
+  'FI2112345600000785',
+]);

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

@@ -0,0 +1,6 @@
+/**
+ * Financial core family: cards, IBAN, BIC. Side-effect imports only.
+ */
+import './creditCard.js';
+import './iban.js';
+import './swiftBic.js';

package/src/detect/detectors/financial/swiftBic.ts

@@ -0,0 +1,61 @@
+/**
+ * SWIFT_BIC — structural validation against country and location code rules.
+ *
+ * ISO 9362: 4-letter bank code, 2-letter ISO country code, 2-character
+ * location code, optional 3-character branch. Location rules: the first
+ * location character must not be '0' or '1'; a location code whose SECOND
+ * character is '0' designates a TEST BIC (non-production) — detected but
+ * classified non-sensitive, like other known test values.
+ *
+ * A BIC has no checksum, and an 8-character uppercase English word whose
+ * characters happen to parse ("FEEDBACK" → bank FEED, country BA, location
+ * CK) is structurally a BIC. Confidence therefore reflects the evidence:
+ * MEDIUM for the bare all-letter 8-char form, HIGH when the BIC carries a
+ * digit or an explicit branch code, which English words do not.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+import { ISO_COUNTRY_CODES } from '../../isoCountries.js';
+
+function validateBic(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+  const bic = raw.toUpperCase();
+
+  const country = bic.slice(4, 6);
+  if (!ISO_COUNTRY_CODES.has(country)) return invalid('not an ISO country code');
+
+  const location = bic.slice(6, 8);
+  if (location[0] === '0' || location[0] === '1') {
+    return invalid('location code cannot begin with 0 or 1');
+  }
+
+  const branch = bic.length === 11 ? bic.slice(8) : undefined;
+  const hasDigit = /\d/.test(bic);
+  const isTest = location[1] === '0';
+
+  return valid({
+    canonical: bic,
+    sensitive: !isTest,
+    confidence: hasDigit || branch !== undefined ? CONFIDENCE.HIGH : CONFIDENCE.MEDIUM,
+    metadata: {
+      country,
+      ...(branch !== undefined ? { branch } : {}),
+      ...(isTest ? { test: true } : {}),
+    },
+    validator: 'bic-structural',
+  });
+}
+
+registerDetector({
+  id: 'swift-bic',
+  entityType: 'SWIFT_BIC',
+  regions: [GLOBAL_REGION],
+  // Uppercase only: BICs are written uppercase by standard, and admitting
+  // lowercase would sweep in ordinary 8-letter words.
+  pattern: /\b[A-Z]{6}[A-Z0-9]{2}(?:[A-Z0-9]{3})?\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'SWIFT/BIC codes: country and location rules; test BICs non-sensitive.',
+  validate: validateBic,
+});

package/src/detect/detectors/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Every Stage 1 detector family, loaded for registration side effects.
+ * Importing this module (directly or via the package root) populates the
+ * registry. One line per family; families grow by batch during M2.
+ */
+import './contact/index.js';
+import './financial/index.js';
+import './bankcodes/index.js';
+import './crypto/index.js';
+import './secrets/index.js';
+import './documents/index.js';
+import './location/index.js';
+import './natid/index.js';
+import './vat/index.js';

package/src/detect/detectors/location/coordinates.ts

@@ -0,0 +1,84 @@
+/**
+ * COORDINATES — latitude/longitude in decimal degrees and DMS.
+ *
+ * This one HAS a real validator (unlike its two siblings): parsed values
+ * must lie in [−90, 90] × [−180, 180]. DMS with its degree/minute/second
+ * marks is unmistakable → HIGH. A bare decimal pair is weaker evidence even
+ * in range — "3.141, 2.718" is a coordinate to no one — so decimal pairs
+ * demand ≥3 fraction digits (GPS-typical precision) and earn MEDIUM, with
+ * hemisphere suffixes lifting them to HIGH.
+ *
+ * (0, 0) — "null island" — is the classic placeholder and is rejected.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+const DECIMAL_PAIR =
+  /^(-?\d{1,3}\.\d{3,8})°?\s*([NS])?[,;]\s*(-?\d{1,3}\.\d{3,8})°?\s*([EW])?$/;
+
+// The seconds mark: detectors see NORMALIZED text, and NFKC decomposes
+// U+2033 DOUBLE PRIME into TWO U+2032 PRIMEs — so ″ arrives here as ′′.
+// Straight quotes pass normalization unchanged; curly ones become straight.
+const SECONDS = String.raw`(?:′′|''|″|")`;
+const DMS_ONE = String.raw`(\d{1,3})°\s?(\d{1,2})[′']\s?(\d{1,2}(?:\.\d+)?)${SECONDS}?\s?([NSEW])`;
+const DMS_PAIR = new RegExp(`^${DMS_ONE}[,;]?\\s*${DMS_ONE}$`);
+
+function validateCoordinates(ctx: ValidationContext): ValidationResult {
+  const value = ctx.match[0].trim();
+
+  const dms = DMS_PAIR.exec(value);
+  if (dms !== null) {
+    const first = dmsToDecimal(Number(dms[1]), Number(dms[2]), Number(dms[3]), dms[4]!);
+    const second = dmsToDecimal(Number(dms[5]), Number(dms[6]), Number(dms[7]), dms[8]!);
+    if (first === null || second === null) return invalid('DMS component out of range');
+    const lat = dms[4] === 'N' || dms[4] === 'S' ? first : second;
+    const lon = dms[4] === 'N' || dms[4] === 'S' ? second : first;
+    if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return invalid('coordinate out of range');
+    return valid({
+      confidence: CONFIDENCE.HIGH,
+      metadata: { format: 'dms', lat: round6(lat), lon: round6(lon) },
+      validator: 'coordinate-range',
+    });
+  }
+
+  const dec = DECIMAL_PAIR.exec(value);
+  if (dec !== null) {
+    let lat = Number(dec[1]);
+    let lon = Number(dec[3]);
+    if (dec[2] === 'S') lat = -lat;
+    if (dec[4] === 'W') lon = -lon;
+    if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return invalid('coordinate out of range');
+    if (lat === 0 && lon === 0) return invalid('null island placeholder');
+    const hasHemispheres = dec[2] !== undefined && dec[4] !== undefined;
+    return valid({
+      confidence: hasHemispheres ? CONFIDENCE.HIGH : CONFIDENCE.MEDIUM,
+      metadata: { format: 'decimal', lat: round6(lat), lon: round6(lon) },
+      validator: 'coordinate-range',
+    });
+  }
+
+  return invalid('not a coordinate pair');
+}
+
+function dmsToDecimal(deg: number, min: number, sec: number, hemi: string): number | null {
+  if (min >= 60 || sec >= 60) return null;
+  const value = deg + min / 60 + sec / 3600;
+  return hemi === 'S' || hemi === 'W' ? -value : value;
+}
+
+const round6 = (n: number): number => Math.round(n * 1e6) / 1e6;
+
+registerDetector({
+  id: 'coordinates',
+  entityType: 'COORDINATES',
+  regions: [GLOBAL_REGION],
+  // Hemisphere letters are grouped WITH their leading space so that an
+  // absent hemisphere cannot leave a trailing space inside the span.
+  pattern:
+    /(?<![\d.])(?:-?\d{1,3}\.\d{3,8}°?(?: ?[NS])?[,;]\s*-?\d{1,3}\.\d{3,8}°?(?: ?[EW])?|\d{1,3}° ?\d{1,2}[′'] ?\d{1,2}(?:\.\d+)?(?:′′|''|″|")? ?[NSEW][,;]? ?\d{1,3}° ?\d{1,2}[′'] ?\d{1,2}(?:\.\d+)?(?:′′|''|″|")? ?[NSEW])(?![\d.])/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Lat/long pairs in decimal (≥3 fraction digits) and DMS, range-validated.',
+  validate: validateCoordinates,
+});

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

@@ -0,0 +1,6 @@
+/**
+ * Location family. Side-effect imports only.
+ */
+import './postalCode.js';
+import './streetAddress.js';
+import './coordinates.js';