@whatworks/payload-rbac 0.1.0

package/dist/plugin.js

@@ -0,0 +1,255 @@
+import { FULL_ACCESS, permissionFor } from "./permissions.js";
+import { collectionActions, globalActions, pluginKey } from "./shared.js";
+import { createRbacAccess } from "./access/rbacAccess.js";
+import { anyUserHoldsRole, findFullAccessRoleIds, warnIfAdminRoleUnheld } from "./utilities/fullAccessHolders.js";
+import { createRolesFieldAccess } from "./access/rolesFieldAccess.js";
+import { createRolesCollection } from "./collections/createRolesCollection.js";
+import { createRolesField } from "./fields/createRolesField.js";
+import { createAssignFirstUserRoleHook } from "./hooks/assignFirstUserRole.js";
+import { createProtectRolesFieldHook } from "./hooks/protectRolesField.js";
+import { createProtectCredentialsHook } from "./hooks/protectCredentials.js";
+import { createProtectedRolesChangeHook, createProtectedRolesDeleteHook } from "./hooks/protectedRoles.js";
+import { createProtectLastAdminChangeHook, createProtectLastAdminDeleteHook } from "./hooks/protectLastAdmin.js";
+import { createProtectRolesCollectionHook } from "./hooks/protectRolesCollection.js";
+import { seedPredefinedRoles } from "./seed.js";
+import { entityLabel } from "./utilities/entityLabel.js";
+
+//#region src/plugin.ts
+const createSelector = (selection) => {
+	if (selection === void 0 || selection === true) return () => true;
+	if (Array.isArray(selection)) {
+		const included = new Set(selection);
+		return (slug) => included.has(slug);
+	}
+	const excluded = new Set(selection.exclude);
+	return (slug) => !excluded.has(slug);
+};
+const hasNamedField = (fields, name) => {
+	return fields.some((field) => "name" in field && field.name === name);
+};
+const resolveUserCollections = (config, pluginConfig) => {
+	if (pluginConfig.userCollections?.length) return pluginConfig.userCollections;
+	const authSlugs = (config.collections ?? []).filter((collection) => Boolean(collection.auth)).map((collection) => collection.slug);
+	if (authSlugs.length) return authSlugs;
+	return [config.admin?.user ?? "users"];
+};
+const rbacPlugin = (pluginConfig = {}) => {
+	return (incomingConfig) => {
+		const config = { ...incomingConfig };
+		if (pluginConfig.enabled === false) return config;
+		const rolesCollectionSlug = pluginConfig.rolesCollection?.slug ?? "roles";
+		const rolesFieldName = pluginConfig.rolesField?.name ?? "roles";
+		const preventEscalation = pluginConfig.preventPrivilegeEscalation !== false;
+		const ownAccountActions = pluginConfig.ownAccountAccess === false ? [] : pluginConfig.ownAccountAccess ?? ["read", "update"];
+		const adminRole = !pluginConfig.adminRole || typeof pluginConfig.adminRole === "string" ? { name: pluginConfig.adminRole || void 0 } : pluginConfig.adminRole;
+		if (adminRole.name && (pluginConfig.roles ?? []).some((role) => role.name === adminRole.name)) throw new Error(`[payload-rbac] "${adminRole.name}" is the adminRole and is defined by the plugin — it always has permissions ['*'] and is protected. Remove it from roles, or use a different name.`);
+		const predefinedRoles = [...adminRole.name ? [{
+			name: adminRole.name,
+			credentialChanges: "self",
+			description: adminRole.description ?? "Full access to everything.",
+			permissions: [FULL_ACCESS],
+			protected: true
+		}] : [], ...(pluginConfig.roles ?? []).map((role) => ({
+			...role,
+			protected: role.protected ?? false
+		}))];
+		const protectedRoles = predefinedRoles.filter((role) => role.protected);
+		const protectedRoleNames = protectedRoles.map((role) => role.name);
+		const selfOnlyCredentialRoleNames = predefinedRoles.filter((role) => role.credentialChanges === "self").map((role) => role.name);
+		if ((config.collections ?? []).some((collection) => collection.slug === rolesCollectionSlug)) throw new Error(`[payload-rbac] A collection with the slug "${rolesCollectionSlug}" already exists. Pass rolesCollection.slug to use a different slug for the roles collection.`);
+		const shouldControlCollection = createSelector(pluginConfig.collections);
+		const shouldControlGlobal = createSelector(pluginConfig.globals);
+		const userCollections = resolveUserCollections(config, pluginConfig);
+		const adminUserCollection = config.admin?.user ?? "users";
+		const matrixRows = [
+			...(config.collections ?? []).filter((collection) => shouldControlCollection(collection.slug)).map((collection) => ({
+				slug: collection.slug,
+				actions: collectionActions,
+				entity: "collection",
+				label: entityLabel(collection.labels?.plural, collection.slug)
+			})),
+			{
+				slug: rolesCollectionSlug,
+				actions: collectionActions,
+				entity: "collection",
+				label: "Roles"
+			},
+			...(config.globals ?? []).filter((global) => shouldControlGlobal(global.slug)).map((global) => ({
+				slug: global.slug,
+				actions: globalActions,
+				entity: "global",
+				label: entityLabel(global.label, global.slug)
+			}))
+		];
+		const validPermissions = new Set([FULL_ACCESS, ...matrixRows.flatMap((row) => row.actions.map((action) => permissionFor(row.slug, action)))]);
+		for (const role of predefinedRoles) for (const permission of role.permissions) if (!validPermissions.has(permission)) throw new Error(`[payload-rbac] Predefined role "${role.name}" grants unknown permission "${permission}". Permissions must be '*' or '<slug>:<action>' for a controlled collection (create/read/update/delete) or global (read/update).`);
+		const withCollectionAccess = (collection) => {
+			const access = { ...collection.access };
+			for (const action of collectionActions) if (access[action] === void 0) access[action] = createRbacAccess({
+				slug: collection.slug,
+				action,
+				ownAccountActions
+			});
+			if (access.readVersions === void 0) access.readVersions = createRbacAccess({
+				slug: collection.slug,
+				action: "read"
+			});
+			if (access.unlock === void 0) access.unlock = createRbacAccess({
+				slug: collection.slug,
+				action: "update"
+			});
+			return {
+				...collection,
+				access
+			};
+		};
+		const withGlobalAccess = (global) => {
+			const access = { ...global.access };
+			for (const action of globalActions) if (access[action] === void 0) access[action] = createRbacAccess({
+				slug: global.slug,
+				action
+			});
+			if (access.readVersions === void 0) access.readVersions = createRbacAccess({
+				slug: global.slug,
+				action: "read"
+			});
+			return {
+				...global,
+				access
+			};
+		};
+		const rolesFieldAccess = createRolesFieldAccess({
+			rolesCollectionSlug,
+			rolesFieldName,
+			...adminRole.name ? { breakGlass: { userCollections } } : {}
+		});
+		const withRolesField = (collection) => {
+			const fields = hasNamedField(collection.fields, rolesFieldName) ? collection.fields : [...collection.fields, createRolesField({
+				name: rolesFieldName,
+				access: {
+					create: rolesFieldAccess,
+					update: rolesFieldAccess
+				},
+				override: pluginConfig.rolesField?.override,
+				rolesCollectionSlug
+			})];
+			const beforeChange = [...collection.hooks?.beforeChange ?? []];
+			const beforeDelete = [...collection.hooks?.beforeDelete ?? []];
+			if (selfOnlyCredentialRoleNames.length > 0) beforeChange.push(createProtectCredentialsHook({
+				rolesCollectionSlug,
+				rolesFieldName,
+				selfOnlyRoleNames: selfOnlyCredentialRoleNames,
+				userCollectionSlug: collection.slug
+			}));
+			if (preventEscalation || adminRole.name) beforeChange.push(createProtectRolesFieldHook({
+				preventEscalation,
+				rolesCollectionSlug,
+				rolesFieldName,
+				...adminRole.name ? {
+					breakGlass: {
+						adminRoleName: adminRole.name,
+						userCollections
+					},
+					holderOnly: {
+						roleNames: [adminRole.name],
+						userCollections
+					}
+				} : {}
+			}));
+			if (adminRole.name) {
+				const protectLastAdminArgs = {
+					adminRoleName: adminRole.name,
+					rolesCollectionSlug,
+					rolesFieldName,
+					userCollections,
+					userCollectionSlug: collection.slug
+				};
+				beforeChange.push(createProtectLastAdminChangeHook(protectLastAdminArgs));
+				beforeDelete.push(createProtectLastAdminDeleteHook(protectLastAdminArgs));
+			}
+			if (adminRole.name && collection.slug === adminUserCollection) beforeChange.push(createAssignFirstUserRoleHook({
+				firstUserRole: adminRole.name,
+				rolesCollectionSlug,
+				rolesFieldName
+			}));
+			return {
+				...collection,
+				fields,
+				hooks: {
+					...collection.hooks,
+					beforeChange,
+					beforeDelete
+				}
+			};
+		};
+		const rolesAccess = {};
+		for (const action of collectionActions) rolesAccess[action] = createRbacAccess({
+			slug: rolesCollectionSlug,
+			action
+		});
+		if (adminRole.name) {
+			const baseRead = rolesAccess.read;
+			rolesAccess.read = async (args) => {
+				const base = await baseRead?.(args);
+				if (base || !args.req.user) return base ?? false;
+				const fullAccessRoleIds = await findFullAccessRoleIds(args.req.payload, rolesCollectionSlug);
+				return !await anyUserHoldsRole(args.req.payload, fullAccessRoleIds, {
+					rolesFieldName,
+					userCollections
+				});
+			};
+		}
+		const rolesBeforeChange = [];
+		if (protectedRoles.length > 0) rolesBeforeChange.push(createProtectedRolesChangeHook({ protectedRoles }));
+		if (preventEscalation) rolesBeforeChange.push(createProtectRolesCollectionHook({ protectedRoleNames }));
+		const rolesHooks = {
+			...rolesBeforeChange.length > 0 ? { beforeChange: rolesBeforeChange } : {},
+			...protectedRoles.length > 0 ? { beforeDelete: [createProtectedRolesDeleteHook({
+				protectedRoleNames,
+				rolesCollectionSlug
+			})] } : {}
+		};
+		const rolesCollection = createRolesCollection({
+			slug: rolesCollectionSlug,
+			access: rolesAccess,
+			hooks: Object.keys(rolesHooks).length > 0 ? rolesHooks : void 0,
+			matrixRows,
+			override: pluginConfig.rolesCollection?.override,
+			protectedRoleNames
+		});
+		config.collections = [...(config.collections ?? []).map((collection) => {
+			let result = shouldControlCollection(collection.slug) ? withCollectionAccess(collection) : collection;
+			if (userCollections.includes(collection.slug)) result = withRolesField(result);
+			return result;
+		}), rolesCollection];
+		config.globals = (config.globals ?? []).map((global) => shouldControlGlobal(global.slug) ? withGlobalAccess(global) : global);
+		const incomingOnInit = config.onInit;
+		config.onInit = async (payload) => {
+			if (predefinedRoles.length > 0) await seedPredefinedRoles(payload, {
+				roles: predefinedRoles,
+				rolesCollectionSlug
+			});
+			if (adminRole.name) await warnIfAdminRoleUnheld(payload, {
+				adminRoleName: adminRole.name,
+				rolesCollectionSlug,
+				rolesFieldName,
+				userCollections
+			});
+			await incomingOnInit?.(payload);
+		};
+		const customConfig = {
+			rolesCollectionSlug,
+			rolesFieldName,
+			userCollections
+		};
+		config.custom = {
+			...config.custom,
+			[pluginKey]: customConfig
+		};
+		return config;
+	};
+};
+
+//#endregion
+export { rbacPlugin };
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","names":["adminRole: { description?: string; name?: string }","matrixRows: MatrixRow[]","rolesAccess: CollectionConfig['access']","rolesBeforeChange: NonNullable<CollectionConfig['hooks']>['beforeChange']","rolesHooks: CollectionConfig['hooks']","customConfig: RbacCustomConfig"],"sources":["../src/plugin.ts"],"sourcesContent":["import type { CollectionConfig, Config, Field, GlobalConfig, Plugin } from 'payload'\n\nimport type { MatrixRow, RbacCustomConfig } from './shared.js'\nimport type { RbacEntitySelection, RbacPluginConfig } from './types.js'\n\nimport { createRbacAccess } from './access/rbacAccess.js'\nimport { createRolesFieldAccess } from './access/rolesFieldAccess.js'\nimport { createRolesCollection } from './collections/createRolesCollection.js'\nimport { createRolesField } from './fields/createRolesField.js'\nimport { createAssignFirstUserRoleHook } from './hooks/assignFirstUserRole.js'\nimport { createProtectCredentialsHook } from './hooks/protectCredentials.js'\nimport {\n  createProtectedRolesChangeHook,\n  createProtectedRolesDeleteHook,\n} from './hooks/protectedRoles.js'\nimport {\n  createProtectLastAdminChangeHook,\n  createProtectLastAdminDeleteHook,\n} from './hooks/protectLastAdmin.js'\nimport { createProtectRolesCollectionHook } from './hooks/protectRolesCollection.js'\nimport { createProtectRolesFieldHook } from './hooks/protectRolesField.js'\nimport { FULL_ACCESS, permissionFor } from './permissions.js'\nimport { seedPredefinedRoles } from './seed.js'\nimport { collectionActions, globalActions, pluginKey } from './shared.js'\nimport { entityLabel } from './utilities/entityLabel.js'\nimport {\n  anyUserHoldsRole,\n  findFullAccessRoleIds,\n  warnIfAdminRoleUnheld,\n} from './utilities/fullAccessHolders.js'\n\nconst createSelector = <TSlug extends string>(\n  selection: RbacEntitySelection<TSlug> | undefined,\n): ((slug: string) => boolean) => {\n  if (selection === undefined || selection === true) {\n    return () => true\n  }\n  if (Array.isArray(selection)) {\n    const included = new Set<string>(selection)\n    return (slug) => included.has(slug)\n  }\n  const excluded = new Set<string>(selection.exclude)\n  return (slug) => !excluded.has(slug)\n}\n\nconst hasNamedField = (fields: Field[], name: string): boolean => {\n  return fields.some((field) => 'name' in field && field.name === name)\n}\n\nconst resolveUserCollections = (config: Config, pluginConfig: RbacPluginConfig): string[] => {\n  if (pluginConfig.userCollections?.length) {\n    return pluginConfig.userCollections\n  }\n  const authSlugs = (config.collections ?? [])\n    .filter((collection) => Boolean(collection.auth))\n    .map((collection) => collection.slug)\n  if (authSlugs.length) {\n    return authSlugs\n  }\n  return [config.admin?.user ?? 'users']\n}\n\nexport const rbacPlugin = (pluginConfig: RbacPluginConfig = {}): Plugin => {\n  return (incomingConfig: Config): Config => {\n    const config = { ...incomingConfig }\n\n    if (pluginConfig.enabled === false) {\n      return config\n    }\n\n    const rolesCollectionSlug = pluginConfig.rolesCollection?.slug ?? 'roles'\n    const rolesFieldName = pluginConfig.rolesField?.name ?? 'roles'\n    const preventEscalation = pluginConfig.preventPrivilegeEscalation !== false\n    const ownAccountActions =\n      pluginConfig.ownAccountAccess === false\n        ? []\n        : (pluginConfig.ownAccountAccess ?? ['read', 'update'])\n    const adminRole: { description?: string; name?: string } =\n      !pluginConfig.adminRole || typeof pluginConfig.adminRole === 'string'\n        ? { name: pluginConfig.adminRole || undefined }\n        : pluginConfig.adminRole\n\n    if (adminRole.name && (pluginConfig.roles ?? []).some((role) => role.name === adminRole.name)) {\n      throw new Error(\n        `[payload-rbac] \"${adminRole.name}\" is the adminRole and is defined by the plugin — ` +\n          `it always has permissions ['*'] and is protected. Remove it from roles, or use a different name.`,\n      )\n    }\n\n    // The admin role is always full-access and protected: an unprotected one can\n    // be downgraded irreversibly — once nobody holds a permission, the escalation\n    // guard blocks everyone from granting it back. Its credentials are always\n    // self-only: with `users:update` enough to set an administrator's password\n    // or email, any admin account could be taken over by another.\n    const predefinedRoles = [\n      ...(adminRole.name\n        ? [\n            {\n              name: adminRole.name,\n              credentialChanges: 'self' as const,\n              description: adminRole.description ?? 'Full access to everything.',\n              permissions: [FULL_ACCESS],\n              protected: true,\n            },\n          ]\n        : []),\n      ...(pluginConfig.roles ?? []).map((role) => ({\n        ...role,\n        protected: role.protected ?? false,\n      })),\n    ]\n    const protectedRoles = predefinedRoles.filter((role) => role.protected)\n    const protectedRoleNames = protectedRoles.map((role) => role.name)\n    const selfOnlyCredentialRoleNames = predefinedRoles\n      .filter((role) => role.credentialChanges === 'self')\n      .map((role) => role.name)\n\n    if ((config.collections ?? []).some((collection) => collection.slug === rolesCollectionSlug)) {\n      throw new Error(\n        `[payload-rbac] A collection with the slug \"${rolesCollectionSlug}\" already exists. ` +\n          `Pass rolesCollection.slug to use a different slug for the roles collection.`,\n      )\n    }\n\n    const shouldControlCollection = createSelector(pluginConfig.collections)\n    const shouldControlGlobal = createSelector(pluginConfig.globals)\n    const userCollections = resolveUserCollections(config, pluginConfig)\n    const adminUserCollection = config.admin?.user ?? 'users'\n\n    const matrixRows: MatrixRow[] = [\n      ...(config.collections ?? [])\n        .filter((collection) => shouldControlCollection(collection.slug))\n        .map((collection) => ({\n          slug: collection.slug,\n          actions: collectionActions,\n          entity: 'collection' as const,\n          label: entityLabel(collection.labels?.plural, collection.slug),\n        })),\n      {\n        slug: rolesCollectionSlug,\n        actions: collectionActions,\n        entity: 'collection' as const,\n        label: 'Roles',\n      },\n      ...(config.globals ?? [])\n        .filter((global) => shouldControlGlobal(global.slug))\n        .map((global) => ({\n          slug: global.slug,\n          actions: globalActions,\n          entity: 'global' as const,\n          label: entityLabel(global.label, global.slug),\n        })),\n    ]\n\n    const validPermissions = new Set<string>([\n      FULL_ACCESS,\n      ...matrixRows.flatMap((row) => row.actions.map((action) => permissionFor(row.slug, action))),\n    ])\n    for (const role of predefinedRoles) {\n      for (const permission of role.permissions) {\n        if (!validPermissions.has(permission)) {\n          throw new Error(\n            `[payload-rbac] Predefined role \"${role.name}\" grants unknown permission \"${permission}\". ` +\n              `Permissions must be '*' or '<slug>:<action>' for a controlled collection ` +\n              `(create/read/update/delete) or global (read/update).`,\n          )\n        }\n      }\n    }\n\n    // Explicit access defined on a collection wins for that operation; the plugin\n    // only fills the gaps. Compose `requirePermission` into your own access\n    // functions to combine both.\n    const withCollectionAccess = (collection: CollectionConfig): CollectionConfig => {\n      const access = { ...collection.access }\n      for (const action of collectionActions) {\n        if (access[action] === undefined) {\n          access[action] = createRbacAccess({ slug: collection.slug, action, ownAccountActions })\n        }\n      }\n      if (access.readVersions === undefined) {\n        access.readVersions = createRbacAccess({ slug: collection.slug, action: 'read' })\n      }\n      if (access.unlock === undefined) {\n        access.unlock = createRbacAccess({ slug: collection.slug, action: 'update' })\n      }\n      return { ...collection, access }\n    }\n\n    const withGlobalAccess = (global: GlobalConfig): GlobalConfig => {\n      const access = { ...global.access }\n      for (const action of globalActions) {\n        if (access[action] === undefined) {\n          access[action] = createRbacAccess({ slug: global.slug, action })\n        }\n      }\n      if (access.readVersions === undefined) {\n        access.readVersions = createRbacAccess({ slug: global.slug, action: 'read' })\n      }\n      return { ...global, access }\n    }\n\n    // Changing role membership requires `roles:update`. Field-level access is\n    // what makes the admin panel render the field read-only for everyone else,\n    // so a user can never accidentally remove their own roles — a hook would\n    // only reject the save after the fact. While no administrator exists the\n    // field stays writable, or the break-glass self-claim could never reach the\n    // escalation guard that vets it.\n    const rolesFieldAccess = createRolesFieldAccess({\n      rolesCollectionSlug,\n      rolesFieldName,\n      ...(adminRole.name ? { breakGlass: { userCollections } } : {}),\n    })\n\n    const withRolesField = (collection: CollectionConfig): CollectionConfig => {\n      // If the collection already defines a field with this name, leave the field\n      // entirely user-managed — the guard hooks still apply to it, but the\n      // `roles:update` field gate does not.\n      const fields = hasNamedField(collection.fields, rolesFieldName)\n        ? collection.fields\n        : [\n            ...collection.fields,\n            createRolesField({\n              name: rolesFieldName,\n              access: { create: rolesFieldAccess, update: rolesFieldAccess },\n              override: pluginConfig.rolesField?.override,\n              rolesCollectionSlug,\n            }),\n          ]\n\n      const beforeChange = [...(collection.hooks?.beforeChange ?? [])]\n      const beforeDelete = [...(collection.hooks?.beforeDelete ?? [])]\n      if (selfOnlyCredentialRoleNames.length > 0) {\n        beforeChange.push(\n          createProtectCredentialsHook({\n            rolesCollectionSlug,\n            rolesFieldName,\n            selfOnlyRoleNames: selfOnlyCredentialRoleNames,\n            userCollectionSlug: collection.slug,\n          }),\n        )\n      }\n      if (preventEscalation || adminRole.name) {\n        beforeChange.push(\n          createProtectRolesFieldHook({\n            preventEscalation,\n            rolesCollectionSlug,\n            rolesFieldName,\n            ...(adminRole.name\n              ? {\n                  // Break-glass: with no administrator left (database-level\n                  // damage), denying a self-claim would leave the system\n                  // unrecoverable.\n                  breakGlass: { adminRoleName: adminRole.name, userCollections },\n                  // Only holders may grant the admin tier — a client\n                  // administrator holding '*' through another role must not be\n                  // able to join it on their own.\n                  holderOnly: { roleNames: [adminRole.name], userCollections },\n                }\n              : {}),\n          }),\n        )\n      }\n      if (adminRole.name) {\n        // There must always be at least one user holding the admin role: with\n        // nobody left holding '*', the escalation guard would block every path\n        // to assigning it again.\n        const protectLastAdminArgs = {\n          adminRoleName: adminRole.name,\n          rolesCollectionSlug,\n          rolesFieldName,\n          userCollections,\n          userCollectionSlug: collection.slug,\n        }\n        beforeChange.push(createProtectLastAdminChangeHook(protectLastAdminArgs))\n        beforeDelete.push(createProtectLastAdminDeleteHook(protectLastAdminArgs))\n      }\n      if (adminRole.name && collection.slug === adminUserCollection) {\n        beforeChange.push(\n          createAssignFirstUserRoleHook({\n            firstUserRole: adminRole.name,\n            rolesCollectionSlug,\n            rolesFieldName,\n          }),\n        )\n      }\n\n      return { ...collection, fields, hooks: { ...collection.hooks, beforeChange, beforeDelete } }\n    }\n\n    const rolesAccess: CollectionConfig['access'] = {}\n    for (const action of collectionActions) {\n      rolesAccess[action] = createRbacAccess({ slug: rolesCollectionSlug, action })\n    }\n    if (adminRole.name) {\n      const baseRead = rolesAccess.read\n      // Break-glass visibility: while no user holds full access, signed-in users\n      // may read roles — the account page must be able to list the admin role\n      // for the self-claim, and nothing here is sensitive.\n      rolesAccess.read = async (args) => {\n        const base = await baseRead?.(args)\n        if (base || !args.req.user) {\n          return base ?? false\n        }\n        const fullAccessRoleIds = await findFullAccessRoleIds(args.req.payload, rolesCollectionSlug)\n        return !(await anyUserHoldsRole(args.req.payload, fullAccessRoleIds, {\n          rolesFieldName,\n          userCollections,\n        }))\n      }\n    }\n\n    // The protected-role guard runs before the escalation guard so its clearer\n    // error wins, and it applies even when preventPrivilegeEscalation is off —\n    // the two solve different problems.\n    const rolesBeforeChange: NonNullable<CollectionConfig['hooks']>['beforeChange'] = []\n    if (protectedRoles.length > 0) {\n      rolesBeforeChange.push(createProtectedRolesChangeHook({ protectedRoles }))\n    }\n    if (preventEscalation) {\n      rolesBeforeChange.push(createProtectRolesCollectionHook({ protectedRoleNames }))\n    }\n    const rolesHooks: CollectionConfig['hooks'] = {\n      ...(rolesBeforeChange.length > 0 ? { beforeChange: rolesBeforeChange } : {}),\n      ...(protectedRoles.length > 0\n        ? {\n            beforeDelete: [\n              createProtectedRolesDeleteHook({ protectedRoleNames, rolesCollectionSlug }),\n            ],\n          }\n        : {}),\n    }\n\n    const rolesCollection = createRolesCollection({\n      slug: rolesCollectionSlug,\n      access: rolesAccess,\n      hooks: Object.keys(rolesHooks).length > 0 ? rolesHooks : undefined,\n      matrixRows,\n      override: pluginConfig.rolesCollection?.override,\n      protectedRoleNames,\n    })\n\n    config.collections = [\n      ...(config.collections ?? []).map((collection) => {\n        let result = shouldControlCollection(collection.slug)\n          ? withCollectionAccess(collection)\n          : collection\n        if (userCollections.includes(collection.slug)) {\n          result = withRolesField(result)\n        }\n        return result\n      }),\n      rolesCollection,\n    ]\n\n    config.globals = (config.globals ?? []).map((global) =>\n      shouldControlGlobal(global.slug) ? withGlobalAccess(global) : global,\n    )\n\n    const incomingOnInit = config.onInit\n    config.onInit = async (payload) => {\n      if (predefinedRoles.length > 0) {\n        await seedPredefinedRoles(payload, { roles: predefinedRoles, rolesCollectionSlug })\n      }\n      if (adminRole.name) {\n        await warnIfAdminRoleUnheld(payload, {\n          adminRoleName: adminRole.name,\n          rolesCollectionSlug,\n          rolesFieldName,\n          userCollections,\n        })\n      }\n      await incomingOnInit?.(payload)\n    }\n\n    const customConfig: RbacCustomConfig = {\n      rolesCollectionSlug,\n      rolesFieldName,\n      userCollections,\n    }\n\n    config.custom = {\n      ...config.custom,\n      [pluginKey]: customConfig,\n    }\n\n    return config\n  }\n}\n"],"mappings":"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"}

package/dist/seed.d.ts

@@ -0,0 +1,24 @@
+import { PredefinedRole } from "./types.js";
+import { Payload } from "payload";
+
+//#region src/seed.d.ts
+type SeedPredefinedRolesArgs = {
+  roles: PredefinedRole[];
+  rolesCollectionSlug: string;
+};
+/**
+ * Creates each predefined role that does not exist yet, keyed by `name`. Existing
+ * roles are never updated or overwritten — the database is the source of truth once
+ * a role exists, so admin edits survive restarts — except `protected` roles, where
+ * code is the source of truth: drifted permissions are restored on every init, so a
+ * protected full-access role recovers even from direct database edits. Runs in
+ * `onInit` before any `onInit` defined on the config, so init seeds can rely on the
+ * roles being present.
+ */
+declare const seedPredefinedRoles: (payload: Payload, {
+  roles,
+  rolesCollectionSlug
+}: SeedPredefinedRolesArgs) => Promise<void>;
+//#endregion
+export { SeedPredefinedRolesArgs, seedPredefinedRoles };
+//# sourceMappingURL=seed.d.ts.map

package/dist/seed.js

@@ -0,0 +1,47 @@
+import { samePermissions } from "./permissions.js";
+
+//#region src/seed.ts
+/**
+* Creates each predefined role that does not exist yet, keyed by `name`. Existing
+* roles are never updated or overwritten — the database is the source of truth once
+* a role exists, so admin edits survive restarts — except `protected` roles, where
+* code is the source of truth: drifted permissions are restored on every init, so a
+* protected full-access role recovers even from direct database edits. Runs in
+* `onInit` before any `onInit` defined on the config, so init seeds can rely on the
+* roles being present.
+*/
+const seedPredefinedRoles = async (payload, { roles, rolesCollectionSlug }) => {
+	for (const role of roles) {
+		const existingDoc = (await payload.find({
+			collection: rolesCollectionSlug,
+			depth: 0,
+			limit: 1,
+			where: { name: { equals: role.name } }
+		})).docs[0];
+		if (existingDoc) {
+			if (role.protected && !samePermissions(existingDoc.permissions, role.permissions)) {
+				await payload.update({
+					id: existingDoc.id,
+					collection: rolesCollectionSlug,
+					data: { permissions: role.permissions },
+					depth: 0
+				});
+				payload.logger.info(`[payload-rbac] Restored permissions of protected role "${role.name}"`);
+			}
+			continue;
+		}
+		await payload.create({
+			collection: rolesCollectionSlug,
+			data: {
+				name: role.name,
+				description: role.description,
+				permissions: role.permissions
+			}
+		});
+		payload.logger.info(`[payload-rbac] Seeded role "${role.name}"`);
+	}
+};
+
+//#endregion
+export { seedPredefinedRoles };
+//# sourceMappingURL=seed.js.map

package/dist/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","names":[],"sources":["../src/seed.ts"],"sourcesContent":["import type { Payload } from 'payload'\n\nimport type { PredefinedRole } from './types.js'\n\nimport { samePermissions } from './permissions.js'\n\nexport type SeedPredefinedRolesArgs = {\n  roles: PredefinedRole[]\n  rolesCollectionSlug: string\n}\n\n/**\n * Creates each predefined role that does not exist yet, keyed by `name`. Existing\n * roles are never updated or overwritten — the database is the source of truth once\n * a role exists, so admin edits survive restarts — except `protected` roles, where\n * code is the source of truth: drifted permissions are restored on every init, so a\n * protected full-access role recovers even from direct database edits. Runs in\n * `onInit` before any `onInit` defined on the config, so init seeds can rely on the\n * roles being present.\n */\nexport const seedPredefinedRoles = async (\n  payload: Payload,\n  { roles, rolesCollectionSlug }: SeedPredefinedRolesArgs,\n): Promise<void> => {\n  for (const role of roles) {\n    const existing = await payload.find({\n      collection: rolesCollectionSlug,\n      depth: 0,\n      limit: 1,\n      where: { name: { equals: role.name } },\n    })\n    const existingDoc = existing.docs[0] as\n      | { id: number | string; permissions?: unknown }\n      | undefined\n    if (existingDoc) {\n      if (role.protected && !samePermissions(existingDoc.permissions, role.permissions)) {\n        await payload.update({\n          id: existingDoc.id,\n          collection: rolesCollectionSlug,\n          data: { permissions: role.permissions },\n          depth: 0,\n        })\n        payload.logger.info(`[payload-rbac] Restored permissions of protected role \"${role.name}\"`)\n      }\n      continue\n    }\n\n    await payload.create({\n      collection: rolesCollectionSlug,\n      data: {\n        name: role.name,\n        description: role.description,\n        permissions: role.permissions,\n      },\n    })\n    payload.logger.info(`[payload-rbac] Seeded role \"${role.name}\"`)\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAoBA,MAAa,sBAAsB,OACjC,SACA,EAAE,OAAO,0BACS;AAClB,MAAK,MAAM,QAAQ,OAAO;EAOxB,MAAM,eANW,MAAM,QAAQ,KAAK;GAClC,YAAY;GACZ,OAAO;GACP,OAAO;GACP,OAAO,EAAE,MAAM,EAAE,QAAQ,KAAK,MAAM,EAAE;GACvC,CAAC,EAC2B,KAAK;AAGlC,MAAI,aAAa;AACf,OAAI,KAAK,aAAa,CAAC,gBAAgB,YAAY,aAAa,KAAK,YAAY,EAAE;AACjF,UAAM,QAAQ,OAAO;KACnB,IAAI,YAAY;KAChB,YAAY;KACZ,MAAM,EAAE,aAAa,KAAK,aAAa;KACvC,OAAO;KACR,CAAC;AACF,YAAQ,OAAO,KAAK,0DAA0D,KAAK,KAAK,GAAG;;AAE7F;;AAGF,QAAM,QAAQ,OAAO;GACnB,YAAY;GACZ,MAAM;IACJ,MAAM,KAAK;IACX,aAAa,KAAK;IAClB,aAAa,KAAK;IACnB;GACF,CAAC;AACF,UAAQ,OAAO,KAAK,+BAA+B,KAAK,KAAK,GAAG"}

package/dist/shared.d.ts

@@ -0,0 +1,38 @@
+import { Config } from "payload";
+
+//#region src/shared.d.ts
+declare const pluginKey = "@whatworks/payload-rbac";
+declare const permissionsMatrixFieldPath = "@whatworks/payload-rbac/client#PermissionsMatrixField";
+/** Actions available on a collection. */
+declare const collectionActions: readonly ["create", "read", "update", "delete"];
+/** Actions available on a global. */
+declare const globalActions: readonly ["read", "update"];
+type RbacAction = (typeof collectionActions)[number];
+/**
+ * One row of the permissions matrix shown on a role document — a collection or
+ * global together with the actions that can be granted on it. Serialized into the
+ * matrix field component's `clientProps`, so it must stay JSON-safe.
+ */
+type MatrixRow = {
+  actions: readonly RbacAction[];
+  entity: 'collection' | 'global';
+  label: string;
+  slug: string;
+};
+/**
+ * Plugin state stored on `config.custom[pluginKey]` so exported helpers
+ * (`getUserPermissions`, `hasPermission`) can find the roles collection and the
+ * roles field without access to the plugin closure. The root `custom` key is a
+ * server-only config property, stripped from the client config.
+ */
+type RbacCustomConfig = {
+  rolesCollectionSlug: string;
+  rolesFieldName: string;
+  userCollections: string[];
+};
+declare const getRbacCustomConfig: (config: {
+  custom?: Record<string, unknown>;
+} | Config) => RbacCustomConfig | undefined;
+//#endregion
+export { MatrixRow, RbacAction, RbacCustomConfig, collectionActions, getRbacCustomConfig, globalActions, permissionsMatrixFieldPath, pluginKey };
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.js

@@ -0,0 +1,19 @@
+//#region src/shared.ts
+const pluginKey = "@whatworks/payload-rbac";
+const permissionsMatrixFieldPath = `${pluginKey}/client#PermissionsMatrixField`;
+/** Actions available on a collection. */
+const collectionActions = [
+	"create",
+	"read",
+	"update",
+	"delete"
+];
+/** Actions available on a global. */
+const globalActions = ["read", "update"];
+const getRbacCustomConfig = (config) => {
+	return config.custom?.[pluginKey];
+};
+
+//#endregion
+export { collectionActions, getRbacCustomConfig, globalActions, permissionsMatrixFieldPath, pluginKey };
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","names":[],"sources":["../src/shared.ts"],"sourcesContent":["import type { Config } from 'payload'\n\nexport const pluginKey = '@whatworks/payload-rbac'\n\nexport const permissionsMatrixFieldPath = `${pluginKey}/client#PermissionsMatrixField`\n\n/** Actions available on a collection. */\nexport const collectionActions = ['create', 'read', 'update', 'delete'] as const\n\n/** Actions available on a global. */\nexport const globalActions = ['read', 'update'] as const\n\nexport type RbacAction = (typeof collectionActions)[number]\n\n/**\n * One row of the permissions matrix shown on a role document — a collection or\n * global together with the actions that can be granted on it. Serialized into the\n * matrix field component's `clientProps`, so it must stay JSON-safe.\n */\nexport type MatrixRow = {\n  actions: readonly RbacAction[]\n  entity: 'collection' | 'global'\n  label: string\n  slug: string\n}\n\n/**\n * Plugin state stored on `config.custom[pluginKey]` so exported helpers\n * (`getUserPermissions`, `hasPermission`) can find the roles collection and the\n * roles field without access to the plugin closure. The root `custom` key is a\n * server-only config property, stripped from the client config.\n */\nexport type RbacCustomConfig = {\n  rolesCollectionSlug: string\n  rolesFieldName: string\n  userCollections: string[]\n}\n\nexport const getRbacCustomConfig = (\n  config: { custom?: Record<string, unknown> } | Config,\n): RbacCustomConfig | undefined => {\n  return config.custom?.[pluginKey] as RbacCustomConfig | undefined\n}\n"],"mappings":";AAEA,MAAa,YAAY;AAEzB,MAAa,6BAA6B,GAAG,UAAU;;AAGvD,MAAa,oBAAoB;CAAC;CAAU;CAAQ;CAAU;CAAS;;AAGvE,MAAa,gBAAgB,CAAC,QAAQ,SAAS;AA4B/C,MAAa,uBACX,WACiC;AACjC,QAAO,OAAO,SAAS"}

package/dist/types.d.ts

@@ -0,0 +1,194 @@
+import { RbacAction } from "./shared.js";
+import { CollectionConfig, CollectionSlug, GlobalSlug, RelationshipField } from "payload";
+
+//#region src/types.d.ts
+
+/**
+ * A single grant. Either:
+ * - `'*'` — full access to every controlled collection and global, present and future.
+ * - `'<slug>:<action>'` — one action on one collection (`create`/`read`/`update`/`delete`)
+ *   or global (`read`/`update`), e.g. `'posts:update'`.
+ */
+type RbacPermission = string;
+/**
+ * A role defined in code. Seeded into the roles collection on init when no role
+ * with the same `name` exists yet; existing roles are never overwritten (unless
+ * `protected`), so database edits always win.
+ */
+type PredefinedRole = {
+  /**
+   * Who may change the credentials — password, email, and username — of users
+   * holding this role:
+   * - `'anyone'` — anyone with update access to the user (the default).
+   * - `'self'` — only the account owner. Everyone else gets a 403 regardless of
+   *   their permissions and should send a password-reset email instead. Email and
+   *   username are locked together with password deliberately: an editable email
+   *   plus the reset flow would take the account over anyway.
+   *
+   * The role defined by `adminRole` is always `'self'`. The protection follows
+   * the role name, so pair `'self'` with `protected: true` to prevent the role
+   * being renamed away from it.
+   *
+   * @default 'anyone'
+   */
+  credentialChanges?: 'anyone' | 'self';
+  description?: string;
+  /**
+   * Unique role name, used as the seeding key and shown as the document title in
+   * the admin panel, so human-friendly names like `'Editor'` are encouraged.
+   */
+  name: string;
+  permissions: RbacPermission[];
+  /**
+   * Locks the role to this code definition. A protected role cannot be renamed,
+   * have its permissions changed, or be deleted through the API — the only
+   * permissions write the API accepts is restoring this exact list — and drifted
+   * permissions are repaired on init. To change a protected role's permissions,
+   * change this definition and restart. The role defined by `adminRole` is always
+   * protected; use this to additionally lock other roles.
+   *
+   * @default false
+   */
+  protected?: boolean;
+};
+/**
+ * Which collections/globals the plugin applies to.
+ * - `true` — every entity in the config (the default).
+ * - `string[]` — only these slugs.
+ * - `{ exclude }` — every entity except these slugs.
+ */
+type RbacEntitySelection<TSlug extends string> = {
+  exclude: TSlug[];
+} | true | TSlug[];
+type RbacPluginConfig = {
+  /**
+   * The built-in administrator role, passed as a role name or `{ name, description }`.
+   * When set, the plugin defines a role with this name that always has full access
+   * (`permissions: ['*']`) and is always protected — it can never be downgraded,
+   * renamed, or deleted through the API, and drifted permissions are repaired on
+   * init — so there is always a role that can reach everything. It is auto-assigned
+   * to the first user created in the admin user collection (`admin.user`) by an
+   * unauthenticated request — the admin "create first user" screen or an init
+   * seed — so a fresh project never locks you out. Its holders' credentials are
+   * protected too: the role's `credentialChanges` is always `'self'`, so only
+   * each holder can change their own password, email, or username — another
+   * user with `users:update` cannot take the account over. And only holders can
+   * assign the role: full access through another role is not enough, so users
+   * below the admin tier can never join it on their own. (While nobody holds
+   * the role at all — a fresh rename, or the plugin newly added to an existing
+   * project — any user whose permissions cover it may step up; init logs a
+   * warning until someone does.) The plugin also guarantees at
+   * least one user always holds this role: removing it from — or deleting — the
+   * last holder is blocked. And should the system somehow end up with no
+   * administrator at all (the roles collection wiped at the database level, or
+   * this option renamed so a fresh role was seeded with no holders), any
+   * signed-in user may assign this role to themselves — the escalation guard
+   * permits exactly that write while no user holds full access, and init logs a
+   * warning describing the state. Do not also list it in `roles`; its definition
+   * is owned by the plugin.
+   *
+   * @default false
+   */
+  adminRole?: {
+    description?: string;
+    name: string;
+  } | false | string;
+  /**
+   * Which collections are access-controlled and appear in the permissions matrix.
+   *
+   * Defaults to `true`: every collection present in the config when the plugin runs —
+   * your own collections plus any added by plugins registered before this one, so
+   * register this plugin last. Payload's internal collections (`payload-preferences`,
+   * `payload-migrations`, `payload-locked-documents`, `payload-folders`, …) are created
+   * after plugins run and are never included. The roles collection itself is always
+   * controlled.
+   *
+   * @default true
+   */
+  collections?: RbacEntitySelection<CollectionSlug>;
+  /**
+   * Enables or disables the plugin.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Which globals are access-controlled and appear in the permissions matrix
+   * (`read`/`update`). Same semantics as `collections`.
+   *
+   * @default true
+   */
+  globals?: RbacEntitySelection<GlobalSlug>;
+  /**
+   * Let every user read/update their own user document even without the matching
+   * collection permission — the admin account view breaks without self-read. Set to
+   * `false` (or narrow to `['read']`) to disable. The roles field stays out of reach
+   * regardless: changing it requires the `roles:update` permission, so users cannot
+   * remove their own roles by accident.
+   *
+   * @default ['read', 'update']
+   */
+  ownAccountAccess?: Exclude<RbacAction, 'create' | 'delete'>[] | false;
+  /**
+   * Blocks users from granting what they do not hold themselves: assigning a role
+   * whose permissions their own roles don't cover, and adding permissions to a role
+   * (or creating one) beyond their own. Removals mirror additions on the user's own
+   * account: a role can only be removed from yourself when the roles you keep cover
+   * its permissions — otherwise you could never assign it back, and one save would
+   * have locked you out. Users with `'*'` can grant anything. Writes without a user
+   * (local API seeds, init scripts, the first-user registration) are not restricted.
+   *
+   * @default true
+   */
+  preventPrivilegeEscalation?: boolean;
+  /**
+   * Roles predefined in code, seeded on init when missing. Roles marked `protected`
+   * are additionally locked to their code definition. The `adminRole` is defined
+   * separately and must not be repeated here. See {@link PredefinedRole}.
+   */
+  roles?: PredefinedRole[];
+  /**
+   * The roles collection added by the plugin.
+   */
+  rolesCollection?: {
+    /**
+     * Escape hatch to customize the generated roles collection — labels, admin group,
+     * extra fields, additional hooks.
+     */
+    override?: (collection: CollectionConfig) => CollectionConfig;
+    /**
+     * Slug of the roles collection.
+     *
+     * @default 'roles'
+     */
+    slug?: string;
+  };
+  /**
+   * The roles field added to each user collection. The generated field carries
+   * field-level access requiring the `roles:update` permission to change it, so
+   * it renders read-only in the admin panel for everyone else and API writes
+   * touching it without the permission are silently ignored (Payload's
+   * field-access semantics — the stored value is kept, no error is raised).
+   */
+  rolesField?: {
+    /**
+     * Field name.
+     *
+     * @default 'roles'
+     */
+    name?: string;
+    /**
+     * Escape hatch to customize the generated relationship field — including
+     * replacing its `access` to lift or change the `roles:update` requirement.
+     */
+    override?: (field: RelationshipField) => RelationshipField;
+  };
+  /**
+   * Auth-enabled collections that receive the roles field. Defaults to every
+   * auth-enabled collection in the config, falling back to `admin.user`.
+   */
+  userCollections?: CollectionSlug[];
+};
+//#endregion
+export { PredefinedRole, RbacEntitySelection, RbacPermission, RbacPluginConfig };
+//# sourceMappingURL=types.d.ts.map

package/dist/utilities/entityLabel.d.ts

@@ -0,0 +1,10 @@
+//#region src/utilities/entityLabel.d.ts
+/**
+ * Resolves a display label for a collection or global at plugin time. Matrix rows
+ * cross to the client as serialized props, so only plain-string labels can be used —
+ * localized objects and label functions fall back to the humanized slug.
+ */
+declare const entityLabel: (label: unknown, slug: string) => string;
+//#endregion
+export { entityLabel };
+//# sourceMappingURL=entityLabel.d.ts.map