@abhishekvardanbotta/mask 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Vardan Botta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @abhishekvardanbotta/mask
+
+Keep personal data out of LLM prompts, tool calls, memory and logs, and still get it back where it is allowed.
+
+`mask` finds personal data in structured and unstructured values. It replaces each value with a reversible
+token such as `ss1_njpskmng`, keeps the original encrypted in a vault, and restores it only for principals
+granted that kind of data. It has zero runtime dependencies and uses only `node:crypto` and `node:net`.
+
+It is the engine behind `privacy: { enabled: true }` in [kiln](https://www.npmjs.com/package/@abhishekvardanbotta/kiln), and works on its own with any LLM stack.
+
+```sh
+npm install @abhishekvardanbotta/mask     # Node 20.3+
+```
+
+```ts
+import { createPrivacy } from "@abhishekvardanbotta/mask";
+
+const privacy = createPrivacy({ key: process.env.KILN_PRIVACY_KEY });   // 32-byte base64 key; omit for a per-process random one
+const session = privacy.session("conversation-123");
+
+const prompt = session.protectSync("I'm Priya Sharma, priya@example.com, card 4111 1111 1111 1111, cvv 123");
+// "I'm ss1_ubjboike, ss1_njpskmng, card ss1_efecfvfz, cvv [BLOCKED:CARD_SECURITY_CODE]"   (letters vary with the key)
+
+const reply = await callYourModel(prompt);              // the model only ever sees placeholders
+session.restore(reply, { allow: ["PII"] });             // email and name restored; the card stays [REDACTED:CREDIT_CARD]
+```
+
+## Classifications
+
+| Classification | What happens | Restorable by |
+|---|---|---|
+| `PII` | Replaced with a vault token | grants `"PII"`, `"*"`, or the entity type |
+| `SENSITIVE` | Replaced with a vault token | grants `"SENSITIVE"` or the entity type. **`"*"` does not cover it.** |
+| `PUBLIC` | Left untouched. On a field, detection is switched off for that subtree | — |
+| `BLOCK` | Removed (`[BLOCKED:TYPE]`) and never stored | nobody, ever |
+
+Default policy per type (override with `policies`):
+
+- **PII**: `EMAIL`, `PHONE`, `PERSON`, `ADDRESS`, `LOCATION`, `DATE_OF_BIRTH`, `IP_ADDRESS`, `USERNAME`
+- **SENSITIVE**: `CREDIT_CARD`, `IBAN`, `BANK_ACCOUNT`, `US_SSN`, `IN_AADHAAR`, `IN_PAN`, `NATIONAL_ID`, `PASSPORT`, `DRIVERS_LICENSE`, `HEALTH`, `SPECIAL_CATEGORY`
+- **BLOCK**: `CREDENTIAL` (API keys, JWTs, passwords, private keys) and `CARD_SECURITY_CODE`
+- Custom types default to PII.
+
+## How data is found
+
+Detection does not rely on a single regex per type. It combines five layers:
+
+1. **Schema annotations.** In a JSON Schema passed as `protect(value, { schema })`:
+   - `"x-privacy": "SENSITIVE"`
+   - `"x-privacy": { "classification": "SENSITIVE", "type": "HEALTH" }`
+   - a `privacy:CLASS[:TYPE]` tag in `description` (what zod's `.describe("privacy:SENSITIVE:HEALTH")` produces)
+   - standard `format: "email" | "ipv4" | "ipv6"`
+
+   Local `$ref`s, `allOf`/`anyOf`/`oneOf`, `items`/`prefixItems` and `additionalProperties` are followed.
+2. **Field paths in config.** For example `fields: { "customer.ssn": "BLOCK", "**.notes": { classification: "SENSITIVE", type: "NOTE" } }`. `*` matches one key and `**` any depth. A bare key matches at any depth.
+3. **Field-name semantics.** `billingEmail`, `phone_number`, `dateOfBirth`, `apiKey` and `diagnosis` are classified from their trailing words, so `emailVerified` and `phoneType` are not. A bare `name` counts as a person's name only under a person-like parent such as `customer.name`. Switch this off with `inferFromFieldNames: false`.
+4. **Validated recognizers for free text.** A candidate pattern only proposes a match; a validator decides:
+
+   | Type | Validation |
+   |---|---|
+   | Cards | Luhn (ISO/IEC 7812) plus issuer ranges |
+   | IBAN | ISO 13616 per-country length plus mod-97 |
+   | US SSN | SSA area, group and serial rules |
+   | Aadhaar | Verhoeff check digit (UIDAI) |
+   | Email | RFC 5321 length and label limits |
+   | IP addresses | `node:net` |
+   | JWT | decoded header with `alg` (RFC 7519) |
+   | Secrets | Shannon entropy |
+
+   Context words then raise or lower the confidence. "SSN", "born" and "card" raise it; "order", "invoice" and "version" lower it. A finding counts only above `threshold` (default 0.5).
+5. **Known-value propagation.** Once a value is tokenized anywhere in a scope (for example a name from a `fullName` field), later free-text mentions of it, and of the parts of a person's name, get the same token.
+
+Add your own detectors, synchronous or asynchronous, such as an NER model or a customer-ID dictionary:
+
+```ts
+createPrivacy({ detectors: [{ name: "ner", detect: async (text) => (await ner(text)).map(e => ({ type: "PERSON", start: e.start, end: e.end, score: e.score })) }] });
+```
+
+`privacy.detect(text)` shows what would be found, with confidences, without tokenizing.
+
+## Tokens, the vault and keys
+
+- **Tokens.** The same value always gets the same token within a scope (looked up by an HMAC-SHA256 fingerprint, RFC 2104), so a model can still tell "the same customer wrote twice" and analytics on masked data still join and group correctly. Different scopes, or different keys, give unrelated tokens. `tokenStyle` picks the format:
+  - `"random"` (default): `ss1_njpskmng`, 8 letters from the keyed HMAC. Reveals nothing, not even what kind of value it replaced, and can't be guessed.
+  - `"sequential"`: `[EMAIL_1]`, `[PERSON_2]`, numbered per type within the scope. The type is visible and ids are guessable within a scope, but small models copy these most reliably.
+  - `"opaque"`: `[EMAIL_3f9a1c0b7e]`, the type plus 40 bits of the keyed HMAC.
+- **Numbers** in JSON stay numbers (amounts, salaries, ages, counts), so aggregates are unchanged. A number is masked only when it is an identifier: in a classified field such as `ssn`, or a long integer that validates as a card or phone number. It restores as a number.
+- **Retention**: `destroy(scope)` deletes a scope; its tokens, wherever they were logged, become permanently opaque. Records also carry `expiresAt` (`retentionMs`, default one hour).
+
+```ts
+const privacy = createPrivacy({ key, store: myStore, retentionMs: 24 * 3600_000 });
+const session = await privacy.open("chat-42");   // loads and decrypts persisted records first
+```
+
+## Restoring, with authorization
+
+```ts
+session.restore(value, { allow: ["PII", "US_SSN"], principal: "user:42" });  // only what is granted
+session.restore(value, { allow: ["EMAIL"], onDenied: "mask" });              // others masked: "***-**-6789"
+session.restore(value, { trusted: true });                                   // everything restorable — your own code only
+```
+
+- **Denied values** become `[REDACTED:TYPE]` (default), a mask (`onDenied: "mask"`), or stay as the token (`"token"`). Masks show at most the last four digits of a card, per PCI DSS 3.4.1.
+- **Bare tokens** without brackets are restored too, since models sometimes drop the brackets.
+- **Unknown tokens are never restored**: another scope's, or a made-up one, is left exactly as it is.
+- **The audit trail** (`session.audit()`) records each tokenize, block, restore and deny by token and type, never by plaintext.
+- **Streaming**: `session.streamRestorer(options)` restores chunk by chunk without ever emitting half a token.
+
+## API summary
+
+| | |
+|---|---|
+| `createPrivacy(options)` | engine: `key`, `store`, `retentionMs`, `tokenStyle`, plus any `PolicyConfig` |
+| `privacy.session(scope, policy?)` / `await privacy.open(scope, policy?)` | a session over a scope (`open` hydrates from the store) |
+| `privacy.policy(overrides)` | compile a policy layered on the engine's (reuse it across sessions) |
+| `await session.protect(value, { schema? })` | tokenize a string or any JSON value; runs async detectors |
+| `session.protectSync(value, { schema? })` | same, synchronous detectors only (plus every value already known in the scope) |
+| `session.restore(value, { allow?, trusted?, onDenied?, principal? })` | authorization-checked restoration |
+| `session.summary()` / `session.audit()` | counts and the audit trail |
+| `await session.flush()` | wait for vault writes; rejects if the store failed |
+| `await privacy.destroy(scope)` | crypto-shred a scope |
+
+`PolicyConfig` options: `policies`, `fields`, `detectors`, `disable` (built-in recognizer names), `threshold`, `inferFromFieldNames`, `allowlist`, `onBlock: "redact" | "throw"`.
+
+## Threat model and limits
+
+**What it protects.** The goal is to keep personal data from leaving your process towards an LLM provider, a tool or API, a memory store, or a log sink. It also stops code outside your trust boundary from turning tokens back into data.
+
+**What it does not do:**
+
+- **Detection is not perfect.**
+  - A name or street address in free text with no supporting cue ("Priya called yesterday") is not found by the built-in recognizers. Use a schema or field classification (values then propagate into free text), or plug in an NER detector.
+  - Free-text health or other special-category content is only caught through field classification or your own detector.
+  - Run `privacy.detect()` on representative data and tune `threshold`, `policies` and `fields`.
+- **Tokens are pseudonymous data, not anonymous data** (GDPR Art. 4(5)). While the vault and key exist, they are reversible by design.
+- **Scope and model behavior.** Inside a scope, deterministic tokens reveal equality: two mentions of the same email share a token. That is what preserves reasoning. A model can also misuse placeholders, for example by combining two into one; it never sees the values, but the task can fail. Measure on your own model.
+- **Key protection is your job.** Anyone with the master key and the store can decrypt it. Keep the key in a secrets manager.
+- **No certification.** It has not been audited or certified for any standard (PCI DSS, HIPAA or GDPR compliance is a property of your whole system). The references above describe which algorithms and rules it follows, not a compliance claim.
+
+## License
+
+MIT

package/dist/crypto.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Two independent subkeys derived from one 256-bit master key with HKDF-SHA256 (RFC 5869), so the key that
+ * encrypts vault values (AES-256-GCM, NIST SP 800-38D) is never the key that derives tokens (HMAC-SHA256,
+ * RFC 2104 / FIPS 198-1).
+ */
+export interface DerivedKeys {
+    readonly encryption: Buffer;
+    readonly mac: Buffer;
+}
+/** A fresh random 256-bit master key, base64-encoded — suitable for `KILN_PRIVACY_KEY` or a secrets manager. */
+export declare function generateKey(): string;
+export declare function normalizeMasterKey(key: string | Uint8Array | undefined): Buffer;
+export declare function deriveKeys(master: Buffer): DerivedKeys;
+/** Keyed fingerprint of a normalized value within a scope. Without the key it supports no dictionary attack. */
+export declare function fingerprint(keys: DerivedKeys, scope: string, type: string, normalized: string): string;
+export interface Sealed {
+    iv: string;
+    ct: string;
+    tag: string;
+}
+/** AES-256-GCM with a random IV per value. `aad` binds the ciphertext to its scope and token, so records cannot be swapped. */
+export declare function seal(keys: DerivedKeys, plaintext: string, aad: string): Sealed;
+export declare function open(keys: DerivedKeys, sealed: Sealed, aad: string): string;

package/dist/crypto.js

@@ -0,0 +1,45 @@
+import { createCipheriv, createDecipheriv, createHmac, hkdfSync, randomBytes } from "node:crypto";
+import { PrivacyError } from "./types.js";
+const HKDF_SALT = Buffer.from("mask/v1", "utf8");
+const IV_BYTES = 12; // 96-bit IV, the GCM recommendation (SP 800-38D §5.2.1.1)
+/** A fresh random 256-bit master key, base64-encoded — suitable for `KILN_PRIVACY_KEY` or a secrets manager. */
+export function generateKey() {
+    return randomBytes(32).toString("base64");
+}
+export function normalizeMasterKey(key) {
+    if (key === undefined)
+        return randomBytes(32);
+    const bytes = typeof key === "string" ? Buffer.from(key, "base64") : Buffer.from(key);
+    if (bytes.length !== 32)
+        throw new PrivacyError(`mask: the master key must be 32 bytes (got ${bytes.length}). Generate one with generateKey().`, "config");
+    return bytes;
+}
+export function deriveKeys(master) {
+    return {
+        encryption: Buffer.from(hkdfSync("sha256", master, HKDF_SALT, "vault-encryption", 32)),
+        mac: Buffer.from(hkdfSync("sha256", master, HKDF_SALT, "token-derivation", 32)),
+    };
+}
+/** Keyed fingerprint of a normalized value within a scope. Without the key it supports no dictionary attack. */
+export function fingerprint(keys, scope, type, normalized) {
+    return createHmac("sha256", keys.mac).update(scope).update("\u0000").update(type).update("\u0000").update(normalized).digest("hex");
+}
+/** AES-256-GCM with a random IV per value. `aad` binds the ciphertext to its scope and token, so records cannot be swapped. */
+export function seal(keys, plaintext, aad) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", keys.encryption, iv);
+    cipher.setAAD(Buffer.from(aad, "utf8"));
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return { iv: iv.toString("base64"), ct: ct.toString("base64"), tag: cipher.getAuthTag().toString("base64") };
+}
+export function open(keys, sealed, aad) {
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", keys.encryption, Buffer.from(sealed.iv, "base64"));
+        decipher.setAAD(Buffer.from(aad, "utf8"));
+        decipher.setAuthTag(Buffer.from(sealed.tag, "base64"));
+        return Buffer.concat([decipher.update(Buffer.from(sealed.ct, "base64")), decipher.final()]).toString("utf8");
+    }
+    catch {
+        throw new PrivacyError("mask: a vault record failed authentication (wrong key, or the record was altered).", "vault");
+    }
+}

