mask-privacy 3.5.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mask-privacy",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "description": "Enterprise-grade AI Data Loss Prevention (DLP) SDK for TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/config.ts

@@ -36,6 +36,11 @@ export const config = {
   get MASK_DEV_MODE() { return getEnvBool('MASK_DEV_MODE', false); },
   get MASK_LOG_LEVEL() { return (process.env.MASK_LOG_LEVEL || 'info').toLowerCase(); },
 
+  // --- COMPLIANCE & PRIVACY (Bijective) ---
+  get MASK_TENANT_ID() { return process.env.MASK_TENANT_ID || 'global-default-tenant'; },
+  get MASK_SALT_ROTATION() { return (process.env.MASK_SALT_ROTATION || 'NONE').toUpperCase(); },
+  get MASK_BIJECTIVE_MODE() { return getEnvBool('MASK_BIJECTIVE_MODE', true); },
+
   // --- SECURITY & CRYPTOGRAPHY ---
   get MASK_ENCRYPTION_KEY() { return process.env.MASK_ENCRYPTION_KEY || null; },
   get MASK_MASTER_KEY() { 

package/src/core/dlp/registry.ts

@@ -35,6 +35,8 @@ export interface PatternDescriptor {
   validatorTag: string | null;
   isHighEntropy: boolean;
   supportedLocales: string[];
+  ruleId: string;                         // Unique ID for compliance audit trail
+  complianceScope: ReadonlySet<string>;    // Compliance frameworks: {"PCI-DSS", "HIPAA", ...}
 }
 
 // ── Locale-specific auxiliary patterns ──────────────────────────────────────
@@ -71,6 +73,8 @@ type RawEntry = [
   validatorTag: string | null,
   isHighEntropy?: boolean,
   supportedLocales?: string[],
+  ruleId?: string,
+  complianceScope?: string[],
 ];
 
 const RAW_PATTERNS: RawEntry[] = [
@@ -291,7 +295,7 @@ export class DLPPatternRegistry {
 
   private buildCatalogue(restrict: ReadonlySet<SensitiveCategory> | null): void {
     for (const entry of RAW_PATTERNS) {
-      const [typeName, regexSource, terms, risk, cat, vtag, isHighEntropy, supportedLocales] = entry;
+      const [typeName, regexSource, terms, risk, cat, vtag, isHighEntropy, supportedLocales, ruleId, complianceScope] = entry;
       if (restrict !== null && !restrict.has(cat)) continue;
 
       let re: RegExp;
@@ -309,6 +313,8 @@ export class DLPPatternRegistry {
         validatorTag: vtag,
         isHighEntropy: isHighEntropy ?? (vtag !== null),
         supportedLocales: supportedLocales ?? ["*"],
+        ruleId: ruleId ?? `MASK-${cat.slice(0, 3)}-${typeName}`,
+        complianceScope: new Set(complianceScope ?? []),
       });
     }
   }

package/src/core/fpe.ts

@@ -10,6 +10,14 @@ import * as crypto from 'crypto';
 import { config } from '../config';
 import { getKeyProvider } from './key_provider';
 import { MaskSecurityError } from './exceptions';
+import {
+  FIRST_NAMES as _BIJECTIVE_NAMES,
+  CONNECTORS as _BIJECTIVE_CONNECTORS,
+  SURNAME_ROOTS as _BIJECTIVE_ROOTS,
+  SURNAME_SUFFIXES as _BIJECTIVE_SUFFIXES,
+  SYLLABLES as _BIJECTIVE_SYLLABLES
+} from './synthesisLibrary';
+
 
 // Master key management
 
@@ -51,7 +59,7 @@ export function resetMasterKey(): void {
 // Detectors — order matters: first match wins
 
 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)/;
+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}$/;
@@ -71,39 +79,165 @@ async function _hmacHex(plaintext: string, n: number = 8): Promise<string> {
   return digest.slice(0, n);
 }
 
-/** Return *n* deterministic decimal digits derived from HMAC(key, plaintext). */
-async function _hmacDigits(plaintext: string, n: number, offset: number = 0): Promise<string> {
+/**
+ * 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 digest = crypto
+  const raw = crypto
     .createHmac('sha256', masterKey)
     .update(plaintext, 'utf-8')
-    .digest('hex');
+    .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');
+}
 
-  const result: string[] = [];
-  for (let i = offset; i < digest.length; i++) {
-    const ch = digest[i];
-    result.push((parseInt(ch, 16) % 10).toString());
-    if (result.length === n) break;
+// ── 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;
   }
 
-  while (result.length < n) {
-    result.push("0");
+  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;
   }
-  return result.join("");
 }
 
-// Public API
+async function _getBijectiveTweak(): Promise<Buffer> {
+  const masterKey = await _getMasterKey();
+  let base = config.MASK_TENANT_ID;
+  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()}`;
+    }
+  }
+  return crypto.createHmac('sha256', masterKey).update(base, 'utf-8').digest();
+}
 
-// Dictionary for Semantic NLP Faker Generation
-const _FIRST_NAMES = ["Taylor", "Jordan", "Casey", "Morgan", "Riley", "Avery", "Rowan", "Quinn", "Charlie", "Peyton", "Blake", "Dakota", "Reese", "Skyler", "Finley", "Eden", "Harley", "Rory", "Emerson", "Remi"];
-const _LAST_NAMES = ["Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis", "Rodriguez", "Martinez", "Hernandez", "Lopez", "Gonzalez", "Wilson", "Anderson", "Thomas", "Taylor", "Moore", "Jackson", "Martin"];
-const _CITIES = ["London", "Paris", "Berlin", "Tokyo", "Rome", "Madrid", "Vienna", "Sydney", "Toronto", "Chicago", "Seattle", "Austin", "Boston", "Denver", "Dallas", "Miami", "Seoul", "Dubai", "Mumbai", "Cairo"];
+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)
+  const suffixIdx = Number((bits >> 29n) & 0x1FFn); // 9 bits (512)
+  const tag = Number((bits >> 38n) & 0x3FFFn);      // 14 bits (16384)
+  const formatIdx = Number((bits >> 52n) & 0xFn);   // 4 bits (16)
+
+  const first = _BIJECTIVE_NAMES[firstIdx % _BIJECTIVE_NAMES.length];
+  const conn = _BIJECTIVE_CONNECTORS[connIdx % _BIJECTIVE_CONNECTORS.length];
+  const root = _BIJECTIVE_ROOTS[rootIdx % _BIJECTIVE_ROOTS.length];
+  const suffix = _BIJECTIVE_SUFFIXES[suffixIdx % _BIJECTIVE_SUFFIXES.length];
+  const surname = `${root}${suffix}`;
+  const numeric = tag % 10000;
+
+  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}`;
+  if (formatIdx === 3) return `${first} ${surname}-${paddedNumeric}`;
+  
+  return `${first} ${surname}-${paddedNumeric}`;
+}
+
+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);
+  const tag = Number((bits >> 30n) & 0xFFFn);
+
+  const city = `${_BIJECTIVE_SYLLABLES[s1 % 1000]}${_BIJECTIVE_SYLLABLES[s2 % 1000].toLowerCase()}${_BIJECTIVE_SYLLABLES[s3 % 1000].toLowerCase()}`;
+  return `${city}-${tag.toString().padStart(3, '0')}`;
+}
 
-/** Return a deterministic item from an array. */
+// ── 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 digits = await _hmacDigits(plaintext, 8);
-   const num = parseInt(digits, 10);
-   return array[num % array.length];
+   const seed = await _hmacInt(plaintext);
+   return array[Number(seed % BigInt(array.length))];
 }
 
 /** Compute Luhn check digit */
@@ -143,7 +277,7 @@ export async function generateFPEToken(rawText: string, entityType: string = 'UN
     else if (_SSN_RE.test(text)) type = "US_SSN";
     else if (_CC_RE.test(text)) type = "CREDIT_CARD";
     else if (_ROUTING_RE.test(text)) type = "US_ROUTING_NUMBER";
-    else if (_ES_ID_RE.test(text)) type = "ES_DNI";
+    else if (_ES_ID_RE.test(text)) type = "ES_ID";
     else if (_IBAN_RE.test(text)) type = "INTL_BANK_IBAN";
     else if (_PHONE_RE.test(text)) type = "PHONE_NUMBER";
   }
@@ -180,23 +314,37 @@ export async function generateFPEToken(rawText: string, entityType: string = 'UN
     return `${countryCode}00${(await _hmacHex(text, 8)).toUpperCase()}`;
   }
 
-  if (type === "ES_DNI") {
+  if (type === "ES_ID" || type === "ES_DNI") {
     const digits = `000${await _hmacDigits(text, 5)}`;
     return digits + _computeEsIdCheck(parseInt(digits, 10));
   }
 
   if (type === "PERSON" || type === "PERSON_NAME") {
-      const f = await _pickFromArray(text, _FIRST_NAMES);
-      const l = await _pickFromArray(text + "last", _LAST_NAMES);
-      return `<PER:${f}_${l}>`;
+      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);
+      }
+      return `[TKN-PERSON-${await _hmacHex(text)}]`;
   }
   if (type === "LOCATION" || type === "PHYS_ADDRESS") {
-      const c = await _pickFromArray(text, _CITIES);
-      return `<LOC:${c}>`;
+      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);
+      }
+      return `[TKN-LOC-${await _hmacHex(text)}]`;
   }
   if (type === "ORGANIZATION") {
-      const c = await _pickFromArray(text, _LAST_NAMES);
-      return `<ORG:${c}_Inc>`;
+      return `[TKN-ORG-${await _hmacHex(text)}]`;
   }
 
   return `[TKN-${await _hmacHex(text)}]`;

