# @gentleduck/auth 中文文档

规范地址：https://npmcn.com/package/%40gentleduck/auth/

版本：5\.18\.0
npm 元数据更新时间：2026-10-27T14:44:27.207Z
中文译文更新时间：2026-11-16T04:01:21.768Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gentleduck/auth
原文对照：https://npmcn.com/package/%40gentleduck/auth/?lang=original
项目主页：https://gentleduck.org/duck-auth
源码仓库：https://github.com/gentleeduck/duck-iam

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

- 包体积（解压后）：3.6 MB，314 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- peer 依赖：pg \>=8，mysql2 \>=2，drizzle-orm ^0\.45\.2，@nestjs/common \>=10 \<13，better-sqlite3 \>=7，@node-rs/argon2 \>=2 \<3，@aws-sdk/client-kms \>=3 \<4，@simplewebauthn/server ^13\.3\.1 \|\| ^14\.0\.0
- 首次发布：2026-05-29T05:47:17.599Z
- 最新版本发布：2026-10-27T14:44:26.890Z
- 近 30 天下载量：3782（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

现代TypeScript应用程序的认证. 面相相相通,框架可知,可通运. 与@gentleduck/iam对等.

## 安装

```sh
npm install @gentleduck/auth
```

也可以使用：`pnpm add @gentleduck/auth`、`yarn add @gentleduck/auth`、`bun add @gentleduck/auth`

## README

