@bernierllc/email-mitm-masking 1.0.0

package/__tests__/EmailMaskingService.test.ts

@@ -0,0 +1,470 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { EmailMaskingService } from '../src/EmailMaskingService.js';
+import { testConfig } from './__fixtures__/test-config.js';
+import type { ProxyAddress } from '../src/types.js';
+
+describe('EmailMaskingService', () => {
+  let service: EmailMaskingService;
+
+  beforeEach(async () => {
+    service = new EmailMaskingService(testConfig);
+    await service.initialize();
+  });
+
+  afterEach(async () => {
+    await service.shutdown();
+  });
+
+  describe('createProxy', () => {
+    it('should create proxy with default TTL', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com');
+
+      expect(proxy.proxyEmail).toMatch(/user123-[a-z0-9]+@proxy\.test\.com/);
+      expect(proxy.realEmail).toBe('user@real.com');
+      expect(proxy.userId).toBe('user123');
+      expect(proxy.status).toBe('active');
+      expect(proxy.expiresAt).toBeDefined();
+      expect(proxy.routingCount).toBe(0);
+    });
+
+    it('should create proxy with custom TTL', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com', {
+        ttlDays: 90
+      });
+
+      expect(proxy.expiresAt).toBeDefined();
+      if (proxy.expiresAt) {
+        const expectedExpiry = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000);
+        const diff = Math.abs(proxy.expiresAt.getTime() - expectedExpiry.getTime());
+        expect(diff).toBeLessThan(5000); // Within 5 seconds
+      }
+    });
+
+    it('should create proxy with external email for per-contact masking', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com', {
+        externalEmail: 'contact@external.com'
+      });
+
+      expect(proxy.externalEmail).toBe('contact@external.com');
+    });
+
+    it('should create proxy with conversation ID', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com', {
+        conversationId: 'conv-abc123'
+      });
+
+      expect(proxy.conversationId).toBe('conv-abc123');
+    });
+
+    it('should create proxy with metadata', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com', {
+        metadata: { source: 'test', priority: 'high' }
+      });
+
+      expect(proxy.metadata).toEqual({ source: 'test', priority: 'high' });
+    });
+
+    it('should enforce user quota limits', async () => {
+      // Create 10 proxies (max)
+      for (let i = 0; i < 10; i++) {
+        await service.createProxy('user123', `user${i}@real.com`);
+      }
+
+      // 11th should fail
+      await expect(
+        service.createProxy('user123', 'user11@real.com')
+      ).rejects.toThrow(/maximum proxy limit/);
+    });
+
+    it('should create unlimited proxies when quota is 0', async () => {
+      const serviceNoQuota = new EmailMaskingService({
+        ...testConfig,
+        maxProxiesPerUser: 0
+      });
+      await serviceNoQuota.initialize();
+
+      // Should be able to create many proxies
+      for (let i = 0; i < 15; i++) {
+        const proxy = await serviceNoQuota.createProxy('user456', `user${i}@real.com`);
+        expect(proxy).toBeDefined();
+      }
+
+      await serviceNoQuota.shutdown();
+    });
+  });
+
+  describe('routeInbound', () => {
+    let proxy: ProxyAddress;
+
+    beforeEach(async () => {
+      proxy = await service.createProxy('user123', 'user@real.com');
+    });
+
+    it('should route inbound email to real address', async () => {
+      const result = await service.routeInbound(
+        'external@example.com',
+        proxy.proxyEmail,
+        'Test Email',
+        'Hello!',
+        '<p>Hello!</p>'
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.routedTo).toBe('user@real.com');
+      expect(result.proxyUsed).toBe(proxy.proxyEmail);
+      expect(result.direction).toBe('inbound');
+      expect(result.auditId).toBeDefined();
+    });
+
+    it('should route inbound email with Name <email> format', async () => {
+      const result = await service.routeInbound(
+        'external@example.com',
+        `John Doe <${proxy.proxyEmail}>`,
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.routedTo).toBe('user@real.com');
+    });
+
+    it('should reject unknown proxy', async () => {
+      const result = await service.routeInbound(
+        'external@example.com',
+        'unknown-abc123@proxy.test.com',
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/not found/);
+      expect(result.direction).toBe('inbound');
+    });
+
+    it('should reject inactive proxy', async () => {
+      await service.deactivateProxy(proxy.id);
+
+      const result = await service.routeInbound(
+        'external@example.com',
+        proxy.proxyEmail,
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/inactive/);
+    });
+
+    it('should reject revoked proxy', async () => {
+      await service.revokeProxy(proxy.id);
+
+      const result = await service.routeInbound(
+        'external@example.com',
+        proxy.proxyEmail,
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/revoked/);
+    });
+
+    it('should reject expired proxy', async () => {
+      // Create proxy with expiration in the past
+      const expiredProxy = await service.createProxy('user789', 'user@real.com', {
+        ttlDays: -1 // Already expired
+      });
+
+      const result = await service.routeInbound(
+        'external@example.com',
+        expiredProxy.proxyEmail,
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/expired/);
+    });
+
+    it('should handle missing proxy address in To field', async () => {
+      const result = await service.routeInbound(
+        'external@example.com',
+        'notaproxy@example.com',
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/No proxy address found/);
+    });
+
+    it('should update proxy usage statistics', async () => {
+      await service.routeInbound(
+        'external@example.com',
+        proxy.proxyEmail,
+        'Test Email',
+        'Hello!'
+      );
+
+      const updatedProxy = await service.getProxyById(proxy.id);
+      expect(updatedProxy?.routingCount).toBe(1);
+      expect(updatedProxy?.lastUsedAt).toBeDefined();
+    });
+  });
+
+  describe('routeOutbound', () => {
+    it('should auto-create proxy for new contact', async () => {
+      const result = await service.routeOutbound(
+        'user123',
+        'user@real.com',
+        'external@example.com',
+        {
+          subject: 'Test',
+          text: 'Hello!',
+          html: '<p>Hello!</p>'
+        }
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.routedTo).toBe('external@example.com');
+      expect(result.proxyUsed).toMatch(/@proxy\.test\.com$/);
+      expect(result.direction).toBe('outbound');
+      expect(result.auditId).toBeDefined();
+    });
+
+    it('should reuse existing proxy for known contact', async () => {
+      // First outbound
+      const result1 = await service.routeOutbound(
+        'user123',
+        'user@real.com',
+        'external@example.com',
+        { subject: 'Test 1', text: 'Hello!' }
+      );
+
+      // Second outbound (should reuse proxy)
+      const result2 = await service.routeOutbound(
+        'user123',
+        'user@real.com',
+        'external@example.com',
+        { subject: 'Test 2', text: 'Hello again!' }
+      );
+
+      expect(result1.proxyUsed).toBe(result2.proxyUsed);
+    });
+
+    it('should handle quota limits during auto-creation', async () => {
+      // Create 10 proxies manually to hit limit
+      for (let i = 0; i < 10; i++) {
+        await service.createProxy('user123', `user${i}@real.com`);
+      }
+
+      // Auto-create should fail due to quota
+      await expect(
+        service.routeOutbound(
+          'user123',
+          'user@real.com',
+          'external@example.com',
+          { subject: 'Test', text: 'Hello!' }
+        )
+      ).rejects.toThrow(/maximum proxy limit/);
+    });
+
+    it('should reject inactive proxy during outbound routing', async () => {
+      // Create and then deactivate proxy
+      const proxy = await service.createProxy('user123', 'user@real.com', {
+        externalEmail: 'external@example.com'
+      });
+      await service.deactivateProxy(proxy.id);
+
+      const result = await service.routeOutbound(
+        'user123',
+        'user@real.com',
+        'external@example.com',
+        { subject: 'Test', text: 'Hello!' }
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/inactive/);
+    });
+
+    it('should update proxy usage statistics', async () => {
+      const result = await service.routeOutbound(
+        'user123',
+        'user@real.com',
+        'external@example.com',
+        { subject: 'Test', text: 'Hello!' }
+      );
+
+      // Get the proxy that was created
+      const proxyEmail = result.proxyUsed;
+      if (!proxyEmail) {
+        throw new Error('Proxy email not returned');
+      }
+
+      // Route again to increment count
+      await service.routeOutbound(
+        'user123',
+        'user@real.com',
+        'external@example.com',
+        { subject: 'Test 2', text: 'Hello again!' }
+      );
+
+      // Find the proxy and check usage - we need to query directly since we don't have the ID
+      // The proxy should have routingCount = 2
+      const result3 = await service.routeOutbound(
+        'user123',
+        'user@real.com',
+        'external@example.com',
+        { subject: 'Test 3', text: 'Hello once more!' }
+      );
+
+      expect(result3.success).toBe(true);
+    });
+  });
+
+  describe('deactivateProxy', () => {
+    it('should deactivate a proxy', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com');
+
+      await service.deactivateProxy(proxy.id);
+
+      const updatedProxy = await service.getProxyById(proxy.id);
+      expect(updatedProxy?.status).toBe('inactive');
+    });
+  });
+
+  describe('revokeProxy', () => {
+    it('should revoke a proxy permanently', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com');
+
+      await service.revokeProxy(proxy.id);
+
+      const updatedProxy = await service.getProxyById(proxy.id);
+      expect(updatedProxy?.status).toBe('revoked');
+    });
+  });
+
+  describe('getProxyById', () => {
+    it('should retrieve proxy by ID', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com');
+
+      const retrieved = await service.getProxyById(proxy.id);
+
+      expect(retrieved).toBeDefined();
+      expect(retrieved?.id).toBe(proxy.id);
+      expect(retrieved?.proxyEmail).toBe(proxy.proxyEmail);
+    });
+
+    it('should return null for non-existent proxy', async () => {
+      const retrieved = await service.getProxyById('00000000-0000-0000-0000-000000000000');
+
+      expect(retrieved).toBeNull();
+    });
+  });
+
+  describe('audit logging', () => {
+    it('should create audit entries when enabled', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com');
+
+      const result = await service.routeInbound(
+        'external@example.com',
+        proxy.proxyEmail,
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.auditId).toBeDefined();
+      expect(result.auditId).not.toBe('');
+    });
+
+    it('should not create audit entries when disabled', async () => {
+      const serviceNoAudit = new EmailMaskingService({
+        ...testConfig,
+        auditEnabled: false
+      });
+      await serviceNoAudit.initialize();
+
+      const proxy = await serviceNoAudit.createProxy('user123', 'user@real.com');
+
+      const result = await serviceNoAudit.routeInbound(
+        'external@example.com',
+        proxy.proxyEmail,
+        'Test Email',
+        'Hello!'
+      );
+
+      expect(result.auditId).toBe('');
+
+      await serviceNoAudit.shutdown();
+    });
+  });
+
+  describe('configuration', () => {
+    it('should use default TTL when not specified', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com');
+
+      expect(proxy.expiresAt).toBeDefined();
+      if (proxy.expiresAt) {
+        const expectedExpiry = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+        const diff = Math.abs(proxy.expiresAt.getTime() - expectedExpiry.getTime());
+        expect(diff).toBeLessThan(5000); // Within 5 seconds
+      }
+    });
+
+    it('should create unlimited TTL when set to 0', async () => {
+      const serviceUnlimited = new EmailMaskingService({
+        ...testConfig,
+        defaultTTL: 0
+      });
+      await serviceUnlimited.initialize();
+
+      const proxy = await serviceUnlimited.createProxy('user123', 'user@real.com');
+
+      expect(proxy.expiresAt).toBeUndefined();
+
+      await serviceUnlimited.shutdown();
+    });
+
+    it('should use correct proxy domain', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com');
+
+      expect(proxy.proxyEmail).toContain('@proxy.test.com');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle concurrent proxy creation requests', async () => {
+      const promises = Array.from({ length: 5 }, (_, i) =>
+        service.createProxy('user123', `user${i}@real.com`)
+      );
+
+      const proxies = await Promise.all(promises);
+
+      expect(proxies).toHaveLength(5);
+      const emails = proxies.map(p => p.proxyEmail);
+      const uniqueEmails = new Set(emails);
+      expect(uniqueEmails.size).toBe(5); // All unique
+    });
+
+    it('should handle empty metadata', async () => {
+      const proxy = await service.createProxy('user123', 'user@real.com', {
+        metadata: {}
+      });
+
+      expect(proxy.metadata).toEqual({});
+    });
+
+    it('should handle special characters in email addresses', async () => {
+      const proxy = await service.createProxy('user123', 'user+tag@real.com');
+
+      expect(proxy.realEmail).toBe('user+tag@real.com');
+    });
+  });
+});

package/__tests__/__fixtures__/test-config.ts

@@ -0,0 +1,24 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import type { EmailMaskingConfig } from '../../src/types.js';
+
+export const testConfig: EmailMaskingConfig = {
+  proxyDomain: 'proxy.test.com',
+  database: {
+    host: process.env.POSTGRES_HOST || 'localhost',
+    port: parseInt(process.env.POSTGRES_PORT || '5432'),
+    database: process.env.POSTGRES_DB || 'email_masking_test',
+    user: process.env.POSTGRES_USER || 'postgres',
+    password: process.env.POSTGRES_PASSWORD || 'postgres'
+  },
+  defaultTTL: 30,
+  maxProxiesPerUser: 10,
+  auditEnabled: true,
+  strategy: 'per-contact'
+};