@gate-forge/pack-auth

中文文档
0.19.2发布于 2026/11/10Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 1993

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

中文使用文档
文档目录8 节
  1. 检测到的框架
  2. 合同义务词汇
  3. 调查结果
  4. 实体适配器方案a
  5. 示例服务器
  6. 测试
  7. 用作 CLI 插件
  8. 限制

@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_GUARDA 类 @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 必须等同于这一价值.

// .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 插件

# .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 共发布 46 个版本,首次发布于 2026/09/17;过去 12 个月发布了 46 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.2latest2026/11/105 天前
0.19.12026/11/106 天前
0.19.02026/10/2917 天前
0.18.32026/10/2522 天前
0.18.22026/10/2125 天前
0.18.12026/10/2125 天前

关于 @gate-forge/pack-auth 的常见问题

@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 和提交记录判断。