@whatworks/payload-rbac 0.1.0

package/dist/hooks/protectRolesField.d.ts

@@ -0,0 +1,57 @@
+import { CollectionBeforeChangeHook } from "payload";
+
+//#region src/hooks/protectRolesField.d.ts
+/** Extracts the role IDs from a relationship value (IDs or populated documents). */
+declare const normalizeRoleIds: (value: unknown) => (number | string)[];
+type ProtectRolesFieldArgs = {
+  /**
+   * Break-glass recovery for the named admin role: while no user in the system
+   * holds full access, a user may assign this role to themselves. Without it, a
+   * system whose administrators were lost to database-level damage could never
+   * regain one through the API.
+   */
+  breakGlass?: {
+    adminRoleName: string;
+    userCollections: string[];
+  };
+  /**
+   * Roles that only their holders may assign — permissions covering the role
+   * (even `'*'`) are not enough. The restriction relaxes while no user holds the
+   * role at all, so a newly introduced or renamed role can still be claimed by a
+   * user passing the ordinary permission check.
+   */
+  holderOnly?: {
+    roleNames: string[];
+    userCollections: string[];
+  };
+  /**
+   * Apply the permission-coverage check. The plugin disables this when
+   * `preventPrivilegeEscalation` is off while `holderOnly` must still apply.
+   *
+   * @default true
+   */
+  preventEscalation?: boolean;
+  rolesCollectionSlug: string;
+  rolesFieldName: string;
+};
+/**
+ * Privilege-escalation guard installed on each user collection: a user may only
+ * assign roles whose permissions their own roles already cover (users with `'*'`
+ * may assign anything), and `holderOnly` roles — the admin role — additionally
+ * only by users who already hold them. Removals mirror additions on the user's
+ * own account: a role may only be removed from yourself when the roles you keep
+ * still cover its permissions — otherwise you could never assign it back and
+ * would have locked yourself out. Removing roles from other users is not
+ * restricted, and writes without a user — seeds, init scripts, first-user
+ * registration — pass through.
+ */
+declare const createProtectRolesFieldHook: ({
+  breakGlass,
+  holderOnly,
+  preventEscalation,
+  rolesCollectionSlug,
+  rolesFieldName
+}: ProtectRolesFieldArgs) => CollectionBeforeChangeHook;
+//#endregion
+export { ProtectRolesFieldArgs, createProtectRolesFieldHook, normalizeRoleIds };
+//# sourceMappingURL=protectRolesField.d.ts.map

package/dist/hooks/protectRolesField.js

