nz-privacy-auditor 0.8.0

package/README.md

@@ -0,0 +1,152 @@
+# nz-privacy-auditor
+
+[![npm version](https://img.shields.io/npm/v/nz-privacy-auditor?style=for-the-badge&color=a78bfa)](https://www.npmjs.com/package/nz-privacy-auditor)
+[![npm downloads](https://img.shields.io/npm/dm/nz-privacy-auditor?style=for-the-badge&color=22c55e)](https://www.npmjs.com/package/nz-privacy-auditor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-a78bfa?style=for-the-badge)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-22c55e?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
+[![Privacy Act 2020](https://img.shields.io/badge/Privacy%20Act-2020-3b82f6?style=for-the-badge)](https://www.legislation.govt.nz/act/public/2020/0031/latest/LMS23223.html)
+[![QAPulse by SK](https://img.shields.io/badge/QAPulse%20by%20SK-Compliance%20Tools-3b82f6?style=for-the-badge)](https://skakarh.com)
+
+> **Privacy Act 2020 compliance auditor for ML datasets.**
+> Scans text for New-Zealand-specific PII — IRD, NHI, driver licence, phone, address, te reo Māori names.
+> Zero dependencies. Works in Node, Deno, and browsers.
+
+---
+
+## ✨ Why nz-privacy-auditor?
+
+NZ practitioners working with health records, government data, or customer corpora need to verify that datasets are free of regulated identifiers **before** they reach an ML pipeline or third-party service. Generic tools miss what actually matters under the [Privacy Act 2020](https://www.legislation.govt.nz/act/public/2020/0031/latest/LMS23223.html) and the Health Information Privacy Code 2020.
+
+| Feature | nz-privacy-auditor | Generic PII tools |
+|---|---|---|
+| IRD number + mod-11 checksum | ✅ | ❌ |
+| NHI number (legacy + new format) | ✅ | ❌ |
+| NZ driver licence | ✅ | Regex only |
+| NZ phone (NSN validation) | ✅ | Partial |
+| NZ address (postcode + gazetteer) | ✅ | ❌ |
+| Te reo Māori names (macron-aware) | ✅ | ❌ |
+| Zero runtime dependencies | ✅ | Usually not |
+| TypeScript-native | ✅ | Varies |
+
+The full Python package (`pip install nz-privacy-auditor`) has [additional detectors, a CLI, Gemini LLM verification, HuggingFace loader, and a live demo](https://github.com/ShahnawazKakarh/nz-privacy-auditor). This TypeScript package is a port focused on the browser and Node ecosystems.
+
+---
+
+## 🚀 Install
+
+```bash
+npm install nz-privacy-auditor
+```
+
+Or with yarn / pnpm:
+
+```bash
+yarn add nz-privacy-auditor
+pnpm add nz-privacy-auditor
+```
+
+Requires Node.js 18+.
+
+### CLI
+
+A `nz-privacy-auditor` binary ships with the package:
+
+```bash
+npx nz-privacy-auditor scan path/to/data.csv
+npx nz-privacy-auditor scan path/to/data.csv --format json --output report.json
+npx nz-privacy-auditor scan data.csv --detector ird,nhi --min-confidence 0.7
+npx nz-privacy-auditor scan data.csv --fail-on-finding   # exit 1 if any PII; CI gate
+npx nz-privacy-auditor scan data.csv --verify-llm        # Gemini second-pass on low-confidence findings
+```
+
+For `--verify-llm`, set `GOOGLE_API_KEY` in your environment (get a free key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey)). Findings are cached at `data/llm_cache/cache.json` so repeat runs cost nothing.
+
+---
+
+## 📖 Usage
+
+### Scan a whole CSV file (programmatic)
+
+```typescript
+import { readFileSync } from "fs";
+import { Scanner, parseCsv, toJson } from "nz-privacy-auditor";
+
+const text = readFileSync("patients.csv", "utf-8");
+const rows = parseCsv(text);
+const result = new Scanner().scanRows(rows);
+
+console.log(`${result.totalFindings} findings across ${result.columnsScanned.length} columns`);
+console.log(toJson(result));
+```
+
+### Detect IRD numbers
+
+```typescript
+import { IRDDetector } from "nz-privacy-auditor";
+
+const detector = new IRDDetector();
+const findings = detector.scan("Please reference IRD 49-091-850 on the form.");
+
+console.log(findings);
+// [{
+//   detector: "ird",
+//   severity: "high",
+//   value: "49-091-850",
+//   start: 17,
+//   end: 27,
+//   confidence: 1.0,
+//   context: { normalised: "49091850" }
+// }]
+```
+
+Only checksum-validated matches are emitted — no false positives on random 8-digit strings.
+
+### CommonJS
+
+```javascript
+const { IRDDetector } = require("nz-privacy-auditor");
+```
+
+### Standalone checksum helper
+
+If you just need to validate an IRD without the detection pipeline:
+
+```typescript
+import { irdChecksumOk } from "nz-privacy-auditor";
+
+irdChecksumOk("49091850");   // true
+irdChecksumOk("49091851");   // false (bad check digit)
+irdChecksumOk("00000000");   // false (below MIN_IRD)
+```
+
+---
+
+## 🗺️ Detector roadmap
+
+| Detector | Approach | Status |
+|---|---|---|
+| **IRD number** | Regex + IR-published mod-11 (primary + secondary weights) | ✅ v0.1.0 |
+| **NHI number** | Regex + Health NZ mod-11 (legacy) / mod-23 (new format per HISO 10046:2024) | ✅ v0.2.0 |
+| **Driver licence** | `[A-Z]{2}\d{6}` + 300-char keyword proximity | ✅ v0.3.0 |
+| **NZ phone** | `+64` / `0x` patterns + NSN validation, E.164 output | ✅ v0.4.0 |
+| **NZ address** | Suffix + postcode + region / suburb gazetteer | ✅ v0.5.0 |
+| **Te reo Māori names** | Macron-aware curated gazetteer | ✅ v0.6.0 |
+| **LLM verification** | Gemini 2.5 Flash second-pass over low-confidence findings | ✅ v0.8.0 |
+
+Test vectors are shared 1:1 with the Python implementation via [`fixtures/*.json`](https://github.com/ShahnawazKakarh/nz-privacy-auditor/tree/master/fixtures) — spec parity is enforced by construction, not by discipline.
+
+---
+
+## 🔗 See also
+
+- **Python package** with full CLI, LLM verification, and HuggingFace loader: [github.com/ShahnawazKakarh/nz-privacy-auditor](https://github.com/ShahnawazKakarh/nz-privacy-auditor)
+- **Live demo** on HuggingFace Spaces: [huggingface.co/spaces/Shahnawazkakarh/nz-privacy-auditor](https://huggingface.co/spaces/Shahnawazkakarh/nz-privacy-auditor)
+- **Privacy Act 2020 mapping doc**: [docs/privacy-act-mapping.md](https://github.com/ShahnawazKakarh/nz-privacy-auditor/blob/master/docs/privacy-act-mapping.md)
+
+---
+
+## 📄 License
+
+MIT © 2026 [QAPulse by SK](https://skakarh.com).
+
+The library reflects publicly available NZ government identifier specifications (Inland Revenue IRD checksum, Health NZ NHI standard HISO 10046:2024) but is **not affiliated with or endorsed by** any NZ government agency. Consult the [Office of the Privacy Commissioner](https://www.privacy.org.nz/) for compliance decisions on production systems.

package/data/llm_cache/cache.json

@@ -0,0 +1 @@
+{"1f49c20f5f9ede6ae1048353f9ef4024427fa29e3314cc21d3ba3bcdd3409040":{"verdict":"rejected","confidence":1,"reason":"The value is explicitly referred to as an SKU in the context, not an NZ driver licence number.","created_at":1783314580473}}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Command-line interface for nz-privacy-auditor.
+ *
+ * Usage:
+ *   nz-privacy-auditor scan path/to/data.csv
+ *   nz-privacy-auditor scan path/to/data.csv --format json --output report.json
+ *   nz-privacy-auditor scan data.csv --detector ird,nhi --min-confidence 0.7
+ */
+/**
+ * Minimal RFC 4180 CSV parser. Handles quoted fields, embedded commas,
+ * embedded newlines, and escaped double-quotes. Comma-separated only.
+ */
+export declare function parseCsv(text: string): Record<string, string>[];
+export declare function main(argv?: string[]): void;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AA+BH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAoD/D;AAkBD,wBAAgB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,IAAI,CAyGxD"}

package/dist/cli.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Command-line interface for nz-privacy-auditor.
+ *
+ * Usage:
+ *   nz-privacy-auditor scan path/to/data.csv
+ *   nz-privacy-auditor scan path/to/data.csv --format json --output report.json
+ *   nz-privacy-auditor scan data.csv --detector ird,nhi --min-confidence 0.7
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCsv = parseCsv;
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const commander_1 = require("commander");
+const report_1 = require("./report");
+const scanner_1 = require("./scanner");
+const verification_1 = require("./verification");
+const gemini_1 = require("./verifiers/gemini");
+const address_1 = require("./detectors/address");
+const driver_licence_1 = require("./detectors/driver_licence");
+const ird_1 = require("./detectors/ird");
+const maori_name_1 = require("./detectors/maori_name");
+const nhi_1 = require("./detectors/nhi");
+const phone_1 = require("./detectors/phone");
+const index_1 = require("./index");
+const DETECTOR_CLASSES = {
+    ird: ird_1.IRDDetector,
+    nhi: nhi_1.NHIDetector,
+    driver_licence: driver_licence_1.DriverLicenceDetector,
+    phone: phone_1.PhoneDetector,
+    address: address_1.AddressDetector,
+    maori_name: maori_name_1.MaoriNameDetector,
+};
+/**
+ * Minimal RFC 4180 CSV parser. Handles quoted fields, embedded commas,
+ * embedded newlines, and escaped double-quotes. Comma-separated only.
+ */
+function parseCsv(text) {
+    const rows = [];
+    let cur = [];
+    let field = "";
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                field += ch;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inQuotes = true;
+        }
+        else if (ch === ",") {
+            cur.push(field);
+            field = "";
+        }
+        else if (ch === "\n" || ch === "\r") {
+            // Handle \r\n
+            if (ch === "\r" && text[i + 1] === "\n")
+                i++;
+            cur.push(field);
+            field = "";
+            rows.push(cur);
+            cur = [];
+        }
+        else {
+            field += ch;
+        }
+    }
+    // Trailing field / row
+    if (field.length > 0 || cur.length > 0) {
+        cur.push(field);
+        rows.push(cur);
+    }
+    if (rows.length === 0)
+        return [];
+    const header = rows[0];
+    return rows.slice(1).map((r) => {
+        const obj = {};
+        header.forEach((h, idx) => {
+            obj[h] = r[idx] ?? "";
+        });
+        return obj;
+    });
+}
+function resolveDetectors(csv) {
+    if (!csv)
+        return (0, scanner_1.defaultDetectors)();
+    const keys = csv
+        .split(",")
+        .map((k) => k.trim())
+        .filter(Boolean);
+    const unknown = keys.filter((k) => !(k in DETECTOR_CLASSES));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown detector(s): ${unknown.join(", ")}. ` +
+            `Valid: ${Object.keys(DETECTOR_CLASSES).sort().join(", ")}`);
+    }
+    return keys.map((k) => new DETECTOR_CLASSES[k]());
+}
+function main(argv = process.argv) {
+    const program = new commander_1.Command();
+    program
+        .name("nz-privacy-auditor")
+        .description("Privacy Act 2020 compliance auditor for ML datasets")
+        .version(index_1.VERSION);
+    program
+        .command("scan")
+        .description("Scan a CSV file for Privacy Act 2020 PII issues")
+        .argument("<path>", "Path to CSV file")
+        .option("--format <format>", "Output format: console or json", "console")
+        .option("-o, --output <file>", "Write output to a file (JSON only)")
+        .option("--detector <names>", "Comma-separated detector names. Default: all. Choices: " +
+        Object.keys(DETECTOR_CLASSES).sort().join(", "))
+        .option("--min-confidence <n>", "Drop findings below this confidence threshold (0-1)", "0.0")
+        .option("--fail-on-finding", "Exit with status 1 if any findings emitted", false)
+        .option("--verify-llm", "Run Gemini second-pass over low-confidence findings. Requires GOOGLE_API_KEY.", false)
+        .option("--llm-threshold <n>", "Only findings with confidence below this threshold are verified", "0.8")
+        .action(async (filePath, opts) => {
+        const abs = path.resolve(filePath);
+        if (!fs.existsSync(abs)) {
+            console.error(`Error: file not found: ${abs}`);
+            process.exit(2);
+        }
+        const detectors = resolveDetectors(opts.detector);
+        const minConfidence = Number(opts.minConfidence);
+        if (Number.isNaN(minConfidence) || minConfidence < 0 || minConfidence > 1) {
+            console.error("Error: --min-confidence must be a number in [0, 1]");
+            process.exit(2);
+        }
+        const text = fs.readFileSync(abs, "utf-8");
+        const rows = parseCsv(text);
+        const scanner = new scanner_1.Scanner({ detectors, minConfidence });
+        let result = scanner.scanRows(rows);
+        if (opts.verifyLlm) {
+            const llmThreshold = Number(opts.llmThreshold);
+            if (Number.isNaN(llmThreshold) || llmThreshold < 0 || llmThreshold > 1) {
+                console.error("Error: --llm-threshold must be a number in [0, 1]");
+                process.exit(2);
+            }
+            try {
+                const verifier = new gemini_1.GeminiVerifier();
+                try {
+                    result = await (0, verification_1.applyVerification)(result, verifier, {
+                        threshold: llmThreshold,
+                    });
+                }
+                finally {
+                    verifier.close();
+                }
+            }
+            catch (exc) {
+                console.error(`Error: LLM verification failed: ${exc instanceof Error ? exc.message : String(exc)}`);
+                process.exit(2);
+            }
+        }
+        const outputFormat = String(opts.format);
+        if (outputFormat === "json") {
+            const payload = (0, report_1.toJson)(result);
+            if (opts.output) {
+                fs.writeFileSync(String(opts.output), payload, "utf-8");
+                console.log(`Wrote report to ${opts.output}`);
+            }
+            else {
+                console.log(payload);
+            }
+        }
+        else if (outputFormat === "console") {
+            if (opts.output) {
+                console.error("Error: --output is only supported with --format json");
+                process.exit(2);
+            }
+            console.log((0, report_1.renderConsole)(result));
+        }
+        else {
+            console.error(`Error: unknown --format value: ${outputFormat}`);
+            process.exit(2);
+        }
+        if (opts.failOnFinding && result.totalFindings > 0) {
+            process.exit(1);
+        }
+    });
+    program.parse(argv);
+}
+// Node's ESM/CJS detection: run main if invoked directly, not when required.
+if (require.main === module) {
+    main();
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/detectors/address.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+import type { Detector, Finding, Severity } from "./base";
+/**
+ * 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.
+ */
+export declare const NZ_LOCATIONS: readonly string[];
+/**
+ * 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.
+ */
+export declare class AddressDetector implements Detector {
+    readonly name = "address";
+    readonly severity: Severity;
+    scan(value: string): Finding[];
+}
+//# sourceMappingURL=address.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/detectors/address.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AA8C1D;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EA2FzC,CAAC;AA0EF;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAY;IAEvC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;CAuB/B"}