mask-privacy 1.0.2

package/tests/fpe.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { generateFPEToken, looksLikeToken, resetMasterKey } from '../src/core/fpe';
+
+describe('TestFPETokenGeneration', () => {
+  beforeEach(() => {
+    resetMasterKey();
+    process.env.MASK_MASTER_KEY = "test-key-for-deterministic-fpe";
+  });
+
+  afterEach(() => {
+    resetMasterKey();
+  });
+
+  test('test_email_format', () => {
+    const token = generateFPEToken("user@company.io");
+    expect(token.endsWith("@email.com")).toBe(true);
+    expect(token.startsWith("tkn-")).toBe(true);
+    expect(token).toMatch(/^[^@]+@[^@]+\.[^@]+$/);
+  });
+
+  test('test_phone_format', () => {
+    const token = generateFPEToken("+1-212-555-1234");
+    expect(token.startsWith("+1-555-")).toBe(true);
+    expect(token.length).toBe(14);
+    expect(token).toMatch(/^\+1-555-\d{7}$/);
+  });
+
+  test('test_seven_digit_phone_format', () => {
+    const token = generateFPEToken("555-1234");
+    expect(token.startsWith("+1-555-")).toBe(true);
+    expect(token.length).toBe(14);
+  });
+
+  test('test_ssn_format', () => {
+    const token = generateFPEToken("123-45-6789");
+    expect(token.startsWith("000-00-")).toBe(true);
+    expect(token.length).toBe(11);
+    expect(token).toMatch(/^\d{3}-\d{2}-\d{4}$/);
+  });
+
+  test('test_cc_format', () => {
+    const token = generateFPEToken("4111-1111-1111-1111");
+    expect(token.startsWith("4000-0000-0000-")).toBe(true);
+    expect(token.length).toBe(19);
+    expect(token).toMatch(/^(?:\d{4}[ \-]?){3}\d{4}$/);
+  });
+
+  test('test_routing_format', () => {
+    const token = generateFPEToken("122000661");
+    expect(token.startsWith("000000")).toBe(true);
+    expect(token.length).toBe(9);
+    expect(token).toMatch(/^\d{9}$/);
+  });
+
+  test('test_opaque_fallback', () => {
+    const token = generateFPEToken("just some random string");
+    expect(token.startsWith("[TKN-")).toBe(true);
+    expect(token.endsWith("]")).toBe(true);
+  });
+
+  test('test_deterministic_same_input_same_output', () => {
+    const t1 = generateFPEToken("a@b.com");
+    const t2 = generateFPEToken("a@b.com");
+    expect(t1).toBe(t2);
+    expect(t1.endsWith("@email.com")).toBe(true);
+  });
+
+  test('test_different_inputs_different_tokens', () => {
+    const t1 = generateFPEToken("alice@example.com");
+    const t2 = generateFPEToken("bob@example.com");
+    expect(t1).not.toBe(t2);
+  });
+
+  test('test_determinism_across_all_types', () => {
+    const values = [
+      "user@test.com",
+      "+1-212-555-1234",
+      "555-1234",
+      "123-45-6789",
+      "4111-1111-1111-1111",
+      "122000661",
+      "John Doe",
+    ];
+    for (const value of values) {
+      expect(generateFPEToken(value)).toBe(generateFPEToken(value));
+    }
+  });
+
+  test('test_whitespace_stripped_determinism', () => {
+    expect(generateFPEToken(" someone@email.com ")).toBe(generateFPEToken("someone@email.com"));
+  });
+});
+
+describe('TestLooksLikeToken', () => {
+  test('test_email_token', () => {
+    expect(looksLikeToken("tkn-abcd1234@email.com")).toBe(true);
+  });
+
+  test('test_phone_token', () => {
+    expect(looksLikeToken("+1-555-1234567")).toBe(true);
+  });
+
+  test('test_ssn_token', () => {
+    expect(looksLikeToken("000-00-1234")).toBe(true);
+  });
+
+  test('test_cc_token', () => {
+    expect(looksLikeToken("4000-0000-0000-1234")).toBe(true);
+  });
+
+  test('test_routing_token', () => {
+    expect(looksLikeToken("000000123")).toBe(true);
+  });
+
+  test('test_opaque_token', () => {
+    expect(looksLikeToken("[TKN-abcd1234]")).toBe(true);
+  });
+
+  test('test_real_email_is_not_token', () => {
+    expect(looksLikeToken("real@company.com")).toBe(false);
+  });
+
+  test('test_random_string_is_not_token', () => {
+    expect(looksLikeToken("hello world")).toBe(false);
+  });
+});

