mask-privacy 1.0.2

package/examples/secure_vault/email_tool.ts

@@ -0,0 +1,13 @@
+export function sendSecureEmail(emailAddress: string, subject: string, message: string): string {
+    /**
+     * Sends an email to the provided address (DEMO-ONLY, LELeaks PII TO STDOUT AND RESPONSES).
+     *
+     * This tool demonstrates the Just-In-Time Detokenization in action. 
+     */
+    console.log("\n[tool execution] smtplib email sender");
+    console.log(`Executing API request to send email to:\n----> ${emailAddress} <----`);
+    console.log(`Subject: ${subject}`);
+    console.log(`Body: ${message}\n`);
+    
+    return `Successfully sent email to ${emailAddress} with subject: '${subject}'`;
+}

package/examples/test_agent.ts

@@ -0,0 +1,50 @@
+import * as path from 'path';
+import { aencode } from '../src/index';
+import { decryptBeforeTool } from '../src/integrations/adk_hooks';
+import { sendSecureEmail } from './secure_vault/email_tool';
+
+class MockTool {
+    name = "send_secure_email";
+}
+
+class MockToolContext {
+    agent_name = "secure_data_assistant";
+}
+
+async function runDemo() {
+    console.log("\nStarting Mask JIT Micro-Vault detokenization demo (NON-PRODUCTION)...");
+    
+    // 1. The local application generates a token for the user's email
+    const realEmail = "user1@example.com";
+    const secureToken = await aencode(realEmail);
+    
+    console.log("\n[app] Intercepted PII. Storing in Micro-Vault...");
+    console.log(`[app] Vault mapping: ${secureToken} -> ${realEmail}`);
+    
+    // 2. We pass ONLY the token to the LLM
+    console.log(`\n[mask -> llm] Passing tokenized context to LLM:`);
+    console.log(`   Context: {'user:email': '${secureToken}'}`);
+    
+    // 3. Simulate the LLM deciding to call the tool with the token
+    console.log("\n[llm -> mask] LLM reasoned successfully. Calling tool `send_secure_email` with tokenized argument...");
+    const llmToolCallArgs: any = {
+        "emailAddress": secureToken,
+        "subject": "Welcome to Mask!",
+        "message": "Your Micro-Vault architecture is secure."
+    };
+    
+    // 4. Mask PRE-HOOK intercepts the tool call BEFORE execution
+    console.log("\n[mask jit detokenization hook]");
+    const mockTool = new MockTool();
+    const mockCtx = new MockToolContext();
+    
+    await decryptBeforeTool(mockTool, llmToolCallArgs, mockCtx);
+    
+    // 5. Execute the actual tool with the detokenized arguments
+    console.log("\n[system] Executing tool with detokenized payload (prints plaintext PII in this demo):");
+    sendSecureEmail(llmToolCallArgs.emailAddress, llmToolCallArgs.subject, llmToolCallArgs.message);
+    
+    console.log("\nVerification complete: The LLM only saw the token, but the tool triggered with the plaintext.");
+}
+
+runDemo().catch(console.error);

package/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts'],
+  verbose: true,
+  forceExit: true,
+  clearMocks: true,
+  resetMocks: true,
+  restoreMocks: true,
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "mask-privacy",
+  "version": "1.0.2",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "demo": "ts-node examples/test_agent.ts",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.1012.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.0",
+    "axios": "^1.13.6",
+    "better-sqlite3": "^12.8.0",
+    "fernet": "^0.3.3",
+    "ioredis": "^5.10.0",
+    "jest": "^30.3.0",
+    "memjs": "^1.3.2",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@aws-sdk/lib-dynamodb": "^3.1012.0",
+    "@langchain/core": "^1.1.33",
+    "llamaindex": "^0.12.1"
+  }
+}

package/src/client.ts