@@ -0,0 +1,99 @@
+import { missingPermissions } from "../permissions.js";
+import { getUserPermissions } from "../utilities/getUserPermissions.js";
+import { anyUserHoldsRole, findFullAccessRoleIds } from "../utilities/fullAccessHolders.js";
+import { APIError } from "payload";
+
+//#region src/hooks/protectRolesField.ts
+/** Extracts the role IDs from a relationship value (IDs or populated documents). */
+const normalizeRoleIds = (value) => {
+	if (!Array.isArray(value)) return [];
+	const ids = [];
+	for (const entry of value) if (typeof entry === "number" || typeof entry === "string") ids.push(entry);
+	else if (entry && typeof entry === "object") {
+		const id = entry.id;
+		if (typeof id === "number" || typeof id === "string") ids.push(id);
+	}
+	return ids;
+};
+/**
+* Privilege-escalation guard installed on each user collection: a user may only
+* assign roles whose permissions their own roles already cover (users with `'*'`
+* may assign anything), and `holderOnly` roles — the admin role — additionally
+* only by users who already hold them. Removals mirror additions on the user's
+* own account: a role may only be removed from yourself when the roles you keep
+* still cover its permissions — otherwise you could never assign it back and
+* would have locked yourself out. Removing roles from other users is not
+* restricted, and writes without a user — seeds, init scripts, first-user
+* registration — pass through.
+*/
+const createProtectRolesFieldHook = ({ breakGlass, holderOnly, preventEscalation, rolesCollectionSlug, rolesFieldName }) => {
+	const holderOnlyNames = new Set(holderOnly?.roleNames ?? []);
+	return async ({ collection, data, originalDoc, req }) => {
+		if (!req.user || !data || !(rolesFieldName in data)) return data;
+		const previousIds = normalizeRoleIds(originalDoc?.[rolesFieldName]);
+		const previousIdSet = new Set(previousIds.map(String));
+		const nextIdSet = new Set(normalizeRoleIds(data[rolesFieldName]).map(String));
+		const addedIds = normalizeRoleIds(data[rolesFieldName]).filter((id) => !previousIdSet.has(String(id)));
+		const targetId = originalDoc?.id;
+		const isSelf = req.user.collection === collection.slug && (typeof targetId === "number" || typeof targetId === "string") && String(targetId) === String(req.user.id);
+		const removedIds = isSelf && preventEscalation !== false ? previousIds.filter((id) => !nextIdSet.has(String(id))) : [];
+		if (addedIds.length === 0 && removedIds.length === 0) return data;
+		let stranded;
+		const systemIsStranded = async () => {
+			if (stranded === void 0) {
+				const fullAccessRoleIds = await findFullAccessRoleIds(req.payload, rolesCollectionSlug);
+				stranded = !await anyUserHoldsRole(req.payload, fullAccessRoleIds, {
+					rolesFieldName,
+					userCollections: breakGlass?.userCollections ?? []
+				});
+			}
+			return stranded;
+		};
+		if (addedIds.length > 0) {
+			const granted = preventEscalation === false ? /* @__PURE__ */ new Set() : await getUserPermissions(req);
+			const heldRoleIds = new Set(normalizeRoleIds(req.user[rolesFieldName]).map(String));
+			const { docs: addedRoles } = await req.payload.find({
+				collection: rolesCollectionSlug,
+				depth: 0,
+				overrideAccess: true,
+				pagination: false,
+				req,
+				where: { id: { in: addedIds } }
+			});
+			for (const role of addedRoles) {
+				const required = Array.isArray(role.permissions) ? role.permissions.filter((p) => typeof p === "string") : [];
+				const missing = preventEscalation === false ? [] : missingPermissions(granted, required);
+				let missingHolder = false;
+				if (typeof role.name === "string" && holderOnlyNames.has(role.name) && !heldRoleIds.has(String(role.id))) missingHolder = await anyUserHoldsRole(req.payload, [role.id], {
+					rolesFieldName,
+					userCollections: holderOnly?.userCollections ?? []
+				});
+				if (missing.length === 0 && !missingHolder) continue;
+				if (breakGlass && role.name === breakGlass.adminRoleName && isSelf && await systemIsStranded()) continue;
+				if (missingHolder) throw new APIError(`The role "${String(role.name)}" can only be assigned by a user who holds it.`, 403);
+				throw new APIError(`You cannot assign the role "${String(role.name)}" — it grants permissions you do not hold: ${missing.join(", ")}`, 403);
+			}
+		}
+		if (removedIds.length > 0) {
+			const { docs: previousRoles } = await req.payload.find({
+				collection: rolesCollectionSlug,
+				depth: 0,
+				overrideAccess: true,
+				pagination: false,
+				req,
+				where: { id: { in: previousIds } }
+			});
+			const keptPermissions = new Set(previousRoles.filter((role) => nextIdSet.has(String(role.id))).flatMap((role) => Array.isArray(role.permissions) ? role.permissions.filter((p) => typeof p === "string") : []));
+			for (const role of previousRoles) {
+				if (nextIdSet.has(String(role.id))) continue;
+				const missing = missingPermissions(keptPermissions, Array.isArray(role.permissions) ? role.permissions.filter((p) => typeof p === "string") : []);
+				if (missing.length > 0) throw new APIError(`You cannot remove the role "${String(role.name)}" from your own account — the roles you would keep do not cover ${missing.join(", ")}, so you could not assign it back. Another user with role management access must remove it.`, 403);
+			}
+		}
+		return data;
+	};
+};
+
+//#endregion
+export { createProtectRolesFieldHook, normalizeRoleIds };
+//# sourceMappingURL=protectRolesField.js.map

