@discretion/core 0.1.0

package/src/detect/detectors/bankcodes/brAgencia.ts

@@ -0,0 +1,46 @@
+/**
+ * BR_AGENCIA — Brazilian bank branch codes.
+ *
+ * A bare four-digit agência is indistinguishable from any other four-digit
+ * number, and its optional check digit follows PER-BANK rules (Banco do
+ * Brasil mod-11, Bradesco a mod-10 variant) that cannot be verified without
+ * knowing the bank. So the FORMAT here includes the label — "ag.", "agência",
+ * "agencia" — which is part of how the identifier is actually written, the
+ * same way a URL's scheme is part of a URL. This is not Stage 3 context
+ * scoring; it is the notation. The span is narrowed to the number so the
+ * label is never masked. MEDIUM: the label plus shape is real evidence, but
+ * no checksum was verified.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function validateAgencia(ctx: ValidationContext): ValidationResult {
+  const raw = ctx.match[0];
+  const numberPart = ctx.match[1];
+  if (numberPart === undefined) return invalid('no branch number captured');
+
+  const numberStart = ctx.start + raw.lastIndexOf(numberPart);
+  const after = ctx.text[ctx.end];
+  if (after !== undefined && /[\d-]/.test(after)) return invalid('fragment of a longer sequence');
+
+  const [branch, check] = numberPart.split('-') as [string, string | undefined];
+  return valid({
+    canonical: numberPart,
+    metadata: { branch, ...(check !== undefined ? { checkDigit: check } : {}) },
+    validator: 'agencia-labeled',
+    span: { start: numberStart, end: ctx.start + raw.length },
+  });
+}
+
+registerDetector({
+  id: 'br-agencia',
+  entityType: 'BR_AGENCIA',
+  regions: ['BR'],
+  // The label is part of the notation; accents survive normalization.
+  pattern: /\b[Aa]g(?:ência|encia|\.)?\s*:?\s*(\d{4}(?:-\d)?)\b/gu,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Brazilian agência branch codes in their labeled notation; span covers the number only.',
+  validate: validateAgencia,
+});

package/src/detect/detectors/bankcodes/caTransit.ts

@@ -0,0 +1,89 @@
+/**
+ * CA_TRANSIT_NUMBER — Canadian branch transit in the paper (MICR) writing:
+ * 5-digit branch, hyphen, 3-digit institution.
+ *
+ * No public checksum covers the branch number, so validation rests on the
+ * institution number, which IS a closed set — the Payments Canada financial
+ * institution numbers. The list below carries the chartered banks, Crown
+ * institutions, and the major trust/credit-union centrals that appear in
+ * practice. Membership → MEDIUM (a real table check, but not a checksum);
+ * an unknown institution number is a rejection, not a low-confidence hit.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+/** Payments Canada institution numbers in active use. */
+const INSTITUTIONS: ReadonlySet<string> = new Set([
+  '001', // Bank of Montreal
+  '002', // Scotiabank
+  '003', // RBC
+  '004', // TD
+  '006', // National Bank
+  '010', // CIBC
+  '016', // HSBC Canada
+  '030', // Canadian Western Bank
+  '039', // Laurentian
+  '117', // Government of Canada
+  '127', // Canada Post (money orders)
+  '177', // Bank of Canada
+  '219', // ATB Financial
+  '241', // Bank of America Canada
+  '245', // Bank of Tokyo-Mitsubishi
+  '260', // Citibank Canada
+  '265', // Deutsche Bank Canada
+  '269', // Mega International
+  '270', // JPMorgan Chase Canada
+  '290', // UBS Canada
+  '308', // Bank of China Canada
+  '309', // Vancity (Citizens)
+  '326', // President's Choice
+  '338', // Canadian Tire Bank
+  '340', // ICICI Canada
+  '509', // Canada Trust
+  '540', // Manulife Bank
+  '568', // Peace Hills Trust
+  '614', // Tangerine
+  '621', // KEB Hana Canada
+  '623', // EQ Bank / Equitable
+  '618', // B2B Bank
+  '809', // Central 1 (BC)
+  '815', // Desjardins (QC)
+  '819', // Desjardins (MB)
+  '828', // Central 1 (ON)
+  '829', // Desjardins (ON)
+  '837', // Meridian
+  '839', // Credit Union Atlantic
+  '849', // Brunswick Credit Union
+  '865', // Desjardins (Caisse populaire)
+  '879', // Credit Union Central MB
+  '889', // Credit Union Central SK
+  '899', // Alberta Central
+]);
+
+function validateTransit(ctx: ValidationContext): ValidationResult {
+  const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+  if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer sequence');
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^\d/.test(after) || /^-\d/.test(after)) return invalid('fragment of a longer sequence');
+
+  const [branch, institution] = ctx.match[0].split('-') as [string, string];
+  if (!INSTITUTIONS.has(institution)) return invalid('unknown institution number');
+
+  return valid({
+    canonical: `${branch}-${institution}`,
+    metadata: { branch, institution },
+    validator: 'transit-institution-table',
+  });
+}
+
+registerDetector({
+  id: 'ca-transit-number',
+  entityType: 'CA_TRANSIT_NUMBER',
+  regions: ['CA'],
+  pattern: /\b\d{5}-\d{3}\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'Canadian branch-institution transit numbers, institution validated against the Payments Canada table.',
+  validate: validateTransit,
+});

