# @access-tokens/express 中文文档

规范地址：https://npmcn.com/package/%40access-tokens/express/

版本：1\.1\.0
npm 元数据更新时间：2025-12-30T20:41:11.594Z
中文译文更新时间：2026-11-05T21:56:43.402Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：241 kB，27 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：8 个
- peer 依赖：express ^4\.18\.0 \|\| ^5\.0\.0
- 首次发布：2025-11-07T01:56:20.803Z
- 最新版本发布：2025-12-30T20:41:11.187Z
- 近 30 天下载量：14660（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 2 个）

## 中文简介

快捷路线和中间软件,用于个人访问令牌认证

## 安装

```sh
npm install @access-tokens/express
```

也可以使用：`pnpm add @access-tokens/express`、`yarn add @access-tokens/express`、`bun add @access-tokens/express`

## README

# @ access-tokens/ 表达

[![npm](https://img.shields.io/npm/v/@access-tokens/express)](https://www.npmjs.com/package/@access-tokens/express) [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

使用OAuth 2.0相容的JWT令牌交换进行个人访问Token(PAT)认证的快道和中间软件.

## 特征

-   **准备使用路线**: 预建的认证和管理令牌管理端点
-   **JWT 托肯交换**: OAuth 2.0相容的 PAT 至 JWT 交换符号端点
-   **表达式中件**数字 : `requireJwt`, (中文(简体) ), `requireAdmin`,以及 `requireRole` 用于路由保护的中间软件
-   **JOSE 整合**工业标准JWT签署和核查
-   **类型脚本**: 带有Express请求增强功能的全类型安全
-   **弹性配置**: 自定义路径、符号寿命和密钥管理

## 安装

```bash
npm install @access-tokens/express @access-tokens/core
```

## 快速启动

```typescript
import express from "express";
import { DynamoDBPat } from "@access-tokens/core";
import {
  createAuthRouter,
  createAdminTokensRouter,
  createRequireJwt,
  createRequireAdmin,
  createRequireRole,
  buildSignerVerifier,
  generateKeySet,
} from "@access-tokens/express";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const app = express();
app.use(express.json());

// Initialize DynamoDB
const dynamoClient = new DynamoDBClient({ region: "us-east-1" });
const docClient = DynamoDBDocumentClient.from(dynamoClient);
const pat = new DynamoDBPat({ tableName: "tokens", docClient });

// Generate JWT signing keys
const keySet = await generateKeySet("my-key-id-1");
const signerVerifier = await buildSignerVerifier({
  keySet,
  issuer: "my-app",
  ttl: "1h",
});

// Add authentication and token admin routes
app.use("/auth", createAuthRouter({ pat, signerVerifier }));
app.use("/admin", createAdminTokensRouter({ pat, signerVerifier }));

const requireJwt = createRequireJwt({ signerVerifier });
const requireAdmin = createRequireAdmin();
const requireEditor = createRequireRole({ role: "editor" });

// Your protected routes
app.get("/api/data", requireJwt, (req, res) => {
  res.json({
    message: "User data",
    user: req.user, // { sub, owner, admin, roles }
  });
});

app.get("/api/admin/data", requireJwt, requireAdmin, (req, res) => {
  res.json({
    message: "Admin data",
    user: req.user, // { sub, owner, admin, roles }
  });
});

app.put("/api/content", requireJwt, requireEditor, (req, res) => {
  res.json({
    message: "Content updated",
    user: req.user, // { sub, owner, admin, roles }
  });
});

app.listen(3000, () => console.log("Server running on port 3000"));
```

## API 参考

### 路线

#### `createAuthRouter(options)`

创建带有认证端点的Express路由器.

**选项 :**

```typescript
{
  pat: DynamoDBPat;                    // DynamoDBPat instance
  signerVerifier: JwtSignerVerifier;   // JWT signer/verifier from buildSignerVerifier()
  logger?: pino.Logger;                // Optional logger
}
```

**说明:** JWT 寿命配置于 `buildSignerVerifier()`。 。 。 .

**终点 :**

-   `POST /token` - JWT交换 PAT(OAuth 2.0标志终点)
    
    **请求正文 :**
    
    ```typescript
    {
      grant_type?: "client_credentials";  // Optional, must be "client_credentials" if provided
      client_secret?: string;             // PAT (for OAuth 2.0 client_secret_post method)
      client_id?: string;                 // Optional, accepted but not used
      state?: string;                     // Optional, echoed back in response
    }
    ```
    
    **认证方法** (按此顺序排列):
    
    1.  **主体参数** (第2.0号) `client_secret_post`: 包含 `client_secret` 请求机构
    2.  **基本认证** (第2.0号) `client_secret_basic`编号: 使用 `Authorization: Basic <base64>` 页眉(格式: `Basic base64(":<token>")`(中文(简体) )
    3.  **借记符**: 使用 `Authorization: Bearer <token>` 标题
    
    **回应:**
    
    ```json
    {
      "access_token": "eyJ...", // The signed JWT
      "token_type": "Bearer", // Always "Bearer"
      "expires_in": 3600, // JWT lifetime in seconds
      "state": "..." // Optional, echoed from request
    }
    ```
    

**实例:**

```bash
# Method 1: Body parameter (client_secret_post)
curl -X POST http://localhost:3000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_secret":"pat_abc123..."}'

# Method 2: Basic authentication (client_secret_basic)
curl -X POST http://localhost:3000/auth/token \
  -H "Authorization: Basic $(echo -n ":pat_abc123..." | base64)"

# Method 3: Bearer token (non-OAuth)
curl -X POST http://localhost:3000/auth/token \
  -H "Authorization: Bearer pat_abc123..."
```

#### `createAdminTokensRouter(options)`

创建带有管理令牌管理端点的快递路由器。 需要 JWT 认证和管理员权限 .

**选项 :**

```typescript
{
  pat: DynamoDBPat;                              // DynamoDBPat instance
  signerVerifier: JwtSignerVerifier;             // JWT signer/verifier
  logger?: pino.Logger;                          // Optional logger
}
```

**终点 :**

-   `GET /tokens` - 列表符号
    
    -   **查询参数 :** `afterTokenId`, (中文(简体) ), `limit`, (中文(简体) ), `includeRevoked`, (中文(简体) ), `includeExpired`, (中文(简体) ), `includeSecretPhc`, (中文(简体) ), `hasRole`
    -   **回应:** `{ "records": [...] }`
-   `POST /tokens` - 发个新令牌
    
    -   **请求正文 :** `{ "owner": "user@example.com", "isAdmin"?: false, "roles"?: ["reader"], "tokenId"?: "...", "expiresAt"?: 1234567890 }`
    -   **回应:** `{ "token": "pat_...", "record": {...} }`
-   `PUT /tokens/:tokenId` - 登记预先生成的代号
    
    -   **请求正文 :** `{ "secretPhc": "...", "owner": "...", "isAdmin"?: false, "roles"?: ["reader"], "expiresAt"?: 1234567890 }`
    -   **回应:** `{ "record": {...} }`
-   `PATCH /tokens/:tokenId` - 更新符号
    
    -   **请求正文 :** `{ "owner"?: "...", "isAdmin"?: true, "secretPhc"?: "...", "roles"?: ..., "expiresAt"?: 1234567890 }`
    -   **角色更新语法 :**
        
        ```json
        { "roles": ["role1", "role2"] }     // Replace all roles
        { "roles": { "add": ["admin"] } }   // Atomic add (cannot combine with remove)
        { "roles": { "remove": ["guest"] } } // Atomic remove (cannot combine with add)
        ```
        
    -   **回应:** 204 无内容
-   `PUT /tokens/:tokenId/revoke` - 撤销证书
    
    -   **请求正文 :** `{ "expiresAt"?: 1234567890 }` (可选)
    -   **回应:** 204 无内容
-   `PUT /tokens/:tokenId/restore` - 恢复已撤销的代号
    
    -   **回应:** 204 无内容
-   `POST /tokens/batch` - 批量取回代币
    
    -   **请求正文 :** `{ "tokenIds": ["id1", "id2"], "includeSecretPhc"?: false }`
    -   **回应:** `{ "found": [...], "missing": [...] }`

**说明:** 所有端点都需要JWT认证和管理员权限. 他们 使用情况 `requireJwt` 财务报告和审定财务报表 `requireAdmin` 内部中间软件.

### 中间软件

#### `createRequireJwt(options)`

创建验证 JWT 令牌和插件的中间软件 `req.user`。 。 。 .

**选项 :**

```typescript
{
  signerVerifier: JwtSignerVerifier;   // JWT signer/verifier from buildSignerVerifier()
  logger?: pino.Logger;                // Optional logger
}
```

**请求扩展 :**

```typescript
req.user = {
  sub: string;      // Token ID
  owner: string;    // Token owner
  admin: boolean;   // Admin status
  roles: string[];  // Array of role strings
};
```

**说明:** 这个 `roles` 阵列取自JWT有效载荷并反映了JWT发行时赋予标志的作用.

**用法 :**

```typescript
const requireJwt = createRequireJwt({ signerVerifier });

app.get("/protected", requireJwt, (req, res) => {
  console.log("User:", req.user?.owner);
  res.json({ data: "secret" });
});
```

#### `createRequireAdmin(options?)`

创建需要的中间软件 `req.user.admin` 将会是 `true`。必须在 `requireJwt`。 。 。 .

**选项 :**

```typescript
{
  logger?: pino.Logger;  // Optional logger
}
```

**用法 :**

```typescript
const requireAdmin = createRequireAdmin();

app.delete("/users/:id", requireJwt, requireAdmin, (req, res) => {
  // Only admin users can access this
  res.json({ success: true });
});
```

#### `createRequireRole(options)`

创建需要的中间软件 `req.user.roles` 包括具体的作用。 必须在之后使用 `requireJwt`。 。 。 .

**选项 :**

```typescript
{
  role: string;            // Required role name
  logger?: pino.Logger;    // Optional logger
}
```

**用法 :**

```typescript
const requireEditor = createRequireRole({ role: "editor" });

app.put("/content/:id", requireJwt, requireEditor, (req, res) => {
  // Only users with "editor" role can access this
  res.json({ success: true });
});
```

### JWT 公用事业

#### `generateKeySet(kid: string, algorithm?: "EdDSA" | "RS256")`

为 JWT 签名生成一个新的不对称密钥集.

**参数:**

-   `kid: string` - 密钥ID( 需要) - 此密钥集的独有标识符
-   `algorithm?: "EdDSA" | "RS256"` - 签名算法( 默认: “ EdDSA ”)

**回返情况:**

```typescript
{
  active_kid: string;    // The active key ID
  private_keys: JWK[];   // Array of private keys in JWK format
  public_keys: JWK[];    // Array of public keys in JWK format
}
```

**示例**

```typescript
const keySet = await generateKeySet("my-key-id-1");
// or with specific algorithm
const rsaKeySet = await generateKeySet("rsa-key-1", "RS256");
```

**说明:** 安全存储密钥( 如 AWS 密钥管理器, 环境变量) 。 生成一次再用.

#### `buildSignerVerifier(config)`

从密钥集创建 JWT 签名和验证器.

**配置 :**

```typescript
{
  keySet: KeySet; // From generateKeySet()
  issuer: string; // JWT issuer claim
  ttl: string; // Token time-to-live (e.g., "1h", "30m")
}
```

**回返情况:**

```typescript
JwtSignerVerifier {
  sign: (claims) => Promise<string>;
  verify: (jws: string) => Promise<JWTVerifyResult>;
  jwks: { keys: readonly JWK[] };
}
```

**示例**

```typescript
const keySet = await generateKeySet("my-key-id");
const signerVerifier = await buildSignerVerifier({
  keySet,
  issuer: "my-app",
  ttl: "1h",
});
```

## OAuth 2.0 流量

此库执行一个简化的 OAuth 2. 0 客户端证书流 :

1.  **客户端认证** 将 PAT 改为 `POST /auth/token`
2.  **服务器验证** PAT和发行寿命短的JWT(默认:1小时)
3.  **客户端使用 JWT** 用于通过 `Authorization: Bearer <jwt>`
4.  **服务器验证 JWT** 使用 `requireJwt` 中间软件

### 为什么是JWT交换?

-   **业绩**: 避免对每次请求进行DynamoDB检查并进行尖叫
-   **可缩放性**: 无国籍的JWT核查
-   **短寿**: JWT 受损的风险降低
-   **标准**: OAuth 2.0 兼容

## 安保最佳做法

1.  **使用 HTTPS** - 生产时始终使用TLS
2.  **安全密钥存储** - 将私人钥匙存放在安全金库(AWS保密管理器等)
3.  **短JWT( 短JWT) 终身** - 建议默认1小时
4.  **旋转密钥** - 实施长期服务的关键轮换
5.  **核证发行人/观众** - 在生产中配置这些
6.  **限制费率** - 增加税率限制 `/auth/token` 结束点

## 密钥生成

使用包含的工具生成密钥 :

```bash
pnpm --filter @access-tokens/express genkey
```

或在方案方面:

```typescript
import { generateKeySet } from "@access-tokens/express";

const keys = await generateKeySet("my-key-id-1");
console.log("Public Key:", keys.public_keys);
console.log("Private Key:", keys.private_keys);
```

安全存储这些密钥,并通过环境变量传递给您的应用程序 .

## 处理错误

所有端点返回标准的 HTTP 错误代码 :

-   `400 Bad Request` - 无效的请求正文或参数
-   `401 Unauthorized` - 无效或缺失的符号
-   `403 Forbidden` - 权限不足(不是管理员)
-   `404 Not Found` - 没有找到托肯
-   `500 Internal Server Error` - 服务器出错

示例错误响应 :

```json
{
  "error": "Invalid token",
  "details": "Token has been revoked"
}
```

## 类型脚本

软件包扩展了Express类型 :

```typescript
declare global {
  namespace Express {
    interface Request {
      user?: {
        sub: string; // Token ID
        owner: string; // Token owner
        admin: boolean; // Admin status
        roles: string[]; // Array of role strings
      };
      logger?: Logger; // Optional Pino logger
      clientIp?: string; // Optional client IP (from request-ip)
    }
  }
}
```

## 所需资源

-   节点.js 20+
-   捷运 4.18+或 5.0+
-   @ access-tokens/ core (帮助)

## 相关软件包

-   [@ access-tokens/ core (帮助)](https://www.npmjs.com/package/@access-tokens/core) - 核心符号管理库
-   [@ access-tokens/ 客户端](https://www.npmjs.com/package/@access-tokens/client) - PAT API的HTTP客户端
-   [@ access-tokens/cli (英语)](https://www.npmjs.com/package/@access-tokens/cli) - 命令行符号管理

## 许可证

[公务员制度委员会](https://opensource.org/licenses/ISC) 2025年贷款信贷有限公司.

## 链接

-   [GitHub 仓库](https://github.com/loancrate/access-tokens)
-   [npm 软件包](https://www.npmjs.com/package/@access-tokens/express)
-   [文档](https://github.com/loancrate/access-tokens#readme)

## 常见问题

### @access-tokens/express 是什么？

快捷路线和中间软件,用于个人访问令牌认证

### 如何安装 @access-tokens/express？

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

### @access-tokens/express 支持 TypeScript 吗？

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

### @access-tokens/express 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @access-tokens/express 需要什么版本的 Node\.js？

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

### @access-tokens/express 可以商用吗？

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

### @access-tokens/express 的下载量有多少？

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

### @access-tokens/express 还在维护吗？

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