npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ts-access-control

v0.1.20

Published

Role Based Access Control

Downloads

282

Readme

Role Based Access Control (RBAC)

Many Role Based Access Control (RBAC) implementations differ, but the basics is widely adopted since it simulates real life role (job) assignments. But while data is getting more and more complex; you need to define policies on resources, subjects or even environments, this is called Attribute Based Access Control (ABAC).

This is a slimmed down and forked version of the unmaintained onury/accesscontrol project.

Core Features

  • Chainable, friendly API, e.g. ac.can(role).create(resource)
  • Role hierarchical inheritance.
  • Define grants at once (e.g. from database result) or one by one.
  • Grant/deny permissions by attributes defined by glob notation.
  • Ability to control access on own or any resources.
  • No silent errors.
  • Fast. (Grants are stored in memory, no database queries.)

Getting Started

yarn install
yarn build
yarn test

Installation

yarn add ts-access-control

Publishing

To publish a new version of the package, firstly bump the version in the package.json file, then cut a new release on Github. This will automatically initiate the publish Github Action workflow and publish a new version to Github Packages

Guide

import { AccessControl } from 'ts-access-control';

Basic Example

Define roles and grants one by one.

const ac = new AccessControl();
ac.grant('user') // define new or modify existing role. also takes an array.
  .createOwn('video') // equivalent to .createOwn('video', ['*'])
  .deleteOwn('video')
  .readAny('video')
  .grant('admin') // switch to another role without breaking the chain
  .extend('user') // inherit role capabilities. also takes an array
  .updateAny('video', ['title']) // explicitly defined attributes
  .deleteAny('video');

const permission = ac.can('user').createOwn('video');
console.log(permission.granted); // —> true
console.log(permission.attributes); // —> ['*'] (all attributes)

permission = ac.can('admin').updateAny('video');
console.log(permission.granted); // —> true
console.log(permission.attributes); // —> ['title']

Roles

You can create/define roles simply by calling .grant(<role>) or .deny(<role>) methods on an AccessControl instance.

  • Roles can extend other roles.
// user role inherits viewer role permissions
ac.grant('user').extend('viewer');
// admin role inherits both user and editor role permissions
ac.grant('admin').extend(['user', 'editor']);
// both admin and superadmin roles inherit moderator permissions
ac.grant(['admin', 'superadmin']).extend('moderator');
  • Inheritance is done by reference, so you can grant resource permissions before or after extending a role.
// case #1
ac.grant('admin')
  .extend('user') // assuming user role already exists
  .grant('user')
  .createOwn('video');

// case #2
ac.grant('user')
  .createOwn('video')
  .grant('admin')
  .extend('user');

// below results the same for both cases
const permission = ac.can('admin').createOwn('video');
console.log(permission.granted); // true

Notes on inheritance:

  • A role cannot extend itself.
  • Cross-inheritance is not allowed.
    e.g. ac.grant('user').extend('admin').grant('admin').extend('user') will throw.
  • A role cannot (pre)extend a non-existing role. In other words, you should first create the base role. e.g. ac.grant('baseRole').grant('role').extend('baseRole')

Actions and Action-Attributes

[CRUD][crud] operations are the actions you can perform on a resource. There are two action-attributes which define the possession of the resource: own and any.

For example, an admin role can create, read, update or delete (CRUD) any account resource. But a user role might only read or update its own account resource.

For example:

ac.grant('role').readOwn('resource');
ac.deny('role').deleteAny('resource');

Note that own requires you to also check for the actual possession.

Checking Permissions

You can call .can(<role>).<action>(<resource>) on an AccessControl instance to check for granted permissions for a specific resource and action.

const permission = ac.can('user').readOwn('account');
permission.granted; // true

Defining All Grants at Once

You can pass the grants directly to the AccessControl constructor. It accepts either an Object:

// This is actually how the grants are maintained internally.
let grantsObject = {
  admin: {
    video: {
      'create:any': ['*'],
      'read:any': ['*'],
      'update:any': ['*'],
      'delete:any': ['*'],
    },
  },
  user: {
    video: {
      'create:own': ['*'],
      'read:own': ['*'],
      'update:own': ['*'],
      'delete:own': ['*'],
    },
  },
};
const ac = new AccessControl(grantsObject);

... or an Array (useful when fetched from a database):

// grant list fetched from DB (to be converted to a valid grants object, internally)
let grantList = [
  { role: 'admin', resource: 'video', action: 'create:any', attributes: '*' },
  { role: 'admin', resource: 'video', action: 'read:any', attributes: '*' },
  { role: 'admin', resource: 'video', action: 'update:any', attributes: '*' },
  { role: 'admin', resource: 'video', action: 'delete:any', attributes: '*' },

  { role: 'user', resource: 'video', action: 'create:own', attributes: '*' },
  { role: 'user', resource: 'video', action: 'read:any', attributes: '*' },
  { role: 'user', resource: 'video', action: 'update:own', attributes: '*' },
  { role: 'user', resource: 'video', action: 'delete:own', attributes: '*' },
];
const ac = new AccessControl(grantList);

You can set grants any time...

const ac = new AccessControl();
ac.setGrants(grantsObject);
console.log(ac.getGrants());

Contribution Guidelines

Never commit directly to master, create a new branch and submit a pull request.