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

payload-rbac

v1.0.3

Published

Simple role based access control for your Payload cms

Downloads

51

Readme

author snyk downloads npm version license

payload-rbac

Easy to use Role based access for your Payload cms.

Main features:

  • plugin to add role system to your users collection(s)
  • ready to use access control functions for many different scenario's
  • powerful filtering options built on top of Payloads query system

Installation

With yarn:

yarn add payload-rbac

With npm:

npm install payload-rbac

Usage

Add the plugin to your payload config to extend your auth collection:

import { buildConfig } from 'payload/config';
import rbac from 'payload-rbac';

export default buildConfig({
  plugins: [
    rbac({
      collections: ['users'], // collections to enable rbac on, default: all auth collections
      roles: ['reader', 'maintainer', 'admin'], // roles
    }),
  ],
  // The rest of your config goes here
});

Use the access control functions

All access control functions allow you to control who can access your data and allow you to add an optional filter. This documentation assumes that you are familiar with the Payload documentation on access control.

Allow anonymous

Anyone has access

import { allowAnonymous } from 'payload-rbac';

const unfilteredAccess = allowAnonymous();
const filteredAccess = allowAnonymous<Page>({ _status: { equals: 'published' } });

You can also use the filtered alias, which might make you code more readable if you're using allowAnonymous in combiniation with other access control functions.

import { filtered } from 'payload-rbac';

const filteredAccess = filtered<Page>({ _status: { equals: 'published' } });

Allow anonymous access to published documents

Any has access to published documents

import { allowPublished } from 'payload-rbac';

const allPublishedAccess = allowPublished();
const filteredAccess = allowPublished<Page>({ author: { equals: 'Santa' } });

Allow any user

Any logged in user has access

import { allowAnyUser } from 'payload-rbac';

const unfilteredAccess = allowAnyUser();
const filteredAccess = allowAnyUser<Post>({ author: { equals: ({ req }) => req.user!.id } });

Allow user with a given role

Only users with the given role have access

import { allowUserWithRole } from 'payload-rbac';

const unfilteredAccess = allowUserWithRole('admin');
const filteredAccess = allowUserWithRole<Media>('reader', { _status: { equals: 'published' } });

Allow access based on environment variable

Only allow access if the node environment variable with the given key has the given value

import { allowEnvironmentValues } from 'payload-rbac';

const unfilteredAccess = allowEnvironmentValues('SERVICE_ENV', 'staging');
const filteredAccess = allowEnvironmentValues<Alert>('SERVICE_ENV', 'staging', { _status: { equals: 'published' } });

Block all requests

Blocks all requests. If used with payload-openapi or payload-swagger, endpoints with this access control function are excluded from documentation.

import { blockAll } from 'payload-rbac';

const access = blockAll();

Filters

All payload-rbac access functions accept an optional where parameter. If a where paremeter is provided it is used as a query if access is granted. See payload documentation for more information queries.

As filter you can use a payload Where query, but you can also use functions as operands, that receive the AccessArgs as input.

import { Access } from 'payload';
import { filtered } from 'payload-rbac';

const access: Access = filtered<Page>({
  or: [
    { _status: { equals: 'published' } }, // normal where
    { author: { equals: ({ req }) => req.user?.id || '#not-an-author#' } }, // active where
  ],
});

To get the most out of the typesystem, it is recommended to use the generic type parameter on the access control function to specify the collection you're using it on (Page in the example above). When you specify the collection the typesystem will be able to check that all paths are correct and your operands are of the correct type and it will be able to provide you autocomplete suggestions.

Composite access control functions

The composite access control functions allow you to easily combine access control functions, both the functions of payload-rbac as well as your own access control functions.

Require one

Allows access if at least one of the given control functions grants access. If all of the matching control functions return a query, those queries are combined with and or statement.

import { allowPublished, allowUserWithRole, requireOne } from 'payload-rbac';

// Anyone has access to published documents, but only editors can see draft documents
const requireOne(allowPublished(), allowUserWithRole('editor'));

Require all

Allows access if all of the given control functions grants access. If one or more of the access control functions return a query, those queries are combined with and and statement.

import { allowPublished, allowAnyUser, requireAll } from 'payload-rbac';

// User needs to login to see the published documents (and cannot see draft documents)
const requireAll(allowPublished(), allowAnyUser());

Combine composites

Composites can be nested:

import { allowPublished, allowAnyUser, allowUserWithRole, requireAll, requireOne } from 'payload-rbac';

const compositeAccess = requireOne(
  requireAll(allowPublished(), allowAnyUser()), // any logged in user can access published documents
  allowUserWithRole('editor'), // editors can access all documents
);

Version history

See changelog