@z_06/relay-temp-mail 2.0.1 → 2.1.0

package/README.md

@@ -4,12 +4,13 @@
 
 A modular TypeScript/JavaScript package for managing email aliases and retrieving temporary emails through pluggable providers.
 
-Built on a provider architecture — combine any **alias provider** with any **mail provider** to fit your workflow. Currently ships with Firefox Relay and CloudFlare Temp Mail support, with more providers coming.
+Built on a provider architecture — combine any **alias provider** with any **mail provider** to fit your workflow. Currently ships with Firefox Relay, DuckDuckGo Email Protection, and CloudFlare Temp Mail support.
 
 ## Features
 
 - **Provider-based architecture** — mix and match alias + mail providers
 - **Firefox Relay** — create, list, and delete email aliases
+- **DuckDuckGo Email Protection** — create email aliases with local storage
 - **CloudFlare Temp Mail** — retrieve and parse emails via API
 - **TypeScript support** — full type definitions for all APIs, including provider interfaces
 - **ESM + CommonJS support** — works with both module systems
@@ -60,7 +61,7 @@ The library uses two types of providers that can be combined independently:
 
 | Provider Type | Interface | Current Implementations |
 |---|---|---|
-| **Alias Provider** | `AliasProvider` | `firefox-relay` |
+| **Alias Provider** | `AliasProvider` | `firefox-relay`, `duckduckgo-email` |
 | **Mail Provider** | `MailProvider` | `cf-temp-mail` |
 
 ### Alias Providers