package/tests/hooks.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { encode, resetVault } from '../src/core/vault';
+import { resetMasterKey } from '../src/core/fpe';
+import { decryptBeforeTool, encryptAfterTool } from '../src/integrations/adk_hooks';
+import { deepDecode, deepEncodePII } from '../src/core/utils';
+import { looksLikeToken } from '../src/core/fpe';
+import * as process from 'process';
+
+// Minimal stubs matching ADK protocol
+class FakeTool {
+    name = "test_tool";
+}
+
+class FakeCtx {
+    agentName = "test_agent";
+}
+
+describe('TestHooks', () => {
+    beforeEach(() => {
+        process.env.MASK_VAULT_TYPE = "memory";
+        resetVault();
+        resetMasterKey();
+        process.env.MASK_MASTER_KEY = "test-hooks-key";
+    });
+
+    afterEach(() => {
+        resetVault();
+        resetMasterKey();
+    });
+
+    describe('TestDeepDecode', () => {
+        test('test_flat_dict', async () => {
+            const token = await encode("alice@corp.io");
+            const result = await deepDecode({"email": token, "msg": "hi"});
+            expect(result.email).toBe("alice@corp.io");
+            expect(result.msg).toBe("hi");
+        });
+
+        test('test_nested_dict', async () => {
+            const token = await encode("bob@bank.com");
+            const data = {"user": {"contact": {"email": token}}};
+            const result = await deepDecode(data);
+            expect(result.user.contact.email).toBe("bob@bank.com");
+        });
+
+        test('test_list_values', async () => {
+            const t1 = await encode("a@b.com");
+            const t2 = await encode("c@d.com");
+            const result = await deepDecode({"recipients": [t1, t2]});
+            expect(result.recipients).toEqual(["a@b.com", "c@d.com"]);
+        });
+
+        test('test_non_token_strings_unchanged', async () => {
+            const result = await deepDecode({"name": "Alice", "age": 30});
+            expect(result).toEqual({"name": "Alice", "age": 30});
+        });
+    });
+
+    describe('TestDeepEncodeEmails', () => {
+        test('test_encodes_raw_email', async () => {
+            const result = await deepEncodePII({"email": "test@example.com"});
+            expect(looksLikeToken(result.email)).toBe(true);
+            expect(result.email).toMatch(/@email\.com$/);
+        });
+
+        test('test_does_not_double_encode_token', async () => {
+            const token = await encode("original@test.com");
+            const result = await deepEncodePII({"email": token});
+            expect(result.email).toBe(token);
+        });
+    });
+
+    describe('TestDecryptBeforeTool', () => {
+        test('test_mutates_args_in_place', async () => {
+            const token = await encode("admin@secure.io");
+            const args = {"email": token, "action": "send"};
+            await decryptBeforeTool(new FakeTool(), args, new FakeCtx());
+            expect(args.email).toBe("admin@secure.io");
+            expect(args.action).toBe("send");
+        });
+    });
+
+    describe('TestEncryptAfterTool', () => {
+        test('test_encodes_leaked_emails_in_args', async () => {
+            const args = {"email": "leaked@plain.com"};
+            await encryptAfterTool(new FakeTool() as any, args, new FakeCtx() as any, {});
+            expect(looksLikeToken(args.email)).toBe(true);
+        });
+
+        test('test_encodes_leaked_emails_in_string_response', async () => {
+            const args = "Contact us at support@example.com for help.";
+            const result = await deepEncodePII(args);
+            expect(typeof result).toBe('string');
+            expect(result).toContain("@email.com");
+            expect(result).not.toContain("support@example.com");
+        });
+
+        test('test_encodes_leaked_emails_but_skips_tokens_in_nested_dict', async () => {
+            const token = await encode("admin@secure.io");
+            const args = {"response": {"leaked": "bad@plain.com", "safe": token}};
+            const result = await deepEncodePII(args);
+            
+            expect(looksLikeToken(result.response.leaked)).toBe(true);
+            expect(result.response.safe).toBe(token);
+        });
+    });
+});

