@zudojs/permissions

INSTALLATION

WHAT IT DOES

@zudojs/permissions is a full-featured authorization engine. It provides:

• → RBAC and ABAC authorization with role-based and attribute-based access control
• → Permission parsing and matching with resource:action format and wildcard support
• → Role hierarchy with inheritance chains and circular detection
• → Rule engine with exact, wildcard, and conditional (ABAC) matching — deny-overrides by default, priority-based on request
• → Policy evaluation with wildcard matching, timeouts, priority ordering, and fail-closed error handling — a policy narrows access by default and grants only with effect: "grant"
• → Ability context for pre-resolved actors with can/cannot/check/explain
• → Decision caching keyed by actor, permission and resource, with configurable TTL, size cap and actor-level invalidation — opt-in only for resolver-backed engines, via resolverCacheKey
• → HTTP middleware integration with actor extraction and permission guards
• → Explain mode for debugging authorization decisions with step-by-step traces
• → 13 error classes covering all permission, role, and policy failure modes
• → Observability events with permission check metrics and duration tracking

WHERE IT SITS

The permissions engine sits between the application layer and the authorization sub-systems. It resolves actor roles, evaluates rules against policies, and produces decisions that applications enforce.

DEPENDENCIES

CORE TYPES

PermissionActor

An entity requesting access — user, service, worker, bot, etc.

Permission

A parsed permission with resource and action.

PermissionString

Permission string format: "resource:action" or wildcards like "post:*", "*:*".

RuleEffect

PermissionRule

A permission rule that grants or denies access under conditions.

PermissionConditionFn

PermissionContext

PermissionDecision

ROLES & HIERARCHY

RoleDefinition

createRoleRegistry

Creates a central registry for role definitions with define/get/has/all/remove/clear methods.

resolveRolePermissions

Resolves all permissions for a set of role names, following inheritance chains and detecting cycles.

Role Errors

PERMISSIONS REGISTRY

createPermissionRegistry

Creates a central registry for defining and looking up permissions.

Implications and the engine

A registry records implications, and expandImplied follows the chains. Since 1.3.0 createPermissionEngine accepts the registry itself in that slot, not only a closure over it.

parsePermission

Matching Functions

Permission Errors

RULE ENGINE

The rule engine compiles rules into an indexed structure for O(1) lookup. Rules support wildcards and deny-overrides by default (any applicable deny wins, whatever its priority); algorithm: "priority" picks highest-priority-wins with deny breaking ties. An allowing policy never overrides a deny rule that applied; such a denial reports reason: "rule_deny".

ruleMatches

evaluateRules

evaluateRules is async, because a rule's conditions may be. It returns a Promise, so await it: without await, result.allowed is undefined, and if (result) is always true. For rules with no conditions, evaluateRulesSync(rules, target) returns the same result synchronously; it skips a conditional allow and applies a conditional deny.

compileRules & findMatchingRules

RuleIndex Structure

CONDITIONS

Condition combinators for composing ABAC policies. All functions return PermissionConditionFn.

Condition Summary

POLICIES

PermissionPolicyDefinition

What a policy's answer means

A policy runs alongside the rules for every permission it lists. Policies run highest priority first and stop at the first denial, and a denial always wins. What a policy's answer means depends on its effect:

• → "constrain" (the default): “no objection”. The policy is an extra condition on top of RBAC/ABAC, so the actor's roles, direct permissions or rules must still grant the permission. An allow means “no objection”; allowed: false, a throw or a policyTimeout denies. It can take access away, never hand it out.
• → "grant": an independent grant. The allow grants the permission even when no role or rule does, with reason policy_allow. allowed: false, a throw or a timeout abstains: the policy adds nothing, and the decision falls to the roles, permissions and rules. It can add access, never take it away. Use it only for a policy that establishes the right on its own, such as an ownership check. Only the exact string "grant" grants; a typo constrains.

Policies that grant

A policy that establishes the right on its own says so with effect: "grant". The rule is one-sided: when it allows, it grants; when it returns false, throws or times out, it abstains. An ownership policy therefore only has to answer “is this the author?” — an editor whose role grants the permission still gets in when the policy says false, and an actor with neither is still refused. A throw or timeout is still reported through onError.

A granting policy never overrides a denial from another policy, deniedPermissions, or a deny rule that applied. createPermissionEngine({ defaultPolicyEffect: "grant" }) keeps the pre-1.4 semantics for policies that set no effect: there, an allow grants and a false still denies. policyGrants(policy, defaultEffect?) tells you whether a policy would grant, and DEFAULT_POLICY_EFFECT is "constrain". Internally, an allow from constraining policies alone is recorded as policy_pass; the decision you get back then carries the grant's reason (such as role_permission) with policy naming the policies that ran.