package/src/core/fpe_utils.ts

@@ -11,14 +11,15 @@
  */
 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
-  "|[A-Z]{2}00[A-F0-9]{4,16}" +                // IBAN token
-  "|<(?:PER|LOC|ORG):[^>]+>" +                 // NLP Semantic tokens
-  "|\\[TKN-[a-f0-9]{8,64}\\]",                  // Opaque
+  "|\\+[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
+  "|[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
   "g"
 );
 
@@ -78,6 +79,15 @@ export function looksLikeToken(value: string | any): boolean {
   if (v.startsWith("[TKN-") && v.endsWith("]")) {
     return true;
   }
+  
+  // Bijective Name: Word Word-1234
+  if (v.includes("-") && v.length >= 6) {
+    const parts = v.split("-");
+    const tag = parts[parts.length - 1];
+    if (tag.length === 4 && /^\d+$/.test(tag)) {
+        return true;
+    }
+  }
 
   return false;
 }

package/src/core/scanner.ts

@@ -132,7 +132,8 @@ export class BaseScanner {
           if (conf >= confidenceThreshold) {
             spans.push({ start: m.index, end: m.index + matchedStr.length,
               entityType: typeTag, originalValue: matchedStr,
-              confidence: conf, method: 'dlp_heuristic', language: detectedLanguage });
+              confidence: conf, method: 'dlp_heuristic', language: detectedLanguage,
+              ruleId: descriptor.ruleId, complianceScope: descriptor.complianceScope });
           }
         }
       }

