@bernierllc/email-mitm-masking 1.0.0

package/__tests__/__mocks__/database.ts

@@ -0,0 +1,252 @@
+/*
+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 { ProxyAddressRow, RoutingAuditRow } from '../../src/types.js';
+
+/**
+ * In-memory database mock for testing email masking service
+ */
+class MockDatabase {
+  private proxyAddresses: Map<string, ProxyAddressRow> = new Map();
+  private routingAudits: Map<string, RoutingAuditRow> = new Map();
+  private proxyEmailIndex: Map<string, string> = new Map(); // proxy_email -> id
+
+  /**
+   * Reset all data (called between tests)
+   */
+  reset(): void {
+    this.proxyAddresses.clear();
+    this.routingAudits.clear();
+    this.proxyEmailIndex.clear();
+  }
+
+  /**
+   * Execute a SQL query (mocked)
+   */
+  async query<T = any>(sql: string, params: any[] = []): Promise<{ rows: T[] }> {
+    const normalizedSql = sql.trim().toLowerCase();
+
+    // CREATE TABLE statements (schema initialization)
+    if (normalizedSql.includes('create table') || normalizedSql.includes('create index')) {
+      return { rows: [] };
+    }
+
+    // INSERT INTO proxy_addresses
+    if (normalizedSql.includes('insert into proxy_addresses')) {
+      const [
+        proxyEmail,
+        realEmail,
+        userId,
+        externalEmail,
+        conversationId,
+        status,
+        expiresAt,
+        metadata
+      ] = params;
+
+      const id = this.generateUUID();
+      const now = new Date().toISOString();
+
+      const row: ProxyAddressRow = {
+        id,
+        proxy_email: proxyEmail,
+        real_email: realEmail,
+        user_id: userId,
+        external_email: externalEmail,
+        conversation_id: conversationId,
+        status,
+        created_at: now,
+        activated_at: null,
+        expires_at: expiresAt ? new Date(expiresAt).toISOString() : null,
+        last_used_at: null,
+        routing_count: '0',
+        metadata: metadata || '{}'
+      };
+
+      this.proxyAddresses.set(id, row);
+      this.proxyEmailIndex.set(proxyEmail, id);
+
+      return { rows: [row] as T[] };
+    }
+
+    // INSERT INTO routing_audit
+    if (normalizedSql.includes('insert into routing_audit')) {
+      const [
+        proxyId,
+        direction,
+        fromAddress,
+        toAddress,
+        success,
+        error,
+        metadata
+      ] = params;
+
+      const id = this.generateUUID();
+      const now = new Date().toISOString();
+
+      const row: RoutingAuditRow = {
+        id,
+        proxy_id: proxyId,
+        direction,
+        from_address: fromAddress,
+        to_address: toAddress,
+        routed_at: now,
+        success,
+        error: error || null,
+        metadata: metadata || '{}'
+      };
+
+      this.routingAudits.set(id, row);
+
+      return { rows: [{ id }] as T[] };
+    }
+
+    // SELECT * FROM proxy_addresses WHERE id = $1
+    if (normalizedSql.includes('select * from proxy_addresses') && normalizedSql.includes('where id')) {
+      const [id] = params;
+      const row = this.proxyAddresses.get(id);
+      return { rows: row ? [row] as T[] : [] };
+    }
+
+    // SELECT * FROM proxy_addresses WHERE proxy_email = $1
+    if (normalizedSql.includes('select * from proxy_addresses') && normalizedSql.includes('where proxy_email')) {
+      const [proxyEmail] = params;
+      const id = this.proxyEmailIndex.get(proxyEmail);
+      const row = id ? this.proxyAddresses.get(id) : undefined;
+      return { rows: row ? [row] as T[] : [] };
+    }
+
+    // SELECT * FROM proxy_addresses WHERE user_id = $1 AND real_email = $2 AND external_email = $3
+    if (normalizedSql.includes('select * from proxy_addresses') &&
+        normalizedSql.includes('where user_id') &&
+        normalizedSql.includes('real_email') &&
+        normalizedSql.includes('external_email')) {
+      const [userId, realEmail, externalEmail] = params;
+
+      let matches = Array.from(this.proxyAddresses.values()).filter(row =>
+        row.user_id === userId &&
+        row.real_email === realEmail &&
+        row.external_email === externalEmail
+      );
+
+      // Sort by created_at DESC if ORDER BY is present
+      if (normalizedSql.includes('order by created_at desc')) {
+        matches.sort((a, b) => {
+          const dateA = new Date(a.created_at).getTime();
+          const dateB = new Date(b.created_at).getTime();
+          return dateB - dateA; // DESC order
+        });
+      }
+
+      return { rows: matches.slice(0, 1) as T[] }; // LIMIT 1
+    }
+
+    // SELECT COUNT(*) FROM proxy_addresses WHERE user_id = $1 AND status = 'active'
+    if (normalizedSql.includes('select count(*)') && normalizedSql.includes('from proxy_addresses')) {
+      const [userId] = params;
+
+      const count = Array.from(this.proxyAddresses.values()).filter(row =>
+        row.user_id === userId && row.status === 'active'
+      ).length;
+
+      return { rows: [{ count: count.toString() }] as T[] };
+    }
+
+    // UPDATE proxy_addresses SET status = $1 WHERE id = $2
+    if (normalizedSql.includes('update proxy_addresses') &&
+        normalizedSql.includes('set status') &&
+        !normalizedSql.includes('routing_count')) {
+      const [status, id] = params;
+      const row = this.proxyAddresses.get(id);
+
+      if (row) {
+        row.status = status;
+        this.proxyAddresses.set(id, row);
+      }
+
+      return { rows: [] };
+    }
+
+    // UPDATE proxy_addresses SET routing_count = routing_count + 1, last_used_at = NOW() WHERE id = $1
+    if (normalizedSql.includes('update proxy_addresses') && normalizedSql.includes('routing_count')) {
+      const [id] = params;
+      const row = this.proxyAddresses.get(id);
+
+      if (row) {
+        row.routing_count = (parseInt(row.routing_count) + 1).toString();
+        row.last_used_at = new Date().toISOString();
+        this.proxyAddresses.set(id, row);
+      }
+
+      return { rows: [] };
+    }
+
+    // UPDATE proxy_addresses SET status = 'expired' WHERE expires_at < NOW() AND status = 'active'
+    if (normalizedSql.includes('update proxy_addresses') && normalizedSql.includes('expires_at < now()')) {
+      const now = new Date();
+
+      Array.from(this.proxyAddresses.values()).forEach(row => {
+        if (row.status === 'active' && row.expires_at) {
+          const expiresAt = new Date(row.expires_at);
+          if (expiresAt < now) {
+            row.status = 'expired';
+          }
+        }
+      });
+
+      return { rows: [] };
+    }
+
+    // Fallback for unhandled queries
+    console.warn('Unhandled mock query:', normalizedSql, params);
+    return { rows: [] };
+  }
+
+  /**
+   * Generate a UUID v4
+   */
+  private generateUUID(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === 'x' ? r : (r & 0x3 | 0x8);
+      return v.toString(16);
+    });
+  }
+}
+
+// Singleton instance
+const mockDb = new MockDatabase();
+
+/**
+ * Mock Pool class that mimics pg.Pool
+ */
+export class Pool {
+  async query<T = any>(sql: string, params: any[] = []): Promise<{ rows: T[] }> {
+    return mockDb.query<T>(sql, params);
+  }
+
+  async end(): Promise<void> {
+    // No-op for mock
+  }
+}
+
+/**
+ * Initialize database schema (no-op in mock)
+ */
+export async function initializeDatabase(_pool: Pool): Promise<void> {
+  // Schema is implicitly created in memory
+  await mockDb.query('CREATE TABLE proxy_addresses');
+  await mockDb.query('CREATE TABLE routing_audit');
+}
+
+/**
+ * Reset mock database between tests
+ */
+export function resetMockDatabase(): void {
+  mockDb.reset();
+}

