@foundrykit/permissions-plugin
v0.1.3
Published
Granular permissions for Payload CMS 3: area.action permissions, editable roles, per-user overrides and an audit log
Readme
@foundrykit/permissions-plugin
Granular permissions for Payload CMS 3: area.action permissions, editable roles, per-user
overrides and an audit log of every change.
Setup
import { permissionsPlugin } from '@foundrykit/permissions-plugin';
export default buildConfig({
plugins: [
permissionsPlugin({
areas: [
{ slug: 'offers', collection: 'offers', label: 'Offers' },
{ slug: 'settings', global: 'settings', label: 'Settings' },
{
slug: 'forms',
label: 'Forms & CRM',
customActions: {
editRecipients: 'Edit enquiry recipients',
resend: 'Resend CRM sends',
},
},
],
// Umi staff: hold every permission, sit outside roles and can't be locked out.
isSuperAdmin: user =>
(process.env.SUPER_ADMIN_EMAILS ?? '')
.split(',')
.includes(user.email as string),
}),
],
});Run payload generate:importmap afterwards. The users collection must not already have role or
lastActiveAt fields, and no roles, permission-overrides or permission-audit-log collections
may exist.
Areas
Each area produces permissions keyed area.action:
| Area maps to | Default actions |
| --------------------- | ------------------------------------------------------------ |
| a collection | read, create, edit, delete (+ publish with drafts) |
| a global | read, edit (+ publish with drafts) |
| nothing (custom area) | none, only customActions |
Pass actions to choose the standard actions explicitly. An action left out is denied for CMS
users. permissions.manage is always registered.
On Postgres, permission keys are stored as an enum, so adding an area or action needs a database
migration (payload migrate:create).
How permissions resolve
- Super admin → allowed.
- Deny override → denied.
- Allow override → allowed.
- Otherwise → the user's role.
Mapped collections and globals are gated for logged-in users of the users collection. Everyone
else (the public site, other auth collections) keeps the entity's original access. Publishing,
meaning _status moving to published, also needs area.publish, and the publish button is
hidden from people without it.
Rules, enforced on the server:
- Changing roles or overrides needs
permissions.manage. - Nobody changes their own role or overrides.
- Nobody grants a permission they don't hold, whether by role edit, role assignment, allow override or lifting a deny.
- A role with users can't be deleted.
- Changing a user's role drops the overrides the new role makes redundant.
Every change is written to the read-only Permission audit log collection.
Using permissions in your own code
import { hasPermission, requirePermission } from '@foundrykit/permissions-plugin'
// Custom endpoint
if (!(await hasPermission(req, 'forms.resend'))) {
return Response.json({ error: 'Forbidden' }, { status: 403 })
}
// Field, collection or global access
{ name: 'recipients', type: 'array', access: { update: requirePermission('forms.editRecipients') } }Admin UI
For people with permissions.manage, a Roles & permissions nav link opens:
/admin/permissions: the roles matrix. Add, rename, duplicate and delete roles, tick permissions per area, and see the impact before saving./admin/permissions/users: every user with their role, override count and when they last logged in or edited. Filter by role or "has overrides". Click a user to open their side panel with role picker, Inherit/Allow/Deny per permission, "Reset to role" and their permission history.- The audit log collection, for the full history.
Development
pnpm install
pnpm dev # dev app on http://localhost:3000/admin ([email protected] / test)
pnpm test # unit, integration and e2e (set E2E_PORT if 3000 is taken)Releasing
Run pnpm release on prod. It bumps the version, updates the changelog and pushes a v* tag.
The tag triggers .github/workflows/publish.yml, which publishes to npm through trusted
publishing, so no npm token is stored locally or in GitHub.
