@bernierllc/电子邮件-mitm-masking

电子邮件口罩和中间人行道服务,用于以隐私为重点的电子邮件通信. 提供代理电子邮件地址,以掩盖真实的用户地址,同时双向传递信息,同时提供完整的审计线索和生命周期管理.

安装

npm install @bernierllc/email-mitm-masking

特征

• 🔒 隐私第一: 生成代理电子邮件地址以掩盖真实的用户地址
• ↔️ 双向旋转: 传送电子邮件(外部 )和传送电子邮件(真实 )
• 🔄 生命周期管理: 创建、激活、停用、过期并撤销代理
• 📊 审计轨迹: 完成合规和调试的路由审计日志
• 🎯 灵活战略: 支持每个用户、每个接触人和每个交谈人的口罩
• ⏱️ TTL 支持: 自动到期, 时间可配置
• 📈 用法跟踪: 监测代理用户和路线统计
• 🔒 配额执行: 防止使用每个用户的代理限制的滥用

使用量

基本设置

import { EmailMaskingService } from '@bernierllc/email-mitm-masking';

const service = new EmailMaskingService({
  proxyDomain: 'proxy.example.com',
  database: {
    host: 'localhost',
    port: 5432,
    database: 'email_masking',
    user: 'postgres',
    password: process.env.DB_PASSWORD
  },
  defaultTTL: 365,          // 365 days
  maxProxiesPerUser: 100,    // 100 proxies per user
  auditEnabled: true,        // Enable audit logging
  strategy: 'per-contact'    // Create one proxy per contact
});

await service.initialize();

创建代理电子邮件地址

// Create a basic proxy
const proxy = await service.createProxy(
  'user123',
  '[email protected]'
);

console.log(proxy.proxyEmail);
// Output: [email protected]

// Create proxy with custom TTL
const tempProxy = await service.createProxy(
  'user123',
  '[email protected]',
  {
    ttlDays: 30,  // Expires in 30 days
    externalEmail: '[email protected]',
    metadata: { source: 'signup-form', priority: 'high' }
  }
);

路由输入电子邮件 (Webhook 处理器)

import express from 'express';

const app = express();

app.post('/webhooks/inbound-email', express.text({ type: '*/*' }), async (req, res) => {
  const { from, to, subject, text, html } = parseEmail(req.body);

  const result = await service.routeInbound(from, to, subject, text, html);

  if (result.success) {
    res.json({
      status: 'routed',
      to: result.routedTo,
      auditId: result.auditId
    });
  } else {
    res.status(400).json({
      status: 'failed',
      error: result.error
    });
  }
});

Route Outround 电子邮件( 通过代理服务器检索)

async function sendReplyViaProxy(
  userId: string,
  userEmail: string,
  recipientEmail: string,
  message: string
) {
  const result = await service.routeOutbound(
    userId,
    userEmail,
    recipientEmail,
    {
      subject: 'Re: Your inquiry',
      text: message,
      html: `<p>${message}</p>`
    }
  );

  if (result.success) {
    console.log(`Reply sent via proxy: ${result.proxyUsed}`);
  } else {
    console.error(`Failed to send reply: ${result.error}`);
  }

  return result;
}

代理生命周期管理

// Create proxy with 30-day expiration
const proxy = await service.createProxy('user456', '[email protected]', {
  ttlDays: 30
});

// Use the proxy for routing...
await service.routeInbound(from, proxy.proxyEmail, subject);

// Deactivate when temporarily not needed
await service.deactivateProxy(proxy.id);

// Permanently revoke
await service.revokeProxy(proxy.id);

// Retrieve proxy details
const proxyDetails = await service.getProxyById(proxy.id);
console.log(proxyDetails.status); // 'revoked'

API 参考

电子邮件 服务

new EmailMaskingService(config)

创建新的邮件掩码服务实例 .

参数:

• config.proxyDomain (字符串,要求): 代理地址的域名
• config.database (数据库Config, 需要): PostgreSQL 连接配置
• config.defaultTTL (数目,可选): 以天为单位的默认 TTL (0 = 无限, 默认: 0)
• config.maxProxiesPerUser (数目,可选): 每个用户最大代理( 0 = 无限, 默认: 0)
• config.auditEnabled (布尔,可选): 启用审计记录( 默认: 真)
• config.strategy (“ per- user” ++ “ per- user ” ++ “ per- user ” , 可选) : 遮罩策略( 默认: “ per- user ” )

initialize(): Promise<void>

初始化服务,创建数据库计划,并启动清理工作.

createProxy(userId, realEmail, options?): Promise<ProxyAddress>

创建新的代理电子邮件地址 .

参数:

• userId (字符串):用户标识符
• realEmail (字符串):真实的用户电子邮件地址
• options.ttlDays (数目,可选):天用TTL
• options.externalEmail (弦,可选): 外部联系电子邮件
• options.conversationId (弦,可选): 对话标识符
• options.metadata (对象,可选): 自定义元数据

回返情况: ProxyAddress 对象

routeInbound(from, to, subject, text?, html?): Promise<RoutingResult>

通过代理将外部发送者传送到真实地址的电子邮件.

参数:

• from (字符串):外部发送地址
• to (字符串):代理电子邮件地址
• subject (字符串):电子邮件主题
• text (弦,可选): 纯文本正文
• html (字符串,可选):HTML正文

回返情况: RoutingResult 有路由状态和审计ID

routeOutbound(userId, realEmail, externalEmail, emailContent): Promise<RoutingResult>

通过代理向外部接收者发送邮件.

参数:

• userId (字符串):用户标识符
• realEmail (字符串):真实的用户电子邮件地址
• externalEmail (字符串):外部收件人地址
• emailContent.subject (字符串):电子邮件主题
• emailContent.text (弦,可选): 纯文本正文
• emailContent.html (字符串,可选):HTML正文

回返情况: RoutingResult 有路由状态和审计ID

deactivateProxy(proxyId): Promise<void>

取消代理地址( 可重新启动) .

revokeProxy(proxyId): Promise<void>

永久取消代理地址 .

getProxyById(proxyId): Promise<ProxyAddress | null>

通过ID获取代理细节.

shutdown(): Promise<void>

清理资源并关闭数据库连接.

配置

环境变量

# EMAIL_MITM_MASKING Configuration
EMAIL_MASKING_PROXY_DOMAIN=proxy.example.com
EMAIL_MASKING_DB_HOST=localhost
EMAIL_MASKING_DB_PORT=5432
EMAIL_MASKING_DB_NAME=email_masking
EMAIL_MASKING_DB_USER=postgres
EMAIL_MASKING_DB_PASSWORD=secret
EMAIL_MASKING_DEFAULT_TTL=365           # Days (0 = unlimited)
EMAIL_MASKING_MAX_PROXIES_PER_USER=100  # Max per user (0 = unlimited)
EMAIL_MASKING_AUDIT_ENABLED=true        # Enable audit logging
EMAIL_MASKING_STRATEGY=per-contact      # per-user, per-contact, per-conversation

数据库Schema

该服务会自动创建以下 PostgreSQL 表格 :

proxy_addresses

存储带有生命周期管理的代理电子邮件地址记录.

routing_audit

所有路线决定的审计线索(在允许审计时).

masking_rules

用户定义的面具规则(保留给将来使用).

完整计划定义见计划文件.

安全考虑

1. 安全托肯生成: 为代理地址使用加密安全随机符号
2. 电子邮件验证: 校验代理域来防止 spoofing
3. 配额执行: 通过用户代理限制防止滥用
4. 审计轨迹: 完成合规和调试的审计日志
5. 状态验证: 在路由前检查代理状态( 活动, 过期, 取消)
6. SQL 注射保护: 在整个过程中使用参数化查询
7. 隐私保障: 真实的电子邮件地址从未在外部电子邮件中被曝光
8. 自动清理: 小时工作自动过期

一体化状况

• 锁定器:综合 -- -- 所有业务的结构化伐木
• 多克套装: 准备就绪 - 用类型Doc完成 API 文档
• 从不: 不适用 - 服务包, NeverHub 集成可选

业绩

• 代理创建:~50ms(包括数据库插入)
• 运行搜索:~10ms(索引查询)
• 审计日志: ~5ms( 启用时)
• 清理任务: 小时运行, 流程已过期 批量代理

处理错误

所有方法返回结构化结果:

interface RoutingResult {
  success: boolean;
  routedTo?: string;
  proxyUsed?: string;
  direction: 'inbound' | 'outbound';
  error?: string;
  auditId?: string;
}

实例错误处理 :

const result = await service.routeInbound(from, to, subject);

if (!result.success) {
  switch (result.error) {
    case 'Proxy address not found':
      // Handle unknown proxy
      break;
    case 'Proxy is inactive':
      // Handle inactive proxy
      break;
    case 'Proxy expired':
      // Handle expired proxy
      break;
    default:
      // Handle other errors
  }
}

实例

与人接触的面具

const service = new EmailMaskingService({
  proxyDomain: 'proxy.example.com',
  database: dbConfig,
  strategy: 'per-contact'
});

// Each user-contact pair gets a unique proxy
const proxy1 = await service.createProxy('user1', '[email protected]', {
  externalEmail: '[email protected]'
});

const proxy2 = await service.createProxy('user1', '[email protected]', {
  externalEmail: '[email protected]'
});

// Different proxies for different contacts
console.log(proxy1.proxyEmail !== proxy2.proxyEmail); // true

临时代理

// Create proxy that expires in 7 days
const tempProxy = await service.createProxy('user123', '[email protected]', {
  ttlDays: 7,
  metadata: { purpose: 'one-time-signup' }
});

// After 7 days, inbound routing will fail
// Cleanup job will mark it as expired

Webhook 集成( SendGrid)

app.post('/webhooks/sendgrid', express.json(), async (req, res) => {
  const { from, to, subject, text, html } = req.body;

  const result = await service.routeInbound(from, to, subject, text, html);

  res.status(result.success ? 200 : 400).json(result);
});

测试

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests once (CI mode)
npm run test:run

许可证

版权(c)2025 Bernier有限责任公司

这个文件凭有限用途许可证发给客户. 客户端可能使用并修改此代码 仅在项目范围内交付。 。 。 . 未经Bernier有限责任公司书面同意,不得再分配或用于其他产品或商业供货.

相关软件包

依赖关系

• @bernierllc/电子邮件-parser - 分析收到的电子邮件(如有需要)
• @bernierllc/电子邮件发送器 - 发送路由电子邮件(如有需要)
• @bernierllc/crypto-utils - 生成安全代理代用符(倒计时)
• @ bernierllc/ 拖放器 - 结构化伐木
• @bernierllc/ 绝不是适应器 - 服务发现(可选)

套房的一部分

• @bernierllc/电子邮件测试套间 - 完整的电子邮件测试解决方案

支助

关于议题和问题,请参见主要伯尼RLLC工具库.