# @gentleduck/iam 中文文档

规范地址：https://npmcn.com/package/%40gentleduck/iam/

版本：5\.13\.0
npm 元数据更新时间：2026-10-27T14:41:17.206Z
中文译文更新时间：2026-11-16T04:04:04.802Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gentleduck/iam
原文对照：https://npmcn.com/package/%40gentleduck/iam/?lang=original
项目主页：https://gentleduck.org/duck-iam
源码仓库：https://github.com/gentleeduck/duck-iam

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

- 包体积（解压后）：3.9 MB，219 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- peer 依赖：react ^19\.2\.6，drizzle-orm \>=0\.30\.0，lucide-react \>=0\.400\.0，@gentleduck/libs \>=0\.2\.0，@gentleduck/registry-ui \>=0\.5\.0
- 首次发布：2026-03-12T02:49:06.240Z
- 最新版本发布：2026-10-27T14:41:16.732Z
- 近 30 天下载量：3693（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

现代ABAC/RBAC访问控制引擎. 框架-不可知核与集成为Express,NestJS,Hono,Next.js,React,和Vue.

## 安装

```sh
npm install @gentleduck/iam
```

也可以使用：`pnpm add @gentleduck/iam`、`yarn add @gentleduck/iam`、`bun add @gentleduck/iam`

## README

