@whatworks/payload-rbac 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 What Works Global
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# @whatworks/payload-rbac
+
+<a href="https://whatworks.com.au/?utm_source=github.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="../../assets/blackbanner.svg">
+    <img alt="@whatworks/payload-rbac" src="../../assets/whitebanner.svg">
+  </picture>
+</a>
+
+Role based access control for Payload where the roles live in the database. Editors manage roles in the admin panel through a per-collection **Create / Read / Update / Delete** checkbox matrix; the plugin enforces those permissions across every collection and global.
+
+- Adds a **roles collection** with a checkbox-matrix permissions editor — one row per collection (CRUD) and per global (Read/Update), plus a **Full access** toggle (`'*'`) that covers everything, including collections added later.
+- **Predefine roles in code** — they are seeded on init when missing, and never overwritten afterwards, so the database stays the source of truth.
+- Adds a `roles` relationship field to your auth collections (multi-role; a user's permissions are the union of their roles).
+- **Applies access control automatically** to every collection and global. Access you define explicitly on a collection always wins for that operation — the plugin only fills the gaps.
+- **Privilege-escalation protection**: users can only assign roles, and only add permissions to roles, that their own roles already cover.
+- **Role assignment requires `roles:update`** — for everyone else the roles field renders read-only in the admin panel. And a role your remaining roles could not re-grant cannot be removed from your own account, so you can never accidentally strip your own access.
+- **Built-in admin role** (`adminRole`): a role the plugin locks to full access (`['*']`) — it can never be downgraded, renamed, or deleted through the API, so you can never lose your last full-access role. Only its holders can assign it (even `'*'` through another role is not enough). It is auto-assigned to the first user created, and at least one user always holds it — removing it from (or deleting) the last administrator is blocked, and if the database is damaged so badly that nobody holds it, any signed-in user can claim it for themselves. Other roles can opt into the same code-locking with `protected: true`.
+- **Per-role credential protection** (`credentialChanges: 'self'`): the password, email, and username of users holding such a role can only be changed by the account owner — anyone else sends a password-reset email instead. Always on for the admin role, so an administrator account can never be taken over by another user with `users:update`.
+- Users can always read/update their own account document (configurable), so the admin account view keeps working for low-privilege users.
+
+## Installation
+
+```sh
+pnpm add @whatworks/payload-rbac
+```
+
+## Usage
+
+```ts
+import { rbacPlugin } from '@whatworks/payload-rbac'
+import { buildConfig } from 'payload'
+
+export default buildConfig({
+  // ...
+  plugins: [
+    // Register last so collections added by other plugins are controlled too.
+    rbacPlugin({
+      adminRole: 'Administrator',
+      roles: [
+        {
+          name: 'Editor',
+          permissions: ['posts:create', 'posts:read', 'posts:update', 'posts:delete'],
+        },
+      ],
+    }),
+  ],
+})
+```
+
+Then regenerate the import map so the admin panel can resolve the permissions-matrix component:
+
+```sh
+payload generate:importmap
+```
+
+That's it — a `roles` collection appears in the admin panel, every auth user gets a `roles` field, and every operation on every collection and global now requires a matching permission.
+
+Role names are plain display strings (the roles collection's title field) that double as the seeding key — permissions never reference them — so human-friendly names like `'Administrator'` and `'Editor'` are encouraged.
+
+## Permissions
+
+A permission is a plain string, stored on the role document:
+
+- `'*'` — full access to every controlled collection and global, present and future.
+- `'<slug>:<action>'` — one action on one entity, e.g. `'posts:update'`. Actions are `create`/`read`/`update`/`delete` for collections and `read`/`update` for globals.
+
+A user's permission set is the union of all their roles. Requests without a user are denied wherever the plugin controls access — see [Public access](#public-access-and-custom-rules) below. `readVersions` maps to the entity's `read` permission and `unlock` to `update`.
+
+Payload's internal collections (`payload-preferences`, `payload-migrations`, `payload-locked-documents`, `payload-folders`, …) are created after plugins run; they are never controlled and never appear in the matrix.
+
+## Public access and custom rules
+
+Access you define explicitly on a collection wins for that operation, so public reads keep working the way you wrote them:
+
+```ts
+{
+  slug: 'posts',
+  access: {
+    // Explicit — the plugin leaves it alone: anyone can read published posts.
+    read: ({ req }) => (req.user ? true : { _status: { equals: 'published' } }),
+    // create/update/delete are not defined — the plugin fills them with role checks.
+  },
+}
+```
+
+To combine your own rule with a role check, compose the exported helpers:
+
+```ts
+import { hasPermission, requirePermission } from '@whatworks/payload-rbac'
+
+{
+  access: {
+    // Access-function factory:
+    update: requirePermission('posts:update'),
+    // Or inside your own logic:
+    delete: async ({ req }) =>
+      (await hasPermission(req, 'posts:delete')) && !req.user?.suspended,
+  },
+}
+```
+
+`getUserPermissions(req)` returns the resolved permission set (memoized per request — the roles are fetched at most once per request, no matter how many access functions run).
+
+## Privilege-escalation protection
+
+Enabled by default (`preventPrivilegeEscalation`):
+
+- Assigning a role to a user requires the assigner's own permissions to cover everything that role grants. Assigning a `'*'` role requires holding `'*'`.
+- The `adminRole` is stricter still: it can only be assigned by a user who already holds it — full access through another role is not enough (see [lockout prevention](#the-admin-role-and-protected-roles-lockout-prevention) below).
+- Removing roles from **your own account** mirrors assignment: the roles you keep must cover the removed role's permissions — otherwise you could never assign it back, and one save would have locked you out. Removing a redundant role (e.g. dropping `Viewer` while you keep a `'*'` role) works; removing the role your access comes from is rejected with a 403. Removing roles from _other_ users is not restricted.
+- Adding permissions to a role (or creating a role) is limited to permissions the editor already holds.
+- Writes without a user — local API seeds, init scripts, the first-user registration — are never restricted.
+
+Note that managing users also requires the relevant collection permissions themselves (e.g. `users:update` to edit users, `roles:read` to see the roles being assigned).
+
+### The roles field requires `roles:update` — know the semantics
+
+Changing anyone's roles — your own account included — requires the `roles:update` permission. This is enforced as **field-level access** on the generated roles field, which is what makes the admin panel render the field read-only: an editor can see their roles but cannot touch them, so nobody unchecks their own access by accident. Field access comes with Payload's standard semantics, which are worth knowing before you debug:
+
+- **API writes are silently ignored, not rejected.** A create or update that includes the roles field without `roles:update` succeeds — every other field saves, the response is a 200 — but the roles value is dropped and the stored value kept. Nothing errors and nothing is logged. If a role assignment "didn't stick", check that the requesting user holds `roles:update`.
+- **Creating or duplicating a user without `roles:update` produces a user with no roles** — roles in the create data are dropped the same way.
+- **Assigning roles to another user needs both permissions**: `users:update` to save their document at all, plus `roles:update` for the field.
+- **Self-removals fail loudly, not silently**: a user who does hold `roles:update` gets a 403 error (not a silent keep) when removing a role from their own account that their kept roles cannot cover — see the escalation rules above.
+- **Break-glass**: while no user in the system holds full access, the field stays writable for signed-in users so the [self-claim recovery](#the-admin-role-and-protected-roles-lockout-prevention) can proceed — the escalation guard still vets that write. Without an `adminRole` configured there is no such relaxation: make sure some role keeps `roles:update`, or roles can only be assigned through the local API.
+- **A roles field you defined yourself is left alone**: if your user collection already has a field with the roles field name, the guard hooks apply to it but the `roles:update` field gate does not. Use `rolesField.override` to replace the generated field's `access` when you want different rules.
+
+## The admin role and protected roles (lockout prevention)
+
+Escalation protection alone has a failure mode: removals are always allowed, so if you remove a permission from your **only** full-access role, nobody holds it anymore — and now nobody is allowed to grant it back. You would be permanently locked out of that permission.
+
+The `adminRole` closes that hole: the plugin defines that role itself with `permissions: ['*']`, seeds it, assigns it to the first user, and permanently protects it — you cannot list it in `roles`, so it cannot even be predefined with anything less than full access. Any other predefined role can opt into the same locking with `protected: true`. A protected role is locked to its code definition:
+
+- Its permissions cannot be changed through the API — not even by a `'*'` user. The one write that is accepted is restoring the exact code-defined list; that restore is exempt from the escalation guard, so anyone still holding `roles:update` can repair a drifted protected role without holding the permissions being restored.
+- It cannot be renamed or deleted.
+- Drifted permissions (e.g. from direct database edits) are restored on init.
+- **Only holders can grant the admin role**: assigning it requires holding it yourself — even a `'*'` user cannot join the admin tier on their own. The restriction relaxes only while _nobody_ holds the role at all (a fresh rename, or the plugin newly added to an existing project): then any user whose permissions cover it may step up, and init logs a warning until someone does.
+- **At least one user always holds the admin role**: removing it from the last holder, or deleting that user, is rejected (holders are counted across every collection that carries the roles field). Writes without a user (local API, init scripts) are exempt, like the other guards.
+- **Break-glass recovery**: the guards cannot see database-level damage — if the roles collection is wiped, re-seeding on restart recreates the admin role under a new ID, so every user's role references dangle and nobody holds it. While **no user in the system holds full access**, any signed-in user may assign the admin role **to themselves**: open your account, add the role, save. The escalation guard permits exactly that write, the roles collection becomes readable to signed-in users so the role can be picked, and the roles field stays writable without `roles:update`. Nothing is granted automatically — an administrator exists again only when someone claims it — and init logs a warning whenever the admin role has no holder. The moment anyone holds full access again, the exemption switches off.
+- The admin panel renders its permissions matrix read-only with an explanatory note.
+
+To change a protected role's permissions, change the code definition and restart. Writes without a user (local API, init scripts) are not restricted, matching the other guards.
+
+Renaming `adminRole` seeds a fresh role under the new name with no holders; your existing administrators still hold full access through the old role, and since the new role has no holders yet, the holder-only rule stands aside and lets them assign it in the admin panel (init logs a warning until someone does). The old role stays in the database as an ordinary, no-longer-protected role — delete it when you're done with it.
+
+## Self-only credentials
+
+Permissions alone cannot protect an account from other users: `users:update` is enough to set someone else's password — or to change their email and request a password reset to it — and take the account over. So credential changes get their own rule, per role: the password, email, and username of a user holding a `credentialChanges: 'self'` role can only be changed by that user, no matter what permissions everyone else holds. Helping a locked-out colleague means sending them a password-reset email. Email and username are locked together with password deliberately — an editable email plus the reset flow would take the account over anyway.
+
+The `adminRole` is always `'self'`; opt other roles in per role. The protection follows the role name, so pair `'self'` with `protected: true` to prevent the role being renamed away from it. Writes without a user (local API, seeds) are never restricted, like the other guards.
+
+### Protecting the developer account from client admins
+
+A common handover: the agency keeps a developer account, and the client gets an administrator account of their own. Give the client full access — no need to enumerate permissions per collection — and keep the developer tier to yourself:
+
+```ts
+rbacPlugin({
+  // The developer/agency tier — only holders can grant it, credentials self-only.
+  adminRole: 'Super Admin',
+  roles: [
+    {
+      name: 'Admin',
+      description: 'Site administrator.',
+      // Full access to everything, including collections added later.
+      permissions: ['*'],
+      protected: true,
+    },
+  ],
+})
+```
+
+The client runs the whole site — content, users, roles, future collections — but the developer account stays out of reach:
+
+- They cannot change the developer's password, email, or username (the admin role is always `credentialChanges: 'self'`), so credential takeover is closed.
+- They cannot hold or hand out `'Super Admin'`: even with `'*'`, assigning the admin role requires already holding it.
+- They cannot strip the role from — or delete — the last developer account, and the role itself cannot be renamed, downgraded, or deleted.
+
+Note the last-holder guard only protects the _last_ holder: with two or more Super Admin accounts, a user with `users:update`/`users:delete` can still strip or delete all but one of them (their credentials stay protected regardless).
+
+## Options
+
+```ts
+rbacPlugin({
+  // Which collections are access-controlled and appear in the matrix. Defaults to all
+  // collections present when the plugin runs (register the plugin last).
+  // - true — every collection (default)
+  // - ['posts', 'pages'] — only these
+  // - { exclude: ['media'] } — all except these
+  collections: true,
+
+  // Which globals are controlled (read/update). Same semantics. Defaults to all.
+  globals: true,
+
+  // Auth collections that receive the roles field.
+  // Defaults to every auth-enabled collection.
+  userCollections: ['users'],
+
+  // The built-in administrator role: always full access (['*']), always protected
+  // (no API edits/renames/deletes, drift repaired on init), auto-assigned to the
+  // first user created. A name, or { name, description }. Default: false.
+  adminRole: 'Administrator',
+
+  // Additional roles seeded on init when no role with the same name exists.
+  // `protected: true` locks a role to its code definition the same way the
+  // adminRole is locked (default: false — the database wins). `credentialChanges:
+  // 'self'` makes holders' password/email/username changeable only by themselves
+  // (default: 'anyone'; the adminRole is always 'self').
+  roles: [{ name: 'Editor', permissions: ['posts:read', 'posts:update'] }],
+
+  // Users may read/update their own user document without holding the collection
+  // permission. Default: ['read', 'update']. Set false to disable.
+  ownAccountAccess: ['read', 'update'],
+
+  // Block users from granting roles/permissions beyond their own. Default: true.
+  preventPrivilegeEscalation: true,
+
+  // The roles collection added by the plugin.
+  rolesCollection: {
+    slug: 'roles', // default
+    // Escape hatch: adjust labels, admin group, extra fields, hooks, …
+    override: (collection) => ({ ...collection, admin: { ...collection.admin, group: 'Admin' } }),
+  },
+
+  // The roles field added to user collections. Changing it requires the
+  // `roles:update` permission (it renders read-only in the admin panel
+  // otherwise); `override` can replace the field's `access` to change that.
+  rolesField: {
+    name: 'roles', // default
+    override: (field) => ({ ...field, saveToJWT: false }),
+  },
+
+  // Disable the plugin entirely (useful per-environment). Default: true.
+  enabled: true,
+})
+```
+
+## Behaviour notes
+
+- **Admin panel navigation** hides collections and globals the user cannot read — no extra configuration needed.
+- **Admin panel login** (`access.admin`) is not restricted by the plugin; a user with no roles can log in but sees nothing. Add your own `access.admin` to auth collections if you want to gate the panel itself.
+- **Roles are resolved from the database** on each request (one indexed query, memoized per request), so permission changes apply immediately — no re-login needed. The role IDs are also stored on the JWT (`saveToJWT`) for consumers reading the token directly.
+- If a user collection already defines a field with the roles field name, the field is left entirely yours — the guard hooks still apply to it, but the `roles:update` field gate does not.
+- Predefined role permissions are validated at startup against the known collections and globals, so a typo fails fast with a clear error.

package/dist/access/rbacAccess.d.ts

@@ -0,0 +1,33 @@
+import { RbacAction } from "../shared.js";
+import { Access } from "payload";
+
+//#region src/access/rbacAccess.d.ts
+type CreateRbacAccessArgs = {
+  action: RbacAction;
+  /**
+   * Actions the requesting user is allowed on their own user document even without
+   * the collection permission. Only relevant on auth collections; grants a
+   * `{ id: { equals: user.id } }` query constraint.
+   */
+  ownAccountActions?: readonly RbacAction[];
+  slug: string;
+};
+/**
+ * Builds the access function the plugin installs for one operation on one
+ * collection or global: deny anonymous requests, allow when any of the user's
+ * roles grants the permission (or `'*'`), otherwise constrain to the user's own
+ * document when the own-account carve-out applies.
+ */
+declare const createRbacAccess: ({
+  slug,
+  action,
+  ownAccountActions
+}: CreateRbacAccessArgs) => Access;
+/**
+ * Access factory for composing role checks into your own access control, e.g.
+ * `access: { update: requirePermission('posts:update') }`.
+ */
+declare const requirePermission: (permission: string) => Access;
+//#endregion
+export { CreateRbacAccessArgs, createRbacAccess, requirePermission };
+//# sourceMappingURL=rbacAccess.d.ts.map

package/dist/access/rbacAccess.js

@@ -0,0 +1,34 @@
+import { permissionsGrant } from "../permissions.js";
+import { getUserPermissions } from "../utilities/getUserPermissions.js";
+
+//#region src/access/rbacAccess.ts
+/**
+* Builds the access function the plugin installs for one operation on one
+* collection or global: deny anonymous requests, allow when any of the user's
+* roles grants the permission (or `'*'`), otherwise constrain to the user's own
+* document when the own-account carve-out applies.
+*/
+const createRbacAccess = ({ slug, action, ownAccountActions = [] }) => {
+	return async ({ req }) => {
+		const { user } = req;
+		if (!user) return false;
+		if (permissionsGrant(await getUserPermissions(req), slug, action)) return true;
+		if (ownAccountActions.includes(action) && user.collection === slug) return { id: { equals: user.id } };
+		return false;
+	};
+};
+/**
+* Access factory for composing role checks into your own access control, e.g.
+* `access: { update: requirePermission('posts:update') }`.
+*/
+const requirePermission = (permission) => {
+	return async ({ req }) => {
+		if (!req.user) return false;
+		const permissions = await getUserPermissions(req);
+		return permissions.has("*") || permissions.has(permission);
+	};
+};
+
+//#endregion
+export { createRbacAccess, requirePermission };
+//# sourceMappingURL=rbacAccess.js.map

package/dist/access/rbacAccess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbacAccess.js","names":[],"sources":["../../src/access/rbacAccess.ts"],"sourcesContent":["import type { Access } from 'payload'\n\nimport type { RbacAction } from '../shared.js'\n\nimport { permissionsGrant } from '../permissions.js'\nimport { getUserPermissions } from '../utilities/getUserPermissions.js'\n\nexport type CreateRbacAccessArgs = {\n  action: RbacAction\n  /**\n   * Actions the requesting user is allowed on their own user document even without\n   * the collection permission. Only relevant on auth collections; grants a\n   * `{ id: { equals: user.id } }` query constraint.\n   */\n  ownAccountActions?: readonly RbacAction[]\n  slug: string\n}\n\n/**\n * Builds the access function the plugin installs for one operation on one\n * collection or global: deny anonymous requests, allow when any of the user's\n * roles grants the permission (or `'*'`), otherwise constrain to the user's own\n * document when the own-account carve-out applies.\n */\nexport const createRbacAccess = ({\n  slug,\n  action,\n  ownAccountActions = [],\n}: CreateRbacAccessArgs): Access => {\n  return async ({ req }) => {\n    const { user } = req\n    if (!user) {\n      return false\n    }\n\n    const permissions = await getUserPermissions(req)\n    if (permissionsGrant(permissions, slug, action)) {\n      return true\n    }\n\n    if (ownAccountActions.includes(action) && user.collection === slug) {\n      return { id: { equals: user.id } }\n    }\n\n    return false\n  }\n}\n\n/**\n * Access factory for composing role checks into your own access control, e.g.\n * `access: { update: requirePermission('posts:update') }`.\n */\nexport const requirePermission = (permission: string): Access => {\n  return async ({ req }) => {\n    if (!req.user) {\n      return false\n    }\n    const permissions = await getUserPermissions(req)\n    return permissions.has('*') || permissions.has(permission)\n  }\n}\n"],"mappings":";;;;;;;;;;AAwBA,MAAa,oBAAoB,EAC/B,MACA,QACA,oBAAoB,EAAE,OACY;AAClC,QAAO,OAAO,EAAE,UAAU;EACxB,MAAM,EAAE,SAAS;AACjB,MAAI,CAAC,KACH,QAAO;AAIT,MAAI,iBADgB,MAAM,mBAAmB,IAAI,EACf,MAAM,OAAO,CAC7C,QAAO;AAGT,MAAI,kBAAkB,SAAS,OAAO,IAAI,KAAK,eAAe,KAC5D,QAAO,EAAE,IAAI,EAAE,QAAQ,KAAK,IAAI,EAAE;AAGpC,SAAO;;;;;;;AAQX,MAAa,qBAAqB,eAA+B;AAC/D,QAAO,OAAO,EAAE,UAAU;AACxB,MAAI,CAAC,IAAI,KACP,QAAO;EAET,MAAM,cAAc,MAAM,mBAAmB,IAAI;AACjD,SAAO,YAAY,IAAI,IAAI,IAAI,YAAY,IAAI,WAAW"}

package/dist/access/rolesFieldAccess.d.ts

@@ -0,0 +1,33 @@
+import { FieldAccess } from "payload";
+
+//#region src/access/rolesFieldAccess.d.ts
+type CreateRolesFieldAccessArgs = {
+  /**
+   * Keep the field writable while no user in the system holds full access, so a
+   * stranded user can still claim the admin role from their own account page.
+   * Set only when an `adminRole` exists — without one there is no break-glass
+   * path to hold open.
+   */
+  breakGlass?: {
+    userCollections: string[];
+  };
+  rolesCollectionSlug: string;
+  rolesFieldName: string;
+};
+/**
+ * Field-level access for the roles field on user collections: changing role
+ * membership requires the `<roles>:update` permission. Field access is what
+ * makes the admin panel render the field read-only, so a user without it can
+ * never accidentally remove their own roles; API writes that include the field
+ * without the permission succeed with the field silently kept unchanged —
+ * Payload's field-access semantics. Writes without a user (seeds, init scripts,
+ * the first-user registration) pass through, like the guard hooks.
+ */
+declare const createRolesFieldAccess: ({
+  breakGlass,
+  rolesCollectionSlug,
+  rolesFieldName
+}: CreateRolesFieldAccessArgs) => FieldAccess;
+//#endregion
+export { CreateRolesFieldAccessArgs, createRolesFieldAccess };
+//# sourceMappingURL=rolesFieldAccess.d.ts.map

package/dist/access/rolesFieldAccess.js

@@ -0,0 +1,31 @@
+import { permissionFor } from "../permissions.js";
+import { hasPermission } from "../utilities/getUserPermissions.js";
+import { anyUserHoldsRole, findFullAccessRoleIds } from "../utilities/fullAccessHolders.js";
+
+//#region src/access/rolesFieldAccess.ts
+/**
+* Field-level access for the roles field on user collections: changing role
+* membership requires the `<roles>:update` permission. Field access is what
+* makes the admin panel render the field read-only, so a user without it can
+* never accidentally remove their own roles; API writes that include the field
+* without the permission succeed with the field silently kept unchanged —
+* Payload's field-access semantics. Writes without a user (seeds, init scripts,
+* the first-user registration) pass through, like the guard hooks.
+*/
+const createRolesFieldAccess = ({ breakGlass, rolesCollectionSlug, rolesFieldName }) => {
+	const requiredPermission = permissionFor(rolesCollectionSlug, "update");
+	return async ({ req }) => {
+		if (!req.user) return true;
+		if (await hasPermission(req, requiredPermission)) return true;
+		if (!breakGlass) return false;
+		const fullAccessRoleIds = await findFullAccessRoleIds(req.payload, rolesCollectionSlug);
+		return !await anyUserHoldsRole(req.payload, fullAccessRoleIds, {
+			rolesFieldName,
+			userCollections: breakGlass.userCollections
+		});
+	};
+};
+
+//#endregion
+export { createRolesFieldAccess };
+//# sourceMappingURL=rolesFieldAccess.js.map

package/dist/access/rolesFieldAccess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rolesFieldAccess.js","names":[],"sources":["../../src/access/rolesFieldAccess.ts"],"sourcesContent":["import type { FieldAccess } from 'payload'\n\nimport { permissionFor } from '../permissions.js'\nimport { anyUserHoldsRole, findFullAccessRoleIds } from '../utilities/fullAccessHolders.js'\nimport { hasPermission } from '../utilities/getUserPermissions.js'\n\nexport type CreateRolesFieldAccessArgs = {\n  /**\n   * Keep the field writable while no user in the system holds full access, so a\n   * stranded user can still claim the admin role from their own account page.\n   * Set only when an `adminRole` exists — without one there is no break-glass\n   * path to hold open.\n   */\n  breakGlass?: {\n    userCollections: string[]\n  }\n  rolesCollectionSlug: string\n  rolesFieldName: string\n}\n\n/**\n * Field-level access for the roles field on user collections: changing role\n * membership requires the `<roles>:update` permission. Field access is what\n * makes the admin panel render the field read-only, so a user without it can\n * never accidentally remove their own roles; API writes that include the field\n * without the permission succeed with the field silently kept unchanged —\n * Payload's field-access semantics. Writes without a user (seeds, init scripts,\n * the first-user registration) pass through, like the guard hooks.\n */\nexport const createRolesFieldAccess = ({\n  breakGlass,\n  rolesCollectionSlug,\n  rolesFieldName,\n}: CreateRolesFieldAccessArgs): FieldAccess => {\n  const requiredPermission = permissionFor(rolesCollectionSlug, 'update')\n  return async ({ req }) => {\n    if (!req.user) {\n      return true\n    }\n    if (await hasPermission(req, requiredPermission)) {\n      return true\n    }\n    if (!breakGlass) {\n      return false\n    }\n    // Break-glass: while nobody holds full access the field must stay writable,\n    // or the stranded self-claim would be stripped from the write before the\n    // escalation guard — which still limits what that write may do — saw it.\n    const fullAccessRoleIds = await findFullAccessRoleIds(req.payload, rolesCollectionSlug)\n    return !(await anyUserHoldsRole(req.payload, fullAccessRoleIds, {\n      rolesFieldName,\n      userCollections: breakGlass.userCollections,\n    }))\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AA6BA,MAAa,0BAA0B,EACrC,YACA,qBACA,qBAC6C;CAC7C,MAAM,qBAAqB,cAAc,qBAAqB,SAAS;AACvE,QAAO,OAAO,EAAE,UAAU;AACxB,MAAI,CAAC,IAAI,KACP,QAAO;AAET,MAAI,MAAM,cAAc,KAAK,mBAAmB,CAC9C,QAAO;AAET,MAAI,CAAC,WACH,QAAO;EAKT,MAAM,oBAAoB,MAAM,sBAAsB,IAAI,SAAS,oBAAoB;AACvF,SAAO,CAAE,MAAM,iBAAiB,IAAI,SAAS,mBAAmB;GAC9D;GACA,iBAAiB,WAAW;GAC7B,CAAC"}

package/dist/collections/createRolesCollection.d.ts

@@ -0,0 +1,30 @@
+import { MatrixRow } from "../shared.js";
+import { CollectionConfig } from "payload";
+
+//#region src/collections/createRolesCollection.d.ts
+type CreateRolesCollectionArgs = {
+  access: CollectionConfig['access'];
+  hooks?: CollectionConfig['hooks'];
+  matrixRows: MatrixRow[];
+  override?: (collection: CollectionConfig) => CollectionConfig;
+  /** Names of code-locked roles; the matrix renders read-only for them. */
+  protectedRoleNames?: string[];
+  slug: string;
+};
+/**
+ * Builds the roles collection. Permissions are stored as an array of
+ * `'<slug>:<action>'` strings (plus `'*'`) in a `select` field, so every value is
+ * validated against the known collections and globals; the admin UI renders them
+ * through the plugin's checkbox-matrix field component.
+ */
+declare const createRolesCollection: ({
+  slug,
+  access,
+  hooks,
+  matrixRows,
+  override,
+  protectedRoleNames
+}: CreateRolesCollectionArgs) => CollectionConfig;
+//#endregion
+export { CreateRolesCollectionArgs, createRolesCollection };
+//# sourceMappingURL=createRolesCollection.d.ts.map

package/dist/collections/createRolesCollection.js

@@ -0,0 +1,63 @@
+import { FULL_ACCESS, permissionFor } from "../permissions.js";
+import { permissionsMatrixFieldPath } from "../shared.js";
+
+//#region src/collections/createRolesCollection.ts
+/**
+* Builds the roles collection. Permissions are stored as an array of
+* `'<slug>:<action>'` strings (plus `'*'`) in a `select` field, so every value is
+* validated against the known collections and globals; the admin UI renders them
+* through the plugin's checkbox-matrix field component.
+*/
+const createRolesCollection = ({ slug, access, hooks, matrixRows, override, protectedRoleNames = [] }) => {
+	const options = [{
+		label: "Full access",
+		value: FULL_ACCESS
+	}, ...matrixRows.flatMap((row) => row.actions.map((action) => ({
+		label: `${row.label}: ${action}`,
+		value: permissionFor(row.slug, action)
+	})))];
+	const collection = {
+		slug,
+		access,
+		admin: {
+			defaultColumns: ["name", "description"],
+			description: "Roles control what users can access. Assign them on the user document.",
+			useAsTitle: "name"
+		},
+		fields: [
+			{
+				name: "name",
+				type: "text",
+				index: true,
+				label: "Name",
+				required: true,
+				unique: true
+			},
+			{
+				name: "description",
+				type: "textarea",
+				label: "Description"
+			},
+			{
+				name: "permissions",
+				type: "select",
+				admin: { components: { Field: {
+					clientProps: {
+						protectedRoleNames,
+						rows: matrixRows
+					},
+					path: permissionsMatrixFieldPath
+				} } },
+				hasMany: true,
+				label: "Permissions",
+				options
+			}
+		],
+		hooks
+	};
+	return override ? override(collection) : collection;
+};
+
+//#endregion
+export { createRolesCollection };
+//# sourceMappingURL=createRolesCollection.js.map

package/dist/collections/createRolesCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createRolesCollection.js","names":["options: Option[]","collection: CollectionConfig"],"sources":["../../src/collections/createRolesCollection.ts"],"sourcesContent":["import type { CollectionConfig, Option } from 'payload'\n\nimport type { MatrixRow } from '../shared.js'\n\nimport { FULL_ACCESS, permissionFor } from '../permissions.js'\nimport { permissionsMatrixFieldPath } from '../shared.js'\n\nexport type CreateRolesCollectionArgs = {\n  access: CollectionConfig['access']\n  hooks?: CollectionConfig['hooks']\n  matrixRows: MatrixRow[]\n  override?: (collection: CollectionConfig) => CollectionConfig\n  /** Names of code-locked roles; the matrix renders read-only for them. */\n  protectedRoleNames?: string[]\n  slug: string\n}\n\n/**\n * Builds the roles collection. Permissions are stored as an array of\n * `'<slug>:<action>'` strings (plus `'*'`) in a `select` field, so every value is\n * validated against the known collections and globals; the admin UI renders them\n * through the plugin's checkbox-matrix field component.\n */\nexport const createRolesCollection = ({\n  slug,\n  access,\n  hooks,\n  matrixRows,\n  override,\n  protectedRoleNames = [],\n}: CreateRolesCollectionArgs): CollectionConfig => {\n  const options: Option[] = [\n    { label: 'Full access', value: FULL_ACCESS },\n    ...matrixRows.flatMap((row) =>\n      row.actions.map((action) => ({\n        label: `${row.label}: ${action}`,\n        value: permissionFor(row.slug, action),\n      })),\n    ),\n  ]\n\n  const collection: CollectionConfig = {\n    slug,\n    access,\n    admin: {\n      defaultColumns: ['name', 'description'],\n      description: 'Roles control what users can access. Assign them on the user document.',\n      useAsTitle: 'name',\n    },\n    fields: [\n      {\n        name: 'name',\n        type: 'text',\n        index: true,\n        label: 'Name',\n        required: true,\n        unique: true,\n      },\n      {\n        name: 'description',\n        type: 'textarea',\n        label: 'Description',\n      },\n      {\n        name: 'permissions',\n        type: 'select',\n        admin: {\n          components: {\n            Field: {\n              clientProps: { protectedRoleNames, rows: matrixRows },\n              path: permissionsMatrixFieldPath,\n            },\n          },\n        },\n        hasMany: true,\n        label: 'Permissions',\n        options,\n      },\n    ],\n    hooks,\n  }\n\n  return override ? override(collection) : collection\n}\n"],"mappings":";;;;;;;;;;AAuBA,MAAa,yBAAyB,EACpC,MACA,QACA,OACA,YACA,UACA,qBAAqB,EAAE,OAC0B;CACjD,MAAMA,UAAoB,CACxB;EAAE,OAAO;EAAe,OAAO;EAAa,EAC5C,GAAG,WAAW,SAAS,QACrB,IAAI,QAAQ,KAAK,YAAY;EAC3B,OAAO,GAAG,IAAI,MAAM,IAAI;EACxB,OAAO,cAAc,IAAI,MAAM,OAAO;EACvC,EAAE,CACJ,CACF;CAED,MAAMC,aAA+B;EACnC;EACA;EACA,OAAO;GACL,gBAAgB,CAAC,QAAQ,cAAc;GACvC,aAAa;GACb,YAAY;GACb;EACD,QAAQ;GACN;IACE,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,UAAU;IACV,QAAQ;IACT;GACD;IACE,MAAM;IACN,MAAM;IACN,OAAO;IACR;GACD;IACE,MAAM;IACN,MAAM;IACN,OAAO,EACL,YAAY,EACV,OAAO;KACL,aAAa;MAAE;MAAoB,MAAM;MAAY;KACrD,MAAM;KACP,EACF,EACF;IACD,SAAS;IACT,OAAO;IACP;IACD;GACF;EACD;EACD;AAED,QAAO,WAAW,SAAS,WAAW,GAAG"}

package/dist/exports/client.d.ts

@@ -0,0 +1,2 @@
+import { PermissionsMatrixField, PermissionsMatrixFieldProps } from "../fields/PermissionsMatrixField.js";
+export { PermissionsMatrixField, type PermissionsMatrixFieldProps };

package/dist/exports/client.js

@@ -0,0 +1,5 @@
+'use client';
+
+import { PermissionsMatrixField } from "../fields/PermissionsMatrixField.js";
+
+export { PermissionsMatrixField };

package/dist/fields/PermissionsMatrixField.d.ts

@@ -0,0 +1,21 @@
+import { MatrixRow } from "../shared.js";
+import { SelectFieldClientProps } from "payload";
+import React from "react";
+
+//#region src/fields/PermissionsMatrixField.d.ts
+type PermissionsMatrixFieldProps = {
+  /** Names of code-locked roles the matrix renders read-only for. */
+  protectedRoleNames?: string[];
+  /** Serialized by the plugin into the field's `clientProps`. */
+  rows?: MatrixRow[];
+} & SelectFieldClientProps;
+/**
+ * Renders the roles collection's `permissions` select as a matrix of collections ×
+ * Create/Read/Update/Delete checkboxes (globals: Read/Update), with a "full access"
+ * master toggle for `'*'`. The stored value stays a plain array of permission
+ * strings, so the REST/local APIs are unaffected.
+ */
+declare const PermissionsMatrixField: React.FC<PermissionsMatrixFieldProps>;
+//#endregion
+export { PermissionsMatrixField, PermissionsMatrixFieldProps };
+//# sourceMappingURL=PermissionsMatrixField.d.ts.map