![@gentleduck/auth](https://npmcn.com/package/%40gentleduck/auth/public/logo-dark.svg)

# @ gentleduck/ auth (英语)

Faced,框架不可知,可移植的TypeScript认证. 与 [`@gentleduck/iam`](https://www.npmjs.com/package/@gentleduck/iam) 授权.

[麻省理工学院](https://npmcn.com/package/%40gentleduck/auth/LICENSE) - 说吧 [更改日志](https://npmcn.com/package/%40gentleduck/auth/CHANGELOG.md) - 说吧 [警卫](https://npmcn.com/package/%40gentleduck/auth/SECURITY.md) - 说吧 [文档](https://gentleduck.org/duck-auth)

[![npm](https://img.shields.io/npm/v/@gentleduck/auth.svg)](https://www.npmjs.com/package/@gentleduck/auth) [![downloads](https://img.shields.io/npm/dm/@gentleduck/auth.svg)](https://www.npmjs.com/package/@gentleduck/auth) [![MIT](https://img.shields.io/npm/l/@gentleduck/auth.svg)](https://npmcn.com/package/%40gentleduck/auth/LICENSE)

* * *

每个 TypeScript auth 库都使您选择框架锁定(NextAuth, Auth.js),一个主机控制平面(Clerk, WorkOS, Stytch),或者DIY-on-Lucia + passport + 您自己的胶水. `@gentleduck/auth` 是第三个选项,但统一:框架-不可知核,包含电池的适配器,没有主机平面. 将它接入快递,Hono,Next.js,Fastify,Koa,NestJS,Elysia,gRPC,或者用一个适配器导入自有的路由器.

零宿主依赖关系. 树能震动的子路径出口。 懒惰同位素分解为重位(argon2,简单webauthn,AWS KMS客户端,数据库驱动程序).

## 安装

```bash
npm install @gentleduck/auth
# or
bun add @gentleduck/auth
```

只安装您窃听的 :

| 软件包 | 当你需要的时候 |
| --- | --- |
| `@node-rs/argon2` | Argon2id 密码散列( FIPS / HIPAA 预设) |
| `@simplewebauthn/server` | 密码 / WebAuthn- MFA |
| `@aws-sdk/client-kms` | AWS KMS 信封在休息时加密 |
| `drizzle-orm` + 键 `pg`, (中文(简体) ), `mysql2` 或者说 `better-sqlite3` | Drizzle 适配器 (pg / mysql / sqlite) (英语) |
| `ioredis` 或者说 `@upstash/redis` | 重新支持的会话 / 偶发性 / 限制 / 事件 / DPoP- nonce 仓库 |
| `@node-saml/node-saml` | SAML 2.0 SP 导弹 |
| `@nestjs/common` | NestJS 适配器 |

## 快开始

```typescript
import { createAuth } from '@gentleduck/auth/core'
import { MemoryAdapter } from '@gentleduck/auth/adapters/memory'
import { MemoryLimiter } from '@gentleduck/auth/limiters/memory'
import { Argon2idHasher, passwords } from '@gentleduck/auth/providers/passwords'

const storage = new MemoryAdapter()

export const auth = createAuth({
  baseUrl: 'http://localhost:3000',
  stores: storage,
  limiter: new MemoryLimiter({ max: 5, windowMs: 60_000 }),
  providers: [passwords({ hasher: new Argon2idHasher() })],
})

const identity = await auth.identities.create({ profile: { username: 'a', email: 'a@x.com' } })
await auth.passwords.set(identity.id, 'correct-horse-battery', auth.cfg.stores.credentials, null)

const result = await auth.flows.signIn({
  providerId: 'password',
  input: { email: 'a@x.com', password: 'correct-horse-battery' },
})
// result.session, result.sid, result.intents[]
```

`createAuth` 工厂是连接侧面,选择正常默认(a) `CookieTransport` 名称 `__Host-duck-sid`, (中文(简体) ), `InMemoryEvents`),并登记您通过的供应者. `passwords()` 随身携带 `Argon2idHasher` 除非你通过 `hasher`安装 `@node-rs/argon2` 或通过 `ScryptHasher`。为了完全控制,即时 `AuthEngine` 直接——两个API接受相同的原始人.

## 建筑

`AuthEngine` 是根:每个状态变化的操作都生活在一个命名的面后,如此适配器,运输器,和提供者组成而不后通道相接.

| 面额 | 拥有 |
| --- | --- |
| `identities` | 配置 CRUD, 链接/ 链接, 软删除 + 宽期恢复, GDPR 导出, 批量导入 |
| `sessions` | 旋转 OrCreate( 单一特权更改 API), 获得BySid, 撤销、 撤销 All Foridentity, gc |
| `credentials` | 密码 / api- key / oauth / passkey / 恢复 / ttp / webauthn- mfa 行; CAS 旋转 |
| `passwords` | 强度 + 上限验证, 恒时验证, 需要 Rehash + 自动重置, 常见列表拒绝 |
| `passkeys` | 列表 / 撤销/ 撤销 全部, 范围为持有它们的身份 |
| `mfa` | TOTP 注册 + 验证, 备份码薄荷/ 验证, WebAuthn- MFA |
| `apiKeys` | 薄荷 / 列表 / 旋转 / 撤销 / 撤销 所有/ 核查 + 范围检查, 租户限制的发放 |
| `flows` | 签名 / signOut / sign Up (多相) / 密码重置 / 电子邮件验证 / 帐号删除 / 链接 / 提供 / 解链接 / 冒用 / 分步/ 分步 |
| `csrf` | 双向投递 + 原产地- + 秒站口, `__Host-` 饼干 |
| `webhooks` | HMAC + 时间戳 + 容忍度, 重试 w/ 后退, 死信, SSRF 守护 URL |
| `events` | 已键入总线,关闭 / signin.success / signin.failed / session.revoked / mfa.removed |
| `hijack` | IP / UA 漂移检测 + 升级 / 旋转 / 取消反应政策 |
| `anomaly` | 可插接的探测器(不可能旅行、设备指印),组成+决定梯 |
| `orgs` | org + 成员 CRUD、角色消毒、多租户警卫 |

加号 `m2m` (单位:千美元)`client_credentials` OAuth2赠款, `compliance` (GDPR/HIPAA/SOC2/FIPS预设),, `plugin` (名称为安装+平面扩展),以及 `audit` (admination-mutation hook with redaction). (原始内容存档于2019-09-29).

## 供应商

| 路径 | 什麽 |
| --- | --- |
| `@gentleduck/auth/providers/passwords` | 电子邮件+密码 |
| `@gentleduck/auth/providers/magic-link` | 无密码的一次性链接 |
| `@gentleduck/auth/providers/passkey` | WebAuthn 密码( 懒惰的端点Dep 打开) `@simplewebauthn/server`(中文(简体) ) |
| `@gentleduck/auth/providers/api-key` | 长寿无记名密钥通过 `ApiKeysFacet` |
| `@gentleduck/auth/providers/oauth/google` | 谷歌 OAuth (PKCE + 非ce) (中文(简体) ) |
| `@gentleduck/auth/providers/oauth/github` | GitHub OAuth( PKCE + 状态) : |
| `@gentleduck/auth/providers/oauth/microsoft` | 微软/ Entra ID OAuth |
| `@gentleduck/auth/providers/oauth/discord` | Discoord OAuth 调制解析器 |
| `@gentleduck/auth/providers/oauth/linkedin` | 链接到 OAuth |
| `@gentleduck/auth/providers/oauth/apple` | 用苹果签名 |
| `@gentleduck/auth/providers/oauth/core` | 任何其他 OAuth 2.0 / OIDC IdP : `oProvider` 超过一个 `OAuthClient` |
| `@gentleduck/auth/providers/saml` | 包装为 a `@node-saml/node-saml` 您构建的客户端: SP- 启动 + IDP- 启动 SSO, SP 元数据 XML 生成, 单一日志( SP- 和 IDP- 启动) |

## 运输

```typescript
import {
  CookieTransport,    // __Host- prefix + HttpOnly + SameSite=Lax (default)
  BearerTransport,    // opaque tokens in Authorization header
  JwtTransport,       // HS256 / RS256 / ES256 / EdDSA + JWKS rotation
  CompositeTransport, // chain multiple transports
} from '@gentleduck/auth/core/transport'

import {
  DPoPVerifier,
  MemoryDPoPNonceStore,
  computeJwkThumbprint,
  bindPayloadToDPoP,
} from '@gentleduck/auth/core/transport' // RFC 9449
```

## 存储适配器

```typescript
import { MemoryAdapter } from '@gentleduck/auth/adapters/memory'
import { DrizzlePgAdapter } from '@gentleduck/auth/adapters/drizzle/pg'
import { DrizzleMysqlAdapter } from '@gentleduck/auth/adapters/drizzle/mysql'
import { DrizzleSqliteAdapter } from '@gentleduck/auth/adapters/drizzle/sqlite'
import {
  RedisSessionImpl,
  RedisEvents,
  RedisDPoPNonceStore,
} from '@gentleduck/auth/adapters/redis'
import { RedisLimiter } from '@gentleduck/auth/limiters/redis'
import { FakeRedis } from '@gentleduck/auth/test' // in-tree, for tests

// One class per dialect, implementing the three store contracts. The constructor takes a
// connection string, a driver pool, or a drizzle handle you already have.
const storage = new DrizzlePgAdapter('postgres://localhost/app')
const { identities, credentials, sessions } = storage
```

### 这么贵的电话费

p50 在适配器边界上 - 细细地构建 SQL, 驱动器, 往返和行映射 - 每个后端都有超过50克的身份和100克的登录数据, 每日载荷下的一台笔记本电脑:

| 调用 | 内存 | SQL 点 | 邮资 | MySQL 数据 |
| --- | --- | --- | --- | --- |
| `find({ id })` | 3 μs (3μs) (3μs) | 0.089毫秒(每秒) | 0.280 毫秒(每秒) | 0.255 分钟 |
| `find({ email })` | 7 微秒( 7 微秒) | 0.090毫秒(每分钟) | 0.299 分钟 | 0.259 分钟 |
| `find({ providerId, providerSub })` | 8 μs (单位:千兆克) | 0.112 分钟 | 0.383 分钟 | 0.282 分钟 |
| `create (2 logins)` | 2.125毫秒(每秒) | 0.632 分钟 | 0.650毫秒(每分钟) | 1.184 分钟 |
| `erase` | 3 μs (3μs) (3μs) | 0.543 毫秒(秒) | 0.499 分钟 | 1.348 分钟 |
| `link` | 0.630 分钟 | 0.454 分钟 | 0.549 分钟 | 1.404毫秒(每秒) |
| `patchMetadata` | 4 微秒( 4 微秒) | 0.282 分钟 | 0.271 分钟 | 0.906 分钟 |

阅读以各种方言为索引驱动,司机的来回旅行费用为~5x所携带的查询. 写作 是一个关于Postgres的声明(`create` 财务报告和审定财务报表 `erase` 每一个CTE)和交易 其他,没有 `RETURNING` 或没有DML在a `WITH`记忆 `create` 财务报告和审定财务报表 `link` 这是 输出者:在适配器所持的每行都检查登录,这是测试双倍是一,而不是一 存储以运行 50k 账户通过.

自己开吧 `bun run bench:adapters` - 它开始并拆除自己的容器。 计划 计划 p95s,这些背后的方法 和故意留下的未优化 [`src/adapters/README.md`](https://npmcn.com/package/%40gentleduck/auth/src/adapters/README.md)。 。 。 .

## 交易

每个 SQL 支持的书写和读取都可以运行在您拥有的交易上. `withTransaction(tx)` 返回绑定在您的交易控件上的引擎视图;该控件不透明到 鸭子 直接交给适配器.

```typescript
const pending = await db.transaction(async (tx) => {
  const auth = engine.withTransaction(tx)
  await auth.identities.softDelete(identityId)
  await auth.sessions.revokeAllForIdentity(identityId)
  await tx.delete(users).where(eq(users.id, identityId))
  return auth.pending
})
await pending.flush()   // publish the events only once the commit landed
```

巢穴电话继承它: `auth.flows.completeAccountDeletion()` 达到 `identities.softDelete`, (中文(简体) ), `sessions.revokeAllForIdentity` 财务报告和审定财务报表 `credentials.delete`,还有所有 三个土地在你的交易。 阅读也捆绑着,所以在交易中读到 那笔交易是自己写的.

**交易内部不会发生任何事件.** 他们缓冲 `pending` 当你出版的时候 调用 `flush()`因此,在审计线索中从未出现回滚式删除 完成一个。 打电话 `flush()` 犯罪后,请打电话 `pending.discard()` 如果你滚动 故意退后,希望缓冲器放下. `pending.peek()` 不检查缓冲器 把它冲干.

### 什么是和不是交易

| 表面 | 交易吗? | 回滚时 |
| --- | --- | --- |
| `identities`, (中文(简体) ), `sessions`, (中文(简体) ), `credentials` - 写作和阅读 | 对 | 已撤销 |
| `flows.*`,包括嵌入式面对面呼叫 | 对 | 已撤销 |
| `mfa`, (中文(简体) ), `apiKeys`, (中文(简体) ), `passwords` 证书写作 | 对 | 已撤销 |
| `orgs` | 接口准备就绪; 没有运出 SQL 适配器 | 无 |
| 事件 | 缓冲 `pending` | 从未出版 |
| `deliver` 电话(核查/重设邮件) | **没有 - 立即发送** | 已发送邮件 |
| `limiter` 计数器 | **没有** | 代币消费 |
| `hijack` 编号 : `anomaly` 评分 | **没有** | 分数显示 |

后两行是警卫: 他们决定 _是否为_ 工作的时候,他们不写给SQL, 它们完全无法在被约束的视图上达到--使用 `engine.limiter`, (中文(简体) ), `engine.hijack` 财务报告和审定财务报表 `engine.anomaly` 交易之外。 发送邮件的流量应该是 调用到交易外, 或拆分, 发送在犯罪发生后进行; 不回滚 可以撤回已发送的电子邮件.

**未提供交易的引擎行为与以前完全相同 :** 写给自己的 连接和事件立即发布.

### 适应器支持

`withTransaction` 需要您作为适配器 `stores` 执行 `withClient` - 一个 调用每个侧面,因为他们共享它的连接。 细雨花花花花花花 适配器会的 内存、 redis 和 valkey 不 - 它们不能加入 SQL 交易 - 也不 一个你拼凑成一面的袋子 `withTransaction` 掷出 `AUTH_MISCONFIGURED` 而不是默不作声地把这些 写在你的交易之外.

### 每一次突变的呼声都用它所做的来回答

返回的文字 `void` 除了没有匹配的外,不能说 第二读到声明的内容。 每一个突变的呼唤 返回行, 或者它碰到的数 一个单行电话 匹配无所拒绝,和 `.orNull()` 读作: `null`; 批量答案 `[]` 或者说 `0`在 方言已经 `RETURNING` 这是同一回程.

```typescript
const identity = await auth.identities.softDelete(id)
// `deletedAt` is when the grace window CLOSES, so the deadline you show the user
// comes off the write itself rather than a second reading of the clock.
identity.deletedAt        // Date | null
identity.emailVerified    // false - the address is free to be claimed meanwhile

const erased = await auth.identities.erase(id, { reason: 'gdpr' })
// The row as it was: after the delete there is nothing left to read.

const ended = await auth.sessions.revokeAllForIdentity(id)
const notice = `Signed out of ${ended.length} devices`   // no second query; already read to emit events
```

| 表面 | 电话 | 答复 |
| --- | --- | --- |
| `identities` | `softDelete`, (中文(简体) ), `restore`, (中文(简体) ), `erase`, (中文(简体) ), `link`, (中文(简体) ), `unlink` | 该行 |
| `sessions` | `revoke`, (中文(简体) ), `revokeByHash` | 会议结束 |
| `sessions` | `revokeAllForIdentity` | 届会结束 |
| `cfg.stores.credentials` | `revoke` 编号 : `revokeByKind`, (中文(简体) ), `delete` 编号 : `deleteByKind` | 线条/行 |
| `apiKeys` | `revoke` 编号 : `revokeAll` | 密钥 / 密钥已撤销 |
| `passkeys` | `revoke` 编号 : `revokeAll` | 密码 / 密码被取消, 没有秘密 |
| `mfa` | `removeTotp`, (中文(简体) ), `removeWebauthnMfa`, (中文(简体) ), `removeBackupCodes` | `{ removed }` - 伯爵,而不是那些带秘密的行 |
| `orgs` | `removeMember`, (中文(简体) ), `setRoles` | 成员名单 **已消毒** 实际存储的角色集 |
| `flows` | `completeAccountDeletion`, (中文(简体) ), `cancelAccountDeletion`, (中文(简体) ), `completeEmailVerification`, (中文(简体) ), `linkProvider`, (中文(简体) ), `unlinkProvider` | `identity`,与已返回的地块一起 |
| `webhooks` | `deliverOne` | 一个 `Delivery` 每个合格终点 |
| `pending` | `flush`, (中文(简体) ), `discard` | `{ published }` 编号 : `{ discarded }` |
| `anomaly` | `unregister` | 是否删除了任何东西 |

请求(`apiKeys.requireScopes`, (中文(简体) ), `hijack.applyReaction`登记`anomaly.register`, (中文(简体) ), `providers.register`和 `plugins.dispose` 留下来 `void`:它们抛出或不投出,返回值就是噪音.

### 批次写

批量表格将列表并回答他们所写的行:

```typescript
const written = await auth.identities.updateProfileMany([
  { id: a, patch: { displayName: 'A' }, expectedVersion: 3 },
  { id: b, patch: { displayName: 'B' }, expectedVersion: 7 },
])
written.map((row) => row.id)  // [a] when b lost its version race
```

备查 `identities` (单位:千美元)`softDeleteMany`, (中文(简体) ), `restoreMany`, (中文(简体) ), `eraseMany`, (中文(简体) ), `updateProfileMany`, (中文(简体) ), `linkMany`, (中文(简体) ), `unlinkMany`和 `sessions` (单位:千美元)`revokeAllForIdentities`, (中文(简体) ), `revokeByHashes`) (中文(简体) ). 每倒塌一个 每个表格中适配器可以表达并循环的语句,所以每个适配器 支持每个批量表单.

A 类 **难** 失败 - 违反约束 - 丢弃和中止您的交易, 所以一个 坏行卷起整批回. A 类 **软** 失败 - 失去的乐观- 锁定比赛, a 丢失行 - 离开行的答案而不扔出.

## 活动

每个操作员选择它运行的地方. 一个 `origin` 处理器在发射的服务器上运行一次 那个请求是同步上下文。 A 类 `fleet` 处理器,默认在每一个服务器上运行;在其他服务器上运行 获得有效载荷的副本,而不请求上下文.

```typescript
import { redisEvents } from '@gentleduck/auth/adapters/redis'

const auth = createAuth({ events: redisEvents({ redis }) /* ... */ })

// A write that must happen once: origin.
auth.events.on('session.revoked', (e) => auditLog.write(e), { delivery: 'origin' })

// State every server keeps: fleet.
auth.events.on('authz.revoked', ({ identityId }) => decisionCache.drop(identityId))
```

`fleet` 处理者需要 `redisEvents` 一旦有多个服务器, 因为进程默认 运行他们在一个。 生产 `strict()` 在进程总线持有时拒绝该总线 `fleet` 管理者,当每个管理者都是的时候 `origin`它只看到在它面前注册的操作者 运行,所以在每次 `on()` 财务报告和审定财务报表 `use()`。 Webhooks 输出为 `origin`一次每次发射.

## 服务器适配器

没有航道也没有客户 您的应用程序将自己的路线写入 `auth.flows.*` 并召唤他们 拥有自己的 `fetch`。每个适配器只携带胶水:一个CSRF后卫、呼叫者的地址和用户代理, 一个意图作者、演员背景和错误映射.

```typescript
import { AuthError } from '@gentleduck/auth/core'
import { applyIntents, expressCaller, expressCsrf, toHeaders } from '@gentleduck/auth/server/express'
import { errorToHttp } from '@gentleduck/auth/server/generic'

app.use('/auth', expressCsrf(auth))

app.post('/auth/signin', async (req, res) => {
  const { providerId, input } = req.body ?? {}
  if (typeof providerId !== 'string') throw new AuthError('AUTH_INVALID_PARAMETERS')
  const headers = toHeaders(req.headers)
  const { intents } = await auth.flows.signIn({
    input,
    providerId,
    ...expressCaller(req),
    previousSid: auth.transport.extract({ headers }) ?? undefined,
  })
  applyIntents(intents, res)
})

app.post('/auth/signout', async (req, res) => {
  const sid = auth.transport.extract({ headers: toHeaders(req.headers) })
  applyIntents(sid ? (await auth.flows.signOut(sid)).intents : auth.transport.revoke(), res)
})

// A refusal throws an AuthError; `errorToHttp` maps it to the status and body
app.use((err, _req, res, _next) => {
  const { status, body } = errorToHttp(err)
  res.status(status).json(body)
})
```

| 框架 | 导入 | 粘贴 |
| --- | --- | --- |
| 快递 | `@gentleduck/auth/server/express` | `expressCsrf`, (中文(简体) ), `expressCaller`, (中文(简体) ), `applyIntents`, (中文(简体) ), `expressActorContext` |
| 浩诺 | `@gentleduck/auth/server/hono` | `honoCsrf`, (中文(简体) ), `honoCaller`, (中文(简体) ), `honoActorContext` |
| 快捷化 | `@gentleduck/auth/server/fastify` | `fastifyCsrf`, (中文(简体) ), `fastifyCaller`, (中文(简体) ), `fastifyWithActor` |
| 科亚 | `@gentleduck/auth/server/koa` | `koaCsrf`, (中文(简体) ), `koaCaller`, (中文(简体) ), `koaApplyIntents`, (中文(简体) ), `koaActorContext` |
| 网点JS | `@gentleduck/auth/server/nestjs` | `makeCsrfGuard`, (中文(简体) ), `makeGuard`, (中文(简体) ), `nestCaller`, (中文(简体) ), `NestExceptionFilter`, (中文(简体) ), `CurrentSession` |
| 爱莉西亚 | `@gentleduck/auth/server/elysia` | `elysiaCsrf`, (中文(简体) ), `elysiaCaller`, (中文(简体) ), `elysiaWithActor` |
| 下一个.js | `@gentleduck/auth/server/next` | `withNextCsrf`, (中文(简体) ), `nextCaller`, (中文(简体) ), `nextWithActor` |
| (原始内容存档于2018-10-21) (英语). gRPC | `@gentleduck/auth/server/grpc` | `withGrpc` |
| 网络获取 | `@gentleduck/auth/server/generic` | `executeIntents`, (中文(简体) ), `jsonResponse`, (中文(简体) ), `errorResponse`, (中文(简体) ), `errorToHttp`, (中文(简体) ), `readBodyJson` |

你现在的路线是什么

-   **中国证监会** 在注册,签出,提供者开始 和所有其他突变.
-   **OAuth召回的电话不设防.** 苹果公司通过设计发布其跨站点,签名状态是: 证明。 读取 GET 上的查询, POST 上的urlencoded body, 然后通过 `cookieHeader` 财务报告和审定财务报表 `previousSid`。 。 。 .
-   **`csrfHash` 任何你回答的会话.** 它是服务器侧状态;浏览器持有平正文本 .
-   **会议涉及每个因素的变化.** 添加、去除或替换一个因子, 刻出备份代码 并记住一个设备 取用呼叫器的会话, 拒绝一个低于 AAL 2 的,一旦账户持有任何 密码旁的因数。 费率限制 `stepup:${identityId}`。 。 。 .
-   **会议的租户** 转至 `auth.mfa.*`没有租户,则只涉及没有租户的因素.
-   **申请的房客**,在一个多租户应用程序中,在演员范围上命名(`tenantId: (req) => ...`和继续 `resolveSession`没有它,一个租户的一次会议 决心没有人.

`examples/duck-auth` 拥有所有8个框架的完整路径集.

## 交付

每个出局的指使 - 魔法链接,电子邮件验证,密码重置,账户删除及其撤销 链接 - 转到一个 `deliver` 调用引擎配置。 库在 URL 上签名并交出 接收者的身份,模板 vars 和租户;东道主选择运输并写入 模板。 每个消息的 `vars` 已经签名 `url` 及其寿命 `ttlMin`; 打开 `kind` 缩进 更进一步`requiresMfa` 密码重置, `restorableUntil` ))). 页面存档备份,存于互联网档案馆. 扔出它来报告失败: 流量对呼叫者的回答是相同的 方式和报告 拒绝作为 `signin.failed` 事件,永远不要丢弃的文本.

```typescript
const auth = createAuth({
  baseUrl: 'https://app.example.com',
  deliver: async ({ identity, kind, vars }) => {
    if (kind === 'magic-link') return mailer.send(identity.profile.email, signInTemplate(vars.url))
    await mailer.send(identity.profile.email, genericTemplate(kind, vars))
  },
  // ...
})
```

## Captcha 核查员

```typescript
import {
  authTurnstileVerifier,
  authHCaptchaVerifier,
  authRecaptchaV3Verifier,
} from '@gentleduck/auth/core'
```

## 工具

| 路径 | 什麽 |
| --- | --- |
| `@gentleduck/auth/oidc` | OIDC 发现- doc + JWKS 帮助器 |
| `@gentleduck/auth/oidc/op` | 完整 OAuth2/OIDC OP : (简体中文) `/authorize` (代码+S256 PCE), `/token` (auth code + 刷新,由家庭轮流), `/userinfo`, (中文(简体) ), `/introspect`, (中文(简体) ), `/revoke`, (中文(简体) ), `/register` (RFC 7591动态客户登记) |
| `@gentleduck/auth/oidc/op/drizzle/pg` | Postgres Drizzle 存储 OIDC OP( 5个表格, GC 助手) |
| `@gentleduck/auth/oidc/op/drizzle/sqlite` | 用于OIDC OP的 SQLite Drizzle 商店 |
| `@gentleduck/auth/oidc/op/drizzle/mysql` | MySQL 数据 为OIDC OP提供的 Drizzle 商店 |

## 生产原始产品

-   **`AuthEngine.strict()`** - 何时启动时间验证 `NODE_ENV` 没有 `development` 或者说 `test`,未设置包含:拒绝 `NoopLimiter`,内存存储,丢失 `lockout` 非 HTTPS 监听器 `baseUrl`
-   **`JwtTransport.rotateSignKey()` + 键 `retireVerifyKey(kid)`** - 零下限 JWKS 旋转并有重叠窗口
-   **`applyCompliancePreset(cfg, 'gdpr' | 'hipaa' | 'soc2' | 'fips')`** - 一个在配置之上的自由函数,而不是引擎方法:它将三个会话TTL推向被命名的地层. 密码、外交部和Api-key 楼层是提供者级别 - 通过相同的预设 `passwords({ compliance })` 及其兄弟姐妹 -- -- 和 `strict()` 执行其余数据,包括备份数据
-   **`WebhookDeliverer`** - HMAC机体 + 时间戳 + 新鲜耐受性 指数回放 死字槽 SSRF 守护端点 URL, `redirect: 'error'` 发送时
-   **`auth.hijack` + 键 `auth.anomaly`** - 漂移探测、决定梯子(允许/升级/拒绝),可插入信号
-   **`redisIdempotency` 编号 : `valkeyIdempotency`** - 每(身份,钥匙)墓碑+对东道主的再玩安全变异路线的民意调查;东道主持有,引擎不持有
-   **DPOP 软件** (RFC 9449) - 持有无记名证的证明 `ath` 绑定和服务器非ce
-   **租户边界**: 一通指定无租户的电话只收到无租户的记录 `ALL_TENANTS` 每个租户; 只有自己的租户才能解决一个会话或 API 密钥

## 安全态势

`AuthEngine.strict()` 运行每个生产级的门 在靴子之前.

见 [`SECURITY.md`](https://npmcn.com/package/%40gentleduck/auth/SECURITY.md) 对于STRIDE / OWASP ASVS 绘制图,显示库所减轻的每一个威胁以及主机应用程序必须拥有的每一个威胁.

## 模块大小( gzipped)

| 模块 | 大小 |
| --- | --- |
| 核心 `AuthEngine` (典型导入) | ~22 KB (韩语) |
| 每一次运输 | 2 - 6个KB |
| 每个供应商 | 1.5 - 8个KB |
| 每个适配器 | 2 - 9个KB |
| 每个服务器中间软件 | 2-4个KB |

真正的部署只输入他们电线的 最终达到25 - 60 KB的总数。 "进口一切"最坏的情况`import * from '@gentleduck/auth'`)不是预期使用.

## 文档

-   站点 : [温和多克.org/duck-auth](https://gentleduck.org/duck-auth)
-   参考应用 : [`apps/duck-auth-demo`](https://github.com/gentleeduck/duck-iam/tree/main/apps/duck-auth-demo) - 每条流都运行端到端
-   兄弟姐妹重现 : [`@gentleduck/iam`](https://www.npmjs.com/package/@gentleduck/iam), (中文(简体) ), [`@gentleduck/ui`](https://github.com/gentleeduck/duck-ui), (中文(简体) ), [`@gentleduck/upload`](https://github.com/gentleeduck/duck-upload), (中文(简体) ), [`@gentleduck/md`](https://github.com/gentleeduck/duck-md)

## 捐款

Repo 中的 PR 核对表 + 样式注释 [`CONTRIBUTING.md`](https://github.com/gentleeduck/duck-iam/blob/main/CONTRIBUTING.md)。 。 。 . 安全披露: [`SECURITY.md`](https://npmcn.com/package/%40gentleduck/auth/SECURITY.md)。 。 。 .

## 许可证

麻省理工学院. 见 [`LICENSE`](https://npmcn.com/package/%40gentleduck/auth/LICENSE)。 。 。 .

## 常见问题

### @gentleduck/auth 是什么？

现代TypeScript应用程序的认证\. 面相相相通,框架可知,可通运\. 与@gentleduck/iam对等\.

### 如何安装 @gentleduck/auth？

在项目目录运行 npm install @gentleduck/auth，或使用 pnpm add / yarn add / bun add。

### @gentleduck/auth 支持 TypeScript 吗？

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

### @gentleduck/auth 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gentleduck/auth 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gentleduck/auth 可以商用吗？

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

### @gentleduck/auth 的下载量有多少？

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

### @gentleduck/auth 还在维护吗？

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

