nz-privacy-auditor 0.8.0

package/dist/detectors/address.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * NZ address detector.
+ *
+ * Address detection combines three signals to flag values that look like a
+ * New Zealand street address:
+ *
+ * 1. **Street-suffix shape** — a numeric prefix followed by 1–4 words and a
+ *    recognised NZ street-type suffix (`Street`, `Road`, `Avenue`, `Drive`,
+ *    `Lane`, etc., and their common abbreviations).
+ * 2. **NZ postcode** — a 4-digit token (NZ Post uses 4-digit postcodes).
+ * 3. **NZ location name** — one of the 16 regions, major cities, or common
+ *    metropolitan suburbs from the bundled gazetteer.
+ *
+ * Severity is MEDIUM because an address is a quasi-identifier under the
+ * Privacy Act 2020. Confidence scales with the number of corroborating
+ * signals:
+ *
+ * - 0.5 — street-suffix shape only
+ * - 0.7 — street-suffix shape + postcode OR location
+ * - 0.9 — street-suffix shape + postcode + location
+ *
+ * TypeScript port of `src/nz_privacy_auditor/detectors/address.py`. The
+ * NZ_LOCATIONS list is a verbatim mirror of the Python `_NZ_LOCATIONS`
+ * frozenset — any change to one must be applied to the other. A parity
+ * check across the two lists lives in the JS test suite.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddressDetector = exports.NZ_LOCATIONS = void 0;
+const STREET_SUFFIXES = [
+    // Full forms
+    "street",
+    "road",
+    "avenue",
+    "drive",
+    "lane",
+    "place",
+    "crescent",
+    "terrace",
+    "boulevard",
+    "highway",
+    "court",
+    "close",
+    "parade",
+    "mall",
+    "quay",
+    "square",
+    "loop",
+    "rise",
+    "grove",
+    "way",
+    "heights",
+    "park",
+    "esplanade",
+    "promenade",
+    // Abbreviations
+    "st",
+    "rd",
+    "ave",
+    "av",
+    "dr",
+    "ln",
+    "pl",
+    "cres",
+    "tce",
+    "blvd",
+    "hwy",
+    "ct",
+    "cl",
+    "pde",
+    "sq",
+];
+/**
+ * NZ regions, major cities, and common metropolitan suburbs.
+ *
+ * IMPORTANT: this list is a mirror of `_NZ_LOCATIONS` in the Python
+ * detector at `src/nz_privacy_auditor/detectors/address.py`. Any addition
+ * or removal must be applied to both files simultaneously.
+ */
+exports.NZ_LOCATIONS = [
+    // 16 regions
+    "Northland",
+    "Auckland",
+    "Waikato",
+    "Bay of Plenty",
+    "Gisborne",
+    "Hawke's Bay",
+    "Hawkes Bay",
+    "Taranaki",
+    "Manawatu-Whanganui",
+    "Manawatū-Whanganui",
+    "Wellington",
+    "Tasman",
+    "Nelson",
+    "Marlborough",
+    "West Coast",
+    "Canterbury",
+    "Otago",
+    "Southland",
+    // Major cities / towns
+    "Whangarei",
+    "Whangārei",
+    "Hamilton",
+    "Tauranga",
+    "Rotorua",
+    "Taupo",
+    "Taupō",
+    "Napier",
+    "Hastings",
+    "New Plymouth",
+    "Palmerston North",
+    "Whanganui",
+    "Lower Hutt",
+    "Upper Hutt",
+    "Porirua",
+    "Kapiti",
+    "Kāpiti",
+    "Blenheim",
+    "Greymouth",
+    "Christchurch",
+    "Timaru",
+    "Dunedin",
+    "Queenstown",
+    "Invercargill",
+    // Common Auckland suburbs
+    "Albany",
+    "Botany",
+    "Devonport",
+    "Epsom",
+    "Glenfield",
+    "Grey Lynn",
+    "Henderson",
+    "Howick",
+    "Manukau",
+    "Mt Albert",
+    "Mt Eden",
+    "Mount Albert",
+    "Mount Eden",
+    "Newmarket",
+    "North Shore",
+    "Onehunga",
+    "Otahuhu",
+    "Otāhuhu",
+    "Pakuranga",
+    "Papakura",
+    "Papatoetoe",
+    "Parnell",
+    "Ponsonby",
+    "Remuera",
+    "Takapuna",
+    // Common Wellington suburbs
+    "Brooklyn",
+    "Karori",
+    "Kelburn",
+    "Khandallah",
+    "Miramar",
+    "Newtown",
+    "Petone",
+    "Thorndon",
+    // Common Christchurch suburbs
+    "Addington",
+    "Fendalton",
+    "Hornby",
+    "Ilam",
+    "Linwood",
+    "Merivale",
+    "Papanui",
+    "Riccarton",
+    "Sumner",
+    "Sydenham",
+];
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// Build a case-insensitive alternation, longest first so multi-word
+// locations like "Bay of Plenty" match before "Bay" alone would.
+const LOCATION_PATTERN = new RegExp("\\b(?:" +
+    [...exports.NZ_LOCATIONS]
+        .sort((a, b) => b.length - a.length)
+        .map(escapeRegex)
+        .join("|") +
+    ")\\b", "gi");
+// 4-digit NZ postcode. NZ Post issues postcodes in 0110-9999; values
+// below 0100 are unused.
+const POSTCODE_PATTERN = /\b(0[1-9]\d{2}|[1-9]\d{3})\b/g;
+const SUFFIX_GROUP = STREET_SUFFIXES.join("|");
+// Street-shape: optional unit prefix (e.g. "5/"), street number with optional
+// trailing letter (e.g. "12A"), 1-4 capitalised words, then a recognised suffix.
+const ADDRESS_PATTERN = new RegExp("\\b(" +
+    "(?:\\d+\\s*/\\s*)?" +
+    "\\d{1,5}[A-Za-z]?" +
+    "\\s+" +
+    "(?:[A-Z][A-Za-z\\u00C0-\\u017F'\\u2019]*[-\\s]){1,4}" +
+    "(?:" +
+    SUFFIX_GROUP +
+    ")" +
+    ")\\b", "gi");
+function supportingSignals(value, addressStart, addressEnd) {
+    const signals = [];
+    // Postcode — outside the address span only.
+    POSTCODE_PATTERN.lastIndex = 0;
+    let pc;
+    while ((pc = POSTCODE_PATTERN.exec(value)) !== null) {
+        if (pc.index >= addressStart && pc.index + pc[0].length <= addressEnd)
+            continue;
+        signals.push(`postcode:${pc[0]}`);
+        break;
+    }
+    // Location — outside the address span only.
+    LOCATION_PATTERN.lastIndex = 0;
+    let loc;
+    while ((loc = LOCATION_PATTERN.exec(value)) !== null) {
+        if (loc.index >= addressStart && loc.index + loc[0].length <= addressEnd)
+            continue;
+        signals.push(`location:${loc[0]}`);
+        break;
+    }
+    return signals;
+}
+function confidenceFor(signals) {
+    const hasPostcode = signals.some((s) => s.startsWith("postcode:"));
+    const hasLocation = signals.some((s) => s.startsWith("location:"));
+    if (hasPostcode && hasLocation)
+        return 0.9;
+    if (hasPostcode || hasLocation)
+        return 0.7;
+    return 0.5;
+}
+/**
+ * Detects NZ street addresses via shape + postcode + gazetteer signals.
+ *
+ * Emits a finding for each street-shape match. Confidence reflects how
+ * many corroborating signals (postcode, NZ region / city / suburb) are
+ * present in the same value.
+ */
+class AddressDetector {
+    constructor() {
+        this.name = "address";
+        this.severity = "medium";
+    }
+    scan(value) {
+        const findings = [];
+        ADDRESS_PATTERN.lastIndex = 0;
+        let match;
+        while ((match = ADDRESS_PATTERN.exec(value)) !== null) {
+            const raw = match[1].trim();
+            const signals = supportingSignals(value, match.index, match.index + match[1].length);
+            findings.push({
+                detector: this.name,
+                severity: this.severity,
+                value: raw,
+                start: match.index,
+                end: match.index + match[1].length,
+                confidence: confidenceFor(signals),
+                context: { signals },
+            });
+        }
+        return findings;
+    }
+}
+exports.AddressDetector = AddressDetector;
+//# sourceMappingURL=address.js.map

