mask-privacy 4.0.0 → 4.2.0

package/dist/index.mjs

@@ -1,19 +1,20 @@
 import * as process2 from 'process';
 import { env, versions } from 'process';
-import * as path from 'path';
+import * as path2 from 'path';
 import { join, normalize, sep, dirname } from 'path';
 import * as os from 'os';
 import { platform, release, homedir } from 'os';
-import * as crypto2 from 'crypto';
-import crypto2__default, { createHmac, createHash, createPrivateKey, createPublicKey, sign } from 'crypto';
+import * as cryptoNode from 'crypto';
+import cryptoNode__default, { createHmac, createHash, createPrivateKey, createPublicKey, sign } from 'crypto';
+import * as fs from 'fs';
+import { ReadStream, lstatSync, fstatSync, readFileSync, promises } from 'fs';
 import { Buffer as Buffer$1 } from 'buffer';
 import { Writable, Readable } from 'stream';
 import { Agent, request as request$1 } from 'https';
 import http2, { constants } from 'http2';
-import fs, { readFile } from 'fs/promises';
+import fs2, { readFile } from 'fs/promises';
 import { request } from 'http';
 import { parse } from 'url';
-import { ReadStream, lstatSync, fstatSync, readFileSync, promises } from 'fs';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 
@@ -103,6 +104,11 @@ var init_config = __esm({
       get MASK_ENCRYPTION_KEY() {
         return process2.env.MASK_ENCRYPTION_KEY || null;
       },
+      // JSON map of keyId -> base64 key string for key rotation, e.g. {"v1":"...","v2":"..."}
+      // The last entry in the map is treated as the active (encryption) key.
+      get MASK_KEYRING() {
+        return process2.env.MASK_KEYRING || null;
+      },
       get MASK_MASTER_KEY() {
         return process2.env.MASK_MASTER_KEY || process2.env.MASK_ENCRYPTION_KEY || "";
       },
@@ -115,6 +121,9 @@ var init_config = __esm({
       get MASK_BLIND_INDEX_SALT() {
         return process2.env.MASK_BLIND_INDEX_SALT || "mask-blind-index";
       },
+      get MASK_KDF_SALT() {
+        return process2.env.MASK_KDF_SALT || "mask-kdf-v4-argon2id";
+      },
       get VAULT_TOKEN() {
         return process2.env.VAULT_TOKEN || null;
       },
@@ -131,6 +140,9 @@ var init_config = __esm({
       get MASK_VAULT_CLEANUP_FREQUENCY() {
         return getEnvFloat("MASK_VAULT_CLEANUP_FREQUENCY", 0.01);
       },
+      get MASK_VAULT_MAX_MEMORY_KEYS() {
+        return getEnvInt("MASK_VAULT_MAX_MEMORY_KEYS", 1e5);
+      },
       // --- BACKEND CONNECTIONS ---
       get MASK_REDIS_URL() {
         return process2.env.MASK_REDIS_URL || "redis://localhost:6379/0";
@@ -170,7 +182,7 @@ var init_config = __esm({
         return process2.env.MASK_SCANNER_URL || "http://localhost:5001/analyze";
       },
       get MASK_MODEL_CACHE_DIR() {
-        return process2.env.MASK_MODEL_CACHE_DIR || path.join(os.homedir(), ".cache", "mask");
+        return process2.env.MASK_MODEL_CACHE_DIR || path2.join(os.homedir(), ".cache", "mask");
       },
       // --- TELEMETRY & AUDIT ---
       get MASK_AUDIT_LOG_STRICT() {
@@ -195,6 +207,16 @@ var init_key_provider = __esm({
   "src/core/key_provider.ts"() {
     init_config();
     BaseKeyProvider = class {
+      /**
+       * Return a JSON keyring string (e.g. from KMS / Secrets Manager), or null
+       * to fall back to the MASK_KEYRING environment variable.
+       *
+       * Override in KMS-backed providers to source the full keyring from a
+       * secure external store, removing the need for MASK_KEYRING in env vars.
+       */
+      getKeyring() {
+        return null;
+      }
     };
     EnvKeyProvider = class extends BaseKeyProvider {
       async getEncryptionKey() {
@@ -210,13 +232,17 @@ var init_key_provider = __esm({
         let key = config.MASK_MASTER_KEY;
         return key || null;
       }
+      /** Return MASK_KEYRING from environment (default behaviour). */
+      async getKeyring() {
+        return config.MASK_KEYRING || null;
+      }
     };
     providerInstance = null;
   }
 });
 
 // src/core/exceptions.ts
-var MaskError, MaskVaultConnectionError, MaskDecryptionError, MaskNLPTimeout, MaskSecurityError;
+var MaskError, MaskVaultConnectionError, MaskDecryptionError, MaskNLPTimeout, MaskSecurityError, TokenCollisionError;
 var init_exceptions = __esm({
   "src/core/exceptions.ts"() {
     MaskError = class extends Error {
@@ -234,6 +260,185 @@ var init_exceptions = __esm({
     };
     MaskSecurityError = class extends MaskError {
     };
+    TokenCollisionError = class extends MaskError {
+      constructor(token, existingHash, incomingHash) {
+        super(
+          `Token collision detected for token '${token}'. Existing plaintext hash '${existingHash.slice(0, 8)}\u2026' conflicts with incoming hash '${incomingHash.slice(0, 8)}\u2026'. Increase token entropy or adjust tenant salt configuration.`
+        );
+        this.token = token;
+        this.existingHash = existingHash;
+        this.incomingHash = incomingHash;
+      }
+    };
+  }
+});
+var FF1;
+var init_ff1 = __esm({
+  "src/core/ff1.ts"() {
+    FF1 = class {
+      constructor(key, tweak, radix) {
+        this.chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+        this.key = key;
+        this.tweak = tweak;
+        this.radix = radix;
+        if (radix > this.chars.length) {
+          throw new Error(`Radix ${radix} not supported`);
+        }
+      }
+      _prf(x6) {
+        const cipher = cryptoNode.createCipheriv("aes-256-cbc", this.key, Buffer.alloc(16, 0));
+        cipher.setAutoPadding(false);
+        return Buffer.concat([cipher.update(x6), cipher.final()]).subarray(-16);
+      }
+      _ciph(x6) {
+        const cipher = cryptoNode.createCipheriv("aes-256-ecb", this.key, null);
+        cipher.setAutoPadding(false);
+        return Buffer.concat([cipher.update(x6), cipher.final()]);
+      }
+      _strToInt(s6) {
+        let n6 = 0n;
+        const r6 = BigInt(this.radix);
+        for (let i6 = 0; i6 < s6.length; i6++) {
+          n6 = n6 * r6 + BigInt(this.chars.indexOf(s6[i6]));
+        }
+        return n6;
+      }
+      _intToStr(num, length) {
+        if (num === 0n) {
+          return this.chars[0].repeat(length);
+        }
+        let digits = [];
+        let n6 = num;
+        const r6 = BigInt(this.radix);
+        while (n6 > 0n) {
+          digits.push(this.chars[Number(n6 % r6)]);
+          n6 /= r6;
+        }
+        let s6 = digits.reverse().join("");
+        while (s6.length < length) s6 = this.chars[0] + s6;
+        return s6;
+      }
+      _bigintToBuffer(num, bytes) {
+        const buf = Buffer.alloc(bytes);
+        let n6 = num;
+        for (let i6 = bytes - 1; i6 >= 0; i6--) {
+          buf[i6] = Number(n6 & 0xFFn);
+          n6 >>= 8n;
+        }
+        return buf;
+      }
+      encrypt(X) {
+        const n6 = X.length;
+        const t6 = this.tweak.length;
+        if (n6 < 2) return X;
+        const u6 = Math.floor(n6 / 2);
+        const v7 = n6 - u6;
+        let A3 = X.substring(0, u6);
+        let B3 = X.substring(u6);
+        const b6 = Math.ceil(Math.ceil(v7 * Math.log2(this.radix)) / 8);
+        const d6 = 4 * Math.ceil(b6 / 4) + 4;
+        const P2 = Buffer.alloc(16);
+        P2[0] = 1;
+        P2[1] = 2;
+        P2[2] = 1;
+        P2.writeUIntBE(this.radix, 3, 3);
+        P2[6] = 10;
+        P2[7] = u6 % 256;
+        P2.writeUInt32BE(n6, 8);
+        P2.writeUInt32BE(t6, 12);
+        for (let i6 = 0; i6 < 10; i6++) {
+          const m6 = i6 % 2 === 0 ? u6 : v7;
+          const padLen = ((-t6 - b6 - 1) % 16 + 16) % 16;
+          const Q2 = Buffer.alloc(t6 + padLen + 1 + b6);
+          this.tweak.copy(Q2, 0);
+          Q2[t6 + padLen] = i6;
+          this._bigintToBuffer(this._strToInt(B3), b6).copy(Q2, t6 + padLen + 1);
+          const R2 = this._prf(Buffer.concat([P2, Q2]));
+          let S2 = Buffer.from(R2);
+          let j6 = 1;
+          while (S2.length < d6) {
+            const xorBlock = Buffer.alloc(16);
+            const jBuf = Buffer.alloc(16);
+            jBuf.writeUInt32BE(j6, 12);
+            for (let k6 = 0; k6 < 16; k6++) xorBlock[k6] = R2[k6] ^ jBuf[k6];
+            S2 = Buffer.concat([S2, this._ciph(xorBlock)]);
+            j6++;
+          }
+          S2 = S2.subarray(0, d6);
+          let y3 = 0n;
+          for (let k6 = 0; k6 < S2.length; k6++) {
+            y3 = (y3 << 8n) + BigInt(S2[k6]);
+          }
+          const modulo = BigInt(this.radix) ** BigInt(m6);
+          const c6 = (this._strToInt(A3) + y3) % modulo;
+          const C3 = this._intToStr(c6, m6);
+          A3 = B3;
+          B3 = C3;
+        }
+        return A3 + B3;
+      }
+      decrypt(X) {
+        const n6 = X.length;
+        const t6 = this.tweak.length;
+        if (n6 < 2) return X;
+        const u6 = Math.floor(n6 / 2);
+        const v7 = n6 - u6;
+        let A3 = X.substring(0, u6);
+        let B3 = X.substring(u6);
+        if (n6 % 2 !== 0) {
+          const temp = A3;
+          A3 = B3;
+          B3 = temp;
+        }
+        const b6 = Math.ceil(Math.ceil(v7 * Math.log2(this.radix)) / 8);
+        const d6 = 4 * Math.ceil(b6 / 4) + 4;
+        const P2 = Buffer.alloc(16);
+        P2[0] = 1;
+        P2[1] = 2;
+        P2[2] = 1;
+        P2.writeUIntBE(this.radix, 3, 3);
+        P2[6] = 10;
+        P2[7] = u6 % 256;
+        P2.writeUInt32BE(n6, 8);
+        P2.writeUInt32BE(t6, 12);
+        for (let i6 = 9; i6 >= 0; i6--) {
+          const m6 = i6 % 2 === 0 ? u6 : v7;
+          const padLen = ((-t6 - b6 - 1) % 16 + 16) % 16;
+          const Q2 = Buffer.alloc(t6 + padLen + 1 + b6);
+          this.tweak.copy(Q2, 0);
+          Q2[t6 + padLen] = i6;
+          this._bigintToBuffer(this._strToInt(A3), b6).copy(Q2, t6 + padLen + 1);
+          const R2 = this._prf(Buffer.concat([P2, Q2]));
+          let S2 = Buffer.from(R2);
+          let j6 = 1;
+          while (S2.length < d6) {
+            const xorBlock = Buffer.alloc(16);
+            const jBuf = Buffer.alloc(16);
+            jBuf.writeUInt32BE(j6, 12);
+            for (let k6 = 0; k6 < 16; k6++) xorBlock[k6] = R2[k6] ^ jBuf[k6];
+            S2 = Buffer.concat([S2, this._ciph(xorBlock)]);
+            j6++;
+          }
+          S2 = S2.subarray(0, d6);
+          let y3 = 0n;
+          for (let k6 = 0; k6 < S2.length; k6++) {
+            y3 = (y3 << 8n) + BigInt(S2[k6]);
+          }
+          const modulo = BigInt(this.radix) ** BigInt(m6);
+          let c6 = (this._strToInt(B3) - y3) % modulo;
+          if (c6 < 0n) c6 += modulo;
+          const C3 = this._intToStr(c6, m6);
+          B3 = A3;
+          A3 = C3;
+        }
+        if (n6 % 2 !== 0) {
+          const temp = A3;
+          A3 = B3;
+          B3 = temp;
+        }
+        return A3 + B3;
+      }
+    };
   }
 });
 
@@ -460,13 +665,13 @@ function looksLikeToken(value) {
   if (/^\+[1-9]\d{0,3}-555-\d{7}$/.test(v7)) {
     return true;
   }
-  if (v7.startsWith("000-00-") && v7.length === 11) {
+  if (/^\d{3}-\d{2}-\d{4}$/.test(v7)) {
     return true;
   }
-  if (v7.startsWith("4000-0000-0000-") && v7.length === 19) {
+  if (/^\d{4}-\d{4}-\d{4}-\d{4}$/.test(v7)) {
     return true;
   }
-  if (v7.startsWith("000000") && v7.length === 9) {
+  if (v7.length === 9 && /^\d+$/.test(v7)) {
     return true;
   }
   if (v7.length === 9 && v7.startsWith("000") && /[A-Z]$/.test(v7)) {
@@ -490,11 +695,28 @@ function looksLikeToken(value) {
   }
   return false;
 }
+function isUnambiguouslySafeToken(value) {
+  if (typeof value !== "string") return false;
+  const v7 = value.trim();
+  if (v7.startsWith("tkn-") && v7.includes("@")) {
+    const parts = v7.split("@");
+    if (parts.length === 2 && parts[0].length >= 12 && parts[1].includes(".")) {
+      return true;
+    }
+  }
+  if (/^\+[1-9]\d{0,3}-555-\d{7}$/.test(v7)) return true;
+  if (/^000\d{5}[A-Z]$/.test(v7)) return true;
+  if (/^[A-Z]{2}00[A-F0-9]{4,16}$/.test(v7)) return true;
+  if (/^<(PER|LOC|ORG):[^>]+>$/.test(v7)) return true;
+  if (v7.startsWith("[TKN-") && v7.endsWith("]")) return true;
+  if (/^[A-Z][a-zA-Z, ]+-[0-9]{3,4}$/.test(v7)) return true;
+  return false;
+}
 var TOKEN_PATTERN;
 var init_fpe_utils = __esm({
   "src/core/fpe_utils.ts"() {
     TOKEN_PATTERN = new RegExp(
-      "tkn-[a-f0-9]{8,64}@[A-Za-z0-9.\\-]+\\.[A-Za-z]{2,}|\\+[1-9]\\d{0,3}-555-\\d{7}|000-00-\\d{4}|4000-0000-0000-\\d{4}|000000\\d{3}|000\\d{5}[A-Z]|[A-Z]{2}00[A-F0-9]{4,16}|<(?:PER|LOC|ORG):[^>]+>|\\b[A-Z][a-zA-Z, ]+-[0-9]{3,4}\\b|\\\\[TKN-[a-f0-9]{8,64}\\\\]",
+      "tkn-[a-f0-9]{8,64}@[A-Za-z0-9.\\-]+\\.[A-Za-z]{2,}|\\+[1-9]\\d{0,3}-555-\\d{7}|\\d{3}-\\d{2}-\\d{4}|\\d{4}-\\d{4}-\\d{4}-\\d{4}|\\b\\d{9}\\b|\\b000\\d{5}[A-Z]\\b|[A-Z]{2}00[A-F0-9]{4,16}|<(?:PER|LOC|ORG):[^>]+>|\\b[A-Z][a-zA-Z, ]+-[0-9]{3,4}\\b|\\[TKN-[^\\]]+\\]",
       // Opaque
       "g"
     );
@@ -509,12 +731,10 @@ async function _getMasterKey() {
     }
     if (!raw) {
       if (config.MASK_DEV_MODE) {
-        raw = crypto2.randomBytes(32).toString("hex");
+        raw = cryptoNode.randomBytes(32).toString("hex");
         process.env.MASK_MASTER_KEY = raw;
       } else {
-        throw new MaskSecurityError(
-          "MASK_MASTER_KEY not set. Set it or use MASK_DEV_MODE=true for dev."
-        );
+        throw new MaskSecurityError("MASK_MASTER_KEY not set.");
       }
     }
     _masterKey = Buffer.from(raw, "utf-8");
@@ -524,38 +744,34 @@ async function _getMasterKey() {
 function resetMasterKey() {
   _masterKey = null;
 }
-async function _hmacHex(plaintext, n6 = 8) {
+async function _getAesKey() {
   const masterKey = await _getMasterKey();
-  const digest = crypto2.createHmac("sha256", masterKey).update(plaintext, "utf-8").digest("hex");
-  return digest.slice(0, n6);
+  return cryptoNode.createHmac("sha256", masterKey).update(config.MASK_TENANT_ID, "utf-8").digest();
 }
-async function _hmacInt(plaintext) {
+async function _hmacHex(plaintext, n6 = 8) {
   const masterKey = await _getMasterKey();
-  const raw = crypto2.createHmac("sha256", masterKey).update(plaintext, "utf-8").digest();
-  let result = 0n;
-  for (let i6 = 0; i6 < 16; i6++) {
-    result = result << 8n | BigInt(raw[i6]);
-  }
-  return result;
-}
-async function _hmacDigits(plaintext, n6, offset = 0) {
-  const salted = offset ? `${plaintext}::${offset}` : plaintext;
-  const seed = await _hmacInt(salted);
-  const modulus = 10n ** BigInt(n6);
-  return (seed % modulus).toString().padStart(n6, "0");
+  const digest = cryptoNode.createHmac("sha256", masterKey).update(plaintext, "utf-8").digest("hex");
+  return digest.slice(0, n6);
 }
 async function _getBijectiveTweak() {
-  const masterKey = await _getMasterKey();
-  let base = config.MASK_TENANT_ID;
   if (config.MASK_SALT_ROTATION !== "NONE") {
-    const now = /* @__PURE__ */ new Date();
-    if (config.MASK_SALT_ROTATION === "MONTHLY") {
-      base += `-${now.getUTCFullYear()}-${now.getUTCMonth() + 1}`;
-    } else if (config.MASK_SALT_ROTATION === "YEARLY") {
-      base += `-${now.getUTCFullYear()}`;
-    }
+    console.warn(
+      `[mask] MASK_SALT_ROTATION=${config.MASK_SALT_ROTATION} is deprecated and ignored. Time-based tweaks caused permanent data loss on month/year rollovers. Use MASK_KEYRING for key rotation instead.`
+    );
   }
-  return crypto2.createHmac("sha256", masterKey).update(base, "utf-8").digest();
+  const masterKey = await _getMasterKey();
+  return cryptoNode.createHmac("sha256", masterKey).update(config.MASK_TENANT_ID, "utf-8").digest();
+}
+async function _encryptBijectiveFF1(text) {
+  const canonical = text.toLowerCase().trim();
+  const hash = cryptoNode.createHash("sha256").update(canonical, "utf-8").digest();
+  const inputInt = hash.readBigUInt64BE(0);
+  const inputStr = inputInt.toString().padStart(20, "0");
+  const aesKey = await _getAesKey();
+  const tweak = await _getBijectiveTweak();
+  const engine = new FF1(aesKey, tweak, 10);
+  const cipherStr = engine.encrypt(inputStr);
+  return BigInt(cipherStr) % 2n ** 64n;
 }
 function _renderBijectivePerson(bits) {
   const firstIdx = Number(bits & 0x7FFn);
@@ -603,7 +819,10 @@ function _computeLuhnDigit(partialNum) {
 function _computeEsIdCheck(num) {
   return "TRWAGMYFPDXBNJZSQVHLCKE"[num % 23];
 }
-async function generateFPEToken(rawText, entityType = "UNKNOWN") {
+function _stripCcSeparators(text) {
+  return text.replace(/[\s\-]/g, "");
+}
+async function generateDPToken(rawText, entityType = "UNKNOWN") {
   const text = rawText.trim();
   let type = (entityType || "UNKNOWN").toUpperCase();
   if (type === "UNKNOWN") {
@@ -623,49 +842,73 @@ async function generateFPEToken(rawText, entityType = "UNKNOWN") {
   if (type === "PHONE_NUMBER" || type === "PHONE_NUM" || type === "PHONE_NUM_INTL") {
     const m6 = text.match(/^\+([1-9]\d{0,3})/);
     const cc = m6 ? m6[1] : "1";
-    return `+${cc}-555-${await _hmacDigits(text, 7)}`;
+    const digits = text.replace(/\D/g, "");
+    if (digits.length >= 7) {
+      const last7 = digits.slice(-7);
+      const engine = new FF1(await _getAesKey(), Buffer.from("PHONE"), 10);
+      const enc = engine.encrypt(last7);
+      return `+${cc}-555-${enc}`;
+    }
   }
   if (type === "US_SSN") {
-    return `000-00-${await _hmacDigits(text, 4)}`;
+    const digits = text.replace(/-/g, "");
+    if (digits.length === 9) {
+      const engine = new FF1(await _getAesKey(), Buffer.from("US_SSN"), 10);
+      const enc = engine.encrypt(digits);
+      return `${enc.slice(0, 3)}-${enc.slice(3, 5)}-${enc.slice(5, 9)}`;
+    }
   }
   if (type === "CREDIT_CARD" || type === "CREDIT_CARD_NUMBER") {
-    const base = `400000000000${await _hmacDigits(text, 3)}`;
-    const checkDig = _computeLuhnDigit(base);
-    const full = base + checkDig;
-    return `${full.slice(0, 4)}-${full.slice(4, 8)}-${full.slice(8, 12)}-${full.slice(12, 16)}`;
+    const digits = _stripCcSeparators(text);
+    if (digits.length === 16) {
+      const bin6 = digits.slice(0, 6);
+      const last4 = digits.slice(12, 16);
+      const middle6 = digits.slice(6, 12);
+      const engine = new FF1(await _getAesKey(), Buffer.from("CREDIT_CARD"), 10);
+      const encMiddle = engine.encrypt(middle6);
+      const base15 = bin6 + encMiddle + last4.slice(0, 3);
+      const checkDig = _computeLuhnDigit(base15);
+      const full = bin6 + encMiddle + last4.slice(0, 3) + checkDig;
+      return `${full.slice(0, 4)}-${full.slice(4, 8)}-${full.slice(8, 12)}-${full.slice(12, 16)}`;
+    } else {
+      const fallbackDigits = digits.padEnd(16, "0").slice(0, 16);
+      const engine = new FF1(await _getAesKey(), Buffer.from("CREDIT_CARD"), 10);
+      const encMiddle = engine.encrypt(fallbackDigits.slice(6, 12));
+      const full = fallbackDigits.slice(0, 6) + encMiddle + fallbackDigits.slice(12);
+      return `${full.slice(0, 4)}-${full.slice(4, 8)}-${full.slice(8, 12)}-${full.slice(12, 16)}`;
+    }
   }
   if (type === "US_ROUTING_NUMBER" || type === "US_ABA_ROUTING") {
-    return `000000${await _hmacDigits(text, 3)}`;
+    if (text.length === 9 && /^\d+$/.test(text)) {
+      const engine = new FF1(await _getAesKey(), Buffer.from("US_ROUTING"), 10);
+      return engine.encrypt(text);
+    }
   }
   if (type === "INTL_BANK_IBAN" || type === "IBAN_CODE") {
     const countryCode = text.length >= 2 && /[a-zA-Z]{2}/.test(text.slice(0, 2)) ? text.slice(0, 2).toUpperCase() : "US";
     return `${countryCode}00${(await _hmacHex(text, 8)).toUpperCase()}`;
   }
   if (type === "ES_ID" || type === "ES_DNI") {
-    const digits = `000${await _hmacDigits(text, 5)}`;
-    return digits + _computeEsIdCheck(parseInt(digits, 10));
+    let digits = text.toUpperCase().replace(/[A-Z]/g, "");
+    if (digits) {
+      digits = digits.padStart(8, "0");
+      const engine = new FF1(await _getAesKey(), Buffer.from("ES_ID"), 10);
+      const enc = engine.encrypt(digits.slice(-5));
+      const tokenDigits = `000${enc}`;
+      return tokenDigits + _computeEsIdCheck(parseInt(tokenDigits, 10));
+    }
   }
   if (type === "PERSON" || type === "PERSON_NAME") {
     if (config.MASK_BIJECTIVE_MODE) {
-      const canonical = text.toLowerCase().trim();
-      const hash = crypto2.createHash("sha256").update(canonical, "utf-8").digest();
-      const inputInt = hash.readBigUInt64BE(0);
-      const masterKey = await _getMasterKey();
-      const engine = new FF1(masterKey.slice(0, 16), await _getBijectiveTweak());
-      const cipher = engine.encrypt(inputInt);
-      return _renderBijectivePerson(cipher);
+      const cipherBits = await _encryptBijectiveFF1(text);
+      return _renderBijectivePerson(cipherBits);
     }
     return `[TKN-PERSON-${await _hmacHex(text)}]`;
   }
   if (type === "LOCATION" || type === "PHYS_ADDRESS") {
     if (config.MASK_BIJECTIVE_MODE) {
-      const canonical = text.toLowerCase().trim();
-      const hash = crypto2.createHash("sha256").update(canonical, "utf-8").digest();
-      const inputInt = hash.readBigUInt64BE(0);
-      const masterKey = await _getMasterKey();
-      const engine = new FF1(masterKey.slice(0, 16), await _getBijectiveTweak());
-      const cipher = engine.encrypt(inputInt);
-      return _renderBijectiveLocation(cipher);
+      const cipherBits = await _encryptBijectiveFF1(text);
+      return _renderBijectiveLocation(cipherBits);
     }
     return `[TKN-LOC-${await _hmacHex(text)}]`;
   }
@@ -674,12 +917,13 @@ async function generateFPEToken(rawText, entityType = "UNKNOWN") {
   }
   return `[TKN-${await _hmacHex(text)}]`;
 }
-var _masterKey, _EMAIL_RE, _PHONE_RE, _SSN_RE, _CC_RE, _ROUTING_RE, _ES_ID_RE, _IBAN_RE, FF1;
+var _masterKey, _EMAIL_RE, _PHONE_RE, _SSN_RE, _CC_RE, _ROUTING_RE, _ES_ID_RE, _IBAN_RE, generateFPEToken;
 var init_fpe = __esm({
   "src/core/fpe.ts"() {
     init_config();
     init_key_provider();
     init_exceptions();
+    init_ff1();
     init_synthesisLibrary();
     init_fpe_utils();
     _masterKey = null;
@@ -690,49 +934,7 @@ var init_fpe = __esm({
     _ROUTING_RE = /^\d{9}$/;
     _ES_ID_RE = /^(?:\d{8}[A-Z]|[XYZ]\d{7}[A-Z])$/;
     _IBAN_RE = /^[A-Z]{2}\d{2}[A-Z0-9]{4,30}$/;
-    FF1 = class {
-      /** NIST SP 800-38G FF1 implementation (simplified for 64-bit domains). */
-      constructor(key, tweak) {
-        this.key = key;
-        this.tweak = tweak;
-      }
-      encrypt(n6) {
-        let A3 = n6 >> 32n;
-        let B3 = n6 & 0xFFFFFFFFn;
-        const radix = 2n ** 32n;
-        for (let i6 = 0; i6 < 10; i6++) {
-          const tweakInfoBuffer = Buffer.alloc(8);
-          tweakInfoBuffer.writeUInt32BE(i6, 0);
-          tweakInfoBuffer.writeUInt32BE(Number(B3), 4);
-          const tweakInfoCombined = Buffer.concat([this.tweak, tweakInfoBuffer]);
-          const h6 = crypto2.createHmac("sha256", this.key).update(tweakInfoCombined).digest();
-          const roundVal = BigInt(h6.readUInt32BE(0));
-          const Anext = B3;
-          const Bnext = (A3 + roundVal) % radix;
-          A3 = Anext;
-          B3 = Bnext;
-        }
-        return A3 << 32n | B3;
-      }
-      decrypt(n6) {
-        let A3 = n6 >> 32n;
-        let B3 = n6 & 0xFFFFFFFFn;
-        const radix = 2n ** 32n;
-        for (let i6 = 9; i6 >= 0; i6--) {
-          const tweakInfoBuffer = Buffer.alloc(8);
-          tweakInfoBuffer.writeUInt32BE(i6, 0);
-          tweakInfoBuffer.writeUInt32BE(Number(A3), 4);
-          const tweakInfoCombined = Buffer.concat([this.tweak, tweakInfoBuffer]);
-          const h6 = crypto2.createHmac("sha256", this.key).update(tweakInfoCombined).digest();
-          const roundVal = BigInt(h6.readUInt32BE(0));
-          const Bprev = A3;
-          const Aprev = (B3 - roundVal + radix) % radix;
-          A3 = Aprev;
-          B3 = Bprev;
-        }
-        return A3 << 32n | B3;
-      }
-    };
+    generateFPEToken = generateDPToken;
   }
 });
 
@@ -749,39 +951,39 @@ var require_core = __commonJS({
       }
     })(exports2, function() {
       var CryptoJS = CryptoJS || (function(Math2, undefined2) {
-        var crypto6;
+        var crypto7;
         if (typeof window !== "undefined" && window.crypto) {
-          crypto6 = window.crypto;
+          crypto7 = window.crypto;
         }
         if (typeof self !== "undefined" && self.crypto) {
-          crypto6 = self.crypto;
+          crypto7 = self.crypto;
         }
         if (typeof globalThis !== "undefined" && globalThis.crypto) {
-          crypto6 = globalThis.crypto;
+          crypto7 = globalThis.crypto;
         }
-        if (!crypto6 && typeof window !== "undefined" && window.msCrypto) {
-          crypto6 = window.msCrypto;
+        if (!crypto7 && typeof window !== "undefined" && window.msCrypto) {
+          crypto7 = window.msCrypto;
         }
-        if (!crypto6 && typeof global !== "undefined" && global.crypto) {
-          crypto6 = global.crypto;
+        if (!crypto7 && typeof global !== "undefined" && global.crypto) {
+          crypto7 = global.crypto;
         }
-        if (!crypto6 && typeof __require === "function") {
+        if (!crypto7 && typeof __require === "function") {
           try {
-            crypto6 = __require("crypto");
+            crypto7 = __require("crypto");
           } catch (err2) {
           }
         }
         var cryptoSecureRandomInt = function() {
-          if (crypto6) {
-            if (typeof crypto6.getRandomValues === "function") {
+          if (crypto7) {
+            if (typeof crypto7.getRandomValues === "function") {
               try {
-                return crypto6.getRandomValues(new Uint32Array(1))[0];
+                return crypto7.getRandomValues(new Uint32Array(1))[0];
               } catch (err2) {
               }
             }
-            if (typeof crypto6.randomBytes === "function") {
+            if (typeof crypto7.randomBytes === "function") {
               try {
-                return crypto6.randomBytes(4).readInt32LE();
+                return crypto7.randomBytes(4).readInt32LE();
               } catch (err2) {
               }
             }
@@ -3047,7 +3249,7 @@ var require_fernet = __commonJS({
     var Base64 = require_enc_base64();
     var HmacSHA256 = require_hmac_sha256();
     var URLBase64 = require_urlsafe_base642();
-    var crypto6 = __require("crypto");
+    var crypto7 = __require("crypto");
     String.prototype.lpad = function(padString, length) {
       var str = this;
       while (str.length < length) str = padString + str;
@@ -3074,7 +3276,7 @@ var require_fernet = __commonJS({
       return hex;
     };
     var randomHex = function(size) {
-      return crypto6.randomBytes(128 / 8).toString("hex");
+      return crypto7.randomBytes(128 / 8).toString("hex");
     };
     var setIV = function setIV2(iv_array) {
       if (iv_array) {
@@ -3157,24 +3359,28 @@ function getCryptoEngine() {
 async function getCryptoEngineAsync() {
   return await CryptoEngine.getInstanceAsync();
 }
-var GCM_IV_BYTES, GCM_AUTH_TAG_BYTES, GCM_ALGORITHM, AES_GCM_PREFIX, _CryptoEngine, CryptoEngine;
+var AES_KEY_BYTES, GCM_IV_BYTES, GCM_AUTH_TAG_BYTES, GCM_ALGORITHM, AES_V2_PREFIX, AES_GCM_PREFIX, AES_GCM_LEGACY_PREFIX, _CryptoEngine, CryptoEngine;
 var init_crypto = __esm({
   "src/core/crypto.ts"() {
     init_config();
     init_key_provider();
     init_exceptions();
+    AES_KEY_BYTES = 32;
     GCM_IV_BYTES = 12;
     GCM_AUTH_TAG_BYTES = 16;
     GCM_ALGORITHM = "aes-256-gcm";
-    AES_GCM_PREFIX = "aes:";
+    AES_V2_PREFIX = "aes:v2:";
+    AES_GCM_PREFIX = "aes:v1:";
+    AES_GCM_LEGACY_PREFIX = "aes:";
     _CryptoEngine = class _CryptoEngine {
       constructor() {
-        this._aesKey = null;
+        this._keyring = /* @__PURE__ */ new Map();
+        this._activeKeyId = "default";
         this._indexSecret = null;
       }
-      /** 
+      /**
        * 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 async getInstanceAsync() {
         if (this._instance === null) {
@@ -3190,33 +3396,96 @@ var init_crypto = __esm({
         }
         return this._instance;
       }
-      /** Clear the singleton instance to force re-initialization (useful for key rotation). */
+      /** Clear the singleton (useful for key rotation / tests). */
       static reset() {
         this._instance = null;
       }
+      async _deriveAesKey(rawKey, keyId) {
+        let argon2;
+        try {
+          argon2 = __require("argon2");
+        } catch (e6) {
+          throw new Error(
+            "The 'argon2' package is required for Mask SDK cryptographic operations. Install with: npm install argon2"
+          );
+        }
+        const kdfSaltStr = config.MASK_KDF_SALT + "-" + config.MASK_TENANT_ID + "-" + keyId;
+        const kdfSaltBytes = cryptoNode.createHash("sha256").update(kdfSaltStr).digest().subarray(0, 16);
+        return await argon2.hash(rawKey, {
+          type: argon2.argon2id,
+          memoryCost: 19456,
+          timeCost: 2,
+          parallelism: 1,
+          hashLength: AES_KEY_BYTES,
+          salt: kdfSaltBytes,
+          raw: true
+        });
+      }
       async _init() {
+        let argon2;
+        try {
+          argon2 = __require("argon2");
+        } catch (e6) {
+          throw new Error("The 'argon2' package is required. Install with: npm install argon2");
+        }
         const provider = getKeyProvider();
-        const keyFromProvider = await provider.getEncryptionKey();
-        let key;
-        if (!keyFromProvider) {
-          if (config.MASK_DEV_MODE) {
-            key = crypto2.randomBytes(32).toString("base64");
-            process.env.MASK_ENCRYPTION_KEY = key;
-            console.warn(
-              "MASK_DEV_MODE is enabled. Using a generated throwaway key. DO NOT USE THIS IN PRODUCTION \u2014 tokens will be lost on restart."
-            );
-          } else {
-            throw new Error(
-              "MASK_ENCRYPTION_KEY is not set. Set MASK_ENCRYPTION_KEY to a valid encryption key, or set MASK_DEV_MODE=true to use an ephemeral throwaway key."
-            );
+        const rawKeys = /* @__PURE__ */ new Map();
+        let activeKeyId = "default";
+        const keyringJson = await provider.getKeyring();
+        if (keyringJson) {
+          let parsed;
+          try {
+            parsed = JSON.parse(keyringJson);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+              throw new Error("MASK_KEYRING must be a non-empty JSON object.");
+            }
+          } catch (e6) {
+            throw new Error(`Invalid MASK_KEYRING format: ${e6}`);
           }
+          const entries = Object.entries(parsed);
+          if (entries.length === 0) throw new Error("MASK_KEYRING must contain at least one key.");
+          for (const [kid, k6] of entries) rawKeys.set(kid, k6);
+          activeKeyId = entries[entries.length - 1][0];
         } else {
-          key = keyFromProvider;
-        }
-        this._aesKey = crypto2.createHash("sha256").update(key).digest();
-        const masterKey = await provider.getMasterKey() || key;
-        const salt = config.MASK_BLIND_INDEX_SALT;
-        this._indexSecret = crypto2.createHmac("sha256", masterKey).update(salt).digest();
+          const keyFromProvider = await provider.getEncryptionKey();
+          let key;
+          if (!keyFromProvider) {
+            if (config.MASK_DEV_MODE) {
+              key = cryptoNode.randomBytes(32).toString("base64");
+              process.env.MASK_ENCRYPTION_KEY = key;
+              console.warn(
+                "MASK_DEV_MODE is enabled. Using a generated throwaway key. DO NOT USE THIS IN PRODUCTION \u2014 tokens will be lost on restart."
+              );
+            } else {
+              throw new Error(
+                "MASK_ENCRYPTION_KEY or MASK_KEYRING is not set. Set one of these, or set MASK_DEV_MODE=true for ephemeral use."
+              );
+            }
+          } else {
+            key = keyFromProvider;
+          }
+          rawKeys.set("default", key);
+          activeKeyId = "default";
+        }
+        this._keyring = /* @__PURE__ */ new Map();
+        for (const [kid, rawKey] of rawKeys) {
+          this._keyring.set(kid, await this._deriveAesKey(rawKey, kid));
+        }
+        this._activeKeyId = activeKeyId;
+        const rawKeysArr = Array.from(rawKeys.values());
+        const lastRawKey = rawKeysArr[rawKeysArr.length - 1];
+        const masterKey = await provider.getMasterKey() || lastRawKey;
+        const indexSaltStr = config.MASK_BLIND_INDEX_SALT + "-" + config.MASK_TENANT_ID;
+        const indexSaltBytes = cryptoNode.createHash("sha256").update(indexSaltStr).digest().subarray(0, 16);
+        this._indexSecret = await argon2.hash(masterKey, {
+          type: argon2.argon2id,
+          memoryCost: 19456,
+          timeCost: 2,
+          parallelism: 1,
+          hashLength: AES_KEY_BYTES,
+          salt: indexSaltBytes,
+          raw: true
+        });
       }
       /** Return the secret used for HMAC-based blind indexing. */
       async getIndexSecret() {
@@ -3225,36 +3494,56 @@ var init_crypto = __esm({
         }
         return this._indexSecret;
       }
+      /** Encrypt plaintext using the active keyring key.
+       *  Envelope format: aes:v2:{keyId}:{base64(iv+authTag+ciphertext)}
+       */
       encrypt(plaintext) {
-        if (!this._aesKey) {
-          throw new Error("CryptoEngine not initialised. AES key missing.");
-        }
-        const iv = crypto2.randomBytes(GCM_IV_BYTES);
-        const cipher = crypto2.createCipheriv(GCM_ALGORITHM, this._aesKey, iv);
-        const encrypted = Buffer.concat([
-          cipher.update(plaintext, "utf8"),
-          cipher.final()
-        ]);
+        const aesKey = this._keyring.get(this._activeKeyId);
+        if (!aesKey) {
+          throw new Error(`CryptoEngine: active key ID '${this._activeKeyId}' not found in keyring.`);
+        }
+        const iv = cryptoNode.randomBytes(GCM_IV_BYTES);
+        const cipher = cryptoNode.createCipheriv(GCM_ALGORITHM, aesKey, iv);
+        const plaintextBuf = Buffer.from(plaintext, "utf8");
+        const encrypted = Buffer.concat([cipher.update(plaintextBuf), cipher.final()]);
         const authTag = cipher.getAuthTag();
+        plaintextBuf.fill(0);
         const combined = Buffer.concat([iv, authTag, encrypted]);
-        return AES_GCM_PREFIX + combined.toString("base64");
+        return `${AES_V2_PREFIX}${this._activeKeyId}:${combined.toString("base64")}`;
       }
+      /** Decrypt ciphertext. Supports all historical envelope formats. */
       decrypt(ciphertext) {
-        if (!this._aesKey) {
-          throw new Error("CryptoEngine not initialised. AES key missing.");
+        if (this._keyring.size === 0) {
+          throw new Error("CryptoEngine not initialised.");
         }
         try {
+          if (ciphertext.startsWith(AES_V2_PREFIX)) {
+            const rest = ciphertext.slice(AES_V2_PREFIX.length);
+            const sep3 = rest.indexOf(":");
+            if (sep3 === -1) throw new Error("Malformed aes:v2 envelope: missing key ID separator.");
+            const keyId = rest.slice(0, sep3);
+            const b64 = rest.slice(sep3 + 1);
+            return this._decryptAesGcm(keyId, b64);
+          }
           if (ciphertext.startsWith(AES_GCM_PREFIX)) {
-            return this._decryptAesGcm(ciphertext.slice(AES_GCM_PREFIX.length));
+            return this._decryptAesGcm("default", ciphertext.slice(AES_GCM_PREFIX.length));
+          }
+          if (ciphertext.startsWith(AES_GCM_LEGACY_PREFIX)) {
+            return this._decryptAesGcm("default", ciphertext.slice(AES_GCM_LEGACY_PREFIX.length));
           }
           return this._decryptLegacyFernet(ciphertext);
         } catch (e6) {
-          console.error("Failed to decrypt vault payload. Check your MASK_ENCRYPTION_KEY. Inner error:", e6);
+          console.error("Failed to decrypt vault payload. Check your MASK_ENCRYPTION_KEY / MASK_KEYRING. Inner error:", e6);
           throw new MaskDecryptionError("Decryption failed");
         }
       }
-      /** Decrypt an AES-256-GCM token (base64 encoded). */
-      _decryptAesGcm(b64) {
+      _decryptAesGcm(keyId, b64) {
+        const aesKey = this._keyring.get(keyId);
+        if (!aesKey) {
+          throw new MaskDecryptionError(
+            `No key found for key ID '${keyId}'. Ensure the key is present in MASK_KEYRING.`
+          );
+        }
         const combined = Buffer.from(b64, "base64");
         if (combined.length < GCM_IV_BYTES + GCM_AUTH_TAG_BYTES) {
           throw new Error("Ciphertext too short for AES-GCM");
@@ -3262,22 +3551,11 @@ var init_crypto = __esm({
         const iv = combined.subarray(0, GCM_IV_BYTES);
         const authTag = combined.subarray(GCM_IV_BYTES, GCM_IV_BYTES + GCM_AUTH_TAG_BYTES);
         const encrypted = combined.subarray(GCM_IV_BYTES + GCM_AUTH_TAG_BYTES);
-        const decipher = crypto2.createDecipheriv(GCM_ALGORITHM, this._aesKey, iv);
+        const decipher = cryptoNode.createDecipheriv(GCM_ALGORITHM, aesKey, iv);
         decipher.setAuthTag(authTag);
-        const decrypted = Buffer.concat([
-          decipher.update(encrypted),
-          decipher.final()
-        ]);
+        const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
         return decrypted.toString("utf8");
       }
-      /**
-       * 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.
-       */
       _decryptLegacyFernet(ciphertext) {
         let fernet;
         try {
@@ -3305,8 +3583,6 @@ var init_crypto = __esm({
     CryptoEngine = _CryptoEngine;
   }
 });
-
-// src/telemetry/audit_logger.ts
 function _getLogLevel() {
   const env3 = config.MASK_LOG_LEVEL;
   return env3 in LOG_LEVELS ? env3 : "info";
@@ -3340,16 +3616,15 @@ function getLogger(name) {
     error: (...args) => _log("error", ...args)
   };
 }
-function _makeEvent(action, token, dataType, agent = "", tool = "", extra = null) {
+function _makeEvent(action, token, dataType, agent = "", tool = "", extra = null, instanceId = "") {
   const event = {
     ts: Date.now() / 1e3,
     action,
-    // "encode" | "decode" | "expired" | "error"
     token,
     data_type: dataType,
-    // "email" | "phone" | "ssn" | "opaque"
     agent,
-    tool
+    tool,
+    instance_id: instanceId
   };
   if (extra) {
     Object.assign(event, _deepMask(extra));
@@ -3359,7 +3634,7 @@ function _makeEvent(action, token, dataType, agent = "", tool = "", extra = null
 function _deepMask(obj) {
   if (obj === null || obj === void 0) return obj;
   if (typeof obj === "string") {
-    return looksLikeToken(obj) ? obj : "[REDACTED]";
+    return isUnambiguouslySafeToken(obj) ? obj : "[REDACTED]";
   }
   if (typeof obj !== "object") return obj;
   if (Array.isArray(obj)) {
@@ -3393,6 +3668,10 @@ var init_audit_logger = __esm({
         this._shutdownRegistered = false;
         this._maxBufferSize = config.MASK_AUDIT_MAX_BUFFER_SIZE;
         this._strictMode = config.MASK_AUDIT_LOG_STRICT;
+        const rawKey = process.env.MASK_MASTER_KEY || process.env.MASK_ENCRYPTION_KEY || "";
+        this._signingKey = cryptoNode.createHash("sha256").update(rawKey).digest();
+        this._instanceId = cryptoNode.randomUUID();
+        this._prevSig = cryptoNode.createHmac("sha256", this._signingKey).update(this._instanceId, "utf-8").digest("hex");
       }
       static getInstance() {
         if (this._instance === null) {
@@ -3400,16 +3679,46 @@ var init_audit_logger = __esm({
         }
         return this._instance;
       }
+      _getOverflowPath() {
+        const d6 = process.env.MASK_SECURE_AUDIT_LOG_DIR || __require("os").tmpdir();
+        return path2.join(d6, `mask_audit_overflow_${this._instanceId}.ndjson`);
+      }
+      _writeOverflow(event) {
+        try {
+          fs.appendFileSync(this._getOverflowPath(), JSON.stringify(event) + "\n", "utf-8");
+        } catch {
+        }
+      }
+      _consumeOverflow(events) {
+        const overflowPath = this._getOverflowPath();
+        if (!fs.existsSync(overflowPath)) return;
+        const processingPath = overflowPath + ".processing";
+        try {
+          fs.renameSync(overflowPath, processingPath);
+        } catch {
+          return;
+        }
+        try {
+          const content = fs.readFileSync(processingPath, "utf-8");
+          for (const line of content.split("\n")) {
+            if (line.trim()) events.push(JSON.parse(line));
+          }
+          fs.unlinkSync(processingPath);
+        } catch (e6) {
+          _logger.error(`Failed to consume overflow: ${e6}`);
+        }
+      }
       log(action, token, dataType = "opaque", agent = "", tool = "", extra = {}) {
-        const event = _makeEvent(action, token, dataType, agent, tool, extra);
+        const event = _makeEvent(action, token, dataType, agent, tool, extra, this._instanceId);
         if (this._buffer.length >= this._maxBufferSize) {
           if (!this._bufferFullWarned) {
             _logger.warn(
-              `AuditLogger buffer full (max=${this._maxBufferSize}). Performing emergency sync-flush to prevent data loss.`
+              `AuditLogger buffer full (max=${this._maxBufferSize}). Spooling to disk overflow to prevent OOM.`
             );
             this._bufferFullWarned = true;
           }
-          this._flushSync();
+          this._writeOverflow(event);
+          return;
         }
         this._buffer.push(event);
       }
@@ -3439,27 +3748,84 @@ var init_audit_logger = __esm({
         await this._flush();
       }
       async _flush() {
-        if (this._isFlushing || this._buffer.length === 0) return;
+        if (this._isFlushing) return;
         this._isFlushing = true;
         try {
           const events = [...this._buffer];
           this._buffer = [];
           this._bufferFullWarned = false;
+          this._consumeOverflow(events);
+          if (events.length === 0) return;
+          const secureLogDir = process.env.MASK_SECURE_AUDIT_LOG_DIR || "";
+          let secureStream = null;
+          if (secureLogDir) {
+            fs.mkdirSync(secureLogDir, { recursive: true });
+            const dateStr = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+            const filePath = path2.join(secureLogDir, `mask-audit-${dateStr}.ndjson`);
+            try {
+              secureStream = fs.createWriteStream(filePath, { flags: "a" });
+            } catch {
+            }
+          }
           for (const evt of events) {
-            const json = JSON.stringify(evt, (_, v7) => typeof v7 === "bigint" ? v7.toString() : v7);
-            console.info(json);
+            const body = JSON.stringify(evt, (_, v7) => typeof v7 === "bigint" ? v7.toString() : v7);
+            const sigInput = Buffer.from(this._prevSig + body, "utf-8");
+            const sig = cryptoNode.createHmac("sha256", this._signingKey).update(sigInput).digest("hex");
+            const signedLine = JSON.stringify({
+              ...evt,
+              prev_sig: this._prevSig,
+              sig
+            }, (_, v7) => typeof v7 === "bigint" ? v7.toString() : v7);
+            this._prevSig = sig;
+            console.info(signedLine);
+            if (secureStream) {
+              secureStream.write(signedLine + "\n");
+            }
+          }
+          if (secureStream) {
+            secureStream.end();
           }
         } finally {
           this._isFlushing = false;
         }
       }
-      /** 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.
+       */
       _flushSync() {
         if (this._buffer.length === 0) return;
         const events = [...this._buffer];
         this._buffer = [];
+        const secureLogDir = process.env.MASK_SECURE_AUDIT_LOG_DIR || "";
+        let secureFilePath = null;
+        if (secureLogDir) {
+          try {
+            fs.mkdirSync(secureLogDir, { recursive: true });
+            const dateStr = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+            secureFilePath = path2.join(secureLogDir, `mask-audit-${dateStr}.ndjson`);
+          } catch {
+          }
+        }
         for (const evt of events) {
-          process.stdout.write(JSON.stringify(evt) + "\n");
+          const body = JSON.stringify(evt, (_, v7) => typeof v7 === "bigint" ? v7.toString() : v7);
+          const sigInput = Buffer.from(this._prevSig + body, "utf-8");
+          const sig = cryptoNode.createHmac("sha256", this._signingKey).update(sigInput).digest("hex");
+          const signedLine = JSON.stringify({
+            ...evt,
+            prev_sig: this._prevSig,
+            sig
+          }, (_, v7) => typeof v7 === "bigint" ? v7.toString() : v7);
+          this._prevSig = sig;
+          process.stdout.write(signedLine + "\n");
+          if (secureFilePath) {
+            try {
+              fs.appendFileSync(secureFilePath, signedLine + "\n", { encoding: "utf-8" });
+            } catch {
+            }
+          }
         }
       }
     };
@@ -3511,7 +3877,7 @@ var init_search = __esm({
       static async getBucketIndex(bucketVal) {
         const engine = await getCryptoEngine();
         const secret = await engine.getIndexSecret();
-        return crypto2.createHmac("sha256", secret).update(bucketVal).digest("hex");
+        return cryptoNode.createHmac("sha256", secret).update(bucketVal).digest("hex");
       }
     };
   }
@@ -15657,9 +16023,9 @@ var init_createPaginator = __esm({
       command = withCommand(command) ?? command;
       return await client.send(command, ...args);
     };
-    get = (fromObject, path3) => {
+    get = (fromObject, path4) => {
       let cursor = fromObject;
-      const pathComponents = path3.split(".");
+      const pathComponents = path4.split(".");
       for (const step of pathComponents) {
         if (!cursor || typeof cursor !== "object") {
           return void 0;
@@ -16270,12 +16636,12 @@ or increase socketAcquisitionWarningTimeout=(millis) in the NodeHttpHandler conf
             const password = request2.password ?? "";
             auth = `${username}:${password}`;
           }
-          let path3 = request2.path;
+          let path4 = request2.path;
           if (queryString) {
-            path3 += `?${queryString}`;
+            path4 += `?${queryString}`;
           }
           if (request2.fragment) {
-            path3 += `#${request2.fragment}`;
+            path4 += `#${request2.fragment}`;
           }
           let hostname = request2.hostname ?? "";
           if (hostname[0] === "[" && hostname.endsWith("]")) {
@@ -16287,7 +16653,7 @@ or increase socketAcquisitionWarningTimeout=(millis) in the NodeHttpHandler conf
             headers: request2.headers,
             host: hostname,
             method: request2.method,
-            path: path3,
+            path: path4,
             port: request2.port,
             agent,
             auth
@@ -16594,16 +16960,16 @@ var init_node_http2_handler = __esm({
             reject(err2);
           };
           const queryString = buildQueryString(query || {});
-          let path3 = request2.path;
+          let path4 = request2.path;
           if (queryString) {
-            path3 += `?${queryString}`;
+            path4 += `?${queryString}`;
           }
           if (request2.fragment) {
-            path3 += `#${request2.fragment}`;
+            path4 += `#${request2.fragment}`;
           }
           const req = session.request({
             ...request2.headers,
-            [constants.HTTP2_HEADER_PATH]: path3,
+            [constants.HTTP2_HEADER_PATH]: path4,
             [constants.HTTP2_HEADER_METHOD]: method
           });
           session.ref();
@@ -18052,10 +18418,10 @@ var init_date_utils = __esm({
     };
   }
 });
-var randomUUID;
+var randomUUID2;
 var init_randomUUID = __esm({
   "node_modules/@smithy/uuid/dist-es/randomUUID.js"() {
-    randomUUID = crypto2__default.randomUUID.bind(crypto2__default);
+    randomUUID2 = cryptoNode__default.randomUUID.bind(cryptoNode__default);
   }
 });
 
@@ -18066,8 +18432,8 @@ var init_v4 = __esm({
     init_randomUUID();
     decimalToHex = Array.from({ length: 256 }, (_, i6) => i6.toString(16).padStart(2, "0"));
     v4 = () => {
-      if (randomUUID) {
-        return randomUUID();
+      if (randomUUID2) {
+        return randomUUID2();
       }
       const rnds = new Uint8Array(16);
       crypto.getRandomValues(rnds);
@@ -18805,11 +19171,11 @@ var init_HttpBindingProtocol = __esm({
           const opTraits = translateTraits(operationSchema.traits);
           if (opTraits.http) {
             request2.method = opTraits.http[0];
-            const [path3, search] = opTraits.http[1].split("?");
+            const [path4, search] = opTraits.http[1].split("?");
             if (request2.path == "/") {
-              request2.path = path3;
+              request2.path = path4;
             } else {
-              request2.path += path3;
+              request2.path += path4;
             }
             const traitSearchParams = new URLSearchParams(search ?? "");
             Object.assign(query, Object.fromEntries(traitSearchParams));
@@ -19842,18 +20208,18 @@ var getAttrPathList;
 var init_getAttrPathList = __esm({
   "node_modules/@smithy/util-endpoints/dist-es/lib/getAttrPathList.js"() {
     init_types2();
-    getAttrPathList = (path3) => {
-      const parts = path3.split(".");
+    getAttrPathList = (path4) => {
+      const parts = path4.split(".");
       const pathList = [];
       for (const part of parts) {
         const squareBracketIndex = part.indexOf("[");
         if (squareBracketIndex !== -1) {
           if (part.indexOf("]") !== part.length - 1) {
-            throw new EndpointError(`Path: '${path3}' does not end with ']'`);
+            throw new EndpointError(`Path: '${path4}' does not end with ']'`);
           }
           const arrayIndex = part.slice(squareBracketIndex + 1, -1);
           if (Number.isNaN(parseInt(arrayIndex))) {
-            throw new EndpointError(`Invalid array index: '${arrayIndex}' in path: '${path3}'`);
+            throw new EndpointError(`Invalid array index: '${arrayIndex}' in path: '${path4}'`);
           }
           if (squareBracketIndex !== 0) {
             pathList.push(part.slice(0, squareBracketIndex));
@@ -19874,9 +20240,9 @@ var init_getAttr = __esm({
   "node_modules/@smithy/util-endpoints/dist-es/lib/getAttr.js"() {
     init_types2();
     init_getAttrPathList();
-    getAttr = (value, path3) => getAttrPathList(path3).reduce((acc, index) => {
+    getAttr = (value, path4) => getAttrPathList(path4).reduce((acc, index) => {
       if (typeof acc !== "object") {
-        throw new EndpointError(`Index '${index}' in '${path3}' not found in '${JSON.stringify(value)}'`);
+        throw new EndpointError(`Index '${index}' in '${path4}' not found in '${JSON.stringify(value)}'`);
       } else if (Array.isArray(acc)) {
         return acc[parseInt(index)];
       }
@@ -19918,8 +20284,8 @@ var init_parseURL = __esm({
             return value;
           }
           if (typeof value === "object" && "hostname" in value) {
-            const { hostname: hostname2, port, protocol: protocol2 = "", path: path3 = "", query = {} } = value;
-            const url = new URL(`${protocol2}//${hostname2}${port ? `:${port}` : ""}${path3}`);
+            const { hostname: hostname2, port, protocol: protocol2 = "", path: path4 = "", query = {} } = value;
+            const url = new URL(`${protocol2}//${hostname2}${port ? `:${port}` : ""}${path4}`);
             url.search = Object.entries(query).map(([k6, v7]) => `${k6}=${v7}`).join("&");
             return url;
           }
@@ -21674,10 +22040,10 @@ ${longDate}
 ${credentialScope}
 ${toHex(hashedRequest)}`;
       }
-      getCanonicalPath({ path: path3 }) {
+      getCanonicalPath({ path: path4 }) {
         if (this.uriEscapePath) {
           const normalizedPathSegments = [];
-          for (const pathSegment of path3.split("/")) {
+          for (const pathSegment of path4.split("/")) {
             if (pathSegment?.length === 0)
               continue;
             if (pathSegment === ".")
@@ -21688,11 +22054,11 @@ ${toHex(hashedRequest)}`;
               normalizedPathSegments.push(pathSegment);
             }
           }
-          const normalizedPath = `${path3?.startsWith("/") ? "/" : ""}${normalizedPathSegments.join("/")}${normalizedPathSegments.length > 0 && path3?.endsWith("/") ? "/" : ""}`;
+          const normalizedPath = `${path4?.startsWith("/") ? "/" : ""}${normalizedPathSegments.join("/")}${normalizedPathSegments.length > 0 && path4?.endsWith("/") ? "/" : ""}`;
           const doubleEncoded = escapeUri(normalizedPath);
           return doubleEncoded.replace(/%2F/g, "/");
         }
-        return path3;
+        return path4;
       }
       validateResolvedCredentials(credentials) {
         if (typeof credentials !== "object" || typeof credentials.accessKeyId !== "string" || typeof credentials.secretAccessKey !== "string") {
@@ -27687,8 +28053,8 @@ var init_createConfigValueProvider = __esm({
               return endpoint.url.href;
             }
             if ("hostname" in endpoint) {
-              const { protocol, hostname, port, path: path3 } = endpoint;
-              return `${protocol}//${hostname}${port ? ":" + port : ""}${path3}`;
+              const { protocol, hostname, port, path: path4 } = endpoint;
+              return `${protocol}//${hostname}${port ? ":" + port : ""}${path4}`;
             }
           }
           return endpoint;
@@ -27904,14 +28270,14 @@ var init_readFile = __esm({
   "node_modules/@smithy/shared-ini-file-loader/dist-es/readFile.js"() {
     filePromises = {};
     fileIntercept = {};
-    readFile2 = (path3, options) => {
-      if (fileIntercept[path3] !== void 0) {
-        return fileIntercept[path3];
+    readFile2 = (path4, options) => {
+      if (fileIntercept[path4] !== void 0) {
+        return fileIntercept[path4];
       }
-      if (!filePromises[path3] || options?.ignoreCache) {
-        filePromises[path3] = readFile(path3, "utf8");
+      if (!filePromises[path4] || options?.ignoreCache) {
+        filePromises[path4] = readFile(path4, "utf8");
       }
-      return filePromises[path3];
+      return filePromises[path4];
     };
   }
 });
@@ -28020,8 +28386,8 @@ var init_externalDataInterceptor = __esm({
       getFileRecord() {
         return fileIntercept;
       },
-      interceptFile(path3, contents) {
-        fileIntercept[path3] = Promise.resolve(contents);
+      interceptFile(path4, contents) {
+        fileIntercept[path4] = Promise.resolve(contents);
       },
       getTokenRecord() {
         return tokenIntercept;
@@ -33819,7 +34185,7 @@ Set AWS_CONTAINER_CREDENTIALS_FULL_URI or AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
         if (token) {
           request2.headers.Authorization = token;
         } else if (tokenFile) {
-          request2.headers.Authorization = (await fs.readFile(tokenFile)).toString();
+          request2.headers.Authorization = (await fs2.readFile(tokenFile)).toString();
         }
         try {
           const result = await requestHandler.handle(request2);
@@ -43291,9 +43657,28 @@ function _getFailStrategy() {
 function _hashPlaintext(plaintext, secret) {
   const trimmed = plaintext.trim();
   if (secret) {
-    return crypto2.createHmac("sha256", secret).update(trimmed, "utf-8").digest("hex");
+    return cryptoNode.createHmac("sha256", secret).update(trimmed, "utf-8").digest("hex");
+  }
+  return cryptoNode.createHash("sha256").update(trimmed, "utf-8").digest("hex");
+}
+function _vaultKey(token) {
+  return `mask:${config.MASK_TENANT_ID}:${token}`;
+}
+function _vaultRevKey(ptHash) {
+  return `mask-rev:${config.MASK_TENANT_ID}:${ptHash}`;
+}
+function _vaultHashKey(token) {
+  return `mask-hash:${config.MASK_TENANT_ID}:${token}`;
+}
+function _unwrapPayload(raw) {
+  if (raw && raw.startsWith("{")) {
+    try {
+      const obj = JSON.parse(raw);
+      if (obj.ct) return obj.ct;
+    } catch {
+    }
   }
-  return crypto2.createHash("sha256").update(trimmed, "utf-8").digest("hex");
+  return raw;
 }
 function getVault() {
   if (_vaultInstance === null) {
@@ -43334,10 +43719,17 @@ async function encode(rawText, options = {}) {
       return existingToken;
     }
   }
-  const token = await generateFPEToken(text, options.entityType || "UNKNOWN");
+  const token = await generateDPToken(text, options.entityType || "UNKNOWN");
   const ciphertext = cryptoEngine.encrypt(text);
+  const existingCiphertext = await vault.retrieve(token);
+  if (existingCiphertext !== null) {
+    const existingHash = await vault.getPtHashForToken(token);
+    if (existingHash && existingHash !== ptHash) {
+      throw new TokenCollisionError(token, existingHash, ptHash);
+    }
+  }
   const ttl = options.ttl || DEFAULT_TTL;
-  await vault.store(token, ciphertext, ttl, ptHash);
+  await vault.store(token, ciphertext, ttl, ptHash, options.metadata || null);
   if (options.searchBuckets && options.searchBuckets.length > 0) {
     for (const bType of options.searchBuckets) {
       let bucketVal;
@@ -43359,8 +43751,8 @@ async function decode(token) {
     throw new DecodeError("Token not found or expired");
   }
   try {
-    const crypto6 = await getCryptoEngineAsync();
-    const result = crypto6.decrypt(ciphertext);
+    const crypto7 = await getCryptoEngineAsync();
+    const result = crypto7.decrypt(ciphertext);
     getAuditLogger().log("decode", token);
     return result;
   } catch (e6) {
@@ -43412,14 +43804,15 @@ var init_vault = __esm({
     MemoryVault = class extends BaseVault {
       constructor() {
         super();
+        this._cleanupTimer = null;
         this._store = /* @__PURE__ */ new Map();
         this._reverseStore = /* @__PURE__ */ new Map();
+        this._cleanupTimer = setInterval(() => this._cleanup(), 6e4);
+        if (this._cleanupTimer && typeof this._cleanupTimer.unref === "function") {
+          this._cleanupTimer.unref();
+        }
       }
       _cleanup() {
-        const cleanupFreq = config.MASK_VAULT_CLEANUP_FREQUENCY;
-        if (Math.random() > cleanupFreq) {
-          return;
-        }
         const now = Date.now() / 1e3;
         for (const [token, entry] of this._store.entries()) {
           if (now > entry.expiry) {
@@ -43430,27 +43823,41 @@ var init_vault = __esm({
           }
         }
       }
-      async store(token, plaintext, ttlSeconds, ptHash = null) {
-        this._cleanup();
+      async store(token, ciphertext, ttlSeconds, ptHash = null, metadata = null) {
+        if (!this._store.has(token) && this._store.size >= config.MASK_VAULT_MAX_MEMORY_KEYS) {
+          const firstKey = this._store.keys().next().value;
+          if (firstKey !== void 0) {
+            const oldEntry = this._store.get(firstKey);
+            this._store.delete(firstKey);
+            if (oldEntry?.ptHash && this._reverseStore.get(oldEntry.ptHash) === firstKey) {
+              this._reverseStore.delete(oldEntry.ptHash);
+            }
+          }
+        }
+        const existing = this._store.get(token);
+        if (existing) this._store.delete(token);
         this._store.set(token, {
-          plaintext,
+          plaintext: ciphertext,
           expiry: Date.now() / 1e3 + ttlSeconds,
-          ptHash
+          ptHash,
+          metadata: { ...existing?.metadata || {}, ...metadata || {} }
         });
         if (ptHash) {
           this._reverseStore.set(ptHash, token);
         }
       }
       async getTokenByPlaintextHash(ptHash) {
-        this._cleanup();
         const token = this._reverseStore.get(ptHash);
         if (token && this._store.has(token)) {
           return token;
         }
         return null;
       }
+      async getPtHashForToken(token) {
+        const entry = this._store.get(token);
+        return entry?.ptHash ?? null;
+      }
       async retrieve(token) {
-        this._cleanup();
         const entry = this._store.get(token);
         if (!entry) {
           return null;
@@ -43506,13 +43913,14 @@ var init_vault = __esm({
           throw new MaskVaultConnectionError(`Failed to connect to Redis: ${e6}`);
         }
       }
-      async store(token, ciphertext, ttlSeconds, ptHash = null) {
+      async store(token, ciphertext, ttlSeconds, ptHash = null, metadata = null) {
         try {
           const pipeline = this._client.pipeline();
-          pipeline.set(`mask:${token}`, ciphertext, "EX", ttlSeconds);
+          const payload = metadata ? JSON.stringify({ ct: ciphertext, meta: metadata }) : ciphertext;
+          pipeline.set(_vaultKey(token), payload, "EX", ttlSeconds);
           if (ptHash) {
-            pipeline.set(`mask-rev:${ptHash}`, token, "EX", ttlSeconds);
-            pipeline.set(`mask-hash:${token}`, ptHash, "EX", ttlSeconds);
+            pipeline.set(_vaultRevKey(ptHash), token, "EX", ttlSeconds);
+            pipeline.set(_vaultHashKey(token), ptHash, "EX", ttlSeconds);
           }
           const results = await pipeline.exec();
           if (results) {
@@ -43524,14 +43932,21 @@ var init_vault = __esm({
           throw new MaskVaultConnectionError(`Redis error: ${e6}`);
         }
       }
+      async getPtHashForToken(token) {
+        try {
+          return await this._client.get(_vaultHashKey(token));
+        } catch {
+          return null;
+        }
+      }
       async getTokenByPlaintextHash(ptHash) {
         try {
-          const token = await this._client.get(`mask-rev:${ptHash}`);
+          const token = await this._client.get(_vaultRevKey(ptHash));
           if (token) {
-            if (await this._client.exists(`mask:${token}`)) {
+            if (await this._client.exists(_vaultKey(token))) {
               return token;
             } else {
-              await this._client.del(`mask-rev:${ptHash}`);
+              await this._client.del(_vaultRevKey(ptHash));
             }
           }
           return null;
@@ -43544,7 +43959,8 @@ var init_vault = __esm({
       }
       async retrieve(token) {
         try {
-          return await this._client.get(`mask:${token}`);
+          const raw = await this._client.get(_vaultKey(token));
+          return raw ? _unwrapPayload(raw) : null;
         } catch (e6) {
           if (_getFailStrategy() === "closed") {
             throw new MaskVaultConnectionError(`Redis read failed: ${e6}`);
@@ -43554,12 +43970,12 @@ var init_vault = __esm({
       }
       async delete(token) {
         try {
-          const ptHash = await this._client.get(`mask-hash:${token}`);
+          const ptHash = await this._client.get(_vaultHashKey(token));
           const pipeline = this._client.pipeline();
-          pipeline.del(`mask:${token}`);
-          pipeline.del(`mask-hash:${token}`);
+          pipeline.del(_vaultKey(token));
+          pipeline.del(_vaultHashKey(token));
           if (ptHash) {
-            pipeline.del(`mask-rev:${ptHash}`);
+            pipeline.del(_vaultRevKey(ptHash));
           }
           await pipeline.exec();
         } catch (e6) {
@@ -43598,39 +44014,26 @@ var init_vault = __esm({
         this._client = DynamoDBDocument.from(baseClient);
         console.info(`DynamoDBVault connected to table ${this._tableName} in ${this._region}`);
       }
-      async store(token, ciphertext, ttlSeconds, ptHash = null) {
+      async store(token, ciphertext, ttlSeconds, ptHash = null, metadata = null) {
         const { TransactWriteCommand, PutCommand } = __require("@aws-sdk/lib-dynamodb");
         const now = Math.floor(Date.now() / 1e3);
         const ttlVal = now + ttlSeconds;
-        const item = {
-          token: `mask:${token}`,
+        const primaryItem = {
+          token: _vaultKey(token),
           ciphertext,
-          ttl: ttlVal,
-          ptr_hash: ptHash || void 0
+          ttl: ttlVal
         };
+        if (ptHash) primaryItem.ptr_hash = ptHash;
+        if (metadata) primaryItem.meta_json = JSON.stringify(metadata);
         if (ptHash) {
           try {
             await this._client.send(new TransactWriteCommand({
               TransactItems: [
+                { Put: { TableName: this._tableName, Item: primaryItem } },
                 {
                   Put: {
                     TableName: this._tableName,
-                    Item: {
-                      token: `mask:${token}`,
-                      ciphertext,
-                      ttl: ttlVal,
-                      ptr_hash: ptHash
-                    }
-                  }
-                },
-                {
-                  Put: {
-                    TableName: this._tableName,
-                    Item: {
-                      token: `mask-rev:${ptHash}`,
-                      ciphertext: token,
-                      ttl: ttlVal
-                    }
+                    Item: { token: _vaultRevKey(ptHash), ciphertext: token, ttl: ttlVal }
                   }
                 }
               ]
@@ -43641,7 +44044,7 @@ var init_vault = __esm({
           }
         } else {
           try {
-            await this._client.send(new PutCommand({ TableName: this._tableName, Item: item }));
+            await this._client.send(new PutCommand({ TableName: this._tableName, Item: primaryItem }));
           } catch (e6) {
             throw new MaskVaultConnectionError(`DynamoDB individual write failed: ${e6}`);
           }
@@ -43653,12 +44056,12 @@ var init_vault = __esm({
           const now = Math.floor(Date.now() / 1e3);
           const resp = await this._client.send(new GetCommand({
             TableName: this._tableName,
-            Key: { token: `mask-rev:${ptHash}` }
+            Key: { token: _vaultRevKey(ptHash) }
           }));
           const item = resp.Item;
           if (!item) return null;
           if (now > (item.ttl || 0)) {
-            await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: `mask-rev:${ptHash}` } }));
+            await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: _vaultRevKey(ptHash) } }));
             return null;
           }
           const token = item.ciphertext;
@@ -43674,16 +44077,16 @@ var init_vault = __esm({
           const now = Math.floor(Date.now() / 1e3);
           const resp = await this._client.send(new GetCommand({
             TableName: this._tableName,
-            Key: { token: `mask:${token}` }
+            Key: { token: _vaultKey(token) }
           }));
           const item = resp.Item;
           if (!item) return null;
           if (now > (item.ttl || 0)) {
             const ptHash = item.ptr_hash;
             if (ptHash) {
-              await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: `mask-rev:${ptHash}` } }));
+              await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: _vaultRevKey(ptHash) } }));
             }
-            await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: `mask:${token}` } }));
+            await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: _vaultKey(token) } }));
             return null;
           }
           return item.ciphertext;
@@ -43692,18 +44095,30 @@ var init_vault = __esm({
           return null;
         }
       }
+      async getPtHashForToken(token) {
+        try {
+          const { GetCommand } = __require("@aws-sdk/lib-dynamodb");
+          const resp = await this._client.send(new GetCommand({
+            TableName: this._tableName,
+            Key: { token: _vaultKey(token) }
+          }));
+          return resp.Item?.ptr_hash ?? null;
+        } catch {
+          return null;
+        }
+      }
       async delete(token) {
         try {
           const { GetCommand, DeleteCommand } = __require("@aws-sdk/lib-dynamodb");
           const resp = await this._client.send(new GetCommand({
             TableName: this._tableName,
-            Key: { token: `mask:${token}` }
+            Key: { token: _vaultKey(token) }
           }));
           const item = resp.Item;
           if (item && item.ptr_hash) {
-            await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: `mask-rev:${item.ptr_hash}` } }));
+            await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: _vaultRevKey(item.ptr_hash) } }));
           }
-          await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: `mask:${token}` } }));
+          await this._client.send(new DeleteCommand({ TableName: this._tableName, Key: { token: _vaultKey(token) } }));
         } catch (e6) {
           if (_getFailStrategy() === "closed") throw new MaskVaultConnectionError(`DynamoDB delete failed: ${e6}`);
         }
@@ -43722,20 +44137,29 @@ var init_vault = __esm({
           throw new MaskVaultConnectionError(`Failed to connect to Memcached: ${e6}`);
         }
       }
-      async store(token, ciphertext, ttlSeconds, ptHash = null) {
+      async store(token, ciphertext, ttlSeconds, ptHash = null, metadata = null) {
         try {
-          await this._client.set(`mask:${token}`, Buffer.from(ciphertext), { expires: ttlSeconds });
+          const payload = metadata ? JSON.stringify({ ct: ciphertext, meta: metadata }) : ciphertext;
+          await this._client.set(_vaultKey(token), Buffer.from(payload), { expires: ttlSeconds });
           if (ptHash) {
-            await this._client.set(`mask-rev:${ptHash}`, Buffer.from(token), { expires: ttlSeconds });
-            await this._client.set(`mask-hash:${token}`, Buffer.from(ptHash), { expires: ttlSeconds });
+            await this._client.set(_vaultRevKey(ptHash), Buffer.from(token), { expires: ttlSeconds });
+            await this._client.set(_vaultHashKey(token), Buffer.from(ptHash), { expires: ttlSeconds });
           }
         } catch (e6) {
           throw new MaskVaultConnectionError(`Memcached error: ${e6}`);
         }
       }
+      async getPtHashForToken(token) {
+        try {
+          const { value } = await this._client.get(_vaultHashKey(token));
+          return value ? value.toString() : null;
+        } catch {
+          return null;
+        }
+      }
       async getTokenByPlaintextHash(ptHash) {
         try {
-          const { value } = await this._client.get(`mask-rev:${ptHash}`);
+          const { value } = await this._client.get(_vaultRevKey(ptHash));
           if (!value) return null;
           const token = value.toString();
           return await this.retrieve(token) !== null ? token : null;
@@ -43746,8 +44170,9 @@ var init_vault = __esm({
       }
       async retrieve(token) {
         try {
-          const { value } = await this._client.get(`mask:${token}`);
-          return value ? value.toString() : null;
+          const { value } = await this._client.get(_vaultKey(token));
+          if (!value) return null;
+          return _unwrapPayload(value.toString());
         } catch (e6) {
           if (_getFailStrategy() === "closed") throw new MaskVaultConnectionError(`Memcached read failed: ${e6}`);
           return null;
@@ -43755,12 +44180,12 @@ var init_vault = __esm({
       }
       async delete(token) {
         try {
-          const { value } = await this._client.get(`mask-hash:${token}`);
+          const { value } = await this._client.get(_vaultHashKey(token));
           const ptHash = value ? value.toString() : null;
-          await this._client.delete(`mask:${token}`);
-          await this._client.delete(`mask-hash:${token}`);
+          await this._client.delete(_vaultKey(token));
+          await this._client.delete(_vaultHashKey(token));
           if (ptHash) {
-            await this._client.delete(`mask-rev:${ptHash}`);
+            await this._client.delete(_vaultRevKey(ptHash));
           }
         } catch (e6) {
           if (_getFailStrategy() === "closed") throw new MaskVaultConnectionError(`Memcached delete failed: ${e6}`);
@@ -53478,11 +53903,11 @@ var require_mime_types = __commonJS({
       }
       return exts[0];
     }
-    function lookup(path3) {
-      if (!path3 || typeof path3 !== "string") {
+    function lookup(path4) {
+      if (!path4 || typeof path4 !== "string") {
         return false;
       }
-      var extension2 = extname("x." + path3).toLowerCase().substr(1);
+      var extension2 = extname("x." + path4).toLowerCase().substr(1);
       if (!extension2) {
         return false;
       }
@@ -54549,13 +54974,13 @@ var require_form_data = __commonJS({
   "node_modules/form-data/lib/form_data.js"(exports2, module) {
     var CombinedStream = require_combined_stream();
     var util = __require("util");
-    var path3 = __require("path");
+    var path4 = __require("path");
     var http = __require("http");
     var https = __require("https");
     var parseUrl2 = __require("url").parse;
-    var fs3 = __require("fs");
+    var fs4 = __require("fs");
     var Stream = __require("stream").Stream;
-    var crypto6 = __require("crypto");
+    var crypto7 = __require("crypto");
     var mime = require_mime_types();
     var asynckit = require_asynckit();
     var setToStringTag = require_es_set_tostringtag();
@@ -54620,7 +55045,7 @@ var require_form_data = __commonJS({
         if (value.end != void 0 && value.end != Infinity && value.start != void 0) {
           callback(null, value.end + 1 - (value.start ? value.start : 0));
         } else {
-          fs3.stat(value.path, function(err2, stat) {
+          fs4.stat(value.path, function(err2, stat) {
             if (err2) {
               callback(err2);
               return;
@@ -54677,11 +55102,11 @@ var require_form_data = __commonJS({
     FormData2.prototype._getContentDisposition = function(value, options) {
       var filename;
       if (typeof options.filepath === "string") {
-        filename = path3.normalize(options.filepath).replace(/\\/g, "/");
+        filename = path4.normalize(options.filepath).replace(/\\/g, "/");
       } else if (options.filename || value && (value.name || value.path)) {
-        filename = path3.basename(options.filename || value && (value.name || value.path));
+        filename = path4.basename(options.filename || value && (value.name || value.path));
       } else if (value && value.readable && hasOwn(value, "httpVersion")) {
-        filename = path3.basename(value.client._httpMessage.path || "");
+        filename = path4.basename(value.client._httpMessage.path || "");
       }
       if (filename) {
         return 'filename="' + filename + '"';
@@ -54761,7 +55186,7 @@ var require_form_data = __commonJS({
       return Buffer.concat([dataBuffer, Buffer.from(this._lastBoundary())]);
     };
     FormData2.prototype._generateBoundary = function() {
-      this._boundary = "--------------------------" + crypto6.randomBytes(12).toString("hex");
+      this._boundary = "--------------------------" + crypto7.randomBytes(12).toString("hex");
     };
     FormData2.prototype.getLengthSync = function() {
       var knownLength = this._overheadLength + this._valueLength;
@@ -55451,7 +55876,7 @@ var require_follow_redirects = __commonJS({
 var require_axios = __commonJS({
   "node_modules/axios/dist/node/axios.cjs"(exports2, module) {
     var FormData$1 = require_form_data();
-    var crypto6 = __require("crypto");
+    var crypto7 = __require("crypto");
     var url = __require("url");
     var proxyFromEnv = require_proxy_from_env();
     var http = __require("http");
@@ -55466,7 +55891,7 @@ var require_axios = __commonJS({
       return e6 && typeof e6 === "object" && "default" in e6 ? e6 : { "default": e6 };
     }
     var FormData__default = /* @__PURE__ */ _interopDefaultLegacy(FormData$1);
-    var crypto__default = /* @__PURE__ */ _interopDefaultLegacy(crypto6);
+    var crypto__default = /* @__PURE__ */ _interopDefaultLegacy(crypto7);
     var url__default = /* @__PURE__ */ _interopDefaultLegacy(url);
     var proxyFromEnv__default = /* @__PURE__ */ _interopDefaultLegacy(proxyFromEnv);
     var http__default = /* @__PURE__ */ _interopDefaultLegacy(http);
@@ -55985,9 +56410,9 @@ var require_axios = __commonJS({
     function removeBrackets(key) {
       return utils$1.endsWith(key, "[]") ? key.slice(0, -2) : key;
     }
-    function renderKey(path3, key, dots) {
-      if (!path3) return key;
-      return path3.concat(key).map(function each(token, i6) {
+    function renderKey(path4, key, dots) {
+      if (!path4) return key;
+      return path4.concat(key).map(function each(token, i6) {
         token = removeBrackets(token);
         return !dots && i6 ? "[" + token + "]" : token;
       }).join(dots ? "." : "");
@@ -56040,13 +56465,13 @@ var require_axios = __commonJS({
         }
         return value;
       }
-      function defaultVisitor(value, key, path3) {
+      function defaultVisitor(value, key, path4) {
         let arr = value;
         if (utils$1.isReactNative(formData) && utils$1.isReactNativeBlob(value)) {
-          formData.append(renderKey(path3, key, dots), convertValue(value));
+          formData.append(renderKey(path4, key, dots), convertValue(value));
           return false;
         }
-        if (value && !path3 && typeof value === "object") {
+        if (value && !path4 && typeof value === "object") {
           if (utils$1.endsWith(key, "{}")) {
             key = metaTokens ? key : key.slice(0, -2);
             value = JSON.stringify(value);
@@ -56065,7 +56490,7 @@ var require_axios = __commonJS({
         if (isVisitable(value)) {
           return true;
         }
-        formData.append(renderKey(path3, key, dots), convertValue(value));
+        formData.append(renderKey(path4, key, dots), convertValue(value));
         return false;
       }
       const stack = [];
@@ -56074,16 +56499,16 @@ var require_axios = __commonJS({
         convertValue,
         isVisitable
       });
-      function build(value, path3) {
+      function build(value, path4) {
         if (utils$1.isUndefined(value)) return;
         if (stack.indexOf(value) !== -1) {
-          throw Error("Circular reference detected in " + path3.join("."));
+          throw Error("Circular reference detected in " + path4.join("."));
         }
         stack.push(value);
         utils$1.forEach(value, function each(el, key) {
-          const result = !(utils$1.isUndefined(el) || el === null) && visitor.call(formData, el, utils$1.isString(key) ? key.trim() : key, path3, exposedHelpers);
+          const result = !(utils$1.isUndefined(el) || el === null) && visitor.call(formData, el, utils$1.isString(key) ? key.trim() : key, path4, exposedHelpers);
           if (result === true) {
-            build(el, path3 ? path3.concat(key) : [key]);
+            build(el, path4 ? path4.concat(key) : [key]);
           }
         });
         stack.pop();
@@ -56271,7 +56696,7 @@ var require_axios = __commonJS({
     };
     function toURLEncodedForm(data, options) {
       return toFormData(data, new platform2.classes.URLSearchParams(), {
-        visitor: function(value, key, path3, helpers) {
+        visitor: function(value, key, path4, helpers) {
           if (platform2.isNode && utils$1.isBuffer(value)) {
             this.append(key, value.toString("base64"));
             return false;
@@ -56299,11 +56724,11 @@ var require_axios = __commonJS({
       return obj;
     }
     function formDataToJSON(formData) {
-      function buildPath(path3, value, target, index) {
-        let name = path3[index++];
+      function buildPath(path4, value, target, index) {
+        let name = path4[index++];
         if (name === "__proto__") return true;
         const isNumericKey = Number.isFinite(+name);
-        const isLast = index >= path3.length;
+        const isLast = index >= path4.length;
         name = !name && utils$1.isArray(target) ? target.length : name;
         if (isLast) {
           if (utils$1.hasOwnProp(target, name)) {
@@ -56316,7 +56741,7 @@ var require_axios = __commonJS({
         if (!target[name] || !utils$1.isObject(target[name])) {
           target[name] = [];
         }
-        const result = buildPath(path3, value, target[name], index);
+        const result = buildPath(path4, value, target[name], index);
         if (result && utils$1.isArray(target[name])) {
           target[name] = arrayToObject(target[name]);
         }
@@ -57627,9 +58052,9 @@ var require_axios = __commonJS({
           auth = urlUsername + ":" + urlPassword;
         }
         auth && headers.delete("authorization");
-        let path3;
+        let path4;
         try {
-          path3 = buildURL(
+          path4 = buildURL(
             parsed.pathname + parsed.search,
             config2.params,
             config2.paramsSerializer
@@ -57647,7 +58072,7 @@ var require_axios = __commonJS({
           false
         );
         const options = {
-          path: path3,
+          path: path4,
           method,
           headers: headers.toJSON(),
           agents: { http: config2.httpAgent, https: config2.httpsAgent },
@@ -57892,14 +58317,14 @@ var require_axios = __commonJS({
     var cookies = platform2.hasStandardBrowserEnv ? (
       // Standard browser envs support document.cookie
       {
-        write(name, value, expires, path3, domain, secure, sameSite) {
+        write(name, value, expires, path4, domain, secure, sameSite) {
           if (typeof document === "undefined") return;
           const cookie = [`${name}=${encodeURIComponent(value)}`];
           if (utils$1.isNumber(expires)) {
             cookie.push(`expires=${new Date(expires).toUTCString()}`);
           }
-          if (utils$1.isString(path3)) {
-            cookie.push(`path=${path3}`);
+          if (utils$1.isString(path4)) {
+            cookie.push(`path=${path4}`);
           }
           if (utils$1.isString(domain)) {
             cookie.push(`domain=${domain}`);
@@ -59245,7 +59670,7 @@ var init_transformers_scanner = __esm({
           );
         }
         if (!this._pool) {
-          const workerPath = path.resolve(__dirname, "nlp_worker.js");
+          const workerPath = path2.resolve(__dirname, "nlp_worker.js");
           const maxThreads = Math.max(1, Math.min(os.cpus().length - 1, 4));
           this._pool = new Piscina({
             filename: workerPath,
@@ -59842,12 +60267,12 @@ var MaskClient = class _MaskClient {
    */
   static async create(options = {}) {
     const vault = options.vault || getVault();
-    const crypto6 = options.crypto || await getCryptoEngineAsync();
+    const crypto7 = options.crypto || await getCryptoEngineAsync();
     const scanner = options.scanner || getScanner();
     const auditLogger = options.auditLogger || getAuditLogger();
     return new _MaskClient({
       vault,
-      crypto: crypto6,
+      crypto: crypto7,
       scanner,
       auditLogger,
       ttl: options.ttl