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

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

版本：2\.3\.0
npm 元数据更新时间：2026-10-07T02:46:39.498Z
中文译文更新时间：2026-11-06T05:47:44.733Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：57.8 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@activescott/auth ^5\.0\.0
- 首次发布：2026-08-01T18:58:22.662Z
- 最新版本发布：2026-10-07T02:46:39.184Z
- 近 30 天下载量：4676（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

@ activescott/ auth 的一次性短信码提供者

## 安装

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

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

## README

# @ activescott/ auth- 提供者 - sms

[![npm version](https://img.shields.io/npm/v/@activescott/auth-provider-sms.svg)](https://www.npmjs.com/package/@activescott/auth-provider-sms) [![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)。用户输入他们的手机号码,得到6位数代码的短信,并按类型(或自动填充)签名.

这个软件包 **无供应商依赖关系** ——快递作为交通工具注入. 使用供应商包或写自己的:

-   [`@activescott/auth-sms-twilio`](https://www.npmjs.com/package/@activescott/auth-sms-twilio) - 特维利奥: `TwilioMessagingTransport` (SMS,或RCS通过信使服务)和 `TwilioVerifyTransport` (Twilio验证)
-   `ConsoleTransport` (包括)——将代码打印到服务器控制台进行开发
-   自定义: 已执行 `SmsTransport { sendMessage(to, message): Promise<boolean> }`。在 [PR 第37号](https://github.com/activescott/auth/pull/37) 实施和单位测试但未经核实的AWS账户;如果想要AWS并且可以测试结束,可以自由地接管该PR([36号](https://github.com/activescott/auth/issues/36) (有核对表).

## 两种运输

|  | `SmsTransport` | `VerificationTransport` |
| --- | --- | --- |
| 谁做代码 | 此软件包 | 供应商 |
| 谁检查代码 | 此软件包 | 供应商 |
| 美国A2P 10DLC注册 | **交给你了** ——通过 " 运动登记册 " 开展品牌+运动,日-周加月费 | **无** - 供应商从已登记的发送者发送 |
| 每次登录的费用(美国) | 每简讯~0.011-0.013美元 | ~ 0.058美元(Twilio验证:每成功0.05美元+频道费) |
| 信件文本、 代码长度、 WebOTP 行 |  | 卖家 |

`SmsProvider` 要么接受,要么接受。 路由,请求机构,饼干绑定,滥用检查,以及错误反应是完全相同的,因此切换是构造时的一行变化:

```ts
new SmsProvider({ appName: "MyApp" }, new TwilioVerifyTransport({ ... }))
```

选择 `VerificationTransport` 当10DLC的注册是你们和航运之间的事时——低注册量的固定月费往往会超过整个核实账单。 选择 `SmsTransport` 当音量使每个消息的价格占据主导地位时,或者您想要对消息文本的控制.

## 使用量

```ts
import { Auth, InMemoryChallengeStore } from "@activescott/auth"
import { SmsProvider, ConsoleTransport } from "@activescott/auth-provider-sms"
import { TwilioMessagingTransport } from "@activescott/auth-sms-twilio"

const auth = new Auth({
  session: { secret: process.env.JWT_SECRET! /* ... */ },
  userStore,
  identityStore,
  challengeStore: new InMemoryChallengeStore(), // DB-backed in production
  providers: [
    new SmsProvider(
      { appName: "MyApp", webOtpDomain: "myapp.example" },
      process.env.NODE_ENV === "production"
        ? new TwilioMessagingTransport({
            accountSid: process.env.TWILIO_ACCOUNT_SID!,
            authToken: process.env.TWILIO_AUTH_TOKEN!,
            messagingServiceSid: process.env.TWILIO_SMS_MESSAGING_SERVICE_SID,
          })
        : new ConsoleTransport(),
    ),
  ],
})
```

登录表单将电话号码张贴到 `/auth/sms/initiate` (提供商将代码发去文本,设置一个 Http 单向挑战 cookie,并用 `?sent=1`); 代码表 `/auth/sms/verify`。一个可运行的应用程序显示全流 [`examples/react-router`](https://github.com/activescott/auth/tree/main/examples/react-router)数字 :

```html
<form method="post" action="/auth/sms/initiate">
  <input name="phone" type="tel" autocomplete="tel" required />
  <button>Text me a code</button>
</form>

<form method="post" action="/auth/sms/verify">
  <input
    name="code"
    autocomplete="one-time-code"
    inputmode="numeric"
    pattern="[0-9]{6}"
    required
  />
  <button>Sign in</button>
</form>
```

## 配置

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `appName` | `"App"` | 在默认信件文本中显示 |
| `expiry` | `"10m"` | 代码寿命( O)`"30s"`, (中文(简体) ), `"10m"`, (中文(简体) ), `"1h"`, (...) (中文(简体) ) |
| `webOtpDomain` | (关闭) | 附加 [网络OTP](https://developer.mozilla.org/docs/Web/API/WebOTP_API) 线条 `@domain #code` android/Chrome 单塔自动填充 |
| `messageTemplate` | 内置 | `(code, appName) => string` 以自定义文本 |
| `otp.length` | `6` | 代码中的数字 |
| `otp.maxAttempts` | `5` | 质疑无效前的错误猜测( E)`RATE_LIMITED`(中文(简体) ) |
| `otp.cookieName` | `"auth_sms_challenge"` | 挑战饼干名称 |

与一个 `VerificationTransport` 卖主负责写信息 所以 `appName`, (中文(简体) ), `messageTemplate`, (中文(简体) ), `webOtpDomain`,以及 `otp.length` 什么都不做——在供应商那里配置这些. `expiry`, (中文(简体) ), `otp.maxAttempts`,以及 `otp.cookieName` 仍然适用; `expiry` 限定本包的质疑记录,而供应商执行自己的代码寿命,以到期为准先结束尝试.

默认消息( 与 `webOtpDomain` set)看起来像:

```
Your MyApp sign-in code is: 123456

@myapp.example #123456
```

最后一句话是 [源代码格式](https://wicg.github.io/sms-one-time-codes/) (a WICG spec由Apple和Google共同编辑——什么) [网络OTP](https://developer.mozilla.org/docs/Web/API/WebOTP_API) safari的代码自动填充分析。 人可读的句子也很重要:苹果公司没有发布iOS安全代码AutoFill的精确语法,该语法从消息文本中快速承认了代码(参见: [`autocomplete="one-time-code"` 关于 MDN](https://developer.mozilla.org/docs/Web/HTML/Attributes/autocomplete)(b) —— `Your <app> sign-in code is: <code>` 遵循广泛观察的规律。 自定义模板应该保持类似形状,以便自动填充工作.

## 电话号码

输入规范化(空格、破折号、圆点、括号被剥去;正向) `00` → `+`),然后必须是有效的 [页:1](https://en.wikipedia.org/wiki/E.164) (单位:千美元)`+` 和需要的国家代码)——提供商从不猜测默认国家. `normalizePhoneNumber` 如果您想要相同的常态客户端,则导出.

## 测试模式: 抓取运输

在e2e测试中,包装你的 `SmsTransport` 内 `CaptureSmsTransport` 然后通过只测试的路由读取代码(在测试-模式env var上) **财务报告和审定财务报表** 而不是需要电话——或支付文字费用.

```typescript
import { CaptureSmsTransport } from "@activescott/auth-provider-sms/testing"

export const smsTransport =
  process.env.E2E_TEST_MODE === "true"
    ? new CaptureSmsTransport(new TwilioTransport({ ... }))
    : new TwilioTransport({ ... })

// in your gated readback route:
const captured = smsTransport.getCapturedSms(phone) // { message, code }
```

代码解析出默认信件模板; 通过第二个参数到 `CaptureSmsTransport` 当配置自定义时 `messageTemplate`它住在这里 `/testing` 子路径而不是软件包根,所以它不包含在应用程序的默认导入图中 .

## 安保模式

与电子邮件提供者相同的挑战模式:每发一次服务器侧式挑战,只存储为盐分的SHA-256散列,尝试数 **在此之前** 每次比较(封顶于 `maxAttempts`),常时比较,单用(在成功时被删除),挑战被HttpOnly cookie捆绑在启动浏览器上——没有它,单用代码是无用的.

与一个 `VerificationTransport` 代码从未到达您的服务器, 所以没有散列存储; 质疑记录持有电话号码和供应商的参考。 其他一切都没有改变,包括计算尝试 **在此之前** 向供应商提出问题,这也限制了一个挑战可以产生多少可开具账单的检查.

平均每艘和每艘IP派出减速舰 `@activescott/auth` 并默认执行(参见其 [虐待保护](https://npmcn.com/package/%40activescott/auth/README.md#abuse-protection) 供应商一级的欺诈/泵卫兵(Twilio,AWS)仍然值得在顶端启用.

如果你认为这些应该不同——属于这个图书馆的保护,模型中的一个弱点——请 [打开一个问题或 PR](https://github.com/activescott/auth/issues) 讨论.

## 常见问题

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

@ activescott/ auth 的一次性短信码提供者

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

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

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

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

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

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

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

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

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

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

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

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