euredact 0.1.0 → 0.3.0

package/dist/esm/rules/engine.js

@@ -1,11 +1,69 @@
-import { DetectionSource } from "../types.js";
+import { DetectionSource, EntityType } from "../types.js";
 import { MultiPatternMatcher } from "./matchers.js";
 import { shouldSuppress } from "./suppressors.js";
 import { detectStructuralDob } from "./structural.js";
 import { COUNTRY_CONFIGS } from "./countries/index.js";
+/**
+ * Heuristic to detect nested quantifiers that cause catastrophic backtracking.
+ * After stripping escaped chars and character classes, look for an unbounded
+ * quantifier (+/*) closing a group that is itself quantified (+/*).
+ */
+const NESTED_QUANTIFIER_RE = /[+*]\)[+*]/;
+function validateCustomPattern(pattern) {
+    try {
+        new RegExp(pattern, "gu");
+    }
+    catch (e) {
+        throw new Error(`Invalid regex pattern: ${e instanceof Error ? e.message : e}`);
+    }
+    const stripped = pattern
+        .replace(/\\./g, "X")
+        .replace(/\[(?:[^\]\\]|\\.)*\]/g, "X");
+    if (NESTED_QUANTIFIER_RE.test(stripped)) {
+        throw new Error("Pattern contains nested quantifiers (e.g. (a+)+) which can cause " +
+            "catastrophic backtracking (ReDoS). Restructure the pattern to " +
+            "avoid quantifiers inside quantified groups.");
+    }
+}
+/**
+ * The country modules use the EU/VAT convention (UK, EL) while the public
+ * contract is ISO 3166-1 alpha-2 (GB, GR). Accept both spellings so a caller
+ * passing correct ISO codes is not punished for it.
+ */
+export const COUNTRY_CODE_ALIASES = {
+    GB: "UK",
+    GR: "EL",
+    UK: "UK",
+    EL: "EL",
+};
+/** Map a caller-supplied code to a registered one, or null if unknown. */
+export function resolveCountryCode(countryCode) {
+    let code = countryCode.trim().toUpperCase();
+    code = COUNTRY_CODE_ALIASES[code] ?? code;
+    return code in COUNTRY_CONFIGS && code !== "SHARED" ? code : null;
+}
+const warnedCountries = new Set();
+function warnUnknownCountry(code) {
+    if (warnedCountries.has(code))
+        return;
+    warnedCountries.add(code);
+    const available = Object.keys(COUNTRY_CONFIGS).filter(c => c !== "SHARED").sort();
+    console.warn(`[euredact] Unknown country code: ${JSON.stringify(code)}. Continuing with ` +
+        `shared country-independent patterns only (email, IBAN, international ` +
+        `phone, credit card, ...). Available: ${available.join(", ")}`);
+}
 export class RuleEngine {
     matcher = new MultiPatternMatcher();
     loadedCountries = new Set();
+    addCustomPattern(name, pattern) {
+        validateCustomPattern(pattern);
+        const pdef = {
+            entityType: name, pattern, validator: null,
+            description: "", contextKeywords: [], requiresContext: false,
+        };
+        this.matcher.addPattern(pdef, "CUSTOM");
+        this.matcher.compile();
+    }
     loadCountries(countryCodes) {
         let configs;
         if (countryCodes === null) {
@@ -14,11 +72,18 @@ export class RuleEngine {
         else {
             configs = [];
             for (const c of countryCodes) {
-                const code = c.toUpperCase();
+                const code = resolveCountryCode(c);
+                if (code === null) {
+                    // Detection continues with the shared, country-independent
+                    // patterns. Throwing on an unknown locale invites callers to wrap
+                    // the call in try/catch and skip redaction — failing open, with
+                    // unredacted PII in the output.
+                    warnUnknownCountry(c);
+                    continue;
+                }
                 const config = COUNTRY_CONFIGS[code];
                 if (config)
                     configs.push(config);
-                // Silently skip unknown country codes (e.g. "INTL")
             }
             const shared = COUNTRY_CONFIGS["SHARED"];
             if (shared)
@@ -37,44 +102,131 @@ export class RuleEngine {
     }
     detect(text, countryCodes) {
         this.loadCountries(countryCodes);
-        let rawMatches = this.matcher.scan(text);
+        // Scope the scan to requested countries for efficiency
+        // Resolve through the alias table so `countries: ["GB"]` actually scans
+        // the patterns registered under "UK".
+        let scanCodes = null;
         if (countryCodes !== null) {
-            const codesUpper = new Set(countryCodes.map(c => c.toUpperCase()));
-            rawMatches = rawMatches.filter(m => codesUpper.has(m.countryCode) || m.countryCode === "SHARED");
+            scanCodes = new Set();
+            for (const c of countryCodes) {
+                const code = resolveCountryCode(c);
+                if (code !== null)
+                    scanCodes.add(code);
+            }
+            scanCodes.add("SHARED");
+            scanCodes.add("CUSTOM");
         }
-        const validated = rawMatches.filter(m => this.matcher.validate(m));
-        const detections = [];
-        for (const match of validated) {
+        let rawMatches = this.matcher.scan(text, scanCodes);
+        // Matches that have a validator but fail it create suppression zones:
+        // the span is recognisably a specific entity (e.g. IBAN-shaped) so
+        // overlapping regex-only matches (license plate, phone) are false
+        // positives and must be suppressed.
+        const validated = [];
+        const rawZones = [];
+        for (const m of rawMatches) {
+            const isValid = this.matcher.validate(m);
+            if (isValid) {
+                validated.push({ match: m, hasValidValidator: m.patternDef.validator !== null });
+            }
+            else if (m.patternDef.validator !== null && !m.patternDef.requiresContext) {
+                rawZones.push([m.start, m.end]);
+            }
+        }
+        // Merge overlapping suppression zones for O(log n) containment checks
+        let zoneStarts = [];
+        let zoneEnds = [];
+        if (rawZones.length > 0) {
+            rawZones.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+            let [ms, me] = rawZones[0];
+            for (let i = 1; i < rawZones.length; i++) {
+                const [zs, ze] = rawZones[i];
+                if (zs <= me) {
+                    me = Math.max(me, ze);
+                }
+                else {
+                    zoneStarts.push(ms);
+                    zoneEnds.push(me);
+                    ms = zs;
+                    me = ze;
+                }
+            }
+            zoneStarts.push(ms);
+            zoneEnds.push(me);
+        }
+        // Build candidates with priority: validated (3) > custom (2) > regex-only (1)
+        const candidates = [];
+        for (const { match, hasValidValidator } of validated) {
             if (shouldSuppress(text, match))
                 continue;
-            detections.push({
-                entityType: match.patternDef.entityType,
-                start: match.start,
-                end: match.end,
-                text: match.text,
-                source: DetectionSource.RULES,
-                country: match.countryCode !== "SHARED" ? match.countryCode : null,
-                confidence: "high",
+            // O(log n) binary-search containment check on merged zones
+            if (match.patternDef.validator === null && zoneStarts.length > 0) {
+                let lo = 0, hi = zoneStarts.length;
+                while (lo < hi) {
+                    const mid = (lo + hi) >>> 1;
+                    if (zoneStarts[mid] <= match.start)
+                        lo = mid + 1;
+                    else
+                        hi = mid;
+                }
+                const idx = lo - 1;
+                if (idx >= 0 && zoneEnds[idx] >= match.end)
+                    continue;
+            }
+            // A bare digit run is the weakest evidence in the engine and must never
+            // re-cut a span a structured detector claims (PHONE, SSN, NATIONAL_ID,
+            // BANK_ACCOUNT, VAT...). Postal codes take unclaimed spans only,
+            // whatever the span lengths.
+            const priority = hasValidValidator
+                ? 3
+                : match.countryCode === "CUSTOM"
+                    ? 2
+                    : match.patternDef.entityType === EntityType.POSTAL_CODE
+                        ? 0
+                        : 1;
+            const spanLength = match.end - match.start;
+            const score = priority * 1_000_000 + spanLength;
+            candidates.push({
+                det: {
+                    entityType: match.patternDef.entityType,
+                    start: match.start,
+                    end: match.end,
+                    text: match.text,
+                    source: DetectionSource.RULES,
+                    country: (match.countryCode !== "SHARED" && match.countryCode !== "CUSTOM") ? match.countryCode : null,
+                    confidence: "high",
+                },
+                score,
             });
         }
-        detections.push(...detectStructuralDob(text));
-        return this.deduplicate(detections);
+        for (const d of detectStructuralDob(text)) {
+            candidates.push({ det: d, score: 1_000_000 + (d.end - d.start) });
+        }
+        return this.deduplicate(candidates);
     }
-    deduplicate(detections) {
-        if (detections.length === 0)
-            return detections;
-        const sorted = [...detections].sort((a, b) => a.start - b.start || (b.end - b.start) - (a.end - a.start));
+    /**
+     * Remove overlapping detections with priority-aware resolution.
+     * Priority: validated (3) > custom (2) > regex-only (1).
+     * Within the same tier, longer span wins.
+     */
+    deduplicate(candidates) {
+        if (candidates.length === 0)
+            return [];
+        const sorted = [...candidates].sort((a, b) => b.score - a.score);
         const result = [];
-        for (const det of sorted) {
+        const occupied = new Set();
+        for (const { det } of sorted) {
             let overlaps = false;
-            for (const kept of result) {
-                if (det.start < kept.end && det.end > kept.start) {
+            for (let p = det.start; p < det.end; p++) {
+                if (occupied.has(p)) {
                     overlaps = true;
                     break;
                 }
             }
-            if (!overlaps)
+            if (!overlaps) {
+                for (let p = det.start; p < det.end; p++)
+                    occupied.add(p);
                 result.push(det);
+            }
         }
         return result;
     }

package/dist/esm/rules/matchers.d.ts

@@ -1,11 +1,12 @@
-import type { CountryConfig } from "../types.js";
+import type { CountryConfig, PatternDef } from "../types.js";
 import type { RawMatch } from "./suppressors.js";
 export type { RawMatch };
 export declare class MultiPatternMatcher {
     private patterns;
     private compiled;
+    addPattern(patternDef: PatternDef, countryCode: string): void;
     addCountry(config: CountryConfig): void;
     compile(): void;
-    scan(text: string): RawMatch[];
+    scan(text: string, countryCodes?: Set<string> | null): RawMatch[];
     validate(match: RawMatch): boolean;
 }

package/dist/esm/rules/matchers.js

@@ -2,6 +2,11 @@ import { VALIDATORS } from "./validators.js";
 export class MultiPatternMatcher {
     patterns = [];
     compiled = false;
+    addPattern(patternDef, countryCode) {
+        const regex = new RegExp(patternDef.pattern, "gu");
+        this.patterns.push({ regex, patternDef, countryCode });
+        this.compiled = false;
+    }
     addCountry(config) {
         for (const pdef of config.patterns) {
             // Convert Python-style \b word boundaries — JS handles them natively
@@ -14,11 +19,13 @@ export class MultiPatternMatcher {
     compile() {
         this.compiled = true;
     }
-    scan(text) {
+    scan(text, countryCodes = null) {
         if (!this.compiled)
             this.compile();
         const matches = [];
         for (const { regex, patternDef, countryCode } of this.patterns) {
+            if (countryCodes !== null && !countryCodes.has(countryCode))
+                continue;
             regex.lastIndex = 0;
             let m;
             while ((m = regex.exec(text)) !== null) {

package/dist/esm/rules/suppressors.js

@@ -1,4 +1,5 @@
 import { EntityType } from "../types.js";
+import { isRegisteredBic } from "./bicRegistry.js";
 const CONTEXT_CHARS = 150;
 function getContext(text, start, end) {
     const ctxStart = Math.max(0, start - CONTEXT_CHARS);
@@ -18,12 +19,14 @@ const REFERENCE_BEFORE = /(?:dossier|ref\.?|referentie|reference|référence|fac
 const LEGAL_BEFORE = /(?:Art(?:ikel|icle|\.)|§|Artikel|Section|Sectie|Afdeling|paragraaf|Absatz|alinéa|punt|point|Punkt|lid)\s*$/i;
 const MATH_BEFORE = /[=+\-×÷*/]\s*$/;
 const MATH_AFTER = /^\s*[=+\-×÷*/]/;
+// "A-1010", "B-2000", "L-1234", "CH-8000", "D-10115": a country prefix on a
+// postal code, not a minus sign.
+const COUNTRY_PREFIX_HYPHEN = /(?:^|[^A-Za-z0-9])[A-Z]{1,2}-\s*$/;
 const SEQUENTIAL_PATTERNS = /^(?:0{6,}|1234567890?|0123456789|9876543210?|1111111111?|000000000|123456789)$/;
-const YEAR_PATTERN = /^(?:19[4-9]\d|20[0-3]\d)$/;
-const DATE_KEYWORD_NEAR = /(?:jaar|year|année|Jahr|datum|date|Datum|in\s+\d{4}|since|sinds|depuis|seit|født|fødselsdato|fødsel|Fødselsdato|född|födelsedatum|födelsedag|syntynyt|syntymäaika|fæddur|fæðingardagur|\d{2}\.\d{2}\.|(?:januar|februar|marts|april|maj|juni|juli|august|september|oktober|november|december|januari|februari|mars|april|mei|juin|juillet|août|Tiltr[æa]delsesdato|Tiltredelsesdato))/i;
+// YEAR_PATTERN kept for reference but replaced by RECENT_YEAR in suppressYearAsPostal
 const ID_LABEL_BEFORE = /(?:BSN|RR|NN|NIR|INSZ|NISS|NIS|Steuer-?ID|TIN|NIF|NIE|SSN|rijksregisternummer|numéro\s*national|national\s*number|matricule|Ausweisnummer|Personalausweis|Versichertennummer|KVNR|KV-Nr|Steuernummer|St\.\-Nr|StNr|Finanzamt\s+ist|Ondernemingen\s+onder\s+nummer|ondernemingsnummer|numéro\s*d'entreprise|enterprise\s*number|Kruispuntbank)\s*[:.]?\s*$/i;
 const SERVICE_NUMBER = /^0800[\-\s]/;
-const DATE_PATTERN_FULL = /^\d{2}[-/.]\d{2}[-/.]\d{4}$/;
+const DATE_PATTERN_FULL = /^\d{2}[-/.]\d{2}[-/.]\d{4}$|^\d{4}[-/.]\d{2}[-/.]\d{2}$/;
 const PASSPORT_CONTEXT_BEFORE = /(?:Reisepass|passport|passeport|paspoort|Bisheriger\s+Reisepass)\s*(?:Nr\.?|Nummer|nummer|number|n[°o])?\s*[:.]?\s*$/i;
 const SE_ORG_CONTEXT_BEFORE = /(?:org\.?\s*nr\.?|organisationsnummer|organisationsnr|Bolagsverket|företag)\s*[:.]?\s*$/i;
 const NUMERIC_TYPES = new Set([EntityType.PHONE, EntityType.NATIONAL_ID, EntityType.SSN, EntityType.TAX_ID, EntityType.POSTAL_CODE]);
@@ -63,23 +66,40 @@ function suppressMath(text, match) {
     if (!NUMERIC_TYPES.has(match.patternDef.entityType))
         return false;
     const [before, after] = getContext(text, match.start, match.end);
+    // A country-prefixed postal code is an address, not a subtraction:
+    // "A-1010 Wien", "B-2000 Antwerpen", "D-10115 Berlin".
+    if (match.patternDef.entityType === EntityType.POSTAL_CODE && COUNTRY_PREFIX_HYPHEN.test(before)) {
+        return false;
+    }
     return MATH_BEFORE.test(before) || MATH_AFTER.test(after);
 }
 function suppressSequential(_text, match) {
     const clean = match.text.replace(/[\s.\-]/g, "");
     return SEQUENTIAL_PATTERNS.test(clean);
 }
+const RECENT_YEAR = /^(?:19[5-9]\d|20[0-3]\d)$/;
+const POSTAL_CONTEXT_NEAR = /(?:postcode|postal|code\s*postal|PLZ|Postleitzahl|postnummer|postinumero|póstnúmer|zip|straat|straße|strasse|rue\s|via\s|calle\s|rua\s|ulica|utca|street|avenue|laan\s|weg\s|plein|adres|adresse|address|woonplaats|wonende|woonachtig|gevestigd|domicili|demeurant|résidant|residant|bosatt|bopæl|wohnhaft|ansässig|stad\b|ville\b|city\b|Stadt|città|ciudad|cidade|miasto|město|város)/i;
+const DATE_KEYWORD_NEAR = /(?:født|fødselsdato|fødsel|Fødselsdato|född|födelsedatum|födelsedag|syntynyt|syntymäaika|fæddur|fæðingardagur|geboren|geboortedatum|Geburtsdatum|nascido|nacido|data di nascita|nato il|nata il|Tiltr[æa]delsesdato|Tiltredelsesdato|datum|date\b|Datum|jaar|year|année|Jahr|since|sinds|depuis|seit|\d{2}\.\d{2}\.|(?:januar|februar|marts|april|maj|juni|juli|august|september|oktober|november|december|januari|februari|mars|mei|juin|juillet|août))/i;
 function suppressYearAsPostal(text, match) {
     if (match.patternDef.entityType !== EntityType.POSTAL_CODE)
         return false;
     const clean = match.text.trim();
-    if (!YEAR_PATTERN.test(clean))
+    if (!RECENT_YEAR.test(clean))
+        return false;
+    const [before, after] = getContext(text, match.start, match.end);
+    const context = before + after;
+    // Keep as postal code if postal/address context nearby
+    if (POSTAL_CONTEXT_NEAR.test(context))
         return false;
+    // Keep if preceded by comma+space (address pattern: "Amsterdam, 2026")
     const immediateBefore = text.slice(Math.max(0, match.start - 3), match.start);
-    if (immediateBefore.endsWith(", ") || immediateBefore.endsWith(",\n"))
+    if (/,\s*$/.test(immediateBefore))
         return false;
-    const [before, after] = getContext(text, match.start, match.end);
-    return DATE_KEYWORD_NEAR.test(before + after);
+    // Suppress if date keyword nearby (birth date, employment date, etc.)
+    if (DATE_KEYWORD_NEAR.test(context))
+        return true;
+    // Suppress: recent years without postal context are almost never postal codes
+    return true;
 }
 function suppressPhoneAfterIdLabel(text, match) {
     if (match.patternDef.entityType !== EntityType.PHONE)
@@ -101,9 +121,13 @@ const NOT_CITY_CODES = new Set([
     "ID", "NR", "NO", "ST", "DR", "MR", "MS", "HR", "FR", "IM", "IN", "OR", "IF", "IS", "IT", "AT", "AD", "AG", "AV",
     "BE", "DE", "EU", "NL", "LU", "WS", "SS", "IP",
 ]);
+const CURRENCY_PLATE = /^(?:EUR|USD|GBP|CHF|SEK|NOK|DKK|ISK|CZK|PLN|HUF|RON|BGN|HRK)\s/i;
 function suppressPlateInCompound(text, match) {
     if (match.patternDef.entityType !== EntityType.LICENSE_PLATE)
         return false;
+    // Suppress currency + number misread as plate (e.g. "EUR 2")
+    if (CURRENCY_PLATE.test(match.text))
+        return true;
     if (match.start >= 3) {
         const before = text.slice(Math.max(0, match.start - 10), match.start);
         if (/[A-Za-zÄÖÜäöüß]{2,}-$/.test(before))
@@ -175,6 +199,218 @@ function suppressPostalAsHouseNumber(text, match) {
     }
     return false;
 }
+// ── BIC: banking-context cues and heading shapes ────────────────────────
+// \bSWIFT\b also covers SWIFT-Code / SWIFT-BIC / Code SWIFT, and \bBIC\b
+// covers BIC-code / BIC/SWIFT.
+const BIC_KEYWORD = /\b(?:BIC|SWIFT)\b/i;
+const BANK_BLOCK = /\b(?:IBAN|Bankverbindung|Bankgegevens|Bankrekening|Rekening(?:nummer)?|Kontonummer|Konto|Kontoinhaber|Compte|Coordonn[ée]es\s+bancaires|Banque|Account\s+(?:number|holder)|Bankleitzahl|BLZ|Betaalgegevens|Zahlungsdaten)\b/i;
+// A line that is nothing but a BIC/SWIFT label, as used in table and column
+// layouts where the code sits on the following line.
+const BIC_LABEL_LINE = /^\s*(?:BIC|SWIFT|SWIFT[-\s]?BIC|BIC\s?\/\s?SWIFT|SWIFT[-\s]?Code|BIC[-\s]?code|Code\s+SWIFT)\s*:?\s*$/i;
+// An IBAN in the same structural unit: CC + 2 check digits + 2 or more groups.
+const IBAN_SHAPE = /\b[A-Z]{2}\d{2}(?:\s?[A-Z0-9]{4}){2,}/;
+// Largest paragraph still treated as one structural unit. Beyond this the unit
+// falls back to the enclosing line, so a run-on document body cannot lend
+// banking context to a token 2,000 characters away.
+const MAX_UNIT_CHARS = 600;
+function enclosingLine(text, start, end) {
+    const lineStart = text.lastIndexOf("\n", start - 1) + 1;
+    let lineEnd = text.indexOf("\n", end);
+    if (lineEnd === -1)
+        lineEnd = text.length;
+    return [lineStart, lineEnd];
+}
+/**
+ * Return the enclosing line / record / paragraph around a match.
+ *
+ * The context window for BIC is scoped structurally, not by character count.
+ * A tight character window measured on the corpus rejects 97.3% of dictionary
+ * false positives but wrongly discards ~316 real-looking codes, because the
+ * banking cue often sits further away in the same record — e.g. a CSV row
+ * carrying the IBAN in one field and the BIC several fields later.
+ */
+function structuralUnit(text, start, end) {
+    const [lineStart, lineEnd] = enclosingLine(text, start, end);
+    let paraStart = lineStart;
+    while (paraStart > 0) {
+        const prevEnd = paraStart - 1;
+        const prevStart = text.lastIndexOf("\n", prevEnd - 1) + 1;
+        if (text.slice(prevStart, prevEnd).trim() === "")
+            break;
+        paraStart = prevStart;
+    }
+    let paraEnd = lineEnd;
+    while (paraEnd < text.length) {
+        const nextStart = paraEnd + 1;
+        let nextEnd = text.indexOf("\n", nextStart);
+        if (nextEnd === -1)
+            nextEnd = text.length;
+        if (text.slice(nextStart, nextEnd).trim() === "")
+            break;
+        paraEnd = nextEnd;
+    }
+    if (paraEnd - paraStart <= MAX_UNIT_CHARS)
+        return text.slice(paraStart, paraEnd);
+    return text.slice(lineStart, lineEnd);
+}
+function previousNonblankLine(text, lineStart) {
+    let pos = lineStart;
+    while (pos > 0) {
+        const prevEnd = pos - 1;
+        const prevStart = text.lastIndexOf("\n", prevEnd - 1) + 1;
+        const line = text.slice(prevStart, prevEnd);
+        if (line.trim() !== "")
+            return line;
+        pos = prevStart;
+    }
+    return "";
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Does `token` also occur as an ordinary lowercase word in this document?
+ *
+ * `hospital`/`HOSPITAL`, `gegevens`/`GEGEVENS` — a token that appears in
+ * ordinary case elsewhere in the same document is a word, not a bank code.
+ * Email and domain contexts are excluded, so `ing.nl` does not vouch for a
+ * heading. Measured on the corpus this alone identifies ~78% of the BIC false
+ * positives with no dictionaries and no labelled data.
+ */
+function occursAsLowercaseWord(text, token) {
+    if (!/^[A-Za-z]+$/.test(token))
+        return false;
+    const lower = token.toLowerCase();
+    const capitalised = lower[0].toUpperCase() + lower.slice(1);
+    for (const form of [lower, capitalised]) {
+        // Cheap pre-check: a plain substring test almost always answers "no".
+        if (!text.includes(form))
+            continue;
+        const re = new RegExp(`\\b${escapeRe(form)}\\b`, "g");
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            const before = m.index > 0 ? text[m.index - 1] : "";
+            const after = text.slice(m.index + form.length, m.index + form.length + 8);
+            if (before === "@" || (before === "." && m.index >= 2 && /[A-Za-z0-9]/.test(text[m.index - 2])))
+                continue;
+            if (after.startsWith("@") || /^\.[a-zA-Z]{2,6}\b/.test(after))
+                continue;
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Is the candidate positioned as a section heading rather than a value?
+ * Headings and shouted words are never bank codes. Lines carrying an explicit
+ * BIC/SWIFT keyword are exempt from the all-caps rule, so a genuine
+ * `BIC: GEBABEBB` line is not mistaken for a heading.
+ */
+function isHeadingShape(text, start, end, token) {
+    const [lineStart, lineEnd] = enclosingLine(text, start, end);
+    const line = text.slice(lineStart, lineEnd);
+    // The token is the entire line — unless the line above is a bare BIC/SWIFT
+    // label, which makes this a labelled value in a table layout, not a heading.
+    if (line.trim() === token) {
+        return !BIC_LABEL_LINE.test(previousNonblankLine(text, lineStart));
+    }
+    // The token starts its line and is immediately followed by a colon
+    if (text.slice(lineStart, start).trim() === "" && text.slice(end, lineEnd).trimStart().startsWith(":")) {
+        return true;
+    }
+    // A shouted line: no lowercase, no digits, and no banking keyword
+    if (!/[a-z]/.test(line) && !/\d/.test(line) && !BIC_KEYWORD.test(line))
+        return true;
+    return false;
+}
+/**
+ * Emit a BIC only on registry membership or banking context.
+ *
+ * 0. the token also occurs as an ordinary lowercase word here -> reject;
+ * 1. registry hit (deployment-supplied, then bundled seed prefixes) -> emit;
+ * 2. heading / shouted-word shape -> reject;
+ * 3. BIC/SWIFT keyword, IBAN or bank block in the structural unit -> emit;
+ *
+ * and a bare shape match reaching the end with none of the above is never
+ * emitted. Gate 0 outranks every tier below it — no genuine BIC is also an
+ * ordinary lowercase word — so it is applied on both emitting paths. It scans
+ * the whole document, so it runs only on the paths that would otherwise emit.
+ */
+function suppressBicWithoutEvidence(text, match) {
+    if (match.patternDef.entityType !== EntityType.BIC)
+        return false;
+    const token = match.text.trim();
+    if (isRegisteredBic(token))
+        return occursAsLowercaseWord(text, token);
+    if (isHeadingShape(text, match.start, match.end, token))
+        return true;
+    // The token itself is blanked out so it cannot vouch for itself.
+    const unit = structuralUnit(text, match.start, match.end).split(token).join(" ".repeat(token.length));
+    if (BIC_KEYWORD.test(unit) || IBAN_SHAPE.test(unit) || BANK_BLOCK.test(unit)) {
+        return occursAsLowercaseWord(text, token);
+    }
+    return true;
+}
+// ── Postal code: digits belonging to a longer identifier ────────────────
+// An identifier label immediately before the digits. A postal code is never
+// introduced this way; an SVNr, policy number or service number always is.
+const ID_CUE_BEFORE = /(?:[\w\-]*Nr|[\w\-]*N[°ºo]|[\w\-]*Nummer|[\w\-]*Numero|[\w\-]*Numéro|No|number|num|Kennzahl|Aktenzeichen|Az|e-?card|Polizze|Police|Policen)\.?\s*:?\s*$/i;
+// An international dialling prefix earlier on the same line, with nothing but
+// number punctuation in between: these digits belong to the phone detector.
+const DIALLING_PREFIX_BEFORE = /\+\d{1,3}[\d\s\-().]*$/;
+// A country prefix on a postal code — "A-1010 Wien", "B-2000", "L-1234".
+const COUNTRY_PREFIXED = /(?:^|[^A-Za-z0-9])[A-Z]{1,2}$/;
+/**
+ * Suppress bare digit runs that belong to a longer number, not an address.
+ *
+ * A bare 4- or 5-digit run is the weakest shape in the engine, and when it
+ * cuts into a longer identifier the damage is worse than a plain false
+ * positive: `SV-Nummer: [POSTAL_CODE] 040390` leaves half an Austrian social
+ * security number exposed with no way to label the remainder.
+ *
+ * Applies only to digits-only matches, so structured forms keep their own
+ * behaviour — NL `1234 AB`, PT `1234-567`, LU `L-1234`.
+ */
+function suppressPostalInLongerIdentifier(text, match) {
+    if (match.patternDef.entityType !== EntityType.POSTAL_CODE)
+        return false;
+    const clean = match.text.trim();
+    if (!/^\d+$/.test(clean))
+        return false;
+    const beforeChar = match.start > 0 ? text[match.start - 1] : "";
+    const afterChar = match.end < text.length ? text[match.end] : "";
+    const prevPrev = match.start >= 2 ? text[match.start - 2] : "";
+    const nextNext = match.end + 1 < text.length ? text[match.end + 1] : "";
+    // Directly glued to more digits
+    if (/\d/.test(beforeChar) || /\d/.test(afterChar))
+        return true;
+    // Joined by identifier punctuation: "0456.2398.71-02", "4471/2025".
+    // The punctuation only counts when it actually *joins two digit groups* — a
+    // trailing period is ordinary sentence punctuation, and treating it as a
+    // separator discards every postal code that ends a sentence
+    // ("Domicilio: Palma, 13867. Pagos a ...").
+    if ("._/".includes(beforeChar) && /\d/.test(prevPrev))
+        return true;
+    if ("._/".includes(afterChar) && /\d/.test(nextNext))
+        return true;
+    if (afterChar === "-" && /\d/.test(nextNext))
+        return true;
+    if (beforeChar === "-" && !COUNTRY_PREFIXED.test(text.slice(0, match.start - 1)))
+        return true;
+    // A further digit group on the same line: "1268 040390", "1234 5678 925",
+    // "+43 664 8213 907". Horizontal whitespace only — a digit on the *next*
+    // line is a separate field, not a continuation.
+    if (/^[ \t]+\d/.test(text.slice(match.end, match.end + 4)))
+        return true;
+    // An identifier label introduces the digits: "DiNr. 4471", "Policen-Nr."
+    if (ID_CUE_BEFORE.test(text.slice(Math.max(0, match.start - 40), match.start)))
+        return true;
+    // Digits after an international dialling prefix belong to PHONE
+    const [lineStart] = enclosingLine(text, match.start, match.end);
+    if (DIALLING_PREFIX_BEFORE.test(text.slice(lineStart, match.start)))
+        return true;
+    return false;
+}
 function suppressRequiresContext(text, match) {
     if (!match.patternDef.requiresContext || match.patternDef.contextKeywords.length === 0)
         return false;
@@ -187,8 +423,9 @@ const TYPE_SUPPRESSORS = {
     [EntityType.NATIONAL_ID]: [suppressCurrency, suppressUnits, suppressReference, suppressLegal, suppressMath, suppressNatidAsPassport, suppressSeNatidAsOrg],
     [EntityType.SSN]: [suppressCurrency, suppressUnits, suppressReference, suppressMath],
     [EntityType.TAX_ID]: [suppressCurrency, suppressUnits, suppressReference, suppressMath],
-    [EntityType.POSTAL_CODE]: [suppressCurrency, suppressUnits, suppressMath, suppressLegal, suppressYearAsPostal, suppressPostalInsideIban, suppressPostalAsHouseNumber],
-    [EntityType.IBAN]: [suppressReference],
+    [EntityType.POSTAL_CODE]: [suppressCurrency, suppressUnits, suppressMath, suppressLegal, suppressYearAsPostal, suppressPostalInsideIban, suppressPostalAsHouseNumber, suppressPostalInLongerIdentifier],
+    [EntityType.BIC]: [suppressBicWithoutEvidence],
+    [EntityType.BANK_ACCOUNT]: [suppressReference],
     [EntityType.LICENSE_PLATE]: [suppressPlateInCompound],
     [EntityType.CHAMBER_OF_COMMERCE]: [suppressReference],
 };

package/dist/esm/rules/validators.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Total IBAN length per country (ISO 13616 registry). Also used to build the
+ * country-independent IBAN pattern in rules/countries, so an IBAN is detected
+ * on its own structure rather than on the caller's `countries` setting.
+ */
+export declare const IBAN_LENGTHS: Record<string, number>;
+/** ISO 3166-1 alpha-2 codes, plus XK (Kosovo, user-assigned but in banking use). */
+export declare const ISO_3166_ALPHA2: ReadonlySet<string>;
 export declare function validateIban(candidate: string): boolean;
 export declare function validateBsn(candidate: string): boolean;
 export declare function validateBelgianNn(candidate: string): boolean;
@@ -10,7 +18,24 @@ export declare function validateVatLu(candidate: string): boolean;
 export declare function validateGermanTaxId(candidate: string): boolean;
 export declare function validateFrenchNir(candidate: string): boolean;
 export declare function validateVin(candidate: string): boolean;
+/**
+ * BIC/SWIFT structural validation (ISO 9362): BBBB CC LL (PPP).
+ *
+ * Necessary but **not sufficient** — BIC has no check digit, and characters
+ * 5-6 of ordinary uppercase words are frequently valid country codes
+ * (`DRINGEND` -> `GE`, `HOSPITAL` -> `IT`). Emission additionally requires a
+ * registry hit or banking context; see `suppressBicWithoutEvidence`.
+ */
 export declare function validateBic(candidate: string): boolean;
+/**
+ * International phone number in E.164 form: `+` then 8-15 digits.
+ *
+ * A `+` prefix makes a phone number self-identifying, so this backs a
+ * country-independent pattern: the per-country patterns each hard-code one
+ * grouping and miss the others (`+43 664 8213 907` was invisible because the
+ * Austrian pattern expects an unbroken subscriber number).
+ */
+export declare function validateE164(candidate: string): boolean;
 export declare function validateKvk(candidate: string): boolean;
 export declare function validateSwedishPnr(candidate: string): boolean;
 export declare function validateNorwegianFnr(candidate: string): boolean;