@trishchuk/nest-casl

Declarative, role-based access control for NestJS powered by CASL. Works with REST, GraphQL and WebSocket.

npm install @trishchuk/nest-casl

Peer dependencies: @nestjs/core, @nestjs/common (>= 7.0.0). Optional: @nestjs/graphql, @nestjs/apollo.

// 1. Define roles
export enum Roles { admin = 'admin', editor = 'editor', viewer = 'viewer' }

// 2. Configure root module
@Module({
  imports: [
    CaslModule.forRoot<Roles>({
      superuserRole: Roles.admin,
      getUserFromRequest: (request) => request.user,
    }),
  ],
})
export class AppModule {}

// 3. Define permissions per feature
const permissions: Permissions<Roles, Post, Actions> = {
  everyone({ can }) {
    can(Actions.read, Post);
  },
  editor({ user, can }) {
    can(Actions.update, Post, { authorId: user.id });
  },
};

@Module({
  imports: [CaslModule.forFeature({ permissions })],
})
export class PostModule {}

// 4. Protect endpoints
@Put(':id')
@UseGuards(AccessGuard)
@UseAbility(Actions.update, Post, PostHook)
async updatePost(@Param('id') id: string, @Body() input: UpdatePostInput) {
  return this.postService.update(id, input);
}

// 5. Use conditions for filtering
@Get()
@UseGuards(AccessGuard)
@UseAbility(Actions.read, Post)
async posts(@CaslFilter() filter: FindOptionsWhere<Post>) {
  return this.postService.findAll({ where: filter });
}

• Role-based permissions with can(), cannot(), extend() and everyone/every
• Conditional access — ownership checks like { userId: user.id } with automatic subject fetching via hooks
• Multi-transport — HTTP, GraphQL, WebSocket via unified ContextProxy
• Conditions as queries — convert CASL rules to SQL, MongoDB, or plain filter objects via @CaslConditions() / @CaslFilter()
• Multi-tenant support — pass tenant context to permission builders via getContextFromRequest
• Dynamic permissions — load rules from database at runtime via onBuildAbility async hook
• Custom ConditionsProxy — conditionsProxyFactory for role-specific proxy behavior (e.g., admin gets no filter)
• Field-level restrictions — cannot(action, subject, ['field']) with customizable getFieldsFromRequest
• Full DI integration — root options registered as global NestJS provider, not global mutable state

This package is a fork of nest-casl with bug fixes, new features, and architectural improvements. See Migration Guide for a step-by-step upgrade path.

MIT