@cqrs-ddd/pipeline-casl
Fine-grained attribute- and role-based authorization using CASL.
Enforces a two-tier defense-in-depth model:
- Type-Level Authorization (Outer Gate):
CaslBehaviorevaluates static permissions before operations execute (e.g. Can this user executeDeleteUserCommand?), avoiding unnecessary database lookups. - Entity & Field Authorization (Inner Gate):
CaslAuthorizerevaluates fine-grained rules on hydrated domain aggregates inside the handler (e.g. Can this user update this specific article whenauthorId !== currentUserId?) and projects readable fields.
Installation
Section titled “Installation”Requires Node.js 22.12 or later and @casl/ability 7.
Architecture & Two-Tier Authorization Flow
Section titled “Architecture & Two-Tier Authorization Flow”Quick Example
Section titled “Quick Example”Capability Format & Condition Interpolation
Section titled “Capability Format & Condition Interpolation”The permission source loads rules as Capability objects. For compact database storage or JWT claims, serialize them as capability strings:
Capability Examples
Section titled “Capability Examples”| Capability String | Action | Subject | Conditions / Fields | Meaning |
|---|---|---|---|---|
Post|read|* |
read |
Post |
Wildcard | Can read any post |
!Post|delete|* |
delete |
Post |
Inverted (!) |
Explicitly forbidden to delete posts |
Post|update|{"authorId":"${user.id}"}|title,body |
update |
Post |
${user.id} match |
Can only update title and body on own posts |
all|manage|* |
manage |
all |
Wildcard | Superadmin: can perform any action |
Dynamic Condition Interpolation
Section titled “Dynamic Condition Interpolation”Placeholders matching ${user.<field>} in conditions are automatically interpolated against attributes of the active principal:
Entity and Field Checks (CaslAuthorizer)
Section titled “Entity and Field Checks (CaslAuthorizer)”Inside command or query handlers, instantiate CaslAuthorizer to evaluate rules against hydrated entities and sanitize output fields:
authorizer.authorize() throws UnauthorizedActionException if the check fails. authorizer.can(action, subject) returns a boolean for non-throwing conditional logic.
Security & Cache Partitioning (abilityDigest)
Section titled “Security & Cache Partitioning (abilityDigest)”When caching query results (@cqrs-ddd/pipeline-cache) or replaying idempotent commands (@cqrs-ddd/pipeline-idempotency), responses must never be replayed across different permission tiers.
abilityDigest(context) generates a SHA-256 fingerprint of the caller’s rules:
If a user’s permissions change, subsequent requests generate a different cache key, preventing unauthorized cache hits.
NestJS Integration (@cqrs-ddd/nestjs)
Section titled “NestJS Integration (@cqrs-ddd/nestjs)”Provide CaslBehavior in a shared security module:
Decorate @CommandHandler or @QueryHandler with requires:
The global ErrorFilter automatically translates UnauthorizedActionException into HTTP 403 Forbidden with details:
Behavior Ordering
Section titled “Behavior Ordering”Position CaslBehavior before cache and idempotency behaviors in the pipeline:
ZodValidationBehavior: Sanitizes input.CaslBehavior: Verifies authorization before any business logic or caching.CacheBehavior/IdempotencyBehavior: Evaluates short-circuit keys usingabilityDigest.