Package Exports

@casl/ability
@casl/ability/extra

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@casl/ability) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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)

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 ruleToSequelizeQuery(rule) {
  return rule.inverted ? { not: rule.conditions } : rule.conditions
}

function toSequelizeQuery(rules) {
  return rulesToQuery(rules, ruleToSequelizeQuery)
}

// now you can construct sequelize query based on Ability
const query = toSequelizeQuery(ability.rulesFor('read', 'Post'))

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

See Storing Abilities 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