mask-privacy 3.0.0 → 3.1.0

package/dist/index.d.mts

@@ -14,6 +14,7 @@ type EncodeOptions = {
     ttl?: number;
     searchBuckets?: ('year' | 'month' | 'day' | 'numeric')[];
     searchBucketSize?: number;
+    entityType?: string;
 };
 /**
  * Tokenise rawText, encrypt it, store in vault, return the FPE token.
@@ -49,9 +50,40 @@ declare function looksLikeToken(value: string | any): boolean;
 /** Clear the cached master key. Useful in tests. */
 declare function resetMasterKey(): void;
 /**
- * Return a **deterministic**, format-preserving token for rawText.
+ * Return a **deterministic**, format-preserving token for rawText using its entityType.
+ */
+declare function generateFPEToken(rawText: string, entityType?: string): Promise<string>;
+
+/**
+ * Span Resolution Engine — Sweep-Line Overlap Resolver (TypeScript).
+ *
+ * All detection tiers now return Span objects instead of mutating the text.
+ * resolveOverlaps() chooses the winning span in every conflicting region,
+ * and reconstruct() rebuilds the string exactly once.
+ */
+interface Span {
+    start: number;
+    end: number;
+    entityType: string;
+    originalValue: string;
+    confidence: number;
+    method: string;
+    language?: string;
+    maskedValue?: string;
+}
+
+/**
+ * Entity Detection Scanner — Tiered Waterfall Pipeline.
+ *
+ * Scans unstructured text to identify PII (Emails, Phones, SSNs, Credit Cards,
+ * Names) and replaces them in-place with Format-Preserving Encryption (FPE)
+ * tokens.
+ *
+ * Detection Architecture (Waterfall):
+ *   Tier 0 — DLP Heuristic: Multilingual, 50+ types, checksum validators
+ *   Tier 1 — Deterministic: Regex + Checksum  (fast, provable, auditable)
+ *   Tier 2 — Probabilistic: Local NLP via Transformers (catches names/orgs)
  */
-declare function generateFPEToken(rawText: string): Promise<string>;
 
 declare class BaseScanner {
     protected _supportedEntities: string[];
@@ -61,19 +93,23 @@ declare class BaseScanner {
     protected static _luhnChecksum(ccNumber: string): boolean;
     /** Validate a US ABA routing number using the checksum algorithm. */
     protected static _abaChecksum(routingNumber: string): boolean;
-    protected _tier0Dlp(text: string, encodeFn: (val: string) => Promise<string>, confidenceThreshold: number): Promise<[string, any[]]>;
-    protected _tier1Regex(text: string, encodeFn: (val: string) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
-    protected _tier2Nlp(text: string, encodeFn: (val: string) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
+    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[]]>;
+    protected _tier1CollectSpans(text: string, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<Span[]>;
+    /** Backward-compat wrapper. */
+    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>;
     scanAndTokenize(text: string, options?: {
-        encodeFn?: (val: string) => Promise<string>;
+        encodeFn?: (val: string, options?: any) => Promise<string>;
         pipeline?: string[];
         confidenceThreshold?: number;
         context?: string | null;
         aggressive?: boolean;
     }): Promise<string>;
     scanAndReturnEntities(text: string, options?: {
-        encodeFn?: (val: string) => Promise<string>;
+        encodeFn?: (val: string, options?: any) => Promise<string>;
         pipeline?: string[];
         confidenceThreshold?: number;
         context?: string | null;
@@ -107,7 +143,7 @@ declare class LocalTransformersScanner extends BaseScanner {
      * Map Transformer entity types to Mask internal entity types.
      */
     private _mapEntityType;
-    protected _tier2Nlp(text: string, encodeFn: (val: string) => 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[]]>;
     /**
      * Merges sub-tokens and entities of the same type while precisely tracking
      * offsets in the original text.
@@ -338,27 +374,28 @@ interface PatternDescriptor {
     baseRisk: number;
     category: SensitiveCategory;
     validatorTag: string | null;
+    isHighEntropy: boolean;
+    supportedLocales: string[];
 }
 /**
  * Immutable catalogue of sensitive-data regex signatures.
- *
- * @example
- * ```ts
- * const reg = new DLPPatternRegistry(); // load everything
- * const reg = new DLPPatternRegistry(new Set([SensitiveCategory.FINANCIAL]));
- * ```
  */
 declare class DLPPatternRegistry {
     private readonly catalogue;
+    private readonly localeCategoryRegexMap;
     constructor(loadGroups?: ReadonlySet<SensitiveCategory>);
     get typeNames(): string[];
     /** Yield [typeName, descriptor] pairs. */
     iterDescriptors(): IterableIterator<[string, PatternDescriptor]>;
     descriptorFor(typeName: string): PatternDescriptor | undefined;
-    /** Return locale-tuned name regexes, falling back to English. */
     namePatternsFor(lang: LanguageTag | string): RegExp[];
-    /** Return locale-tuned address regexes, falling back to English. */
     addressPatternsFor(lang: LanguageTag | string): RegExp[];
+    getCategoryRegexesMap(locale?: string): Map<string, {
+        re: RegExp;
+        typeOrder: string[];
+    }>;
+    getCategoryTypeMap(categoryName: string, locale?: string): string[];
+    private compileForLocale;
     private buildCatalogue;
 }
 

package/dist/index.d.ts

@@ -14,6 +14,7 @@ type EncodeOptions = {
     ttl?: number;
     searchBuckets?: ('year' | 'month' | 'day' | 'numeric')[];
     searchBucketSize?: number;
+    entityType?: string;
 };
 /**
  * Tokenise rawText, encrypt it, store in vault, return the FPE token.
@@ -49,9 +50,40 @@ declare function looksLikeToken(value: string | any): boolean;
 /** Clear the cached master key. Useful in tests. */
 declare function resetMasterKey(): void;
 /**
- * Return a **deterministic**, format-preserving token for rawText.
+ * Return a **deterministic**, format-preserving token for rawText using its entityType.
+ */
+declare function generateFPEToken(rawText: string, entityType?: string): Promise<string>;
+
+/**
+ * Span Resolution Engine — Sweep-Line Overlap Resolver (TypeScript).
+ *
+ * All detection tiers now return Span objects instead of mutating the text.
+ * resolveOverlaps() chooses the winning span in every conflicting region,
+ * and reconstruct() rebuilds the string exactly once.
+ */
+interface Span {
+    start: number;
+    end: number;
+    entityType: string;
+    originalValue: string;
+    confidence: number;
+    method: string;
+    language?: string;
+    maskedValue?: string;
+}
+
+/**
+ * Entity Detection Scanner — Tiered Waterfall Pipeline.
+ *
+ * Scans unstructured text to identify PII (Emails, Phones, SSNs, Credit Cards,
+ * Names) and replaces them in-place with Format-Preserving Encryption (FPE)
+ * tokens.
+ *
+ * Detection Architecture (Waterfall):
+ *   Tier 0 — DLP Heuristic: Multilingual, 50+ types, checksum validators
+ *   Tier 1 — Deterministic: Regex + Checksum  (fast, provable, auditable)
+ *   Tier 2 — Probabilistic: Local NLP via Transformers (catches names/orgs)
  */
-declare function generateFPEToken(rawText: string): Promise<string>;
 
 declare class BaseScanner {
     protected _supportedEntities: string[];
@@ -61,19 +93,23 @@ declare class BaseScanner {
     protected static _luhnChecksum(ccNumber: string): boolean;
     /** Validate a US ABA routing number using the checksum algorithm. */
     protected static _abaChecksum(routingNumber: string): boolean;
-    protected _tier0Dlp(text: string, encodeFn: (val: string) => Promise<string>, confidenceThreshold: number): Promise<[string, any[]]>;
-    protected _tier1Regex(text: string, encodeFn: (val: string) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
-    protected _tier2Nlp(text: string, encodeFn: (val: string) => Promise<string>, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<[string, any[]]>;
+    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[]]>;
+    protected _tier1CollectSpans(text: string, boostEntities: Set<string>, aggressive: boolean, confidenceThreshold: number): Promise<Span[]>;
+    /** Backward-compat wrapper. */
+    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>;
     scanAndTokenize(text: string, options?: {
-        encodeFn?: (val: string) => Promise<string>;
+        encodeFn?: (val: string, options?: any) => Promise<string>;
         pipeline?: string[];
         confidenceThreshold?: number;
         context?: string | null;
         aggressive?: boolean;
     }): Promise<string>;
     scanAndReturnEntities(text: string, options?: {
-        encodeFn?: (val: string) => Promise<string>;
+        encodeFn?: (val: string, options?: any) => Promise<string>;
         pipeline?: string[];
         confidenceThreshold?: number;
         context?: string | null;
@@ -107,7 +143,7 @@ declare class LocalTransformersScanner extends BaseScanner {
      * Map Transformer entity types to Mask internal entity types.
      */
     private _mapEntityType;
-    protected _tier2Nlp(text: string, encodeFn: (val: string) => 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[]]>;
     /**
      * Merges sub-tokens and entities of the same type while precisely tracking
      * offsets in the original text.
@@ -338,27 +374,28 @@ interface PatternDescriptor {
     baseRisk: number;
     category: SensitiveCategory;
     validatorTag: string | null;
+    isHighEntropy: boolean;
+    supportedLocales: string[];
 }
 /**
  * Immutable catalogue of sensitive-data regex signatures.
- *
- * @example
- * ```ts
- * const reg = new DLPPatternRegistry(); // load everything
- * const reg = new DLPPatternRegistry(new Set([SensitiveCategory.FINANCIAL]));
- * ```
  */
 declare class DLPPatternRegistry {
     private readonly catalogue;
+    private readonly localeCategoryRegexMap;
     constructor(loadGroups?: ReadonlySet<SensitiveCategory>);
     get typeNames(): string[];
     /** Yield [typeName, descriptor] pairs. */
     iterDescriptors(): IterableIterator<[string, PatternDescriptor]>;
     descriptorFor(typeName: string): PatternDescriptor | undefined;
-    /** Return locale-tuned name regexes, falling back to English. */
     namePatternsFor(lang: LanguageTag | string): RegExp[];
-    /** Return locale-tuned address regexes, falling back to English. */
     addressPatternsFor(lang: LanguageTag | string): RegExp[];
+    getCategoryRegexesMap(locale?: string): Map<string, {
+        re: RegExp;
+        typeOrder: string[];
+    }>;
+    getCategoryTypeMap(categoryName: string, locale?: string): string[];
+    private compileForLocale;
     private buildCatalogue;
 }