package/src/detect/detectors/bankcodes/inIfsc.ts

@@ -0,0 +1,40 @@
+/**
+ * IN_IFSC — Indian Financial System Codes.
+ *
+ * Structure: 4 uppercase letters (bank), a MANDATORY '0' (reserved fifth
+ * character), 6 alphanumerics (branch). The fixed zero at position five is
+ * what makes this format strong: no English word or acronym has that shape,
+ * so unlike SWIFT BICs the all-letter collision class is empty and HIGH
+ * confidence is warranted despite the absence of a checksum. A bank-code
+ * whitelist was considered and rejected — the RBI issues new bank codes
+ * routinely, and a stale table would silently reject real branches.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function validateIfsc(ctx: ValidationContext): ValidationResult {
+  const code = ctx.match[0];
+  // The branch part must not be all letters: real branch codes carry at
+  // least one digit, and requiring it removes the residual word-shaped
+  // collisions (e.g. an uppercase heading "ABCD0EFGHI" would need exactly
+  // this test to sneak through).
+  if (!/\d/.test(code.slice(5))) return invalid('branch code carries no digit');
+
+  return valid({
+    canonical: code,
+    metadata: { bank: code.slice(0, 4), branch: code.slice(5) },
+    validator: 'ifsc-structural',
+  });
+}
+
+registerDetector({
+  id: 'in-ifsc',
+  entityType: 'IN_IFSC',
+  regions: ['IN'],
+  pattern: /\b[A-Z]{4}0[A-Z0-9]{6}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Indian IFSC codes: four letters, the mandatory reserved zero, six-character branch.',
+  validate: validateIfsc,
+});

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

@@ -0,0 +1,9 @@
+/**
+ * National bank-code family. Side-effect imports only.
+ */
+import './usRouting.js';
+import './ukSortCode.js';
+import './caTransit.js';
+import './auBsb.js';
+import './inIfsc.js';
+import './brAgencia.js';

package/src/detect/detectors/bankcodes/ukSortCode.ts

