@extantape/payload-plugin-roles 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EXTANT APE
+
+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

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# payload-plugin-roles
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Per-site role ladders for multi-tenant [Payload](https://payloadcms.com) sites.
+
+Most sites need a handful of roles per site, where a higher role can do everything a lower one can.
+Permission matrices are overkill for that. This plugin gives you:
+
+- **A ladder** of per-site roles, lowest first, e.g. **Member · Author · Curator · Administrator**.
+  `atLeast('author')` means Author, Curator or Administrator.
+- **Platform roles** (e.g. **Maintainer**) for people who work across every site.
+- **Add-on roles** outside the ladder (e.g. "Lab partner") that grant only what you check for them.
+- **Per-site role names**: call Curator "Editor" on one site without changing permissions.
+- **Access helpers** that return Payload `Where` constraints (`tenant in [...]`), built for
+  [`@payloadcms/plugin-multi-tenant`](https://payloadcms.com/docs/plugins/multi-tenant)'s `tenants[].roles` layout.
+
+A role on one site never grants anything on another.
+
+## On its own, and with others
+
+**On its own:** `defineRoles` gives you the helpers with no plugin installed at all. `rolesPlugin` only adds per-site role names to your tenants collection and keeps the role system on `config.custom.roles`. Field names default to the multi-tenant plugin's layout, and `fields` changes them.
+
+**Works with:**
+- **Payload's multi-tenant plugin** (`@payloadcms/plugin-multi-tenant`): its `tenants[].roles` layout is the default, and `roles.options()` fills its role select.
+
+No other Captive Origins plugin reads `config.custom.roles` yet.
+
+**Family:** It's part of the **Identity** family (a working draft): plugins designed to sit together for accounts and access.
+
+## Install
+
+```bash
+npm install @extantape/payload-plugin-roles
+```
+
+```ts
+import { defineRoles, rolesPlugin } from '@extantape/payload-plugin-roles'
+
+export const roles = defineRoles({
+  ladder: [
+    { value: 'member', label: 'Member' },
+    { value: 'author', label: 'Author' },
+    { value: 'curator', label: 'Curator' },
+    { value: 'admin', label: 'Administrator' },
+  ],
+  addOns: [{ value: 'lab', label: 'Lab partner' }],
+  platform: [{ value: 'maintainer', label: 'Maintainer' }],
+})
+
+export default buildConfig({
+  plugins: [
+    multiTenantPlugin({
+      tenantsArrayField: { rowFields: [{ name: 'roles', type: 'select', hasMany: true, options: roles.options() }] },
+      userHasAccessToAllTenants: (user) => roles.isPlatform(user, 'maintainer'),
+    }),
+    rolesPlugin(roles), // adds "Role names on this site" to the tenants collection
+  ],
+})
+```
+
+## Helpers
+
+| Helper | |
+|---|---|
+| `roles.atLeast('curator')` | `['curator', 'admin']` |
+| `roles.sites(user, 'author')` | Site IDs where the user is Author or higher |
+| `roles.has(user, site, 'curator', { platformRole: 'maintainer' })` | Curator or higher there (maintainers pass) |
+| `roles.highest(user, site)` | The user's top ladder role on a site |
+| `roles.isPlatform(user, 'maintainer')` | Platform role check |
+| `roles.access.atLeast('curator', { platformRole: 'maintainer' })` | A Payload `Access`: `true` for maintainers, else `{ tenant: { in: [...] } }` |
+| `roles.label(role, site.roleLabels)` / `roles.options(aliases)` | Names and select options, with per-site names |
+
+Field names default to the multi-tenant plugin's (`tenants`, `tenant`, `roles`) and `platformRoles`;
+change them with `fields`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { defineRoles, type RoleAliases, type RoleDef, type RolesConfig, type RoleSystem } from './roles.js';
+export { rolesPlugin, type RolesPluginOptions } from './plugin.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defineRoles } from './roles.js';
+export { rolesPlugin } from './plugin.js';

package/dist/plugin.d.ts

@@ -0,0 +1,14 @@
+import type { Config, FieldAccess, Plugin } from 'payload';
+import type { RoleSystem } from './roles.js';
+export type RolesPluginOptions = {
+    /** The tenants (sites) collection that gets per-site role names. Default `tenants`. Set false to skip. */
+    tenants?: string | false;
+    /** Who may rename roles on a site (field access). Default: anyone who may update the site. */
+    canRename?: FieldAccess;
+};
+/**
+ * Adds per-site role names ("aliases", e.g. call Curator "Editor" on one site)
+ * to the tenants collection and keeps the role system on `config.custom.roles`.
+ * The helpers themselves come from `defineRoles()` and work without the plugin.
+ */
+export declare const rolesPlugin: (system: RoleSystem, options?: RolesPluginOptions) => ((config: Config) => Config) & Plugin;

package/dist/plugin.js

@@ -0,0 +1,30 @@
+/**
+ * Adds per-site role names ("aliases", e.g. call Curator "Editor" on one site)
+ * to the tenants collection and keeps the role system on `config.custom.roles`.
+ * The helpers themselves come from `defineRoles()` and work without the plugin.
+ */
+export const rolesPlugin = (system, options = {}) => (config) => {
+    const tenants = options.tenants === false ? null : (options.tenants ?? 'tenants');
+    const aliases = {
+        name: 'roleLabels',
+        label: 'Role names on this site',
+        type: 'array',
+        admin: { description: 'Optional: show a role under another name here (e.g. Curator as “Editor”). Permissions don’t change.', initCollapsed: true },
+        access: options.canRename ? { create: options.canRename, update: options.canRename } : undefined,
+        fields: [
+            {
+                type: 'row',
+                fields: [
+                    { name: 'role', type: 'select', required: true, options: [...system.ladder, ...system.addOns].map((r) => ({ label: r.label, value: r.value })), admin: { width: '50%' } },
+                    { name: 'label', type: 'text', required: true, admin: { width: '50%' } },
+                ],
+            },
+        ],
+    };
+    const next = {
+        ...config,
+        collections: (config.collections ?? []).map((c) => (tenants && c.slug === tenants ? { ...c, fields: [...c.fields, aliases] } : c)),
+        custom: { ...config.custom, roles: system },
+    };
+    return next;
+};

package/dist/roles.d.ts

@@ -0,0 +1,72 @@
+import type { Access } from 'payload';
+/** One role: the stored value and its default label. */
+export type RoleDef = {
+    value: string;
+    label: string;
+    description?: string;
+};
+export type RolesConfig = {
+    /** Per-site roles, lowest first. Each includes every role below it (Curator can do what Author can). */
+    ladder: RoleDef[];
+    /** Per-site roles outside the ladder (e.g. "Lab partner"): they grant only what you check for them. */
+    addOns?: RoleDef[];
+    /** Platform-wide roles (e.g. "Maintainer"), for every site. */
+    platform?: RoleDef[];
+    /** Where roles live on the user. Defaults match @payloadcms/plugin-multi-tenant. */
+    fields?: {
+        tenants?: string;
+        tenant?: string;
+        roles?: string;
+        platform?: string;
+    };
+};
+/** Any user object (e.g. Payload's generated `User`); read defensively. */
+type AnyUser = unknown;
+/** Per-site display names, e.g. `[{ role: 'curator', label: 'Editor' }]` (stored on the site by the plugin). */
+export type RoleAliases = {
+    role: string;
+    label: string;
+}[] | null | undefined;
+export type RoleSystem = ReturnType<typeof defineRoles>;
+/**
+ * A role system: a ranked ladder of per-site roles, add-on roles and platform
+ * roles, with helpers that answer "may this user do X on this site?" and
+ * Payload access functions built from them.
+ */
+export declare function defineRoles(config: RolesConfig): {
+    ladder: RoleDef[];
+    addOns: RoleDef[];
+    platform: RoleDef[];
+    fields: {
+        tenants: string;
+        tenant: string;
+        roles: string;
+        platform: string;
+    };
+    /** Every per-site role value (ladder and add-ons). */
+    values: string[];
+    rank: (role: string) => number;
+    atLeast: (role: string) => string[];
+    isPlatform: (user: AnyUser, role?: string) => boolean;
+    sites: (user: AnyUser, role: string | readonly string[]) => string[];
+    has: (user: AnyUser, site: unknown, role: string, { platformRole }?: {
+        platformRole?: string;
+    }) => boolean;
+    highest: (user: AnyUser, site: unknown) => string | null;
+    label: (role: string, aliases?: RoleAliases) => string;
+    options: (aliases?: RoleAliases) => {
+        label: string;
+        value: string;
+    }[];
+    platformOptions: () => {
+        label: string;
+        value: string;
+    }[];
+    access: {
+        atLeast: (role: string, { platformRole, field }?: {
+            platformRole?: string;
+            field?: string;
+        }) => Access;
+    };
+};
+export {};

package/dist/roles.js

@@ -0,0 +1,88 @@
+const idOf = (v) => (v && typeof v === 'object' ? v.id != null ? String(v.id) : null : v != null && v !== '' ? String(v) : null);
+/**
+ * A role system: a ranked ladder of per-site roles, add-on roles and platform
+ * roles, with helpers that answer "may this user do X on this site?" and
+ * Payload access functions built from them.
+ */
+export function defineRoles(config) {
+    const ladder = config.ladder;
+    const addOns = config.addOns ?? [];
+    const platform = config.platform ?? [];
+    if (!ladder.length)
+        throw new Error('payload-plugin-roles: the ladder needs at least one role');
+    const values = [...ladder, ...addOns].map((r) => r.value);
+    if (new Set(values).size !== values.length)
+        throw new Error('payload-plugin-roles: role values must be unique');
+    const f = { tenants: 'tenants', tenant: 'tenant', roles: 'roles', platform: 'platformRoles', ...config.fields };
+    const rank = (role) => ladder.findIndex((r) => r.value === role);
+    /** Ladder roles at or above `role`; an add-on role is only itself. */
+    const atLeast = (role) => {
+        const i = rank(role);
+        if (i >= 0)
+            return ladder.slice(i).map((r) => r.value);
+        if (addOns.some((r) => r.value === role))
+            return [role];
+        throw new Error(`payload-plugin-roles: unknown role "${role}"`);
+    };
+    const field = (user, name) => (user && typeof user === 'object' ? user[name] : undefined);
+    const rows = (user) => { const v = field(user, f.tenants); return Array.isArray(v) ? v : []; };
+    const platformRoles = (user) => { const v = field(user, f.platform); return Array.isArray(v) ? v : []; };
+    /** A row's roles. Anything but an array (e.g. a string) reads as no roles: unclear data grants nothing. */
+    const rowRoles = (row) => {
+        const v = row && typeof row === 'object' ? row[f.roles] : undefined;
+        return Array.isArray(v) ? v.filter((r) => typeof r === 'string') : [];
+    };
+    /** Has this platform role (any platform role when omitted). */
+    const isPlatform = (user, role) => (role ? platformRoles(user).includes(role) : platformRoles(user).length > 0);
+    /** Sites where the user holds `role` or higher (or exactly one of a list of roles). */
+    const sites = (user, role) => {
+        const wanted = typeof role === 'string' ? atLeast(role) : role;
+        return rows(user)
+            .filter((row) => rowRoles(row).some((r) => wanted.includes(r)))
+            .map((row) => idOf(row[f.tenant]))
+            .filter((id) => Boolean(id));
+    };
+    /** Whether the user holds `role` or higher on this site. `platformRole` holders pass everywhere. */
+    const has = (user, site, role, { platformRole } = {}) => (platformRole ? isPlatform(user, platformRole) : false) || (Boolean(idOf(site)) && sites(user, role).includes(idOf(site)));
+    /** The user's highest ladder role on a site (null if none). No site, or a row without one, never matches. */
+    const highest = (user, site) => {
+        const id = idOf(site);
+        if (!id)
+            return null;
+        const row = rows(user).find((r) => r && typeof r === 'object' && idOf(r[f.tenant]) === id);
+        const held = rowRoles(row).map(rank).filter((i) => i >= 0);
+        return held.length ? ladder[Math.max(...held)].value : null;
+    };
+    const label = (role, aliases) => aliases?.find((a) => a.role === role)?.label || [...ladder, ...addOns, ...platform].find((r) => r.value === role)?.label || role;
+    /** Select options for per-site roles (ladder highest first, then add-ons), with optional aliases. */
+    const options = (aliases) => [...[...ladder].reverse(), ...addOns].map((r) => ({ label: label(r.value, aliases), value: r.value }));
+    const platformOptions = () => platform.map((r) => ({ label: r.label, value: r.value }));
+    /**
+     * Access: platform role holders see everything; others only records of sites
+     * where they hold `role` or higher (a `tenant in [...]` constraint).
+     */
+    const accessAtLeast = (role, { platformRole, field = f.tenant } = {}) => ({ req }) => {
+        if (platformRole && isPlatform(req.user, platformRole))
+            return true;
+        const ids = sites(req.user, role);
+        return ids.length ? { [field]: { in: ids } } : false;
+    };
+    return {
+        ladder,
+        addOns,
+        platform,
+        fields: f,
+        /** Every per-site role value (ladder and add-ons). */
+        values,
+        rank,
+        atLeast,
+        isPlatform,
+        sites,
+        has,
+        highest,
+        label,
+        options,
+        platformOptions,
+        access: { atLeast: accessAtLeast },
+    };
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@extantape/payload-plugin-roles",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Roles for Payload: per-site role ladders (Member, Author, Curator, Administrator) for multi-tenant sites, plus add-on and platform roles, per-site role names and access helpers.",
+  "homepage": "https://github.com/ExtantApe/payload-plugin-roles#readme",
+  "bugs": {
+    "url": "https://github.com/ExtantApe/payload-plugin-roles/issues"
+  },
+  "keywords": [
+    "payload",
+    "payload-plugin",
+    "payloadcms",
+    "roles",
+    "rbac",
+    "multi-tenant",
+    "access-control",
+    "permissions"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExtantApe/payload-plugin-roles.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.9"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "payload": "^3.80.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "payload": "3.92.1",
+    "typescript": "^5.9.0",
+    "vitest": "^5.1.0"
+  }
+}