model card: full 12-class label table + adversarial coverage + sync with GitHub README

README.md

@@ -91,11 +91,41 @@ Cold start (first `sanitize()`, ONNX load included): ~756 ms.
 
 ## Schema (12 classes)
 
-ML-trained (8): `account_number` · `private_address` · `private_date` · `private_email` · `private_person` · `private_phone` · `private_url` · `secret`
-
-Zero-shot prompted + regex post-pass (4): `private_passport` · `private_driver_license` · `private_vehicle_id` · `private_geolocation`
+| Label | Examples | Source |
+|---|---|---|
+| `private_person` | names | model |
+| `private_email` | emails | model + regex |
+| `private_phone` | int'l + IT / FR / ES / HIPAA-fax domestic | model + regex |
+| `private_address` | street, city, ZIP | model |
+| `private_date` | birth / hire dates | model |
+| `private_url` | `http(s)://`, `www.` | model + regex |
+| `private_ip` | IPv4, IPv6 (RFC 1918 / 5737 / loopback filtered) | regex post-pass |
+| `private_mac` | MAC addresses (broadcast / multicast filtered) | regex post-pass |
+| `private_passport` | US / IT / FR / ES / DE / UK + context-anchored generic (30 countries) | model (zero-shot) + regex post-pass |
+| `private_driver_license` | US per-state + IT / EU per-country (context-anchored) | model (zero-shot) + regex post-pass |
+| `private_vehicle_id` | VIN (ISO 3779 mod-11), plates IT / FR / DE / UK / ES / US | model (zero-shot) + regex (validated) |
+| `private_geolocation` | lat/lon decimal pairs (range-validated) + DMS notation | model (zero-shot) + regex (validated) |
+| `account_number` | IBAN mod-97, cards (Luhn), SSN, MRN, BTC / ETH, DNI / CPF / CF / EIN, Medicare MBI / HIC, NPI, insurance policy, IMEI | model + regex (validated) |
+| `secret` | API keys (AWS / GitHub / OpenAI / Anthropic / Stripe / 30+), JWT, PEM, base64-wrapped PII | regex (50+) + base64 |
+
+The GLiNER head is trained on 8 categories (the first 8 + `account_number` + `secret`). The other 4 (`private_passport` / `driver_license` / `vehicle_id` / `geolocation`) are prompted zero-shot and paired with validated regex post-pass. `private_ip` / `private_mac` are regex-only — the model is not trained on them.
+
+## Tricky inputs the npm runtime still catches
+
+Where the adversarial-input preprocessor + recognizer pack pulls PII the bare model alone would miss:
+
+| Surface | Input | Detected as |
+|---|---|---|
+| base64-wrapped secret | `(base64-encoded) c2stYW50LWFwaTAzLWFCY0RlRmcw…` | `sk-ant-api03-…` (Anthropic key) |
+| HTML-entity-encoded secret | `sk-ant…` | `sk-ant-…` (Anthropic key) |
+| double-URL-encoded email | `bob.jones%2540company.io` | `bob.jones@company.io` (email) |
+| zero-width-obfuscated address | `221B Baker St`U+200B`re`U+200B`et `U+200B`London` | `221B Baker Street London` (address) |
+| spaced-out email | `u s e r . 1 2 3 @ g m a i l . c o m` | `user.123@gmail.com` (email) |
+| Cyrillic-homoglyph email | `pаyments@bank.com` (`а` = U+0430) | `payments@bank.com` (email) |
+| fullwidth ASCII email | `ＵＳＥＲ．ＮＡＭＥ＠ｅｘａｍｐｌｅ．ｃｏｍ` | `USER.NAME@example.com` (email) |
+| Italian IBAN in prose | `IT60X0542811101000001023456` | `IT60X0542811101000001023456` (account_number, mod-97 verified) |
 
-Pure regex post-pass (2): `private_ip` · `private_mac` (GLiNER head not trained on them).
+Five passes total: Unicode normalisation (NFKC + `any-ascii` transliteration), base64 decode-then-classify, iterative URL `%XX` + HTML-entity decode, zero-width strip with offset remap, 50+ validated regex pack.
 
 ## Intended use
 
@@ -105,8 +135,8 @@ Pure regex post-pass (2): `private_ip` · `private_mac` (GLiNER head not trained
 
 ## Out-of-scope
 
-- **GDPR Article 9 special categories** (health, biometric, genetic, religious, political, trade-union, sexual orientation). Not represented in the schema.
-- **HIPAA PHI** — `account_number` catches MRN-shaped digit runs but the model is not a HIPAA de-identifier.
+- **Implied / opinion-based attributes** (race, religion, health conditions, political views, sexual orientation). These need a different kind of model — this one only finds explicit text spans.
+- **HIPAA PHI** — `account_number` catches MRN-shaped digit runs but the model is not a HIPAA de-identifier. Diagnoses, ICD codes, dosages, biometric / genetic identifiers — out of scope.
 - **CJK / RTL / Indic scripts** — limited coverage; treat as out-of-scope.
 - **Air-gapped first-run** — point at a local mirror via `NULLPII_MODEL_DIR` or `modelDir` config.