@@ -0,0 +1,38 @@
+/**
+ * UK_SORT_CODE — six digits in the conventional 00-00-00 writing.
+ *
+ * NO CHECKSUM EXISTS for sort codes, so this is a structural detector and
+ * is capped at MEDIUM by design — SPEC.md forbids high confidence without a
+ * validator, and no validator is possible. Only the hyphenated form is
+ * matched: a bare six-digit run ("123456") is any quantity in the world,
+ * while the 2-2-2 hyphenation is the standard banking notation and rarely
+ * anything else. Stage 3 trigger evidence ("sort code", "acct") is what
+ * will raise or suppress these later.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function validateSortCode(ctx: ValidationContext): ValidationResult {
+  const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+  if (/[\d-]/.test(before ?? '')) return invalid('fragment of a longer sequence');
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^\d/.test(after) || /^-\d/.test(after)) return invalid('fragment of a longer sequence');
+
+  const digits = ctx.match[0].replace(/-/g, '');
+  return valid({
+    canonical: digits,
+    validator: 'sort-code-structural',
+  });
+}
+
+registerDetector({
+  id: 'uk-sort-code',
+  entityType: 'UK_SORT_CODE',
+  regions: ['GB'],
+  pattern: /\b\d{2}-\d{2}-\d{2}\b/g,
+  baseConfidence: CONFIDENCE.MEDIUM,
+  description: 'UK sort codes in 00-00-00 notation. No checksum exists; capped at MEDIUM.',
+  validate: validateSortCode,
+});

package/src/detect/detectors/bankcodes/usRouting.ts

@@ -0,0 +1,47 @@
+/**
+ * US_ROUTING_NUMBER — ABA checksum plus Federal Reserve prefix ranges.
+ *
+ * The checksum (shared library) is necessary but weak alone: one in ten
+ * arbitrary 9-digit runs passes. The first two digits must also be a real
+ * Federal Reserve routing symbol — 01–12 (primary districts), 21–32
+ * (thrift institutions), 61–72 (electronic transaction identifiers), 80
+ * (traveler's cheques). 00 is excluded deliberately: 000000000 sums to an
+ * ABA-valid zero but routes nowhere.
+ */
+
+import { abaValid } from '../../../checksums/index.js';
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+function prefixValid(p: number): boolean {
+  return (p >= 1 && p <= 12) || (p >= 21 && p <= 32) || (p >= 61 && p <= 72) || p === 80;
+}
+
+function validateRouting(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 digits = ctx.match[0];
+  const prefix = Number(digits.slice(0, 2));
+  if (!prefixValid(prefix)) return invalid('not a Federal Reserve routing prefix');
+  if (!abaValid(digits)) return invalid('ABA checksum failed');
+
+  return valid({
+    canonical: digits,
+    metadata: { prefix },
+    validator: 'aba-frb-prefix',
+  });
+}
+
+registerDetector({
+  id: 'us-routing-number',
+  entityType: 'US_ROUTING_NUMBER',
+  regions: ['US'],
+  pattern: /\b\d{9}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'US ABA routing numbers: checksum plus Federal Reserve prefix validation.',
+  validate: validateRouting,
+});

package/src/detect/detectors/contact/email.ts

