@abhishekvardanbotta/mask 0.0.0-stage → 0.1.0

package/dist/detectors/validators.js

@@ -0,0 +1,209 @@
+import { isIPv4, isIPv6 } from "node:net";
+/** ISO/IEC 7812-1 Annex B (Luhn mod 10). */
+export function luhnValid(digits) {
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (d < 0 || d > 9)
+            return false;
+        if (double) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        double = !double;
+    }
+    return digits.length > 0 && sum % 10 === 0;
+}
+/** Card brand from the issuer identification number (IIN) ranges published by the networks. Undefined if unknown. */
+export function cardBrand(digits) {
+    const n2 = Number(digits.slice(0, 2));
+    const n3 = Number(digits.slice(0, 3));
+    const n4 = Number(digits.slice(0, 4));
+    const n6 = Number(digits.slice(0, 6));
+    const len = digits.length;
+    if (digits[0] === "4" && (len === 13 || len === 16 || len === 19))
+        return "visa";
+    if (((n2 >= 51 && n2 <= 55) || (n4 >= 2221 && n4 <= 2720)) && len === 16)
+        return "mastercard";
+    if ((n2 === 34 || n2 === 37) && len === 15)
+        return "amex";
+    if ((n4 === 6011 || n2 === 65 || (n3 >= 644 && n3 <= 649) || (n6 >= 622126 && n6 <= 622925)) && len >= 16 && len <= 19)
+        return "discover";
+    if (n4 >= 3528 && n4 <= 3589 && len >= 16 && len <= 19)
+        return "jcb";
+    if (((n3 >= 300 && n3 <= 305) || n2 === 36 || n2 === 38 || n2 === 39) && len >= 14 && len <= 19)
+        return "diners";
+    if ((n2 === 60 || n2 === 81 || n2 === 82 || n3 === 508) && len === 16)
+        return "rupay";
+    if ((n2 === 50 || (n2 >= 56 && n2 <= 69)) && len >= 12 && len <= 19)
+        return "maestro";
+    return undefined;
+}
+/** IBAN lengths per country, ISO 13616 registry (SWIFT IBAN Registry). */
+const IBAN_LENGTHS = {
+    AD: 24, AE: 23, AL: 28, AT: 20, AZ: 28, BA: 20, BE: 16, BG: 22, BH: 22, BR: 29, BY: 28, CH: 21, CR: 22, CY: 28,
+    CZ: 24, DE: 22, DK: 18, DO: 28, EE: 20, EG: 29, ES: 24, FI: 18, FO: 18, FR: 27, GB: 22, GE: 22, GI: 23, GL: 18,
+    GR: 27, GT: 28, HR: 21, HU: 28, IE: 22, IL: 23, IQ: 23, IS: 26, IT: 27, JO: 30, KW: 30, KZ: 20, LB: 28, LC: 32,
+    LI: 21, LT: 20, LU: 20, LV: 21, MC: 27, MD: 24, ME: 22, MK: 19, MR: 27, MT: 31, MU: 30, NL: 18, NO: 15, PK: 24,
+    PL: 28, PS: 29, PT: 25, QA: 29, RO: 24, RS: 22, SA: 24, SC: 31, SE: 24, SI: 19, SK: 24, SM: 27, ST: 25, SV: 28,
+    TL: 23, TN: 24, TR: 26, UA: 29, VA: 22, VG: 24, XK: 20,
+};
+/** ISO 13616 / ISO 7064 MOD 97-10: country length check plus the mod-97 checksum. */
+export function ibanValid(raw) {
+    const iban = raw.replace(/\s+/g, "").toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]+$/.test(iban))
+        return false;
+    if (IBAN_LENGTHS[iban.slice(0, 2)] !== iban.length)
+        return false;
+    const rearranged = iban.slice(4) + iban.slice(0, 4);
+    let remainder = 0;
+    for (const ch of rearranged) {
+        const value = ch >= "A" && ch <= "Z" ? String(ch.charCodeAt(0) - 55) : ch;
+        for (const digit of value)
+            remainder = (remainder * 10 + (digit.charCodeAt(0) - 48)) % 97;
+    }
+    return remainder === 1;
+}
+/**
+ * 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 function ssnValid(digits) {
+    if (!/^\d{9}$/.test(digits))
+        return false;
+    const area = Number(digits.slice(0, 3));
+    const group = Number(digits.slice(3, 5));
+    const serial = Number(digits.slice(5));
+    if (area === 0 || area === 666 || area >= 900 || group === 0 || serial === 0)
+        return false;
+    if (digits === "078051120" || digits === "219099999")
+        return false;
+    return !/^(\d)\1{8}$/.test(digits);
+}
+const VERHOEFF_D = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 2, 3, 4, 0, 6, 7, 8, 9, 5], [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+    [3, 4, 0, 1, 2, 8, 9, 5, 6, 7], [4, 0, 1, 2, 3, 9, 5, 6, 7, 8], [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+    [6, 5, 9, 8, 7, 1, 0, 4, 3, 2], [7, 6, 5, 9, 8, 2, 1, 0, 4, 3], [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+    [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+];
+const VERHOEFF_P = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 5, 7, 6, 2, 8, 3, 0, 9, 4], [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+    [8, 9, 1, 6, 0, 4, 3, 5, 2, 7], [9, 4, 5, 3, 1, 2, 6, 8, 7, 0], [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+    [2, 7, 9, 3, 8, 0, 6, 4, 1, 5], [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+];
+/** Verhoeff checksum — the check digit UIDAI uses for Aadhaar numbers. */
+export function verhoeffValid(digits) {
+    let c = 0;
+    const reversed = [...digits].reverse();
+    for (let i = 0; i < reversed.length; i++)
+        c = VERHOEFF_D[c][VERHOEFF_P[i % 8][reversed[i].charCodeAt(0) - 48]];
+    return c === 0;
+}
+/** Aadhaar: 12 digits, first digit 2-9, valid Verhoeff check digit, not a repeated digit. */
+export function aadhaarValid(digits) {
+    return /^[2-9]\d{11}$/.test(digits) && !/^(\d)\1{11}$/.test(digits) && verhoeffValid(digits);
+}
+/**
+ * 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 function emailValid(candidate) {
+    if (candidate.length > 254)
+        return false;
+    const at = candidate.lastIndexOf("@");
+    if (at <= 0)
+        return false;
+    const local = candidate.slice(0, at);
+    const domain = candidate.slice(at + 1);
+    if (local.length > 64 || local.startsWith(".") || local.endsWith(".") || local.includes(".."))
+        return false;
+    const labels = domain.split(".");
+    if (labels.length < 2)
+        return false;
+    for (const label of labels) {
+        if (!label || label.length > 63 || label.startsWith("-") || label.endsWith("-"))
+            return false;
+    }
+    const tld = labels[labels.length - 1];
+    return /^[A-Za-z]{2,63}$/.test(tld) || /^xn--[A-Za-z0-9-]+$/.test(tld);
+}
+export function ipVersion(candidate) {
+    if (isIPv4(candidate))
+        return 4;
+    if (isIPv6(candidate))
+        return 6;
+    return 0;
+}
+/** RFC 1918 private, loopback, link-local, CGNAT and unspecified IPv4 ranges — less identifying than public addresses. */
+export function isNonPublicIPv4(ip) {
+    const [a, b] = ip.split(".").map(Number);
+    return a === 10 || a === 127 || a === 0 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127);
+}
+/** Shannon entropy in bits per character. */
+export function shannonEntropy(text) {
+    if (!text)
+        return 0;
+    const counts = new Map();
+    for (const ch of text)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / text.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+/** RFC 7519: a JWT's first segment is base64url JSON with an `alg` member. */
+export function jwtValid(candidate) {
+    const [header] = candidate.split(".");
+    try {
+        const decoded = JSON.parse(Buffer.from(header, "base64url").toString("utf8"));
+        return typeof decoded === "object" && decoded !== null && "alg" in decoded;
+    }
+    catch {
+        return false;
+    }
+}
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+/** Parses the common written date shapes; returns undefined for anything that is not a real calendar date. */
+export function parseDate(text) {
+    let y, m, d;
+    let match;
+    if ((match = text.match(/^(\d{4})[-/.](\d{1,2})[-/.](\d{1,2})$/))) {
+        y = +match[1];
+        m = +match[2];
+        d = +match[3];
+    }
+    else if ((match = text.match(/^(\d{1,2})[-/.](\d{1,2})[-/.](\d{4})$/))) {
+        // Ambiguous DD/MM vs MM/DD: accept if either reading is a real date.
+        y = +match[3];
+        const a = +match[1], b = +match[2];
+        if (a > 12) {
+            d = a;
+            m = b;
+        }
+        else {
+            m = a;
+            d = b;
+        }
+    }
+    else if ((match = text.match(/^(\d{1,2})(?:st|nd|rd|th)?\s+([A-Za-z]{3,9})\.?,?\s+(\d{4})$/))) {
+        d = +match[1];
+        m = MONTHS.indexOf(match[2].slice(0, 3).toLowerCase()) + 1;
+        y = +match[3];
+    }
+    else if ((match = text.match(/^([A-Za-z]{3,9})\.?\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(\d{4})$/))) {
+        m = MONTHS.indexOf(match[1].slice(0, 3).toLowerCase()) + 1;
+        d = +match[2];
+        y = +match[3];
+    }
+    else
+        return undefined;
+    if (m < 1 || m > 12 || d < 1 || d > 31 || y < 1000)
+        return undefined;
+    const date = new Date(Date.UTC(y, m - 1, d));
+    return date.getUTCMonth() === m - 1 && date.getUTCDate() === d ? date : undefined;
+}

package/dist/fields.d.ts

@@ -0,0 +1,39 @@
+import type { Classification, EntityType, FieldClass } from "./types.js";
+export declare function isClassification(value: unknown): value is Classification;
+/** Splits `billingEmail`, `billing_email`, `billing-email`, `BillingEMAIL` into lowercase words. */
+export declare function keyWords(key: string): string[];
+/** Infers what a field holds from its key (and, for a bare `name`, its parent key). Undefined if it cannot tell. */
+export declare function inferFieldType(key: string, parentKey?: string): EntityType | undefined;
+/** `medicalHistory` -> `MEDICAL_HISTORY`, for custom types derived from a field's own name. */
+export declare function typeFromKey(key: string): EntityType;
+export interface CompiledFieldRule {
+    pattern: string;
+    segments: string[];
+    value: FieldClass;
+}
+export declare function compileFieldRules(fields: Record<string, Classification | FieldClass> | undefined): CompiledFieldRule[];
+export declare function matchFieldRule(rules: readonly CompiledFieldRule[], path: string[]): FieldClass | undefined;
+type SchemaNode = Record<string, unknown>;
+declare function asNode(value: unknown): SchemaNode | undefined;
+/**
+ * Reads a schema node's own privacy annotation, in order of precedence:
+ *   1. `"x-privacy": "SENSITIVE"` or `"x-privacy": { "classification": "SENSITIVE", "type": "HEALTH" }` (plus `"x-pii-type"`)
+ *   2. a `privacy:CLASS[:TYPE]` tag in `description` — what zod's `.describe("privacy:PII:EMAIL")` produces
+ *   3. standard JSON Schema `format`: `email`/`idn-email` -> EMAIL, `ipv4`/`ipv6` -> IP_ADDRESS
+ * The classification of a format-derived type comes from the policy, so it is returned without one.
+ */
+export declare function schemaAnnotation(node: SchemaNode | undefined): (Partial<FieldClass> & {
+    type?: EntityType;
+}) | undefined;
+/** Resolves local `$ref`s (`#/definitions/...`, `#/$defs/...`) against the root schema. */
+export declare function resolveRef(root: SchemaNode, node: SchemaNode | undefined, depth?: number): SchemaNode | undefined;
+/** The subschema for property `key` of an object node. */
+export declare function propertySchema(root: SchemaNode, node: SchemaNode | undefined, key: string): SchemaNode | undefined;
+/** The subschema for element `index` of an array node. */
+export declare function itemSchema(root: SchemaNode, node: SchemaNode | undefined, index: number): SchemaNode | undefined;
+/** A node's annotation, looking through allOf/anyOf/oneOf (zod-to-json-schema wraps `.optional()`/`.nullable()` that way). */
+export declare function nodeAnnotation(root: SchemaNode, node: SchemaNode | undefined): (Partial<FieldClass> & {
+    type?: EntityType;
+}) | undefined;
+export { asNode };
+export type { SchemaNode };

package/dist/fields.js

@@ -0,0 +1,219 @@
+const CLASSIFICATIONS = new Set(["PII", "SENSITIVE", "PUBLIC", "BLOCK"]);
+export function isClassification(value) {
+    return typeof value === "string" && CLASSIFICATIONS.has(value);
+}
+/** Splits `billingEmail`, `billing_email`, `billing-email`, `BillingEMAIL` into lowercase words. */
+export function keyWords(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((w) => w.toLowerCase());
+}
+/**
+ * Field-name vocabulary: the joined word sequence a key ends with, mapped to the entity type it names. Matching is
+ * on the key's trailing words, so `customerEmail` and `billing_email` match `email` while `emailVerified`,
+ * `emailCount` and `phoneType` do not — the last word decides what the field holds.
+ */
+const FIELD_VOCABULARY = {
+    email: "EMAIL", emailaddress: "EMAIL", mail: "EMAIL", emailid: "EMAIL",
+    phone: "PHONE", phonenumber: "PHONE", phoneno: "PHONE", mobile: "PHONE", mobilenumber: "PHONE",
+    cellphone: "PHONE", telephone: "PHONE", tel: "PHONE", msisdn: "PHONE", whatsapp: "PHONE", fax: "PHONE",
+    firstname: "PERSON", lastname: "PERSON", fullname: "PERSON", givenname: "PERSON", familyname: "PERSON", surname: "PERSON",
+    middlename: "PERSON", maidenname: "PERSON", legalname: "PERSON", displayname: "PERSON", nickname: "PERSON",
+    username: "USERNAME", screenname: "USERNAME",
+    address: "ADDRESS", streetaddress: "ADDRESS", street: "ADDRESS", addressline: "ADDRESS", addressline1: "ADDRESS",
+    addressline2: "ADDRESS", postalcode: "ADDRESS", postcode: "ADDRESS", zipcode: "ADDRESS", zip: "ADDRESS", pincode: "ADDRESS",
+    latitude: "LOCATION", longitude: "LOCATION", lat: "LOCATION", lng: "LOCATION", lon: "LOCATION", geolocation: "LOCATION", coordinates: "LOCATION",
+    dob: "DATE_OF_BIRTH", dateofbirth: "DATE_OF_BIRTH", birthdate: "DATE_OF_BIRTH", birthday: "DATE_OF_BIRTH",
+    ip: "IP_ADDRESS", ipaddress: "IP_ADDRESS", ipaddr: "IP_ADDRESS", remoteaddr: "IP_ADDRESS", remoteaddress: "IP_ADDRESS",
+    creditcard: "CREDIT_CARD", cardnumber: "CREDIT_CARD", ccnumber: "CREDIT_CARD", cardno: "CREDIT_CARD", pan: "CREDIT_CARD",
+    cvv: "CARD_SECURITY_CODE", cvc: "CARD_SECURITY_CODE", cvv2: "CARD_SECURITY_CODE", securitycode: "CARD_SECURITY_CODE", cardpin: "CARD_SECURITY_CODE",
+    iban: "IBAN", bankaccount: "BANK_ACCOUNT", accountnumber: "BANK_ACCOUNT", bankaccountnumber: "BANK_ACCOUNT", routingnumber: "BANK_ACCOUNT", sortcode: "BANK_ACCOUNT", ifsc: "BANK_ACCOUNT",
+    ssn: "US_SSN", socialsecuritynumber: "US_SSN", socialsecurity: "US_SSN",
+    aadhaar: "IN_AADHAAR", aadhar: "IN_AADHAAR", aadhaarnumber: "IN_AADHAAR", pannumber: "IN_PAN",
+    nationalid: "NATIONAL_ID", nationalidnumber: "NATIONAL_ID", taxid: "NATIONAL_ID", tin: "NATIONAL_ID", nin: "NATIONAL_ID", sin: "NATIONAL_ID", nric: "NATIONAL_ID",
+    passport: "PASSPORT", passportnumber: "PASSPORT", passportno: "PASSPORT",
+    driverslicense: "DRIVERS_LICENSE", driverlicense: "DRIVERS_LICENSE", drivinglicense: "DRIVERS_LICENSE", licensenumber: "DRIVERS_LICENSE",
+    diagnosis: "HEALTH", diagnoses: "HEALTH", medicalhistory: "HEALTH", medicalrecord: "HEALTH", medication: "HEALTH", medications: "HEALTH",
+    prescription: "HEALTH", allergies: "HEALTH", allergy: "HEALTH", bloodtype: "HEALTH", disability: "HEALTH", healthcondition: "HEALTH",
+    symptoms: "HEALTH",
+    religion: "SPECIAL_CATEGORY", ethnicity: "SPECIAL_CATEGORY", race: "SPECIAL_CATEGORY", sexualorientation: "SPECIAL_CATEGORY",
+    politicalaffiliation: "SPECIAL_CATEGORY", politicalopinion: "SPECIAL_CATEGORY", tradeunion: "SPECIAL_CATEGORY",
+    biometric: "SPECIAL_CATEGORY", biometricdata: "SPECIAL_CATEGORY", genetic: "SPECIAL_CATEGORY", geneticdata: "SPECIAL_CATEGORY",
+    password: "CREDENTIAL", passwd: "CREDENTIAL", passphrase: "CREDENTIAL", secret: "CREDENTIAL", clientsecret: "CREDENTIAL",
+    apikey: "CREDENTIAL", apisecret: "CREDENTIAL", accesstoken: "CREDENTIAL", refreshtoken: "CREDENTIAL", idtoken: "CREDENTIAL",
+    authtoken: "CREDENTIAL", bearertoken: "CREDENTIAL", sessiontoken: "CREDENTIAL", privatekey: "CREDENTIAL", accesskey: "CREDENTIAL",
+    secretkey: "CREDENTIAL", otp: "CREDENTIAL", pin: "CREDENTIAL",
+};
+/** Parent keys that make a bare `name` field a person's name (`customer.name`, `patients[].name`). */
+const PERSON_CONTAINERS = new Set([
+    "customer", "customers", "user", "users", "patient", "patients", "person", "people", "persons", "contact", "contacts",
+    "employee", "employees", "member", "members", "client", "clients", "owner", "recipient", "sender", "author", "applicant",
+    "holder", "cardholder", "guest", "passenger", "student", "candidate", "beneficiary", "account", "profile", "lead", "buyer", "seller",
+]);
+/** Words that, placed before `name`, make it a person's name (`customerName`, `patient_name`). */
+const PERSON_QUALIFIERS = new Set([...PERSON_CONTAINERS, "first", "last", "full", "given", "family", "middle", "maiden", "legal", "contact", "billing", "shipping", "emergency"]);
+/** Infers what a field holds from its key (and, for a bare `name`, its parent key). Undefined if it cannot tell. */
+export function inferFieldType(key, parentKey) {
+    const words = keyWords(key);
+    if (!words.length)
+        return undefined;
+    for (let i = 0; i < words.length; i++) {
+        const tail = words.slice(i).join("");
+        const type = FIELD_VOCABULARY[tail];
+        if (type)
+            return type;
+    }
+    if (words[words.length - 1] === "name") {
+        if (words.length > 1 && PERSON_QUALIFIERS.has(words[words.length - 2]))
+            return "PERSON";
+        if (words.length === 1 && parentKey !== undefined) {
+            const parentWords = keyWords(parentKey);
+            if (parentWords.length && PERSON_CONTAINERS.has(parentWords[parentWords.length - 1]))
+                return "PERSON";
+        }
+    }
+    return undefined;
+}
+/** `medicalHistory` -> `MEDICAL_HISTORY`, for custom types derived from a field's own name. */
+export function typeFromKey(key) {
+    const words = keyWords(key);
+    return (words.length ? words.join("_") : "FIELD").toUpperCase();
+}
+export function compileFieldRules(fields) {
+    const rules = [];
+    for (const [pattern, raw] of Object.entries(fields ?? {})) {
+        const value = typeof raw === "string" ? { classification: raw } : raw;
+        if (!isClassification(value.classification))
+            throw new TypeError(`mask: field "${pattern}" has an invalid classification ${JSON.stringify(value.classification)}`);
+        const segments = pattern.split(".").filter(Boolean);
+        // A bare key ("ssn") means that key at any depth.
+        rules.push({ pattern, segments: segments.length === 1 && segments[0] !== "**" ? ["**", segments[0]] : segments, value });
+    }
+    // More specific (longer, fewer wildcards) rules first.
+    return rules.sort((a, b) => specificity(b.segments) - specificity(a.segments));
+}
+function specificity(segments) {
+    return segments.reduce((n, s) => n + (s === "**" ? 0 : s === "*" ? 1 : 3), 0);
+}
+function matchSegments(pattern, path, pi = 0, si = 0) {
+    if (pi === pattern.length)
+        return si === path.length;
+    const seg = pattern[pi];
+    if (seg === "**") {
+        for (let k = si; k <= path.length; k++)
+            if (matchSegments(pattern, path, pi + 1, k))
+                return true;
+        return false;
+    }
+    if (si === path.length)
+        return false;
+    return (seg === "*" || seg === path[si]) && matchSegments(pattern, path, pi + 1, si + 1);
+}
+export function matchFieldRule(rules, path) {
+    for (const rule of rules)
+        if (matchSegments(rule.segments, path))
+            return rule.value;
+    return undefined;
+}
+function asNode(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+const DESCRIPTION_TAG = /\bprivacy\s*:\s*(PII|SENSITIVE|PUBLIC|BLOCK)(?:\s*:\s*([A-Za-z][A-Za-z0-9_]*))?/i;
+/**
+ * Reads a schema node's own privacy annotation, in order of precedence:
+ *   1. `"x-privacy": "SENSITIVE"` or `"x-privacy": { "classification": "SENSITIVE", "type": "HEALTH" }` (plus `"x-pii-type"`)
+ *   2. a `privacy:CLASS[:TYPE]` tag in `description` — what zod's `.describe("privacy:PII:EMAIL")` produces
+ *   3. standard JSON Schema `format`: `email`/`idn-email` -> EMAIL, `ipv4`/`ipv6` -> IP_ADDRESS
+ * The classification of a format-derived type comes from the policy, so it is returned without one.
+ */
+export function schemaAnnotation(node) {
+    if (!node)
+        return undefined;
+    const ext = node["x-privacy"];
+    const extType = typeof node["x-pii-type"] === "string" ? node["x-pii-type"].toUpperCase() : undefined;
+    if (isClassification(ext))
+        return { classification: ext, type: extType };
+    if (ext && typeof ext === "object" && isClassification(ext.classification)) {
+        const declared = ext.type;
+        return { classification: ext.classification, type: declared ? declared.toUpperCase() : extType };
+    }
+    if (typeof node.description === "string") {
+        const tag = DESCRIPTION_TAG.exec(node.description);
+        if (tag)
+            return { classification: tag[1].toUpperCase(), type: tag[2]?.toUpperCase() ?? extType };
+    }
+    if (node.format === "email" || node.format === "idn-email")
+        return { type: "EMAIL" };
+    if (node.format === "ipv4" || node.format === "ipv6")
+        return { type: "IP_ADDRESS" };
+    if (extType)
+        return { type: extType };
+    return undefined;
+}
+/** Resolves local `$ref`s (`#/definitions/...`, `#/$defs/...`) against the root schema. */
+export function resolveRef(root, node, depth = 0) {
+    if (!node || depth > 32)
+        return node;
+    const ref = node.$ref;
+    if (typeof ref !== "string" || !ref.startsWith("#"))
+        return node;
+    let target = root;
+    for (const part of ref.slice(1).split("/").filter(Boolean)) {
+        target = asNode(target)?.[part.replace(/~1/g, "/").replace(/~0/g, "~")];
+    }
+    return resolveRef(root, asNode(target), depth + 1);
+}
+/** The variants a node allows — itself plus its allOf/anyOf/oneOf members, refs resolved. */
+function variants(root, node) {
+    const resolved = resolveRef(root, node);
+    if (!resolved)
+        return [];
+    const out = [resolved];
+    for (const key of ["allOf", "anyOf", "oneOf"]) {
+        const list = resolved[key];
+        if (Array.isArray(list))
+            for (const member of list)
+                out.push(...variants(root, asNode(member)));
+    }
+    return out;
+}
+/** The subschema for property `key` of an object node. */
+export function propertySchema(root, node, key) {
+    for (const variant of variants(root, node)) {
+        const props = asNode(variant.properties);
+        if (props && key in props)
+            return resolveRef(root, asNode(props[key]));
+    }
+    for (const variant of variants(root, node)) {
+        const extra = asNode(variant.additionalProperties);
+        if (extra)
+            return resolveRef(root, extra);
+    }
+    return undefined;
+}
+/** The subschema for element `index` of an array node. */
+export function itemSchema(root, node, index) {
+    for (const variant of variants(root, node)) {
+        if (Array.isArray(variant.prefixItems) && index < variant.prefixItems.length)
+            return resolveRef(root, asNode(variant.prefixItems[index]));
+        if (Array.isArray(variant.items))
+            return resolveRef(root, asNode(variant.items[index]));
+        const items = asNode(variant.items);
+        if (items)
+            return resolveRef(root, items);
+    }
+    return undefined;
+}
+/** A node's annotation, looking through allOf/anyOf/oneOf (zod-to-json-schema wraps `.optional()`/`.nullable()` that way). */
+export function nodeAnnotation(root, node) {
+    for (const variant of variants(root, node)) {
+        const annotation = schemaAnnotation(variant);
+        if (annotation)
+            return annotation;
+    }
+    return undefined;
+}
+export { asNode };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createPrivacy, Privacy, PrivacySession, StreamRestorer } from "./privacy.js";
+export type { PrivacyOptions } from "./privacy.js";
+export { DEFAULT_POLICIES, compilePolicy, isGranted, maskValue, mergePolicyConfig } from "./policy.js";
+export type { CompiledPolicy } from "./policy.js";
+export { BUILT_IN_RECOGNIZERS } from "./detectors/recognizers.js";
+export type { Recognizer } from "./detectors/recognizers.js";
+export { aadhaarValid, cardBrand, emailValid, ibanValid, luhnValid, shannonEntropy, ssnValid, verhoeffValid } from "./detectors/validators.js";
+export { inferFieldType } from "./fields.js";
+export { generateKey } from "./crypto.js";
+export { InMemoryVaultStore } from "./vault.js";
+export type { VaultRecord, VaultStore } from "./vault.js";
+export { PrivacyError } from "./types.js";
+export type { AuditEvent, BuiltInEntityType, Classification, DeniedMode, Detection, Detector, EntityType, FieldClass, Grant, PolicyConfig, PrivacySummary, ProtectOptions, RestoreOptions, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createPrivacy, Privacy, PrivacySession, StreamRestorer } from "./privacy.js";
+export { DEFAULT_POLICIES, compilePolicy, isGranted, maskValue, mergePolicyConfig } from "./policy.js";
+export { BUILT_IN_RECOGNIZERS } from "./detectors/recognizers.js";
+export { aadhaarValid, cardBrand, emailValid, ibanValid, luhnValid, shannonEntropy, ssnValid, verhoeffValid } from "./detectors/validators.js";
+export { inferFieldType } from "./fields.js";
+export { generateKey } from "./crypto.js";
+export { InMemoryVaultStore } from "./vault.js";
+export { PrivacyError } from "./types.js";

package/dist/policy.d.ts

@@ -0,0 +1,36 @@
+import { type Recognizer } from "./detectors/recognizers.js";
+import { type CompiledFieldRule } from "./fields.js";
+import type { Classification, DeniedMode, Detector, EntityType, Grant, PolicyConfig } from "./types.js";
+/**
+ * Default handling per entity type, following NIST SP 800-122's confidentiality-impact guidance, GDPR Art. 9
+ * special categories, and PCI DSS v4.0:
+ *  - direct identifiers and contact data -> PII
+ *  - government IDs, financial accounts, card numbers, health and Art. 9 data -> SENSITIVE
+ *  - card security codes (sensitive authentication data, which PCI DSS 3.3.1 forbids storing) and credentials -> BLOCK
+ * Types not listed (custom ones) default to PII.
+ */
+export declare const DEFAULT_POLICIES: Readonly<Record<string, Classification>>;
+export interface CompiledPolicy {
+    readonly threshold: number;
+    readonly recognizers: readonly Recognizer[];
+    readonly detectors: readonly Detector[];
+    readonly fieldRules: readonly CompiledFieldRule[];
+    readonly inferFromFieldNames: boolean;
+    readonly onBlock: "redact" | "throw";
+    classify(type: EntityType): Classification;
+    allowlisted(value: string): boolean;
+}
+/** Layers `override` on top of `base`: maps merge, lists concatenate, scalars replace. */
+export declare function mergePolicyConfig(base?: PolicyConfig, override?: PolicyConfig): PolicyConfig;
+export declare function compilePolicy(config?: PolicyConfig): CompiledPolicy;
+/**
+ * Whether a principal holding `grants` may see a value. `*` covers PII only: SENSITIVE always needs an explicit
+ * `SENSITIVE` or entity-type grant, so a broad grant can never silently widen to high-impact data.
+ */
+export declare function isGranted(grants: readonly Grant[] | undefined, type: EntityType, classification: Classification): boolean;
+/**
+ * Display masks. Card numbers show at most the last four digits (PCI DSS 3.4.1 permits up to BIN + last four);
+ * Aadhaar follows UIDAI's masked-Aadhaar format; anything without a well-known mask is fully redacted.
+ */
+export declare function maskValue(type: EntityType, value: string): string;
+export declare function deniedReplacement(mode: DeniedMode, type: EntityType, value: string, token: string): string;

package/dist/policy.js

@@ -0,0 +1,116 @@
+import { BUILT_IN_RECOGNIZERS } from "./detectors/recognizers.js";
+import { compileFieldRules, isClassification } from "./fields.js";
+import { PrivacyError } from "./types.js";
+/**
+ * Default handling per entity type, following NIST SP 800-122's confidentiality-impact guidance, GDPR Art. 9
+ * special categories, and PCI DSS v4.0:
+ *  - direct identifiers and contact data -> PII
+ *  - government IDs, financial accounts, card numbers, health and Art. 9 data -> SENSITIVE
+ *  - card security codes (sensitive authentication data, which PCI DSS 3.3.1 forbids storing) and credentials -> BLOCK
+ * Types not listed (custom ones) default to PII.
+ */
+export const DEFAULT_POLICIES = Object.freeze({
+    EMAIL: "PII", PHONE: "PII", PERSON: "PII", ADDRESS: "PII", LOCATION: "PII", DATE_OF_BIRTH: "PII", IP_ADDRESS: "PII", USERNAME: "PII",
+    CREDIT_CARD: "SENSITIVE", IBAN: "SENSITIVE", BANK_ACCOUNT: "SENSITIVE", US_SSN: "SENSITIVE", IN_AADHAAR: "SENSITIVE", IN_PAN: "SENSITIVE",
+    NATIONAL_ID: "SENSITIVE", PASSPORT: "SENSITIVE", DRIVERS_LICENSE: "SENSITIVE", HEALTH: "SENSITIVE", SPECIAL_CATEGORY: "SENSITIVE",
+    CARD_SECURITY_CODE: "BLOCK", CREDENTIAL: "BLOCK",
+});
+const TYPE_NAME = /^[A-Z][A-Z0-9_]*$/;
+/** Layers `override` on top of `base`: maps merge, lists concatenate, scalars replace. */
+export function mergePolicyConfig(base = {}, override = {}) {
+    return {
+        policies: { ...base.policies, ...override.policies },
+        fields: { ...base.fields, ...override.fields },
+        detectors: [...(base.detectors ?? []), ...(override.detectors ?? [])],
+        disable: [...(base.disable ?? []), ...(override.disable ?? [])],
+        threshold: override.threshold ?? base.threshold,
+        inferFromFieldNames: override.inferFromFieldNames ?? base.inferFromFieldNames,
+        allowlist: [...(base.allowlist ?? []), ...(override.allowlist ?? [])],
+        onBlock: override.onBlock ?? base.onBlock,
+    };
+}
+export function compilePolicy(config = {}) {
+    const threshold = config.threshold ?? 0.5;
+    if (!(threshold >= 0 && threshold <= 1))
+        throw new PrivacyError(`mask: threshold must be within [0, 1] (got ${threshold}).`, "config");
+    const policies = { ...DEFAULT_POLICIES };
+    for (const [type, classification] of Object.entries(config.policies ?? {})) {
+        if (!TYPE_NAME.test(type))
+            throw new PrivacyError(`mask: entity type "${type}" must be UPPER_SNAKE_CASE.`, "config");
+        if (!isClassification(classification))
+            throw new PrivacyError(`mask: "${type}" has an invalid classification ${JSON.stringify(classification)}.`, "config");
+        policies[type] = classification;
+    }
+    const disabled = new Set(config.disable ?? []);
+    const known = new Set(BUILT_IN_RECOGNIZERS.map((r) => r.name));
+    for (const name of disabled)
+        if (!known.has(name))
+            throw new PrivacyError(`mask: no built-in recognizer named "${name}". Known: ${[...known].join(", ")}.`, "config");
+    const exact = new Set();
+    const patterns = [];
+    for (const entry of config.allowlist ?? [])
+        (typeof entry === "string" ? exact.add(entry) : patterns.push(entry));
+    let fieldRules;
+    try {
+        fieldRules = compileFieldRules(config.fields);
+    }
+    catch (error) {
+        throw new PrivacyError(error.message, "config");
+    }
+    return {
+        threshold,
+        recognizers: BUILT_IN_RECOGNIZERS.filter((r) => !disabled.has(r.name)),
+        detectors: config.detectors ?? [],
+        fieldRules,
+        inferFromFieldNames: config.inferFromFieldNames ?? true,
+        onBlock: config.onBlock ?? "redact",
+        classify: (type) => policies[type] ?? "PII",
+        allowlisted: (value) => exact.has(value) || patterns.some((re) => { re.lastIndex = 0; return re.test(value); }),
+    };
+}
+/**
+ * Whether a principal holding `grants` may see a value. `*` covers PII only: SENSITIVE always needs an explicit
+ * `SENSITIVE` or entity-type grant, so a broad grant can never silently widen to high-impact data.
+ */
+export function isGranted(grants, type, classification) {
+    if (!grants?.length || classification === "BLOCK")
+        return false;
+    for (const grant of grants) {
+        if (grant === type || grant === classification)
+            return true;
+        if (grant === "*" && classification === "PII")
+            return true;
+    }
+    return false;
+}
+/**
+ * Display masks. Card numbers show at most the last four digits (PCI DSS 3.4.1 permits up to BIN + last four);
+ * Aadhaar follows UIDAI's masked-Aadhaar format; anything without a well-known mask is fully redacted.
+ */
+export function maskValue(type, value) {
+    const digits = value.replace(/\D/g, "");
+    switch (type) {
+        case "EMAIL": {
+            const at = value.lastIndexOf("@");
+            return at > 0 ? `${value[0]}***@${value.slice(at + 1)}` : "***";
+        }
+        case "PHONE": return digits.length >= 6 ? `***-***-${digits.slice(-4)}` : "***";
+        case "CREDIT_CARD": return `**** **** **** ${digits.slice(-4)}`;
+        case "US_SSN": return `***-**-${digits.slice(-4)}`;
+        case "IN_AADHAAR": return `XXXX XXXX ${digits.slice(-4)}`;
+        case "IBAN": {
+            const compact = value.replace(/\s+/g, "");
+            return `${compact.slice(0, 2)}** **** ${compact.slice(-4)}`;
+        }
+        case "BANK_ACCOUNT": return digits.length >= 4 ? `****${digits.slice(-4)}` : "****";
+        case "PERSON": return value.split(/\s+/).filter(Boolean).map((part) => `${part[0]}.`).join(" ");
+        default: return `[REDACTED:${type}]`;
+    }
+}
+export function deniedReplacement(mode, type, value, token) {
+    if (mode === "token")
+        return `[${token}]`;
+    if (mode === "mask")
+        return maskValue(type, value);
+    return `[REDACTED:${type}]`;
+}