gentleeduck/duck-ui / skills/duck-iam
duck-iam
VerifiedActivate when working with @gentleduck/iam for RBAC/ABAC authorization, defining roles and policies, creating access control middleware for Express/Hono/Next.js, building permission checks in React, or configuring the duck-iam engine with adapters. Covers role builders, policy builders, rule builders, condition builders, server guards, and client-side permission components.
@gentleduck/iam
Modern ABAC/RBAC access control engine. Framework-agnostic core with integrations for Express, Hono, Next.js, NestJS, React, and Vue.
Package Exports
@gentleduck/iam # Main entry (re-exports core)
@gentleduck/iam/core # Core engine, builders, evaluate, explain
@gentleduck/iam/adapters/memory # In-memory adapter (testing/prototyping)
@gentleduck/iam/adapters/prisma # Prisma ORM adapter
@gentleduck/iam/adapters/drizzle # Drizzle ORM adapter
@gentleduck/iam/adapters/http # HTTP adapter (remote engine)
@gentleduck/iam/server/express # Express middleware + guards
@gentleduck/iam/server/hono # Hono middleware + guards
@gentleduck/iam/server/next # Next.js App Router integration
@gentleduck/iam/server/nest # NestJS decorators + module
@gentleduck/iam/server/generic # Framework-agnostic server helpers
@gentleduck/iam/client/react # React provider, hooks, components
@gentleduck/iam/client/vue # Vue composables
@gentleduck/iam/client/vanilla # Vanilla JS permission checker
Quick Setup
1. Define Your Access Schema
Use createIam with as const arrays for full type safety. Every builder method constrains actions, resources, roles, and scopes at compile time.
import { createIam } from '@gentleduck/iam'
const access = createIam({
actions: ['create', 'read', 'update', 'delete', 'publish'] as const,
resources: ['post', 'comment', 'user'] as const,
roles: ['viewer', 'editor', 'admin'] as const,
scopes: ['org-acme', 'org-globex'] as const,
context: {} as unknown as AppContext, // phantom field for typed dot-paths
})
2. Define Roles (RBAC)
const viewer = access.defineRole('viewer')
.name('Viewer')
.desc('Read-only access')
.grantRead('post', 'comment')
.build()
const editor = access.defineRole('editor')
.name('Editor')
.inherits('viewer')
.grant('create', 'post')
.grant('update', 'post')
.grantCRUD('comment')
.grantWhen('delete', 'post', w => w.isOwner())
.build()
const admin = access.defineRole('admin')
.name('Administrator')
.grantAll('*')
.build()
Role builder API:
.name(n)/.desc(d)-- display name and description.inherits(...roleIds)-- inherit permissions from parent roles (recursive, cycle-safe).scope(s)-- restrict all permissions to a scope.grant(action, resource, scope?)-- single permission.grantScoped(scope, action, resource)-- single scoped permission.grantWhen(action, resource, fn)-- conditional permission.grantAll(resource)-- all actions on a resource ('*'for everything).grantRead(...resources)-- read access on multiple resources.grantCRUD(resource)-- create/read/update/delete.meta(attrs)-- arbitrary metadata.build()-- returns plainRoleobject
3. Define Policies (ABAC)
const weekendDeny = access.policy('deny-weekends')
.name('Deny on Weekends')
.algorithm('deny-overrides')
.rule('r-deny-weekends', r => r
.deny()
.on('create', 'update', 'delete')
.of('*')
.when(w => w.env('dayOfWeek', 'in', [0, 6]))
)
.build()
const ownerPolicy = access.policy('owner-access')
.algorithm('allow-overrides')
.rule('owner-update', r => r
.allow()
.on('update')
.of('post')
.when(w => w.isOwner())
)
.rule('owner-delete', r => r
.allow()
.on('delete')
.of('post')
.when(w => w.isOwner())
)
.build()
Combining algorithms:
deny-overrides-- any deny wins (default, best for restrictions)allow-overrides-- any allow wins (best for RBAC / permissive rules)first-match-- first matching rule wins (firewall-style)highest-priority-- highest priority number wins
Policy builder API:
.name(n)/.desc(d)/.version(v)-- metadata.algorithm(a)-- combining algorithm.target({ actions?, resources?, roles? })-- skip policy if request does not match targets.rule(id, fn)-- inline rule via callback.addRule(rule)-- add pre-built rule.build()-- returns plainPolicyobject
4. Define Rules
const rule = access.defineRule('post.update.owner')
.allow()
.desc('Authors may update their own posts')
.priority(20)
.on('update')
.of('post')
.when(w => w.isOwner())
.build()
Rule builder API:
.allow()/.deny()-- set effect (default: allow).desc(d)-- description.priority(p)-- higher = evaluated first (default: 10).on(...actions)-- actions this rule applies to ('*'for all).of(...resources)-- resources this rule applies to ('*'for all).forScope(...scopes)-- restrict to scopes.when(fn)-- ALL-of conditions (AND).whenAny(fn)-- ANY-of conditions (OR).meta(attrs)-- arbitrary metadata.build()-- returns plainRuleobject
5. Condition Builder (When)
The When builder is used inside .when(), .whenAny(), and .grantWhen() callbacks.
Typed dot-path checks:
.check(field, op, value)-- raw condition with typed field paths.eq(field, value)/.neq(field, value).gt(field, value)/.gte(field, value)/.lt(field, value)/.lte(field, value).in(field, values)/.contains(field, value)/.exists(field)/.matches(field, regex)
Semantic shortcuts:
.attr(path, op, value)-- subject attribute (subject.attributes.{path}).resourceAttr(path, op, value)-- resource attribute (resource.attributes.{path}).env(path, op, value)-- environment attribute (environment.{path}).role(roleId)-- subject has role.roles(...ids)-- subject has one of these roles.scope(id)/.scopes(...ids)-- request is in scope.isOwner(ownerField?)--resource.attributes.ownerId eq $subject.id.resourceType(...types)-- resource type check
Nesting (boolean logic):
.and(fn)-- nested ALL-of group.or(fn)-- nested ANY-of group (at least one must hold).not(fn)-- nested NONE-of group (none may hold)
Example -- complex condition:
.when(w => w
.or(o => o.isOwner().role('admin'))
.env('hour', 'gte', 9)
.env('hour', 'lte', 17)
.not(n => n.attr('status', 'eq', 'banned'))
)
6. Create the Engine
import { MemoryAdapter } from '@gentleduck/iam/adapters/memory'
const adapter = new MemoryAdapter({
policies: [weekendDeny, ownerPolicy],
roles: [viewer, editor, admin],
assignments: { 'user-1': ['editor'], 'user-2': ['viewer'] },
attributes: { 'user-1': { department: 'engineering' } },
})
const engine = access.createEngine({
adapter,
defaultEffect: 'deny', // deny when no rule matches (default)
cacheTTL: 60, // seconds (default: 60)
maxCacheSize: 1000, // LRU cache entries (default: 1000)
hooks: {
beforeEvaluate: async (req) => req,
afterEvaluate: async (req, decision) => { /* audit log */ },
onDeny: async (req, decision) => { /* alert */ },
onError: async (err, req) => { /* report */ },
},
})
Engine API (all async except invalidation):
engine.can(subjectId, action, resource, environment?, scope?)-- returnsboolean.resourceis aResourceobject:{ type: string, id?: string, attributes: Record<string, unknown> }.engine.check(subjectId, action, resource, environment?, scope?)-- returnsDecision(includesallowed,effect,reason,duration,timestamp)engine.authorize(request)-- fullAccessRequestevaluationengine.explain(subjectId, action, resource, environment?, scope?)-- returnsExplainResulttrace (debug only, has overhead)engine.permissions(subjectId, checks, environment?)-- batch check, returnsPermissionMapkeyed by"action:resource"or"scope:action:resource"engine.admin-- CRUD interface for policies, roles, subjects (lazy-created)engine.invalidate()/engine.invalidateSubject(id)/engine.invalidatePolicies()/engine.invalidateRoles()
7. Server Integrations
Express
import { accessMiddleware, guard, adminRouter } from '@gentleduck/iam/server/express'
// Global middleware
app.use(accessMiddleware(engine, { getUserId: req => req.user?.id }))
// Per-route guard
app.delete('/posts/:id', guard(engine, 'delete', 'post'), handler)
// Admin API
app.use('/api/access-admin', adminRouter(engine)(() => express.Router()))
Hono
import { accessMiddleware, guard } from '@gentleduck/iam/server/hono'
app.use('*', accessMiddleware(engine, { getUserId: c => c.get('userId') as string }))
app.delete('/posts/:id', guard(engine, 'delete', 'post'), handler)
Next.js App Router
import { withAccess, checkAccess, getPermissions, createNextMiddleware } from '@gentleduck/iam/server/next'
// Route handler wrapper
export const DELETE = withAccess(engine, 'delete', 'post', handler, {
getUserId: req => req.headers.get('x-user-id'),
})
// Server component helper
const allowed = await checkAccess(engine, userId, 'read', 'post')
// Generate permission map for client hydration
const perms = await getPermissions(engine, userId, [
{ action: 'create', resource: 'post' },
{ action: 'delete', resource: 'post' },
])
// Edge middleware
const checkMiddleware = createNextMiddleware(engine, {
rules: [{ pattern: '/api/posts', resource: 'post' }],
getUserId: req => req.headers.get('x-user-id'),
})
8. React Client Integration
import React from 'react'
import { createAccessControl } from '@gentleduck/iam/client/react'
// Create once at app init
export const { AccessProvider, useAccess, usePermissions, Can, Cannot } = createAccessControl(React)
// In layout (pass server-generated permissions)
<AccessProvider permissions={perms}>
<App />
</AccessProvider>
// In components
const { can, cannot } = useAccess()
if (can('delete', 'post')) { /* show delete button */ }
// Declarative
<Can action="create" resource="post" fallback={<p>No access</p>}>
<CreatePostButton />
</Can>
<Cannot action="delete" resource="post">
<p>You cannot delete posts</p>
</Cannot>
Also exported by createAccessControl:
usePermissions(fetchFn, deps?)-- hook to async-fetch permissions from a server endpoint; returns{ permissions, can, loading, error }AccessContext-- raw React context (rarely needed directly)
Testing Authorization
Use MemoryAdapter for unit tests. Seed it with roles, policies, and assignments, then assert with engine.can() or engine.check():
import { createIam } from '@gentleduck/iam'
import { MemoryAdapter } from '@gentleduck/iam/adapters/memory'
import { describe, expect, it } from 'vitest'
describe('authorization', () => {
const access = createIam({
actions: ['read', 'delete'] as const,
resources: ['post'] as const,
roles: ['viewer', 'admin'] as const,
})
const viewer = access.defineRole('viewer').grantRead('post').build()
const admin = access.defineRole('admin').grantAll('*').build()
const engine = access.createEngine({
adapter: new MemoryAdapter({
roles: [viewer, admin],
assignments: { 'u1': ['viewer'], 'u2': ['admin'] },
}),
})
it('viewer can read posts', async () => {
expect(await engine.can('u1', 'read', { type: 'post', attributes: {} })).toBe(true)
})
it('viewer cannot delete posts', async () => {
expect(await engine.can('u1', 'delete', { type: 'post', attributes: {} })).toBe(false)
})
it('admin can delete posts', async () => {
expect(await engine.can('u2', 'delete', { type: 'post', attributes: {} })).toBe(true)
})
})
Use engine.explain() to debug failing assertions -- it returns the full evaluation trace.
Coding Conventions
- Use
createIamfor type-safe builders. Use standalonedefineRole/defineRule/policy/whenonly for untyped or dynamic scenarios. - Always call
.build()to finalize builders -- they return plain data objects. - Roles produce RBAC permissions; policies produce ABAC rules. The engine combines both.
- A deny from any policy is final when using
deny-overrides. - Adapters are async interfaces. Use
MemoryAdapterfor tests, implementAdapterfor production. - The engine caches roles, policies, subjects, and RBAC-to-policy conversions with configurable TTL.
- Use
engine.explain()for debugging -- it returns a full trace of why a decision was made. - Use
engine.permissions()for batch checks -- it loads data once and evaluates many. - Server integrations follow a consistent pattern:
accessMiddlewarefor global checks,guardfor per-route.
Do Not
- Do NOT import from
dist/paths -- use the package export paths listed above. - Do NOT skip
.build()-- builders are mutable; only the built object is safe to pass around. - Do NOT use
allow-overridesfor restriction policies -- a deny rule will be ignored if any allow matches. - Do NOT hardcode role checks in application code -- use the engine or permission maps instead.
- Do NOT mutate
Role/Policy/Ruleobjects after building -- treat them as immutable. - Do NOT call
engine.explain()in production hot paths -- it is a debug tool with extra overhead. - Do NOT forget to invalidate caches after CRUD operations on roles/policies/subjects.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |