mask-privacy 4.0.0 → 4.1.0

package/dist/index.d.mts

@@ -1,11 +1,13 @@
 /** Interface every vault backend must implement. */
 declare abstract class BaseVault {
-    /** Persist a token → plaintext mapping with a TTL. Optionally save a reverse lookup hash. */
-    abstract store(token: string, plaintext: string, ttlSeconds: number, ptHash?: string | null): Promise<void>;
+    /** Persist a token → encrypted plaintext mapping with a TTL and optional compliance metadata. */
+    abstract store(token: string, plaintext: string, ttlSeconds: number, ptHash?: string | null, metadata?: Record<string, string> | null): Promise<void>;
     /** Return the existing unexpired token for a given plaintext hash, or null. */
     abstract getTokenByPlaintextHash(ptHash: string): Promise<string | null>;
     /** Return the plaintext for token, or null if missing/expired. */
     abstract retrieve(token: string): Promise<string | null>;
+    /** Return the plaintext hash stored for this token (used for collision detection), or null. */
+    abstract getPtHashForToken(token: string): Promise<string | null>;
     /** Delete a token and its reverse mapping. */
     abstract delete(token: string): Promise<void>;
 }
@@ -15,6 +17,7 @@ type EncodeOptions = {
     searchBuckets?: ('year' | 'month' | 'day' | 'numeric')[];
     searchBucketSize?: number;
     entityType?: string;
+    metadata?: Record<string, string> | null;
 };
 /**
  * Tokenise rawText, encrypt it, store in vault, return the FPE token.
@@ -41,18 +44,11 @@ declare const adetokenizeText: typeof detokenizeText;
 declare function looksLikeToken(value: string | any): boolean;
 
 /**
- * Format-Preserving Encryption (FPE) token generation.
- *
- * Generates structurally valid, **deterministic** tokens that preserve the
- * format of the original data type so downstream tools, schemas, and
- * validators continue to work without modification.
+ * Deterministic Pseudonymization (DP) token generation using NIST SP 800-38G FF1.
  */
-/** Clear the cached master key. Useful in tests. */
 declare function resetMasterKey(): void;
-/**
- * Return a **deterministic**, format-preserving token for rawText using its entityType.
- */
-declare function generateFPEToken(rawText: string, entityType?: string): Promise<string>;
+declare function generateDPToken(rawText: string, entityType?: string): Promise<string>;
+declare const generateFPEToken: typeof generateDPToken;
 
 /**
  * Span Resolution Engine — Sweep-Line Overlap Resolver (TypeScript).
@@ -236,6 +232,8 @@ declare class AuditLogger {
     private _strictMode;
     private _bufferFullWarned;
     private _shutdownRegistered;
+    private _signingKey;
+    private _prevSig;
     private constructor();
     static getInstance(): AuditLogger;
     log(action: string, token: string, dataType?: string, agent?: string, tool?: string, extra?: Record<string, any>): void;

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 /** Interface every vault backend must implement. */
 declare abstract class BaseVault {
-    /** Persist a token → plaintext mapping with a TTL. Optionally save a reverse lookup hash. */
-    abstract store(token: string, plaintext: string, ttlSeconds: number, ptHash?: string | null): Promise<void>;
+    /** Persist a token → encrypted plaintext mapping with a TTL and optional compliance metadata. */
+    abstract store(token: string, plaintext: string, ttlSeconds: number, ptHash?: string | null, metadata?: Record<string, string> | null): Promise<void>;
     /** Return the existing unexpired token for a given plaintext hash, or null. */
     abstract getTokenByPlaintextHash(ptHash: string): Promise<string | null>;
     /** Return the plaintext for token, or null if missing/expired. */
     abstract retrieve(token: string): Promise<string | null>;
+    /** Return the plaintext hash stored for this token (used for collision detection), or null. */
+    abstract getPtHashForToken(token: string): Promise<string | null>;
     /** Delete a token and its reverse mapping. */
     abstract delete(token: string): Promise<void>;
 }
@@ -15,6 +17,7 @@ type EncodeOptions = {
     searchBuckets?: ('year' | 'month' | 'day' | 'numeric')[];
     searchBucketSize?: number;
     entityType?: string;
+    metadata?: Record<string, string> | null;
 };
 /**
  * Tokenise rawText, encrypt it, store in vault, return the FPE token.
@@ -41,18 +44,11 @@ declare const adetokenizeText: typeof detokenizeText;
 declare function looksLikeToken(value: string | any): boolean;
 
 /**
- * Format-Preserving Encryption (FPE) token generation.
- *
- * Generates structurally valid, **deterministic** tokens that preserve the
- * format of the original data type so downstream tools, schemas, and
- * validators continue to work without modification.
+ * Deterministic Pseudonymization (DP) token generation using NIST SP 800-38G FF1.
  */
-/** Clear the cached master key. Useful in tests. */
 declare function resetMasterKey(): void;
-/**
- * Return a **deterministic**, format-preserving token for rawText using its entityType.
- */
-declare function generateFPEToken(rawText: string, entityType?: string): Promise<string>;
+declare function generateDPToken(rawText: string, entityType?: string): Promise<string>;
+declare const generateFPEToken: typeof generateDPToken;
 
 /**
  * Span Resolution Engine — Sweep-Line Overlap Resolver (TypeScript).
@@ -236,6 +232,8 @@ declare class AuditLogger {
     private _strictMode;
     private _bufferFullWarned;
     private _shutdownRegistered;
+    private _signingKey;
+    private _prevSig;
     private constructor();
     static getInstance(): AuditLogger;
     log(action: string, token: string, dataType?: string, agent?: string, tool?: string, extra?: Record<string, any>): void;