package/tests/key_provider.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { 
+  EnvKeyProvider, 
+  AwsKmsKeyProvider, 
+  AzureKeyVaultProvider, 
+  HashiCorpVaultProvider, 
+  getKeyProvider, 
+  setKeyProvider, 
+  resetKeyProvider 
+} from '../src/core/key_provider';
+
+describe('TestKeyProvider', () => {
+  beforeEach(() => {
+    resetKeyProvider();
+    delete process.env.MASK_ENCRYPTION_KEY;
+    delete process.env.MASK_MASTER_KEY;
+  });
+
+  afterEach(() => {
+    resetKeyProvider();
+    delete process.env.MASK_ENCRYPTION_KEY;
+    delete process.env.MASK_MASTER_KEY;
+  });
+
+  test('test_default_is_env_provider', () => {
+    const provider = getKeyProvider();
+    expect(provider).toBeInstanceOf(EnvKeyProvider);
+  });
+
+  test('test_set_custom_provider', () => {
+    class DummyProvider extends EnvKeyProvider {}
+    const dummy = new DummyProvider();
+    setKeyProvider(dummy);
+    expect(getKeyProvider()).toBe(dummy);
+  });
+
+  test('test_env_provider_reads_from_environ', () => {
+    process.env.MASK_ENCRYPTION_KEY = "test-enc-key";
+    process.env.MASK_MASTER_KEY = "test-master-key";
+    
+    const provider = new EnvKeyProvider();
+    expect(provider.getEncryptionKey()).toBe("test-enc-key");
+    expect(provider.getMasterKey()).toBe("test-master-key");
+  });
+
+  test('test_env_provider_falls_back_master_to_encryption', () => {
+    process.env.MASK_ENCRYPTION_KEY = "fallback-key";
+    delete process.env.MASK_MASTER_KEY;
+    
+    const provider = new EnvKeyProvider();
+    expect(provider.getEncryptionKey()).toBe("fallback-key");
+    expect(provider.getMasterKey()).toBe("fallback-key");
+  });
+
+  test('test_stub_providers_raise_not_implemented', () => {
+    const aws = new AwsKmsKeyProvider("alias/key");
+    expect(() => aws.getEncryptionKey()).toThrow();
+    expect(() => aws.getMasterKey()).toThrow();
+        
+    const azure = new AzureKeyVaultProvider("https://vault");
+    expect(() => azure.getEncryptionKey()).toThrow();
+    expect(() => azure.getMasterKey()).toThrow();
+        
+    const hashi = new HashiCorpVaultProvider("https://vault:8200");
+    expect(() => hashi.getEncryptionKey()).toThrow();
+    expect(() => hashi.getMasterKey()).toThrow();
+  });
+});