![@gentleduck/iam](https://npmcn.com/package/%40gentleduck/iam/public/logo-dark.svg)

# @ gentleduck/ iam (英语)

现代ABAC/RBAC访问控制引擎. 框架-不可知核与集成为Express,NestJS,Hono,Next.js,React,和Vue.

[麻省理工学院](https://npmcn.com/package/%40gentleduck/iam/LICENSE) - 说吧 [更改日志](https://npmcn.com/package/%40gentleduck/iam/CHANGELOG.md) - 说吧 [警卫](https://npmcn.com/package/%40gentleduck/iam/SECURITY.md) - 说吧 [文档](https://gentleduck.org/duck-iam)

[![npm](https://img.shields.io/npm/v/@gentleduck/iam.svg)](https://www.npmjs.com/package/@gentleduck/iam) [![downloads](https://img.shields.io/npm/dm/@gentleduck/iam.svg)](https://www.npmjs.com/package/@gentleduck/iam) [![MIT](https://img.shields.io/npm/l/@gentleduck/iam.svg)](https://npmcn.com/package/%40gentleduck/iam/LICENSE)

* * *

TypeScript的型号安全授权引擎. RBAC + ABAC 具有政策引擎,条件评价,范围化作用,以及特快,雀巢JS,Hono,Next.js,React,Vue,和香草JS的集成.

一次运行中的依赖性(`uuid`只有Drizzle计划帮手才进来 树能震动 - 看 [模块大小](https://npmcn.com/package/%40gentleduck/iam/#readme-module-sizes-gzipped) 下面是每个单元的实际数字.

## 安装

```bash
npm install @gentleduck/iam
# or
bun add @gentleduck/iam
```

## 快开始

```typescript
import { createIam } from '@gentleduck/iam/core'
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'

const access = createIam({
  actions: ['create', 'read', 'update', 'delete'] as const,
  resources: ['post', 'comment', 'user'] as const,
  roles: ['viewer', 'editor', 'admin'] as const,
})

const viewer = access.defineRole('viewer').grant('read', 'post').grant('read', 'comment').build()
const editor = access.defineRole('editor').inherits('viewer').grant('update', 'post').build()
const admin = access.defineRole('admin').inherits('editor').grantCRUD('post').grantCRUD('comment').build()

const policy = access
  .definePolicy('blog')
  .rule('owner-edit', (r) => r.allow().on('update').of('post').when((w) => w.isOwner()))
  .build()

const adapter = new IamMemoryAdapter({
  policies: [policy],
  roles: [viewer, editor, admin],
  assignments: { 'user-1': ['editor'] },
})

const engine = access.createEngine({ adapter })
const allowed = await engine.can('user-1', 'read', { type: 'post', attributes: {} })
// true
```

## 业绩

以其他5个联署材料授权图书馆为基准,使用vitest板凳 (单位:千美元)`bun run bench`) (中文(简体) ). 本节中的每个数字均以下列数值计量: **5.6.0 (简体中文)** 一个 机器在一次运行中,此后没有重新计量;将其读作比率 而不是当下读取您的硬件。 重新运行 `bun run bench` 在引用其中任何一个之前。 两种不同的东西被测量 - 保持它们 分开.

**只有规则匹配** (没有适配器,没有引擎包装), ops/sec:

| 图书馆 | 行动/秒 | 对CASL |
| --- | --- | --- |
| @ casl/ 可读性 | ~17.0M (单位:千美元) | 基线 |
| 轻而易举 | ~ 5.0M (单位:千米) | 3.4x 较慢 |
| @rbac/rbac (英语) | 约3.3M | 5.2x 慢点 |
| **@ gentleduck/ iam (英语)** `iamEvaluateFast()` | ~7.6M) 坐标: | 2.2x 慢点 |
| 访问控制 | ~1.3M (单位:千美元) | 12.8x 较慢 |
| 凸轮 | ~ 208K 键 | 82x 慢点 |

**`engine.can()`** - 真正的入口,完整的堆放(适应器+钩子+) 专题分辨率+汇编的表格:

| 模式 | 行动/秒 | 对CASL |
| --- | --- | --- |
| `mode: 'production'` (编译表 | ~1.15亿 | ~14x 慢点 |
| @casl/可读性(可预建, `.can()`(中文(简体) ) | ~17.0M (单位:千美元) | 基线 |

`mode: 'development'` 运行同一汇总的判决书表格,并 _(单位:千美元)_ 运行口译,以恢复 `reason`编号 :`policy`编号 :`rule` 来源 表格在编译时擦去,并申明两者一致。 这大概要花很多钱 2.4x在同一台机上生产. 这就是目的:发展就是发展 表格/解释的分歧应浮出水面,生产是 第二评价员将纯粹是间接费用.

CASL是一个更窄的工具:一个平整的规则集,完全同步,没有持久性 层. `engine.can()` 还运行一个政策引擎( 4个结合算法) 区域局角色继承、适配器/缓冲/ 残废层 和生命周期钩 - 这是 `async`。这一差距是: 地面的成本,而不是低效率的追逐.

实际不是瓶颈:~1.15M操作/秒为~0.87μs每检查一次 在一个核心上 - 网络, DB, 及其周围的串行化成本超过 在任何真实的要求中,检查本身。 吞吐量不会下降 目录大小 ; 编译表为 O(1) 索引查询 不论存在多少角色或政策。 到底发生了什么 约束大小为目录 _形状_ - 角色数,非常广 动作 x 资源网格, 以及深层层资源类型 不是原始请求吞吐量。 过去32个角色的32位赠与面罩不能 所以引擎会发出一次警告,然后回到 翻译:仍然正确,不再使用O(1).

对于最小的捆绑,仅导入您通过子路径使用的东西:

```typescript
// Engine-only (skip adapters, server middleware, client wrappers)
import { IamEngine, iamEvaluatePolicyFast } from '@gentleduck/iam/core'

// Each adapter, server adapter, and client wrapper is a separate entry
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { iamAdminRouter } from '@gentleduck/iam/server/express'
import { createIamAccessControl } from '@gentleduck/iam/client/react'

// Validator (12 KB) - lazy-loaded by engine.admin.savePolicy on first
// call, or imported directly for standalone validation tooling
import { validatePolicy } from '@gentleduck/iam/core/validate'

// Fluent builder (9 KB) - config-time only, separate subpath
import { definePolicy, defineRole } from '@gentleduck/iam/core/builder'
```

`import * from '@gentleduck/iam'` 拉起所有管子(~41 KB) g. 使用子路径导入 + 抖出树来的实际部署 在15-25 KB时.

## 特征

-   **非洲区域局+非洲区域局** 在一个引擎中合并
-   **政策引擎** 包含4个政策内部算法(默认覆盖、允许覆盖、第一匹配、最高优先级)和3个交叉政策组合模式(和/允许覆盖/第一适用)
-   **19个条件操作员** (eq, neq, gt, lt, in, 包含, 起始 with, 匹配, 存在, 子集 of, before, between, gt, and more)
-   **范围化的作用** 多租户系统
-   **开发/程序模式**数字 : `check()` 返回一个 `IDecision` (一) 在发展中,在生产中; `can()` 返回两者中的布尔值
-   **解释 API**: 完整的评价追踪,确切显示批准或拒绝批准的原因
-   **生命周期钩**数字 : `beforeEvaluate`, (中文(简体) ), `afterEvaluate`, (中文(简体) ), `onDeny`, (中文(简体) ), `onError`, (中文(简体) ), `onPolicyError`, (中文(简体) ), `onMetrics`
-   **类型安全配置**:在编译时验证行动、资源、作用和范围

### SRE 原始人类

-   **`engine.preload()`** - 在靴子上取暖; `{ validator: true }` 也验证每个存储行
-   **`engine.healthCheck()`** - 说吧 `/healthz`\- 已准备好的探测器,适配器耐用性+缓存命中率
-   **`engine.stats.get()` 编号 : `engine.stats.reset()`** - 缓存击中/ 漏掉每个缓存的计数器
-   **`engine.cache.invalidate()` 编号 : `invalidatePolicies()` 编号 : `invalidateRoles(id?)` 编号 : `invalidateSubject(id)`** - 有目标的缓存冲
-   **`engine.admin.export()` 编号 : `import(snapshot, { mode })`** - 计划化政策+促进环境的作用简介
-   **`engine.dispose()`** - 关闭时解除交叉无效订阅
-   **`IConfig.adapterTimeoutMs`** - 说吧 `AbortController`\- 每一次适配器呼叫、决定路径和 `engine.admin` 相同(违约5 s)
-   **`IConfig.hookTimeoutMs`** - 在承诺下捆绑回钩(默认5 s; `0` 无限期等待)
-   **`IConfig.maxPolicies` 编号 : `maxRoles`** - 关闭的负载时封盖
-   **`IConfig.allowFailOpen`** - 何时要求明确选择加入 `defaultEffect` 实值 `'allow'`,在每个模式下
-   **`IConfig.invalidator`** - 跨事件缓存验证广播机
-   **`createIamRedisInvalidator`** 时间 `@gentleduck/iam/invalidators/redis` - 酒吧/子助手,自带过滤器
-   **`iamCreateMetricsAggregator`** 时间 `@gentleduck/iam/observability/metrics` - 第50页/第95页/第99页 `onMetrics` 事件
-   **HttpAdapter 重试 + 按请求超时 + 断路器** (退后、退后、门槛、冷却)
-   **需求 `authorize` 回调** 在每个管理员路由器上( Express, Hono, Next, Nest)

## 一体化

### 服务器中间软件

```typescript
// Express
import { iamGuard, iamAdminRouter } from '@gentleduck/iam/server/express'
app.delete('/posts/:id', iamGuard(engine, 'delete', 'post'), handler)
app.use('/admin', iamAdminRouter(engine, { authorize: (req) => isAdmin(req) })(() => express.Router()))

// Hono
import { iamGuard, iamBindAdminRouter } from '@gentleduck/iam/server/hono'
app.delete('/posts/:id', iamGuard(engine, 'delete', 'post'), handler)
iamBindAdminRouter(adminApp, engine, { authorize: (c) => isAdmin(c) })

// NestJS
import { iamNestAccessGuard, IamAuthorize, createIamAdminOperations } from '@gentleduck/iam/server/nest'
@IamAuthorize({ action: 'delete', resource: 'post' })

// Next.js
import { withIamAccess, createIamAdminHandlers } from '@gentleduck/iam/server/next'
export const DELETE = withIamAccess(engine, 'delete', 'post', handler, {
  getUserId: async () => (await auth()).userId, // required - headers are spoofable
})
```

### 客户端库

```typescript
// React
import { createIamAccessControl } from '@gentleduck/iam/client/react'
const { AccessProvider, useAccess, Can, Cannot } = createIamAccessControl(React)

// Vue
import { createIamVueAccess } from '@gentleduck/iam/client/vue'
const { useAccess, Can, Cannot } = createIamVueAccess(vue)

// Vanilla JS
import { IamAccessClient } from '@gentleduck/iam/client/vanilla'
const client = await IamAccessClient.fromServer('/api/permissions')
client.can('read', 'post') // boolean
```

### 数据库适配器

```typescript
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { IamFileAdapter } from '@gentleduck/iam/adapters/file'
import { IamPrismaAdapter } from '@gentleduck/iam/adapters/prisma'
import { IamDrizzleAdapter } from '@gentleduck/iam/adapters/drizzle'
import { IamRedisAdapter } from '@gentleduck/iam/adapters/redis'
import { IamHttpAdapter } from '@gentleduck/iam/adapters/http'
```

### 交易

写作和阅读可以运行在您拥有的交易上. `withTransaction(tx)` 返回视图 与您的交易控件绑定的引擎; 控件对 duck-iam 是不透明的, 并交接 直接回到你的适配器.

```typescript
let pending
await db.transaction(async (tx) => {
  const perms = engine.withTransaction(tx)
  await perms.admin.assignRole(userId, 'admin', orgId)
  await tx.insert(members).values({ userId, orgId })
  pending = perms.pending
})
await pending.flush()   // invalidate and broadcast only after the commit
```

写字经过 `.admin`,与 `engine.admin`因此,有一个写 表面而不是两个.

在绑定视图上读取与交易本地缓存对齐运行,所以它们可以看到交易的 拥有未承付的赠款; 共享引擎不断从其温暖的缓存中解答 交易从不污染。 一个空的本地缓存总是漏入绑定适配器, 使交易中的复写正确.

**缓存无效不会在交易中开火** - 包括 `config.invalidator` 舰队广播。 他们缓冲 `pending`,去重复,并开火 `flush()`A级 因此,回滚赠款从不驱逐另一个节点的缓存,因为一个没有的字 发生. `pending.discard()` 将缓冲器降为明确的回滚路径.

`withTransaction` 需要一个执行的适配器 `withClient`细雨和棱镜 适配器这样做; 内存、 文件、 redis 和 http 不 - 他们没有交易可加入 - & `withTransaction` 而不是默默地离开你的书写.

### 批次写

`assignRoles`, (中文(简体) ), `revokeRoles` 财务报告和审定财务报表 `moveRoleScopes` 列表并逐行报告结果. (单位:千美元)`invalidateSubjects` 也需要列表,但它是一个缓存滴,而不是一个写入 返回时 `void`. ) (中文(简体) )

```typescript
const result = await engine.admin.assignRoles([
  { subjectId: 'u1', roleId: 'admin' },
  { subjectId: 'u2', roleId: 'editor', scope: 'org-1' },
])
result.applied   // 2
result.outcomes  // one entry per input row, in input order
```

每行在写出之前都会被验证,所以一个错误的行会中止批次 半应用。 每个受影响的主体一次被宣布无效,尽管有许多行将其命名. 细雨适配器会把写作崩溃成一个 `INSERT` 和一个 `DELETE` - 那个 `DELETE` 需求 `or` 在适配器中 `ops`,并逐行取消没有它。 无适配器 基于设置的形式循环,因此每个适配器都支持每个批量的形式.

每个结果都带有它回答的一行, 所以没有什么可以分析一个ID回一个三, 和两行结构相同的条目分开:

```typescript
const result = await engine.admin.assignRoles(rows)
result.outcomes.map((o) => o.row) // the rows you passed in, same objects, same order
```

两个角色都是一流的 所以每一行都是 `ok`: 已授予一个主题角色 持有是成功,而不是错过, 完全像一行 `assignRole` 治疗之. `changed` 带更细的回答:

```typescript
const again = await engine.admin.assignRoles([{ subjectId: 'u1', roleId: 'admin' }])
again.applied // 1 - the grant is in place

// `ok` is always `true`: a malformed row aborts the whole batch before any write, so
// there is no failed-row arm to narrow on. Read `value` directly.
const [outcome] = again.outcomes
outcome?.value.changed // false - this call is not what put it there
```

| `changed` | 含义 |
| --- | --- |
| `true` | 此行用于写入所作的声明 |
| `false` | ,该行已经处于请求状态,或者该批次中较早的一行已经用于此写入 |
| 缺席 | 适配器不能说,也没有猜到 |

它没有出现在 MySQL上,因为它没有 `RETURNING`,并且在每个适配器上循环 单行法,返回 `void`也不付额外阅读费.

每次写作都记在一行的账上 也就是第一行 名单 同一三次报告 `true` 接下来 `false` 而不是两行都要求写 一次创建数据库并撤销 `{u1, admin}` 并行 `{u1, admin, scope: 'org-1'}` 贷方 通配符行,它已经覆盖了更窄的一行。 两者均被驳回 老实回答.

### 可操作性

```typescript
import { createIamRedisInvalidator } from '@gentleduck/iam/invalidators/redis'
import { iamCreateMetricsAggregator } from '@gentleduck/iam/observability/metrics'

const metrics = iamCreateMetricsAggregator()
const engine = new IamEngine({
  adapter,
  invalidator: createIamRedisInvalidator({ client: redis }),
  hooks: { onMetrics: metrics.record },
})

await engine.preload()
app.get('/healthz', async (_, res) => res.json(await engine.healthCheck()))
app.get('/metrics', (_, res) => res.json(metrics.snapshot()))
```

无效者 `client` 需要两个 Redis 连接, 而不是一个 - 订阅 连接不能发布其他命令 - 并使用 `secret` 用于HMAC-SHA256 信封签名,应当设置在生产中.

见 [生产部署指南](https://gentleduck.org/duck-iam/duck-iam/guides/production) 用于缓存 TTL 权衡,多节点无效模式,故障关闭默认,以及 SLO 目标.

## 模块大小( gzipped)

按5.6.0计算,与上述业绩数字相同.

| 模块 | 大小 |
| --- | --- |
| 核心引擎(典型的导入) | ~ 15 KB 键 |
| `core/validate` (只管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管管 | 12个KB |
| `core/builder` (仅限配置时间) | 9个KB |
| `core/explain` (dev-mode 跟踪) | 单独块 |
| 每个适配器 | 1.7 - 6 KB (韩语) |
| 每个服务器中间软件 | 2.4 - 3.7 KB (韩语) |
| 每个客户端库 | 1.2 - 2.0 KB (韩语) |

基准中的"完整"捆绑头条(~41 KB)是最糟糕的 "进口一切"的号码 什么 `import * from '@gentleduck/iam'` 会拉出。 现实部署最终达到15-25KB,因为适配器, 服务器中间软件,客户端位于子路径导入和 校验器仅在管理员写入路径运行时才懒惰地装入 。 见 [基准页](https://gentleduck.org/duck-iam/duck-iam/benchmarks) 用于每个标注的测量.

## 文档

-   **引用( 从这里开始) : [`docs/reference/`](https://npmcn.com/package/%40gentleduck/iam/docs/reference/README.md)** - 11页 以子系统覆盖包子系统,对源写入. 发动机及其 配置、操作员表、角色和范围、验证、构建者和痕迹 适配器,四个服务器集成,客户端,devtools,以及操作.
-   站点 : [(原始内容存档于2012-10-10). sweetduck.org/duck-iam](https://gentleduck.org/duck-iam)
-   所编译的引擎内部(圆卡桶,角色比特马斯克,所编译的表格,并有图表): [`docs/compiled-engine-explained.md`](https://npmcn.com/package/%40gentleduck/iam/docs/compiled-engine-explained.md)
-   引擎重写设计历史 + 已知限制 : [`docs/engine-rewrite.md`](https://npmcn.com/package/%40gentleduck/iam/docs/engine-rewrite.md)
-   开发工具:导入 `@gentleduck/iam/dt` 检查应用程序内的政策评价
-   兄弟姐妹重现 : [`@gentleduck/auth`](https://www.npmjs.com/package/@gentleduck/auth), (中文(简体) ), [`@gentleduck/ui`](https://github.com/gentleeduck/duck-ui), (中文(简体) ), [`@gentleduck/upload`](https://github.com/gentleeduck/duck-upload), (中文(简体) ), [`@gentleduck/md`](https://github.com/gentleeduck/duck-md)

## 捐款

Repo 中的 PR 核对表 + 样式注释 [`CONTRIBUTING.md`](https://github.com/gentleeduck/duck-iam/blob/main/CONTRIBUTING.md)。 。 。 . 安全披露: [`SECURITY.md`](https://npmcn.com/package/%40gentleduck/iam/SECURITY.md)。 。 。 .

## 许可证

麻省理工学院. 见 [`LICENSE`](https://npmcn.com/package/%40gentleduck/iam/LICENSE)。 。 。 .

## 常见问题

### @gentleduck/iam 是什么？

现代ABAC/RBAC访问控制引擎\. 框架-不可知核与集成为Express,NestJS,Hono,Next\.js,React,和Vue\.

### 如何安装 @gentleduck/iam？

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

### @gentleduck/iam 支持 TypeScript 吗？

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

### @gentleduck/iam 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gentleduck/iam 需要什么版本的 Node\.js？

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

### @gentleduck/iam 可以商用吗？

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

### @gentleduck/iam 的下载量有多少？

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

### @gentleduck/iam 还在维护吗？

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