package/src/core/span.ts

@@ -14,6 +14,9 @@ export interface Span {
   confidence: number;
   method: string;      // "dlp_heuristic" | "regex" | "nlp"
   language?: string;
+  // Audit trail fields (DSPM compliance)
+  ruleId?: string;                 // e.g. "MASK-FIN-001"
+  complianceScope?: ReadonlySet<string>;  // e.g. {"PCI-DSS", "HIPAA"}
   maskedValue?: string;
 }
 

package/src/core/synthesisLibrary.ts

@@ -0,0 +1,41 @@
+/**
+ * Synthesis Library — Identical components to the Python SDK.
+ */
+
+export const FIRST_NAMES: string[] = [
+    "James", "Mary", "Robert", "Patricia", "John", "Jennifer", "Michael", "Linda",
+    "David", "Elizabeth", "William", "Barbara", "Richard", "Susan", "Joseph", "Jessica"
+];
+while (FIRST_NAMES.length < 2048) { FIRST_NAMES.push(`NameEx_${FIRST_NAMES.length}`); }
+
+export const CONNECTORS: string[] = [
+    "of", "from", "van", "del", "di", "von", "le", "la", "de", "el",
+    "the", "near", "at", "by", "under", "over", "across", "beyond", "within", "without",
+    "and", "with", "aka", "alias", "formally", "lately", "born", "styled", "known", "called",
+    "st", "al", "bin", "ibn", "abu", "ben", "bar", "fitz", "mac", "mc",
+    "o", "da", "dos", "das", "do", "du", "della", "degli", "dei", "delle",
+    "sur", "ter", "ten", "zu", "zum", "zur", "auf", "an", "der", "die", "das",
+    "pro", "anti", "ex", "quasi"
+];
+
+export const SURNAME_ROOTS: string[] = [
+    "Silver", "Gold", "Iron", "Stone", "Rock", "Wood", "Leaf", "Rain", "Snow", "Wind",
+    "Storm", "Cloud", "Sun", "Moon", "Star", "Sky", "Sea", "Lake", "River", "Brook",
+    "Hill", "Mount", "Vale", "Glen", "Dale", "Field", "Meadow", "Forest", "Grove", "Wild"
+];
+while (SURNAME_ROOTS.length < 4096) { SURNAME_ROOTS.push(`RootEx_${SURNAME_ROOTS.length}`); }
+
+export const SURNAME_SUFFIXES: string[] = [
+    "son", "man", "field", "wood", "berg", "stein", "ov", "ova", "ski", "ska",
+    "ez", "ez", "ia", "ic", "os", "as", "is", "us", "er", "en",
+    "ard", "ier", "eau", "oux", "ly", "ley", "ton", "don", "ham", "ford",
+    "wick", "shire", "land", "way", "side", "gate", "bridge", "well", "pool", "cliff",
+    "bank", "shore", "hart", "foot", "head", "more", "less", "ness", "ship", "ward"
+];
+while (SURNAME_SUFFIXES.length < 512) { SURNAME_SUFFIXES.push(`SuffixEx_${SURNAME_SUFFIXES.length}`); }
+
+export const SYLLABLES: string[] = [
+    "San", "Ver", "Dina", "Lon", "Don", "Chi", "Ca", "Go", "New", "York",
+    "Los", "An", "Ge", "Les", "Pa", "Ris", "Ber", "Lin", "Mad", "Rid"
+];
+while (SYLLABLES.length < 1000) { SYLLABLES.push(`Syl_${SYLLABLES.length}`); }

