mask-privacy 3.2.0 → 3.4.0

package/README.md

@@ -127,27 +127,18 @@ Performance-sensitive deployments utilize the built-in `LocalTransformersScanner
 ### 7. Sub-string Detokenization
 Mask includes the ability to detokenize PII embedded within larger text blocks (like email bodies or chat messages). `detokenizeText()` uses high-performance regex to find and restore all tokens within a paragraph before they hit your tools.
 
-## Multilingual PII Detection (Waterfall Pipeline)
+## Multilingual PII Detection (2-Tier Waterfall)
 
-Mask is built for the global enterprise. The TypeScript SDK implements a **3-Tier Waterfall Detection** strategy for high-precision PII detection in **English and Spanish** using local ONNX models.
-
-### Supported Language Matrix
-
-Mask provides first-class support for the following languages:
-
-| Language | Code | Tier 0 (DLP) | Tier 2 (NLP Engine) |
-| :--- | :--- | :--- | :--- |
-| **English** | `en` | ✅ Full | DistilBERT (Simple) |
-| **Spanish** | `es` | ✅ Full | BERT Multilingual |
+Mask is built for the global enterprise. The TypeScript SDK implements a **2-Tier Model-Augmented Waterfall** strategy for high-precision PII detection in **English and Spanish**.
 
 ### How the Waterfall Works: The Excising Mechanism
 
-To maintain high performance, the TypeScript SDK does not simply run three separate scans. It uses a **Sequential Mutation** strategy:
+To maintain high performance, the TypeScript SDK does not simply run multiple separate scans. It uses a **Sequential Mutation** strategy:
 
-1.  **Tier 0 & 1 (The Scouts):** The SDK first runs the high-speed DLP and Regex engines synchronously in the main thread.
-2.  **Immediate Tokenization:** Any PII found by these tiers is **immediately replaced** by a token in the string buffer.
-3.  **Tier 2 (The Heavy Infantry):** The expensive NLP engine (Transformers.js) only scans the *remaining* text. Because the PII has already been "excised" (cut out and replaced with tokens), the NLP engine doesn't waste compute on data already identified.
-4.  **Bypass Logic:** All tiers are "token-aware." If a scan encounter a string that is already a Mask token, it skips it entirely, preventing redundant processing or "double-tokenization."
+1.  **Tier 0: Deterministic (The Registry):** The SDK first runs the high-speed DLP and Registry engines. These use regex + checksums (Luhn, Mod-97, Mod-11) + Proximity Keywords to identify structured PII (Bank Accounts, SSNs, DNI, NUSS, etc.) with 100% precision.
+2.  **Immediate Tokenization:** Any PII found by Tier 0 is **immediately replaced** by a token in the string buffer.
+3.  **Tier 1: Probabilistic (Neural NER):** The expensive NLP engine (Transformers.js) only scans the *remaining* text for unstructured entities: **PERSON**, **LOCATION**, and **ORGANIZATION**. Because Tier 0 PII has already been "excised", the NLP engine doesn't waste compute on data already identified, and entity collisions are avoided.
+4.  **Bypass Logic:** All tiers are "token-aware." If a scan encounters a string that is already a Mask token, it skips it entirely.
 
 ---
 

package/dist/index.d.mts

@@ -96,8 +96,9 @@ declare class BaseScanner {
     protected _tier0CollectSpans(text: string, confidenceThreshold: number): Promise<Span[]>;
     /** Backward-compat wrapper — collects spans then single-pass encodes. */
     protected _tier0Dlp(text: string, encodeFn: (val: string, options?: any) => Promise<string>, confidenceThreshold: number): Promise<[string, any[]]>;
+    /** Tier 1 — Deterministic detection (Legacy: Redirected to DLP) */
     protected _tier1CollectSpans(text: string, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<Span[]>;
-    /** Backward-compat wrapper. */
+    /** Backward-compat wrapper. Redirected to DLP. */
     protected _tier1Regex(text: string, encodeFn: (val: string, options?: any) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
     protected _tier2Nlp(text: string, encodeFn: (val: string, options?: any) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
     protected _resolveBoost(context?: string | null): Set<string>;
@@ -480,7 +481,7 @@ declare class DLPConfidenceScorer {
  * Provides format-preserving encryption, local/distributed vaulting,
  * and framework-agnostic tool interception hooks.
  */
-declare const VERSION = "2.0.0";
+declare const VERSION = "3.4.0";
 
 /**
  * Detect PII entities in text and return a list of objects with metadata.

package/dist/index.d.ts

@@ -96,8 +96,9 @@ declare class BaseScanner {
     protected _tier0CollectSpans(text: string, confidenceThreshold: number): Promise<Span[]>;
     /** Backward-compat wrapper — collects spans then single-pass encodes. */
     protected _tier0Dlp(text: string, encodeFn: (val: string, options?: any) => Promise<string>, confidenceThreshold: number): Promise<[string, any[]]>;
+    /** Tier 1 — Deterministic detection (Legacy: Redirected to DLP) */
     protected _tier1CollectSpans(text: string, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<Span[]>;
-    /** Backward-compat wrapper. */
+    /** Backward-compat wrapper. Redirected to DLP. */
     protected _tier1Regex(text: string, encodeFn: (val: string, options?: any) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
     protected _tier2Nlp(text: string, encodeFn: (val: string, options?: any) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
     protected _resolveBoost(context?: string | null): Set<string>;
@@ -480,7 +481,7 @@ declare class DLPConfidenceScorer {
  * Provides format-preserving encryption, local/distributed vaulting,
  * and framework-agnostic tool interception hooks.
  */
-declare const VERSION = "2.0.0";
+declare const VERSION = "3.4.0";
 
 /**
  * Detect PII entities in text and return a list of objects with metadata.

package/dist/index.js

@@ -43580,7 +43580,7 @@ var init_registry = __esm({
       [
         "CREDIT_CARD_NUMBER",
         "\\b(?:4\\d{3}|5[1-5]\\d{2}|3[47]\\d{2}|6(?:011|5\\d{2}))[- ]?\\d{4}[- ]?\\d{4}[- ]?\\d{4}\\b",
-        ["card", "credit", "visa", "mastercard", "amex", "payment"],
+        ["card", "credit", "visa", "mastercard", "amex", "payment", "tarjeta", "credito", "debito", "pago"],
         0.97,
         "FINANCIAL" /* FINANCIAL */,
         "luhn"
@@ -43588,7 +43588,7 @@ var init_registry = __esm({
       [
         "INTL_BANK_IBAN",
         "\\b[A-Z]{2}\\d{2}[A-Z0-9]{4}\\d{7}[A-Z0-9]{0,16}\\b",
-        ["iban", "swift", "sepa", "wire", "bank transfer"],
+        ["iban", "swift", "sepa", "wire", "bank transfer", "cuenta", "banco", "transferencia"],
         0.96,
         "FINANCIAL" /* FINANCIAL */,
         "iban"
@@ -43625,6 +43625,16 @@ var init_registry = __esm({
         "FINANCIAL" /* FINANCIAL */,
         "luhn_soft"
       ],
+      [
+        "ES_CCC",
+        "\\b\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{2}[-\\s]?\\d{10}\\b",
+        ["cuenta", "ccc", "banco", "sucursal", "entidad", "codigo cuenta cliente"],
+        0.9,
+        "FINANCIAL" /* FINANCIAL */,
+        "es_ccc",
+        true,
+        ["*", "es"]
+      ],
       [
         "SWIFT_BIC",
         "\\b[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?\\b",
@@ -43637,15 +43647,15 @@ var init_registry = __esm({
       [
         "EMAIL_ADDR",
         "\\b[A-Za-z0-9._%+\\-]+@[A-Za-z0-9.\\-]+\\.[A-Za-z]{2,}\\b",
-        ["email", "mail", "contact", "address"],
+        ["email", "mail", "contact", "address", "correo", "electronico"],
         0.99,
         "CONTACT" /* CONTACT */,
         null
       ],
       [
         "PHONE_NUM",
-        /(?<!\d)(?:\+?[1-9]\d{0,3}[-.\s]?)?\(?\d{1,4}\)?[-.\s]?\d{1,4}[-.\s]?\d{1,4}[-.\s]?\d{1,9}(?!\d)/,
-        ["phone", "call", "mobile", "tel", "whatsapp", "number"],
+        /(?<!\d)(?:\+?[1-9]\d{0,3}[-.\s]?)?\(?\d{1,4}\)?[-.\s]?\d{1,4}[-.\s]?\d{1,4}[-.\s]?\d{1,4}[-.\s]?\d{1,9}(?!\d)/,
+        ["phone", "call", "mobile", "tel", "whatsapp", "number", "tel\xE9fono", "telefono", "movil", "celular", "llamada"],
         0.8,
         "CONTACT" /* CONTACT */,
         null
@@ -43685,8 +43695,8 @@ var init_registry = __esm({
       // ── PERSONAL ───────────────────────────────────────────────────────
       [
         "BIRTH_DATE",
-        "\\b(?:0[1-9]|1[0-2])[/-](?:0[1-9]|[12]\\d|3[01])[/-](?:19|20)\\d{2}\\b",
-        ["birth", "dob", "born", "birthday", "date of birth"],
+        "\\b(?:(?:0[1-9]|1[0-2])[/-](?:0[1-9]|[12]\\d|3[01])[/-](?:19|20)\\d{2}|(?:19|20)\\d{2}[/-](?:0[1-9]|1[0-2])[/-](?:0[1-9]|[12]\\d|3[01]))\\b",
+        ["birth", "dob", "born", "birthday", "date of birth", "nacimiento", "fecha", "cumplea\xF1os"],
         0.88,
         "PERSONAL" /* PERSONAL */,
         null
@@ -43793,6 +43803,16 @@ var init_registry = __esm({
         true,
         ["*", "es"]
       ],
+      [
+        "ES_NUSS",
+        "\\b\\d{2}[-\\s]?\\d{8}[-\\s]?\\d{2}\\b",
+        ["seguridad social", "nuss", "naf", "afiliacion"],
+        0.9,
+        "IDENTITY_INTL" /* IDENTITY_INTL */,
+        "es_nuss",
+        true,
+        ["*", "es"]
+      ],
       // ── CORPORATE ──────────────────────────────────────────────────────
       [
         "CORP_EMPLOYEE_ID",
@@ -44023,6 +44043,38 @@ function checkEsId(raw) {
   const validLetters = "TRWAGMYFPDXBNJZSQVHLCKE";
   return cleaned[8] === validLetters[num % 23];
 }
+function checkEsNuss(raw) {
+  const digits = raw.replace(/\D/g, "");
+  if (digits.length !== 12) return false;
+  const a6 = parseInt(digits.slice(0, 2), 10);
+  const b6 = parseInt(digits.slice(2, 10), 10);
+  const c6 = parseInt(digits.slice(10), 10);
+  let check;
+  if (b6 < 1e7) {
+    check = (a6 * 1e7 + b6) % 97;
+  } else {
+    check = Number(BigInt(digits.slice(0, 10)) % 97n);
+  }
+  return check === c6;
+}
+function checkEsCcc(raw) {
+  const digits = raw.replace(/\D/g, "");
+  if (digits.length !== 20) return false;
+  const weights = [1, 2, 4, 8, 5, 10, 9, 7, 3, 6];
+  const calcDigit = (block) => {
+    let s6 = 0;
+    for (let i6 = 0; i6 < block.length; i6++) {
+      s6 += parseInt(block[i6], 10) * weights[i6];
+    }
+    let rem = 11 - s6 % 11;
+    if (rem === 10) return 1;
+    if (rem === 11) return 0;
+    return rem;
+  };
+  const d1 = calcDigit("00" + digits.slice(0, 8));
+  const d22 = calcDigit(digits.slice(10));
+  return parseInt(digits[8], 10) === d1 && parseInt(digits[9], 10) === d22;
+}
 var IBAN_COUNTRY_LENGTHS, VIN_TRANSLITERATION, VIN_WEIGHTS, UK_NINO_REGEX, VALIDATOR_DISPATCH; exports.DLPValidationEngine = void 0;
 var init_handlers = __esm({
   "src/core/dlp/handlers.ts"() {
@@ -44129,6 +44181,7 @@ var init_handlers = __esm({
     UK_NINO_REGEX = /^(?!BG|GB|NK|KN|TN|NT|ZZ)[A-CEGHJ-PR-TW-Z]{2}[0-9]{6}[A-D]$/;
     VALIDATOR_DISPATCH = {
       luhn: checkLuhn,
+      luhn_soft: checkLuhn,
       ssn_area: checkSsnArea,
       iban: checkIbanStructure,
       aba_check: checkAbaRouting,
@@ -44137,7 +44190,9 @@ var init_handlers = __esm({
       ipv4: checkIpv4Octets,
       ca_sin: checkCaSin,
       uk_nino: checkUkNino,
-      es_id: checkEsId
+      es_id: checkEsId,
+      es_nuss: checkEsNuss,
+      es_ccc: checkEsCcc
     };
     exports.DLPValidationEngine = class {
       /**
@@ -58926,6 +58981,7 @@ var init_transformers_scanner = __esm({
             const end = r6.end;
             const val = text.slice(start, end);
             const entityType = this._mapEntityType(r6.entity);
+            if (!this._supportedEntities.includes(entityType)) continue;
             let confidence = r6.score || 0.7;
             if (aggressive || boostEntities.has(entityType.toLowerCase().replace(/_/g, " "))) {
               confidence = Math.min(1, confidence + 0.2);
@@ -59028,7 +59084,7 @@ function getScanner() {
   }
   return scannerInstance;
 }
-var _dlpLanguageResolver, _dlpPatternRegistry, _dlpValidationEngine, _dlpConfidenceScorer, REGEX_PATTERNS, CONTEXT_KEYWORDS; exports.BaseScanner = void 0; exports.PresidioScanner = void 0; var scannerInstance;
+var _dlpLanguageResolver, _dlpPatternRegistry, _dlpValidationEngine, _dlpConfidenceScorer; exports.BaseScanner = void 0; exports.PresidioScanner = void 0; var scannerInstance;
 var init_scanner = __esm({
   "src/core/scanner.ts"() {
     init_config();
@@ -59043,39 +59099,12 @@ var init_scanner = __esm({
     _dlpPatternRegistry = new exports.DLPPatternRegistry();
     _dlpValidationEngine = new exports.DLPValidationEngine();
     _dlpConfidenceScorer = new exports.DLPConfidenceScorer();
-    REGEX_PATTERNS = {
-      "EMAIL_ADDRESS": /[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+/g,
-      "PHONE_NUMBER": /(?<!\d)(?:\+?1?[\s\-.]?\(?\d{3}\)?[\s\-.]?\d{3}[\s\-.]?\d{4}|\d{3}[\s\-.]?\d{4})(?!\d)/g,
-      "PHONE_NUMBER_INTL": /(?<!\d)\+(?:[1-9]\d{0,3})[-.\s]?\(?\d{1,5}\)?(?:[-.\s]?\d{2,4}){2,4}(?!\d)/g,
-      "US_SSN": /(?<!\d)\d{3}-\d{2}-\d{4}(?!\d)/g,
-      "CREDIT_CARD": /(?<!\d)(?:\d{4}[ \-]?){3}\d{4}(?!\d)/g,
-      "US_ROUTING_NUMBER": /(?<!\d)\d{9}(?!\d)/g,
-      "US_PASSPORT": /\b[A-Z]\d{8}\b/g,
-      "DATE_OF_BIRTH": /\b(?:0[1-9]|1[0-2])\/(?:0[1-9]|[12]\d|3[01])\/(?:19|20)\d{2}\b|\b(?:19|20)\d{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])\b/g
-    };
-    CONTEXT_KEYWORDS = /* @__PURE__ */ new Set([
-      "account number",
-      "ssn",
-      "phone",
-      "credit card",
-      "iban",
-      "bank",
-      "email",
-      "pii",
-      "personal info"
-    ]);
-    exports.BaseScanner = class _BaseScanner {
+    exports.BaseScanner = class {
       constructor() {
         this._supportedEntities = [
-          "EMAIL_ADDRESS",
-          "PHONE_NUMBER",
-          "US_SSN",
-          "CREDIT_CARD",
-          "US_BANK_NUMBER",
-          "CRYPTO",
-          "IBAN_CODE",
-          "IP_ADDRESS",
-          "PERSON"
+          "PERSON",
+          "LOCATION",
+          "ORGANIZATION"
         ];
       }
       setSupportedEntities(entities) {
@@ -59219,47 +59248,13 @@ var init_scanner = __esm({
         }));
         return [reconstruct(text, resolved), entities];
       }
+      /** Tier 1 — Deterministic detection (Legacy: Redirected to DLP) */
       async _tier1CollectSpans(text, boostEntities, aggressive, confidenceThreshold) {
-        const spans = [];
-        for (const [entityType, pattern] of Object.entries(REGEX_PATTERNS)) {
-          const re = new RegExp(pattern.source, pattern.flags);
-          let match;
-          while ((match = re.exec(text)) !== null) {
-            const val = match[0];
-            if (looksLikeToken(val)) continue;
-            let confidence = aggressive || boostEntities.has(entityType.toLowerCase().replace(/_/g, " ")) ? 1 : 0.95;
-            if (entityType === "CREDIT_CARD" && _BaseScanner._luhnChecksum(val)) confidence = Math.max(confidence, 0.99);
-            if (entityType === "US_ROUTING_NUMBER" && !_BaseScanner._abaChecksum(val)) continue;
-            if (confidence >= confidenceThreshold) {
-              spans.push({
-                start: match.index,
-                end: match.index + val.length,
-                entityType,
-                originalValue: val,
-                confidence,
-                method: "regex"
-              });
-            }
-          }
-        }
-        return spans;
+        return this._tier0CollectSpans(text, confidenceThreshold);
       }
-      /** Backward-compat wrapper. */
+      /** Backward-compat wrapper. Redirected to DLP. */
       async _tier1Regex(text, encodeFn, boostEntities, aggressive, confidenceThreshold) {
-        const spans = await this._tier1CollectSpans(text, boostEntities, aggressive, confidenceThreshold);
-        const resolved = resolveOverlaps(spans);
-        const entities = [];
-        await Promise.all(resolved.map(async (span) => {
-          span.maskedValue = await encodeFn(span.originalValue, { entityType: span.entityType });
-          entities.push({
-            type: span.entityType,
-            value: span.originalValue,
-            method: span.method,
-            confidence: span.confidence,
-            masked_value: span.maskedValue
-          });
-        }));
-        return [reconstruct(text, resolved), entities];
+        return this._tier0Dlp(text, encodeFn, confidenceThreshold);
       }
       async _tier2Nlp(text, encodeFn, boostEntities, aggressive, confidenceThreshold) {
         return [text, []];
@@ -59268,24 +59263,26 @@ var init_scanner = __esm({
         if (!context) return /* @__PURE__ */ new Set();
         const lowered = context.toLowerCase();
         const boosted = /* @__PURE__ */ new Set();
-        for (const kw of CONTEXT_KEYWORDS) {
-          if (lowered.includes(kw)) boosted.add(kw);
+        for (const [, desc] of _dlpPatternRegistry.iterDescriptors()) {
+          for (const term of desc.proximityTerms) {
+            if (lowered.includes(term)) {
+              boosted.add(desc.category.toLowerCase());
+              break;
+            }
+          }
         }
         return boosted;
       }
       async scanAndTokenize(text, options = {}) {
         if (!text || typeof text !== "string") return text;
-        const pipeline = options.pipeline || ["dlp", "regex", "checksum", "nlp"];
+        const pipeline = options.pipeline || ["dlp", "nlp"];
         const _encode = options.encodeFn || encode;
         const confidenceThreshold = options.confidenceThreshold ?? 0.7;
         const boost = this._resolveBoost(options.context);
         const allSpans = [];
-        if (pipeline.includes("dlp")) {
+        if (pipeline.includes("dlp") || pipeline.includes("regex") || pipeline.includes("checksum")) {
           allSpans.push(...await this._tier0CollectSpans(text, confidenceThreshold));
         }
-        if (pipeline.includes("regex") || pipeline.includes("checksum")) {
-          allSpans.push(...await this._tier1CollectSpans(text, boost, !!options.aggressive, confidenceThreshold));
-        }
         const resolved = resolveOverlaps(allSpans);
         await Promise.all(resolved.map(async (span) => {
           span.maskedValue = await _encode(span.originalValue, { entityType: span.entityType });
@@ -59298,18 +59295,15 @@ var init_scanner = __esm({
       }
       async scanAndReturnEntities(text, options = {}) {
         if (!text || typeof text !== "string") return [];
-        const pipeline = options.pipeline || ["dlp", "regex", "checksum", "nlp"];
+        const pipeline = options.pipeline || ["dlp", "nlp"];
         const _encode = options.encodeFn || encode;
         const confidenceThreshold = options.confidenceThreshold ?? 0.7;
         const boost = this._resolveBoost(options.context);
         const allEntities = [];
         const allSpans = [];
-        if (pipeline.includes("dlp")) {
+        if (pipeline.includes("dlp") || pipeline.includes("regex") || pipeline.includes("checksum")) {
           allSpans.push(...await this._tier0CollectSpans(text, confidenceThreshold));
         }
-        if (pipeline.includes("regex") || pipeline.includes("checksum")) {
-          allSpans.push(...await this._tier1CollectSpans(text, boost, !!options.aggressive, confidenceThreshold));
-        }
         const resolved = resolveOverlaps(allSpans);
         await Promise.all(resolved.map(async (span) => {
           span.maskedValue = await _encode(span.originalValue, { entityType: span.entityType });
@@ -59625,7 +59619,7 @@ init_handlers();
 init_scorer();
 
 // src/index.ts
-var VERSION = "2.0.0";
+var VERSION = "3.4.0";
 async function detectEntitiesWithConfidence(text, options = {}) {
   const scanner = getScanner();
   return await scanner.scanAndReturnEntities(text, options);