Introduction

duck-iam (@gentleduck/iam, version 5.9.0) decides what an authenticated subject may do. It runs role-based and attribute-based access control through one evaluation pipeline, loads its catalog from a pluggable adapter, and ships server middleware and client permission maps for the common frameworks.

What duck-iam is

An authorization engine. You declare your actions, resources, roles, and scopes once; define roles with permissions and policies with rules and conditions; then ask the engine questions:

await engine.can('user-1', 'read', { type: 'post', attributes: {} }) // boolean

Actions, resources, scopes, and role IDs are constrained at compile time through const type parameters on createIam(). A misspelled action fails the type check before it can fail a request.

duck-iam is not authentication. It answers "may this subject do this?", never "who is this?". Pair it with duck-auth for the identity half; the auth bridge guide wires the two together.

Why one engine for roles and policies

RBAC is simple and rigid: it cannot express "editors may update only their own posts". ABAC is expressive and verbose: writing every ordinary role grant as a policy rule is tedious.

duck-iam does both, and does not keep two code paths. Roles are compiled into a synthetic policy by rolesToPolicy(), so a role grant and an attribute policy hit the same evaluator, the same condition operators, and the same combining algorithms. There is no second set of semantics to reason about.

• Role inheritance — admin inherits editor inherits viewer; permissions cascade. Depth is capped by MAX_INHERITANCE_DEPTH (32) and cycles are cut by a shallowest-depth memo, so a bad role graph cannot hang a check.
• Policies with conditions — allow delete on post when resource.attributes.ownerId equals $subject.id.
• Four in-policy combining algorithms — deny-overrides, allow-overrides, first-match, highest-priority.
• Three cross-policy combine modes — and (default), allow-overrides, first-applicable.
• 19 condition operators — eq, neq, gt, gte, lt, lte, in, nin, contains, not_contains, starts_with, ends_with, matches, exists, not_exists, subset_of, superset_of, before, after.
• Scoped roles — one subject can be admin in org-1 and viewer in org-2.
• Explain traces — engine.explain() returns which policies were considered, which rules matched, and which conditions passed or failed, with actual versus expected values.

Feature map

System architecture

The engine sits between your request handlers and your policy storage. Everything above the adapter line is in-process and cache-backed; the adapter is the only thing that talks to a database.

Engine. Construct an IamEngine with an IamEngineTypes.IConfig, then call can(), check(), permissions(), explain(), or authorize(). RES and LOAD are the cache-backed loaders; a steady-state request hits cache and never reaches AD.

Adapter. The storage backend, implementing policy, role, and subject stores. IamMemoryAdapter is for tests and small apps; IamPrismaAdapter and IamDrizzleAdapter back production databases; IamHttpAdapter reads from a remote authorization service.

Policies. ABAC rules grouped into policy objects. Each policy carries a combining algorithm and a rule list; each rule carries an effect, target actions and resources, conditions, and a priority. Policies evaluate independently, then EV combines them with policyCombine.

Roles. RBAC definitions with permissions and optional inheritance, converted into a synthetic policy so they meet your own policies inside EV. Role permissions may carry conditions of their own.

Invalidator and metrics. INV broadcasts cache invalidation across nodes so a policy write on one instance is visible on all of them. MET aggregates the onMetrics events that HOOK emits.

How a check flows

A call to engine.can() walks five layers: entry validation, catalog load, subject preparation, evaluation, and reporting. It fails closed at every one of them — an adapter timeout, a subject-resolution failure, or a throwing hook resolves to deny, never to allow.

1. Resolve subject. Load assigned roles, scoped roles, and attributes; close roles over inherits.
2. Enrich scoped roles. When the request carries a scope, merge the roles assigned in that scope.
3. Load the catalog. Fetch policies, generate the RBAC policy from roles, and merge. Concurrent misses collapse into one adapter call.
4. Evaluate. Skip policies whose targets do not match, match rules by action and resource, evaluate conditions, apply each policy's algorithm, then combine across policies. Under the default and, any deny is final; policies that do not apply are skipped rather than folded in as default-deny.
5. Report. Return an AccessControl.IDecision in development mode or a plain boolean in production, and fire the reporting hooks.

The evaluation pipeline page walks each layer with the source; rule matching covers step 4 in detail.

Quick example

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

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

const viewer = access.defineRole('viewer').grantRead('post', 'comment').build()
const editor = access.defineRole('editor').inherits('viewer').grant('create', 'post').grant('update', 'post').build()
const admin = access.defineRole('admin').inherits('editor').grant('delete', 'post').grant('manage', 'user').build()

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

const engine = access.createEngine({ adapter })

await engine.can('user-1', 'read', { type: 'post', attributes: {} }) // true, inherited from viewer
await engine.can('user-1', 'create', { type: 'post', attributes: {} }) // true, direct editor grant
await engine.can('user-2', 'create', { type: 'post', attributes: {} }) // false, viewer cannot create
await engine.can('user-1', 'delete', { type: 'post', attributes: {} }) // false, only admin may delete

Adapters, server middleware, and clients live behind subpath imports; the root barrel exports only the core surface. See installation for the full export map.

Which page do I need

Gotchas

• engine.explain() throws in production mode. That is deliberate: the tracer is a lazily imported chunk that production bundles never load.
• The root barrel @gentleduck/iam exports the core surface only. Adapters, server middleware, clients, invalidators, metrics, and the devtools live behind subpaths, and importing the barrel pulls roughly 41 KB gzipped where subpath imports land at 15 to 25 KB.
• defaultEffect: 'allow' throws at construction unless you also pass allowFailOpen: true, and even then logs a startup warning. Failing open is opt-in and loud on purpose.
• The compiled table addresses roles with a 32-bit grant mask, so a catalog over 32 roles cannot be compiled. Nothing denies and nothing throws to the caller: the engine warns once, drops to the interpreter for every subsequent request in both modes, and reports it on healthCheck().compiledTable. Verdicts are unchanged; the O(1) lookup is not. The flag is latched for the life of the engine — deleting roles back under 32 does not restore the table, only a new engine does.

See also

• Installation — every export path and its peer dependencies.
• Core concepts — the model in depth.
• Quick start — the end-to-end walkthrough.
• How it compares — the honest trade-offs against other engines.
• @gentleduck/auth — the identity half. duck-auth proves who the caller is; duck-iam decides what they may do.

Quick FAQ

Contributing

Issues and pull requests go to the GitHub repository. Security disclosures follow the process in the package's SECURITY.md.