# @authup/server-adapter-kit 中文文档

规范地址：https://npmcn.com/package/%40authup/server-adapter-kit/

版本：1\.0\.0-beta\.73
npm 元数据更新时间：2026-11-01T20:47:08.878Z
中文译文更新时间：2026-11-07T06:18:21.512Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：66.7 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.0\.0
- 运行依赖：6 个
- 首次发布：2024-10-04T07:48:23.342Z
- 最新版本发布：2026-11-01T20:47:08.726Z
- 近 30 天下载量：3305（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 43 个）

## 中文简介

在您自己的 API 中校验 Authup 访问令牌, 本地对照域键, 或者通过内向检查 .

## 安装

```sh
npm install @authup/server-adapter-kit
```

也可以使用：`pnpm add @authup/server-adapter-kit`、`yarn add @authup/server-adapter-kit`、`bun add @authup/server-adapter-kit`

## README

![Authup logo](https://raw.githubusercontent.com/authup/authup/master/.github/assets/logo.svg)

# @ authup/ server- adapter- kit

**在您自己的 API 中校验 Authup 访问令牌, 本地对照域键, 或者通过内向检查 .**  
验证器,缓存和无记名者 解析后节点,Socket。 IO和Web适配器.

[![npm version](https://img.shields.io/npm/v/@authup/server-adapter-kit)](https://www.npmjs.com/package/@authup/server-adapter-kit) [![CI](https://github.com/authup/authup/actions/workflows/main.yml/badge.svg)](https://github.com/authup/authup/actions/workflows/main.yml) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://npmcn.com/package/%40authup/server-adapter-kit/LICENSE)

[**安装**](https://npmcn.com/package/%40authup/server-adapter-kit/#readme-installation) • 妇女 [使用量](https://npmcn.com/package/%40authup/server-adapter-kit/#readme-usage) • 妇女 [API 密码](https://npmcn.com/package/%40authup/server-adapter-kit/#readme-api) • 妇女 [文档](https://authup.org/)

* * *

## 为什么?

一个信任由Authup发布的令牌的API必须取回正确的签名密钥,检查签名和过期,拒绝非访问令牌的令牌,并决定一个被核实的结果可以再用多久. 这个软件包做过一次,所以每个运输适配器(和你自己的代码)都共享同样的规则.

| 关切 | 没有它 | 用这个 |
| --- | --- | --- |
| **签名密钥** | 抓取 JWKS , 选取密钥, 缓存它, 旋转时反射 | 符号域的密钥由 `kid` 每个域和密钥缓存5分钟 |
| **权限** | 调用内向端点并解析答案 | 带有您 API 客户端证书的远程模式内观并返回对象的 `permissions` |
| **托肯类** | 持同一把钥匙签的汇票或外交部的汇票 | 任意 `kind` 其他 `access_token` 被拒绝 |
| **重复请求** | 检查每个请求中的每个符号 | 可选 `cache` (memory或Redis) 将结果保存到符号过期 |
| **约束令牌** | 比较 `cnf.x5t#S256` 你自己来 | 证书绑定符 (RFC 8705) 失败, 除非显示的缩写匹配 |

对于一个HTTP服务器,一个Socket. IO 服务器或网络 `Request` 处理器,使用此包上的一个适配器 : [`@authup/server-adapter-node`](https://github.com/authup/authup/tree/master/packages/server-adapter-node), (中文(简体) ), [`@authup/server-adapter-socket-io`](https://github.com/authup/authup/tree/master/packages/server-adapter-socket-io) 或者说 [`@authup/server-adapter-web`](https://github.com/authup/authup/tree/master/packages/server-adapter-web)。 。 。 .

## 安装

```shell
npm install @authup/server-adapter-kit
```

一揽子措施仅限无害环境管理,需要节点 `>=26.0.0`。它没有同伴依赖关系。 安装 [`@authup/core-http-kit`](https://github.com/authup/authup/tree/master/packages/core-http-kit) 当您使用远程模式时 `createClientTokenCreator`。 。 。 .

## 使用量

### 本地验证

```typescript
import { TokenVerifier } from '@authup/server-adapter-kit';

const verifier = new TokenVerifier({ baseURL: 'https://auth.example.com' });

const data = await verifier.verify(token);
// data.sub, data.sub_kind, data.realm_id, data.realm_name, data.scope, data.exp
```

没有 `creator` 核查者检查标志本身:

-   标题 `kid` 有效载荷必须携带 `realm_id`· ;
-   从 `GET /realms/<realm_id>/jwks/<kid>`所以另一个域的密钥 永远无法验证符号;
-   签名, `exp` 和标志 `kind` 检查;
-   `permissions` 总是 `[]`,因为一个进入符 不携带它们.

### 远程验证

```typescript
import { createClientTokenCreator } from '@authup/core-http-kit';
import { TokenVerifier } from '@authup/server-adapter-kit';

const verifier = new TokenVerifier({
    baseURL: 'https://auth.example.com',
    creator: createClientTokenCreator(
        { id: process.env.AUTHUP_CLIENT_ID ?? '', secret: process.env.AUTHUP_CLIENT_SECRET ?? '' },
        { client: { baseURL: 'https://auth.example.com' } },
    ),
});

const data = await verifier.verify(token);
const canRead = data.permissions.some((permission) => permission.name === 'order_read');
```

与一个 `creator` 核查员将标志发给 `POST /token/introspect`,用一种标志认证了创造者薄荷(再用薄荷) `401`) (中文(简体) ). 答案包括主题 `permissions`。不活动符号抛出.

给你API的客户端 `token_introspect` 允许。 如果没有它,客户端可能只能透视给自己发行的会令牌,其他所有会令牌都报告为不活动.

### 缓存已校验的令牌

```typescript
import { MemoryTokenCache, RedisTokenCache, TokenVerifier } from '@authup/server-adapter-kit';

const verifier = new TokenVerifier({
    baseURL: 'https://auth.example.com',
    cache: new MemoryTokenCache(),
});

const shared = new TokenVerifier({
    baseURL: 'https://auth.example.com',
    cache: new RedisTokenCache('redis://127.0.0.1:6379'),
    maxRemoteCacheTTL: 60,
});
```

验证结果仅在您通过时缓存 `cache`。结果保存在符物的剩余寿命,或最多 `maxRemoteCacheTTL` 秒,在远程模式中。 条目由命名空间和符号的 SHA-256 散列键入,默认名称空间为 `authup:<local|remote>:<baseURL>`。 。 。 . `MemoryTokenCache` (再由出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出自出. `RedisTokenCache` 使用连接字符串, a `redis-extension` 客户端,或无(redis-extension的默认连接). 隐藏你自己的枪械 `ITokenCache` (单位:千美元)`get(key)` 财务报告和审定财务报表 `set(key, entry, ttl)`) (中文(简体) ).

签名密钥从未存储于 `cache`:它们保持进程内存,因为 `CryptoKey` 无法序列化 .

### 约束令牌

```typescript
const bound = await verifier.verify(token, {
    certificateThumbprint: () => thumbprintOfPresentedCertificate(),
});
```

代币携带 `cnf` (RFC 8705) 失败,除非 `certificateThumbprint` 解析 SHA-256 DER 缩写 `cnf.x5t#S256`。提供方只被调用这样的符号,检查会运行在每一个呼叫上,包含缓存结果.

### 分析授权页眉

```typescript
import { extractBearerToken } from '@authup/server-adapter-kit';

const value = extractBearerToken(authorizationHeader); // undefined when the header is absent
```

它会扔 `BearerTokenMalformedError` (单位:千美元)`bearer_token_malformed`, HTTP 401 对于一个没有空格的标题, 一个除此之外的其他方案 `Bearer` (大小写不敏感),或为空值.

## 选项

`new TokenVerifier(context)`数字 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `baseURL` | `string` | (必须) | Authup API 的基础 URL |
| `creator` | `TokenCreator` | `undefined` | 切换到远程模式: 薄荷表示代号 |
| `cache` | `ITokenCache | false` | `undefined` | Caches 校验结果;没有它,每一次通话都会再次校验 |
| `cacheNamespace` | `string` | `authup:<local|remote>:<baseURL>` | 将共享一个缓存的核查者条目分开。 只有配置相同的核查者可以共享命名空间 |
| `maxRemoteCacheTTL` | `number` | 剩余符号寿命 | 缓存远程结果的上行绑定秒数 |
| `jwkCache` | `{ ttl?, timeout? } | false` | `{ ttl: 300, timeout: 10 }` | 为本地模式签名密钥缓存, 保存在进程内存中 . `ttl` 是秒键保留了缓存( q)`0` 存储什么, `timeout` 获取密钥可能需要的秒. `false` 获取每次校验的密钥 |

`verify(token, options)`数字 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `certificateThumbprint` | `string | () => string | undefined | Promise<string | undefined>` | `undefined` | 已出示客户端证书的缩略图, 或是其懒惰的提供者 |

## API 密码

| 导出 | 仁爱 | 目的 |
| --- | --- | --- |
| `TokenVerifier` | 类 | `verify(token, options?)` |
| `ITokenVerifier` | 接口 | 这个 `verify(token, options?)` 适配方接受的合同 |
| `MemoryTokenCache` | 类 | 进行中 `ITokenCache` 每入TTL(从担保出口) |
| `RedisTokenCache` | 类 | 重新支持 `ITokenCache` |
| `ITokenCache`, (中文(简体) ), `TokenCacheEntry` | 类型 | 担保的缓存合同,你自己的缓存 |
| `extractBearerToken` | 函数 | 读取一个符号 `Authorization` 页眉值 |
| `assertTokenCertificateBinding` | 函数 | RFC 8705拇指印自己检查 |
| `TokenVerifierContext`, (中文(简体) ), `TokenVerifyOptions`, (中文(简体) ), `TokenVerificationData` | 类型 | 选项和结果形状 |

## 页:1

-   **本地模式不显示撤销 .** 一个被取消会话的符号持续验证直到到期,一个已禁用的签名密钥持续验证直到其缓存条目过期(默认为5分钟). 使用远程模式, 或简称 `jwkCache.ttl`这很重要.
-   **错误是 `JWTError`编号.** 签名错误、 索赔缺失或投错 `invalid_token`,过期的符号 `expired_token`,不活动 `inactive_token`。在远程模式下,其他失败都是 `invalid_token`;服务器本身的错误代码没有通过.
-   **结果就是复制品.** `verify` 返回一个克隆,这样它就永远不会改变缓存的条目.
-   **亲切的标志通过.** 只有礼物 `kind` 其他 `access_token` 被拒绝.

## 许可证

由 所制

现按 [Apache 2.0 许可证](https://npmcn.com/package/%40authup/server-adapter-kit/LICENSE)。 。 。 .

## 常见问题

### @authup/server-adapter-kit 是什么？

在您自己的 API 中校验 Authup 访问令牌, 本地对照域键, 或者通过内向检查 \.

### 如何安装 @authup/server-adapter-kit？

在项目目录运行 npm install @authup/server-adapter-kit，或使用 pnpm add / yarn add / bun add。

### @authup/server-adapter-kit 支持 TypeScript 吗？

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

### @authup/server-adapter-kit 支持 ESM 还是 CommonJS？

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

### @authup/server-adapter-kit 需要什么版本的 Node\.js？

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

### @authup/server-adapter-kit 可以商用吗？

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

### @authup/server-adapter-kit 的下载量有多少？

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

### @authup/server-adapter-kit 还在维护吗？

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