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

a-seal

v2.1.3

Published

Access Control Library (ACL)

Downloads

49

Readme

A Seal

Access Control List (ACL) library for Node.JS

Install

npm install a-seal

Usage

Setting up an access control list consists of creating a list of rules. Each rule is composed with the process:

  • match a resource for action(s) then allow role(s).

The isAllowed() function can then by used to check if a user, given their role, is authorized to access a resource. A Seal creates a white-list of rules, so isAllowed() will return false, unless an exception has been created.


// Get the acl instance
import acl from './index.js'

// Compose rules of a 'resource', 'actions' and 'roles' using...
// `match`, `for` and `allow` respectively:
acl.match(/^\/protected-path$/).for(['GET', 'POST']).allow(['admin']);

// Optionally label the rule with a "scope" using an `as` clause
acl.match(/^\/protected-path/).for(['GET', 'POST']).allow(['admin']).as('PROTECTED_WRITE');

//use `isAllowed(role, resource, action)`...
//to determine if a request is allowed to access the resource with a given action:
acl.isAllowed('admin', '/protected-path', 'POST') //true
acl.isAllowed('user', '/protected-path', 'POST') //false

//A Seal creates a white-list of rules, so:
acl.isAllowed('admin', '/protected-path', 'DELETE') //false

Although the examples on this page use HTTP, there is nothing HTTP specific about A Seal.

Middleware

A Seal can be used as Express middleware to authorize requests after authentication with tools such as Passport:

//authentication with Passport
app.use(passport.authenticate('local'));

const acl = require('a-seal')();
acl.match('/protected-path').for('GET').allow('user');
acl.match('/protected-path').for('GET', 'POST').allow('admin').as('PROTECTED_WRITE');

app.use(acl.middleware());

app.use('/protected-path', (req, res, next) => {
    // the matched rule's "scope" label will be added to the request
    res.send(`<p>Authorized ok with scope: ${req.scope}</p>`);
});

app.use((err, req, res) => {
    if(err.status === 403) {
        res.send('<p>Authorization failed</p>');
    }
});

API

match(resource)

Begins a matching context given a resource to match.

Returns: object (matchingContext)

Params

resource

Type: RegExp

Examples:

acl.match(/^\/my-path/) //match with regex (starting with /my-path)

matchingContext.for(actions)

Returns: object (matchingContext)

Completes a matching context by adding one or more actions. When authorizing HTTP requests, for example, actions will typically be HTTP methods.

Returns object (matchingContext)

Params

actions

Type: Array

A list of permitted actions as an array of strings.

Examples

acl.match('/my-path').for(['GET', 'POST']);

//match any action
acl.match('/my-path').for([ANY]);

matchingContext.allow(roles)

Adds a new ACL rule by adding one or more roles to a matching context.

Returns: object (rule)

Params

roles

Type: Array

A list of permitted roles as an array of strings or a list of strings as arguments.

Examples

acl.match('/my-path').for(['GET']).allow([ 'user', 'anon' ]);

//match any role
acl.match('/public').for(['GET']).allow(ANY);

rule.as(scope)

Labels this rule with a custom "scope"

Params

scope

Type: string

Examples

acl.match('/my-path').for(['POST']).allow(['user']).as('user_create');

isAllowed(role, resource, action)

Determines if a given role is authorized to access a given resource with a given action.

Params

role

Type: string

resource

Type: string

action

Type: string

Examples:

acl.isAllowed('admin', '/my-path', 'GET');

middleware(opts)

Returns an Express middleware function that accepts req, res and next arguments.

The role is checked against the ACL ruleset using the isAllowed function. If it returns false, it creates a 403 error; if true the routing chain is allowed to continue.

If req.role is not defined, and a custom anonymous role is not provided, the role value will default to guest.

Params

opts.anon

Type: string

The default role for users (anonymous users). This defaults to 'guest'.

app.use(acl.middleware({ anon: 'anonymous'});

License

MIT © Phil Mander