package/dist/hooks/protectRolesField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectRolesField.js","names":["ids: (number | string)[]","targetId: unknown","stranded: boolean | undefined"],"sources":["../../src/hooks/protectRolesField.ts"],"sourcesContent":["import type { CollectionBeforeChangeHook } from 'payload'\n\nimport { APIError } from 'payload'\n\nimport { missingPermissions } from '../permissions.js'\nimport { anyUserHoldsRole, findFullAccessRoleIds } from '../utilities/fullAccessHolders.js'\nimport { getUserPermissions } from '../utilities/getUserPermissions.js'\n\n/** Extracts the role IDs from a relationship value (IDs or populated documents). */\nexport const normalizeRoleIds = (value: unknown): (number | string)[] => {\n  if (!Array.isArray(value)) {\n    return []\n  }\n  const ids: (number | string)[] = []\n  for (const entry of value) {\n    if (typeof entry === 'number' || typeof entry === 'string') {\n      ids.push(entry)\n    } else if (entry && typeof entry === 'object') {\n      const id = (entry as Record<string, unknown>).id\n      if (typeof id === 'number' || typeof id === 'string') {\n        ids.push(id)\n      }\n    }\n  }\n  return ids\n}\n\nexport type ProtectRolesFieldArgs = {\n  /**\n   * Break-glass recovery for the named admin role: while no user in the system\n   * holds full access, a user may assign this role to themselves. Without it, a\n   * system whose administrators were lost to database-level damage could never\n   * regain one through the API.\n   */\n  breakGlass?: {\n    adminRoleName: string\n    userCollections: string[]\n  }\n  /**\n   * Roles that only their holders may assign — permissions covering the role\n   * (even `'*'`) are not enough. The restriction relaxes while no user holds the\n   * role at all, so a newly introduced or renamed role can still be claimed by a\n   * user passing the ordinary permission check.\n   */\n  holderOnly?: {\n    roleNames: string[]\n    userCollections: string[]\n  }\n  /**\n   * Apply the permission-coverage check. The plugin disables this when\n   * `preventPrivilegeEscalation` is off while `holderOnly` must still apply.\n   *\n   * @default true\n   */\n  preventEscalation?: boolean\n  rolesCollectionSlug: string\n  rolesFieldName: string\n}\n\n/**\n * Privilege-escalation guard installed on each user collection: a user may only\n * assign roles whose permissions their own roles already cover (users with `'*'`\n * may assign anything), and `holderOnly` roles — the admin role — additionally\n * only by users who already hold them. Removals mirror additions on the user's\n * own account: a role may only be removed from yourself when the roles you keep\n * still cover its permissions — otherwise you could never assign it back and\n * would have locked yourself out. Removing roles from other users is not\n * restricted, and writes without a user — seeds, init scripts, first-user\n * registration — pass through.\n */\nexport const createProtectRolesFieldHook = ({\n  breakGlass,\n  holderOnly,\n  preventEscalation,\n  rolesCollectionSlug,\n  rolesFieldName,\n}: ProtectRolesFieldArgs): CollectionBeforeChangeHook => {\n  const holderOnlyNames = new Set(holderOnly?.roleNames ?? [])\n  return async ({ collection, data, originalDoc, req }) => {\n    if (!req.user || !data || !(rolesFieldName in data)) {\n      return data\n    }\n\n    const previousIds = normalizeRoleIds(originalDoc?.[rolesFieldName])\n    const previousIdSet = new Set(previousIds.map(String))\n    const nextIdSet = new Set(normalizeRoleIds(data[rolesFieldName]).map(String))\n    const addedIds = normalizeRoleIds(data[rolesFieldName]).filter(\n      (id) => !previousIdSet.has(String(id)),\n    )\n\n    const targetId: unknown = originalDoc?.id\n    const isSelf =\n      req.user.collection === collection.slug &&\n      (typeof targetId === 'number' || typeof targetId === 'string') &&\n      String(targetId) === String(req.user.id)\n    const removedIds =\n      isSelf && preventEscalation !== false\n        ? previousIds.filter((id) => !nextIdSet.has(String(id)))\n        : []\n\n    if (addedIds.length === 0 && removedIds.length === 0) {\n      return data\n    }\n\n    let stranded: boolean | undefined\n    const systemIsStranded = async (): Promise<boolean> => {\n      if (stranded === undefined) {\n        const fullAccessRoleIds = await findFullAccessRoleIds(req.payload, rolesCollectionSlug)\n        stranded = !(await anyUserHoldsRole(req.payload, fullAccessRoleIds, {\n          rolesFieldName,\n          userCollections: breakGlass?.userCollections ?? [],\n        }))\n      }\n      return stranded\n    }\n\n    if (addedIds.length > 0) {\n      const granted =\n        preventEscalation === false ? new Set<string>() : await getUserPermissions(req)\n      const heldRoleIds = new Set(\n        normalizeRoleIds((req.user as Record<string, unknown>)[rolesFieldName]).map(String),\n      )\n\n      const { docs: addedRoles } = await req.payload.find({\n        collection: rolesCollectionSlug,\n        depth: 0,\n        overrideAccess: true,\n        pagination: false,\n        req,\n        where: { id: { in: addedIds } },\n      })\n\n      for (const role of addedRoles) {\n        const required = Array.isArray(role.permissions)\n          ? role.permissions.filter((p): p is string => typeof p === 'string')\n          : []\n        const missing = preventEscalation === false ? [] : missingPermissions(granted, required)\n\n        let missingHolder = false\n        if (\n          typeof role.name === 'string' &&\n          holderOnlyNames.has(role.name) &&\n          !heldRoleIds.has(String(role.id))\n        ) {\n          // Only holders may hand out a holder-only role — except while nobody\n          // holds it at all (a fresh rename, or the plugin newly added to an\n          // existing project), when a user passing the permission check steps up.\n          missingHolder = await anyUserHoldsRole(req.payload, [role.id], {\n            rolesFieldName,\n            userCollections: holderOnly?.userCollections ?? [],\n          })\n        }\n\n        if (missing.length === 0 && !missingHolder) {\n          continue\n        }\n\n        if (\n          breakGlass &&\n          role.name === breakGlass.adminRoleName &&\n          isSelf &&\n          (await systemIsStranded())\n        ) {\n          continue\n        }\n        if (missingHolder) {\n          throw new APIError(\n            `The role \"${String(role.name)}\" can only be assigned by a user who holds it.`,\n            403,\n          )\n        }\n        throw new APIError(\n          `You cannot assign the role \"${String(role.name)}\" — it grants permissions you do not hold: ${missing.join(', ')}`,\n          403,\n        )\n      }\n    }\n\n    if (removedIds.length > 0) {\n      // Removals mirror additions on your own account: the roles you keep must\n      // cover what the removed role granted, or the escalation guard could never\n      // let you re-assign it — one save away from locking yourself out. Roles\n      // whose documents no longer exist grant nothing and may always be removed.\n      const { docs: previousRoles } = await req.payload.find({\n        collection: rolesCollectionSlug,\n        depth: 0,\n        overrideAccess: true,\n        pagination: false,\n        req,\n        where: { id: { in: previousIds } },\n      })\n      const keptPermissions = new Set(\n        previousRoles\n          .filter((role) => nextIdSet.has(String(role.id)))\n          .flatMap((role) =>\n            Array.isArray(role.permissions)\n              ? role.permissions.filter((p): p is string => typeof p === 'string')\n              : [],\n          ),\n      )\n      for (const role of previousRoles) {\n        if (nextIdSet.has(String(role.id))) {\n          continue\n        }\n        const required = Array.isArray(role.permissions)\n          ? role.permissions.filter((p): p is string => typeof p === 'string')\n          : []\n        const missing = missingPermissions(keptPermissions, required)\n        if (missing.length > 0) {\n          throw new APIError(\n            `You cannot remove the role \"${String(role.name)}\" from your own account — the roles you would keep do not cover ${missing.join(', ')}, so you could not assign it back. Another user with role management access must remove it.`,\n            403,\n          )\n        }\n      }\n    }\n\n    return data\n  }\n}\n"],"mappings":"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"}

package/dist/hooks/protectedRoles.d.ts

@@ -0,0 +1,34 @@
+import { PredefinedRole } from "../types.js";
+import { CollectionBeforeChangeHook, CollectionBeforeDeleteHook } from "payload";
+
+//#region src/hooks/protectedRoles.d.ts
+type ProtectedRolesChangeArgs = {
+  protectedRoles: PredefinedRole[];
+};
+type ProtectedRolesDeleteArgs = {
+  protectedRoleNames: string[];
+  rolesCollectionSlug: string;
+};
+/**
+ * Locks protected roles to their code definition: they cannot be renamed and their
+ * permissions cannot be changed through the API — the only permissions write
+ * accepted is restoring the exact code-defined list, so a drifted role can always
+ * be repaired but never downgraded. Applies regardless of the caller's own
+ * permissions (even `'*'`): the point is that the last full-access role can never
+ * be sawed off, leaving nobody able to grant permissions back. Writes without a
+ * user (seeding, local API scripts) pass through.
+ */
+declare const createProtectedRolesChangeHook: ({
+  protectedRoles
+}: ProtectedRolesChangeArgs) => CollectionBeforeChangeHook;
+/**
+ * Blocks deleting protected roles through the API — deleting the only full-access
+ * role would lock everyone out just as surely as downgrading it.
+ */
+declare const createProtectedRolesDeleteHook: ({
+  protectedRoleNames,
+  rolesCollectionSlug
+}: ProtectedRolesDeleteArgs) => CollectionBeforeDeleteHook;
+//#endregion
+export { ProtectedRolesChangeArgs, ProtectedRolesDeleteArgs, createProtectedRolesChangeHook, createProtectedRolesDeleteHook };
+//# sourceMappingURL=protectedRoles.d.ts.map

package/dist/hooks/protectedRoles.js

@@ -0,0 +1,50 @@
+import { samePermissions } from "../permissions.js";
+import { APIError } from "payload";
+
+//#region src/hooks/protectedRoles.ts
+/**
+* Locks protected roles to their code definition: they cannot be renamed and their
+* permissions cannot be changed through the API — the only permissions write
+* accepted is restoring the exact code-defined list, so a drifted role can always
+* be repaired but never downgraded. Applies regardless of the caller's own
+* permissions (even `'*'`): the point is that the last full-access role can never
+* be sawed off, leaving nobody able to grant permissions back. Writes without a
+* user (seeding, local API scripts) pass through.
+*/
+const createProtectedRolesChangeHook = ({ protectedRoles }) => {
+	const byName = new Map(protectedRoles.map((role) => [role.name, role]));
+	return ({ data, originalDoc, req }) => {
+		if (!req.user || !data) return data;
+		const originalName = typeof originalDoc?.name === "string" ? originalDoc.name : void 0;
+		const incomingName = typeof data.name === "string" ? data.name : void 0;
+		const role = byName.get(originalName ?? "") ?? byName.get(incomingName ?? "");
+		if (!role) return data;
+		if (originalName === role.name && incomingName !== void 0 && incomingName !== role.name) throw new APIError(`The role "${role.name}" is protected and cannot be renamed.`, 403);
+		if ("permissions" in data && !samePermissions(data.permissions, role.permissions)) throw new APIError(`The role "${role.name}" is protected — its permissions are defined in code and cannot be changed here.`, 403);
+		return data;
+	};
+};
+/**
+* Blocks deleting protected roles through the API — deleting the only full-access
+* role would lock everyone out just as surely as downgrading it.
+*/
+const createProtectedRolesDeleteHook = ({ protectedRoleNames, rolesCollectionSlug }) => {
+	const names = new Set(protectedRoleNames);
+	return async ({ id, req }) => {
+		if (!req.user) return;
+		const doc = await req.payload.findByID({
+			id,
+			collection: rolesCollectionSlug,
+			depth: 0,
+			disableErrors: true,
+			overrideAccess: true,
+			req
+		});
+		const name = typeof doc?.name === "string" ? doc.name : void 0;
+		if (name !== void 0 && names.has(name)) throw new APIError(`The role "${name}" is protected and cannot be deleted.`, 403);
+	};
+};
+
+//#endregion
+export { createProtectedRolesChangeHook, createProtectedRolesDeleteHook };
+//# sourceMappingURL=protectedRoles.js.map

package/dist/hooks/protectedRoles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectedRoles.js","names":[],"sources":["../../src/hooks/protectedRoles.ts"],"sourcesContent":["import type { CollectionBeforeChangeHook, CollectionBeforeDeleteHook } from 'payload'\n\nimport { APIError } from 'payload'\n\nimport type { PredefinedRole } from '../types.js'\n\nimport { samePermissions } from '../permissions.js'\n\nexport type ProtectedRolesChangeArgs = {\n  protectedRoles: PredefinedRole[]\n}\n\nexport type ProtectedRolesDeleteArgs = {\n  protectedRoleNames: string[]\n  rolesCollectionSlug: string\n}\n\n/**\n * Locks protected roles to their code definition: they cannot be renamed and their\n * permissions cannot be changed through the API — the only permissions write\n * accepted is restoring the exact code-defined list, so a drifted role can always\n * be repaired but never downgraded. Applies regardless of the caller's own\n * permissions (even `'*'`): the point is that the last full-access role can never\n * be sawed off, leaving nobody able to grant permissions back. Writes without a\n * user (seeding, local API scripts) pass through.\n */\nexport const createProtectedRolesChangeHook = ({\n  protectedRoles,\n}: ProtectedRolesChangeArgs): CollectionBeforeChangeHook => {\n  const byName = new Map(protectedRoles.map((role) => [role.name, role]))\n  return ({ data, originalDoc, req }) => {\n    if (!req.user || !data) {\n      return data\n    }\n\n    const originalName = typeof originalDoc?.name === 'string' ? originalDoc.name : undefined\n    const incomingName = typeof data.name === 'string' ? data.name : undefined\n    const role = byName.get(originalName ?? '') ?? byName.get(incomingName ?? '')\n    if (!role) {\n      return data\n    }\n\n    if (originalName === role.name && incomingName !== undefined && incomingName !== role.name) {\n      throw new APIError(`The role \"${role.name}\" is protected and cannot be renamed.`, 403)\n    }\n    if ('permissions' in data && !samePermissions(data.permissions, role.permissions)) {\n      throw new APIError(\n        `The role \"${role.name}\" is protected — its permissions are defined in code and cannot be changed here.`,\n        403,\n      )\n    }\n\n    return data\n  }\n}\n\n/**\n * Blocks deleting protected roles through the API — deleting the only full-access\n * role would lock everyone out just as surely as downgrading it.\n */\nexport const createProtectedRolesDeleteHook = ({\n  protectedRoleNames,\n  rolesCollectionSlug,\n}: ProtectedRolesDeleteArgs): CollectionBeforeDeleteHook => {\n  const names = new Set(protectedRoleNames)\n  return async ({ id, req }) => {\n    if (!req.user) {\n      return\n    }\n    const doc = (await req.payload.findByID({\n      id,\n      collection: rolesCollectionSlug,\n      depth: 0,\n      disableErrors: true,\n      overrideAccess: true,\n      req,\n    })) as { name?: unknown } | null\n    const name = typeof doc?.name === 'string' ? doc.name : undefined\n    if (name !== undefined && names.has(name)) {\n      throw new APIError(`The role \"${name}\" is protected and cannot be deleted.`, 403)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AA0BA,MAAa,kCAAkC,EAC7C,qBAC0D;CAC1D,MAAM,SAAS,IAAI,IAAI,eAAe,KAAK,SAAS,CAAC,KAAK,MAAM,KAAK,CAAC,CAAC;AACvE,SAAQ,EAAE,MAAM,aAAa,UAAU;AACrC,MAAI,CAAC,IAAI,QAAQ,CAAC,KAChB,QAAO;EAGT,MAAM,eAAe,OAAO,aAAa,SAAS,WAAW,YAAY,OAAO;EAChF,MAAM,eAAe,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO;EACjE,MAAM,OAAO,OAAO,IAAI,gBAAgB,GAAG,IAAI,OAAO,IAAI,gBAAgB,GAAG;AAC7E,MAAI,CAAC,KACH,QAAO;AAGT,MAAI,iBAAiB,KAAK,QAAQ,iBAAiB,UAAa,iBAAiB,KAAK,KACpF,OAAM,IAAI,SAAS,aAAa,KAAK,KAAK,wCAAwC,IAAI;AAExF,MAAI,iBAAiB,QAAQ,CAAC,gBAAgB,KAAK,aAAa,KAAK,YAAY,CAC/E,OAAM,IAAI,SACR,aAAa,KAAK,KAAK,mFACvB,IACD;AAGH,SAAO;;;;;;;AAQX,MAAa,kCAAkC,EAC7C,oBACA,0BAC0D;CAC1D,MAAM,QAAQ,IAAI,IAAI,mBAAmB;AACzC,QAAO,OAAO,EAAE,IAAI,UAAU;AAC5B,MAAI,CAAC,IAAI,KACP;EAEF,MAAM,MAAO,MAAM,IAAI,QAAQ,SAAS;GACtC;GACA,YAAY;GACZ,OAAO;GACP,eAAe;GACf,gBAAgB;GAChB;GACD,CAAC;EACF,MAAM,OAAO,OAAO,KAAK,SAAS,WAAW,IAAI,OAAO;AACxD,MAAI,SAAS,UAAa,MAAM,IAAI,KAAK,CACvC,OAAM,IAAI,SAAS,aAAa,KAAK,wCAAwC,IAAI"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { MatrixRow, RbacAction, RbacCustomConfig, collectionActions, getRbacCustomConfig, globalActions, permissionsMatrixFieldPath, pluginKey } from "./shared.js";
+import { CreateRbacAccessArgs, createRbacAccess, requirePermission } from "./access/rbacAccess.js";
+import { CreateRolesFieldAccessArgs, createRolesFieldAccess } from "./access/rolesFieldAccess.js";
+import { CreateRolesCollectionArgs, createRolesCollection } from "./collections/createRolesCollection.js";
+import { CreateRolesFieldArgs, createRolesField } from "./fields/createRolesField.js";
+import { AssignFirstUserRoleArgs, createAssignFirstUserRoleHook } from "./hooks/assignFirstUserRole.js";
+import { ProtectCredentialsArgs, createProtectCredentialsHook } from "./hooks/protectCredentials.js";
+import { PredefinedRole, RbacEntitySelection, RbacPermission, RbacPluginConfig } from "./types.js";
+import { ProtectedRolesChangeArgs, ProtectedRolesDeleteArgs, createProtectedRolesChangeHook, createProtectedRolesDeleteHook } from "./hooks/protectedRoles.js";
+import { ProtectLastAdminArgs, createProtectLastAdminChangeHook, createProtectLastAdminDeleteHook } from "./hooks/protectLastAdmin.js";
+import { ProtectRolesCollectionArgs, createProtectRolesCollectionHook } from "./hooks/protectRolesCollection.js";
+import { ProtectRolesFieldArgs, createProtectRolesFieldHook, normalizeRoleIds } from "./hooks/protectRolesField.js";
+import { FULL_ACCESS, missingPermissions, permissionFor, permissionsGrant, samePermissions } from "./permissions.js";
+import { rbacPlugin } from "./plugin.js";
+import { SeedPredefinedRolesArgs, seedPredefinedRoles } from "./seed.js";
+import { entityLabel } from "./utilities/entityLabel.js";
+import { RoleHolderQueryArgs, WarnIfAdminRoleUnheldArgs, anyUserHoldsRole, findFullAccessRoleIds, warnIfAdminRoleUnheld } from "./utilities/fullAccessHolders.js";
+import { getUserPermissions, hasPermission } from "./utilities/getUserPermissions.js";
+export { type AssignFirstUserRoleArgs, type CreateRbacAccessArgs, type CreateRolesCollectionArgs, type CreateRolesFieldAccessArgs, type CreateRolesFieldArgs, FULL_ACCESS, type MatrixRow, type PredefinedRole, type ProtectCredentialsArgs, type ProtectLastAdminArgs, type ProtectRolesCollectionArgs, type ProtectRolesFieldArgs, type ProtectedRolesChangeArgs, type ProtectedRolesDeleteArgs, type RbacAction, type RbacCustomConfig, type RbacEntitySelection, type RbacPermission, type RbacPluginConfig, type RoleHolderQueryArgs, type SeedPredefinedRolesArgs, type WarnIfAdminRoleUnheldArgs, anyUserHoldsRole, collectionActions, createAssignFirstUserRoleHook, createProtectCredentialsHook, createProtectLastAdminChangeHook, createProtectLastAdminDeleteHook, createProtectRolesCollectionHook, createProtectRolesFieldHook, createProtectedRolesChangeHook, createProtectedRolesDeleteHook, createRbacAccess, createRolesCollection, createRolesField, createRolesFieldAccess, entityLabel, findFullAccessRoleIds, getRbacCustomConfig, getUserPermissions, globalActions, hasPermission, missingPermissions, normalizeRoleIds, permissionFor, permissionsGrant, permissionsMatrixFieldPath, pluginKey, rbacPlugin, requirePermission, samePermissions, seedPredefinedRoles, warnIfAdminRoleUnheld };

package/dist/index.js

@@ -0,0 +1,19 @@
+import { FULL_ACCESS, missingPermissions, permissionFor, permissionsGrant, samePermissions } from "./permissions.js";
+import { collectionActions, getRbacCustomConfig, globalActions, permissionsMatrixFieldPath, pluginKey } from "./shared.js";
+import { getUserPermissions, hasPermission } from "./utilities/getUserPermissions.js";
+import { createRbacAccess, requirePermission } 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, normalizeRoleIds } 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";
+import { rbacPlugin } from "./plugin.js";
+
+export { FULL_ACCESS, anyUserHoldsRole, collectionActions, createAssignFirstUserRoleHook, createProtectCredentialsHook, createProtectLastAdminChangeHook, createProtectLastAdminDeleteHook, createProtectRolesCollectionHook, createProtectRolesFieldHook, createProtectedRolesChangeHook, createProtectedRolesDeleteHook, createRbacAccess, createRolesCollection, createRolesField, createRolesFieldAccess, entityLabel, findFullAccessRoleIds, getRbacCustomConfig, getUserPermissions, globalActions, hasPermission, missingPermissions, normalizeRoleIds, permissionFor, permissionsGrant, permissionsMatrixFieldPath, pluginKey, rbacPlugin, requirePermission, samePermissions, seedPredefinedRoles, warnIfAdminRoleUnheld };

package/dist/permissions.d.ts

@@ -0,0 +1,23 @@
+import { RbacAction } from "./shared.js";
+
+//#region src/permissions.d.ts
+/** Grants every action on every controlled collection and global. */
+declare const FULL_ACCESS = "*";
+/** Builds the permission string for one action on one collection or global. */
+declare const permissionFor: (slug: string, action: RbacAction) => string;
+/** Whether a permission set grants an action on a collection or global. */
+declare const permissionsGrant: (permissions: ReadonlySet<string>, slug: string, action: RbacAction) => boolean;
+/**
+ * Order-insensitive equality between a stored permissions value (unknown shape —
+ * may be missing or malformed) and a code-defined permission list. Used by the
+ * protected-role guard and the drift repair in seeding.
+ */
+declare const samePermissions: (value: unknown, permissions: readonly string[]) => boolean;
+/**
+ * The subset of `required` not covered by `granted`. Used by the privilege-escalation
+ * guards: an empty result means the grantor holds everything they are handing out.
+ */
+declare const missingPermissions: (granted: ReadonlySet<string>, required: readonly string[]) => string[];
+//#endregion
+export { FULL_ACCESS, missingPermissions, permissionFor, permissionsGrant, samePermissions };
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.js

@@ -0,0 +1,31 @@
+//#region src/permissions.ts
+/** Grants every action on every controlled collection and global. */
+const FULL_ACCESS = "*";
+/** Builds the permission string for one action on one collection or global. */
+const permissionFor = (slug, action) => `${slug}:${action}`;
+/** Whether a permission set grants an action on a collection or global. */
+const permissionsGrant = (permissions, slug, action) => {
+	return permissions.has(FULL_ACCESS) || permissions.has(permissionFor(slug, action));
+};
+/**
+* Order-insensitive equality between a stored permissions value (unknown shape —
+* may be missing or malformed) and a code-defined permission list. Used by the
+* protected-role guard and the drift repair in seeding.
+*/
+const samePermissions = (value, permissions) => {
+	const stored = new Set(Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : []);
+	const expected = new Set(permissions);
+	return stored.size === expected.size && [...expected].every((entry) => stored.has(entry));
+};
+/**
+* The subset of `required` not covered by `granted`. Used by the privilege-escalation
+* guards: an empty result means the grantor holds everything they are handing out.
+*/
+const missingPermissions = (granted, required) => {
+	if (granted.has(FULL_ACCESS)) return [];
+	return required.filter((permission) => !granted.has(permission));
+};
+
+//#endregion
+export { FULL_ACCESS, missingPermissions, permissionFor, permissionsGrant, samePermissions };
+//# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","names":[],"sources":["../src/permissions.ts"],"sourcesContent":["import type { RbacAction } from './shared.js'\n\n/** Grants every action on every controlled collection and global. */\nexport const FULL_ACCESS = '*'\n\n/** Builds the permission string for one action on one collection or global. */\nexport const permissionFor = (slug: string, action: RbacAction): string => `${slug}:${action}`\n\n/** Whether a permission set grants an action on a collection or global. */\nexport const permissionsGrant = (\n  permissions: ReadonlySet<string>,\n  slug: string,\n  action: RbacAction,\n): boolean => {\n  return permissions.has(FULL_ACCESS) || permissions.has(permissionFor(slug, action))\n}\n\n/**\n * Order-insensitive equality between a stored permissions value (unknown shape —\n * may be missing or malformed) and a code-defined permission list. Used by the\n * protected-role guard and the drift repair in seeding.\n */\nexport const samePermissions = (value: unknown, permissions: readonly string[]): boolean => {\n  const stored = new Set(\n    Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [],\n  )\n  const expected = new Set(permissions)\n  return stored.size === expected.size && [...expected].every((entry) => stored.has(entry))\n}\n\n/**\n * The subset of `required` not covered by `granted`. Used by the privilege-escalation\n * guards: an empty result means the grantor holds everything they are handing out.\n */\nexport const missingPermissions = (\n  granted: ReadonlySet<string>,\n  required: readonly string[],\n): string[] => {\n  if (granted.has(FULL_ACCESS)) {\n    return []\n  }\n  return required.filter((permission) => !granted.has(permission))\n}\n"],"mappings":";;AAGA,MAAa,cAAc;;AAG3B,MAAa,iBAAiB,MAAc,WAA+B,GAAG,KAAK,GAAG;;AAGtF,MAAa,oBACX,aACA,MACA,WACY;AACZ,QAAO,YAAY,IAAI,YAAY,IAAI,YAAY,IAAI,cAAc,MAAM,OAAO,CAAC;;;;;;;AAQrF,MAAa,mBAAmB,OAAgB,gBAA4C;CAC1F,MAAM,SAAS,IAAI,IACjB,MAAM,QAAQ,MAAM,GAAG,MAAM,QAAQ,UAA2B,OAAO,UAAU,SAAS,GAAG,EAAE,CAChG;CACD,MAAM,WAAW,IAAI,IAAI,YAAY;AACrC,QAAO,OAAO,SAAS,SAAS,QAAQ,CAAC,GAAG,SAAS,CAAC,OAAO,UAAU,OAAO,IAAI,MAAM,CAAC;;;;;;AAO3F,MAAa,sBACX,SACA,aACa;AACb,KAAI,QAAQ,IAAI,YAAY,CAC1B,QAAO,EAAE;AAEX,QAAO,SAAS,QAAQ,eAAe,CAAC,QAAQ,IAAI,WAAW,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,8 @@
+import { RbacPluginConfig } from "./types.js";
+import { Plugin } from "payload";
+
+//#region src/plugin.d.ts
+declare const rbacPlugin: (pluginConfig?: RbacPluginConfig) => Plugin;
+//#endregion
+export { rbacPlugin };
+//# sourceMappingURL=plugin.d.ts.map