CASL Documentation

The CASL documentation is split into two distinct styles to serve different needs:

• The Guide: A narrative-driven introduction that builds knowledge incrementally. It uses simple examples to explain core features and assumes intermediate ES2015 JavaScript knowledge.
• The Cookbook: A collection of standalone recipes focused on specific, complex use cases. Recipes are deeper, more complex, and frequently use TypeScript, frontend/backend frameworks, and real-world scenarios. Each recipe is self-contained and does not assume knowledge from previous sections.

Prerequisites for Cookbook recipes: A basic understanding of JavaScript, npm/yarn, CommonJS, ES import/export, and Node.js module resolution is expected. Depending on the specific recipe, familiarity with certain frontend or backend libraries may be required.

The accessibleRecordsPlugin adds accessibleBy methods to Mongoose queries and model statics. Note: This plugin is deprecated. The recommended approach is to use the accessibleBy helper function instead.

// Global registration
const { accessibleRecordsPlugin } = require('@casl/mongoose');
const mongoose = require('mongoose');

mongoose.plugin(accessibleRecordsPlugin);

// OR Local registration on a specific schema
const mongoose = require('mongoose')
const { accessibleRecordsPlugin } = require('@casl/mongoose')

const Post = new mongoose.Schema({
  title: String,
  author: String
})

Post.plugin(accessibleRecordsPlugin)

module.exports = mongoose.model('Post', Post)

You can attach a reason to an inverted rule using the .because() method. When a permission check fails, you can catch a ForbiddenError to retrieve this specific explanation.

import { defineAbility, ForbiddenError } from '@casl/ability';

export default defineAbility((can, cannot) => {
  can('read', 'all');
  cannot('read', 'all', { private: true })
    .because('You are not allowed to read private information');
});

// Usage
import ability from './defineAbility';

try {
  ForbiddenError.from(ability).throwUnlessCan('read', { private: true });
} catch (error) {
  if (error instanceof ForbiddenError) {
    console.log(error.message); // "You are not allowed to read private information"
  }
}

To avoid confusion between the can/cannot methods used to define rules and the ability.can() method used to check permissions, you can use object destructuring to rename the rule-definition functions. This makes it explicitly clear whether you are currently in a definition context (using names like allow and forbid) or a checking context (using ability.can()).

You can apply this pattern using either defineAbility or the AbilityBuilder class.

import { defineAbility } from '@casl/ability';

// define abilities using explicit names
const ability = defineAbility((allow, forbid) => {
  allow('read', 'Post');
  forbid('read', 'Post', { private: true });
});

// check abilities using the standard can method
ability.can('read', 'Post');

CASL does not include logical operators like $and, $or, $nor, or $not in its condition language. Instead, you achieve this logic through rule composition:

• AND: Combine multiple fields within a single condition object, or use multiple can rules. All properties in a single condition object are checked with AND logic.
• OR: Define multiple can rules for the same action and subject. If any rule matches, the permission is granted.
• NOT: Use cannot rules to negate permissions.

Note: $nor cannot be natively reproduced with standard rules; if required, you must customize the ability.

The pattern of persisting permissions in a database (roles with persisted permissions) should be avoided in the following scenarios:

1. Static Permissions: If you have a predefined set of permissions for every role that is very unlikely to change.
2. Project Uncertainty: If you are starting a new project and are unsure whether you will actually need to dynamically configure permissions.

To use CASL pipes or services in your templates, import the necessary modules and provide the Ability instance in your AppModule. You typically use createMongoAbility() to initialize the ability instance.

import { NgModule } from '@angular/core';
import { AblePipe } from '@casl/angular';
import { createMongoAbility, Ability } from '@casl/ability';

@NgModule({
  imports: [
    // other modules
    AblePipe
  ],
  providers: [
    { provide: Ability, useValue: createMongoAbility() }
  ]
})
export class AppModule {}

To integrate CASL with a Vue 3 application, install both @casl/vue and @casl/ability using your preferred package manager.

npm install @casl/vue @casl/ability
# or
yarn add @casl/vue @casl/ability
# or
pnpm add @casl/vue @casl/ability