nz-privacy-auditor

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 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. This TypeScript package is a port focused on the browser and Node ecosystems.

🚀 Install

npm install nz-privacy-auditor

Or with yarn / pnpm:

yarn add nz-privacy-auditor
pnpm add nz-privacy-auditor

Requires Node.js 18+.

CLI

A nz-privacy-auditor binary ships with the package:

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). Findings are cached at data/llm_cache/cache.json so repeat runs cost nothing.

📖 Usage

Scan a whole CSV file (programmatic)

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

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

const { IRDDetector } = require("nz-privacy-auditor");

Standalone checksum helper

If you just need to validate an IRD without the detection pipeline:

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 — 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
• Live demo on HuggingFace Spaces: huggingface.co/spaces/Shahnawazkakarh/nz-privacy-auditor
• Privacy Act 2020 mapping doc: docs/privacy-act-mapping.md

📄 License

MIT © 2026 QAPulse by SK.

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 for compliance decisions on production systems.