mask-privacy 4.0.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mask-privacy",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Enterprise-grade AI Data Loss Prevention (DLP) SDK for TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,6 +35,7 @@
     "@aws-sdk/lib-dynamodb": "^3.1012.0",
     "@huggingface/transformers": "^3.8.1",
     "@langchain/core": "^1.1.33",
+    "argon2": "^0.41.1",
     "llamaindex": "^0.12.1",
     "piscina": "^5.1.4"
   },

package/src/config.ts

@@ -43,12 +43,16 @@ export const config = {
 
   // --- SECURITY & CRYPTOGRAPHY ---
   get MASK_ENCRYPTION_KEY() { return process.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 process.env.MASK_KEYRING || null; },
   get MASK_MASTER_KEY() { 
     return process.env.MASK_MASTER_KEY || process.env.MASK_ENCRYPTION_KEY || ''; 
   },
   get MASK_ENCRYPTED_KEY() { return process.env.MASK_ENCRYPTED_KEY || null; },
   get MASK_STRICT_PROD() { return getEnvBool('MASK_STRICT_PROD', false); },
   get MASK_BLIND_INDEX_SALT() { return process.env.MASK_BLIND_INDEX_SALT || "mask-blind-index"; },
+  get MASK_KDF_SALT() { return process.env.MASK_KDF_SALT || "mask-kdf-v4-argon2id"; },
   get VAULT_TOKEN() { return process.env.VAULT_TOKEN || null; },
 
   // --- VAULT & STORAGE ---
@@ -56,6 +60,7 @@ export const config = {
   get MASK_FAIL_STRATEGY() { return (process.env.MASK_FAIL_STRATEGY || "").toLowerCase(); },
   get MASK_VAULT_TTL() { return getEnvInt('MASK_VAULT_TTL', 600); },
   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', 100_000); },
 
   // --- BACKEND CONNECTIONS ---
   get MASK_REDIS_URL() { return process.env.MASK_REDIS_URL || "redis://localhost:6379/0"; },

package/src/core/crypto.ts

@@ -1,14 +1,16 @@
 /**
  * Core cryptography engine for Mask SDK.
  *
- * Provides a CryptoEngine singleton that handles Envelope Encryption,
- * ensuring that plaintext PII is encrypted locally before being
- * transmitted and stored in distributed vaults (Redis/Memcached/DynamoDB).
+ * Supports a JSON-based Keyring for transparent key rotation:
+ *   MASK_KEYRING='{"v1":"oldkey...","v2":"newkey..."}'
+ * The *last* key in the JSON object is the active encryption key.
+ * All keys in the keyring are available for decryption (zero-downtime rotation).
  *
- * Uses AES-256-GCM (authenticated encryption) via native Node.js crypto.
- * Includes a compatibility layer to decrypt legacy Fernet-format tokens.
+ * Legacy single-key mode (MASK_ENCRYPTION_KEY) is fully mapped to key ID "default".
  *
- * Requires MASK_ENCRYPTION_KEY to be set in the environment.
+ * Ciphertext envelope format: aes:v2:{keyId}:{base64(iv+authTag+ciphertext)}
+ *
+ * Uses AES-256-GCM via native Node.js crypto and Argon2id for key derivation.
  */
 
 import { config } from '../config';
@@ -19,24 +21,32 @@ import { MaskDecryptionError } from './exceptions';
 // ---------------------------------------------------------------------------
 // AES-256-GCM constants
 // ---------------------------------------------------------------------------
-const AES_KEY_BYTES = 32;        // 256 bits
-const GCM_IV_BYTES = 12;         // 96-bit nonce (NIST recommended for GCM)
-const GCM_AUTH_TAG_BYTES = 16;   // 128-bit auth tag
+const AES_KEY_BYTES = 32;       // 256 bits
+const GCM_IV_BYTES = 12;        // 96-bit nonce (NIST recommended for GCM)
+const GCM_AUTH_TAG_BYTES = 16;  // 128-bit auth tag
 const GCM_ALGORITHM = 'aes-256-gcm';
 
-// Prefix for new AES-GCM tokens to distinguish from legacy Fernet
-const AES_GCM_PREFIX = 'aes:';
+// Envelope prefixes (in priority order for decryption)
+const AES_V2_PREFIX = 'aes:v2:';          // current: aes:v2:{keyId}:{base64}
+const AES_GCM_PREFIX = 'aes:v1:';         // legacy single-key
+const AES_GCM_LEGACY_PREFIX = 'aes:';     // oldest legacy
+
+// ---------------------------------------------------------------------------
+// Keyring type
+// ---------------------------------------------------------------------------
+type Keyring = Map<string, Buffer>; // keyId -> derived AES key
 
 export class CryptoEngine {
   private static _instance: CryptoEngine | null = null;
-  private _aesKey: Buffer | null = null;
+  private _keyring: Keyring = new Map();
+  private _activeKeyId: string = 'default';
   private _indexSecret: Buffer | null = null;
 
   private constructor() {}
 
-  /** 
+  /**
    * Return the singleton instance, initialising it if necessary.
-   * This is asynchronous because key providers (KMS, etc.) might be async.
+   * Async because Argon2id key derivation is async.
    */
   public static async getInstanceAsync(): Promise<CryptoEngine> {
     if (this._instance === null) {
@@ -54,52 +64,122 @@ export class CryptoEngine {
     return this._instance;
   }
 
-  /** Clear the singleton instance to force re-initialization (useful for key rotation). */
+  /** Clear the singleton (useful for key rotation / tests). */
   public static reset(): void {
     this._instance = null;
   }
 
+  private async _deriveAesKey(rawKey: string, keyId: string): Promise<Buffer> {
+    /**
+     * Derive a 256-bit AES key from a raw key string using Argon2id.
+     * Salt = KDF_SALT + tenant_id + key_id — unique per tenant and per key version.
+     */
+    let argon2: any;
+    try {
+      argon2 = require('argon2');
+    } catch (e) {
+      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,
+    }) as Buffer;
+  }
+
   private async _init(): Promise<void> {
     /**
-     * Initialize the AES-256-GCM engine.
-     *
-     * The encryption key is retrieved from the active KeyProvider.
-     * If no key is available, a throwaway key is auto-generated for
-     * local/test/demo use.
+     * Initialize the keyring. Loading order:
+     *  1. MASK_KEYRING (JSON): {"v1": "oldkey", "v2": "newkey"}
+     *     Last key is treated as the active key.
+     *  2. MASK_ENCRYPTION_KEY (legacy): single key mapped to ID "default".
+     *  3. Dev mode: auto-generate ephemeral key if MASK_DEV_MODE=true.
      */
+    let argon2: any;
+    try {
+      argon2 = require('argon2');
+    } catch (e) {
+      throw new Error("The 'argon2' package is required. Install with: npm install argon2");
+    }
+
     const provider = getKeyProvider();
-    const keyFromProvider = await provider.getEncryptionKey();
-    
-    let key: string;
-    if (!keyFromProvider) {
-      if (config.MASK_DEV_MODE) {
-        key = cryptoNode.randomBytes(32).toString('base64');
-        // We can't easily write back to config exports, but we can update process.env for the legacy path below
-        process.env.MASK_ENCRYPTION_KEY = key;
-        console.warn(
-          "MASK_DEV_MODE is enabled. Using a generated throwaway key. " +
-          "DO NOT USE THIS IN PRODUCTION — 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.'
-        );
+
+    // ── Build raw key map ─────────────────────────────────────────────────
+    const rawKeys: Map<string, string> = new Map();
+    let activeKeyId = 'default';
+
+    const keyringJson = await provider.getKeyring();
+    if (keyringJson) {
+      let parsed: Record<string, string>;
+      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 (e) {
+        throw new Error(`Invalid MASK_KEYRING format: ${e}`);
       }
+      const entries = Object.entries(parsed);
+      if (entries.length === 0) throw new Error('MASK_KEYRING must contain at least one key.');
+      for (const [kid, k] of entries) rawKeys.set(kid, k);
+      // Last key in JSON insertion order is the active key
+      activeKeyId = entries[entries.length - 1][0];
     } else {
-      key = keyFromProvider;
+      // Legacy single-key mode
+      const keyFromProvider = await provider.getEncryptionKey();
+      let key: string;
+      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 — 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';
     }
 
-    // Derive a 32-byte AES key from the provided key material.
-    // This normalises any key format (Fernet base64, raw base64, etc.)
-    // into a consistent 32-byte key via SHA-256 derivation.
-    this._aesKey = cryptoNode.createHash('sha256').update(key).digest();
+    // ── Derive AES-256 keys for every keyring entry ───────────────────────
+    this._keyring = new Map();
+    for (const [kid, rawKey] of rawKeys) {
+      this._keyring.set(kid, await this._deriveAesKey(rawKey, kid));
+    }
+    this._activeKeyId = activeKeyId;
 
-    // Derive a separate secret for blind indexing (HMAC-SHA256)
-    // We derive it from the master encryption key so we don't need a 3rd env var.
-    const masterKey = await provider.getMasterKey() || key;
-    const salt = config.MASK_BLIND_INDEX_SALT;
-    this._indexSecret = cryptoNode.createHmac('sha256', masterKey).update(salt).digest();
+    // ── Blind Index Secret (separate Argon2id derivation) ─────────────────
+    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,
+    }) as Buffer;
   }
 
   /** Return the secret used for HMAC-based blind indexing. */
@@ -110,75 +190,83 @@ export class CryptoEngine {
     return this._indexSecret!;
   }
 
+  /** Encrypt plaintext using the active keyring key.
+   *  Envelope format: aes:v2:{keyId}:{base64(iv+authTag+ciphertext)}
+   */
   public encrypt(plaintext: string): string {
-    /** Encrypt plaintext using AES-256-GCM. Returns prefixed base64 string. */
-    if (!this._aesKey) {
-      throw new Error("CryptoEngine not initialised. AES key missing.");
+    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, this._aesKey, iv);
-    
-    const encrypted = Buffer.concat([
-      cipher.update(plaintext, 'utf8'),
-      cipher.final()
-    ]);
+    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();
 
-    // Wire format: iv (12) + authTag (16) + ciphertext (variable)
+    // Zero out the plaintext buffer to minimise time-in-memory for sensitive data
+    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. */
   public decrypt(ciphertext: string): string {
-    /** Decrypt ciphertext. Supports both new AES-GCM and legacy Fernet formats. */
-    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)) {
+        // aes:v2:{keyId}:{base64}
+        const rest = ciphertext.slice(AES_V2_PREFIX.length);
+        const sep = rest.indexOf(':');
+        if (sep === -1) throw new Error('Malformed aes:v2 envelope: missing key ID separator.');
+        const keyId = rest.slice(0, sep);
+        const b64 = rest.slice(sep + 1);
+        return this._decryptAesGcm(keyId, b64);
+      }
+
       if (ciphertext.startsWith(AES_GCM_PREFIX)) {
-        return this._decryptAesGcm(ciphertext.slice(AES_GCM_PREFIX.length));
+        // aes:v1:{base64} — implicit key ID "default"
+        return this._decryptAesGcm('default', ciphertext.slice(AES_GCM_PREFIX.length));
       }
 
-      // Legacy path: attempt Fernet-format decryption
+      if (ciphertext.startsWith(AES_GCM_LEGACY_PREFIX)) {
+        // aes:{base64} — oldest format, implicit key ID "default"
+        return this._decryptAesGcm('default', ciphertext.slice(AES_GCM_LEGACY_PREFIX.length));
+      }
+
+      // Final fallback: legacy Fernet format
       return this._decryptLegacyFernet(ciphertext);
     } catch (e) {
-      console.error("Failed to decrypt vault payload. Check your MASK_ENCRYPTION_KEY. Inner error:", e);
+      console.error("Failed to decrypt vault payload. Check your MASK_ENCRYPTION_KEY / MASK_KEYRING. Inner error:", e);
       throw new MaskDecryptionError("Decryption failed");
     }
   }
 
-  /** Decrypt an AES-256-GCM token (base64 encoded). */
-  private _decryptAesGcm(b64: string): string {
+  private _decryptAesGcm(keyId: string, b64: string): string {
+    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");
     }
-
     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 = cryptoNode.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.
-   */
   private _decryptLegacyFernet(ciphertext: string): string {
     let fernet: any;
     try {
@@ -189,10 +277,7 @@ export class CryptoEngine {
         "Please run 'npm install fernet' to support legacy tokens."
       );
     }
-
     try {
-      // Reconstruct the original Fernet key from our AES key
-      // This won't work if the key was derived differently, but it's a best-effort compat layer
       const token = new fernet.Token({
         secret: new fernet.Secret(config.MASK_ENCRYPTION_KEY || process.env.MASK_ENCRYPTION_KEY || ''),
         token: ciphertext,
@@ -200,7 +285,6 @@ export class CryptoEngine {
       });
       return token.decode();
     } catch (e) {
-      // If decryption fails, throw to caller
       throw new MaskDecryptionError(
         "Failed to decrypt legacy Fernet token. The key may have changed or the token is corrupt."
       );

package/src/core/exceptions.ts

@@ -24,3 +24,28 @@ export class MaskNLPTimeout extends MaskError {}
 
 /** Raised when mandatory security keys (MASK_MASTER_KEY, etc.) are missing. */
 export class MaskSecurityError extends MaskError {}
+
+/**
+ * Raised when a newly generated token already maps to a *different* plaintext.
+ *
+ * This indicates a Birthday-Paradox collision in the deterministic pseudonymization
+ * engine — two distinct plaintexts produced the same token.  The vault refuses to
+ * overwrite existing PII, so the caller must handle the collision.
+ */
+export class TokenCollisionError extends MaskError {
+  public readonly token: string;
+  public readonly existingHash: string;
+  public readonly incomingHash: string;
+
+  constructor(token: string, existingHash: string, incomingHash: string) {
+    super(
+      `Token collision detected for token '${token}'. ` +
+      `Existing plaintext hash '${existingHash.slice(0, 8)}…' conflicts with ` +
+      `incoming hash '${incomingHash.slice(0, 8)}…'. ` +
+      'Increase token entropy or adjust tenant salt configuration.'
+    );
+    this.token = token;
+    this.existingHash = existingHash;
+    this.incomingHash = incomingHash;
+  }
+}

package/src/core/ff1.ts

@@ -0,0 +1,196 @@
+import * as crypto from 'crypto';
+
+export class FF1 {
+  private key: Buffer;
+  private tweak: Buffer;
+  private radix: number;
+  private chars: string = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+
+  constructor(key: Buffer, tweak: Buffer, radix: number) {
+    this.key = key;
+    this.tweak = tweak;
+    this.radix = radix;
+    if (radix > this.chars.length) {
+      throw new Error(`Radix ${radix} not supported`);
+    }
+  }
+
+  private _prf(x: Buffer): Buffer {
+    const cipher = crypto.createCipheriv('aes-256-cbc', this.key, Buffer.alloc(16, 0));
+    cipher.setAutoPadding(false);
+    return Buffer.concat([cipher.update(x), cipher.final()]).subarray(-16);
+  }
+
+  private _ciph(x: Buffer): Buffer {
+    const cipher = crypto.createCipheriv('aes-256-ecb', this.key, null);
+    cipher.setAutoPadding(false);
+    return Buffer.concat([cipher.update(x), cipher.final()]);
+  }
+
+  private _strToInt(s: string): bigint {
+    let n = 0n;
+    const r = BigInt(this.radix);
+    for (let i = 0; i < s.length; i++) {
+        n = n * r + BigInt(this.chars.indexOf(s[i]));
+    }
+    return n;
+  }
+
+  private _intToStr(num: bigint, length: number): string {
+    if (num === 0n) {
+      return this.chars[0].repeat(length);
+    }
+    let digits: string[] = [];
+    let n = num;
+    const r = BigInt(this.radix);
+    while (n > 0n) {
+      digits.push(this.chars[Number(n % r)]);
+      n /= r;
+    }
+    let s = digits.reverse().join('');
+    while (s.length < length) s = this.chars[0] + s;
+    return s;
+  }
+
+  private _bigintToBuffer(num: bigint, bytes: number): Buffer {
+    const buf = Buffer.alloc(bytes);
+    let n = num;
+    for (let i = bytes - 1; i >= 0; i--) {
+      buf[i] = Number(n & 0xFFn);
+      n >>= 8n;
+    }
+    return buf;
+  }
+
+  encrypt(X: string): string {
+    const n = X.length;
+    const t = this.tweak.length;
+    if (n < 2) return X;
+    const u = Math.floor(n / 2);
+    const v = n - u;
+    
+    let A = X.substring(0, u);
+    let B = X.substring(u);
+    
+    const b = Math.ceil(Math.ceil(v * Math.log2(this.radix)) / 8);
+    const d = 4 * Math.ceil(b / 4) + 4;
+
+    const P = Buffer.alloc(16);
+    P[0] = 1; P[1] = 2; P[2] = 1;
+    P.writeUIntBE(this.radix, 3, 3);
+    P[6] = 10; P[7] = u % 256;
+    P.writeUInt32BE(n, 8);
+    P.writeUInt32BE(t, 12);
+
+    for (let i = 0; i < 10; i++) {
+      const m = i % 2 === 0 ? u : v;
+      // padding length calculates correctly using JS modulo for negative numbers
+      const padLen = ((-t - b - 1) % 16 + 16) % 16;
+      
+      const Q = Buffer.alloc(t + padLen + 1 + b);
+      this.tweak.copy(Q, 0);
+      Q[t + padLen] = i;
+      this._bigintToBuffer(this._strToInt(B), b).copy(Q, t + padLen + 1);
+
+      const R = this._prf(Buffer.concat([P, Q]));
+      let S = Buffer.from(R);
+      let j = 1;
+      
+      while (S.length < d) {
+        const xorBlock = Buffer.alloc(16);
+        const jBuf = Buffer.alloc(16);
+        jBuf.writeUInt32BE(j, 12); // j fits in 32 bits natively
+        for (let k = 0; k < 16; k++) xorBlock[k] = R[k] ^ jBuf[k];
+        S = Buffer.concat([S, this._ciph(xorBlock)]);
+        j++;
+      }
+      
+      S = S.subarray(0, d);
+      
+      // Convert S to bigint
+      let y = 0n;
+      for (let k = 0; k < S.length; k++) {
+        y = (y << 8n) + BigInt(S[k]);
+      }
+      
+      const modulo = BigInt(this.radix) ** BigInt(m);
+      const c = (this._strToInt(A) + y) % modulo;
+      const C = this._intToStr(c, m);
+      
+      A = B;
+      B = C;
+    }
+    
+    return A + B;
+  }
+
+  decrypt(X: string): string {
+    const n = X.length;
+    const t = this.tweak.length;
+    if (n < 2) return X;
+    const u = Math.floor(n / 2);
+    const v = n - u;
+    
+    let A = X.substring(0, u);
+    let B = X.substring(u);
+    
+    if (n % 2 !== 0) {
+      const temp = A; A = B; B = temp;
+    }
+    
+    const b = Math.ceil(Math.ceil(v * Math.log2(this.radix)) / 8);
+    const d = 4 * Math.ceil(b / 4) + 4;
+
+    const P = Buffer.alloc(16);
+    P[0] = 1; P[1] = 2; P[2] = 1;
+    P.writeUIntBE(this.radix, 3, 3);
+    P[6] = 10; P[7] = u % 256;
+    P.writeUInt32BE(n, 8);
+    P.writeUInt32BE(t, 12);
+
+    for (let i = 9; i >= 0; i--) {
+      const m = i % 2 === 0 ? u : v;
+      const padLen = ((-t - b - 1) % 16 + 16) % 16;
+      
+      const Q = Buffer.alloc(t + padLen + 1 + b);
+      this.tweak.copy(Q, 0);
+      Q[t + padLen] = i;
+      this._bigintToBuffer(this._strToInt(A), b).copy(Q, t + padLen + 1);
+
+      const R = this._prf(Buffer.concat([P, Q]));
+      let S = Buffer.from(R);
+      let j = 1;
+      
+      while (S.length < d) {
+        const xorBlock = Buffer.alloc(16);
+        const jBuf = Buffer.alloc(16);
+        jBuf.writeUInt32BE(j, 12);
+        for (let k = 0; k < 16; k++) xorBlock[k] = R[k] ^ jBuf[k];
+        S = Buffer.concat([S, this._ciph(xorBlock)]);
+        j++;
+      }
+      
+      S = S.subarray(0, d);
+      
+      let y = 0n;
+      for (let k = 0; k < S.length; k++) {
+        y = (y << 8n) + BigInt(S[k]);
+      }
+      
+      const modulo = BigInt(this.radix) ** BigInt(m);
+      let c = (this._strToInt(B) - y) % modulo;
+      if (c < 0n) c += modulo;
+      
+      const C = this._intToStr(c, m);
+      
+      B = A;
+      A = C;
+    }
+    
+    if (n % 2 !== 0) {
+      const temp = A; A = B; B = temp;
+    }
+    
+    return A + B;
+  }
+}