@gentleduck/iam

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.

Zero runtime dependencies. Tree-shakeable. 23 KB full, under 1 KB per module.

Install

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

Quick start

import { createAccessConfig } from '@gentleduck/iam'
import { MemoryAdapter } from '@gentleduck/iam/adapters/memory'

const access = createAccessConfig({
  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
  .policy('blog')
  .rule('owner-edit', (r) => r.allow().on('update').of('post').when((w) => w.isOwner()))
  .build()

const adapter = new MemoryAdapter({
  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 7 JS authorization libraries using vitest bench. Simple RBAC check, ops/sec (higher is better):

| Library | ops/sec | vs CASL | |---------|---------|---------| | @casl/ability | 16,857,000 | baseline | | @gentleduck/iam [PROD] | 8,233,000 | 2x slower | | easy-rbac | 5,003,000 | 3.4x slower | | @rbac/rbac | 2,884,000 | 5.8x slower | | accesscontrol | 674,000 | 25x slower | | casbin | 143,000 | 118x slower | | role-acl | 140,000 | 120x slower |

CASL is faster on raw lookups because it pre-compiles rules into a hash table at build time. duck-iam supports dynamic policies that can change at runtime, which costs an extra Map lookup per check.

For the smallest bundle, import only the evaluator:

import { evaluatePolicyFast } from '@gentleduck/iam'
const allowed = evaluatePolicyFast(policy, request) // boolean

Features

• RBAC + ABAC combined in one engine
• Policy engine with 4 combining algorithms (deny-overrides, allow-overrides, first-match, highest-priority)
• 18 condition operators (eq, neq, gt, lt, in, contains, starts_with, matches, exists, subset_of, and more)
• Scoped roles for multi-tenant systems
• Dev/prod mode: rich Decision objects in development, plain booleans in production
• Explain API: full evaluation trace showing exactly why a permission was granted or denied
• Lifecycle hooks: beforeEvaluate, afterEvaluate, onDeny, onError
• LRU caching with configurable TTL
• Rule indexing with pre-computed results for unconditional rules
• Type-safe config: actions, resources, roles, and scopes are validated at compile time

Integrations

Server middleware

// Express
import { guard } from '@gentleduck/iam/server/express'
app.delete('/posts/:id', guard(engine, 'delete', 'post'), handler)

// Hono
import { guard } from '@gentleduck/iam/server/hono'
app.delete('/posts/:id', guard(engine, 'delete', 'post'), handler)

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

// Next.js
import { withAccess } from '@gentleduck/iam/server/next'
export const DELETE = withAccess(engine, 'delete', 'post', handler)

Client libraries

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

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

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

Database adapters

import { MemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { PrismaAdapter } from '@gentleduck/iam/adapters/prisma'
import { DrizzleAdapter } from '@gentleduck/iam/adapters/drizzle'
import { HttpAdapter } from '@gentleduck/iam/adapters/http'

Module sizes (gzipped)

| Module | Size | |--------|------| | Core (full) | 23.3 KB | | Each adapter | 0.9 - 1.7 KB | | Each server middleware | 0.8 - 1.3 KB | | Each client library | 1.0 - 1.4 KB |

Documentation

Full docs, course, and API reference: duck-iam docs

License

MIT