@@ -0,0 +1,113 @@
+/**
+ * EMAIL — structural validation, IDN/punycode aware.
+ *
+ * SPEC.md: "EMAIL — structural validation, IDN/punycode aware, reject
+ * reserved example domains at high confidence." "Reject" there means reject
+ * as SENSITIVE: an address at example.com is detected (so eval can see it)
+ * but classified non-sensitive, the same treatment as test credit cards.
+ *
+ * The pattern over-generates: it accepts any plausible local@domain.tld run,
+ * including Unicode letters on both sides (IDN). The validator applies the
+ * structural rules that matter for precision — label lengths, hyphen and dot
+ * placement, TLD plausibility — rather than attempting full RFC 5322, whose
+ * grammar admits addresses no mail system accepts.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+/**
+ * Reserved names that can never be a real deliverable domain (RFC 2606 /
+ * RFC 6761). Addresses here are documentation examples: detected, but
+ * non-sensitive.
+ */
+const RESERVED_SECOND_LEVEL = new Set(['example.com', 'example.net', 'example.org']);
+const RESERVED_TLDS = new Set(['test', 'example', 'invalid', 'localhost']);
+
+/** atext (RFC 5322) plus Unicode letters/digits for EAI local parts. */
+const UNQUOTED_LOCAL = /^[\p{L}\p{N}!#$%&'*+/=?^_`{|}~.-]+$/u;
+
+/** One domain label: letters/digits with interior hyphens. */
+const LABEL = /^[\p{L}\p{N}](?:[\p{L}\p{N}-]*[\p{L}\p{N}])?$/u;
+
+/** Punycode labels must be pure LDH after the xn-- prefix. */
+const PUNYCODE_LABEL = /^xn--[a-z0-9-]+$/;
+
+function validateEmail(ctx: ValidationContext): ValidationResult {
+  let start = ctx.start;
+  const end = ctx.end;
+  let raw = ctx.text.slice(start, end);
+
+  // Sentence punctuation and quoting absorb into the local part because '.'
+  // and '\'' are legal atext: «Contact: .john@x.com» or «'john@x.com'».
+  // Trim from the left and narrow the span. Interior dots/apostrophes
+  // (o'brien@…) are untouched.
+  while (raw.length > 0 && (raw[0] === '.' || raw[0] === "'")) {
+    raw = raw.slice(1);
+    start += 1;
+  }
+
+  if (raw.length > 254) return invalid('address exceeds 254 characters');
+
+  const at = raw.lastIndexOf('@');
+  if (at <= 0 || at === raw.length - 1) return invalid('missing local part or domain');
+  const local = raw.slice(0, at);
+  const domain = raw.slice(at + 1);
+
+  // Local part: quoted string or dot-atom.
+  if (local.startsWith('"') && local.endsWith('"') && local.length >= 3) {
+    if (local.length > 64) return invalid('local part exceeds 64 characters');
+  } else {
+    if (local.length > 64) return invalid('local part exceeds 64 characters');
+    if (!UNQUOTED_LOCAL.test(local)) return invalid('illegal character in local part');
+    if (local.startsWith('.') || local.endsWith('.')) return invalid('local part begins or ends with a dot');
+    if (local.includes('..')) return invalid('consecutive dots in local part');
+  }
+
+  // Domain: dot-separated labels, each individually checked.
+  const domainLower = domain.toLowerCase();
+  const labels = domainLower.split('.');
+  if (labels.length < 2) return invalid('domain has no top-level label');
+  for (const label of labels) {
+    if (label.length === 0 || label.length > 63) return invalid('domain label length out of range');
+    if (label.startsWith('xn--')) {
+      if (!PUNYCODE_LABEL.test(label)) return invalid('malformed punycode label');
+      continue;
+    }
+    if (!LABEL.test(label)) return invalid('malformed domain label');
+  }
+  const tld = labels[labels.length - 1]!;
+  if (tld.length < 2 && !tld.startsWith('xn--')) return invalid('implausible top-level domain');
+  if (/^[0-9]+$/.test(tld)) return invalid('all-numeric top-level domain');
+
+  // Reserved documentation domains: detected, classified non-sensitive.
+  const lastTwo = labels.slice(-2).join('.');
+  const reserved = RESERVED_TLDS.has(tld) || RESERVED_SECOND_LEVEL.has(lastTwo);
+
+  const hasUnicode = !/^[\x20-\x7e]*$/.test(raw);
+
+  return valid({
+    canonical: `${local}@${domainLower}`,
+    sensitive: !reserved,
+    metadata: {
+      domain: domainLower,
+      idn: hasUnicode,
+      punycode: labels.some((l) => l.startsWith('xn--')),
+      ...(reserved ? { reserved: true } : {}),
+    },
+    validator: 'email-structural',
+    span: { start, end },
+  });
+}
+
+registerDetector({
+  id: 'email',
+  entityType: 'EMAIL',
+  regions: [GLOBAL_REGION],
+  pattern:
+    /(?:"[^"\r\n]{1,62}"|[\p{L}\p{N}!#$%&'*+/=?^_`{|}~.-]+)@[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?(?:\.[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?)+/gu,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'Email addresses, IDN/punycode aware; example-domain addresses non-sensitive.',
+  validate: validateEmail,
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Contact & network detector family. Side-effect imports only — each file
+ * registers itself (see ../../AUTHORING.md).
+ */
+import './email.js';
+import './phone.js';
+import './ipv4.js';
+import './ipv6.js';
+import './mac.js';
+import './urlCredentials.js';

package/src/detect/detectors/contact/ipv4.ts

@@ -0,0 +1,112 @@
+/**
+ * IP_ADDRESS (IPv4) — valid-range checking with scope classification.
+ *
+ * SPEC.md: "IP_ADDRESS — v4 and v6 with valid-range checking;
+ * private/reserved ranges classified separately and lower sensitivity by
+ * default." Scope drives both metadata and confidence: a routable public
+ * address is a strong signal; a 10.x.x.x reveals only that someone has a
+ * LAN. The TEST-NET documentation ranges are non-sensitive by construction —
+ * they exist so that documentation can contain addresses.
+ */
+
+import { registerDetector } from '../../registry.js';
+import { CONFIDENCE, GLOBAL_REGION, invalid, valid } from '../../types.js';
+import type { ValidationContext, ValidationResult } from '../../types.js';
+
+type Ipv4Scope =
+  | 'public'
+  | 'private'
+  | 'loopback'
+  | 'link-local'
+  | 'cgn'
+  | 'documentation'
+  | 'benchmarking'
+  | 'multicast'
+  | 'reserved'
+  | 'broadcast'
+  | 'unspecified'
+  | 'this-network';
+
+function classify(o: readonly [number, number, number, number]): Ipv4Scope {
+  const [a, b, c] = o;
+  if (a === 0) return o.every((x) => x === 0) ? 'unspecified' : 'this-network';
+  if (a === 10) return 'private';
+  if (a === 100 && b >= 64 && b <= 127) return 'cgn';
+  if (a === 127) return 'loopback';
+  if (a === 169 && b === 254) return 'link-local';
+  if (a === 172 && b >= 16 && b <= 31) return 'private';
+  if (a === 192 && b === 0 && c === 2) return 'documentation'; // TEST-NET-1
+  if (a === 192 && b === 168) return 'private';
+  if (a === 198 && (b === 18 || b === 19)) return 'benchmarking';
+  if (a === 198 && b === 51 && c === 100) return 'documentation'; // TEST-NET-2
+  if (a === 203 && b === 0 && c === 113) return 'documentation'; // TEST-NET-3
+  if (a >= 224 && a <= 239) return 'multicast';
+  if (o[0] === 255 && o[1] === 255 && o[2] === 255 && o[3] === 255) return 'broadcast';
+  if (a >= 240) return 'reserved';
+  return 'public';
+}
+
+function validateIpv4(ctx: ValidationContext): ValidationResult {
+  // Reject dotted runs that are fragments of something longer: a version
+  // string ("v1.2.3.4"), a 5-part sequence ("1.2.3.4.5"), or a decimal
+  // neighbourhood. \b cannot see these, so the validator looks around.
+  const before = ctx.start > 0 ? ctx.text[ctx.start - 1] : '';
+  if (before === '.' || before === 'v' || before === 'V' || /\d/.test(before ?? '')) {
+    return invalid('embedded in a longer dotted sequence');
+  }
+  const after = ctx.text.slice(ctx.end, ctx.end + 2);
+  if (/^\.\d/.test(after)) return invalid('embedded in a longer dotted sequence');
+
+  const parts = ctx.match[0].split('.');
+  if (parts.length !== 4) return invalid('not four octets');
+  const octets: number[] = [];
+  for (const p of parts) {
+    if (p.length === 0 || p.length > 3) return invalid('octet length out of range');
+    const v = Number(p);
+    if (!Number.isInteger(v) || v < 0 || v > 255) return invalid('octet out of range');
+    octets.push(v);
+  }
+  const o = octets as unknown as readonly [number, number, number, number];
+  const scope = classify(o);
+
+  // Canonical form strips zero-padding ("192.168.001.001" → "192.168.1.1")
+  // so log-formatted and plain writings of one address share a vault entry.
+  const canonical = o.join('.');
+
+  if (scope === 'documentation') {
+    return valid({
+      canonical,
+      sensitive: false,
+      confidence: CONFIDENCE.MEDIUM,
+      metadata: { version: 4, scope },
+      validator: 'ipv4-range',
+    });
+  }
+  if (scope === 'broadcast' || scope === 'unspecified') {
+    // Well-known constants; identifying nothing.
+    return valid({
+      canonical,
+      sensitive: false,
+      confidence: CONFIDENCE.LOW,
+      metadata: { version: 4, scope },
+      validator: 'ipv4-range',
+    });
+  }
+  const isPublic = scope === 'public';
+  return valid({
+    canonical,
+    confidence: isPublic ? CONFIDENCE.HIGH : CONFIDENCE.MEDIUM,
+    metadata: { version: 4, scope },
+    validator: 'ipv4-range',
+  });
+}
+
+registerDetector({
+  id: 'ip-v4',
+  entityType: 'IP_ADDRESS',
+  regions: [GLOBAL_REGION],
+  pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+  baseConfidence: CONFIDENCE.HIGH,
+  description: 'IPv4 addresses with range validation; private/reserved scopes classified at lower confidence.',
+  validate: validateIpv4,
+});