mask-privacy 4.0.0 → 4.2.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).
@@ -184,44 +180,43 @@ declare class MaskSecurityError extends MaskError {
 /**
  * Core cryptography engine for Mask SDK.
  *
- * Provides a CryptoEngine singleton that handles Envelope Encryption,
- * ensuring that plaintext PII is encrypted locally before being
- * transmitted and stored in distributed vaults (Redis/Memcached/DynamoDB).
+ * Supports a JSON-based Keyring for transparent key rotation:
+ *   MASK_KEYRING='{"v1":"oldkey...","v2":"newkey..."}'
+ * The *last* key in the JSON object is the active encryption key.
+ * All keys in the keyring are available for decryption (zero-downtime rotation).
  *
- * Uses AES-256-GCM (authenticated encryption) via native Node.js crypto.
- * Includes a compatibility layer to decrypt legacy Fernet-format tokens.
+ * Legacy single-key mode (MASK_ENCRYPTION_KEY) is fully mapped to key ID "default".
  *
- * Requires MASK_ENCRYPTION_KEY to be set in the environment.
+ * Ciphertext envelope format: aes:v2:{keyId}:{base64(iv+authTag+ciphertext)}
+ *
+ * Uses AES-256-GCM via native Node.js crypto and Argon2id for key derivation.
  */
 declare class CryptoEngine {
     private static _instance;
-    private _aesKey;
+    private _keyring;
+    private _activeKeyId;
     private _indexSecret;
     private constructor();
     /**
      * Return the singleton instance, initialising it if necessary.
-     * This is asynchronous because key providers (KMS, etc.) might be async.
+     * Async because Argon2id key derivation is async.
      */
     static getInstanceAsync(): Promise<CryptoEngine>;
     /** Legacy synchronous accessor — will throw if not already initialised. */
     static getInstance(): CryptoEngine;
-    /** Clear the singleton instance to force re-initialization (useful for key rotation). */
+    /** Clear the singleton (useful for key rotation / tests). */
     static reset(): void;
+    private _deriveAesKey;
     private _init;
     /** Return the secret used for HMAC-based blind indexing. */
     getIndexSecret(): Promise<Buffer>;
+    /** Encrypt plaintext using the active keyring key.
+     *  Envelope format: aes:v2:{keyId}:{base64(iv+authTag+ciphertext)}
+     */
     encrypt(plaintext: string): string;
+    /** Decrypt ciphertext. Supports all historical envelope formats. */
     decrypt(ciphertext: string): string;
-    /** Decrypt an AES-256-GCM token (base64 encoded). */
     private _decryptAesGcm;
-    /**
-     * Attempt to decrypt a legacy Fernet-format token.
-     *
-     * Fernet format: Version (1) || Timestamp (8) || IV (16) || Ciphertext (var) || HMAC (32)
-     * All base64url-encoded.
-     *
-     * We try to use the `fernet` npm package if available, otherwise throw.
-     */
     private _decryptLegacyFernet;
 }
 
@@ -236,13 +231,24 @@ declare class AuditLogger {
     private _strictMode;
     private _bufferFullWarned;
     private _shutdownRegistered;
+    private _signingKey;
+    private _prevSig;
+    private _instanceId;
     private constructor();
     static getInstance(): AuditLogger;
+    private _getOverflowPath;
+    private _writeOverflow;
+    private _consumeOverflow;
     log(action: string, token: string, dataType?: string, agent?: string, tool?: string, extra?: Record<string, any>): void;
     start(): void;
     stop(): Promise<void>;
     private _flush;
-    /** Synchronous flush for use in signal handlers where async is unreliable. */
+    /** Synchronous flush for use in signal handlers where async is unreliable.
+     *
+     * Computes HMAC signatures to maintain chain integrity and writes to the
+     * secure ndjson audit file (MASK_SECURE_AUDIT_LOG_DIR) if configured,
+     * ensuring SOC 2 tamper-evidence guarantees hold through process shutdown.
+     */
     private _flushSync;
 }
 

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).
@@ -184,44 +180,43 @@ declare class MaskSecurityError extends MaskError {
 /**
  * Core cryptography engine for Mask SDK.
  *
- * Provides a CryptoEngine singleton that handles Envelope Encryption,
- * ensuring that plaintext PII is encrypted locally before being
- * transmitted and stored in distributed vaults (Redis/Memcached/DynamoDB).
+ * Supports a JSON-based Keyring for transparent key rotation:
+ *   MASK_KEYRING='{"v1":"oldkey...","v2":"newkey..."}'
+ * The *last* key in the JSON object is the active encryption key.
+ * All keys in the keyring are available for decryption (zero-downtime rotation).
  *
- * Uses AES-256-GCM (authenticated encryption) via native Node.js crypto.
- * Includes a compatibility layer to decrypt legacy Fernet-format tokens.
+ * Legacy single-key mode (MASK_ENCRYPTION_KEY) is fully mapped to key ID "default".
  *
- * Requires MASK_ENCRYPTION_KEY to be set in the environment.
+ * Ciphertext envelope format: aes:v2:{keyId}:{base64(iv+authTag+ciphertext)}
+ *
+ * Uses AES-256-GCM via native Node.js crypto and Argon2id for key derivation.
  */
 declare class CryptoEngine {
     private static _instance;
-    private _aesKey;
+    private _keyring;
+    private _activeKeyId;
     private _indexSecret;
     private constructor();
     /**
      * Return the singleton instance, initialising it if necessary.
-     * This is asynchronous because key providers (KMS, etc.) might be async.
+     * Async because Argon2id key derivation is async.
      */
     static getInstanceAsync(): Promise<CryptoEngine>;
     /** Legacy synchronous accessor — will throw if not already initialised. */
     static getInstance(): CryptoEngine;
-    /** Clear the singleton instance to force re-initialization (useful for key rotation). */
+    /** Clear the singleton (useful for key rotation / tests). */
     static reset(): void;
+    private _deriveAesKey;
     private _init;
     /** Return the secret used for HMAC-based blind indexing. */
     getIndexSecret(): Promise<Buffer>;
+    /** Encrypt plaintext using the active keyring key.
+     *  Envelope format: aes:v2:{keyId}:{base64(iv+authTag+ciphertext)}
+     */
     encrypt(plaintext: string): string;
+    /** Decrypt ciphertext. Supports all historical envelope formats. */
     decrypt(ciphertext: string): string;
-    /** Decrypt an AES-256-GCM token (base64 encoded). */
     private _decryptAesGcm;
-    /**
-     * Attempt to decrypt a legacy Fernet-format token.
-     *
-     * Fernet format: Version (1) || Timestamp (8) || IV (16) || Ciphertext (var) || HMAC (32)
-     * All base64url-encoded.
-     *
-     * We try to use the `fernet` npm package if available, otherwise throw.
-     */
     private _decryptLegacyFernet;
 }
 
@@ -236,13 +231,24 @@ declare class AuditLogger {
     private _strictMode;
     private _bufferFullWarned;
     private _shutdownRegistered;
+    private _signingKey;
+    private _prevSig;
+    private _instanceId;
     private constructor();
     static getInstance(): AuditLogger;
+    private _getOverflowPath;
+    private _writeOverflow;
+    private _consumeOverflow;
     log(action: string, token: string, dataType?: string, agent?: string, tool?: string, extra?: Record<string, any>): void;
     start(): void;
     stop(): Promise<void>;
     private _flush;
-    /** Synchronous flush for use in signal handlers where async is unreliable. */
+    /** Synchronous flush for use in signal handlers where async is unreliable.
+     *
+     * Computes HMAC signatures to maintain chain integrity and writes to the
+     * secure ndjson audit file (MASK_SECURE_AUDIT_LOG_DIR) if configured,
+     * ensuring SOC 2 tamper-evidence guarantees hold through process shutdown.
+     */
     private _flushSync;
 }