@@ -87,6 +88,53 @@ Manages email aliases through [Firefox Relay](https://relay.firefox.com).
 4. Find Cookies for `relay.firefox.com`
 5. Copy the values for `csrftoken` and `sessionid`
 
+#### `duckduckgo-email`
+
+Manages email aliases through [DuckDuckGo Email Protection](https://duckduckgo.com/email/).
+
+Since the DuckDuckGo API does not provide endpoints for listing or deleting aliases, this provider uses a local store. A default in-memory store is included; implement `DuckDuckGoAliasStore` for custom persistence (e.g., file-based, database).
+
+**Configuration:**
+
+```typescript
+{
+  type: 'duckduckgo-email',
+  jwtToken: string;             // JWT token from DuckDuckGo Email Protection
+  store?: DuckDuckGoAliasStore; // Optional custom store (default: in-memory)
+}
+```
+
+**Getting your JWT token:**
+
+1. Visit [duckduckgo.com/email](https://duckduckgo.com/email/) and register an account
+2. Open your browser's developer tools (F12)
+3. Click "Generate New Address" in the DuckDuckGo Email UI
+4. In the Network tab, find the request to `quack.duckduckgo.com`
+5. Copy the Bearer token from the `Authorization` header
+
+**Custom persistence:**
+
+```typescript
+import type { DuckDuckGoAliasStore, RelayAlias } from '@z_06/relay-temp-mail';
+
+class MyFileStore implements DuckDuckGoAliasStore {
+  getAll(): RelayAlias[] { /* read from file */ }
+  add(alias: RelayAlias): void { /* append to file */ }
+  remove(id: number): void { /* remove from file */ }
+}
+
+const client = new TempMailClient({
+  aliasProvider: {
+    type: 'duckduckgo-email',
+    jwtToken: 'your-jwt-token',
+    store: new MyFileStore(),
+  },
+  mailProvider: { /* ... */ },
+});
+```
+
+**Duplicate detection:** The DuckDuckGo API may occasionally return a previously-generated address with a 201 response. The provider detects this and throws a `RelayTempMailError` with code `DUPLICATE_ALIAS`.
+
 ### Mail Providers
 
 #### `cf-temp-mail`
@@ -255,6 +303,8 @@ import type {
   MailProvider,
   TempMailConfig,
   FirefoxRelayConfig,
+  DuckDuckGoEmailConfig,
+  DuckDuckGoAliasStore,
   CFTempMailConfig,
   RelayAlias,
   Email,

package/README.zh-CN.md

@@ -4,12 +4,13 @@
 
 一个模块化的 TypeScript/JavaScript 包，通过可插拔的 Provider 管理邮箱别名和接收临时邮件。
 
-基于 Provider 架构 — 自由组合**别名提供商**与**邮件提供商**。当前内置 Firefox Relay 和 CloudFlare 临时邮箱支持，更多提供商即将推出。
+基于 Provider 架构 — 自由组合**别名提供商**与**邮件提供商**。当前内置 Firefox Relay、DuckDuckGo 邮件保护和 CloudFlare 临时邮箱支持。
 
 ## 功能特性
 
 - **Provider 架构** — 自由组合别名与邮件提供商
 - **Firefox Relay** — 创建、列出、删除邮箱别名
+- **DuckDuckGo 邮件保护** — 创建邮箱别名，支持本地存储
 - **CloudFlare 临时邮箱** — 通过 API 获取并解析邮件
 - **TypeScript 支持** — 所有 API 均有完整类型定义，包括 Provider 接口
 - **ESM + CommonJS 支持** — 兼容两种模块系统
@@ -60,7 +61,7 @@ const emails = await client.getEmails(alias.fullAddress, { limit: 10 });
 
 | Provider 类型 | 接口 | 当前实现 |
 |---|---|---|
-| **别名提供商** | `AliasProvider` | `firefox-relay` |
+| **别名提供商** | `AliasProvider` | `firefox-relay`, `duckduckgo-email` |
 | **邮件提供商** | `MailProvider` | `cf-temp-mail` |
 
 ### 别名提供商
@@ -87,6 +88,53 @@ const emails = await client.getEmails(alias.fullAddress, { limit: 10 });
 4. 找到 `relay.firefox.com` 的 Cookies
 5. 复制 `csrftoken` 和 `sessionid` 的值
 
+#### `duckduckgo-email`
+
+通过 [DuckDuckGo 邮件保护](https://duckduckgo.com/email/) 管理邮箱别名。
+
+由于 DuckDuckGo API 不提供列出或删除别名的接口，该提供商使用本地存储。内置内存存储；可通过实现 `DuckDuckGoAliasStore` 接口自定义持久化（如文件、数据库）。
+
+**配置：**
+
+```typescript
+{
+  type: 'duckduckgo-email',
+  jwtToken: string;             // DuckDuckGo 邮件保护的 JWT token
+  store?: DuckDuckGoAliasStore; // 可选自定义存储（默认: 内存存储）
+}
+```
+
+**获取 JWT Token：**
+
+1. 访问 [duckduckgo.com/email](https://duckduckgo.com/email/) 并注册账户
+2. 打开浏览器开发者工具（F12）
+3. 在 DuckDuckGo 邮件界面点击"生成新地址"
+4. 在网络请求栏中找到发往 `quack.duckduckgo.com` 的请求
+5. 从 `Authorization` 请求头中复制 Bearer token
+
+**自定义持久化：**
+
+```typescript
+import type { DuckDuckGoAliasStore, RelayAlias } from '@z_06/relay-temp-mail';
+
+class MyFileStore implements DuckDuckGoAliasStore {
+  getAll(): RelayAlias[] { /* 从文件读取 */ }
+  add(alias: RelayAlias): void { /* 追加到文件 */ }
+  remove(id: number): void { /* 从文件中删除 */ }
+}
+
+const client = new TempMailClient({
+  aliasProvider: {
+    type: 'duckduckgo-email',
+    jwtToken: 'your-jwt-token',
+    store: new MyFileStore(),
+  },
+  mailProvider: { /* ... */ },
+});
+```
+
+**重复检测：** DuckDuckGo API 偶尔会返回之前已生成过的地址（仍返回 201）。该提供商会检测这种情况并抛出 `RelayTempMailError`，错误代码为 `DUPLICATE_ALIAS`。
+
 ### 邮件提供商
 
 #### `cf-temp-mail`
@@ -255,6 +303,8 @@ import type {
   MailProvider,
   TempMailConfig,
   FirefoxRelayConfig,
+  DuckDuckGoEmailConfig,
+  DuckDuckGoAliasStore,
   CFTempMailConfig,
   RelayAlias,
   Email,

package/dist/index.cjs

@@ -23,7 +23,9 @@ __export(index_exports, {
   AuthError: () => AuthError,
   CFEmailClient: () => CFEmailClient,
   CFTempMailProvider: () => CFTempMailProvider,
+  DuckDuckGoEmailProvider: () => DuckDuckGoEmailProvider,
   FirefoxRelayProvider: () => FirefoxRelayProvider,
+  InMemoryDuckDuckGoAliasStore: () => InMemoryDuckDuckGoAliasStore,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
   ParseError: () => ParseError,
@@ -167,114 +169,6 @@ var DefaultHttpClient = class {
   }
 };
 
-// src/parser.ts
-var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
-var MOZMAIL_SUFFIX_PATTERN = /@mozmail\.com$/i;
-var ENCODED_WORD_PATTERN = /=\?([^?]+)\?([BbQq])\?([^?]*)\?=/g;
-var EmailParser = class {
-  parseEmail(raw) {
-    const headers = this.parseHeaders(raw);
-    const toHeader = headers.get("to") || "";
-    const fromHeader = headers.get("from") || "";
-    const messageIdHeader = headers.get("message-id") || "";
-    const relayAlias = this.extractRelayAlias(raw);
-    return {
-      id: 0,
-      messageId: this.extractMessageId(messageIdHeader),
-      source: this.extractEmailAddress(fromHeader),
-      address: this.extractEmailAddress(toHeader),
-      raw,
-      metadata: null,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      relayAlias: relayAlias || void 0
-    };
-  }
-  extractRelayAlias(raw) {
-    try {
-      const headers = this.parseHeaders(raw);
-      const fromAddresses = this.extractHeaderEmails(headers.get("from"));
-      const toAddresses = this.extractHeaderEmails(headers.get("to"));
-      const allAddresses = [...fromAddresses, ...toAddresses];
-      const mozmailAddress = allAddresses.find(
-        (address) => MOZMAIL_SUFFIX_PATTERN.test(address)
-      );
-      if (mozmailAddress) return mozmailAddress;
-      return toAddresses[0] ?? null;
-    } catch {
-      return null;
-    }
-  }
-  parseHeaders(raw) {
-    const headers = /* @__PURE__ */ new Map();
-    const headerEnd = raw.indexOf("\r\n\r\n");
-    const headerSection = headerEnd === -1 ? raw : raw.substring(0, headerEnd);
-    const lines = headerSection.split(/\r?\n/);
-    let currentHeader = null;
-    let currentValue = "";
-    for (const line of lines) {
-      if (/^\s/.test(line)) {
-        if (currentHeader) currentValue += " " + line.trim();
-      } else {
-        if (currentHeader) headers.set(currentHeader, currentValue);
-        const colonIndex = line.indexOf(":");
-        if (colonIndex > 0) {
-          currentHeader = line.substring(0, colonIndex).toLowerCase().trim();
-          currentValue = line.substring(colonIndex + 1).trim();
-        } else {
-          currentHeader = null;
-          currentValue = "";
-        }
-      }
-    }
-    if (currentHeader) headers.set(currentHeader, currentValue);
-    return headers;
-  }
-  decodeHeader(value) {
-    return value.replace(ENCODED_WORD_PATTERN, (_, charset, encoding, encoded) => {
-      try {
-        if (encoding.toUpperCase() === "Q") {
-          return this.decodeQuotedPrintable(encoded);
-        } else if (encoding.toUpperCase() === "B") {
-          return this.decodeBase64(encoded);
-        }
-        return encoded;
-      } catch {
-        return encoded;
-      }
-    });
-  }
-  decodeQuotedPrintable(encoded) {
-    let decoded = encoded.replace(/_/g, " ");
-    decoded = decoded.replace(
-      /=([0-9A-Fa-f]{2})/g,
-      (_, hex) => String.fromCharCode(parseInt(hex, 16))
-    );
-    return decoded;
-  }
-  decodeBase64(encoded) {
-    return Buffer.from(encoded, "base64").toString("utf-8");
-  }
-  extractEmailAddress(headerValue) {
-    if (!headerValue) return "";
-    const decoded = this.decodeHeader(headerValue);
-    const bracketMatch = decoded.match(/<([^>]+)>/);
-    if (bracketMatch) return bracketMatch[1].trim().toLowerCase();
-    const emailMatch = decoded.match(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/);
-    return emailMatch ? emailMatch[0].toLowerCase() : decoded.trim().toLowerCase();
-  }
-  extractHeaderEmails(headerValue) {
-    if (!headerValue) return [];
-    const decoded = this.decodeHeader(headerValue);
-    const matches = decoded.match(EMAIL_PATTERN);
-    return matches ? matches.map((match) => match.toLowerCase()) : [];
-  }
-  extractMessageId(headerValue) {
-    if (!headerValue) return `<generated-${Date.now()}@relay-temp-mail>`;
-    const cleaned = headerValue.replace(/[<>]/g, "").trim();
-    return `<${cleaned}>`;
-  }
-};
-
 // src/http.ts
 var HttpClient = class {
   /**
@@ -431,6 +325,187 @@ var HttpClient = class {
   }
 };
 
+// src/duckduckgo-api.ts
+var InMemoryDuckDuckGoAliasStore = class {
+  constructor() {
+    this.aliases = [];
+  }
+  getAll() {
+    return [...this.aliases];
+  }
+  add(alias) {
+    this.aliases.push(alias);
+  }
+  remove(id) {
+    this.aliases = this.aliases.filter((a) => a.id !== id);
+  }
+};
+var DuckDuckGoEmailProvider = class {
+  constructor(jwtToken, store, httpClient) {
+    this.jwtToken = jwtToken;
+    this.store = store ?? new InMemoryDuckDuckGoAliasStore();
+    this.httpClient = httpClient ?? new HttpClient("https://quack.duckduckgo.com");
+    this.nextId = 1;
+  }
+  async listAliases() {
+    return this.store.getAll();
+  }
+  async createAlias() {
+    const response = await this.httpClient.request(
+      "POST",
+      "/api/email/addresses",
+      {
+        headers: {
+          Authorization: `Bearer ${this.jwtToken}`
+        }
+      }
+    );
+    const fullAddress = `${response.address}@duck.com`;
+    const existing = await this.store.getAll();
+    if (existing.some((a) => a.fullAddress === fullAddress)) {
+      throw new RelayTempMailError(
+        `DuckDuckGo returned a duplicate alias: ${fullAddress}`,
+        "DUPLICATE_ALIAS",
+        201
+      );
+    }
+    const alias = {
+      id: this.nextId++,
+      address: response.address,
+      fullAddress,
+      enabled: true,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      domain: 3,
+      maskType: "random"
+    };
+    await this.store.add(alias);
+    return alias;
+  }
+  async deleteAlias(id) {
+    await this.store.remove(id);
+  }
+};
+
+// src/parser.ts
+var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+var MOZMAIL_SUFFIX_PATTERN = /@mozmail\.com$/i;
+var DUCK_SUFFIX_PATTERN = /@duck\.com$/i;
+var ENCODED_WORD_PATTERN = /=\?([^?]+)\?([BbQq])\?([^?]*)\?=/g;
+var EmailParser = class {
+  parseEmail(raw) {
+    const headers = this.parseHeaders(raw);
+    const toHeader = headers.get("to") || "";
+    const fromHeader = headers.get("from") || "";
+    const messageIdHeader = headers.get("message-id") || "";
+    const relayAlias = this.extractRelayAlias(raw);
+    return {
+      id: 0,
+      messageId: this.extractMessageId(messageIdHeader),
+      source: this.extractEmailAddress(fromHeader),
+      address: this.extractEmailAddress(toHeader),
+      raw,
+      metadata: null,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      relayAlias: relayAlias || void 0
+    };
+  }
+  extractRelayAlias(raw) {
+    try {
+      const headers = this.parseHeaders(raw);
+      const duckOriginalTo = headers.get("duck-original-to");
+      if (duckOriginalTo) {
+        const duckAddress2 = this.extractEmailAddress(duckOriginalTo);
+        if (duckAddress2 && DUCK_SUFFIX_PATTERN.test(duckAddress2)) {
+          return duckAddress2;
+        }
+      }
+      const fromAddresses = this.extractHeaderEmails(headers.get("from"));
+      const toAddresses = this.extractHeaderEmails(headers.get("to"));
+      const allAddresses = [...fromAddresses, ...toAddresses];
+      const mozmailAddress = allAddresses.find(
+        (address) => MOZMAIL_SUFFIX_PATTERN.test(address)
+      );
+      if (mozmailAddress) return mozmailAddress;
+      const duckAddress = allAddresses.find(
+        (address) => DUCK_SUFFIX_PATTERN.test(address)
+      );
+      if (duckAddress) return duckAddress;
+      return toAddresses[0] ?? null;
+    } catch {
+      return null;
+    }
+  }
+  parseHeaders(raw) {
+    const headers = /* @__PURE__ */ new Map();
+    const headerEnd = raw.indexOf("\r\n\r\n");
+    const headerSection = headerEnd === -1 ? raw : raw.substring(0, headerEnd);
+    const lines = headerSection.split(/\r?\n/);
+    let currentHeader = null;
+    let currentValue = "";
+    for (const line of lines) {
+      if (/^\s/.test(line)) {
+        if (currentHeader) currentValue += " " + line.trim();
+      } else {
+        if (currentHeader) headers.set(currentHeader, currentValue);
+        const colonIndex = line.indexOf(":");
+        if (colonIndex > 0) {
+          currentHeader = line.substring(0, colonIndex).toLowerCase().trim();
+          currentValue = line.substring(colonIndex + 1).trim();
+        } else {
+          currentHeader = null;
+          currentValue = "";
+        }
+      }
+    }
+    if (currentHeader) headers.set(currentHeader, currentValue);
+    return headers;
+  }
+  decodeHeader(value) {
+    return value.replace(ENCODED_WORD_PATTERN, (_, charset, encoding, encoded) => {
+      try {
+        if (encoding.toUpperCase() === "Q") {
+          return this.decodeQuotedPrintable(encoded);
+        } else if (encoding.toUpperCase() === "B") {
+          return this.decodeBase64(encoded);
+        }
+        return encoded;
+      } catch {
+        return encoded;
+      }
+    });
+  }
+  decodeQuotedPrintable(encoded) {
+    let decoded = encoded.replace(/_/g, " ");
+    decoded = decoded.replace(
+      /=([0-9A-Fa-f]{2})/g,
+      (_, hex) => String.fromCharCode(parseInt(hex, 16))
+    );
+    return decoded;
+  }
+  decodeBase64(encoded) {
+    return Buffer.from(encoded, "base64").toString("utf-8");
+  }
+  extractEmailAddress(headerValue) {
+    if (!headerValue) return "";
+    const decoded = this.decodeHeader(headerValue);
+    const bracketMatch = decoded.match(/<([^>]+)>/);
+    if (bracketMatch) return bracketMatch[1].trim().toLowerCase();
+    const emailMatch = decoded.match(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/);
+    return emailMatch ? emailMatch[0].toLowerCase() : decoded.trim().toLowerCase();
+  }
+  extractHeaderEmails(headerValue) {
+    if (!headerValue) return [];
+    const decoded = this.decodeHeader(headerValue);
+    const matches = decoded.match(EMAIL_PATTERN);
+    return matches ? matches.map((match) => match.toLowerCase()) : [];
+  }
+  extractMessageId(headerValue) {
+    if (!headerValue) return `<generated-${Date.now()}@relay-temp-mail>`;
+    const cleaned = headerValue.replace(/[<>]/g, "").trim();
+    return `<${cleaned}>`;
+  }
+};
+
 // src/relay-api.ts
 var FirefoxRelayProvider = class {
   constructor(csrfToken, sessionId, httpClient) {
@@ -508,6 +583,11 @@ function createAliasProvider(config, httpClient) {
         aliasConfig.sessionId,
         httpClient
       );
+    case "duckduckgo-email":
+      return new DuckDuckGoEmailProvider(
+        aliasConfig.jwtToken,
+        aliasConfig.store
+      );
   }
 }
 function createMailProvider(config) {
@@ -568,7 +648,9 @@ var RelayClient = TempMailClient;
   AuthError,
   CFEmailClient,
   CFTempMailProvider,
+  DuckDuckGoEmailProvider,
   FirefoxRelayProvider,
+  InMemoryDuckDuckGoAliasStore,
   NetworkError,
   NotFoundError,
   ParseError,