@gate-forge/pack-auth

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

Authorization discovery pack: AST/heuristic detection of role guards, tenant scoping, and authentication enforcement in TypeScript/JavaScript HTTP routes; emits auth resource per guarded endpoint with roleRequirement + tenancy attributes; ships the auth o

原始使用文档
文档目录8 节
  1. Detected frameworks
  2. Obligation contract vocabulary
  3. Findings
  4. Entity adapter schema
  5. Example server
  6. Tests
  7. Use as a CLI plugin
  8. Limitations

@gate-forge/pack-auth

Authorization contract pack. Pure TypeScript detector (no subprocess) that discovers role-guard patterns across four frameworks and emits auth.resource entries with role + tenancy attributes.

Detected frameworks

FrameworkDetection signal
NestJS@Controller() class with @UseGuards(...) + @Roles('admin', ...) + @Get/Post/Put/Patch/Delete
Expressapp.METHOD(path, mw, ...) / router.METHOD(path, mw, ...) where mw reads req.user.role
Fastifyfastify.METHOD(path, { preHandler }, handler) whose preHandler reads request.user.role
Honoapp.METHOD(path, mw, ...) where mw reads c.var.user.role or c.get('user')

Each guarded endpoint becomes one resource:

{
  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
  }
}

Resource ids follow the grammar auth.<area>.<verb>-<endpoint>; the area is the first path segment, the verb is the lowercased HTTP method.

Obligation contract vocabulary

Defined in src/obligations.ts and re-exported as AUTH_OBLIGATION_CONTRACTS. Obligation ids are <resourceId>:<contract> per the engine's id grammar.

ContractMeaning
auth:role-allowedCaller with a role in roleRequirement receives a 2xx response
auth:role-deniedCaller without a matching role receives 401/403
auth:tenant-isolatedCaller with the right role but wrong tenant receives 403 (when tenancy: true)
auth:denied-no-side-effectDenied requests do not mutate the resource (post-deny GET shows the row unchanged/missing)
auth:forged-token-rejectedForged JWT (bad signature, expired, malformed, missing) returns 401

Findings

CodeMeaning
AMBIGUOUS_GUARDA @Roles() decorator uses non-literal arguments (e.g. @Roles(...ALLOWED))
DUPLICATE_RESOURCE_IDTwo declarations produce the same auth.<area>.<verb>-<endpoint> id
PARSE_ERRORFile could not be read for scanning

Entity adapter schema

The pack ships src/adapter-schema.ts (mirror of @gate-forge/pack-sqlalchemy's adapter contract) so billing resources can be witnessed GET-only. The example auth server emits x-gateforge-env: example-auth-v1 on every response; the adapter's environmentFingerprint must equal that value.

// .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 server

example/auth/server.js — zero-dependency node:http server on port 3001:

  • POST /billing/refund guarded by role (admin) AND tenant match; creates an in-memory row.
  • GET /billing/refund/:id returns the row (404 if absent; 403 cross-tenant).
  • All responses carry x-gateforge-env: example-auth-v1.

Run it:

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

Tests

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

The e2e suite boots the server on an OS-assigned free port, exercises all five obligation contracts, and includes two adversarial tests:

  1. fake-green: role-denied with 200 — vitest must reject (server returns 403).
  2. fake-green: no-side-effect without post-deny GET — companion assertion in the positive suite proves the GET probe is required.

Use as a CLI plugin

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

Limitations

  • Python sources are out of scope (TS-only per brief).
  • Dynamic role sets (e.g. @Roles(...ALLOWED)) surface as AMBIGUOUS_GUARD and never become resources; users must lift them to literals.
  • The regex detector does not run a TS compiler; framework-specific syntax must match the documented signal exactly (decorator order, option-block shape, etc.).

版本与发布记录

@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 是什么?

Authorization discovery pack: AST/heuristic detection of role guards, tenant scoping, and authentication enforcement in TypeScript/JavaScript HTTP routes; emits auth resource per guarded endpoint with roleRequirement + tenancy attributes; ships the auth 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 和提交记录判断。