# @authup/specs 中文文档

规范地址：https://npmcn.com/package/%40authup/specs/

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

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

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

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

- 包体积（解压后）：187 kB，77 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.0\.0
- 运行依赖：4 个
- 首次发布：2025-01-20T20:59:42.244Z
- 最新版本发布：2026-11-01T20:47:35.463Z
- 近 30 天下载量：4431（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 44 个）

## 中文简介

OAuth 2.0,OpenID Connect,JWT和JWK的常数,类型和出错类,因为Authup使用它们.

## 安装

```sh
npm install @authup/specs
```

也可以使用：`pnpm add @authup/specs`、`yarn add @authup/specs`、`bun add @authup/specs`

## README

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

# @ authup/ 规格

**OAuth 2.0,OpenID Connect,JWT和JWK的常数,类型和出错类,因为Authup使用它们.**  
Authup 登录共享的两侧的授予名称、令牌有效载荷形状、错误代码和范围帮助器.

[![npm version](https://img.shields.io/npm/v/@authup/specs)](https://www.npmjs.com/package/@authup/specs) [![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/specs/LICENSE)

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

* * *

## 合适的话

`@authup/specs` 是一个基础包 : [`@authup/core-kit`](https://github.com/authup/authup/tree/master/packages/core-kit), (中文(简体) ), [`@authup/core-http-kit`](https://github.com/authup/authup/tree/master/packages/core-http-kit),服务器和服务器适配器都从中取出协议词汇. 您在读取 Authup 令牌或协议错误时直接安装它, 例如输入解码访问令牌为 `OAuth2TokenPayload` 或将错误与 `OAuth2ErrorCode.INVALID_GRANT`它不是一个通用的OAuth2库:它包含Authup的发文和答案,包括Authup自己的主张,例如: `realm_name` 财务报告和审定财务报表 `sub_kind`。 。 。 .

## 安装

```shell
npm install @authup/specs
```

仅限无害环境管理。 节点.js `>=26.0.0`,或浏览器捆绑器。 不存在同伴依赖关系.

## 使用量

### 托肯有效载荷和赠款

```typescript
import type { OAuth2TokenGrantResponse, OAuth2TokenPayload } from '@authup/specs';
import { OAuth2SubKind, OAuth2TokenGrant, OAuth2TokenKind } from '@authup/specs';

function isUserAccessToken(payload: OAuth2TokenPayload) : boolean {
    return payload.kind === OAuth2TokenKind.ACCESS &&
        payload.sub_kind === OAuth2SubKind.USER;
}

OAuth2TokenGrant.DEVICE_CODE; // 'urn:ietf:params:oauth:grant-type:device_code'
```

`OAuth2TokenPayload` 这是JWT的索赔,加上Authup的索赔: `kind`, (中文(简体) ), `sub_kind`, (中文(简体) ), `realm_id`, (中文(简体) ), `realm_name`, (中文(简体) ), `client_id`, (中文(简体) ), `scope`, (中文(简体) ), `session_id` 编号 : `sid`, (中文(简体) ), `amr`, (中文(简体) ), `acr`, (中文(简体) ), `cnf`, (中文(简体) ), `realm_access` 财务报告和审定财务报表 `global_access`。 。 。 . `OAuth2TokenGrantResponse` 这是 `/token` 答话.

### 范围

```typescript
import { hasOAuth2Scopes, mergeOAuth2Scopes } from '@authup/specs';

hasOAuth2Scopes('openid Email', ['email']); // true
mergeOAuth2Scopes('openid email', ['email', 'roles']); // 'openid email roles'
```

-   `hasOAuth2Scopes(granted, required)` 小写两边,接受空格或逗号分隔字符串或数组,然后返回 `false` 当什么也没有得到.
-   `deserializeOAuth2Scope` 财务报告和审定财务报表 `unwrapOAuth2Scope` 拆分和小写; `splitOAuth2Scope` 财务报告和审定财务报表 `mergeOAuth2Scopes` 分开和去除 但保持这个案子.

### 错误

错误类扩展 `AuthupError` 从 `@authup/errors` 并携带 OAuth2 错误代码 `data.error`数字 :

```typescript
import { OAuth2ErrorCode, OAuth2GrantError, isJWTError, isOAuth2Error } from '@authup/specs';

const error = OAuth2GrantError.invalid('refresh token is unknown');
error.data?.error === OAuth2ErrorCode.INVALID_GRANT; // true

function describe(e: unknown) : string {
    if (isJWTError(e)) return 'token rejected';
    if (isOAuth2Error(e)) return e.message;
    return 'unknown';
}
```

这个 `is*` 警卫们既符合JSON的例,也符合JSON的补水错误,因为他们读取了序列标记链而不是原型. `isJWTErrorCode` 财务报告和审定财务报表 `isJWKErrorCode` 测试一个赤色 `code` 绳子.

## API 密码

| 导出 | 仁爱 | 目的 |
| --- | --- | --- |
| `OAuth2TokenGrant`, (中文(简体) ), `OAuth2TokenKind`, (中文(简体) ), `OAuth2SubKind` | 语句 | 赠款类型、象征性类型(`access_token`, (中文(简体) ), `refresh_token`, (中文(简体) ), `id_token`, (中文(简体) ), `mfa_token`),主题类型 |
| `OAuth2AuthorizationResponseType`, (中文(简体) ), `OAuth2AuthorizationCodeChallengeMethod`, (中文(简体) ), `OAuth2AuthorizationPrompt`, (中文(简体) ), `OAuth2UIColorMode` | 语句 | `/authorize` 参数 |
| `OAuth2AuthenticationMethodReference`, (中文(简体) ), `OAuth2AuthenticationContextClass` | 语句 | `amr` (单位:千美元)`pwd`, (中文(简体) ), `otp`, (中文(简体) ), `ext`和 `acr` (单位:千美元)`urn:authup:pwd`, (中文(简体) ), `urn:authup:mfa`数值 |
| `OAuth2ErrorCode` | 语句 | RFC 6749, OIDC 和 RFC 8628 错误代码 |
| `OAuth2TokenGrantResponse`, (中文(简体) ), `OAuth2TokenPayload`, (中文(简体) ), `OAuth2TokenIntrospectionResponse`, (中文(简体) ), `OAuth2TokenPermission`, (中文(简体) ), `OAuth2JsonWebKey` | 类型 | 隐藏端点答案和符号内容 |
| `OAuth2Error` 财务报告和审定财务报表 `OAuth2RequestError`, (中文(简体) ), `OAuth2ClientError`, (中文(简体) ), `OAuth2ClientUnauthorizedError`, (中文(简体) ), `OAuth2GrantError`, (中文(简体) ), `OAuth2GrantTypeError`, (中文(简体) ), `OAuth2ScopeError`, (中文(简体) ), `OAuth2ResponseTypeError`, (中文(简体) ), `OAuth2AccessDeniedError`, (中文(简体) ), `OAuth2LoginRequiredError`, (中文(简体) ), `OAuth2MfaRequiredError`, (中文(简体) ), `OAuth2DeviceAuthorizationError`, (中文(简体) ), `OAuth2ServerError` | 类 | 静态工厂的礼宾出错`OAuth2GrantError.invalid()`, (中文(简体) ), `OAuth2DeviceAuthorizationError.slowDown()`, (...) (中文(简体) ) |
| `isOAuth2Error` 还有一个 `isOAuth2*Error` 每类警卫(无 `OAuth2LoginRequiredError`(中文(简体) ) | 函数 | 错误守护 |
| `serializeOAuth2Scope`, (中文(简体) ), `deserializeOAuth2Scope`, (中文(简体) ), `unwrapOAuth2Scope`, (中文(简体) ), `splitOAuth2Scope`, (中文(简体) ), `mergeOAuth2Scopes`, (中文(简体) ), `hasOAuth2Scopes` | 函数 | 范围字符串处理 |
| `JWTAlgorithm` | 语句 | `HS*`, (中文(简体) ), `RS*`, (中文(简体) ), `ES*`, (中文(简体) ), `PS*` (256、384、512) (中文(简体) ) |
| `JWTHeader`, (中文(简体) ), `JWTClaims` | 接口 | JWT标题和已登记索赔 |
| `JWTError`, (中文(简体) ), `isJWTError`, (中文(简体) ), `isJWTErrorCode` | 类, 函数 | 脚本出错( T)`expired_token`, (中文(简体) ), `inactive_token`, (中文(简体) ), `invalid_token`(中文(简体) ) |
| `getJWTClaimByPattern` | 函数 | 以路径模式读取索赔, 可选择匹配值或正则x |
| `JWKType`, (中文(简体) ), `JWKUse` | 语句 | 关键类型`oct`, (中文(简体) ), `rsa`, (中文(简体) ), `ec`)和使用(`sig`, (中文(简体) ), `enc`(中文(简体) ) |
| `JWKError`, (中文(简体) ), `isJWKError`, (中文(简体) ), `isJWKErrorCode` | 类, 函数 | 密钥错误 |
| `OpenIDProviderMetadata`, (中文(简体) ), `OpenIDTokenPayload`, (中文(简体) ), `OpenIDClaims` | 类型 | 发现文件、id token有效载荷和OIDC核心标准索赔 |
| `isOpenIDProviderMetadata` | 函数 | 保护发现文件 |

## 页:1

-   **`JWKType` 是 Authup 的密钥类型,而不是 JWK `kty`。 。 。 .** 其值为小写(`rsa`, (中文(简体) ), `ec`, (中文(简体) ), `oct`; RFC 7517 咒语 `kty` 作为 `RSA` 财务报告和审定财务报表 `EC`。 。 。 .
-   **缺失的 OpenID 请求是省略的密钥 .** `OpenIDClaims` 将每一项债权作为可选的,永远不要 `null`,而Authup 留下了权利要求,而不是发送 `null`。 。 。 .

## 许可证

由 所制

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

## 常见问题

### @authup/specs 是什么？

OAuth 2\.0,OpenID Connect,JWT和JWK的常数,类型和出错类,因为Authup使用它们\.

### 如何安装 @authup/specs？

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

### @authup/specs 支持 TypeScript 吗？

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

### @authup/specs 支持 ESM 还是 CommonJS？

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

### @authup/specs 需要什么版本的 Node\.js？

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

### @authup/specs 可以商用吗？

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

### @authup/specs 的下载量有多少？

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

### @authup/specs 还在维护吗？

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