@bernierllc/email-mitm-masking 1.0.0

package/src/EmailMaskingService.ts

@@ -0,0 +1,425 @@
+/*
+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 { Pool } from 'pg';
+import type {
+  EmailMaskingConfig,
+  ProxyAddress,
+  RoutingResult,
+  RoutingAudit,
+  CreateProxyOptions,
+  ProxyAddressRow
+} from './types.js';
+import { initializeDatabase } from './database.js';
+
+/**
+ * Email masking and man-in-the-middle routing service
+ */
+export class EmailMaskingService {
+  private config: EmailMaskingConfig;
+  private db: Pool;
+  private cleanupInterval?: NodeJS.Timeout;
+
+  constructor(config: EmailMaskingConfig) {
+    this.config = config;
+    this.db = new 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(): Promise<void> {
+    // Initialize database schema
+    await initializeDatabase(this.db);
+
+    // Start cleanup job for expired proxies
+    this.startCleanupJob();
+  }
+
+  /**
+   * Cleanup resources
+   */
+  async shutdown(): Promise<void> {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+    await this.db.end();
+  }
+
+  /**
+   * Create a new proxy email address
+   */
+  async createProxy(
+    userId: string,
+    realEmail: string,
+    options?: CreateProxyOptions
+  ): Promise<ProxyAddress> {
+    // 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<ProxyAddressRow>(
+      `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: string,
+    to: string,
+    _subject: string,
+    _text?: string,
+    _html?: string
+  ): Promise<RoutingResult> {
+    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: string,
+    realEmail: string,
+    externalEmail: string,
+    _emailContent: { subject: string; text?: string; html?: string }
+  ): Promise<RoutingResult> {
+    // 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: string): Promise<void> {
+    await this.db.query(
+      'UPDATE proxy_addresses SET status = $1 WHERE id = $2',
+      ['inactive', proxyId]
+    );
+  }
+
+  /**
+   * Revoke a proxy address permanently
+   */
+  async revokeProxy(proxyId: string): Promise<void> {
+    await this.db.query(
+      'UPDATE proxy_addresses SET status = $1 WHERE id = $2',
+      ['revoked', proxyId]
+    );
+  }
+
+  /**
+   * Get proxy by ID
+   */
+  async getProxyById(proxyId: string): Promise<ProxyAddress | null> {
+    const result = await this.db.query<ProxyAddressRow>(
+      'SELECT * FROM proxy_addresses WHERE id = $1',
+      [proxyId]
+    );
+
+    return result.rows.length > 0 ? this.mapProxyRow(result.rows[0]) : null;
+  }
+
+  /**
+   * Get proxy by email address
+   */
+  private async getProxyByEmail(proxyEmail: string): Promise<ProxyAddress | null> {
+    const result = await this.db.query<ProxyAddressRow>(
+      '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
+   */
+  private async getProxyForContact(
+    userId: string,
+    realEmail: string,
+    externalEmail: string
+  ): Promise<ProxyAddress | null> {
+    const result = await this.db.query<ProxyAddressRow>(
+      `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
+   */
+  private async updateProxyUsage(proxyId: string): Promise<void> {
+    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
+   */
+  private async auditRouting(
+    audit: Omit<RoutingAudit, 'id' | 'routedAt'>
+  ): Promise<string> {
+    if (!this.config.auditEnabled) {
+      return '';
+    }
+
+    const result = await this.db.query<{ id: string }>(
+      `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
+   */
+  private mapProxyRow(row: ProxyAddressRow): ProxyAddress {
+    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 as 'active' | 'inactive' | 'expired' | 'revoked',
+      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) as Record<string, unknown> : {}
+    };
+  }
+
+  /**
+   * Get user's proxy count
+   */
+  private async getUserProxyCount(userId: string): Promise<number> {
+    const result = await this.db.query<{ count: string }>(
+      `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
+   */
+  private async expireProxy(proxyId: string): Promise<void> {
+    await this.db.query(
+      'UPDATE proxy_addresses SET status = $1 WHERE id = $2',
+      ['expired', proxyId]
+    );
+  }
+
+  /**
+   * Start cleanup job for expired proxies
+   */
+  private startCleanupJob(): void {
+    // Run every hour
+    this.cleanupInterval = setInterval(() => {
+      void this.cleanupExpiredProxies();
+    }, 60 * 60 * 1000); // 1 hour
+  }
+
+  /**
+   * Cleanup expired proxies
+   */
+  private async cleanupExpiredProxies(): Promise<void> {
+    await this.db.query(
+      `UPDATE proxy_addresses
+       SET status = 'expired'
+       WHERE expires_at < NOW() AND status = 'active'`
+    );
+  }
+
+  /**
+   * Extract proxy address from To field
+   */
+  private extractProxyAddress(to: string): string | null {
+    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
+   */
+  private generateProxyToken(): string {
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let token = '';
+    for (let i = 0; i < 16; i++) {
+      token += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return token;
+  }
+}

package/src/database.ts

@@ -0,0 +1,69 @@
+/*
+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 { Pool } from 'pg';
+
+/**
+ * Initialize database schema for email masking
+ */
+export async function initializeDatabase(pool: Pool): Promise<void> {
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS proxy_addresses (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      proxy_email TEXT UNIQUE NOT NULL,
+      real_email TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      external_email TEXT,
+      conversation_id TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+      activated_at TIMESTAMP,
+      expires_at TIMESTAMP,
+      last_used_at TIMESTAMP,
+      routing_count INTEGER NOT NULL DEFAULT 0,
+      metadata JSONB
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_proxy_email ON proxy_addresses(proxy_email);
+    CREATE INDEX IF NOT EXISTS idx_user_id ON proxy_addresses(user_id);
+    CREATE INDEX IF NOT EXISTS idx_real_email ON proxy_addresses(real_email);
+    CREATE INDEX IF NOT EXISTS idx_status ON proxy_addresses(status);
+    CREATE INDEX IF NOT EXISTS idx_expires_at ON proxy_addresses(expires_at) WHERE status = 'active';
+
+    CREATE TABLE IF NOT EXISTS routing_audit (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      proxy_id UUID NOT NULL,
+      direction TEXT NOT NULL,
+      from_address TEXT NOT NULL,
+      to_address TEXT NOT NULL,
+      routed_at TIMESTAMP NOT NULL DEFAULT NOW(),
+      success BOOLEAN NOT NULL,
+      error TEXT,
+      metadata JSONB
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_audit_proxy_id ON routing_audit(proxy_id);
+    CREATE INDEX IF NOT EXISTS idx_routed_at ON routing_audit(routed_at);
+    CREATE INDEX IF NOT EXISTS idx_direction ON routing_audit(direction);
+
+    CREATE TABLE IF NOT EXISTS masking_rules (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      user_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      criteria TEXT NOT NULL,
+      action TEXT NOT NULL,
+      priority INTEGER NOT NULL DEFAULT 0,
+      enabled BOOLEAN NOT NULL DEFAULT true,
+      created_at TIMESTAMP NOT NULL DEFAULT NOW()
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_rules_user_id ON masking_rules(user_id);
+    CREATE INDEX IF NOT EXISTS idx_priority ON masking_rules(priority);
+    CREATE INDEX IF NOT EXISTS idx_enabled ON masking_rules(enabled);
+  `);
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/*
+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.
+*/
+
+export { EmailMaskingService } from './EmailMaskingService.js';
+export type {
+  EmailMaskingConfig,
+  DatabaseConfig,
+  ProxyAddress,
+  MaskingRule,
+  RoutingResult,
+  RoutingAudit,
+  MaskingResult,
+  CreateProxyOptions,
+  EmailContent
+} from './types.js';

package/src/types.ts

@@ -0,0 +1,200 @@
+/*
+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.
+*/
+
+/**
+ * Configuration for email masking service
+ */
+export interface EmailMaskingConfig {
+  /** Proxy domain for masked addresses (e.g., proxy.example.com) */
+  proxyDomain: string;
+
+  /** Database connection for proxy storage */
+  database: DatabaseConfig;
+
+  /** Default TTL for proxy addresses (in days, 0 = unlimited) */
+  defaultTTL?: number;
+
+  /** Maximum proxies per user (0 = unlimited) */
+  maxProxiesPerUser?: number;
+
+  /** Enable audit logging */
+  auditEnabled?: boolean;
+
+  /** Masking strategy */
+  strategy?: 'per-user' | 'per-contact' | 'per-conversation';
+}
+
+/**
+ * Database configuration
+ */
+export interface DatabaseConfig {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+}
+
+/**
+ * Proxy email address record
+ */
+export interface ProxyAddress {
+  /** Unique proxy identifier */
+  id: string;
+
+  /** Proxy email address (e.g., user-abc123@proxy.domain.com) */
+  proxyEmail: string;
+
+  /** Real user email address */
+  realEmail: string;
+
+  /** User identifier */
+  userId: string;
+
+  /** Optional external contact email (for per-contact masking) */
+  externalEmail?: string;
+
+  /** Optional conversation identifier (for per-conversation masking) */
+  conversationId?: string;
+
+  /** Proxy status */
+  status: 'active' | 'inactive' | 'expired' | 'revoked';
+
+  /** Creation timestamp */
+  createdAt: Date;
+
+  /** Activation timestamp */
+  activatedAt?: Date;
+
+  /** Expiration timestamp (null = no expiration) */
+  expiresAt?: Date;
+
+  /** Last used timestamp */
+  lastUsedAt?: Date;
+
+  /** Routing count */
+  routingCount: number;
+
+  /** Metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Masking rule configuration
+ */
+export interface MaskingRule {
+  /** Rule identifier */
+  id: string;
+
+  /** User identifier */
+  userId: string;
+
+  /** Rule type */
+  type: 'domain' | 'address' | 'pattern';
+
+  /** Match criteria */
+  criteria: string;
+
+  /** Action (mask or allow) */
+  action: 'mask' | 'allow';
+
+  /** Priority (higher = evaluated first) */
+  priority: number;
+
+  /** Enabled flag */
+  enabled: boolean;
+}
+
+/**
+ * Routing result
+ */
+export interface RoutingResult {
+  success: boolean;
+  routedTo?: string;
+  proxyUsed?: string;
+  direction: 'inbound' | 'outbound';
+  error?: string;
+  auditId?: string;
+}
+
+/**
+ * Audit entry
+ */
+export interface RoutingAudit {
+  id: string;
+  proxyId: string;
+  direction: 'inbound' | 'outbound';
+  fromAddress: string;
+  toAddress: string;
+  routedAt: Date;
+  success: boolean;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result wrapper for masking operations
+ */
+export interface MaskingResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+/**
+ * Options for creating a proxy
+ */
+export interface CreateProxyOptions {
+  externalEmail?: string;
+  conversationId?: string;
+  ttlDays?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Email content for outbound routing
+ */
+export interface EmailContent {
+  subject: string;
+  text?: string;
+  html?: string;
+}
+
+/**
+ * Database row type for proxy addresses
+ */
+export interface ProxyAddressRow {
+  id: string;
+  proxy_email: string;
+  real_email: string;
+  user_id: string;
+  external_email: string | null;
+  conversation_id: string | null;
+  status: string;
+  created_at: string;
+  activated_at: string | null;
+  expires_at: string | null;
+  last_used_at: string | null;
+  routing_count: string;
+  metadata: string | null;
+}
+
+/**
+ * Database row type for routing audit
+ */
+export interface RoutingAuditRow {
+  id: string;
+  proxy_id: string;
+  direction: string;
+  from_address: string;
+  to_address: string;
+  routed_at: string;
+  success: boolean;
+  error: string | null;
+  metadata: string | null;
+}