@@ -0,0 +1,135 @@
+/**
+ * Explicit Client initialization for the Mask SDK.
+ *
+ * Provides MaskClient — a unified, explicitly-configured client that
+ * bundles vault, crypto, scanner, and audit logger into a single object.
+ */
+
+import { BaseVault, getVault, decode, encode, detokenizeText } from './core/vault';
+import { CryptoEngine, getCryptoEngine } from './core/crypto';
+import { PresidioScanner, getScanner } from './core/scanner';
+import { generateFPEToken, looksLikeToken } from './core/fpe';
+import { AuditLogger, getAuditLogger } from './telemetry/audit_logger';
+
+export class MaskClient {
+  public vault: BaseVault;
+  public crypto: CryptoEngine;
+  public scanner: PresidioScanner;
+  public auditLogger: AuditLogger;
+  /** backward compat alias */
+  public logger: AuditLogger;
+  public ttl: number;
+
+  /**
+   * Initialise the client with specific component instances.
+   *
+   * If an instance is not provided, the client will fall back to
+   * the standard environment-configured singleton for that component.
+   */
+  constructor(options: {
+    vault?: BaseVault;
+    crypto?: CryptoEngine;
+    scanner?: PresidioScanner;
+    auditLogger?: AuditLogger;
+    ttl?: number;
+  } = {}) {
+    this.vault = options.vault || getVault();
+    this.crypto = options.crypto || getCryptoEngine();
+    this.scanner = options.scanner || getScanner();
+    this.auditLogger = options.auditLogger || getAuditLogger();
+    this.logger = this.auditLogger;
+    this.ttl = options.ttl || 600;
+
+    // Ensure the audit logger is running
+    this.auditLogger.start();
+  }
+
+  /**
+   * Tokenise rawText, encrypt it, and store it in the vault.
+   *
+   * Includes deduplication: if the same plaintext has been encoded
+   * before and the token is still active, the existing token is returned.
+   */
+  async encode(rawText: string): Promise<string> {
+    // Token Guard: never re-encode a value that is already a Mask token
+    if (looksLikeToken(rawText)) {
+      return rawText;
+    }
+
+    // Normalise whitespace so " Alice " and "Alice" share the same hash
+    const text = rawText.trim();
+
+    // 1. Deduplication check
+    // We'll use the vault methods directly here to match Python client logic
+    const cryptoSub = require('crypto');
+    const ptHash = cryptoSub.createHash('sha256').update(text, 'utf-8').digest('hex');
+
+    const existingToken = await this.vault.getTokenByPlaintextHash(ptHash);
+    if (existingToken && (await this.vault.retrieve(existingToken)) !== null) {
+      this.logger.log("encode", existingToken, "opaque");
+      return existingToken;
+    }
+
+    // 2. Generate deterministic token
+    const token = generateFPEToken(text);
+
+    // 3. Encrypt
+    const ciphertext = this.crypto.encrypt(text);
+
+    // 4. Store with reverse lookup hash
+    await this.vault.store(token, ciphertext, this.ttl, ptHash);
+
+    this.logger.log("encode", token, "opaque");
+    return token;
+  }
+
+  /** Retrieve token from vault and decrypt it. */
+  async decode(token: string): Promise<string> {
+    const ciphertext = await this.vault.retrieve(token);
+    if (ciphertext === null) {
+      this.logger.log("expired", token, "opaque");
+      return token;
+    }
+
+    try {
+      const plaintext = this.crypto.decrypt(ciphertext);
+      this.logger.log("decode", token, "opaque");
+      return plaintext;
+    } catch (e) {
+      this.logger.log("error", token, "opaque", "decryption_failed");
+      return token;
+    }
+  }
+
+  /** Scan text using the Waterfall pipeline and replace PII with FPE tokens. */
+  async scanAndTokenize(text: string): Promise<string> {
+    return await this.scanner.scanAndTokenize(text, {
+      encodeFn: (val) => this.encode(val)
+    });
+  }
+
+  /** Async wrapper for encode (parity with Python aencode). */
+  async aencode(rawText: string): Promise<string> {
+    return await this.encode(rawText);
+  }
+
+  /** Async wrapper for decode (parity with Python adecode). */
+  async adecode(token: string): Promise<string> {
+    return await this.decode(token);
+  }
+
+  /** Async wrapper for scanAndTokenize (parity with Python ascan_and_tokenize). */
+  async ascanAndTokenize(text: string): Promise<string> {
+    return await this.scanAndTokenize(text);
+  }
+
+  /** Find and replace all tokens within text with their plaintext. */
+  async detokenizeText(text: string): Promise<string> {
+    return await detokenizeText(text);
+  }
+
+  /** Async wrapper for detokenizeText (parity with Python adetokenize_text). */
+  async adetokenizeText(text: string): Promise<string> {
+    return await this.detokenizeText(text);
+  }
+}

package/src/core/crypto.ts