createPolicyRegistry

Policy Errors

EVALUATOR

EvaluatorOptions

evaluate

evaluateWithExplain

resolveActorPermissions

Resolves all permissions for an actor (direct + role-based).

PermissionEngine

The main public API for permission checks.

createPermissionEngine

ABILITY

An Ability provides fast permission checks for a pre-resolved actor. Create once, check many times.

Ability Interface

createAbility

RESOLVERS

Interfaces

Factory Functions

Resolvers and the decision cache

resolverCacheKey takes the actor and returns something that changes whenever the resolver's answer for that actor could change — a grants-table version, an updatedAt stamp, a generation counter. It has no default. Returning undefined leaves that actor uncached, which is the right answer for an actor whose upstream state you cannot describe.

A resolver that fails is reported through onError and the check continues fail-closed, rather than throwing out of the authorization path.

CACHING

Hand the cache to the engine and it manages the keys itself. A key carries the actor id, a digest of everything else the actor holds (roles, permissions, type, any other field a condition may read), the permission, the resource id and the engine's configuration generation. The same user id with different roles — an admin token in one tenant and a viewer token in another, or a demoted token — therefore never shares a decision. Role and policy registry changes, and invalidateRoles(), clear the decision cache.

A check is cached only when the key can describe it completely. These are not cached:

• → a resource with no id and no options.resourceId — the key would collapse to actor + permission, and an allow for one object would answer for the next;
• → a check carrying metadata, because conditions such as tenantIsolation() read the tenant from there and it is not part of the key;
• → an actor carrying something the digest cannot describe — a function, a class instance, a Map;
• → a decision produced by a policy marked cacheable: false, or forced by a condition that threw;
• → since 1.3.0, anything from an engine with a roleResolver or permissionResolver and no resolverCacheKey;
• → since 1.3.0, anything from an engine whose expandImplied is a bare function rather than a createPermissionRegistry();
• → a TTL of 0 or less, which means "do not cache", not "cache forever".

deniedPermissions is evaluated before the cache is consulted, so a deny added to the actor takes effect immediately rather than waiting for a cached allow to expire.

PermissionCache Interface

createMemoryPermissionCache

HTTP MIDDLEWARE

Middleware factories that integrate the authorization engine with @zudojs/http's middleware pipeline.

A refusal is a real HTTP response. authorize(), createRequirePermissionMiddleware(), createRequirePermissionsMiddleware() and createActorMiddleware({ requireActor: true }) return a guard response (createGuardResponse from @zudojs/middleware): 403 when the engine denies, 401 with WWW-Authenticate: Bearer when there is no actor. @zudojs/http sends it with that status and a JSON body, and the guards go straight into a route's middleware list with no cast.

Types

Middleware Factories

HTTP Options

extractResource may be async and is awaited; a loader that throws or rejects answers 403. An empty list passed to createRequirePermissionsMiddleware denies. createForbiddenResponse, createUnauthorizedResponse, createNotFoundResponse (since 1.4.1) and createJsonResponse(status, body) build the same guard responses for your own middleware; createJsonResponse throws RangeError for a status outside 100–599.

A resource that does not exist: onMissingResource

Since 1.4.1, authorize(), createRequirePermissionMiddleware and createRequirePermissionsMiddleware take onMissingResource, which decides what the guard does when extractResource returns undefined or null:

• → "check" (the default): evaluate the permission with no resource, as the guards always have. A role grant alone lets the request through, so the handler still has to answer 404 itself.
• → "notFound": answer 404 without evaluating. notFoundResponse shapes the body; the default is {"error":"Not Found","message":"Resource not found"}.
• → "forbid": answer 403 without evaluating.

A request with no actor still gets 401 first. The option does nothing on a guard without extractResource. A refusal records RESOURCE_NOT_FOUND_DECISION (reason: "resource_not_found") under permissions:decision.

OBSERVABILITY

PermissionCheckEvent

createPermissionEventEmitter

UTILITIES

ERROR HIERARCHY

All error types extend PermissionError which extends AuthorizationError from @zudojs/errors.

FULL INTEGRATION EXAMPLE

Complete working example: define roles, create engine, create actor, check permissions, use ability, use HTTP middleware, add caching, and explain mode.

COMPLETE EXPORT INDEX

Every name @zudojs/permissions exports from its package root at v1.3.0 — 139 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.