# @askrjs/auth 中文文档

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

版本：0\.5\.1
npm 元数据更新时间：2026-11-02T10:25:13.069Z
中文译文更新时间：2026-11-06T23:35:21.778Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：339 kB，46 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：3 个
- 首次发布：2026-07-15T19:20:41.709Z
- 最新版本发布：2026-11-02T10:25:12.606Z
- 近 30 天下载量：2448（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

为 Askr 共享认证合同和请求认证解析

## 安装

```sh
npm install @askrjs/auth
```

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

## README

# @ askrjs/ auth (英语)

[![CI](https://github.com/askrjs/askr-auth/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/askrjs/askr-auth/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/%40askrjs%2Fauth.svg)](https://www.npmjs.com/package/@askrjs/auth)

Askr 拥有框架,域中立认证原始. Server会话需要节点.js 24或更新. 低级的OIDC和密码客户端条目保留了它们明显的Web Crypto/Fetch或Census API边界.

## 特性矩阵

| 条目 | 拥有 | 不拥有 |
| --- | --- | --- |
| `@askrjs/auth` | `Principal`,验证背景和要求,无记名/cookie/会议要求解决 | 用户、组织、证书存储、密码散列 |
| `@askrjs/auth/jwt` | RS256/ES256 签发和核证、索赔、JWKS延期 | 坚守或撤销列表 |
| `@askrjs/auth/oidc` | 发现 授权码 PKCE 调用关联 核实的ID -token -`Principal` 交换 | 提供者 UI, 账户连接, 刷新存储 |
| `@askrjs/auth/server` | 服务器拥有的提供者交易、封存会话 cookie、刷新家庭和应用程序钩 | 应用程序用户/政策和HTTP适配器所有权 |
| `@askrjs/auth/providers/auth0` | 本地 Auth0 提供者政策和 API 受众 | 浏览器 SDK 和应用路径 |
| `@askrjs/auth/providers/microsoft` | 租户捆绑的微软供应商和明确的API权限 | 多租户推论和应用路线 |
| `@askrjs/auth/providers/google` | 谷歌供应商、主机域政策和明确的API权限 | 工作空间管理和应用路线 |
| `@askrjs/auth/providers/apple` | 苹果网登录和每日账户检查 | API 访问控制赠款和申请途径 |
| `@askrjs/auth/saml` | SP元数据和请求,签名/加密响应验证,请求关联 | IdP 操作, SLO, IdP 启动的 SAML, 外部 CA 信任政策 |
| `@askrjs/auth/mfa` | TOTP和WebAuthn 注册/认证核查 | 证书存储、恢复政策、入学 |

重放预防在应用程序的持久存储界限内。 SAML 需要原子 `requestStore.consume()`. TOTP 返回已接受的计数器,以便它可以被原子标记使用. WebAuthn 返回已核实的新签名计数器,这样它可以在解剖上被坚持.

## 请求认证

`createAuth()` 将 Bearer JWTs, JWT cookie, 和不透明的会话 cookie 解为一个认证上下文 . 无效、过期或畸形的JWT始终被视为未经认证和解决 继续到下一个配置的证书源。 租户、本金、, 或会话存储仍然拒绝 `resolve()` 因此,呼叫者可以处理不可用的依赖.

## 伊办

`exchangeCode()` 接受回调和存储的授权请求。 它检查 状态在网络访问之前,然后验证所需的 ID 令牌,以防发现和 JWKS 前 返回时 `{ tokens, principal }`。只需要识别该客户端;任何明确的 `azp` 必须匹配配置的客户端ID。 额外的观众信任不属于此客户端配置.

OIDC 的入站点也在浏览器中运行, 包含 Web Crypto, Fetch, 和 UTF-8 编码支持. JWT 解码使用浏览器- 本地字节并需要 No Node `Buffer` 混合填充剂。 浏览客户端省略 `clientSecret`; 保留授权 请求回调关联。 本条目为低等协议原始; 3; 它不会取代服务器拥有的应用程序的签名或保留会话符 浏览器。 申请会话使用 [服务器合同](https://npmcn.com/package/%40askrjs/auth/docs/server-session-contract.md) 编辑 [0.5 移徙](https://npmcn.com/package/%40askrjs/auth/docs/0.5.0-api.md#browser-session-migration)。 。 。 .

```ts
import { createOidcClient } from "@askrjs/auth/oidc";

const client = createOidcClient({ issuer, clientId, clientSecret, redirectUri });
const request = await client.createAuthorizationRequest();
const result = await client.exchangeCode({ code: callback.code, state: callback.state, request });
```

## 供应商申请会话

配置共享 `createProviderSession` 引擎从 `@askrjs/auth/server` 与一个或多个本地供应商结合,然后将其绑定在提供者-自动模式中 `@askrjs/server`服务器拥有授权/召回运输,密封饼干, 刷新令牌和每笔资源令牌赠款. `createSessionAuth` 从 `@askrjs/askr/router` 将公开会话快照约束在SRS或SPA应用程序; 供应商的代号 和客户端的秘密 保持服务器侧。 见承诺 [所有权/API合同](https://npmcn.com/package/%40askrjs/auth/docs/server-session-contract.md) 设置 [自动 0](https://npmcn.com/package/%40askrjs/auth/docs/providers-auth0.md), (中文(简体) ), [微软](https://npmcn.com/package/%40askrjs/auth/docs/providers-microsoft.md), (中文(简体) ), [谷歌](https://npmcn.com/package/%40askrjs/auth/docs/providers-google.md) 或者说 [苹果公司](https://npmcn.com/package/%40askrjs/auth/docs/providers-apple.md)。 。 。 .

`@askrjs/auth/browser` 和只开发的 `@askrjs/auth/auth0` SDK 适配器 在0.5中删除。 没有替换浏览器持有的会话/ SDK 路径 . 已发布的0.4.2浏览器生命周期要求明确 [服务器会话迁移](https://npmcn.com/package/%40askrjs/auth/docs/0.5.0-api.md#browser-session-migration)。 。 。 .

## 外交部

```ts
import { generateTotpSecret, verifyTotpCode } from "@askrjs/auth/mfa";

const secret = generateTotpSecret();
const result = await verifyTotpCode({ secret, code });
if (result.valid) await counters.consume(result.counter); // application-owned atomic replay guard
```

TOTP默认为SHA-1,6位数,30秒周期,以及一阶窗口. SHA-256, SHA-512, (英语), 并且支持八位数代码。 WebAuthn 使用精确的 Base64url 挑战, 精确的来源 允许列表, 1 RP ID, 以及默认的用户验证 。 它接受ES256、RS256(RSA 2048-bit或 edDSA/Ed25519 键。 注册接受 `none` 并用密码验证包装 仅自证; 证书支持的证明被故意拒绝。 核查也 对客户端数据、证书身份、质疑、证明对象、, 验证器数据,以及解析或加密工作前的签名.

## 萨姆

只有服务器 `@askrjs/auth/saml` 入口提供狭义由SP启动的 SAML 2.0 流: 元数据生成, 已签名或未签名的 HTTP- Redirect Authn 请求, 已签名的断言验证, 可选的签名响应,加密断言,请求相关性,以及原子回放保护. 它有意与 `createAuth()` 和软件包根.

```ts
import { createSamlServiceProvider } from "@askrjs/auth/saml";

const saml = createSamlServiceProvider({
  entityId: "https://app.example.com/saml/metadata",
  acsUrl: "https://app.example.com/saml/acs",
  idp: {
    entityId: "https://idp.example.com",
    ssoUrl: "https://idp.example.com/sso",
    certificates: [idpCertificate],
  },
  requestStore, // save/get plus an atomic consume operation
});

const { url } = await saml.createAuthnRequest({ relayState: "return-to" });
const principal = await saml.validateResponse({ samlResponse, relayState: "return-to" });
```

请求商店是一个安全边界: `consume(id)` 必须解剖返回 `false` (单位:千美元) 缺少、过期或先前使用的身份证。 校验器默认为10分钟请求 TTL, 5分钟的确认年龄 和60秒的时钟 总是签名; `requireSignedResponse` 还需要外部反应签名.

JWT发行和验证支持RS256配有RSA密钥,ES256配有EC P-256密钥. 一个JWK的 `alg` 可省略并从密钥形状中推断出来;当存在时,必须与密钥相匹配.

## 安装

```sh
npm install @askrjs/auth
```

## 0.5.0 准备

见 [完整 API 决定和迁移](https://npmcn.com/package/%40askrjs/auth/docs/0.5.0-api.md) 财务报告和审定财务报表 [强化证据](https://npmcn.com/package/%40askrjs/auth/docs/0.5.0-hardening.md)。浏览器密码助手仍然在 `@askrjs/auth/webauthn-client`; CBOR/COSE 解析和 Base64url 转换为私有. 应用程序商店保留回放、证书和政策所有权.

## 常见问题

### @askrjs/auth 是什么？

为 Askr 共享认证合同和请求认证解析

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

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

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

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

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

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

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

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

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

@askrjs/auth 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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