@@ -0,0 +1,100 @@
+/**
+ * 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).
+ *
+ * Requires MASK_ENCRYPTION_KEY to be set in the environment.
+ */
+
+import * as process from 'process';
+import { getKeyProvider } from './key_provider';
+
+const fernet = require('fernet');
+const cryptoNode = require('crypto');
+import { MaskDecryptionError } from './exceptions';
+
+export class CryptoEngine {
+  private static _instance: CryptoEngine | null = null;
+  private _fernet: any;
+
+  private constructor() {
+    this._init();
+  }
+
+  public static getInstance(): CryptoEngine {
+    if (this._instance === null) {
+      this._instance = new CryptoEngine();
+    }
+    return this._instance;
+  }
+
+  /** Clear the singleton instance to force re-initialization (useful for key rotation). */
+  public static reset(): void {
+    this._instance = null;
+  }
+
+  private _init(): void {
+    /**
+     * Initialize the underlying Fernet 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.
+     */
+    const keyFromProvider = getKeyProvider().getEncryptionKey();
+    let key: string;
+    if (!keyFromProvider) {
+      key = cryptoNode.randomBytes(32).toString('base64');
+      process.env.MASK_ENCRYPTION_KEY = key;
+      console.warn(
+        "MASK_ENCRYPTION_KEY not set. Using a generated throwaway key. DO NOT USE THIS IN PRODUCTION."
+      );
+    } else {
+      key = keyFromProvider;
+    }
+
+    try {
+      // fernet Secret expects a base64 encoded string
+      const secret = new fernet.Secret(key);
+      this._fernet = secret;
+    } catch (e) {
+      throw new Error(
+        "Invalid MASK_ENCRYPTION_KEY. Must be a valid url-safe base64-encoded " +
+        "Fernet key."
+      );
+    }
+  }
+
+  public encrypt(plaintext: string): string {
+    /** Encrypt plaintext into a url-safe base64 string. */
+    const token = new fernet.Token({
+      secret: this._fernet,
+      time: Date.now(),
+      iv: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] // Placeholder if needed, but fernet generates its own
+    });
+    // The fernet npm package encode returns a string
+    return token.encode(plaintext);
+  }
+
+  public decrypt(ciphertext: string): string {
+    /** Decrypt url-safe base64 ciphertext back to plaintext. */
+    try {
+      const token = new fernet.Token({
+        secret: this._fernet,
+        token: ciphertext,
+        ttl: 0 // No TTL check by default to match Python's Fernet default
+      });
+      return token.decode();
+    } catch (e) {
+      console.error("Failed to decrypt vault payload. Check your MASK_ENCRYPTION_KEY.");
+      throw new MaskDecryptionError("Decryption failed");
+    }
+  }
+}
+
+/** Return the configured crypto engine singleton. */
+export function getCryptoEngine(): CryptoEngine {
+  return CryptoEngine.getInstance();
+}

package/src/core/exceptions.ts

@@ -0,0 +1,23 @@
+/**
+ * Custom exception hierarchy for the Mask SDK.
+ *
+ * Provides specific exceptions so callers can implement targeted
+ * retry/fallback logic instead of catching generic Error.
+ */
+
+export class MaskError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/** Raised when a vault backend (Redis, DynamoDB) is unreachable. */
+export class MaskVaultConnectionError extends MaskError {}
+
+/** Raised when CryptoEngine.decrypt() fails (bad key, corrupt data). */
+export class MaskDecryptionError extends MaskError {}
+
+/** Raised when spaCy / Presidio analysis exceeds the time budget. */
+export class MaskNLPTimeout extends MaskError {}