package/src/index.ts

@@ -6,7 +6,7 @@
  * and framework-agnostic tool interception hooks.
  */
 
-export const VERSION = "3.5.0";
+export const VERSION = "3.5.1";
 
 export {
     getVault,

package/src/telemetry/audit_logger.ts

@@ -200,7 +200,9 @@ export class AuditLogger {
             this._bufferFullWarned = false;
 
             for (const evt of events) {
-                console.info(JSON.stringify(evt));
+                // Use a replacer to handle BigInt values which are not JSON-serializable by default
+                const json = JSON.stringify(evt, (_, v) => typeof v === 'bigint' ? v.toString() : v);
+                console.info(json);
             }
         } finally {
             this._isFlushing = false;

package/tests/bijective_fpe.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { generateFPEToken, resetMasterKey, FF1 } from '../src/core/fpe';
+import { config } from '../src/config';
+import * as process from 'process';
+import * as crypto from 'crypto';
+
+describe('BijectiveFPEIntegration', () => {
+  const TEST_KEY = "fixed-test-key-for-bijective-proof";
+  const TENANT_ID = "tenant-a";
+
+  let originalBijective: string | undefined;
+  let originalTenant: string | undefined;
+
+  beforeEach(() => {
+    resetMasterKey();
+    originalBijective = process.env.MASK_BIJECTIVE_MODE;
+    originalTenant = process.env.MASK_TENANT_ID;
+    
+    process.env.MASK_BIJECTIVE_MODE = "true";
+    process.env.MASK_MASTER_KEY = TEST_KEY;
+    process.env.MASK_TENANT_ID = TENANT_ID;
+  });
+
+  afterEach(() => {
+    resetMasterKey();
+    if (originalBijective === undefined) delete process.env.MASK_BIJECTIVE_MODE;
+    else process.env.MASK_BIJECTIVE_MODE = originalBijective;
+    
+    if (originalTenant === undefined) delete process.env.MASK_TENANT_ID;
+    else process.env.MASK_TENANT_ID = originalTenant;
+  });
+
+  test('test_ff1_bijective_property', async () => {
+    /** Verify that FF1 is a true bijection (decrypt(encrypt(x)) == x). */
+    const masterKeyFull = Buffer.from(TEST_KEY, 'utf-8');
+    const masterKey16 = masterKeyFull.slice(0, 16);
+    const tenantTweak = crypto.createHmac('sha256', masterKeyFull).update(TENANT_ID, 'utf-8').digest();
+    
+    const engine = new FF1(masterKey16, tenantTweak);
+    
+    const testValues = [
+      0n, 1n, 100n, BigInt(2**31 - 1), BigInt(2**32), BigInt(2**32 + 1),
+      (1n << 63n) - 1n, (1n << 64n) - 1n,
+      1234567890123456789n
+    ];
+    
+    for (const val of testValues) {
+      const cipher = engine.encrypt(val);
+      const decrypted = engine.decrypt(cipher);
+      expect(decrypted).toBe(val);
+    }
+  });
+
+  test('test_cross_sdk_parity_golden_vector', async () => {
+    /** 
+     * Verify bit-for-bit parity with Python implementation.
+     * Input 0 with TEST_KEY and TENANT_ID should match exactly.
+     */
+    const masterKeyFull = Buffer.from(TEST_KEY, 'utf-8');
+    const masterKey16 = masterKeyFull.slice(0, 16);
+    const tenantTweak = crypto.createHmac('sha256', masterKeyFull).update(TENANT_ID, 'utf-8').digest();
+    const engine = new FF1(masterKey16, tenantTweak);
+    
+    const cipher = engine.encrypt(0n);
+    // This value matches Python output for the same test keys
+    expect(cipher.toString()).toBe("14723038793896035711");
+  });
+
+  test('test_tenant_isolation', async () => {
+    /** Verify that different tenants produce unique tokens. */
+    const name = "John Doe";
+    
+    process.env.MASK_TENANT_ID = "tenant-a";
+    const tokenA = await generateFPEToken(name, "PERSON");
+    
+    process.env.MASK_TENANT_ID = "tenant-b";
+    const tokenB = await generateFPEToken(name, "PERSON");
+    
+    expect(tokenA).not.toBe(tokenB);
+    
+    process.env.MASK_TENANT_ID = "tenant-a";
+    const tokenA2 = await generateFPEToken(name, "PERSON");
+    expect(tokenA).toBe(tokenA2);
+  });
+
+  test('test_human_readable_synthesis', async () => {
+    /** Verify synthesis pattern matches Bijective expectations. */
+    const res = await generateFPEToken("Jane Doe", "PERSON");
+    // Pattern: Name Surname-Tag (4 digits)
+    expect(res).toContain("-");
+    const parts = res.split("-");
+    expect(parts[parts.length - 1].length).toBe(4);
+  });
+
+  test('test_location_synthesis', async () => {
+    /** Verify bijective location synthesis. */
+    const res = await generateFPEToken("San Francisco", "LOCATION");
+    // Pattern: CityName-Tag (12 bits -> 3-4 digits)
+    expect(res).toContain("-");
+    const tag = res.split("-").pop()!;
+    expect(tag.length).toBeGreaterThanOrEqual(3);
+  });
+});