package/dist/detectors/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/detectors/address.ts"],"names":[],"mappings":"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"}

package/dist/detectors/base.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Base detector interface and shared types.
+ */
+/**
+ * Severity of a Privacy Act 2020 finding.
+ *
+ * - HIGH — directly identifying, regulated identifiers (IRD, NHI, driver licence).
+ * - MEDIUM — quasi-identifiers that combine readily (phone, address).
+ * - LOW — context-sensitive signals (te reo names, generic name tokens).
+ */
+export type Severity = "high" | "medium" | "low";
+/** A single PII match within a value. */
+export interface Finding {
+    /** Detector name (e.g. `"ird"`, `"nhi"`). */
+    detector: string;
+    /** Severity of the finding. */
+    severity: Severity;
+    /** The matched substring (raw). */
+    value: string;
+    /** Zero-indexed character offset within the source value. */
+    start: number;
+    /** Exclusive end offset. */
+    end: number;
+    /** Detector confidence, 0..1. 1.0 for checksum-verified matches. */
+    confidence: number;
+    /** Detector-specific context (e.g. normalised form). */
+    context: Record<string, unknown>;
+}
+/**
+ * Abstract base for all PII detectors.
+ *
+ * Implementations must be stateless — a single instance may be called
+ * across many rows / columns of a dataset.
+ */
+export interface Detector {
+    /** Machine-readable detector name (e.g. `"ird"`). */
+    readonly name: string;
+    /** Severity emitted by this detector. */
+    readonly severity: Severity;
+    /** Scan a single string value and yield findings. */
+    scan(value: string): Finding[];
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/detectors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/detectors/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEjD,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,qDAAqD;IACrD,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;CAChC"}

package/dist/detectors/base.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Base detector interface and shared types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=base.js.map

package/dist/detectors/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/detectors/base.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/detectors/driver_licence.d.ts

@@ -0,0 +1,38 @@
+/**
+ * NZ driver licence number detector.
+ *
+ * NZ driver licence numbers are issued by Waka Kotahi | NZ Transport Agency
+ * in the format `[A-Z]{2}\d{6}` — two uppercase letters followed by six
+ * digits, e.g. `BQ739482` or `UE093153`. The licence number remains the
+ * same when a new card is issued; the three-digit card version number
+ * printed on the card is per-issue and is not detected by this module.
+ *
+ * Unlike IRD and NHI numbers, NZTA does NOT publish a check-digit algorithm
+ * for driver licence numbers. This means a regex alone produces many false
+ * positives on dataset columns containing 2-letter prefixed codes (order
+ * IDs, SKUs, flight references). To compensate, this detector lowers
+ * confidence when no contextual keyword (`licence`, `license`, `driver`,
+ * `DL`) appears within a 300-character window of the match — the same
+ * approach used by Microsoft Purview's NZ driver licence sensitive-
+ * information type.
+ *
+ * Findings are emitted at confidence 0.9 when a keyword is nearby, and
+ * confidence 0.5 otherwise. Downstream code may filter on confidence to
+ * trade off precision against recall.
+ *
+ * TypeScript port of `src/nz_privacy_auditor/detectors/driver_licence.py`.
+ */
+import type { Detector, Finding, Severity } from "./base";
+/**
+ * Detects NZ driver licence numbers (`[A-Z]{2}\d{6}`).
+ *
+ * Confidence is 0.9 when a contextual keyword (licence, license, driver,
+ * DL, NZTA, Waka Kotahi) is found within ±300 characters of the match,
+ * and 0.5 otherwise. There is no public NZTA checksum to validate against.
+ */
+export declare class DriverLicenceDetector implements Detector {
+    readonly name = "driver_licence";
+    readonly severity: Severity;
+    scan(value: string): Finding[];
+}
+//# sourceMappingURL=driver_licence.d.ts.map

package/dist/detectors/driver_licence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver_licence.d.ts","sourceRoot":"","sources":["../../src/detectors/driver_licence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAuB1D;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,QAAQ;IACpD,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAU;IAErC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;CAsB/B"}

package/dist/detectors/driver_licence.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * NZ driver licence number detector.
+ *
+ * NZ driver licence numbers are issued by Waka Kotahi | NZ Transport Agency
+ * in the format `[A-Z]{2}\d{6}` — two uppercase letters followed by six
+ * digits, e.g. `BQ739482` or `UE093153`. The licence number remains the
+ * same when a new card is issued; the three-digit card version number
+ * printed on the card is per-issue and is not detected by this module.
+ *
+ * Unlike IRD and NHI numbers, NZTA does NOT publish a check-digit algorithm
+ * for driver licence numbers. This means a regex alone produces many false
+ * positives on dataset columns containing 2-letter prefixed codes (order
+ * IDs, SKUs, flight references). To compensate, this detector lowers
+ * confidence when no contextual keyword (`licence`, `license`, `driver`,
+ * `DL`) appears within a 300-character window of the match — the same
+ * approach used by Microsoft Purview's NZ driver licence sensitive-
+ * information type.
+ *
+ * Findings are emitted at confidence 0.9 when a keyword is nearby, and
+ * confidence 0.5 otherwise. Downstream code may filter on confidence to
+ * trade off precision against recall.
+ *
+ * TypeScript port of `src/nz_privacy_auditor/detectors/driver_licence.py`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriverLicenceDetector = void 0;
+// Two letters + six digits, case-insensitive.
+const LICENCE_PATTERN = /\b([A-Z]{2}\d{6})\b/gi;
+// Context keywords. Case-insensitive whole-word match within the proximity
+// window. `DL` is constrained to upper-case-only via a separate pattern
+// below to avoid matching the common English word "dl" in chemistry / units.
+const KEYWORD_PATTERN = /\b(?:licen[cs]e|driver(?:'?s)?|driver\s*licen[cs]e|driving\s*licen[cs]e|nzta|waka\s*kotahi)\b/i;
+const DL_PATTERN = /\bDL\b/;
+// Proximity window (chars) used to look for a contextual keyword around the
+// matched licence-shaped token. Matches Microsoft Purview's NZ DLP setting.
+const PROXIMITY = 300;
+function hasKeywordNear(value, start, end) {
+    const lo = Math.max(0, start - PROXIMITY);
+    const hi = Math.min(value.length, end + PROXIMITY);
+    const window = value.slice(lo, hi);
+    return KEYWORD_PATTERN.test(window) || DL_PATTERN.test(window);
+}
+/**
+ * Detects NZ driver licence numbers (`[A-Z]{2}\d{6}`).
+ *
+ * Confidence is 0.9 when a contextual keyword (licence, license, driver,
+ * DL, NZTA, Waka Kotahi) is found within ±300 characters of the match,
+ * and 0.5 otherwise. There is no public NZTA checksum to validate against.
+ */
+class DriverLicenceDetector {
+    constructor() {
+        this.name = "driver_licence";
+        this.severity = "high";
+    }
+    scan(value) {
+        const findings = [];
+        LICENCE_PATTERN.lastIndex = 0;
+        let match;
+        while ((match = LICENCE_PATTERN.exec(value)) !== null) {
+            const raw = match[1];
+            const hasKw = hasKeywordNear(value, match.index, match.index + raw.length);
+            findings.push({
+                detector: this.name,
+                severity: this.severity,
+                value: raw,
+                start: match.index,
+                end: match.index + raw.length,
+                confidence: hasKw ? 0.9 : 0.5,
+                context: {
+                    normalised: raw.toUpperCase(),
+                    keyword_proximity: hasKw,
+                },
+            });
+        }
+        return findings;
+    }
+}
+exports.DriverLicenceDetector = DriverLicenceDetector;
+//# sourceMappingURL=driver_licence.js.map

package/dist/detectors/driver_licence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver_licence.js","sourceRoot":"","sources":["../../src/detectors/driver_licence.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAIH,8CAA8C;AAC9C,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEhD,2EAA2E;AAC3E,wEAAwE;AACxE,6EAA6E;AAC7E,MAAM,eAAe,GACnB,gGAAgG,CAAC;AACnG,MAAM,UAAU,GAAG,QAAQ,CAAC;AAE5B,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa,EAAE,GAAW;IAC/D,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;IAC1C,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAa,qBAAqB;IAAlC;QACW,SAAI,GAAG,gBAAgB,CAAC;QACxB,aAAQ,GAAa,MAAM,CAAC;IAwBvC,CAAC;IAtBC,IAAI,CAAC,KAAa;QAChB,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,eAAe,CAAC,SAAS,GAAG,CAAC,CAAC;QAC9B,IAAI,KAA6B,CAAC;QAClC,OAAO,CAAC,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACtD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACtB,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;YAC3E,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,MAAM;gBAC7B,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;gBAC7B,OAAO,EAAE;oBACP,UAAU,EAAE,GAAG,CAAC,WAAW,EAAE;oBAC7B,iBAAiB,EAAE,KAAK;iBACzB;aACF,CAAC,CAAC;QACL,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AA1BD,sDA0BC"}

package/dist/detectors/ird.d.ts

@@ -0,0 +1,37 @@
+/**
+ * IRD (Inland Revenue Department) number detector.
+ *
+ * NZ IRD numbers are 8 or 9 digits with a mod-11 check digit. The algorithm
+ * is published by Inland Revenue and uses a primary weight set, falling back
+ * to a secondary weight set when the primary calculation yields a check
+ * digit of 10.
+ *
+ * Reference:
+ *   https://www.ird.govt.nz/-/media/project/ir/home/documents/digital-service-providers/draft-documents/payday-filing/algorithm-for-ird-numbers.pdf
+ *
+ * Valid IRD numbers fall between 10,000,000 and ~150,000,000. We use the
+ * conservative upper bound of 150,000,000 to reject obviously out-of-range
+ * candidates while remaining future-proof.
+ *
+ * TypeScript port of `src/nz_privacy_auditor/detectors/ird.py`. Test vectors
+ * for both implementations live in `fixtures/ird.json`.
+ */
+import type { Detector, Finding, Severity } from "./base";
+/**
+ * Validate the mod-11 check digit for an 8- or 9-digit IRD string.
+ *
+ * `digits` must contain only digit characters. Returns true only when the
+ * IRD passes range and checksum validation.
+ */
+export declare function checksumOk(digits: string): boolean;
+/**
+ * Detects NZ Inland Revenue (IRD) numbers via regex + mod-11 checksum.
+ *
+ * Only checksum-validated matches are emitted. The detector is stateless.
+ */
+export declare class IRDDetector implements Detector {
+    readonly name = "ird";
+    readonly severity: Severity;
+    scan(value: string): Finding[];
+}
+//# sourceMappingURL=ird.d.ts.map

package/dist/detectors/ird.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ird.d.ts","sourceRoot":"","sources":["../../src/detectors/ird.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAe1D;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CA6BlD;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,QAAQ;IAC1C,QAAQ,CAAC,IAAI,SAAS;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAU;IAErC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;CAsB/B"}

package/dist/detectors/ird.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * IRD (Inland Revenue Department) number detector.
+ *
+ * NZ IRD numbers are 8 or 9 digits with a mod-11 check digit. The algorithm
+ * is published by Inland Revenue and uses a primary weight set, falling back
+ * to a secondary weight set when the primary calculation yields a check
+ * digit of 10.
+ *
+ * Reference:
+ *   https://www.ird.govt.nz/-/media/project/ir/home/documents/digital-service-providers/draft-documents/payday-filing/algorithm-for-ird-numbers.pdf
+ *
+ * Valid IRD numbers fall between 10,000,000 and ~150,000,000. We use the
+ * conservative upper bound of 150,000,000 to reject obviously out-of-range
+ * candidates while remaining future-proof.
+ *
+ * TypeScript port of `src/nz_privacy_auditor/detectors/ird.py`. Test vectors
+ * for both implementations live in `fixtures/ird.json`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IRDDetector = void 0;
+exports.checksumOk = checksumOk;
+// IRD numbers appear as 8 or 9 digit runs, optionally hyphen- or space-separated
+// in groups like 49-091-850 or 49 091 850 or 049091850.
+const IRD_PATTERN = /\b(\d{2,3}[-\s]?\d{3}[-\s]?\d{3})\b/g;
+// Inland Revenue's published weight sets.
+const PRIMARY_WEIGHTS = [3, 2, 7, 6, 5, 4, 3, 2];
+const SECONDARY_WEIGHTS = [7, 4, 3, 2, 5, 2, 7, 6];
+// IRDs below 10_000_000 are not issued.
+const MIN_IRD = 10000000;
+// Upper sanity bound; IR is currently issuing in the 100M+ range.
+const MAX_IRD = 150000000;
+/**
+ * Validate the mod-11 check digit for an 8- or 9-digit IRD string.
+ *
+ * `digits` must contain only digit characters. Returns true only when the
+ * IRD passes range and checksum validation.
+ */
+function checksumOk(digits) {
+    if (![8, 9].includes(digits.length))
+        return false;
+    if (!/^\d+$/.test(digits))
+        return false;
+    // Left-pad 8-digit IRDs to 9 digits for uniform handling.
+    const padded = digits.padStart(9, "0");
+    const body = padded.slice(0, 8);
+    const check = Number(padded[8]);
+    const bodyInt = Number(padded);
+    if (bodyInt < MIN_IRD || bodyInt > MAX_IRD)
+        return false;
+    const calc = (weights) => {
+        let total = 0;
+        for (let i = 0; i < 8; i++) {
+            total += Number(body[i]) * weights[i];
+        }
+        const rem = total % 11;
+        return rem === 0 ? 0 : 11 - rem;
+    };
+    const primary = calc(PRIMARY_WEIGHTS);
+    if (primary < 10)
+        return primary === check;
+    // Primary produced 10 — fall back to secondary weights.
+    const secondary = calc(SECONDARY_WEIGHTS);
+    // Number is invalid per IR spec if secondary also yields 10.
+    if (secondary === 10)
+        return false;
+    return secondary === check;
+}
+/**
+ * Detects NZ Inland Revenue (IRD) numbers via regex + mod-11 checksum.
+ *
+ * Only checksum-validated matches are emitted. The detector is stateless.
+ */
+class IRDDetector {
+    constructor() {
+        this.name = "ird";
+        this.severity = "high";
+    }
+    scan(value) {
+        const findings = [];
+        // Reset lastIndex — the regex is global and shared across calls.
+        IRD_PATTERN.lastIndex = 0;
+        let match;
+        while ((match = IRD_PATTERN.exec(value)) !== null) {
+            const raw = match[1];
+            const digits = raw.replace(/[-\s]/g, "");
+            if (checksumOk(digits)) {
+                findings.push({
+                    detector: this.name,
+                    severity: this.severity,
+                    value: raw,
+                    start: match.index,
+                    end: match.index + raw.length,
+                    confidence: 1.0,
+                    context: { normalised: digits },
+                });
+            }
+        }
+        return findings;
+    }
+}
+exports.IRDDetector = IRDDetector;
+//# sourceMappingURL=ird.js.map

package/dist/detectors/ird.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ird.js","sourceRoot":"","sources":["../../src/detectors/ird.ts"],"names":[],"mappings":"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"}

package/dist/detectors/maori_name.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Te reo Māori personal-name detector.
+ *
+ * Detects predominantly Māori given names and surnames from a curated
+ * gazetteer. The detector is **macron-aware**: a value like `Tāne` and its
+ * non-macron form `Tane` both match the canonical entry. Confidence is
+ * higher (0.9) when the input preserved the macron — a signal that the
+ * data was entered with cultural care — and lower (0.7) otherwise.
+ *
+ * Severity is LOW because a personal name on its own is not necessarily
+ * identifying under the Privacy Act 2020. The detector exists so that
+ * downstream consumers can apply additional care to records that contain
+ * culturally significant te reo Māori identifiers (e.g. IPP 4 collection
+ * manner, IPP 8 accuracy obligations around name spelling and macron
+ * preservation).
+ *
+ * TypeScript port of `src/nz_privacy_auditor/detectors/maori_name.py`. The
+ * name lists below are verbatim mirrors of the Python `_GIVEN_NAMES` and
+ * `_SURNAMES` sets — any change to one must be applied to the other.
+ */
+import type { Detector, Finding, Severity } from "./base";
+/** Casefold and strip combining marks (macrons) for fuzzy matching. */
+export declare function foldMacrons(s: string): string;
+/**
+ * Detects te reo Māori personal names from a curated gazetteer.
+ *
+ * The detector is macron-aware and case-insensitive. Findings carry the
+ * canonical macron-preserved form in `context.canonical` even when the
+ * input did not use macrons.
+ */
+export declare class MaoriNameDetector implements Detector {
+    readonly name = "maori_name";
+    readonly severity: Severity;
+    scan(value: string): Finding[];
+}
+//# sourceMappingURL=maori_name.d.ts.map

package/dist/detectors/maori_name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maori_name.d.ts","sourceRoot":"","sources":["../../src/detectors/maori_name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAoK1D,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAiCD;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAS;IAEpC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;CAyB/B"}