@casl/ability

CASL Ability

This package is the core of CASL. It includes logic responsible for checking and defining permissions.

Installation

npm install @casl/ability

Getting Started

CASL concentrates all attention at what a user can actually do and allows to create abilities in DSL style. Lets see how

1. Defining Abilities

AbilityBuilder allows to define abilities using DSL:

import { AbilityBuidler } from '@casl/abiltiy'

const ability = AbilityBuilder.define((can, cannot) => {
  can('protect', 'Website')
  cannot('delete', 'Website')
})

class Website {}

console.log(ability.can('delete', new Website())) // false

If you would like to define abilities in own function, it'd better to use its extract method:

import { AbilityBuidler, Ability } from '@casl/abiltiy'

function defineAbilityFor(user) {
  const { rules, can, cannot } = AbilityBuilder.extract()

  if (user.isAdmin) {
    can('manage', 'all')
  } else {
    can('read', 'all')
    can('manage', 'Post', { author: 'me' })
    cannot('delete', 'Post')
  }

  return new Ability(rules)
}

Also you can combine similar rules together:

const { can, rules } = AbilityBuilder.extract()

can(['read', 'update'], 'User', { id: 'me' })
can(['read', 'update'], ['Post', 'Comment'], { authorId: 'me' })

console.log(rules)

Sometimes you may need to define permissions per field. For example, you can let moderator update only post status field

const { can, rules } = AbilityBuilder.extract()

can('read', 'all')

if (user.is('moderator')) {
  can('update', 'Post', 'status')
} else if (user.is('editor')) {
  can('update', 'Post', ['title', 'description'], { authorId: user.id })
}

const ability = new Ability(rules)

See Defining Abilities for details.

2. Checking rules

Later on you can check abilities by using can and cannot.

// true if user can read at least one Post
ability.can('read', 'Post')

// true if user cannot update a post
const post = new Post({ title: 'What is CASL?', authorId: 'not_me' })
ability.cannot('update', post)

See Check Abilities for details.

3. Serializing rules

As rules are plain objects, they can be easily serialized and cached in session or JWT token or even saved to any database and added dynamically later in admin panel.

const jwt = require('jsonwebtoken')
const payload = {
  rules: ability.rules
}

jwt.sign(payload, secret, (error, token) => {
  if (error) {
    return next(error)
  }

  // later you can send this token to client
  // and restore Ability on the client using `jwt.verify`
  console.log(token)
})

See Caching Abilities for details.

4. Extra

This package also provides @casl/ability/extra submodule which contains helper functions that can construct a database query based on permissions or extract some information from them.

import { rulesToQuery } from '@casl/ability/extra'

function ruleToMongoQuery(rule) {
  return rule.inverted ? { $nor: [rule.conditions] } : rule.conditions
}

function toMongoQuery(ability, subject, action = 'read') {
  return rulesToQuery(ability, action, subject, ruleToMongoQuery)
}

// now you can construct query based on Ability
const query = toMongoQuery(ability, 'Post')

@casl/mongoose uses rulesToQuery function to construct queries to MongoDB database.

See Storing Abilities for details.

Another useful method is permittedFieldsOf which allows to find all permitted fields for specific subject and action. You can use this method together with lodash.pick to extract only allowed fields from request body

import { permittedFieldsOf } from '@casl/ability/extra'

const { can, rules } = AbilityBuilder.extract()

can('update', 'Post', ['title', 'description'])

const ability = new Ability(rules)

// later in request middleware
const fields = permittedFieldsOf(ability, 'update', 'Post')
const attributesToUpdate = _.pick(req.body, fields)

See Extracting Permitted Attributes for details.

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on guidelines for contributing

License

MIT License

Similar packages

Other packages similar to @casl/ability

accesscontrol

AccessControl is a Node.js module that provides a flexible and intuitive way to manage role-based access control (RBAC) and attribute-based access control (ABAC). It is similar to @casl/ability in that it allows you to define and check permissions, but it focuses more on roles and attributes.

rbac

RBAC is a simple and flexible role-based access control library for Node.js. It allows you to define roles and permissions and check if a user has a specific role or permission. Compared to @casl/ability, RBAC is more focused on role management and less on fine-grained permissions.