@gentleduck/iam

中文文档
5.13.0发布于 2026/10/27MITTypeScriptESM + CJS近 30 天下载 3693

Modern ABAC/RBAC access control engine. Framework-agnostic core with integrations for Express, NestJS, Hono, Next.js, React, and Vue.

原始使用文档
文档目录16 节
  1. Install
  2. Quick start
  3. Performance
  4. Features
  5. SRE primitives
  6. Integrations
  7. Server middleware
  8. Client libraries
  9. Database adapters
  10. Transactions
  11. Batch writes
  12. Operability
  13. Module sizes (gzipped)
  14. Docs
  15. Contributing
  16. License

@gentleduck/iam

@gentleduck/iam

Modern ABAC/RBAC access control engine. Framework-agnostic core with integrations for Express, NestJS, Hono, Next.js, React, and Vue.

MIT - Changelog - Security - Docs

npm downloads MIT


Type-safe authorization engine for TypeScript. RBAC + ABAC with a policy engine, condition evaluation, scoped roles, and integrations for Express, NestJS, Hono, Next.js, React, Vue, and vanilla JS.

One runtime dependency (uuid, pulled in only by the Drizzle schema helpers). Tree-shakeable - see Module sizes below for real per-module numbers.

Install

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

Quick start

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

Performance

Benchmarked against 5 other JS authorization libraries using vitest bench (bun run bench). Every number in this section was measured at 5.6.0 on one machine in a single run and has not been re-measured since; read them as ratios from that run, not as a current reading of your hardware. Re-run bun run bench before quoting any of them. Two different things get measured - keep them separate.

Rule-matching only (no adapter, no engine wrapper), ops/sec:

Libraryops/secvs CASL
@casl/ability~17.0Mbaseline
easy-rbac~5.0M3.4x slower
@rbac/rbac~3.3M5.2x slower
@gentleduck/iam iamEvaluateFast()~7.6M2.2x slower
accesscontrol~1.3M12.8x slower
casbin~208K82x slower

engine.can() - the real entry point, full stack (adapter + hooks + subject resolution + the compiled table):

Modeops/secvs CASL
mode: 'production' (compiled table)~1.15M~14x slower
@casl/ability (ability pre-built, .can())~17.0Mbaseline

mode: 'development' runs the same compiled table for the verdict and also runs the interpreter, to recover the reason/policy/rule provenance the table erases at compile time and to assert the two agree. That costs roughly 2.4x production on the same machine. That is the intent: development is where a table/interpreter disagreement should surface, and production is where the second evaluator would be pure overhead.

CASL is a narrower tool: one flat rule set, fully sync, no persistence layer. engine.can() also runs a policy engine (4 combining algorithms across N named policies), RBAC role inheritance, an adapter/cache/ invalidation layer, and lifecycle hooks - and it's async. That gap is the cost of that surface, not inefficiency to chase down.

In practice it isn't the bottleneck: ~1.15M ops/sec is ~0.87µs per check on one core - network, DB, and serialization around it cost more than the check itself in any real request. Throughput doesn't degrade with catalog size either; the compiled table is an O(1) index lookup regardless of how many roles or policies exist. What actually constrains scale is catalog shape - role count, very wide action x resource grids, and deeply nested hierarchical resource types - not raw request throughput. Past 32 roles the 32-bit grant mask can no longer address them all, so the engine warns once and falls back to the interpreter: still correct, no longer O(1).

For the smallest bundle, import only what you use via subpaths:

// 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' pulls the everything-barrel (~41 KB gzipped). Real deployments using subpath imports + tree-shaking come in at 15-25 KB.

Features

  • RBAC + ABAC combined in one engine
  • Policy engine with 4 intra-policy algorithms (deny-overrides, allow-overrides, first-match, highest-priority) and 3 cross-policy combine modes (and / allow-overrides / first-applicable)
  • 19 condition operators (eq, neq, gt, lt, in, contains, starts_with, matches, exists, subset_of, before, after, and more)
  • Scoped roles for multi-tenant systems
  • Dev/prod mode: check() returns an IDecision in development and a bare boolean in production; can() returns a boolean in both
  • Explain API: full evaluation trace showing exactly why a permission was granted or denied
  • Lifecycle hooks: beforeEvaluate, afterEvaluate, onDeny, onError, onPolicyError, onMetrics
  • Type-safe config: actions, resources, roles, and scopes are validated at compile time