package/__tests__/setup.ts

@@ -0,0 +1,16 @@
+/*
+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 { resetMockDatabase } from './__mocks__/database.js';
+
+/**
+ * Reset mock database before each test
+ */
+beforeEach(() => {
+  resetMockDatabase();
+});

package/dist/EmailMaskingService.d.ts

@@ -0,0 +1,90 @@
+import type { EmailMaskingConfig, ProxyAddress, RoutingResult, CreateProxyOptions } from './types.js';
+/**
+ * Email masking and man-in-the-middle routing service
+ */
+export declare class EmailMaskingService {
+    private config;
+    private db;
+    private cleanupInterval?;
+    constructor(config: EmailMaskingConfig);
+    /**
+     * Initialize the masking service
+     */
+    initialize(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Create a new proxy email address
+     */
+    createProxy(userId: string, realEmail: string, options?: CreateProxyOptions): Promise<ProxyAddress>;
+    /**
+     * Route inbound email (external → real address)
+     */
+    routeInbound(from: string, to: string, _subject: string, _text?: string, _html?: string): Promise<RoutingResult>;
+    /**
+     * Route outbound email (real address → external via proxy)
+     */
+    routeOutbound(userId: string, realEmail: string, externalEmail: string, _emailContent: {
+        subject: string;
+        text?: string;
+        html?: string;
+    }): Promise<RoutingResult>;
+    /**
+     * Deactivate a proxy address
+     */
+    deactivateProxy(proxyId: string): Promise<void>;
+    /**
+     * Revoke a proxy address permanently
+     */
+    revokeProxy(proxyId: string): Promise<void>;
+    /**
+     * Get proxy by ID
+     */
+    getProxyById(proxyId: string): Promise<ProxyAddress | null>;
+    /**
+     * Get proxy by email address
+     */
+    private getProxyByEmail;
+    /**
+     * Get proxy for specific user-contact pair
+     */
+    private getProxyForContact;
+    /**
+     * Update proxy usage statistics
+     */
+    private updateProxyUsage;
+    /**
+     * Audit a routing decision
+     */
+    private auditRouting;
+    /**
+     * Map database row to ProxyAddress
+     */
+    private mapProxyRow;
+    /**
+     * Get user's proxy count
+     */
+    private getUserProxyCount;
+    /**
+     * Expire a proxy
+     */
+    private expireProxy;
+    /**
+     * Start cleanup job for expired proxies
+     */
+    private startCleanupJob;
+    /**
+     * Cleanup expired proxies
+     */
+    private cleanupExpiredProxies;
+    /**
+     * Extract proxy address from To field
+     */
+    private extractProxyAddress;
+    /**
+     * Generate secure proxy token
+     */
+    private generateProxyToken;
+}

package/dist/EmailMaskingService.js

@@ -0,0 +1,316 @@
+"use strict";
+/*
+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.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailMaskingService = void 0;
+const pg_1 = require("pg");
+const database_js_1 = require("./database.js");
+/**
+ * Email masking and man-in-the-middle routing service
+ */
+class EmailMaskingService {
+    constructor(config) {
+        this.config = config;
+        this.db = new pg_1.Pool({
+            host: config.database.host,
+            port: config.database.port,
+            database: config.database.database,
+            user: config.database.user,
+            password: config.database.password,
+        });
+    }
+    /**
+     * Initialize the masking service
+     */
+    async initialize() {
+        // Initialize database schema
+        await (0, database_js_1.initializeDatabase)(this.db);
+        // Start cleanup job for expired proxies
+        this.startCleanupJob();
+    }
+    /**
+     * Cleanup resources
+     */
+    async shutdown() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+        }
+        await this.db.end();
+    }
+    /**
+     * Create a new proxy email address
+     */
+    async createProxy(userId, realEmail, options) {
+        // Validate user's proxy quota
+        const userProxies = await this.getUserProxyCount(userId);
+        const maxProxies = this.config.maxProxiesPerUser || 0;
+        if (maxProxies > 0 && userProxies >= maxProxies) {
+            throw new Error(`User ${userId} has reached maximum proxy limit (${maxProxies})`);
+        }
+        // Generate secure proxy token
+        const proxyToken = this.generateProxyToken();
+        const proxyEmail = `${userId}-${proxyToken}@${this.config.proxyDomain}`;
+        // Calculate expiration
+        const ttl = options?.ttlDays !== undefined ? options.ttlDays : (this.config.defaultTTL || 0);
+        const expiresAt = ttl !== 0
+            ? new Date(Date.now() + ttl * 24 * 60 * 60 * 1000)
+            : null;
+        // Insert proxy record
+        const result = await this.db.query(`INSERT INTO proxy_addresses
+       (proxy_email, real_email, user_id, external_email, conversation_id, status, expires_at, metadata)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       RETURNING *`, [
+            proxyEmail,
+            realEmail,
+            userId,
+            options?.externalEmail || null,
+            options?.conversationId || null,
+            'active',
+            expiresAt,
+            JSON.stringify(options?.metadata || {})
+        ]);
+        return this.mapProxyRow(result.rows[0]);
+    }
+    /**
+     * Route inbound email (external → real address)
+     */
+    async routeInbound(from, to, _subject, _text, _html) {
+        const toAddress = this.extractProxyAddress(to);
+        if (!toAddress) {
+            return {
+                success: false,
+                direction: 'inbound',
+                error: 'No proxy address found in To field'
+            };
+        }
+        // Look up proxy
+        const proxy = await this.getProxyByEmail(toAddress);
+        if (!proxy) {
+            return {
+                success: false,
+                direction: 'inbound',
+                error: `Proxy address not found: ${toAddress}`
+            };
+        }
+        // Validate proxy status
+        if (proxy.status !== 'active') {
+            return {
+                success: false,
+                direction: 'inbound',
+                error: `Proxy is ${proxy.status}: ${toAddress}`
+            };
+        }
+        // Check expiration
+        if (proxy.expiresAt && proxy.expiresAt < new Date()) {
+            await this.expireProxy(proxy.id);
+            return {
+                success: false,
+                direction: 'inbound',
+                error: `Proxy expired: ${toAddress}`
+            };
+        }
+        // Update proxy usage
+        await this.updateProxyUsage(proxy.id);
+        // Audit the routing
+        const auditId = await this.auditRouting({
+            proxyId: proxy.id,
+            direction: 'inbound',
+            fromAddress: from,
+            toAddress: proxy.realEmail,
+            success: true
+        });
+        return {
+            success: true,
+            routedTo: proxy.realEmail,
+            proxyUsed: toAddress,
+            direction: 'inbound',
+            auditId
+        };
+    }
+    /**
+     * Route outbound email (real address → external via proxy)
+     */
+    async routeOutbound(userId, realEmail, externalEmail, _emailContent) {
+        // Find or create proxy for this user-external pair
+        let proxy = await this.getProxyForContact(userId, realEmail, externalEmail);
+        if (!proxy) {
+            // Auto-create proxy for outbound routing
+            proxy = await this.createProxy(userId, realEmail, {
+                externalEmail,
+                metadata: { autoCreated: true, direction: 'outbound' }
+            });
+        }
+        // Validate proxy status
+        if (proxy.status !== 'active') {
+            return {
+                success: false,
+                direction: 'outbound',
+                error: `Proxy is ${proxy.status}`
+            };
+        }
+        // Update proxy usage
+        await this.updateProxyUsage(proxy.id);
+        // Audit the routing
+        const auditId = await this.auditRouting({
+            proxyId: proxy.id,
+            direction: 'outbound',
+            fromAddress: realEmail,
+            toAddress: externalEmail,
+            success: true
+        });
+        return {
+            success: true,
+            routedTo: externalEmail,
+            proxyUsed: proxy.proxyEmail,
+            direction: 'outbound',
+            auditId
+        };
+    }
+    /**
+     * Deactivate a proxy address
+     */
+    async deactivateProxy(proxyId) {
+        await this.db.query('UPDATE proxy_addresses SET status = $1 WHERE id = $2', ['inactive', proxyId]);
+    }
+    /**
+     * Revoke a proxy address permanently
+     */
+    async revokeProxy(proxyId) {
+        await this.db.query('UPDATE proxy_addresses SET status = $1 WHERE id = $2', ['revoked', proxyId]);
+    }
+    /**
+     * Get proxy by ID
+     */
+    async getProxyById(proxyId) {
+        const result = await this.db.query('SELECT * FROM proxy_addresses WHERE id = $1', [proxyId]);
+        return result.rows.length > 0 ? this.mapProxyRow(result.rows[0]) : null;
+    }
+    /**
+     * Get proxy by email address
+     */
+    async getProxyByEmail(proxyEmail) {
+        const result = await this.db.query('SELECT * FROM proxy_addresses WHERE proxy_email = $1', [proxyEmail]);
+        return result.rows.length > 0 ? this.mapProxyRow(result.rows[0]) : null;
+    }
+    /**
+     * Get proxy for specific user-contact pair
+     */
+    async getProxyForContact(userId, realEmail, externalEmail) {
+        const result = await this.db.query(`SELECT * FROM proxy_addresses
+       WHERE user_id = $1
+       AND real_email = $2
+       AND external_email = $3
+       ORDER BY created_at DESC
+       LIMIT 1`, [userId, realEmail, externalEmail]);
+        return result.rows.length > 0 ? this.mapProxyRow(result.rows[0]) : null;
+    }
+    /**
+     * Update proxy usage statistics
+     */
+    async updateProxyUsage(proxyId) {
+        await this.db.query(`UPDATE proxy_addresses
+       SET routing_count = routing_count + 1, last_used_at = NOW()
+       WHERE id = $1`, [proxyId]);
+    }
+    /**
+     * Audit a routing decision
+     */
+    async auditRouting(audit) {
+        if (!this.config.auditEnabled) {
+            return '';
+        }
+        const result = await this.db.query(`INSERT INTO routing_audit
+       (proxy_id, direction, from_address, to_address, success, error, metadata)
+       VALUES ($1, $2, $3, $4, $5, $6, $7)
+       RETURNING id`, [
+            audit.proxyId,
+            audit.direction,
+            audit.fromAddress,
+            audit.toAddress,
+            audit.success,
+            audit.error || null,
+            JSON.stringify(audit.metadata || {})
+        ]);
+        return result.rows[0].id;
+    }
+    /**
+     * Map database row to ProxyAddress
+     */
+    mapProxyRow(row) {
+        return {
+            id: row.id,
+            proxyEmail: row.proxy_email,
+            realEmail: row.real_email,
+            userId: row.user_id,
+            externalEmail: row.external_email || undefined,
+            conversationId: row.conversation_id || undefined,
+            status: row.status,
+            createdAt: new Date(row.created_at),
+            activatedAt: row.activated_at ? new Date(row.activated_at) : undefined,
+            expiresAt: row.expires_at ? new Date(row.expires_at) : undefined,
+            lastUsedAt: row.last_used_at ? new Date(row.last_used_at) : undefined,
+            routingCount: parseInt(row.routing_count) || 0,
+            metadata: row.metadata ? JSON.parse(row.metadata) : {}
+        };
+    }
+    /**
+     * Get user's proxy count
+     */
+    async getUserProxyCount(userId) {
+        const result = await this.db.query(`SELECT COUNT(*) as count FROM proxy_addresses
+       WHERE user_id = $1 AND status = 'active'`, [userId]);
+        return parseInt(result.rows[0].count) || 0;
+    }
+    /**
+     * Expire a proxy
+     */
+    async expireProxy(proxyId) {
+        await this.db.query('UPDATE proxy_addresses SET status = $1 WHERE id = $2', ['expired', proxyId]);
+    }
+    /**
+     * Start cleanup job for expired proxies
+     */
+    startCleanupJob() {
+        // Run every hour
+        this.cleanupInterval = setInterval(() => {
+            void this.cleanupExpiredProxies();
+        }, 60 * 60 * 1000); // 1 hour
+    }
+    /**
+     * Cleanup expired proxies
+     */
+    async cleanupExpiredProxies() {
+        await this.db.query(`UPDATE proxy_addresses
+       SET status = 'expired'
+       WHERE expires_at < NOW() AND status = 'active'`);
+    }
+    /**
+     * Extract proxy address from To field
+     */
+    extractProxyAddress(to) {
+        const proxyDomain = this.config.proxyDomain;
+        if (to.includes(`@${proxyDomain}`)) {
+            // Extract email from "Name <email>" format
+            const match = to.match(/<(.+?)>/) || [null, to];
+            return match[1];
+        }
+        return null;
+    }
+    /**
+     * Generate secure proxy token
+     */
+    generateProxyToken() {
+        const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+        let token = '';
+        for (let i = 0; i < 16; i++) {
+            token += chars.charAt(Math.floor(Math.random() * chars.length));
+        }
+        return token;
+    }
+}
+exports.EmailMaskingService = EmailMaskingService;

package/dist/database.d.ts

@@ -0,0 +1,5 @@
+import { Pool } from 'pg';
+/**
+ * Initialize database schema for email masking
+ */
+export declare function initializeDatabase(pool: Pool): Promise<void>;