Install npm package with yarn add nest-casl or npm i nest-casl
Peer dependencies are @nestjs/core, @nestjs/common and @nestjs/graphql
Define roles for app:
// app.roles.ts
export enum Roles {
admin = 'admin',
operator = 'operator',
customer = 'customer',
}Configure application:
// app.module.ts
import { Module } from '@nestjs/common';
import { CaslModule } from 'nest-casl';
import { Roles } from './app.roles';
@Module({
imports: [
CaslModule.forRoot<Roles>({
// Role to grant full access, optional
superuserRole: Roles.admin,
// Function to get casl user from request
// Optional, defaults to `(request) => request.user`
getUserFromRequest: (request) => request.currentUser,
}),
],
})
export class AppModule {}superuserRole will have unrestricted access. If getUserFromRequest omitted request.user will be used. User expected to have properties id: string and roles: Roles[] by default, request and user types can be customized.
nest-casl comes with a set of default actions, aligned with Nestjs Query.
manage has a special meaning of any action.
DefaultActions aliased to Actions for convenicence.
export enum DefaultActions {
read = 'read',
aggregate = 'aggregate',
create = 'create',
update = 'update',
delete = 'delete',
manage = 'manage',
}In case you need custom actions either extend DefaultActions or just copy and update, if extending typescript enum looks too tricky.
Permissions defined per module. everyone permissions applied to every user, it has every alias for every({ user, can }) be more readable. Roles can be extended with previously defined roles.
// post.permissions.ts
import { Permissions, Actions } from 'nest-casl';
import { InferSubjects } from '@casl/ability';
import { Roles } from '../app.roles';
import { Post } from './dtos/post.dto';
import { Comment } from './dtos/comment.dto';
export type Subjects = InferSubjects<typeof Post, typeof Comment>;
export const permissions: Permissions<Roles, Subjects, Actions> = {
everyone({ can }) {
can(Actions.read, Post);
can(Actions.create, Post);
},
customer({ user, can }) {
can(Actions.update, Post, { userId: user.id });
},
operator({ can, cannot, extend }) {
extend(Roles.customer);
can(Actions.manage, PostCategory);
can(Actions.manage, Post);
cannot(Actions.delete, Post);
},
};// post.module.ts
import { Module } from '@nestjs/common';
import { CaslModule } from 'nest-casl';
import { permissions } from './post.permissions';
@Module({
imports: [CaslModule.forFeature({ permissions })],
})
export class PostModule {}Assuming authentication handled by AuthGuard. AccessGuard expects user to at least exist, if not authenticated user obtained from request acess will be denied.
// post.resolver.ts
import { UseGuards } from '@nestjs/common';
import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
import { AccessGuard, UseAbility, Actions } from 'nest-casl';
import { CreatePostInput } from './dtos/create-post-input.dto';
import { UpdatePostInput } from './dtos/update-post-input.dto';
import { PostService } from './post.service';
import { PostHook } from './post.hook';
import { Post } from './dtos/post.dto';
@Resolver(() => Post)
export class PostResolver {
constructor(private postService: PostService) {}
// No access restrictions, no request.user
@Query(() => [Post])
posts() {
return this.postService.findAll();
}
// No access restrictions, request.user populated
@Query(() => Post)
@UseGuards(AuthGuard)
async post(@Args('id') id: string) {
return this.postService.findById(id);
}
// Tags method with ability action and subject and adds AccessGuard implicitly
@UseGuards(AuthGuard, AccessGuard)
@UseAbility(Actions.create, Post)
async createPost(@Args('input') input: CreatePostInput) {
return this.postService.create(input);
}
// Use hook to get subject for conditional rule
@Mutation(() => Post)
@UseGuards(AuthGuard, AccessGuard)
@UseAbility(Actions.update, Post, PostHook)
async updatePost(@Args('input') input: UpdatePostInput) {
return this.postService.update(input);
}
}For permissions with conditions we need to provide subject hook in UseAbility decorator. It can be class implementing SubjectBeforeFilterHook interface
// post.hook.ts
import { Injectable } from '@nestjs/common';
import { Request, SubjectBeforeFilterHook } from 'nest-casl';
import { PostService } from './post.service';
import { Post } from './dtos/post.dto';
@Injectable()
export class PostHook implements SubjectBeforeFilterHook<Post, Request> {
constructor(readonly postService: PostService) {}
async run({ params }: Request) {
return this.postService.findById(params.input.id);
}
}passed as third argument of UserAbility
@Mutation(() => Post)
@UseGuards(AuthGuard, AccessGuard)
@UseAbility(Actions.update, Post, PostHook)
async updatePost(@Args('input') input: UpdatePostInput) {
return this.postService.update(input);
}Class hooks are preferred method, it has full dependency injection support and can be reused. Alternatively inline 'tuple hook' may be used, it can inject single service and may be useful for prototyping or single usage use cases.
@Mutation(() => Post)
@UseGuards(AuthGuard, AccessGuard)
@UseAbility<Post>(Actions.update, Post, [
PostService,
(service: PostService, { params }) => service.findById(params.input.id),
])
async updatePost(@Args('input') input: UpdatePostInput) {
return this.postService.update(input);
}CaslSubject decorator provides access to lazy loaded subject, obtained from subject hook and cached on request object.
@Mutation(() => Post)
@UseGuards(AuthGuard, AccessGuard)
@UseAbility(Actions.update, Post, PostHook)
async updatePost(
@Args('input') input: UpdatePostInput,
@CaslSubject() subjectProxy: SubjectProxy<Post>
) {
const post = await subjectProxy.get();
}Permission conditions can be used in resolver through CaslConditions decorator, ie to filter selected records. Subject hook is not required.
@Mutation(() => Post)
@UseGuards(AuthGuard, AccessGuard)
@UseAbility(Actions.update, Post)
async updatePostConditionParamNoHook(
@Args('input') input: UpdatePostInput,
@CaslConditions() conditions: ConditionsProxy
) {
conditions.toSql(); // ['"userId" = $1', ['userId'], []]
conditions.toMongo(); // { $or: [{ userId: 'userId' }] }
}CaslUser decorator provides access to lazy loaded user, obtained from request or user hook and cached on request object.
@Mutation(() => Post)
@UseGuards(AuthGuard, AccessGuard)
@UseAbility(Actions.update, Post)
async updatePostConditionParamNoHook(
@Args('input') input: UpdatePostInput,
@CaslUser() userProxy: UserProxy<User>
) {
const user = await userProxy.get();
}Use AccessService to check permissions without AccessGuard and UseAbility decorator
// ...
import { AccessService, Actions, CaslUser } from 'nest-casl';
@Resolver(() => Post)
export class PostResolver {
constructor(private postService: PostService, private accessService: AccessService) {}
@Mutation(() => Post)
@UseGuards(AuthGuard)
async updatePost(@Args('input') input: UpdatePostInput, @CaslUser() userProxy: UserProxy<User>) {
const user = await userProxy.get();
const post = await this.postService.findById(input.id);
//check and throw error
// 403 when no conditions
// 404 when conditions set
this.accessService.assertAbility(user, Actions.update, post);
// return true or false
this.accessService.hasAbility(user, Actions.update, post);
}
}Check package e2e tests for application testing example.
Sometimes permission conditions require more info on user than exists on request.user User hook called after getUserFromRequest only for abilities with conditions. Similar to subject hook, it can be class or tuple.
Despite UserHook is configured on application level, it is executed in context of modules under authorization. To avoid importing user service to each module, consider making user module global.
// user.hook.ts
import { Injectable } from '@nestjs/common';
import { UserBeforeFilterHook } from 'nest-casl';
import { UserService } from './user.service';
import { User } from './dtos/user.dto';
@Injectable()
export class UserHook implements UserBeforeFilterHook<User> {
constructor(readonly userService: UserService) {}
async run(user: User) {
return {
...user,
...(await this.userService.findById(user.id)),
};
}
}//app.module.ts
import { Module } from '@nestjs/common';
import { CaslModule } from 'nest-casl';
@Module({
imports: [
CaslModule.forRoot({
getUserFromRequest: (request) => request.user,
getUserHook: UserHook,
}),
],
})
export class AppModule {}or with dynamic module initialization
//app.module.ts
import { Module } from '@nestjs/common';
import { CaslModule } from 'nest-casl';
@Module({
imports: [
CaslModule.forRootAsync({
useFactory: async (service: SomeCoolService) => {
const isOk = await service.doSomething();
return {
getUserFromRequest: () => {
if (isOk) {
return request.user;
}
},
};
},
inject: [SomeCoolService],
}),
],
})
export class AppModule {}or with tuple hook
//app.module.ts
import { Module } from '@nestjs/common';
import { CaslModule } from 'nest-casl';
@Module({
imports: [
CaslModule.forRoot({
getUserFromRequest: (request) => request.user,
getUserHook: [
UserService,
async (service: UserService, user) => {
return service.findById(user.id);
},
],
}),
],
})
export class AppModule {}Extending enums is a bit tricky in TypeScript There are multiple solutions described in this issue but this one is the simplest:
enum CustomActions {
feature = 'feature',
}
export type Actions = DefaultActions | CustomActions;
export const Actions = { ...DefaultActions, ...CustomActions };For example, if you have User with numeric id and current user assigned to request.loggedInUser
class User implements AuthorizableUser<Roles, number> {
id: number;
roles: Array<Roles>;
}
interface CustomAuthorizableRequest {
loggedInUser: User;
}
@Module({
imports: [
CaslModule.forRoot<Roles, User, CustomAuthorizableRequest>({
superuserRole: Roles.admin,
getUserFromRequest(request) {
return request.loggedInUser;
},
getUserHook: [
UserService,
async (service: UserService, user) => {
return service.findById(user.id);
},
],
}),
// ...
],
})
export class AppModule {}