package/dist/detectors/recognizers.d.ts

@@ -0,0 +1,24 @@
+import type { Detection, EntityType } from "../types.js";
+/**
+ * A built-in recognizer: a cheap candidate pattern, then a validator that scores (or rejects) each candidate, then a
+ * context pass that raises the score when supporting words sit nearby ("SSN", "card", "born") and lowers it when
+ * contradicting words do ("order", "invoice", "version"). The pattern only proposes; the validator and context decide.
+ */
+export interface Recognizer {
+    readonly name: string;
+    readonly type: EntityType;
+    readonly pattern: RegExp;
+    /** Capture group holding the value (the rest of the match is context, e.g. "password:"). Default 0. */
+    readonly group?: number;
+    /** Returns a base confidence, or undefined to reject the candidate. */
+    score(value: string): number | undefined;
+    readonly context?: string[];
+    /** Added when a context word appears within the window. Default 0.35. */
+    readonly contextBoost?: number;
+    /** How far past the match to look for context, in characters. Default 24. */
+    readonly contextAfter?: number;
+    readonly negativeContext?: string[];
+}
+export declare const BUILT_IN_RECOGNIZERS: Recognizer[];
+/** Runs one recognizer over `text`, applying its validator and context scoring. */
+export declare function runRecognizer(recognizer: Recognizer, text: string): Detection[];

