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(), policy(), 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 Engine with an adapter, 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. MemoryAdapter is for testing and small apps. PrismaAdapter and DrizzleAdapter are for production databases. HttpAdapter 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: A deny from any policy means the overall result is deny.
6. Return decision: The Decision object contains allowed, effect, the matching rule and policy, a reason string, and timing information.

Quick Example

import { defineRole, Engine, MemoryAdapter } 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 MemoryAdapter({
  roles: [viewer, editor, admin],
  assignments: { "user-1": ["editor"], "user-2": ["viewer"] },
});
 
const engine = new Engine({ 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)

import { defineRole, Engine, MemoryAdapter } 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 MemoryAdapter({
  roles: [viewer, editor, admin],
  assignments: { "user-1": ["editor"], "user-2": ["viewer"] },
});
 
const engine = new Engine({ 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

Contributing

Open an issue or pull request on the GitHub repository.

Quick FAQ