package/tests/langchain.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { encode, resetVault } from '../src/core/vault';
+import { resetMasterKey } from '../src/core/fpe';
+import { MaskToolWrapper, secureTool, getMaskCallbackHandler } from '../src/integrations/langchain_hooks';
+import * as process from 'process';
+
+describe('TestLangchainHooks', () => {
+    beforeEach(() => {
+        process.env.MASK_VAULT_TYPE = "memory";
+        resetVault();
+        resetMasterKey();
+        process.env.MASK_MASTER_KEY = "test-langchain-key";
+    });
+
+    afterEach(() => {
+        resetVault();
+        resetMasterKey();
+    });
+
+    describe('TestLangchainMaskToolWrapper', () => {
+        test('test_wrapper_detokenizes_inputs_and_tokenizes_outputs', async () => {
+            const token = await encode("user@example.com");
+
+            const mockTool = jest.fn<any>().mockImplementation(async (email: string, subject: string) => {
+                expect(email).toBe("user@example.com");
+                expect(subject).toBe("Welcome");
+                return {"target": email, "subject": subject};
+            });
+
+            const secure = new MaskToolWrapper(mockTool);
+            const result = await secure.run(token, "Welcome");
+
+            expect(result.target).not.toBe("user@example.com");
+            expect(result.target).toMatch(/@email\.com$/);
+        });
+    });
+
+    describe('TestLangchainMaskCallbackHandler', () => {
+        test('test_on_tool_start_mutates_inputs', async () => {
+             // Mock BaseCallbackHandler since we don't want to install @langchain/core in this environment if not present
+            const MockHandlerClass = await getMaskCallbackHandler();
+            const handler = new MockHandlerClass();
+
+            const token1 = await encode("alice@corp.io");
+            const token2 = await encode("bob@corp.io");
+
+            const inputsDict = {
+                "primary": token1,
+                "cc": [token2, "charlie@corp.io"],
+            };
+
+            if ((handler as any).handleToolStart) {
+                await (handler as any).handleToolStart(
+                    {"name": "send_email"},
+                    "...",
+                    "run-id",
+                    undefined,
+                    [],
+                    {},
+                    inputsDict
+                );
+
+                expect(inputsDict.primary).toBe("alice@corp.io");
+                expect(inputsDict.cc[0]).toBe("bob@corp.io");
+                expect(inputsDict.cc[1]).toBe("charlie@corp.io");
+            }
+        });
+    });
+
+    describe('TestLangchainSecureTool', () => {
+        test('test_secure_tool_decorator_detokenizes_and_retokenizes', async () => {
+            const token = await encode("dev@mask.ai");
+
+            const sendEmail = secureTool(async (email: string, body: string) => {
+                expect(email).toBe("dev@mask.ai");
+                return `Sent to ${email}`;
+            });
+
+            const result = await sendEmail(token, "Hello");
+            expect(result).not.toContain("dev@mask.ai");
+            expect(result).toContain("@email.com");
+        });
+
+        test('test_secure_tool_preserves_non_pii', async () => {
+            const greet = secureTool(async (name: string) => {
+                return `Hello, ${name}!`;
+            });
+
+            const result = await greet("World");
+            expect(result).toBe("Hello, World!");
+        });
+
+        test('test_secure_tool_with_custom_name', () => {
+            const lookup = secureTool(async (userId: string) => {
+                return {"id": userId};
+            }, { name: "custom_lookup" });
+
+            expect(lookup.name).toBe("custom_lookup");
+        });
+    });
+});

package/tests/llamaindex.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { encode, resetVault } from '../src/core/vault';
+import { resetMasterKey } from '../src/core/fpe';
+import { MaskToolWrapper, maskLlamaIndexHooks } from '../src/integrations/llamaindex_hooks';
+import * as process from 'process';
+
+describe('TestLlamaindexHooks', () => {
+    beforeEach(() => {
+        process.env.MASK_VAULT_TYPE = "memory";
+        resetVault();
+        resetMasterKey();
+        process.env.MASK_MASTER_KEY = "test-llamaindex-key";
+    });
+
+    afterEach(() => {
+        resetVault();
+        resetMasterKey();
+        jest.restoreAllMocks();
+    });
+
+    describe('TestLlamaindexMaskToolWrapper', () => {
+        test('test_wrapper_detokenizes_inputs_and_tokenizes_outputs', async () => {
+            const token = await encode("admin@hospital.com");
+
+            const mockTool = jest.fn<any>().mockImplementation(async (email: string, prompt: string) => {
+                expect(email).toBe("admin@hospital.com");
+                expect(prompt).toBe("Give me the records");
+                return {"target": email, "status": "success"};
+            });
+
+            const secureTool = new MaskToolWrapper(mockTool);
+            const result = await secureTool.run(token, "Give me the records");
+
+            expect(result.target).not.toBe("admin@hospital.com");
+            expect(result.target).toMatch(/@email\.com$/);
+        });
+    });
+
+    describe('TestLlamaindexMagicHooks', () => {
+        test('test_mask_llamaindex_hooks_patches_basetool', async () => {
+            // Minimal stub for LlamaIndex BaseTool
+            class BaseTool {
+                async call(...args: any[]) {
+                    return `Secret: ${args[0]}`;
+                }
+            }
+
+            // Mock 'llamaindex' module discovery
+            // In a real environment, we'd use jest.mock('llamaindex', ...)
+            // Here we'll manually apply the logic to our stub to verify the "magic" patch logic
+            
+            const originalCall = BaseTool.prototype.call;
+            const deepDecode = require('../src/core/utils').deepDecode;
+            const deepEncodePII = require('../src/core/utils').deepEncodePII;
+
+            BaseTool.prototype.call = async function(this: any, ...args: any[]) {
+                const decodedArgs = await Promise.all(args.map(a => deepDecode(a)));
+                const result = await originalCall.apply(this, decodedArgs);
+                if (typeof result === 'string' || typeof result === 'object') {
+                    return await deepEncodePII(result);
+                }
+                return result;
+            };
+
+            const tool = new BaseTool();
+            const token = await encode("llamaindex@mask.ai");
+
+            const result = await tool.call(token);
+
+            expect(result).not.toContain("llamaindex@mask.ai");
+            expect(result).toContain("Secret:");
+            expect(result).toContain("tkn-");
+        });
+    });
+});

package/tests/scanner.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect } from '@jest/globals';
+import { REGEX_PATTERNS, PresidioScanner } from '../src/core/scanner';
+
+describe('TestInternationalPhonePatterns', () => {
+  const pattern = new RegExp(REGEX_PATTERNS["PHONE_NUMBER_INTL"].source, 'g');
+
+  test.each([
+    "+44 20 7946 0958",
+    "+44 7911 123456",
+    "+442079460958",
+    "+33 1 23 45 67 89",
+    "+33 6 12 34 56 78",
+    "+49 30 1234 5678",
+    "+49 170 1234567",
+  ])('test_intl_phone_match: %s', (number) => {
+    pattern.lastIndex = 0;
+    expect(pattern.test(number)).toBe(true);
+  });
+
+  test.each([
+    "+1 555 123 4567",
+    "020 7946 0958",
+    "just some text",
+  ])('test_intl_phone_no_match: %s', (nonMatch) => {
+    pattern.lastIndex = 0;
+    expect(pattern.test(nonMatch)).toBe(false);
+  });
+});
+
+describe('TestUSRoutingNumber', () => {
+  const pattern = new RegExp(REGEX_PATTERNS["US_ROUTING_NUMBER"].source, 'g');
+
+  test('test_regex_matches_9_digit_number', () => {
+    pattern.lastIndex = 0;
+    expect(pattern.test("021000021")).toBe(true);
+  });
+
+  test('test_regex_does_not_match_8_digits', () => {
+    pattern.lastIndex = 0;
+    expect(pattern.test("word 12345678 word")).toBe(false);
+  });
+
+  test('test_aba_checksum_valid', () => {
+    // @ts-ignore - accessing protected static for test
+    expect(PresidioScanner._abaChecksum("021000021")).toBe(true);
+  });
+
+  test('test_aba_checksum_invalid', () => {
+    // @ts-ignore
+    expect(PresidioScanner._abaChecksum("123456789")).toBe(false);
+  });
+
+  test('test_aba_checksum_wrong_length', () => {
+    // @ts-ignore
+    expect(PresidioScanner._abaChecksum("12345")).toBe(false);
+  });
+});
+
+describe('TestUSPassport', () => {
+  const pattern = new RegExp(REGEX_PATTERNS["US_PASSPORT"].source, 'g');
+
+  test.each([
+    "C12345678",
+    "A00000001",
+    "Z99999999",
+  ])('test_passport_match: %s', (passport) => {
+    pattern.lastIndex = 0;
+    expect(pattern.test(passport)).toBe(true);
+  });
+
+  test.each([
+    "c12345678",
+    "12345678A",
+    "AB12345678",
+    "A1234567",
+  ])('test_passport_no_match: %s', (nonMatch) => {
+    pattern.lastIndex = 0;
+    expect(pattern.test(nonMatch)).toBe(false);
+  });
+});
+
+describe('TestDateOfBirth', () => {
+  const pattern = new RegExp(REGEX_PATTERNS["DATE_OF_BIRTH"].source, 'g');
+
+  test.each([
+    "01/15/1990",
+    "12/31/2000",
+    "06/01/1985",
+    "1990-01-15",
+    "2000-12-31",
+    "1985-06-01",
+  ])('test_dob_match: %s', (dob) => {
+    pattern.lastIndex = 0;
+    expect(pattern.test(dob)).toBe(true);
+  });
+
+  test.each([
+    "13/01/1990",
+    "00/15/1990",
+    "01/32/1990",
+    "1890-01-01",
+    "2100-01-01",
+  ])('test_dob_no_match: %s', (nonMatch) => {
+    pattern.lastIndex = 0;
+    expect(pattern.test(nonMatch)).toBe(false);
+  });
+});