package/dist/detectors/recognizers.js

@@ -0,0 +1,274 @@
+import { aadhaarValid, cardBrand, emailValid, ibanValid, ipVersion, isNonPublicIPv4, jwtValid, luhnValid, parseDate, shannonEntropy, ssnValid, } from "./validators.js";
+const CONTEXT_BEFORE = 48;
+const CONTEXT_AFTER = 24;
+const NEGATIVE_PENALTY = 0.35;
+const PHONE_CONTEXT = ["phone", "mobile", "cell", "call", "tel", "telephone", "contact", "whatsapp", "sms", "text", "reach", "fax", "ph", "number"];
+const ID_NEGATIVE = ["order", "invoice", "ref", "reference", "ticket", "tracking", "sku", "isbn", "serial", "version", "po", "case", "transaction", "txn", "build", "batch"];
+function digitsOf(value) {
+    return value.replace(/\D/g, "");
+}
+export const BUILT_IN_RECOGNIZERS = [
+    {
+        name: "email",
+        type: "EMAIL",
+        pattern: /[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+/g,
+        score: (v) => (emailValid(v) ? 0.95 : undefined),
+    },
+    {
+        name: "credit-card",
+        type: "CREDIT_CARD",
+        pattern: /(?<![\d-])\d(?:[ -]?\d){12,18}(?![\d])/g,
+        score: (v) => {
+            const digits = digitsOf(v);
+            if (digits.length < 13 || digits.length > 19 || !luhnValid(digits) || /^(\d)\1+$/.test(digits))
+                return undefined;
+            return cardBrand(digits) ? 0.9 : 0.4;
+        },
+        context: ["card", "credit", "debit", "visa", "mastercard", "amex", "cc", "payment", "pan"],
+        contextBoost: 0.4,
+        negativeContext: ID_NEGATIVE,
+    },
+    {
+        name: "card-security-code",
+        type: "CARD_SECURITY_CODE",
+        pattern: /\b(?:cvv2?|cvc2?|cid|csc|security code)\b\s*(?:is|[:#=-])?\s*(\d{3,4})\b/gi,
+        group: 1,
+        score: () => 0.9,
+    },
+    {
+        name: "iban",
+        type: "IBAN",
+        pattern: /\b[A-Z]{2}\d{2}(?:[ ]?[A-Z0-9]{4}){2,7}(?:[ ]?[A-Z0-9]{1,3})?\b/g,
+        score: (v) => (ibanValid(v) ? 0.95 : undefined),
+    },
+    {
+        name: "us-ssn",
+        type: "US_SSN",
+        pattern: /(?<![\d-])\d{3}([- ]?)\d{2}\1\d{4}(?![\d-])/g,
+        score: (v) => {
+            if (!ssnValid(digitsOf(v)))
+                return undefined;
+            if (v.includes("-"))
+                return 0.6;
+            return v.includes(" ") ? 0.35 : 0.15;
+        },
+        context: ["ssn", "social security", "social sec", "ss#", "ss no", "taxpayer", "tin"],
+        contextBoost: 0.45,
+        negativeContext: ID_NEGATIVE,
+    },
+    {
+        name: "in-aadhaar",
+        type: "IN_AADHAAR",
+        pattern: /(?<![\d-])[2-9]\d{3}([ -]?)\d{4}\1\d{4}(?![\d-])/g,
+        score: (v) => (aadhaarValid(digitsOf(v)) ? (/[ -]/.test(v) ? 0.6 : 0.35) : undefined),
+        context: ["aadhaar", "aadhar", "adhaar", "uidai", "uid"],
+        contextBoost: 0.4,
+        negativeContext: ID_NEGATIVE,
+    },
+    {
+        name: "in-pan",
+        type: "IN_PAN",
+        // 4th character is the holder type defined by the Income Tax Department (P = person, C = company, ...).
+        pattern: /\b[A-Z]{3}[PCHFATBLJG][A-Z]\d{4}[A-Z]\b/g,
+        score: () => 0.6,
+        context: ["pan", "permanent account", "income tax"],
+        contextBoost: 0.3,
+    },
+    {
+        name: "phone",
+        type: "PHONE",
+        pattern: /(?<![\w+.@/-])(?:\+\d{1,3}[ .-]?)?(?:\(\d{1,4}\)[ .-]?)?\d{2,5}(?:[ .-]?\d{2,5}){1,4}(?![\w@]|[.-]\d)/g,
+        score: (v) => {
+            const digits = digitsOf(v);
+            if (digits.length < 7 || digits.length > 15 || /^(\d)\1+$/.test(digits))
+                return undefined;
+            if (parseDate(v) || ipVersion(v) || /^\d+\.\d+$/.test(v))
+                return undefined;
+            const separators = v.replace(/[\d+()]/g, "");
+            if (separators.length && new Set(separators.replace(/ /g, "")).size > 1)
+                return undefined; // mixed "-" and "." is not a phone format
+            if (v.startsWith("+"))
+                return digits.length >= 8 ? 0.8 : undefined;
+            const formatted = /[ .()-]/.test(v);
+            const national = digits.length === 11 && digits.startsWith("1") ? digits.slice(1) : digits;
+            if (national.length === 10 && /^[2-9]\d{2}[2-9]\d{6}$/.test(national) && formatted)
+                return 0.65; // NANP (area + exchange rules)
+            if (digits.length === 10 && /^[6-9]/.test(digits))
+                return 0.5; // Indian mobile numbering plan (TRAI): 10 digits, leading 6-9
+            if (national.length === 10 && /^[2-9]\d{2}[2-9]\d{6}$/.test(national))
+                return 0.35;
+            return formatted ? 0.3 : 0.15;
+        },
+        context: PHONE_CONTEXT,
+        contextBoost: 0.35,
+        negativeContext: [...ID_NEGATIVE, "account", "acct", "id", "zip", "pin", "price", "amount", "total"],
+    },
+    {
+        name: "ipv4",
+        type: "IP_ADDRESS",
+        // A trailing "." ends the sentence, not the address: only a dot followed by a digit means a longer number.
+        pattern: /(?<![\d.])(?:\d{1,3}\.){3}\d{1,3}(?!\d|\.\d)/g,
+        score: (v) => (ipVersion(v) === 4 ? (isNonPublicIPv4(v) ? 0.3 : 0.6) : undefined),
+        context: ["ip", "address", "client", "host", "login", "from", "remote", "source"],
+        contextBoost: 0.3,
+        negativeContext: ["version", "v", "release", "build"],
+    },
+    {
+        name: "ipv6",
+        type: "IP_ADDRESS",
+        pattern: /(?<![\w:])(?=[A-Fa-f0-9:]*[A-Fa-f0-9]:[A-Fa-f0-9:]*:[A-Fa-f0-9])[A-Fa-f0-9:]{6,39}(?![\w:])/g,
+        score: (v) => {
+            if (ipVersion(v) !== 6)
+                return undefined;
+            if (v.split(":").filter(Boolean).length < 3)
+                return undefined;
+            return /^fe80:/i.test(v) ? 0.4 : 0.6;
+        },
+        context: ["ip", "address", "client", "host", "remote"],
+        contextBoost: 0.3,
+    },
+    {
+        name: "date-of-birth",
+        type: "DATE_OF_BIRTH",
+        pattern: /\b(?:\d{4}[-/.]\d{1,2}[-/.]\d{1,2}|\d{1,2}[-/.]\d{1,2}[-/.]\d{4}|\d{1,2}(?:st|nd|rd|th)?\s+[A-Z][a-z]{2,8}\.?,?\s+\d{4}|[A-Z][a-z]{2,8}\.?\s+\d{1,2}(?:st|nd|rd|th)?,?\s+\d{4})\b/g,
+        // A date is not personal data on its own; only "born"/"DOB"-style context lifts it over the threshold.
+        score: (v) => {
+            const date = parseDate(v);
+            if (!date)
+                return undefined;
+            const year = date.getUTCFullYear();
+            return year >= 1900 && date.getTime() <= Date.now() ? 0.1 : undefined;
+        },
+        context: ["born", "birth", "dob", "d.o.b", "birthday", "birthdate", "date of birth"],
+        contextBoost: 0.6,
+        // "shipped 2024-01-15. I was born ..." — the next sentence's context must not leak backwards onto this date.
+        contextAfter: 0,
+    },
+    {
+        name: "jwt",
+        type: "CREDENTIAL",
+        pattern: /\beyJ[A-Za-z0-9_-]{4,}\.eyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{8,}/g,
+        score: (v) => (jwtValid(v) ? 0.95 : undefined),
+    },
+    {
+        name: "private-key",
+        type: "CREDENTIAL",
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+        score: () => 0.99,
+    },
+    {
+        name: "vendor-api-key",
+        type: "CREDENTIAL",
+        // Vendor-published, fixed-prefix credential formats (OpenAI/Anthropic, GitHub, AWS, Slack, Google, Stripe).
+        pattern: /\b(?:sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,}|(?:AKIA|ASIA)[0-9A-Z]{16}|xox[abposr]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{35}|(?:sk|rk)_live_[0-9A-Za-z]{16,})/g,
+        score: () => 0.95,
+    },
+    {
+        name: "secret-assignment",
+        type: "CREDENTIAL",
+        pattern: /\b(?:password|passwd|pwd|passphrase|secret|client[_-]?secret|api[_-]?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|bearer|private[_-]?key)\b["']?\s*(?:[:=]|\bis\b)?\s*["']?([^\s"',;]{4,})/gi,
+        group: 1,
+        // "password is incorrect" captures "incorrect": a plain lowercase word is not scored as a secret.
+        score: (v) => (/[\d\W_]/.test(v) || /[A-Z]/.test(v.slice(1)) || v.length >= 16 ? 0.85 : undefined),
+    },
+    {
+        name: "high-entropy-secret",
+        type: "CREDENTIAL",
+        pattern: /(?<![A-Za-z0-9+/_=[-])[A-Za-z0-9+/_=-]{24,}(?![A-Za-z0-9+/_=\]-])/g,
+        score: (v) => {
+            const classes = [/[a-z]/, /[A-Z]/, /\d/, /[+/_=-]/].filter((re) => re.test(v)).length;
+            return classes >= 3 && shannonEntropy(v) >= 4 ? 0.45 : undefined;
+        },
+        context: ["key", "token", "secret", "bearer", "authorization", "credential", "api", "password", "auth"],
+        contextBoost: 0.4,
+    },
+    {
+        name: "person-introduced",
+        type: "PERSON",
+        pattern: /\b(?:[Mm]y name is|[Mm]y name's|[Nn]ame\s*(?:is|:)|[Ss]igned(?: by)?,?|[Cc]ustomer\s*:|[Pp]atient\s*:|[Cc]ontact\s*:|[Dd]ear)\s+((?:[A-Z][a-z'’-]+)(?:\s+(?:[A-Z][a-z'’-]+|[A-Z]\.)){0,3})/g,
+        group: 1,
+        score: (v) => (NON_NAME_WORDS.has(v.split(/\s+/)[0]) ? undefined : 0.75),
+    },
+    {
+        name: "person-role",
+        type: "PERSON",
+        // "Customer Priya Sharma reported..." — a role noun followed by a first-plus-last shape. One capitalized word is not
+        // enough ("Customer Service"), and department words are excluded.
+        pattern: /\b(?:[Cc]ustomer|[Cc]lient|[Pp]atient|[Uu]ser|[Mm]ember|[Ee]mployee|[Aa]pplicant|[Gg]uest|[Pp]assenger|[Tt]enant|[Ss]tudent|[Cc]andidate)\s+([A-Z][a-z'’-]+\s+[A-Z][a-z'’-]+)\b/g,
+        group: 1,
+        score: (v) => (v.split(/\s+/).some((w) => NON_NAME_WORDS.has(w)) ? undefined : 0.6),
+    },
+    {
+        name: "person-self-reference",
+        type: "PERSON",
+        // "I am Excited" is not a name; "I am Priya Sharma" probably is. Only a first-plus-last shape clears the threshold.
+        pattern: /\b(?:[Ii] am|[Ii]'m|[Tt]his is)\s+((?:[A-Z][a-z'’-]+)(?:\s+[A-Z][a-z'’-]+){0,2})/g,
+        group: 1,
+        score: (v) => (NON_NAME_WORDS.has(v.split(/\s+/)[0]) ? undefined : v.includes(" ") ? 0.55 : 0.3),
+    },
+    {
+        name: "person-honorific",
+        type: "PERSON",
+        pattern: /\b(?:Mr|Mrs|Ms|Miss|Mx|Dr|Prof|Shri|Smt)\.?\s+([A-Z][a-z'’-]+(?:\s+[A-Z][a-z'’-]+){0,2})/g,
+        group: 1,
+        score: (v) => (NON_NAME_WORDS.has(v.split(/\s+/)[0]) ? undefined : 0.8),
+    },
+    {
+        name: "person-signoff",
+        type: "PERSON",
+        pattern: /\b(?:Regards|Sincerely|Thanks|Thank you|Best|Cheers|Warmly|Yours truly)[,!.]?[ \t]*\r?\n+[ \t]*([A-Z][a-z'’-]+(?:[ \t]+[A-Z][a-z'’-]+){0,2})/g,
+        group: 1,
+        score: (v) => (NON_NAME_WORDS.has(v.split(/\s+/)[0]) ? undefined : 0.6),
+    },
+    {
+        name: "street-address",
+        type: "ADDRESS",
+        // USPS Publication 28 street suffixes (plus common Indian/UK forms), after a house number and capitalized words.
+        pattern: /\b\d{1,6}[A-Za-z]?,?\s+(?:[A-Z][A-Za-z.'-]*\s+){1,4}(?:Street|St|Avenue|Ave|Road|Rd|Boulevard|Blvd|Lane|Ln|Drive|Dr|Court|Ct|Way|Place|Pl|Terrace|Ter|Circle|Cir|Highway|Hwy|Parkway|Pkwy|Square|Sq|Trail|Trl|Crescent|Close|Marg|Nagar)\b\.?(?:,?\s*(?:Apt|Apartment|Suite|Ste|Unit|Flat|#)\.?\s*[A-Za-z0-9-]+)?/g,
+        score: () => 0.7,
+    },
+];
+/** Capitalized words that follow "Hi"/"I am"/"Dear" without being a name. */
+const NON_NAME_WORDS = new Set([
+    "Team", "All", "There", "Everyone", "World", "Sir", "Madam", "Support", "Customer", "Guys", "Folks", "Bot", "Assistant",
+    "The", "A", "An", "Not", "Very", "So", "Just", "Happy", "Sorry", "Here", "Going", "Looking", "Writing", "Calling",
+    "Trying", "Unable", "Interested", "New", "Please", "Hello", "Hi", "Thanks", "Thank", "User", "Admin", "Available",
+    "Service", "Services", "Success", "Care", "Experience", "Relations", "Portal", "Account", "Accounts", "Data", "Feedback",
+    "Satisfaction", "Journey", "Segment", "Profile", "Record", "Records", "Id", "Number", "Name", "Group", "Manager", "Interface",
+]);
+const contextRegexCache = new WeakMap();
+function contextRegex(words) {
+    let re = contextRegexCache.get(words);
+    if (!re) {
+        re = new RegExp(`(?:^|[^a-z0-9])(?:${words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?:$|[^a-z0-9])`, "i");
+        contextRegexCache.set(words, re);
+    }
+    return re;
+}
+function window(text, start, end, after) {
+    return text.slice(Math.max(0, start - CONTEXT_BEFORE), start) + " " + text.slice(end, end + after);
+}
+/** Runs one recognizer over `text`, applying its validator and context scoring. */
+export function runRecognizer(recognizer, text) {
+    const detections = [];
+    const pattern = new RegExp(recognizer.pattern.source, recognizer.pattern.flags.includes("d") ? recognizer.pattern.flags : recognizer.pattern.flags + "d");
+    for (const match of text.matchAll(pattern)) {
+        const group = recognizer.group ?? 0;
+        const value = match[group];
+        const indices = match.indices?.[group];
+        if (!value || !indices)
+            continue;
+        const base = recognizer.score(value);
+        if (base === undefined)
+            continue;
+        const [start, end] = indices;
+        let score = base;
+        const around = window(text, start, end, recognizer.contextAfter ?? CONTEXT_AFTER);
+        if (recognizer.context && contextRegex(recognizer.context).test(around))
+            score += recognizer.contextBoost ?? 0.35;
+        if (recognizer.negativeContext && contextRegex(recognizer.negativeContext).test(text.slice(Math.max(0, start - CONTEXT_BEFORE), start)))
+            score -= NEGATIVE_PENALTY;
+        detections.push({ type: recognizer.type, start, end, score: Math.max(0, Math.min(1, score)) });
+    }
+    return detections;
+}

package/dist/detectors/validators.d.ts

@@ -0,0 +1,29 @@
+/** ISO/IEC 7812-1 Annex B (Luhn mod 10). */
+export declare function luhnValid(digits: string): boolean;
+/** Card brand from the issuer identification number (IIN) ranges published by the networks. Undefined if unknown. */
+export declare function cardBrand(digits: string): string | undefined;
+/** ISO 13616 / ISO 7064 MOD 97-10: country length check plus the mod-97 checksum. */
+export declare function ibanValid(raw: string): boolean;
+/**
+ * US SSN structural rules (SSA): area not 000, 666 or 900-999; group not 00; serial not 0000. Also rejects the
+ * well-known advertising/test numbers that are frequently used as fake data.
+ */
+export declare function ssnValid(digits: string): boolean;
+/** Verhoeff checksum — the check digit UIDAI uses for Aadhaar numbers. */
+export declare function verhoeffValid(digits: string): boolean;
+/** Aadhaar: 12 digits, first digit 2-9, valid Verhoeff check digit, not a repeated digit. */
+export declare function aadhaarValid(digits: string): boolean;
+/**
+ * RFC 5321/5322 structural limits: local part at most 64 octets, address at most 254, no leading, trailing or
+ * doubled dots in the local part, each domain label 1-63 chars without edge hyphens, and an alphabetic TLD.
+ */
+export declare function emailValid(candidate: string): boolean;
+export declare function ipVersion(candidate: string): 4 | 6 | 0;
+/** RFC 1918 private, loopback, link-local, CGNAT and unspecified IPv4 ranges — less identifying than public addresses. */
+export declare function isNonPublicIPv4(ip: string): boolean;
+/** Shannon entropy in bits per character. */
+export declare function shannonEntropy(text: string): number;
+/** RFC 7519: a JWT's first segment is base64url JSON with an `alg` member. */
+export declare function jwtValid(candidate: string): boolean;
+/** Parses the common written date shapes; returns undefined for anything that is not a real calendar date. */
+export declare function parseDate(text: string): Date | undefined;