# @gate-forge/pack-auth 中文文档

规范地址：https://npmcn.com/package/%40gate-forge/pack-auth/

版本：0\.19\.2
npm 元数据更新时间：2026-11-10T03:55:55.538Z
中文译文更新时间：2026-11-16T00:05:48.494Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：85.7 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-09-16T21:52:31.643Z
- 最新版本发布：2026-11-10T03:55:54.972Z
- 近 30 天下载量：1993（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

授权发现包:在TypeScript/JavaScript HTTP线路中AST/heuristic地检测角色守护者、租户范围界定和认证执法;每个被守护端点释放授权资源,并带有角色要求+租赁属性;船舶使用权限o

## 安装

```sh
npm install @gate-forge/pack-auth
```

也可以使用：`pnpm add @gate-forge/pack-auth`、`yarn add @gate-forge/pack-auth`、`bun add @gate-forge/pack-auth`

## README

# `@gate-forge/pack-auth`

授权合同包。 纯 TypeScript 检测器( 无子进程) , 可以发现四个框架和释放的作用守护模式 `auth.resource` 带有角色+租赁属性的条目.

## 检测到的框架

| 框架 | 检测信号 |
| --- | --- |
| 网点JS | `@Controller()` 分类 `@UseGuards(...)` + 键 `@Roles('admin', ...)` + 键 `@Get/Post/Put/Patch/Delete` |
| 快递 | `app.METHOD(path, mw, ...)` 编号 : `router.METHOD(path, mw, ...)` 地点 `mw` 读取 `req.user.role` |
| 快捷化 | `fastify.METHOD(path, { preHandler }, handler)` 谁 `preHandler` 读取 `request.user.role` |
| 浩诺 | `app.METHOD(path, mw, ...)` 地点 `mw` 读取 `c.var.user.role` 或者说 `c.get('user')` |

每个被守护的终点都变成了一个资源:

```
{
  id: "auth.billing.post-refund",
  kind: "auth.resource",
  source: "src/billing.controller.ts",
  location: { file, line, col },
  detectorVersion: "0.1.0",
  attributes: {
    framework: "nestjs" | "express" | "fastify" | "hono",
    path: "/billing/refund",
    httpMethods: ["POST"],
    roleRequirement: ["admin", "finance"],
    tenancy: true | false
  }
}
```

资源 ID 遵循语法 `auth.<area>.<verb>-<endpoint>`;区域是第一个路径段,动词是小写HTTP方法.

## 合同义务词汇

定义 `src/obligations.ts` 和再出口为 `AUTH_OBLIGATION_CONTRACTS`义务编号 `<resourceId>:<contract>` 按引擎的id语法.

| 合同 | 含义 |
| --- | --- |
| `auth:role-allowed` | 负责 `roleRequirement` 收到2xx回复 |
| `auth:role-denied` | 没有匹配角色的呼叫者获得401/403 |
| `auth:tenant-isolated` | 具有正确角色但错误租户的打电话者可领取403(何时) `tenancy: true`(中文(简体) ) |
| `auth:denied-no-side-effect` | 被拒绝的请求不会改变资源( 后拒绝显示行不变/ 丢失) |
| `auth:forged-token-rejected` | 伪造 JWT( 错误签名、 过期、 错误、 缺失) 返回 401 |

## 调查结果

| 代码 | 含义 |
| --- | --- |
| `AMBIGUOUS_GUARD` | A 类 `@Roles()` 装饰者使用非文体参数(例如. `@Roles(...ALLOWED)`(中文(简体) ) |
| `DUPLICATE_RESOURCE_ID` | 两个声明产生相同的结果 `auth.<area>.<verb>-<endpoint>` 编号 |
| `PARSE_ERROR` | 无法读取扫描文件 |

## 实体适配器方案a

货船 `src/adapter-schema.ts` 页:1 `@gate-forge/pack-sqlalchemy`适配器合同),所以收费资源可以被目击到只有GET-. 实例 Auth 服务器发送 `x-gateforge-env: example-auth-v1` 每个响应;适配器 `environmentFingerprint` 必须等同于这一价值.

```js
// .gateforge/adapters/auth.billing.refund.mjs
export default {
  resourceId: 'auth.billing.refund',
  read: async (ctx, id) => fetch(`${ctx.baseUrl}/billing/refund/${id}`, { headers: ctx.headers ?? {} }),
  normalize: (body) => ({ entityId: body.id, fields: { id: body.id, status: body.status, tenant_id: body.tenant_id } }),
  deletion: 'archive',
  environmentFingerprint: 'example-auth-v1',
};
```

## 示例服务器

`example/auth/server.js` ——零依赖节点:http服务器于端口 `3001`数字 :

-   `POST /billing/refund` 由角色监管`admin`和房客的配对; 创建一行内在的一行.
-   `GET /billing/refund/:id` 返回行(缺行为404;交叉租户为403).
-   所有答复均附有 `x-gateforge-env: example-auth-v1`。 。 。 .

运行它:

```
node example/auth/server.js
# → gateforge auth example server listening on http://127.0.0.1:3001
```

## 测试

```
cd packages/pack-auth
npx tsc --noEmit   # typecheck
npx vitest run     # unit + e2e
```

E2e套接字套接字在OS指定的自由端口上为服务器提供靴子,执行所有5个义务合同,并包括两个对抗测试:

1.  `fake-green: role-denied with 200` ——vitest必须拒绝(服务器返回403).
2.  `fake-green: no-side-effect without post-deny GET` ——正格套件中的伴奏断言证明需要GET探测器.

## 用作 CLI 插件

```yaml
# .gateforge.yml
plugins:
  - id: gateforge.pack-auth
    version: 0.1.0
    transport: in-process
    module: '@gate-forge/pack-auth'
```

## 限制

-   Python出处超出范围(每个简报只限TS).
-   动态角色集(例如. `@Roles(...ALLOWED)`表面为 `AMBIGUOUS_GUARD` 永远不要成为资源;用户必须将其提升到文字上.
-   Regex 检测器不运行 TS 编译器;框架特定语法必须精确匹配所记录的信号(解码器顺序,选项块形状等).

## 常见问题

### @gate-forge/pack-auth 是什么？

授权发现包:在TypeScript/JavaScript HTTP线路中AST/heuristic地检测角色守护者、租户范围界定和认证执法;每个被守护端点释放授权资源,并带有角色要求\+租赁属性;船舶使用权限o

### 如何安装 @gate-forge/pack-auth？

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

### @gate-forge/pack-auth 支持 TypeScript 吗？

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

### @gate-forge/pack-auth 支持 ESM 还是 CommonJS？

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

### @gate-forge/pack-auth 需要什么版本的 Node\.js？

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

### @gate-forge/pack-auth 可以商用吗？

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

### @gate-forge/pack-auth 的下载量有多少？

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

### @gate-forge/pack-auth 还在维护吗？

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

