Introduction

What is duck-iam?

duck-iam is an authorization engine that runs Role-Based Access Control (RBAC) and Attribute-Based Access Control (ABAC) through one evaluation pipeline. Define roles with permissions, write policies with conditions, and the engine produces an allow or deny decision.

Actions, resources, scopes, and role IDs are checked at compile time through const assertion generics. A misspelled action or unknown resource fails the type check before the code runs.

Why duck-iam?

Most authorization libraries force a choice between RBAC and ABAC. RBAC is simple but rigid; it cannot express "editors can only update their own posts." ABAC is expressive but expensive; writing every permission as a policy rule is tedious for common role patterns.

duck-iam does both. Use roles for the common cases and policies for the edge cases. Roles are converted into policies internally, so one condition engine handles everything.

What you get:

• Role inheritance: admin inherits from editor, which inherits from viewer. Permissions cascade.
• Policies with conditions: "Allow delete on post when resource.attributes.ownerId equals $subject.id."
• Type-safe builders: defineRole(), definePolicy(), when(), all constrained to your declared actions, resources, and scopes.
• Four combining algorithms: deny-overrides, allow-overrides, first-match, highest-priority.
• Multi-tenant scoping: A user can be admin in org-1 and viewer in org-2.
• Caching: LRU caches for policies, roles, and resolved subjects with configurable TTL.
• Dev/Prod mode: Diagnostics and validation in development, fast boolean evaluation in production. See benchmarks.
• Debug tooling: engine.explain() returns the full evaluation trace: which rules matched, which conditions passed or failed, and why.

Key Features

Architecture Overview

duck-iam has four core concepts:

Engine: The evaluator. Create an IamEngine with an IamEngineTypes.IConfig, then call engine.can(), engine.check(), engine.permissions(), or engine.explain(). The engine loads roles and policies from the adapter, resolves the subject, and runs evaluation.

Adapter: The storage backend. Adapters implement PolicyStore + RoleStore + SubjectStore. IamMemoryAdapter is for testing and small apps. IamPrismaAdapter and IamDrizzleAdapter are for production databases. IamHttpAdapter fetches from a remote service.

Policies: ABAC rules organized into policy objects. Each policy has a combining algorithm and a list of rules. Each rule has an effect (allow/deny), target actions and resources, conditions, and a priority. Policies evaluate independently and then combine: a deny from any policy results in an overall deny.

Roles: RBAC definitions with permissions and optional inheritance. Roles are converted to a synthetic ABAC policy, so RBAC and ABAC share the same evaluation path. RBAC permissions can carry conditions (owner-only grants, for example).

How It Works

When an authorization request comes in, the engine follows this pipeline:

1. Resolve subject: Load the user's roles, scoped roles, and attributes from the adapter.
2. Enrich scoped roles: If the request has a scope (org-1, for example), merge in roles assigned to that scope.
3. Load policies: Fetch ABAC policies from the adapter. Convert RBAC roles into a synthetic policy.
4. Evaluate: For each policy, check if it applies to the request. For each matching rule, evaluate conditions against the request context. Apply the policy's combining algorithm to produce a per-policy decision.
5. Combine: Apply policyCombine across policy results. With the default 'and', any deny is final. NotApplicable policies (targets miss) are skipped, not folded as default-deny.
6. Return decision: In development mode the engine returns an AccessControl.IDecision with allowed, effect, the matching rule and policy, a reason string, and timing. In production it returns a plain boolean.

Quick Example

import { defineRole, IamEngine, IamMemoryAdapter } from "@gentleduck/iam";

// 1. Define roles
const viewer = defineRole("viewer")
  .grant("read", "post")
  .grant("read", "comment")
  .build();

const editor = defineRole("editor")
  .inherits("viewer")
  .grant("create", "post")
  .grant("update", "post")
  .build();

const admin = defineRole("admin")
  .inherits("editor")
  .grant("delete", "post")
  .grant("manage", "user")
  .build();

// 2. Create adapter and engine
const adapter = new IamMemoryAdapter({
  roles: [viewer, editor, admin],
  assignments: { "user-1": ["editor"], "user-2": ["viewer"] },
});

const engine = new IamEngine({ adapter });

// 3. Check permissions
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 permission)

await engine.can("user-2", "create", { type: "post", attributes: {} });
// -> false (viewer cannot create)

await engine.can("user-1", "delete", { type: "post", attributes: {} });
// -> false (editor cannot delete, only admin can)

Documentation Map

See also

• @gentleduck/auth - pairs with duck-iam for end-to-end identity + authorization. duck-auth proves who the caller is; duck-iam decides what they may do.

Contributing

Open an issue or pull request on the GitHub repository.

Quick FAQ