# @bernierllc/email-mitm-masking 中文文档

规范地址：https://npmcn.com/package/%40bernierllc/email-mitm-masking/

版本：1\.6\.11
npm 元数据更新时间：2026-11-05T01:26:51.207Z
中文译文更新时间：2026-11-07T23:15:33.541Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bernierllc/email-mitm-masking
原文对照：https://npmcn.com/package/%40bernierllc/email-mitm-masking/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：36.3 kB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2025-11-11T02:15:16.616Z
- 最新版本发布：2026-11-05T01:26:51.032Z
- 近 30 天下载量：2072（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

提供电子邮件口罩和中间人行道服务,以进行注重隐私的电子邮件通信

## 安装

```sh
npm install @bernierllc/email-mitm-masking
```

也可以使用：`pnpm add @bernierllc/email-mitm-masking`、`yarn add @bernierllc/email-mitm-masking`、`bun add @bernierllc/email-mitm-masking`

## README

# @bernierllc/电子邮件-mitm-masking

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

## 安装

```bash
npm install @bernierllc/email-mitm-masking
```

## 特征

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

## 使用量

### 基本设置

```typescript
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();
```

### 创建代理电子邮件地址

```typescript
// Create a basic proxy
const proxy = await service.createProxy(
  'user123',
  'user@real.com'
);

console.log(proxy.proxyEmail);
// Output: user123-a1b2c3d4e5f6@proxy.example.com

// Create proxy with custom TTL
const tempProxy = await service.createProxy(
  'user123',
  'user@real.com',
  {
    ttlDays: 30,  // Expires in 30 days
    externalEmail: 'contact@external.com',
    metadata: { source: 'signup-form', priority: 'high' }
  }
);
```

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

```typescript
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 电子邮件( 通过代理服务器检索)

```typescript
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;
}
```

### 代理生命周期管理

```typescript
// Create proxy with 30-day expiration
const proxy = await service.createProxy('user456', 'user@example.com', {
  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>`

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

## 配置

### 环境变量

```bash
# 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( 启用时)
-   **清理任务**: 小时运行, 流程已过期 批量代理

## 处理错误

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

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

实例错误处理 :

```typescript
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
  }
}
```

## 实例

### 与人接触的面具

```typescript
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', 'user@real.com', {
  externalEmail: 'alice@example.com'
});

const proxy2 = await service.createProxy('user1', 'user@real.com', {
  externalEmail: 'bob@example.com'
});

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

### 临时代理

```typescript
// Create proxy that expires in 7 days
const tempProxy = await service.createProxy('user123', 'user@real.com', {
  ttlDays: 7,
  metadata: { purpose: 'one-time-signup' }
});

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

### Webhook 集成( SendGrid)

```typescript
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);
});
```

## 测试

```bash
# 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](https://npmcn.com/core/email-parser) - 分析收到的电子邮件(如有需要)
-   [@bernierllc/电子邮件发送器](https://npmcn.com/core/email-sender) - 发送路由电子邮件(如有需要)
-   [@bernierllc/crypto-utils](https://npmcn.com/core/crypto-utils) - 生成安全代理代用符(倒计时)
-   [@ bernierllc/ 拖放器](https://npmcn.com/core/logger) - 结构化伐木
-   [@bernierllc/ 绝不是适应器](https://npmcn.com/core/neverhub-adapter) - 服务发现(可选)

### 套房的一部分

-   [@bernierllc/电子邮件测试套间](https://npmcn.com/package/suite/email-testing-suite) - 完整的电子邮件测试解决方案

## 支助

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

## 常见问题

### @bernierllc/email-mitm-masking 是什么？

提供电子邮件口罩和中间人行道服务,以进行注重隐私的电子邮件通信

### 如何安装 @bernierllc/email-mitm-masking？

在项目目录运行 npm install @bernierllc/email-mitm-masking，或使用 pnpm add / yarn add / bun add。

### @bernierllc/email-mitm-masking 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bernierllc/email-mitm-masking 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bernierllc/email-mitm-masking 可以商用吗？

@bernierllc/email-mitm-masking 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @bernierllc/email-mitm-masking 的下载量有多少？

根据 npm 官方下载统计，@bernierllc/email-mitm-masking 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,072 次，日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bernierllc/email-mitm-masking 还在维护吗？

最新版本 1\.6\.11 发布于 2026/11/05（3 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2025/11/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。