SRE primitives

  • engine.preload() - warm cache at boot; { validator: true } also validates every stored row
  • engine.healthCheck() - /healthz-ready probe with adapter latency + cache hit rate
  • engine.stats.get() / engine.stats.reset() - cache hit / miss counters per cache
  • engine.cache.invalidate() / invalidatePolicies() / invalidateRoles(id?) / invalidateSubject(id) - targeted cache flushes
  • engine.admin.export() / import(snapshot, { mode }) - schema-versioned policy + role snapshots for env promotion
  • engine.dispose() - release the cross-instance invalidator subscription on shutdown
  • IConfig.adapterTimeoutMs - AbortController-driven timeout on every adapter call, decision path and engine.admin alike (default 5 s)
  • IConfig.hookTimeoutMs - bound on a promise a hook returns (default 5 s; 0 waits indefinitely)
  • IConfig.maxPolicies / maxRoles - load-time caps that fail closed
  • IConfig.allowFailOpen - explicit opt-in required whenever defaultEffect is 'allow', in every mode
  • IConfig.invalidator - cross-instance cache-invalidation broadcaster
  • createIamRedisInvalidator at @gentleduck/iam/invalidators/redis - pub/sub helper with self-echo filter
  • iamCreateMetricsAggregator at @gentleduck/iam/observability/metrics - p50 / p95 / p99 over onMetrics events
  • HttpAdapter retry + per-request timeout + circuit breaker (retries, backoff, threshold, cooldown)
  • Required authorize callback on every admin router (Express, Hono, Next, Nest)

Integrations

Server middleware

// 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
})

Client libraries

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

Database adapters

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'

Transactions

Writes and reads can run on a transaction you own. withTransaction(tx) returns a view of the engine bound to your transaction handle; the handle is opaque to duck-iam and is handed straight back to your adapter.

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

Writes go through .admin, the same interface as engine.admin, so there is one write surface rather than two.

Reads on the bound view run against transaction-local caches, so they see the transaction's own uncommitted grants; the shared engine keeps answering from its warm caches, which the transaction never pollutes. An empty local cache always misses through to the bound adapter, which is what makes a read-after-write inside the transaction correct.

Cache invalidations do not fire inside a transaction - including the config.invalidator fleet broadcast. They buffer in pending, de-duplicated, and fire on flush(). A rolled-back grant therefore never evicts another node's cache for a write that did not happen. pending.discard() drops the buffer for an explicit rollback path.

withTransaction needs an adapter that implements withClient. The drizzle and prisma adapters do; memory, file, redis and http do not - they have no transaction to join - and withTransaction throws rather than silently leaving writes outside yours.

Batch writes

assignRoles, revokeRoles and moveRoleScopes take a list and report per-row outcomes. (invalidateSubjects also takes a list, but it is a cache drop rather than a write and returns void.)

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

Every row is validated before any is written, so a malformed row aborts the batch instead of half-applying it. Each affected subject is invalidated once, however many rows named it. The drizzle adapter collapses the writes into one INSERT and one DELETE - the DELETE needs or in the adapter's ops, and revokes row by row without it. Adapters with no set-based form loop, so every adapter supports every batch form.

Each outcome carries the row it answers, so nothing has to parse an id back into a triple, and two structurally identical rows stay separate entries:

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

Both role writes are idempotent, so every row is ok: granting a role a subject already holds is success, not a miss, exactly as the single-row assignRole treats it. changed carries the finer answer:

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
changedMeaning
truethis row accounts for a write the statement made
falsethe row was already in the requested state, or an earlier row of the batch already accounts for that write
absentthe adapter could not say, and did not guess

It is absent on MySQL, which has no RETURNING, and on every adapter that loops the single-row methods, which return void. Neither pays for an extra read to find out.

Every write is credited to exactly one row - the first that accounts for it. Listing the same triple twice reports true then false rather than both rows claiming a write the database made once, and revoking {u1, admin} alongside {u1, admin, scope: 'org-1'} credits the wildcard row, which already covers the narrower one. Neither is rejected; both are answered honestly.

Operability

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()))

The invalidator's client needs two Redis connections, not one - a subscribed connection cannot issue other commands - and takes a secret for HMAC-SHA256 envelope signing, which should be set in production.

See the production deployment guide for cache TTL trade-offs, multi-node invalidation patterns, fail-closed defaults, and SLO targets.

Module sizes (gzipped)

Measured at 5.6.0, same run as the performance figures above.

ModuleSize
Core engine (typical import)~15 KB
core/validate (admin only, lazy-loaded)12 KB
core/builder (config-time only)9 KB
core/explain (dev-mode trace)separate chunk
Each adapter1.7 - 6 KB
Each server middleware2.4 - 3.7 KB
Each client library1.2 - 2.0 KB

The "full" bundle headline in benchmarks (~41 KB) is the worst-case "import everything" number - what import * from '@gentleduck/iam' would pull. Realistic deployments end up at 15-25 KB because adapters, server middleware, and clients live behind subpath imports and the validator is lazy-loaded only when admin write paths run. See the benchmarks page for per-profile measurements.

Docs

Contributing

PR checklist + style notes in the repo's CONTRIBUTING.md. Security disclosures: SECURITY.md.

License

MIT. See LICENSE.

版本与发布记录

@gentleduck/iam 共发布 34 个版本,首次发布于 2026/03/12;过去 12 个月发布了 34 个版本。

版本发布日期距今
5.13.0latest2026/10/2719 天前
5.12.02026/10/2323 天前
5.11.02026/09/291 个月前
5.10.02026/09/171 个月前
5.9.02026/09/062 个月前
5.8.12026/09/042 个月前

关于 @gentleduck/iam 的常见问题

@gentleduck/iam 是什么?

Modern ABAC/RBAC access control engine. Framework-agnostic core with integrations for Express, NestJS, Hono, Next.js, React, and 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 和提交记录判断。