package/src/core/fpe.ts

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ *
+ * Determinism is achieved via HMAC-SHA256 keyed with a master key, ensuring
+ * the same plaintext always produces the same token. This preserves entity
+ * relationships for LLMs (e.g. "John" is always [TKN-abc]) without leaking
+ * the identity.
+ *
+ * Supported formats:
+ *   - Email  →  tkn-<hex>@email.com
+ *   - Phone  →  +1-555-<7 digits>
+ *   - SSN    →  000-00-<4 digits>
+ *   - CC     →  4000-0000-0000-<4 digits>
+ *   - Routing→  000000<3 digits>
+ *   - Default→  [TKN-<hex>]
+ */
+
+import * as crypto from 'crypto';
+import * as process from 'process';
+import { getKeyProvider } from './key_provider';
+
+// Master key management
+
+let _masterKey: Buffer | null = null;
+
+/** Return the HMAC master key, lazily initialised from the key provider. */
+function _getMasterKey(): Buffer {
+  if (_masterKey === null) {
+    let raw = getKeyProvider().getMasterKey() || "";
+    if (!raw) {
+      // Auto-generate a session-local key (non-persistent)
+      raw = crypto.randomBytes(32).toString('hex');
+      process.env.MASK_MASTER_KEY = raw;
+      console.warn(
+        "MASK_MASTER_KEY not set. Using an ephemeral session key. " +
+        "Tokens will NOT be reproducible across process restarts."
+      );
+    }
+    _masterKey = Buffer.from(raw, 'utf-8');
+  }
+  return _masterKey;
+}
+
+/** Clear the cached master key. Useful in tests. */
+export function resetMasterKey(): void {
+  _masterKey = null;
+}
+
+// Detectors — order matters: first match wins
+
+const _EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+const _PHONE_RE = /^\+?1?[\s\-.]?\(?\d{3}\)?[\s\-.]?\d{3}[\s\-.]?\d{4}$|^\d{3}[\s\-.]?\d{4}$/;
+const _SSN_RE = /^\d{3}-\d{2}-\d{4}$/;
+const _CC_RE = /^(?:\d{4}[ \-]?){3}\d{4}$/;
+const _ROUTING_RE = /^\d{9}$/;
+
+// Deterministic helpers (HMAC-based)
+
+/** Return *n* deterministic hex characters derived from HMAC(key, plaintext). */
+function _hmacHex(plaintext: string, n: number = 8): string {
+  const digest = crypto
+    .createHmac('sha256', _getMasterKey())
+    .update(plaintext, 'utf-8')
+    .digest('hex');
+  return digest.slice(0, n);
+}
+
+/** Return *n* deterministic decimal digits derived from HMAC(key, plaintext). */
+function _hmacDigits(plaintext: string, n: number, offset: number = 0): string {
+  const digest = crypto
+    .createHmac('sha256', _getMasterKey())
+    .update(plaintext, 'utf-8')
+    .digest('hex');
+
+  // Convert hex nibbles to digits via modulo-10
+  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;
+    }
+  }
+
+  // Safety: pad with zeros if digest is too short (shouldn't happen for SHA-256)
+  while (result.length < n) {
+    result.push("0");
+  }
+  return result.join("");
+}
+
+// Public API
+
+/**
+ * Return a **deterministic**, format-preserving token for rawText.
+ *
+ * The token is structurally compatible with the original data type
+ * so that downstream schema validators, regex checks, and database
+ * constraints continue to pass.
+ */
+export function generateFPEToken(rawText: string): string {
+  const text = rawText.trim();
+
+  if (_EMAIL_RE.test(text)) {
+    return `tkn-${_hmacHex(text)}@email.com`;
+  }
+
+  if (_PHONE_RE.test(text)) {
+    return `+1-555-${_hmacDigits(text, 7)}`;
+  }
+
+  if (_SSN_RE.test(text)) {
+    return `000-00-${_hmacDigits(text, 4)}`;
+  }
+
+  // Standard 16-digit credit card (format: 4000-0000-0000-XXXX)
+  if (_CC_RE.test(text)) {
+    return `4000-0000-0000-${_hmacDigits(text, 4)}`;
+  }
+
+  // US ABA Routing Number (format: 000000XXX)
+  if (_ROUTING_RE.test(text)) {
+    return `000000${_hmacDigits(text, 3)}`;
+  }
+
+  // Opaque fallback
+  return `[TKN-${_hmacHex(text)}]`;
+}
+
+/**
+ * Regex that matches ANY valid Mask token.
+ * Used for sub-string detokenization (finding tokens inside paragraphs).
+ */
+export const TOKEN_PATTERN = new RegExp(
+  "tkn-[a-f0-9]{8,64}@email\\.com" +            // Email
+  "|\\+1-555-\\d{7}" +                           // Phone
+  "|000-00-\\d{4}" +                            // SSN
+  "|4000-0000-0000-\\d{4}" +                    // CC
+  "|000000\\d{3}" +                             // Routing
+  "|\\[TKN-[a-f0-9]{8,64}\\]",                  // Opaque
+  "g"
+);
+
+/**
+ * Heuristic: return true if value appears to be a Mask token.
+ */
+export function looksLikeToken(value: string): boolean {
+  const v = value.trim();
+
+  // Email tokens: tkn-<hex>@email.com
+  if (v.startsWith("tkn-") && v.endsWith("@email.com")) {
+    return true;
+  }
+
+  // Phone tokens: +1-555-XXXXXXX  (555 is the standard fictional exchange)
+  if (v.startsWith("+1-555-") && v.length === 14) {
+    return true;
+  }
+
+  // SSN tokens: 000-00-XXXX  (area 000 is never assigned)
+  if (v.startsWith("000-00-") && v.length === 11 && /^\d+$/.test(v.slice(7))) {
+    return true;
+  }
+
+  // Credit card tokens: 4000-0000-0000-XXXX  (reserved test BIN)
+  if (v.startsWith("4000-0000-0000-") && v.length === 19 && /^\d+$/.test(v.slice(15))) {
+    return true;
+  }
+
+  // Routing tokens: 000000XXX  (invalid Fed symbol 0000)
+  if (v.startsWith("000000") && v.length === 9 && /^\d+$/.test(v.slice(6))) {
+    return true;
+  }
+
+  // Opaque fallback tokens: [TKN-<hex>]
+  if (v.startsWith("[TKN-") && v.endsWith("]")) {
+    return true;
+  }
+
+  return false;
+}