\n\n---\n\nType-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.\n\nOne runtime dependency (`uuid`, pulled in only by the Drizzle schema helpers). Tree-shakeable - see [Module sizes](#module-sizes-gzipped) below for real per-module numbers.\n\n## Install\n\n```bash\nnpm install @gentleduck/iam\n# or\nbun add @gentleduck/iam\n```\n\n## Quick start\n\n```typescript\nimport { createIam } from '@gentleduck/iam/core'\nimport { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'\n\nconst access = createIam({\n actions: ['create', 'read', 'update', 'delete'] as const,\n resources: ['post', 'comment', 'user'] as const,\n roles: ['viewer', 'editor', 'admin'] as const,\n})\n\nconst viewer = access.defineRole('viewer').grant('read', 'post').grant('read', 'comment').build()\nconst editor = access.defineRole('editor').inherits('viewer').grant('update', 'post').build()\nconst admin = access.defineRole('admin').inherits('editor').grantCRUD('post').grantCRUD('comment').build()\n\nconst policy = access\n .definePolicy('blog')\n .rule('owner-edit', (r) => r.allow().on('update').of('post').when((w) => w.isOwner()))\n .build()\n\nconst adapter = new IamMemoryAdapter({\n policies: [policy],\n roles: [viewer, editor, admin],\n assignments: { 'user-1': ['editor'] },\n})\n\nconst engine = access.createEngine({ adapter })\nconst allowed = await engine.can('user-1', 'read', { type: 'post', attributes: {} })\n// true\n```\n\n## Performance\n\nBenchmarked against 5 other JS authorization libraries using vitest bench\n(`bun run bench`). Every number in this section was measured at **5.6.0** on one\nmachine in a single run and has not been re-measured since; read them as ratios\nfrom that run, not as a current reading of your hardware. Re-run `bun run bench`\nbefore quoting any of them. Two different things get measured - keep them\nseparate.\n\n**Rule-matching only** (no adapter, no engine wrapper), ops/sec:\n\n| Library | ops/sec | vs CASL |\n|---------|---------|---------|\n| @casl/ability | ~17.0M | baseline |\n| easy-rbac | ~5.0M | 3.4x slower |\n| @rbac/rbac | ~3.3M | 5.2x slower |\n| **@gentleduck/iam** `iamEvaluateFast()` | ~7.6M | 2.2x slower |\n| accesscontrol | ~1.3M | 12.8x slower |\n| casbin | ~208K | 82x slower |\n\n**`engine.can()`** - the real entry point, full stack (adapter + hooks +\nsubject resolution + the compiled table):\n\n| Mode | ops/sec | vs CASL |\n|------|---------|---------|\n| `mode: 'production'` (compiled table) | ~1.15M | ~14x slower |\n| @casl/ability (ability pre-built, `.can()`) | ~17.0M | baseline |\n\n`mode: 'development'` runs the same compiled table for the verdict and *also*\nruns the interpreter, to recover the `reason`/`policy`/`rule` provenance the\ntable erases at compile time and to assert the two agree. That costs roughly\n2.4x production on the same machine. That is the intent: development is where a\ntable/interpreter disagreement should surface, and production is where the\nsecond evaluator would be pure overhead.\n\nCASL is a narrower tool: one flat rule set, fully sync, no persistence\nlayer. `engine.can()` also runs a policy engine (4 combining algorithms\nacross N named policies), RBAC role inheritance, an adapter/cache/\ninvalidation layer, and lifecycle hooks - and it's `async`. That gap is\nthe cost of that surface, not inefficiency to chase down.\n\nIn practice it isn't the bottleneck: ~1.15M ops/sec is ~0.87µs per check\non one core - network, DB, and serialization around it cost more than\nthe check itself in any real request. Throughput doesn't degrade with\ncatalog size either; the compiled table is an O(1) index lookup\nregardless of how many roles or policies exist. What actually\nconstrains scale is catalog *shape* - role count, very wide\naction x resource grids, and deeply nested hierarchical resource types -\nnot raw request throughput. Past 32 roles the 32-bit grant mask can no\nlonger address them all, so the engine warns once and falls back to the\ninterpreter: still correct, no longer O(1).\n\nFor the smallest bundle, import only what you use via subpaths:\n\n```typescript\n// Engine-only (skip adapters, server middleware, client wrappers)\nimport { IamEngine, iamEvaluatePolicyFast } from '@gentleduck/iam/core'\n\n// Each adapter, server adapter, and client wrapper is a separate entry\nimport { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'\nimport { iamAdminRouter } from '@gentleduck/iam/server/express'\nimport { createIamAccessControl } from '@gentleduck/iam/client/react'\n\n// Validator (12 KB) - lazy-loaded by engine.admin.savePolicy on first\n// call, or imported directly for standalone validation tooling\nimport { validatePolicy } from '@gentleduck/iam/core/validate'\n\n// Fluent builder (9 KB) - config-time only, separate subpath\nimport { definePolicy, defineRole } from '@gentleduck/iam/core/builder'\n```\n\n`import * from '@gentleduck/iam'` pulls the everything-barrel (~41 KB\ngzipped). Real deployments using subpath imports + tree-shaking come in\nat 15-25 KB.\n\n## Features\n\n- **RBAC + ABAC** combined in one engine\n- **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)\n- **19 condition operators** (eq, neq, gt, lt, in, contains, starts_with, matches, exists, subset_of, before, after, and more)\n- **Scoped roles** for multi-tenant systems\n- **Dev/prod mode**: `check()` returns an `IDecision` in development and a bare boolean in production; `can()` returns a boolean in both\n- **Explain API**: full evaluation trace showing exactly why a permission was granted or denied\n- **Lifecycle hooks**: `beforeEvaluate`, `afterEvaluate`, `onDeny`, `onError`, `onPolicyError`, `onMetrics`\n- **Type-safe config**: actions, resources, roles, and scopes are validated at compile time\n\n### SRE primitives\n\n- **`engine.preload()`** - warm cache at boot; `{ validator: true }` also validates every stored row\n- **`engine.healthCheck()`** - `/healthz`-ready probe with adapter latency + cache hit rate\n- **`engine.stats.get()` / `engine.stats.reset()`** - cache hit / miss counters per cache\n- **`engine.cache.invalidate()` / `invalidatePolicies()` / `invalidateRoles(id?)` / `invalidateSubject(id)`** - targeted cache flushes\n- **`engine.admin.export()` / `import(snapshot, { mode })`** - schema-versioned policy + role snapshots for env promotion\n- **`engine.dispose()`** - release the cross-instance invalidator subscription on shutdown\n- **`IConfig.adapterTimeoutMs`** - `AbortController`-driven timeout on every adapter call, decision path and `engine.admin` alike (default 5 s)\n- **`IConfig.hookTimeoutMs`** - bound on a promise a hook returns (default 5 s; `0` waits indefinitely)\n- **`IConfig.maxPolicies` / `maxRoles`** - load-time caps that fail closed\n- **`IConfig.allowFailOpen`** - explicit opt-in required whenever `defaultEffect` is `'allow'`, in every mode\n- **`IConfig.invalidator`** - cross-instance cache-invalidation broadcaster\n- **`createIamRedisInvalidator`** at `@gentleduck/iam/invalidators/redis` - pub/sub helper with self-echo filter\n- **`iamCreateMetricsAggregator`** at `@gentleduck/iam/observability/metrics` - p50 / p95 / p99 over `onMetrics` events\n- **HttpAdapter retry + per-request timeout + circuit breaker** (retries, backoff, threshold, cooldown)\n- **Required `authorize` callback** on every admin router (Express, Hono, Next, Nest)\n\n## Integrations\n\n### Server middleware\n\n```typescript\n// Express\nimport { iamGuard, iamAdminRouter } from '@gentleduck/iam/server/express'\napp.delete('/posts/:id', iamGuard(engine, 'delete', 'post'), handler)\napp.use('/admin', iamAdminRouter(engine, { authorize: (req) => isAdmin(req) })(() => express.Router()))\n\n// Hono\nimport { iamGuard, iamBindAdminRouter } from '@gentleduck/iam/server/hono'\napp.delete('/posts/:id', iamGuard(engine, 'delete', 'post'), handler)\niamBindAdminRouter(adminApp, engine, { authorize: (c) => isAdmin(c) })\n\n// NestJS\nimport { iamNestAccessGuard, IamAuthorize, createIamAdminOperations } from '@gentleduck/iam/server/nest'\n@IamAuthorize({ action: 'delete', resource: 'post' })\n\n// Next.js\nimport { withIamAccess, createIamAdminHandlers } from '@gentleduck/iam/server/next'\nexport const DELETE = withIamAccess(engine, 'delete', 'post', handler, {\n getUserId: async () => (await auth()).userId, // required - headers are spoofable\n})\n```\n\n### Client libraries\n\n```typescript\n// React\nimport { createIamAccessControl } from '@gentleduck/iam/client/react'\nconst { AccessProvider, useAccess, Can, Cannot } = createIamAccessControl(React)\n\n// Vue\nimport { createIamVueAccess } from '@gentleduck/iam/client/vue'\nconst { useAccess, Can, Cannot } = createIamVueAccess(vue)\n\n// Vanilla JS\nimport { IamAccessClient } from '@gentleduck/iam/client/vanilla'\nconst client = await IamAccessClient.fromServer('/api/permissions')\nclient.can('read', 'post') // boolean\n```\n\n### Database adapters\n\n```typescript\nimport { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'\nimport { IamFileAdapter } from '@gentleduck/iam/adapters/file'\nimport { IamPrismaAdapter } from '@gentleduck/iam/adapters/prisma'\nimport { IamDrizzleAdapter } from '@gentleduck/iam/adapters/drizzle'\nimport { IamRedisAdapter } from '@gentleduck/iam/adapters/redis'\nimport { IamHttpAdapter } from '@gentleduck/iam/adapters/http'\n```\n\n### Transactions\n\nWrites and reads can run on a transaction you own. `withTransaction(tx)` returns a view of\nthe engine bound to your transaction handle; the handle is opaque to duck-iam and is handed\nstraight back to your adapter.\n\n```typescript\nlet pending\nawait db.transaction(async (tx) => {\n const perms = engine.withTransaction(tx)\n await perms.admin.assignRole(userId, 'admin', orgId)\n await tx.insert(members).values({ userId, orgId })\n pending = perms.pending\n})\nawait pending.flush() // invalidate and broadcast only after the commit\n```\n\nWrites go through `.admin`, the same interface as `engine.admin`, so there is one write\nsurface rather than two.\n\nReads on the bound view run against transaction-local caches, so they see the transaction's\nown uncommitted grants; the shared engine keeps answering from its warm caches, which the\ntransaction never pollutes. An empty local cache always misses through to the bound adapter,\nwhich is what makes a read-after-write inside the transaction correct.\n\n**Cache invalidations do not fire inside a transaction** - including the `config.invalidator`\nfleet broadcast. They buffer in `pending`, de-duplicated, and fire on `flush()`. A\nrolled-back grant therefore never evicts another node's cache for a write that did not\nhappen. `pending.discard()` drops the buffer for an explicit rollback path.\n\n`withTransaction` needs an adapter that implements `withClient`. The drizzle and prisma\nadapters do; memory, file, redis and http do not - they have no transaction to join - and\n`withTransaction` throws rather than silently leaving writes outside yours.\n\n### Batch writes\n\n`assignRoles`, `revokeRoles` and `moveRoleScopes` take a list and report per-row outcomes.\n(`invalidateSubjects` also takes a list, but it is a cache drop rather than a write and\nreturns `void`.)\n\n```typescript\nconst result = await engine.admin.assignRoles([\n { subjectId: 'u1', roleId: 'admin' },\n { subjectId: 'u2', roleId: 'editor', scope: 'org-1' },\n])\nresult.applied // 2\nresult.outcomes // one entry per input row, in input order\n```\n\nEvery row is validated before any is written, so a malformed row aborts the batch instead\nof half-applying it. Each affected subject is invalidated once, however many rows named it.\nThe drizzle adapter collapses the writes into one `INSERT` and one `DELETE` - the `DELETE`\nneeds `or` in the adapter's `ops`, and revokes row by row without it. Adapters with no\nset-based form loop, so every adapter supports every batch form.\n\nEach outcome carries the row it answers, so nothing has to parse an id back into a triple,\nand two structurally identical rows stay separate entries:\n\n```typescript\nconst result = await engine.admin.assignRoles(rows)\nresult.outcomes.map((o) => o.row) // the rows you passed in, same objects, same order\n```\n\nBoth role writes are idempotent, so every row is `ok`: granting a role a subject already\nholds is success, not a miss, exactly as the single-row `assignRole` treats it. `changed`\ncarries the finer answer:\n\n```typescript\nconst again = await engine.admin.assignRoles([{ subjectId: 'u1', roleId: 'admin' }])\nagain.applied // 1 - the grant is in place\n\n// `ok` is always `true`: a malformed row aborts the whole batch before any write, so\n// there is no failed-row arm to narrow on. Read `value` directly.\nconst [outcome] = again.outcomes\noutcome?.value.changed // false - this call is not what put it there\n```\n\n| `changed` | Meaning |\n|---|---|\n| `true` | this row accounts for a write the statement made |\n| `false` | the row was already in the requested state, or an earlier row of the batch already accounts for that write |\n| absent | the adapter could not say, and did not guess |\n\nIt is absent on MySQL, which has no `RETURNING`, and on every adapter that loops the\nsingle-row methods, which return `void`. Neither pays for an extra read to find out.\n\nEvery write is credited to exactly one row - the first that accounts for it. Listing the\nsame triple twice reports `true` then `false` rather than both rows claiming a write the\ndatabase made once, and revoking `{u1, admin}` alongside `{u1, admin, scope: 'org-1'}` credits\nthe wildcard row, which already covers the narrower one. Neither is rejected; both are\nanswered honestly.\n\n### Operability\n\n```typescript\nimport { createIamRedisInvalidator } from '@gentleduck/iam/invalidators/redis'\nimport { iamCreateMetricsAggregator } from '@gentleduck/iam/observability/metrics'\n\nconst metrics = iamCreateMetricsAggregator()\nconst engine = new IamEngine({\n adapter,\n invalidator: createIamRedisInvalidator({ client: redis }),\n hooks: { onMetrics: metrics.record },\n})\n\nawait engine.preload()\napp.get('/healthz', async (_, res) => res.json(await engine.healthCheck()))\napp.get('/metrics', (_, res) => res.json(metrics.snapshot()))\n```\n\nThe invalidator's `client` needs two Redis connections, not one - a subscribed\nconnection cannot issue other commands - and takes a `secret` for HMAC-SHA256\nenvelope signing, which should be set in production.\n\nSee the [production deployment guide](https://gentleduck.org/duck-iam/duck-iam/guides/production) for cache TTL trade-offs, multi-node invalidation patterns, fail-closed defaults, and SLO targets.\n\n## Module sizes (gzipped)\n\nMeasured at 5.6.0, same run as the performance figures above.\n\n| Module | Size |\n|--------|------|\n| Core engine (typical import) | ~15 KB |\n| `core/validate` (admin only, lazy-loaded) | 12 KB |\n| `core/builder` (config-time only) | 9 KB |\n| `core/explain` (dev-mode trace) | separate chunk |\n| Each adapter | 1.7 - 6 KB |\n| Each server middleware | 2.4 - 3.7 KB |\n| Each client library | 1.2 - 2.0 KB |\n\nThe \"full\" bundle headline in benchmarks (~41 KB) is the worst-case\n\"import everything\" number - what `import * from '@gentleduck/iam'`\nwould pull. Realistic deployments end up at 15-25 KB because adapters,\nserver middleware, and clients live behind subpath imports and the\nvalidator is lazy-loaded only when admin write paths run. See the\n[benchmarks page](https://gentleduck.org/duck-iam/duck-iam/benchmarks)\nfor per-profile measurements.\n\n## Docs\n\n- **Reference (start here): [`docs/reference/`](./docs/reference/README.md)** - eleven pages\n covering the package subsystem by subsystem, written against the source. The engine and its\n config, the operator table, roles and scope, validation, the builder and traces, every\n adapter, the four server integrations, the clients, the devtools, and operations.\n- Site: [gentleduck.org/duck-iam](https://gentleduck.org/duck-iam)\n- Compiled engine internals (wildcard buckets, role bitmasks, the compiled table, with diagrams): [`docs/compiled-engine-explained.md`](./docs/compiled-engine-explained.md)\n- Engine rewrite design history + known limits: [`docs/engine-rewrite.md`](./docs/engine-rewrite.md)\n- Devtools: import `@gentleduck/iam/dt` to inspect policy evaluation inside your app\n- Sibling repos: [`@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)\n\n## Contributing\n\nPR checklist + style notes in the repo's [`CONTRIBUTING.md`](https://github.com/gentleeduck/duck-iam/blob/main/CONTRIBUTING.md).\nSecurity disclosures: [`SECURITY.md`](./SECURITY.md).\n\n## License\n\nMIT. See [`LICENSE`](./LICENSE).\n","readmeFilename":"README.md"}
![\"@gentleduck/iam\"](\"./public/logo-dark.svg\"){kind=logo}
\n![\"npm\"/](\"https://img.shields.io/npm/v/@gentleduck/iam.svg\")
\n ![\"downloads\"/](\"https://img.shields.io/npm/dm/@gentleduck/iam.svg\")
\n ![\"MIT\"/](\"https://img.shields.io/npm/l/@gentleduck/iam.svg\")
\n