# @activescott/auth-provider-email 中文文档

规范地址：https://npmcn.com/package/%40activescott/auth-provider-email/

版本：3\.2\.2
npm 元数据更新时间：2026-09-20T09:07:59.090Z
中文译文更新时间：2026-11-06T01:47:39.299Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40activescott/auth-provider-email
原文对照：https://npmcn.com/package/%40activescott/auth-provider-email/?lang=original
项目主页：https://github.com/activescott/auth#readme
源码仓库：https://github.com/activescott/auth

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

- 包体积（解压后）：75.9 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@activescott/auth ^5\.0\.1
- 首次发布：2026-03-16T19:01:07.423Z
- 最新版本发布：2026-09-20T09:07:58.765Z
- 近 30 天下载量：7042（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

@ actionscott/ auth 的电子邮件魔法链接提供者

## 安装

```sh
npm install @activescott/auth-provider-email
```

也可以使用：`pnpm add @activescott/auth-provider-email`、`yarn add @activescott/auth-provider-email`、`bun add @activescott/auth-provider-email`

## README

# @ activescott/ auth- professor- 电子邮件

[![npm version](https://img.shields.io/npm/v/@activescott/auth-provider-email.svg)](https://www.npmjs.com/package/@activescott/auth-provider-email) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

电子邮件魔法链接认证提供者 [`@activescott/auth`](https://www.npmjs.com/package/@activescott/auth)。 。 。 .

发送包含一款单用魔法链接和一款数字一次性代码的签名电子邮件,两者均由一款服务器侧面挑战支持. 重新查找或创建用户 `UserStore`编号 :`IdentityStore` 并手控回认证核心 发行会话饼干.

用于生产 [frumblefeed.com (英语)](https://ramblefeed.com/) 财务报告和审定财务报表 [(原始内容存档于2018-10-21). dinkerbellbot.com](https://tinkerbellbot.com/)。 。 。 .

## 安装

```bash
npm install @activescott/auth @activescott/auth-provider-email
```

## 使用量

```ts
import { Auth } from "@activescott/auth"
import { EmailProvider } from "@activescott/auth-provider-email"

const auth = new Auth({
  // ...session, identityStore, userStore, challengeStore...
  providers: [
    new EmailProvider({
      smtp: {
        host: process.env.SMTP_HOST!,
        port: Number(process.env.SMTP_PORT),
        user: process.env.SMTP_USER!,
        pass: process.env.SMTP_PASS!,
      },
      from: process.env.FROM_EMAIL!,
      template: { appName: "My App", subject: "Sign in to My App" },
    }),
  ],
})
```

## 注册路线

提供者处理四个 URL 模式 `/auth/email/*` (由您的框架适配器挂起):

| 方法 | 路径 | 目的 |
| --- | --- | --- |
| 邮政 | `/auth/email/initiate` | 发送到所提供邮件的神奇链接 . |
| 邮政 | `/auth/email/send` | 别名 `initiate`。 。 。 . |
| 获取 | `/auth/email/verify` | 从链接中校验令牌, 登录用户 . |
| 邮政 | `/auth/email/verify` | 验证一次性代码( 当 `otp` 已启用). |
| 获取 | `/auth/email/callback` | 别名 `verify`。 。 。 . |

## 登录邮件是如何工作的

每次发送都会创建一个服务器侧的挑战(通过 `Auth` 配置的 `challengeStore`(a) 有两条救赎路径,既单用,又共用一条过期(默认为15米):

1.  **神奇的链接** —— 说 `/auth/email/verify?challenge=<id>&key=<256-bit secret>`。单击(GET)显示最小值 **"确认注册"** 页面;确认按钮 POST 救赎。 电子邮件安全扫描仪(Outlook SafeLinks, Mimecast, 链接预览)预设了GET链接,但从未提交表格,因此无法消耗单用链接.
2.  **数字代码** ——用户在您的登录页面上输入,而不是点击链接. iOS 和 macOS 在 Mail 中检测代码, 并在输入使用时通过 AutoFill 提供 `autoComplete="one-time-code"`。 。 。 . `initiate` 仅设置 Http `auth_challenge` cookie 绑定启动浏览器的代码条目; 您的代码输入 POST 到 `/auth/email/verify`。代码是尝试封装的:错误代码 = `INVALID_CREDENTIALS`,太多尝试 ~ `RATE_LIMITED`页:1 `EXPIRED_TOKEN`。 。 。 .

没有签名邮件的签名秘密管理——链接密钥和代码都被存储在挑战中被盐化的散列上,并在使用时被删除.

调音 : `expiry` (上层,例如:. `"15m"`和 `otp: { length?, maxAttempts?, cookieName? }`,或 vars 环境 `EMAIL_EXPIRY`, (中文(简体) ), `EMAIL_OTP_LENGTH`, (中文(简体) ), `EMAIL_OTP_MAX_ATTEMPTS` 与 `emailConfigFromEnvironment`。 。 。 .

`initiate` 拒绝一个其域名没有点的地址(例如:. `scott@willeke`在任何商店写作或发送之前,因为它几乎总是缺少TLD而不是真正的目的地. 设定 `allowDotlessDomain: true` 用于内部网络或编程设置,以登录到一个赤裸的主机名,例如 `user@localhost`。 。 。 .

## Dev 模式( 不需要 SMTP)

`NodemailerTransport` 接受一个 `isDevelopment` 旗帜。 何时 `true`,它通过Nodemailer的流传输来缓冲电子邮件(没有真正的SMTP连接)并打印到服务器控制台的魔法链接——对本地的dev,example,以及CI有用:

```ts
import {
  EmailProvider,
  NodemailerTransport,
} from "@activescott/auth-provider-email"

new EmailProvider(
  {/* ...config... */},
  new NodemailerTransport(true), // dev mode: log link, don't send
)
```

或没有通过任何运输 和提供者自动创建 `new NodemailerTransport(process.env.NODE_ENV === "development")`。 。 。 .

## 自定义电子邮件传输

船舶 `NodemailerTransport` (SMTP) (中文(简体) ). 执行 `EmailTransport` 用于插入Resend、SES、Postmark等:

```ts
import type {
  EmailProviderConfig,
  EmailTransport,
} from "@activescott/auth-provider-email"

class ResendTransport implements EmailTransport {
  async sendMagicLink(
    to: string,
    magicLink: string,
    config: EmailProviderConfig,
  ): Promise<boolean> {
    // ...call Resend API...
    return true
  }
}

new EmailProvider(config, new ResendTransport())
```

## 测试模式: 抓取运输

在e2e测试中,包装你的 `EmailTransport` 内 `CaptureEmailTransport`,通过一个仅测试的回读路径(在测试-模版env var上显示)来显示它记录的内容 **财务报告和审定财务报表** a supre-secret header),并驱动真实的确认页或代码输入流——没有SMTP服务器,没有收件箱投票.

```typescript
import { CaptureEmailTransport } from "@activescott/auth-provider-email/testing"

// Install it only under your test-mode flag: what it holds are live sign-in
// credentials for as long as the challenge lives.
export const emailTransport =
  process.env.E2E_TEST_MODE === "true"
    ? new CaptureEmailTransport(new NodemailerTransport())
    : new NodemailerTransport()

// in your gated readback route:
const captured = emailTransport.getCapturedEmail(email) // { magicLink, code }
```

它住在这里 `/testing` 子路径而不是软件包根,所以它不包含在应用程序的默认导入图中 。 见下文可操作的例子.

## 文档实例( E)

Full Docs 和一个带有 Playwright 测试的可运行的 React Router 框架- mode 实例在 monrepo 中直播 :

→ **[https://github.com/活塞斯科特/奥斯\*](https://github.com/activescott/auth*)\* 联合国**

## 许可证

麻省理工学院

## 常见问题

### @activescott/auth-provider-email 是什么？

@ actionscott/ auth 的电子邮件魔法链接提供者

### 如何安装 @activescott/auth-provider-email？

在项目目录运行 npm install @activescott/auth-provider-email，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@activescott/auth（^5\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @activescott/auth-provider-email 支持 TypeScript 吗？

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

### @activescott/auth-provider-email 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @activescott/auth-provider-email 可以商用吗？

@activescott/auth-provider-email 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @activescott/auth-provider-email 的下载量有多少？

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

### @activescott/auth-provider-email 还在维护吗？

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