mask-privacy 4.1.0 → 4.2.0

package/dist/index.d.mts

@@ -180,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;
 }
 
@@ -234,13 +233,22 @@ declare class AuditLogger {
     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

@@ -180,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;
 }
 
@@ -234,13 +233,22 @@ declare class AuditLogger {
     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;
 }