mask-privacy 4.0.0 → 4.2.0

package/src/core/fpe.ts

@@ -1,15 +1,12 @@
 /**
- * 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.
  */
 
 import * as crypto from 'crypto';
 import { config } from '../config';
 import { getKeyProvider } from './key_provider';
 import { MaskSecurityError } from './exceptions';
+import { FF1 } from './ff1';
 import {
   FIRST_NAMES as _BIJECTIVE_NAMES,
   CONNECTORS as _BIJECTIVE_CONNECTORS,
@@ -18,32 +15,23 @@ import {
   SYLLABLES as _BIJECTIVE_SYLLABLES
 } from './synthesisLibrary';
 
-
-// Master key management
-
 let _masterKey: Buffer | null = null;
 
-/** Return the HMAC master key, lazily initialised from the key provider. */
 async function _getMasterKey(): Promise<Buffer> {
   if (_masterKey === null) {
     const provider = getKeyProvider();
     let raw = await provider.getMasterKey();
     
     if (!raw) {
-      // Fallback to encryption key if no master key is set
       raw = await provider.getEncryptionKey() || "";
     }
 
     if (!raw) {
       if (config.MASK_DEV_MODE) {
-        // Auto-generate a session-local key (non-persistent)
         raw = crypto.randomBytes(32).toString('hex');
-        // Update process.env for any other legacy paths that might check it
         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');
@@ -51,149 +39,71 @@ async function _getMasterKey(): Promise<Buffer> {
   return _masterKey;
 }
 
-/** Clear the cached master key. Useful in tests. */
 export function resetMasterKey(): void {
   _masterKey = null;
 }
 
-// Detectors — order matters: first match wins
+async function _getAesKey(): Promise<Buffer> {
+  // Salt the derivation with the tenant ID to guarantee per-tenant FF1
+  // uniqueness — two tenants with the same plaintext must never produce
+  // the same FPE token (cross-tenant collision prevention).
+  const masterKey = await _getMasterKey();
+  return crypto.createHmac('sha256', masterKey).update(config.MASK_TENANT_ID, 'utf-8').digest();
+}
 
 const _EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
 const _PHONE_RE = /(?<!\d)(?:\+?1?[\s\-.]?\(?\d{3}\)?[\s\-.]?\d{3}[\s\-.]?\d{4}|\d{3}[\s\-.]?\d{4}|\+\d{2,3}[\s\-.]?\d{3}[\s\-.]?\d{3}[\s\-.]?\d{3,4})(?!\d)/;
-const _PHONE_INTL_RE = /(?<!\d)\+(?:[1-9]\d{0,3})[-.\s]?\(?\d{1,5}\)?(?:[-.\s]?\d{2,4}){2,4}(?!\d)/;
 const _SSN_RE = /^\d{3}-\d{2}-\d{4}$/;
 const _CC_RE = /^(?:\d{4}[ \-]?){3}\d{4}$/;
 const _ROUTING_RE = /^\d{9}$/;
 const _ES_ID_RE = /^(?:\d{8}[A-Z]|[XYZ]\d{7}[A-Z])$/;
 const _IBAN_RE = /^[A-Z]{2}\d{2}[A-Z0-9]{4,30}$/;
 
-// Deterministic helpers (HMAC-based)
-
-/** Return *n* deterministic hex characters derived from HMAC(key, plaintext). */
 async function _hmacHex(plaintext: string, n: number = 8): Promise<string> {
   const masterKey = await _getMasterKey();
-  const digest = crypto
-    .createHmac('sha256', masterKey)
-    .update(plaintext, 'utf-8')
-    .digest('hex');
+  const digest = crypto.createHmac('sha256', masterKey).update(plaintext, 'utf-8').digest('hex');
   return digest.slice(0, n);
 }
 
-/**
- * Return a deterministic 128-bit BigInt from HMAC(key, plaintext).
- *
- * Uses the first 16 bytes (128 bits) of the SHA-256 HMAC digest,
- * providing a namespace of 2^128 (~3.4 × 10^38). This replaces the
- * old nibble-by-nibble modulo-10 approach which suffered from severe
- * distribution bias in short fields (3-4 digits).
- */
-async function _hmacInt(plaintext: string): Promise<bigint> {
-  const masterKey = await _getMasterKey();
-  const raw = crypto
-    .createHmac('sha256', masterKey)
-    .update(plaintext, 'utf-8')
-    .digest();
-  // Read first 16 bytes as a big-endian unsigned integer
-  let result = 0n;
-  for (let i = 0; i < 16; i++) {
-    result = (result << 8n) | BigInt(raw[i]);
-  }
-  return result;
-}
-
-/**
- * Return *n* deterministic decimal digits from HMAC(key, plaintext).
- *
- * Uses full-integer division of a 128-bit HMAC-derived seed instead of
- * per-nibble modulo-10, which eliminates the distribution bias that
- * caused collisions in short numeric fields (routing numbers, SSN
- * suffixes). The offset parameter salts the input to derive
- * independent digit sequences from the same plaintext.
- */
-async function _hmacDigits(plaintext: string, n: number, offset: number = 0): Promise<string> {
-  const salted = offset ? `${plaintext}::${offset}` : plaintext;
-  const seed = await _hmacInt(salted);
-  const modulus = 10n ** BigInt(n);
-  return (seed % modulus).toString().padStart(n, '0');
-}
-
 // ── Bijective Synthesis Engine ─────────────────────────────────────────────
 
-export class FF1 {
-  /** NIST SP 800-38G FF1 implementation (simplified for 64-bit domains). */
-  constructor(private key: Buffer, private tweak: Buffer) {}
-
-  encrypt(n: bigint): bigint {
-    /** Encrypts 64-bit bigint n using FF1 (10 rounds). */
-    let A = n >> 32n;
-    let B = n & 0xFFFFFFFFn;
-    const radix = 2n ** 32n;
-
-    for (let i = 0; i < 10; i++) {
-      const tweakInfoBuffer = Buffer.alloc(8);
-      tweakInfoBuffer.writeUInt32BE(i, 0);
-      tweakInfoBuffer.writeUInt32BE(Number(B), 4);
-      const tweakInfoCombined = Buffer.concat([this.tweak, tweakInfoBuffer]);
-
-      const h = crypto.createHmac('sha256', this.key)
-        .update(tweakInfoCombined)
-        .digest();
-      
-      const roundVal = BigInt(h.readUInt32BE(0));
-
-      const Anext = B;
-      const Bnext = (A + roundVal) % radix;
-      A = Anext;
-      B = Bnext;
-    }
-
-    return (A << 32n) | B;
-  }
-
-  decrypt(n: bigint): bigint {
-    /** Decrypts 64-bit bigint n using FF1 (10 rounds in reverse). */
-    let A = n >> 32n;
-    let B = n & 0xFFFFFFFFn;
-    const radix = 2n ** 32n;
-
-    for (let i = 9; i >= 0; i--) {
-      const tweakInfoBuffer = Buffer.alloc(8);
-      tweakInfoBuffer.writeUInt32BE(i, 0);
-      tweakInfoBuffer.writeUInt32BE(Number(A), 4);
-      const tweakInfoCombined = Buffer.concat([this.tweak, tweakInfoBuffer]);
-
-      const h = crypto.createHmac('sha256', this.key)
-        .update(tweakInfoCombined)
-        .digest();
-      
-      const roundVal = BigInt(h.readUInt32BE(0));
-
-      const Bprev = A;
-      const Aprev = (B - roundVal + radix) % radix;
-      A = Aprev;
-      B = Bprev;
-    }
-
-    return (A << 32n) | B;
-  }
-}
-
 async function _getBijectiveTweak(): Promise<Buffer> {
-  const masterKey = await _getMasterKey();
-  let base = config.MASK_TENANT_ID;
+  /**
+   * Derive the FF1 tweak deterministically from the tenant ID.
+   *
+   * IMPORTANT: The tweak is intentionally time-independent. Historical use of
+   * MASK_SALT_ROTATION (MONTHLY/YEARLY) caused permanent data loss when the
+   * calendar rolled over because old tokens could no longer be re-derived.
+   * Use MASK_KEYRING for key rotation instead; MASK_SALT_ROTATION is now a
+   * no-op and will emit a console.warn if set to a non-NONE value.
+   */
   if (config.MASK_SALT_ROTATION !== 'NONE') {
-    const now = 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 crypto.createHmac('sha256', masterKey).update(base, 'utf-8').digest();
+  const masterKey = await _getMasterKey();
+  return crypto.createHmac('sha256', masterKey).update(config.MASK_TENANT_ID, 'utf-8').digest();
+}
+
+async function _encryptBijectiveFF1(text: string): Promise<bigint> {
+  const canonical = text.toLowerCase().trim();
+  const hash = crypto.createHash('sha256').update(canonical, 'utf-8').digest();
+  // Hash to 64-bit int, then to 20-digit string
+  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: bigint): string {
-  /** Render a 64-bit cipher into a human-readable name (Bijective Synthesis). */
   const firstIdx = Number(bits & 0x7FFn);          // 11 bits (2048)
   const connIdx = Number((bits >> 11n) & 0x3Fn);    // 6 bits (64)
   const rootIdx = Number((bits >> 17n) & 0xFFFn);    // 12 bits (4096)
@@ -210,7 +120,6 @@ function _renderBijectivePerson(bits: bigint): string {
 
   const paddedNumeric = numeric.toString().padStart(4, '0');
 
-  // Format Shuffle
   if (formatIdx === 0) return `${first} ${conn} ${surname}-${paddedNumeric}`;
   if (formatIdx === 1) return `${surname}, ${first}-${paddedNumeric}`;
   if (formatIdx === 2) return `${first[0]}. ${surname}-${paddedNumeric}`;
@@ -220,7 +129,6 @@ function _renderBijectivePerson(bits: bigint): string {
 }
 
 function _renderBijectiveLocation(bits: bigint): string {
-  /** Render a 64-bit cipher into a bijective location name. */
   const s1 = Number(bits & 0x3FFn);
   const s2 = Number((bits >> 10n) & 0x3FFn);
   const s3 = Number((bits >> 20n) & 0x3FFn);
@@ -230,17 +138,6 @@ function _renderBijectiveLocation(bits: bigint): string {
   return `${city}-${tag.toString().padStart(3, '0')}`;
 }
 
-// ── Legacy Semantic Token Banks (Redirected in Bijective Mode) ──────────────
-// Seed lists are imported from semanticBanks.ts, maintaining architecture
-// parity with python/semantic_banks.py
-
-/** Return a deterministic item from an array using full 128-bit entropy. */
-async function _pickFromArray(plaintext: string, array: string[]): Promise<string> {
-   const seed = await _hmacInt(plaintext);
-   return array[Number(seed % BigInt(array.length))];
-}
-
-/** Compute Luhn check digit */
 function _computeLuhnDigit(partialNum: string): string {
     const digits = partialNum.split("").map(Number);
     let sum = 0;
@@ -257,18 +154,15 @@ function _computeLuhnDigit(partialNum: string): string {
     return ((10 - (sum % 10)) % 10).toString();
 }
 
-
-
 function _computeEsIdCheck(num: number): string {
   return "TRWAGMYFPDXBNJZSQVHLCKE"[num % 23];
 }
 
-// Public API
+function _stripCcSeparators(text: string): string {
+  return text.replace(/[\s\-]/g, '');
+}
 
-/**
- * Return a **deterministic**, format-preserving token for rawText using its entityType.
- */
-export async function generateFPEToken(rawText: string, entityType: string = 'UNKNOWN'): Promise<string> {
+export async function generateDPToken(rawText: string, entityType: string = 'UNKNOWN'): Promise<string> {
   const text = rawText.trim();
   let type = (entityType || "UNKNOWN").toUpperCase();
 
@@ -291,22 +185,52 @@ export async function generateFPEToken(rawText: string, entityType: string = 'UN
   if (type === "PHONE_NUMBER" || type === "PHONE_NUM" || type === "PHONE_NUM_INTL") {
     const m = text.match(/^\+([1-9]\d{0,3})/);
     const cc = m ? m[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") {
@@ -315,31 +239,27 @@ export async function generateFPEToken(rawText: string, entityType: string = 'UN
   }
 
   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 = crypto.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 = crypto.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)}]`;
   }
@@ -350,4 +270,6 @@ export async function generateFPEToken(rawText: string, entityType: string = 'UN
   return `[TKN-${await _hmacHex(text)}]`;
 }
 
+export const generateFPEToken = generateDPToken;
+
 export * from './fpe_utils';

package/src/core/fpe_utils.ts

@@ -12,14 +12,14 @@
 export const TOKEN_PATTERN = new RegExp(
   "tkn-[a-f0-9]{8,64}@[A-Za-z0-9.\\-]+\\.[A-Za-z]{2,}" +            // Email
   "|\\+[1-9]\\d{0,3}-555-\\d{7}" +                                 // Phone
-  "|000-00-\\d{4}" +                                               // SSN
-  "|4000-0000-0000-\\d{4}" +                                       // CC
-  "|000000\\d{3}" +                                                // Routing
-  "|000\\d{5}[A-Z]" +                                              // Spanish DNI token
+  "|\\d{3}-\\d{2}-\\d{4}" +                                        // SSN
+  "|\\d{4}-\\d{4}-\\d{4}-\\d{4}" +                                 // CC
+  "|\\b\\d{9}\\b" +                                                // Routing
+  "|\\b000\\d{5}[A-Z]\\b" +                                        // Spanish DNI token
   "|[A-Z]{2}00[A-F0-9]{4,16}" +                                    // IBAN token
   "|<(?:PER|LOC|ORG):[^>]+>" +                                     // NLP Semantic tokens V4
   "|\\b[A-Z][a-zA-Z, ]+-[0-9]{3,4}\\b" +                           // Bijective Name/Loc
-  "|\\\\[TKN-[a-f0-9]{8,64}\\\\]",                                 // Opaque
+  "|\\[TKN-[^\\]]+\\]",                                            // Opaque
   "g"
 );
 
@@ -43,18 +43,18 @@ export function looksLikeToken(value: string | any): boolean {
     return true;
   }
 
-  // SSN tokens: 000-00-XXXX
-  if (v.startsWith("000-00-") && v.length === 11) {
+  // SSN tokens: XXX-XX-XXXX
+  if (/^\d{3}-\d{2}-\d{4}$/.test(v)) {
     return true;
   }
 
-  // Credit card tokens: 4000-0000-0000-XXXX
-  if (v.startsWith("4000-0000-0000-") && v.length === 19) {
+  // Credit card tokens: XXXX-XXXX-XXXX-XXXX
+  if (/^\d{4}-\d{4}-\d{4}-\d{4}$/.test(v)) {
     return true;
   }
 
-  // Routing tokens: 000000XXX
-  if (v.startsWith("000000") && v.length === 9) {
+  // Routing tokens: XXXXXXXXX
+  if (v.length === 9 && /^\d+$/.test(v)) {
     return true;
   }
 
@@ -92,4 +92,50 @@ export function looksLikeToken(value: string | any): boolean {
   return false;
 }
 
+/**
+ * Strict token check safe for use inside audit log redaction (_deepMask).
+ *
+ * Unlike looksLikeToken(), this function excludes patterns that are AMBIGUOUS
+ * with real sensitive data (raw Credit Card and SSN formats). It only returns
+ * true when the value carries an unambiguous FPE watermark that real PII
+ * cannot share.
+ *
+ * This prevents real PANs / SSNs from bypassing redaction and being written
+ * to SOC 2 / HIPAA audit logs in plaintext — a PCI DSS Level 1 failure.
+ */
+export function isUnambiguouslySafeToken(value: string | any): boolean {
+  if (typeof value !== 'string') return false;
+  const v = value.trim();
 
+  // Email FPE token: tkn-<hex>@domain.tld
+  if (v.startsWith("tkn-") && v.includes("@")) {
+    const parts = v.split("@");
+    if (parts.length === 2 && parts[0].length >= 12 && parts[1].includes(".")) {
+      return true;
+    }
+  }
+
+  // Phone FPE token: +CC-555-XXXXXXX  (555 exchange is synthetic watermark)
+  if (/^\+[1-9]\d{0,3}-555-\d{7}$/.test(v)) return true;
+
+  // Spanish DNI FPE token: always starts 000 (real DNIs never start 000)
+  if (/^000\d{5}[A-Z]$/.test(v)) return true;
+
+  // IBAN FPE token: XX00... (real IBANs never have 00 as check digits)
+  if (/^[A-Z]{2}00[A-F0-9]{4,16}$/.test(v)) return true;
+
+  // Semantic NLP tokens: <PER:...>, <LOC:...>, <ORG:...>
+  if (/^<(PER|LOC|ORG):[^>]+>$/.test(v)) return true;
+
+  // Opaque fallback tokens: [TKN-...]
+  if (v.startsWith("[TKN-") && v.endsWith("]")) return true;
+
+  // Bijective Name/Location tokens: always end -DDDD (synthetic pattern)
+  if (/^[A-Z][a-zA-Z, ]+-[0-9]{3,4}$/.test(v)) return true;
+
+  // NOTE: Raw SSN (\d{3}-\d{2}-\d{4}), CC (\d{4}-\d{4}-\d{4}-\d{4}),
+  // and routing (\d{9}) patterns are intentionally EXCLUDED because real
+  // PII shares these exact formats. Use looksLikeToken() only for
+  // detokenization (where context guarantees a token is present).
+  return false;
+}

package/src/core/key_provider.ts

@@ -33,6 +33,17 @@ export abstract class BaseKeyProvider {
 
   /** Return the HMAC master key, or null to auto-generate. */
   abstract getMasterKey(): Promise<string | null> | string | null;
+
+  /**
+   * 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(): Promise<string | null> | string | null {
+    return null;
+  }
 }
 
 /**
@@ -58,6 +69,11 @@ export class EnvKeyProvider extends BaseKeyProvider {
     let key = config.MASK_MASTER_KEY;
     return key || null;
   }
+
+  /** Return MASK_KEYRING from environment (default behaviour). */
+  async getKeyring(): Promise<string | null> {
+    return config.MASK_KEYRING || null;
+  }
 }
 
 /**
@@ -141,6 +157,30 @@ export class AwsKmsKeyProvider extends BaseKeyProvider {
   async getMasterKey(): Promise<string | null> {
     return await this.getEncryptionKey();
   }
+
+  /**
+   * Retrieve the JSON keyring from AWS Secrets Manager.
+   *
+   * If MASK_KEYRING_SECRET_ID is set, this provider fetches the full JSON
+   * keyring document from Secrets Manager, enabling zero-downtime key
+   * rotation without writing key material to environment variables.
+   */
+  async getKeyring(): Promise<string | null> {
+    const secretId = process.env.MASK_KEYRING_SECRET_ID;
+    if (!secretId) return null;
+    try {
+      const { GetSecretValueCommand } = require('@aws-sdk/client-secrets-manager');
+      const client = await this._getSecretsClient();
+      const response = await client.send(new GetSecretValueCommand({ SecretId: secretId }));
+      const keyringStr = response.SecretString;
+      if (!keyringStr) throw new Error('MASK_KEYRING_SECRET_ID returned an empty secret.');
+      console.info(`Keyring loaded from AWS Secrets Manager (secret: ${secretId})`);
+      return keyringStr;
+    } catch (e) {
+      console.error('Failed to retrieve keyring from AWS Secrets Manager:', e);
+      throw e;
+    }
+  }
 }
 
 /**
@@ -176,6 +216,25 @@ export class AzureKeyVaultProvider extends BaseKeyProvider {
   async getMasterKey(): Promise<string | null> {
     return await this.getEncryptionKey();
   }
+
+  /**
+   * Retrieve the JSON keyring from Azure Key Vault.
+   * Looks for a secret named `<secretName>-keyring`.
+   */
+  async getKeyring(): Promise<string | null> {
+    const keyringSecretName = this.secretName + '-keyring';
+    try {
+      const client = await this._getClient();
+      const secret = await client.getSecret(keyringSecretName);
+      if (secret.value) {
+        console.info(`Keyring loaded from Azure Key Vault (secret: ${keyringSecretName})`);
+        return secret.value;
+      }
+    } catch {
+      // Secret may not exist; fall back to env
+    }
+    return null;
+  }
 }
 
 /**
@@ -207,6 +266,27 @@ export class HashiCorpVaultProvider extends BaseKeyProvider {
   async getMasterKey(): Promise<string | null> {
     return await this.getEncryptionKey();
   }
+
+  /**
+   * Retrieve the JSON keyring from HashiCorp Vault.
+   * Looks for a `keyring` key in the secret at `secretPath`.
+   */
+  async getKeyring(): Promise<string | null> {
+    try {
+      const axios = require('axios');
+      const url = `${this.vaultAddr}/v1/${this.secretPath}`;
+      const response = await axios.get(url, { headers: { 'X-Vault-Token': this._token } });
+      const data = response.data?.data?.data || response.data?.data;
+      const keyringStr = data?.keyring;
+      if (keyringStr) {
+        console.info(`Keyring loaded from HashiCorp Vault (path: ${this.secretPath})`);
+        return keyringStr;
+      }
+    } catch (e) {
+      console.error('HashiCorp Vault keyring retrieval failed:', e);
+    }
+    return null;
+  }
 }
 
 // Singleton accessor