package/tests/smoke.test.ts

@@ -0,0 +1,6 @@
+import { describe, test, expect } from '@jest/globals';
+describe('SmokeTest', () => {
+  test('true is true', () => {
+    expect(true).toBe(true);
+  });
+});

package/tests/substring.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { encode, resetVault, detokenizeText } from '../src/core/vault';
+import { resetMasterKey } from '../src/core/fpe';
+import { deepDecode } from '../src/core/utils';
+import * as process from 'process';
+
+describe('TestSubstringDetokenization', () => {
+  beforeEach(() => {
+    process.env.MASK_VAULT_TYPE = "memory";
+    resetVault();
+    resetMasterKey();
+    process.env.MASK_MASTER_KEY = "test-substring-key";
+  });
+
+  afterEach(() => {
+    resetVault();
+    resetMasterKey();
+  });
+
+  test('test_detokenize_text_with_embedded_tokens', async () => {
+    const email = "alice@example.com";
+    const phone = "+1-555-123-4567";
+    
+    const tEmail = await encode(email);
+    const tPhone = await encode(phone);
+    
+    const paragraph = `Contact ${tEmail} at ${tPhone} today.`;
+    const restored = await detokenizeText(paragraph);
+    
+    expect(restored).toContain(email);
+    expect(restored).toContain(phone);
+    expect(restored).toBe(`Contact ${email} at ${phone} today.`);
+  });
+
+  test('test_deep_decode_handles_paragraphs', async () => {
+    const email = "bob@work.com";
+    const tEmail = await encode(email);
+    
+    const data = {
+        "email": tEmail,
+        "body": `Hi, I am ${tEmail}. Please call me.`,
+        "nested": [`Token: ${tEmail}`]
+    };
+    
+    const decoded: any = await deepDecode(data);
+    
+    expect(decoded.email).toBe(email);
+    expect(decoded.body).toBe(`Hi, I am ${email}. Please call me.`);
+    expect(decoded.nested[0]).toBe(`Token: ${email}`);
+  });
+
+  test('test_detokenize_text_lenient', async () => {
+    const bogus = "tkn-12345678@email.com";
+    const paragraph = `Hello ${bogus}`;
+    
+    const restored = await detokenizeText(paragraph);
+    expect(restored).toBe(paragraph);
+  });
+});