@whatworks/payload-rbac 0.1.0

package/dist/fields/PermissionsMatrixField.js

@@ -0,0 +1,180 @@
+'use client';
+
+import { FULL_ACCESS, permissionFor } from "../permissions.js";
+import { collectionActions } from "../shared.js";
+import { FieldDescription, FieldLabel, useField, useFormFields } from "@payloadcms/ui";
+import React, { useCallback, useMemo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/fields/PermissionsMatrixField.tsx
+const cellStyle = {
+	border: "1px solid var(--theme-elevation-150)",
+	padding: "8px 12px",
+	textAlign: "center"
+};
+const rowLabelStyle = {
+	...cellStyle,
+	textAlign: "left"
+};
+/**
+* Renders the roles collection's `permissions` select as a matrix of collections ×
+* Create/Read/Update/Delete checkboxes (globals: Read/Update), with a "full access"
+* master toggle for `'*'`. The stored value stays a plain array of permission
+* strings, so the REST/local APIs are unaffected.
+*/
+const PermissionsMatrixField = (props) => {
+	const { field, path, protectedRoleNames = [], readOnly, rows = [] } = props;
+	const { setValue, showError, value } = useField({ path });
+	const roleName = useFormFields(([fields]) => fields?.name?.value);
+	const selected = useMemo(() => new Set(value ?? []), [value]);
+	const fullAccess = selected.has(FULL_ACCESS);
+	const isProtected = typeof roleName === "string" && protectedRoleNames.includes(roleName);
+	const locked = Boolean(readOnly) || isProtected;
+	const toggle = useCallback((permission) => {
+		const next = new Set(selected);
+		if (next.has(permission)) next.delete(permission);
+		else next.add(permission);
+		setValue(Array.from(next).sort());
+	}, [selected, setValue]);
+	const toggleRow = useCallback((row) => {
+		const permissions = row.actions.map((action) => permissionFor(row.slug, action));
+		const allSelected = permissions.every((permission) => selected.has(permission));
+		const next = new Set(selected);
+		for (const permission of permissions) if (allSelected) next.delete(permission);
+		else next.add(permission);
+		setValue(Array.from(next).sort());
+	}, [selected, setValue]);
+	const hasGlobals = rows.some((row) => row.entity === "global");
+	const hasCollections = rows.some((row) => row.entity === "collection");
+	const renderRows = (entity) => rows.filter((row) => row.entity === entity).map((row) => {
+		const rowPermissions = row.actions.map((action) => permissionFor(row.slug, action));
+		const allChecked = fullAccess || rowPermissions.every((permission) => selected.has(permission));
+		const someChecked = rowPermissions.some((permission) => selected.has(permission));
+		return /* @__PURE__ */ jsxs("tr", { children: [
+			/* @__PURE__ */ jsx("td", {
+				style: rowLabelStyle,
+				children: row.label
+			}),
+			/* @__PURE__ */ jsx("td", {
+				style: cellStyle,
+				children: /* @__PURE__ */ jsx("input", {
+					"aria-label": `${row.label}: all actions`,
+					checked: allChecked,
+					disabled: locked || fullAccess,
+					onChange: () => toggleRow(row),
+					ref: (el) => {
+						if (el) el.indeterminate = !allChecked && someChecked;
+					},
+					type: "checkbox"
+				})
+			}),
+			collectionActions.map((action) => {
+				const available = row.actions.includes(action);
+				const permission = permissionFor(row.slug, action);
+				return /* @__PURE__ */ jsx("td", {
+					style: cellStyle,
+					children: available ? /* @__PURE__ */ jsx("input", {
+						"aria-label": `${row.label}: ${action}`,
+						checked: fullAccess || selected.has(permission),
+						disabled: locked || fullAccess,
+						onChange: () => toggle(permission),
+						type: "checkbox"
+					}) : /* @__PURE__ */ jsx("span", {
+						"aria-hidden": true,
+						children: "—"
+					})
+				}, action);
+			})
+		] }, `${row.entity}:${row.slug}`);
+	});
+	const sectionHeading = (label) => /* @__PURE__ */ jsx("tr", { children: /* @__PURE__ */ jsx("th", {
+		colSpan: collectionActions.length + 2,
+		style: {
+			...rowLabelStyle,
+			fontWeight: 600
+		},
+		children: label
+	}) });
+	return /* @__PURE__ */ jsxs("div", {
+		className: "field-type rbac-permissions-matrix",
+		style: { marginBottom: "var(--base)" },
+		children: [
+			/* @__PURE__ */ jsx(FieldLabel, {
+				label: field?.label ?? "Permissions",
+				path
+			}),
+			showError && /* @__PURE__ */ jsx("div", {
+				style: {
+					color: "var(--theme-error-500)",
+					marginBottom: 8
+				},
+				children: "Invalid permissions value"
+			}),
+			isProtected && /* @__PURE__ */ jsx("div", {
+				style: {
+					color: "var(--theme-elevation-500)",
+					margin: "8px 0"
+				},
+				children: "This role is protected — its permissions are defined in code and cannot be edited here."
+			}),
+			/* @__PURE__ */ jsxs("label", {
+				style: {
+					alignItems: "center",
+					display: "flex",
+					gap: 8,
+					margin: "8px 0 12px"
+				},
+				children: [/* @__PURE__ */ jsx("input", {
+					"aria-label": "Full access",
+					checked: fullAccess,
+					disabled: locked,
+					onChange: () => toggle(FULL_ACCESS),
+					type: "checkbox"
+				}), /* @__PURE__ */ jsx("span", { children: "Full access — every action on every collection and global, including ones added in the future" })]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				style: {
+					opacity: fullAccess ? .5 : 1,
+					overflowX: "auto"
+				},
+				children: /* @__PURE__ */ jsxs("table", {
+					style: {
+						borderCollapse: "collapse",
+						width: "100%"
+					},
+					children: [/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+						/* @__PURE__ */ jsx("th", {
+							"aria-label": "Collection or global",
+							style: rowLabelStyle
+						}),
+						/* @__PURE__ */ jsx("th", {
+							style: cellStyle,
+							children: "All"
+						}),
+						collectionActions.map((action) => /* @__PURE__ */ jsx("th", {
+							style: {
+								...cellStyle,
+								textTransform: "capitalize"
+							},
+							children: action
+						}, action))
+					] }) }), /* @__PURE__ */ jsxs("tbody", { children: [
+						hasCollections && hasGlobals && sectionHeading("Collections"),
+						renderRows("collection"),
+						hasGlobals && sectionHeading("Globals"),
+						renderRows("global")
+					] })]
+				})
+			}),
+			/* @__PURE__ */ jsx(FieldDescription, {
+				description: field?.admin?.description,
+				marginPlacement: "bottom",
+				path
+			})
+		]
+	});
+};
+
+//#endregion
+export { PermissionsMatrixField };
+//# sourceMappingURL=PermissionsMatrixField.js.map

package/dist/fields/PermissionsMatrixField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionsMatrixField.js","names":["cellStyle: React.CSSProperties","rowLabelStyle: React.CSSProperties","PermissionsMatrixField: React.FC<PermissionsMatrixFieldProps>"],"sources":["../../src/fields/PermissionsMatrixField.tsx"],"sourcesContent":["'use client'\n\nimport type { SelectFieldClientProps } from 'payload'\n\nimport { FieldDescription, FieldLabel, useField, useFormFields } from '@payloadcms/ui'\nimport React, { useCallback, useMemo } from 'react'\n\nimport type { MatrixRow, RbacAction } from '../shared.js'\n\nimport { FULL_ACCESS, permissionFor } from '../permissions.js'\nimport { collectionActions } from '../shared.js'\n\nconst cellStyle: React.CSSProperties = {\n  border: '1px solid var(--theme-elevation-150)',\n  padding: '8px 12px',\n  textAlign: 'center',\n}\n\nconst rowLabelStyle: React.CSSProperties = {\n  ...cellStyle,\n  textAlign: 'left',\n}\n\nexport type PermissionsMatrixFieldProps = {\n  /** Names of code-locked roles the matrix renders read-only for. */\n  protectedRoleNames?: string[]\n  /** Serialized by the plugin into the field's `clientProps`. */\n  rows?: MatrixRow[]\n} & SelectFieldClientProps\n\n/**\n * Renders the roles collection's `permissions` select as a matrix of collections ×\n * Create/Read/Update/Delete checkboxes (globals: Read/Update), with a \"full access\"\n * master toggle for `'*'`. The stored value stays a plain array of permission\n * strings, so the REST/local APIs are unaffected.\n */\nexport const PermissionsMatrixField: React.FC<PermissionsMatrixFieldProps> = (props) => {\n  const { field, path, protectedRoleNames = [], readOnly, rows = [] } = props\n  const { setValue, showError, value } = useField<string[]>({ path })\n  const roleName = useFormFields(([fields]) => fields?.name?.value)\n\n  const selected = useMemo(() => new Set(value ?? []), [value])\n  const fullAccess = selected.has(FULL_ACCESS)\n  // Best-effort UX only — the beforeChange guard on the server is authoritative.\n  const isProtected = typeof roleName === 'string' && protectedRoleNames.includes(roleName)\n  const locked = Boolean(readOnly) || isProtected\n\n  const toggle = useCallback(\n    (permission: string) => {\n      const next = new Set(selected)\n      if (next.has(permission)) {\n        next.delete(permission)\n      } else {\n        next.add(permission)\n      }\n      setValue(Array.from(next).sort())\n    },\n    [selected, setValue],\n  )\n\n  const toggleRow = useCallback(\n    (row: MatrixRow) => {\n      const permissions = row.actions.map((action) => permissionFor(row.slug, action))\n      const allSelected = permissions.every((permission) => selected.has(permission))\n      const next = new Set(selected)\n      for (const permission of permissions) {\n        if (allSelected) {\n          next.delete(permission)\n        } else {\n          next.add(permission)\n        }\n      }\n      setValue(Array.from(next).sort())\n    },\n    [selected, setValue],\n  )\n\n  const hasGlobals = rows.some((row) => row.entity === 'global')\n  const hasCollections = rows.some((row) => row.entity === 'collection')\n\n  const renderRows = (entity: MatrixRow['entity']) =>\n    rows\n      .filter((row) => row.entity === entity)\n      .map((row) => {\n        const rowPermissions = row.actions.map((action) => permissionFor(row.slug, action))\n        const allChecked =\n          fullAccess || rowPermissions.every((permission) => selected.has(permission))\n        const someChecked = rowPermissions.some((permission) => selected.has(permission))\n        return (\n          <tr key={`${row.entity}:${row.slug}`}>\n            <td style={rowLabelStyle}>{row.label}</td>\n            <td style={cellStyle}>\n              <input\n                aria-label={`${row.label}: all actions`}\n                checked={allChecked}\n                disabled={locked || fullAccess}\n                onChange={() => toggleRow(row)}\n                ref={(el) => {\n                  if (el) {\n                    el.indeterminate = !allChecked && someChecked\n                  }\n                }}\n                type=\"checkbox\"\n              />\n            </td>\n            {collectionActions.map((action: RbacAction) => {\n              const available = row.actions.includes(action)\n              const permission = permissionFor(row.slug, action)\n              return (\n                <td key={action} style={cellStyle}>\n                  {available ? (\n                    <input\n                      aria-label={`${row.label}: ${action}`}\n                      checked={fullAccess || selected.has(permission)}\n                      disabled={locked || fullAccess}\n                      onChange={() => toggle(permission)}\n                      type=\"checkbox\"\n                    />\n                  ) : (\n                    <span aria-hidden>—</span>\n                  )}\n                </td>\n              )\n            })}\n          </tr>\n        )\n      })\n\n  const sectionHeading = (label: string) => (\n    <tr>\n      <th colSpan={collectionActions.length + 2} style={{ ...rowLabelStyle, fontWeight: 600 }}>\n        {label}\n      </th>\n    </tr>\n  )\n\n  return (\n    <div className=\"field-type rbac-permissions-matrix\" style={{ marginBottom: 'var(--base)' }}>\n      <FieldLabel label={field?.label ?? 'Permissions'} path={path} />\n      {showError && (\n        <div style={{ color: 'var(--theme-error-500)', marginBottom: 8 }}>\n          Invalid permissions value\n        </div>\n      )}\n      {isProtected && (\n        <div style={{ color: 'var(--theme-elevation-500)', margin: '8px 0' }}>\n          This role is protected — its permissions are defined in code and cannot be edited here.\n        </div>\n      )}\n      <label style={{ alignItems: 'center', display: 'flex', gap: 8, margin: '8px 0 12px' }}>\n        <input\n          aria-label=\"Full access\"\n          checked={fullAccess}\n          disabled={locked}\n          onChange={() => toggle(FULL_ACCESS)}\n          type=\"checkbox\"\n        />\n        <span>\n          Full access — every action on every collection and global, including ones added in the\n          future\n        </span>\n      </label>\n      <div style={{ opacity: fullAccess ? 0.5 : 1, overflowX: 'auto' }}>\n        <table style={{ borderCollapse: 'collapse', width: '100%' }}>\n          <thead>\n            <tr>\n              <th aria-label=\"Collection or global\" style={rowLabelStyle} />\n              <th style={cellStyle}>All</th>\n              {collectionActions.map((action) => (\n                <th key={action} style={{ ...cellStyle, textTransform: 'capitalize' }}>\n                  {action}\n                </th>\n              ))}\n            </tr>\n          </thead>\n          <tbody>\n            {hasCollections && hasGlobals && sectionHeading('Collections')}\n            {renderRows('collection')}\n            {hasGlobals && sectionHeading('Globals')}\n            {renderRows('global')}\n          </tbody>\n        </table>\n      </div>\n      <FieldDescription\n        description={field?.admin?.description}\n        marginPlacement=\"bottom\"\n        path={path}\n      />\n    </div>\n  )\n}\n"],"mappings":"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"}

package/dist/fields/createRolesField.d.ts

@@ -0,0 +1,23 @@
+import { RelationshipField } from "payload";
+
+//#region src/fields/createRolesField.d.ts
+type CreateRolesFieldArgs = {
+  access?: RelationshipField['access'];
+  name: string;
+  override?: (field: RelationshipField) => RelationshipField;
+  rolesCollectionSlug: string;
+};
+/**
+ * Builds the roles field added to each user collection. `saveToJWT` keeps the role
+ * IDs on the token payload for consumers reading the JWT directly; access checks
+ * always resolve permissions from the user document.
+ */
+declare const createRolesField: ({
+  name,
+  access,
+  override,
+  rolesCollectionSlug
+}: CreateRolesFieldArgs) => RelationshipField;
+//#endregion
+export { CreateRolesFieldArgs, createRolesField };
+//# sourceMappingURL=createRolesField.d.ts.map

package/dist/fields/createRolesField.js

@@ -0,0 +1,27 @@
+//#region src/fields/createRolesField.ts
+/**
+* Builds the roles field added to each user collection. `saveToJWT` keeps the role
+* IDs on the token payload for consumers reading the JWT directly; access checks
+* always resolve permissions from the user document.
+*/
+const createRolesField = ({ name, access, override, rolesCollectionSlug }) => {
+	const field = {
+		name,
+		type: "relationship",
+		...access ? { access } : {},
+		admin: {
+			description: "Roles controlling what this user can access.",
+			position: "sidebar"
+		},
+		hasMany: true,
+		index: true,
+		label: "Roles",
+		relationTo: rolesCollectionSlug,
+		saveToJWT: true
+	};
+	return override ? override(field) : field;
+};
+
+//#endregion
+export { createRolesField };
+//# sourceMappingURL=createRolesField.js.map

package/dist/fields/createRolesField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createRolesField.js","names":["field: RelationshipField"],"sources":["../../src/fields/createRolesField.ts"],"sourcesContent":["import type { RelationshipField } from 'payload'\n\nexport type CreateRolesFieldArgs = {\n  access?: RelationshipField['access']\n  name: string\n  override?: (field: RelationshipField) => RelationshipField\n  rolesCollectionSlug: string\n}\n\n/**\n * Builds the roles field added to each user collection. `saveToJWT` keeps the role\n * IDs on the token payload for consumers reading the JWT directly; access checks\n * always resolve permissions from the user document.\n */\nexport const createRolesField = ({\n  name,\n  access,\n  override,\n  rolesCollectionSlug,\n}: CreateRolesFieldArgs): RelationshipField => {\n  const field: RelationshipField = {\n    name,\n    type: 'relationship',\n    ...(access ? { access } : {}),\n    admin: {\n      description: 'Roles controlling what this user can access.',\n      position: 'sidebar',\n    },\n    hasMany: true,\n    index: true,\n    label: 'Roles',\n    relationTo: rolesCollectionSlug,\n    saveToJWT: true,\n  }\n\n  return override ? override(field) : field\n}\n"],"mappings":";;;;;;AAcA,MAAa,oBAAoB,EAC/B,MACA,QACA,UACA,0BAC6C;CAC7C,MAAMA,QAA2B;EAC/B;EACA,MAAM;EACN,GAAI,SAAS,EAAE,QAAQ,GAAG,EAAE;EAC5B,OAAO;GACL,aAAa;GACb,UAAU;GACX;EACD,SAAS;EACT,OAAO;EACP,OAAO;EACP,YAAY;EACZ,WAAW;EACZ;AAED,QAAO,WAAW,SAAS,MAAM,GAAG"}

package/dist/hooks/assignFirstUserRole.d.ts

@@ -0,0 +1,22 @@
+import { CollectionBeforeChangeHook } from "payload";
+
+//#region src/hooks/assignFirstUserRole.d.ts
+type AssignFirstUserRoleArgs = {
+  firstUserRole: string;
+  rolesCollectionSlug: string;
+  rolesFieldName: string;
+};
+/**
+ * Bootstrap hook installed on the admin user collection: when the very first user
+ * is created without roles by an unauthenticated request — the admin "create first
+ * user" screen or an init seed — assign the configured role so a fresh project
+ * starts with a usable admin account.
+ */
+declare const createAssignFirstUserRoleHook: ({
+  firstUserRole,
+  rolesCollectionSlug,
+  rolesFieldName
+}: AssignFirstUserRoleArgs) => CollectionBeforeChangeHook;
+//#endregion
+export { AssignFirstUserRoleArgs, createAssignFirstUserRoleHook };
+//# sourceMappingURL=assignFirstUserRole.d.ts.map

package/dist/hooks/assignFirstUserRole.js

@@ -0,0 +1,40 @@
+//#region src/hooks/assignFirstUserRole.ts
+/**
+* Bootstrap hook installed on the admin user collection: when the very first user
+* is created without roles by an unauthenticated request — the admin "create first
+* user" screen or an init seed — assign the configured role so a fresh project
+* starts with a usable admin account.
+*/
+const createAssignFirstUserRoleHook = ({ firstUserRole, rolesCollectionSlug, rolesFieldName }) => {
+	return async ({ collection, data, operation, req }) => {
+		if (operation !== "create" || req.user || !data) return data;
+		const existingRoles = data[rolesFieldName];
+		if (Array.isArray(existingRoles) && existingRoles.length > 0) return data;
+		const { totalDocs } = await req.payload.count({
+			collection: collection.slug,
+			req
+		});
+		if (totalDocs > 0) return data;
+		const { docs } = await req.payload.find({
+			collection: rolesCollectionSlug,
+			depth: 0,
+			limit: 1,
+			overrideAccess: true,
+			req,
+			where: { name: { equals: firstUserRole } }
+		});
+		const role = docs[0];
+		if (!role) {
+			req.payload.logger.warn(`[payload-rbac] firstUserRole "${firstUserRole}" not found — first user created without roles`);
+			return data;
+		}
+		return {
+			...data,
+			[rolesFieldName]: [role.id]
+		};
+	};
+};
+
+//#endregion
+export { createAssignFirstUserRoleHook };
+//# sourceMappingURL=assignFirstUserRole.js.map

package/dist/hooks/assignFirstUserRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignFirstUserRole.js","names":[],"sources":["../../src/hooks/assignFirstUserRole.ts"],"sourcesContent":["import type { CollectionBeforeChangeHook } from 'payload'\n\nexport type AssignFirstUserRoleArgs = {\n  firstUserRole: string\n  rolesCollectionSlug: string\n  rolesFieldName: string\n}\n\n/**\n * Bootstrap hook installed on the admin user collection: when the very first user\n * is created without roles by an unauthenticated request — the admin \"create first\n * user\" screen or an init seed — assign the configured role so a fresh project\n * starts with a usable admin account.\n */\nexport const createAssignFirstUserRoleHook = ({\n  firstUserRole,\n  rolesCollectionSlug,\n  rolesFieldName,\n}: AssignFirstUserRoleArgs): CollectionBeforeChangeHook => {\n  return async ({ collection, data, operation, req }) => {\n    if (operation !== 'create' || req.user || !data) {\n      return data\n    }\n\n    const existingRoles = data[rolesFieldName]\n    if (Array.isArray(existingRoles) && existingRoles.length > 0) {\n      return data\n    }\n\n    const { totalDocs } = await req.payload.count({ collection: collection.slug, req })\n    if (totalDocs > 0) {\n      return data\n    }\n\n    const { docs } = await req.payload.find({\n      collection: rolesCollectionSlug,\n      depth: 0,\n      limit: 1,\n      overrideAccess: true,\n      req,\n      where: { name: { equals: firstUserRole } },\n    })\n    const role = docs[0]\n    if (!role) {\n      req.payload.logger.warn(\n        `[payload-rbac] firstUserRole \"${firstUserRole}\" not found — first user created without roles`,\n      )\n      return data\n    }\n\n    return { ...data, [rolesFieldName]: [role.id] }\n  }\n}\n"],"mappings":";;;;;;;AAcA,MAAa,iCAAiC,EAC5C,eACA,qBACA,qBACyD;AACzD,QAAO,OAAO,EAAE,YAAY,MAAM,WAAW,UAAU;AACrD,MAAI,cAAc,YAAY,IAAI,QAAQ,CAAC,KACzC,QAAO;EAGT,MAAM,gBAAgB,KAAK;AAC3B,MAAI,MAAM,QAAQ,cAAc,IAAI,cAAc,SAAS,EACzD,QAAO;EAGT,MAAM,EAAE,cAAc,MAAM,IAAI,QAAQ,MAAM;GAAE,YAAY,WAAW;GAAM;GAAK,CAAC;AACnF,MAAI,YAAY,EACd,QAAO;EAGT,MAAM,EAAE,SAAS,MAAM,IAAI,QAAQ,KAAK;GACtC,YAAY;GACZ,OAAO;GACP,OAAO;GACP,gBAAgB;GAChB;GACA,OAAO,EAAE,MAAM,EAAE,QAAQ,eAAe,EAAE;GAC3C,CAAC;EACF,MAAM,OAAO,KAAK;AAClB,MAAI,CAAC,MAAM;AACT,OAAI,QAAQ,OAAO,KACjB,iCAAiC,cAAc,gDAChD;AACD,UAAO;;AAGT,SAAO;GAAE,GAAG;IAAO,iBAAiB,CAAC,KAAK,GAAG;GAAE"}

package/dist/hooks/protectCredentials.d.ts

@@ -0,0 +1,29 @@
+import { CollectionBeforeChangeHook } from "payload";
+
+//#region src/hooks/protectCredentials.d.ts
+type ProtectCredentialsArgs = {
+  rolesCollectionSlug: string;
+  rolesFieldName: string;
+  /** Names of the `credentialChanges: 'self'` roles (the adminRole always is one). */
+  selfOnlyRoleNames: string[];
+  /** Slug of the user collection this hook is installed on. */
+  userCollectionSlug: string;
+};
+/**
+ * Credential guard installed on each user collection: the password, email, and
+ * username of a user holding a `credentialChanges: 'self'` role can only be
+ * changed by that user — everyone else gets a 403 no matter what permissions
+ * they hold, 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. Writes without a user (seeds,
+ * local API scripts) pass through, matching the other guards.
+ */
+declare const createProtectCredentialsHook: ({
+  rolesCollectionSlug,
+  rolesFieldName,
+  selfOnlyRoleNames,
+  userCollectionSlug
+}: ProtectCredentialsArgs) => CollectionBeforeChangeHook;
+//#endregion
+export { ProtectCredentialsArgs, createProtectCredentialsHook };
+//# sourceMappingURL=protectCredentials.d.ts.map

package/dist/hooks/protectCredentials.js

@@ -0,0 +1,43 @@
+import { normalizeRoleIds } from "./protectRolesField.js";
+import { APIError } from "payload";
+
+//#region src/hooks/protectCredentials.ts
+const identityFields = ["email", "username"];
+/**
+* Credential guard installed on each user collection: the password, email, and
+* username of a user holding a `credentialChanges: 'self'` role can only be
+* changed by that user — everyone else gets a 403 no matter what permissions
+* they hold, 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. Writes without a user (seeds,
+* local API scripts) pass through, matching the other guards.
+*/
+const createProtectCredentialsHook = ({ rolesCollectionSlug, rolesFieldName, selfOnlyRoleNames, userCollectionSlug }) => {
+	const selfOnly = new Set(selfOnlyRoleNames);
+	return async ({ data, operation, originalDoc, req }) => {
+		if (!req.user || !data || operation !== "update") return data;
+		const targetId = originalDoc?.id;
+		if (req.user.collection === userCollectionSlug && (typeof targetId === "number" || typeof targetId === "string") && String(targetId) === String(req.user.id)) return data;
+		const changingPassword = typeof data.password === "string" && data.password.length > 0;
+		const changedField = identityFields.find((field) => data[field] != null && data[field] !== originalDoc?.[field]);
+		if (!changingPassword && !changedField) return data;
+		const targetRoleIds = normalizeRoleIds(originalDoc?.[rolesFieldName]);
+		if (targetRoleIds.length === 0) return data;
+		const { docs } = await req.payload.find({
+			collection: rolesCollectionSlug,
+			depth: 0,
+			overrideAccess: true,
+			pagination: false,
+			req,
+			where: { id: { in: targetRoleIds } }
+		});
+		const protectedRole = docs.find((doc) => typeof doc.name === "string" && selfOnly.has(doc.name));
+		if (!protectedRole) return data;
+		if (changingPassword) throw new APIError(`The password of a user holding the "${String(protectedRole.name)}" role can only be changed by that user — send them a password-reset email instead.`, 403);
+		throw new APIError(`The ${changedField} of a user holding the "${String(protectedRole.name)}" role can only be changed by that user.`, 403);
+	};
+};
+
+//#endregion
+export { createProtectCredentialsHook };
+//# sourceMappingURL=protectCredentials.js.map

package/dist/hooks/protectCredentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectCredentials.js","names":["targetId: unknown"],"sources":["../../src/hooks/protectCredentials.ts"],"sourcesContent":["import type { CollectionBeforeChangeHook } from 'payload'\n\nimport { APIError } from 'payload'\n\nimport { normalizeRoleIds } from './protectRolesField.js'\n\nexport type ProtectCredentialsArgs = {\n  rolesCollectionSlug: string\n  rolesFieldName: string\n  /** Names of the `credentialChanges: 'self'` roles (the adminRole always is one). */\n  selfOnlyRoleNames: string[]\n  /** Slug of the user collection this hook is installed on. */\n  userCollectionSlug: string\n}\n\nconst identityFields = ['email', 'username'] as const\n\n/**\n * Credential guard installed on each user collection: the password, email, and\n * username of a user holding a `credentialChanges: 'self'` role can only be\n * changed by that user — everyone else gets a 403 no matter what permissions\n * they hold, and should send a password-reset email instead. Email and username\n * are locked together with password deliberately: an editable email plus the\n * reset flow would take the account over anyway. Writes without a user (seeds,\n * local API scripts) pass through, matching the other guards.\n */\nexport const createProtectCredentialsHook = ({\n  rolesCollectionSlug,\n  rolesFieldName,\n  selfOnlyRoleNames,\n  userCollectionSlug,\n}: ProtectCredentialsArgs): CollectionBeforeChangeHook => {\n  const selfOnly = new Set(selfOnlyRoleNames)\n  return async ({ data, operation, originalDoc, req }) => {\n    if (!req.user || !data || operation !== 'update') {\n      return data\n    }\n    const targetId: unknown = originalDoc?.id\n    if (\n      req.user.collection === userCollectionSlug &&\n      (typeof targetId === 'number' || typeof targetId === 'string') &&\n      String(targetId) === String(req.user.id)\n    ) {\n      return data\n    }\n\n    // `data.password` is only deleted after collection beforeChange hooks run,\n    // so a password change is visible here; identity fields are compared so a\n    // full-document save with an unchanged email still passes.\n    const changingPassword = typeof data.password === 'string' && data.password.length > 0\n    const changedField = identityFields.find(\n      (field) => data[field] != null && data[field] !== originalDoc?.[field],\n    )\n    if (!changingPassword && !changedField) {\n      return data\n    }\n\n    const targetRoleIds = normalizeRoleIds(originalDoc?.[rolesFieldName])\n    if (targetRoleIds.length === 0) {\n      return data\n    }\n    const { docs } = await req.payload.find({\n      collection: rolesCollectionSlug,\n      depth: 0,\n      overrideAccess: true,\n      pagination: false,\n      req,\n      where: { id: { in: targetRoleIds } },\n    })\n    const protectedRole = docs.find((doc) => typeof doc.name === 'string' && selfOnly.has(doc.name))\n    if (!protectedRole) {\n      return data\n    }\n\n    if (changingPassword) {\n      throw new APIError(\n        `The password of a user holding the \"${String(protectedRole.name)}\" role can only be changed by that user — send them a password-reset email instead.`,\n        403,\n      )\n    }\n    throw new APIError(\n      `The ${changedField} of a user holding the \"${String(protectedRole.name)}\" role can only be changed by that user.`,\n      403,\n    )\n  }\n}\n"],"mappings":";;;;AAeA,MAAM,iBAAiB,CAAC,SAAS,WAAW;;;;;;;;;;AAW5C,MAAa,gCAAgC,EAC3C,qBACA,gBACA,mBACA,yBACwD;CACxD,MAAM,WAAW,IAAI,IAAI,kBAAkB;AAC3C,QAAO,OAAO,EAAE,MAAM,WAAW,aAAa,UAAU;AACtD,MAAI,CAAC,IAAI,QAAQ,CAAC,QAAQ,cAAc,SACtC,QAAO;EAET,MAAMA,WAAoB,aAAa;AACvC,MACE,IAAI,KAAK,eAAe,uBACvB,OAAO,aAAa,YAAY,OAAO,aAAa,aACrD,OAAO,SAAS,KAAK,OAAO,IAAI,KAAK,GAAG,CAExC,QAAO;EAMT,MAAM,mBAAmB,OAAO,KAAK,aAAa,YAAY,KAAK,SAAS,SAAS;EACrF,MAAM,eAAe,eAAe,MACjC,UAAU,KAAK,UAAU,QAAQ,KAAK,WAAW,cAAc,OACjE;AACD,MAAI,CAAC,oBAAoB,CAAC,aACxB,QAAO;EAGT,MAAM,gBAAgB,iBAAiB,cAAc,gBAAgB;AACrE,MAAI,cAAc,WAAW,EAC3B,QAAO;EAET,MAAM,EAAE,SAAS,MAAM,IAAI,QAAQ,KAAK;GACtC,YAAY;GACZ,OAAO;GACP,gBAAgB;GAChB,YAAY;GACZ;GACA,OAAO,EAAE,IAAI,EAAE,IAAI,eAAe,EAAE;GACrC,CAAC;EACF,MAAM,gBAAgB,KAAK,MAAM,QAAQ,OAAO,IAAI,SAAS,YAAY,SAAS,IAAI,IAAI,KAAK,CAAC;AAChG,MAAI,CAAC,cACH,QAAO;AAGT,MAAI,iBACF,OAAM,IAAI,SACR,uCAAuC,OAAO,cAAc,KAAK,CAAC,sFAClE,IACD;AAEH,QAAM,IAAI,SACR,OAAO,aAAa,0BAA0B,OAAO,cAAc,KAAK,CAAC,2CACzE,IACD"}

package/dist/hooks/protectLastAdmin.d.ts

@@ -0,0 +1,28 @@
+import { CollectionBeforeChangeHook, CollectionBeforeDeleteHook } from "payload";
+
+//#region src/hooks/protectLastAdmin.d.ts
+type ProtectLastAdminArgs = {
+  adminRoleName: string;
+  rolesCollectionSlug: string;
+  rolesFieldName: string;
+  /** Every collection carrying the roles field — admin holders are counted across all of them. */
+  userCollections: string[];
+  /** Slug of the user collection this hook is installed on. */
+  userCollectionSlug: string;
+};
+/**
+ * Guards the last administrator: removing the admin role from the only user who
+ * holds it would strand the system — the escalation guard then blocks everyone
+ * from assigning a `'*'` role again. Applies to any authenticated write, including
+ * the last admin editing themselves; writes without a user (seeds, init scripts)
+ * pass through.
+ */
+declare const createProtectLastAdminChangeHook: (args: ProtectLastAdminArgs) => CollectionBeforeChangeHook;
+/**
+ * Blocks deleting the last user holding the admin role — the counterpart of the
+ * change guard for the delete operation.
+ */
+declare const createProtectLastAdminDeleteHook: (args: ProtectLastAdminArgs) => CollectionBeforeDeleteHook;
+//#endregion
+export { ProtectLastAdminArgs, createProtectLastAdminChangeHook, createProtectLastAdminDeleteHook };
+//# sourceMappingURL=protectLastAdmin.d.ts.map

package/dist/hooks/protectLastAdmin.js

@@ -0,0 +1,76 @@
+import { normalizeRoleIds } from "./protectRolesField.js";
+import { APIError } from "payload";
+
+//#region src/hooks/protectLastAdmin.ts
+const getAdminRoleId = async (req, { adminRoleName, rolesCollectionSlug }) => {
+	const { docs } = await req.payload.find({
+		collection: rolesCollectionSlug,
+		depth: 0,
+		limit: 1,
+		overrideAccess: true,
+		req,
+		where: { name: { equals: adminRoleName } }
+	});
+	const id = docs[0]?.id;
+	return typeof id === "number" || typeof id === "string" ? id : void 0;
+};
+const otherAdminUsersExist = async (req, adminRoleId, excludeId, { rolesFieldName, userCollections, userCollectionSlug }) => {
+	for (const slug of userCollections) {
+		const holdsAdminRole = { [rolesFieldName]: { in: [adminRoleId] } };
+		const { totalDocs } = await req.payload.count({
+			collection: slug,
+			overrideAccess: true,
+			req,
+			where: slug === userCollectionSlug && excludeId !== void 0 ? { and: [holdsAdminRole, { id: { not_equals: excludeId } }] } : holdsAdminRole
+		});
+		if (totalDocs > 0) return true;
+	}
+	return false;
+};
+/**
+* Guards the last administrator: removing the admin role from the only user who
+* holds it would strand the system — the escalation guard then blocks everyone
+* from assigning a `'*'` role again. Applies to any authenticated write, including
+* the last admin editing themselves; writes without a user (seeds, init scripts)
+* pass through.
+*/
+const createProtectLastAdminChangeHook = (args) => {
+	const { adminRoleName, rolesFieldName } = args;
+	return async ({ data, originalDoc, req }) => {
+		if (!req.user || !data || !(rolesFieldName in data)) return data;
+		const after = new Set(normalizeRoleIds(data[rolesFieldName]).map(String));
+		const removedIds = normalizeRoleIds(originalDoc?.[rolesFieldName]).filter((id) => !after.has(String(id)));
+		if (removedIds.length === 0) return data;
+		const adminRoleId = await getAdminRoleId(req, args);
+		if (adminRoleId === void 0 || !removedIds.some((id) => String(id) === String(adminRoleId))) return data;
+		const excludeId = originalDoc?.id;
+		if (!await otherAdminUsersExist(req, adminRoleId, excludeId, args)) throw new APIError(`Cannot remove the "${adminRoleName}" role from the last user holding it — at least one administrator must remain.`, 403);
+		return data;
+	};
+};
+/**
+* Blocks deleting the last user holding the admin role — the counterpart of the
+* change guard for the delete operation.
+*/
+const createProtectLastAdminDeleteHook = (args) => {
+	const { adminRoleName, rolesFieldName, userCollectionSlug } = args;
+	return async ({ id, req }) => {
+		if (!req.user) return;
+		const roleIds = normalizeRoleIds((await req.payload.findByID({
+			id,
+			collection: userCollectionSlug,
+			depth: 0,
+			disableErrors: true,
+			overrideAccess: true,
+			req
+		}))?.[rolesFieldName]).map(String);
+		if (roleIds.length === 0) return;
+		const adminRoleId = await getAdminRoleId(req, args);
+		if (adminRoleId === void 0 || !roleIds.includes(String(adminRoleId))) return;
+		if (!await otherAdminUsersExist(req, adminRoleId, id, args)) throw new APIError(`Cannot delete the last user holding the "${adminRoleName}" role — at least one administrator must remain.`, 403);
+	};
+};
+
+//#endregion
+export { createProtectLastAdminChangeHook, createProtectLastAdminDeleteHook };
+//# sourceMappingURL=protectLastAdmin.js.map

package/dist/hooks/protectLastAdmin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectLastAdmin.js","names":[],"sources":["../../src/hooks/protectLastAdmin.ts"],"sourcesContent":["import type {\n  CollectionBeforeChangeHook,\n  CollectionBeforeDeleteHook,\n  PayloadRequest,\n} from 'payload'\n\nimport { APIError } from 'payload'\n\nimport { normalizeRoleIds } from './protectRolesField.js'\n\nexport type ProtectLastAdminArgs = {\n  adminRoleName: string\n  rolesCollectionSlug: string\n  rolesFieldName: string\n  /** Every collection carrying the roles field — admin holders are counted across all of them. */\n  userCollections: string[]\n  /** Slug of the user collection this hook is installed on. */\n  userCollectionSlug: string\n}\n\nconst getAdminRoleId = async (\n  req: PayloadRequest,\n  { adminRoleName, rolesCollectionSlug }: ProtectLastAdminArgs,\n): Promise<number | string | undefined> => {\n  const { docs } = await req.payload.find({\n    collection: rolesCollectionSlug,\n    depth: 0,\n    limit: 1,\n    overrideAccess: true,\n    req,\n    where: { name: { equals: adminRoleName } },\n  })\n  const id = (docs[0] as { id?: unknown } | undefined)?.id\n  return typeof id === 'number' || typeof id === 'string' ? id : undefined\n}\n\nconst otherAdminUsersExist = async (\n  req: PayloadRequest,\n  adminRoleId: number | string,\n  excludeId: number | string | undefined,\n  { rolesFieldName, userCollections, userCollectionSlug }: ProtectLastAdminArgs,\n): Promise<boolean> => {\n  for (const slug of userCollections) {\n    const holdsAdminRole = { [rolesFieldName]: { in: [adminRoleId] } }\n    const { totalDocs } = await req.payload.count({\n      collection: slug,\n      overrideAccess: true,\n      req,\n      where:\n        slug === userCollectionSlug && excludeId !== undefined\n          ? { and: [holdsAdminRole, { id: { not_equals: excludeId } }] }\n          : holdsAdminRole,\n    })\n    if (totalDocs > 0) {\n      return true\n    }\n  }\n  return false\n}\n\n/**\n * Guards the last administrator: removing the admin role from the only user who\n * holds it would strand the system — the escalation guard then blocks everyone\n * from assigning a `'*'` role again. Applies to any authenticated write, including\n * the last admin editing themselves; writes without a user (seeds, init scripts)\n * pass through.\n */\nexport const createProtectLastAdminChangeHook = (\n  args: ProtectLastAdminArgs,\n): CollectionBeforeChangeHook => {\n  const { adminRoleName, rolesFieldName } = args\n  return async ({ data, originalDoc, req }) => {\n    if (!req.user || !data || !(rolesFieldName in data)) {\n      return data\n    }\n\n    const after = new Set(normalizeRoleIds(data[rolesFieldName]).map(String))\n    const removedIds = normalizeRoleIds(originalDoc?.[rolesFieldName]).filter(\n      (id) => !after.has(String(id)),\n    )\n    if (removedIds.length === 0) {\n      return data\n    }\n\n    const adminRoleId = await getAdminRoleId(req, args)\n    if (adminRoleId === undefined || !removedIds.some((id) => String(id) === String(adminRoleId))) {\n      return data\n    }\n\n    const excludeId = (originalDoc as { id?: number | string } | undefined)?.id\n    if (!(await otherAdminUsersExist(req, adminRoleId, excludeId, args))) {\n      throw new APIError(\n        `Cannot remove the \"${adminRoleName}\" role from the last user holding it — at least one administrator must remain.`,\n        403,\n      )\n    }\n\n    return data\n  }\n}\n\n/**\n * Blocks deleting the last user holding the admin role — the counterpart of the\n * change guard for the delete operation.\n */\nexport const createProtectLastAdminDeleteHook = (\n  args: ProtectLastAdminArgs,\n): CollectionBeforeDeleteHook => {\n  const { adminRoleName, rolesFieldName, userCollectionSlug } = args\n  return async ({ id, req }) => {\n    if (!req.user) {\n      return\n    }\n\n    const doc = (await req.payload.findByID({\n      id,\n      collection: userCollectionSlug,\n      depth: 0,\n      disableErrors: true,\n      overrideAccess: true,\n      req,\n    })) as null | Record<string, unknown>\n    const roleIds = normalizeRoleIds(doc?.[rolesFieldName]).map(String)\n    if (roleIds.length === 0) {\n      return\n    }\n\n    const adminRoleId = await getAdminRoleId(req, args)\n    if (adminRoleId === undefined || !roleIds.includes(String(adminRoleId))) {\n      return\n    }\n\n    if (!(await otherAdminUsersExist(req, adminRoleId, id, args))) {\n      throw new APIError(\n        `Cannot delete the last user holding the \"${adminRoleName}\" role — at least one administrator must remain.`,\n        403,\n      )\n    }\n  }\n}\n"],"mappings":";;;;AAoBA,MAAM,iBAAiB,OACrB,KACA,EAAE,eAAe,0BACwB;CACzC,MAAM,EAAE,SAAS,MAAM,IAAI,QAAQ,KAAK;EACtC,YAAY;EACZ,OAAO;EACP,OAAO;EACP,gBAAgB;EAChB;EACA,OAAO,EAAE,MAAM,EAAE,QAAQ,eAAe,EAAE;EAC3C,CAAC;CACF,MAAM,KAAM,KAAK,IAAqC;AACtD,QAAO,OAAO,OAAO,YAAY,OAAO,OAAO,WAAW,KAAK;;AAGjE,MAAM,uBAAuB,OAC3B,KACA,aACA,WACA,EAAE,gBAAgB,iBAAiB,yBACd;AACrB,MAAK,MAAM,QAAQ,iBAAiB;EAClC,MAAM,iBAAiB,GAAG,iBAAiB,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE;EAClE,MAAM,EAAE,cAAc,MAAM,IAAI,QAAQ,MAAM;GAC5C,YAAY;GACZ,gBAAgB;GAChB;GACA,OACE,SAAS,sBAAsB,cAAc,SACzC,EAAE,KAAK,CAAC,gBAAgB,EAAE,IAAI,EAAE,YAAY,WAAW,EAAE,CAAC,EAAE,GAC5D;GACP,CAAC;AACF,MAAI,YAAY,EACd,QAAO;;AAGX,QAAO;;;;;;;;;AAUT,MAAa,oCACX,SAC+B;CAC/B,MAAM,EAAE,eAAe,mBAAmB;AAC1C,QAAO,OAAO,EAAE,MAAM,aAAa,UAAU;AAC3C,MAAI,CAAC,IAAI,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,MAC5C,QAAO;EAGT,MAAM,QAAQ,IAAI,IAAI,iBAAiB,KAAK,gBAAgB,CAAC,IAAI,OAAO,CAAC;EACzE,MAAM,aAAa,iBAAiB,cAAc,gBAAgB,CAAC,QAChE,OAAO,CAAC,MAAM,IAAI,OAAO,GAAG,CAAC,CAC/B;AACD,MAAI,WAAW,WAAW,EACxB,QAAO;EAGT,MAAM,cAAc,MAAM,eAAe,KAAK,KAAK;AACnD,MAAI,gBAAgB,UAAa,CAAC,WAAW,MAAM,OAAO,OAAO,GAAG,KAAK,OAAO,YAAY,CAAC,CAC3F,QAAO;EAGT,MAAM,YAAa,aAAsD;AACzE,MAAI,CAAE,MAAM,qBAAqB,KAAK,aAAa,WAAW,KAAK,CACjE,OAAM,IAAI,SACR,sBAAsB,cAAc,iFACpC,IACD;AAGH,SAAO;;;;;;;AAQX,MAAa,oCACX,SAC+B;CAC/B,MAAM,EAAE,eAAe,gBAAgB,uBAAuB;AAC9D,QAAO,OAAO,EAAE,IAAI,UAAU;AAC5B,MAAI,CAAC,IAAI,KACP;EAWF,MAAM,UAAU,kBARH,MAAM,IAAI,QAAQ,SAAS;GACtC;GACA,YAAY;GACZ,OAAO;GACP,eAAe;GACf,gBAAgB;GAChB;GACD,CAAC,IACqC,gBAAgB,CAAC,IAAI,OAAO;AACnE,MAAI,QAAQ,WAAW,EACrB;EAGF,MAAM,cAAc,MAAM,eAAe,KAAK,KAAK;AACnD,MAAI,gBAAgB,UAAa,CAAC,QAAQ,SAAS,OAAO,YAAY,CAAC,CACrE;AAGF,MAAI,CAAE,MAAM,qBAAqB,KAAK,aAAa,IAAI,KAAK,CAC1D,OAAM,IAAI,SACR,4CAA4C,cAAc,mDAC1D,IACD"}

package/dist/hooks/protectRolesCollection.d.ts

@@ -0,0 +1,25 @@
+import { CollectionBeforeChangeHook } from "payload";
+
+//#region src/hooks/protectRolesCollection.d.ts
+type ProtectRolesCollectionArgs = {
+  /**
+   * Roles locked to their code definition. The escalation check is skipped for
+   * them: the protected-role guard (which runs first) only lets through writes
+   * that exactly restore the code-defined permissions, and that restore must stay
+   * possible even when nobody holds the drifted-away permissions anymore.
+   */
+  protectedRoleNames?: string[];
+};
+/**
+ * Privilege-escalation guard installed on the roles collection: a user editing or
+ * creating a role may only add permissions their own roles already cover — without
+ * this, anyone with update access on the roles collection could widen their own
+ * role to full access. Users with `'*'` may grant anything; writes without a user
+ * pass through.
+ */
+declare const createProtectRolesCollectionHook: ({
+  protectedRoleNames
+}?: ProtectRolesCollectionArgs) => CollectionBeforeChangeHook;
+//#endregion
+export { ProtectRolesCollectionArgs, createProtectRolesCollectionHook };
+//# sourceMappingURL=protectRolesCollection.d.ts.map

package/dist/hooks/protectRolesCollection.js

@@ -0,0 +1,30 @@
+import { missingPermissions } from "../permissions.js";
+import { getUserPermissions } from "../utilities/getUserPermissions.js";
+import { APIError } from "payload";
+
+//#region src/hooks/protectRolesCollection.ts
+/**
+* Privilege-escalation guard installed on the roles collection: a user editing or
+* creating a role may only add permissions their own roles already cover — without
+* this, anyone with update access on the roles collection could widen their own
+* role to full access. Users with `'*'` may grant anything; writes without a user
+* pass through.
+*/
+const createProtectRolesCollectionHook = ({ protectedRoleNames = [] } = {}) => {
+	const protectedNames = new Set(protectedRoleNames);
+	return async ({ data, originalDoc, req }) => {
+		if (!req.user || !data || !("permissions" in data)) return data;
+		const name = typeof originalDoc?.name === "string" ? originalDoc.name : typeof data.name === "string" ? data.name : void 0;
+		if (name !== void 0 && protectedNames.has(name)) return data;
+		const previous = new Set(Array.isArray(originalDoc?.permissions) ? originalDoc.permissions : []);
+		const added = (Array.isArray(data.permissions) ? data.permissions : []).filter((permission) => typeof permission === "string" && !previous.has(permission));
+		if (added.length === 0) return data;
+		const missing = missingPermissions(await getUserPermissions(req), added);
+		if (missing.length > 0) throw new APIError(`You cannot grant permissions you do not hold: ${missing.join(", ")}`, 403);
+		return data;
+	};
+};
+
+//#endregion
+export { createProtectRolesCollectionHook };
+//# sourceMappingURL=protectRolesCollection.js.map

package/dist/hooks/protectRolesCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectRolesCollection.js","names":[],"sources":["../../src/hooks/protectRolesCollection.ts"],"sourcesContent":["import type { CollectionBeforeChangeHook } from 'payload'\n\nimport { APIError } from 'payload'\n\nimport { missingPermissions } from '../permissions.js'\nimport { getUserPermissions } from '../utilities/getUserPermissions.js'\n\nexport type ProtectRolesCollectionArgs = {\n  /**\n   * Roles locked to their code definition. The escalation check is skipped for\n   * them: the protected-role guard (which runs first) only lets through writes\n   * that exactly restore the code-defined permissions, and that restore must stay\n   * possible even when nobody holds the drifted-away permissions anymore.\n   */\n  protectedRoleNames?: string[]\n}\n\n/**\n * Privilege-escalation guard installed on the roles collection: a user editing or\n * creating a role may only add permissions their own roles already cover — without\n * this, anyone with update access on the roles collection could widen their own\n * role to full access. Users with `'*'` may grant anything; writes without a user\n * pass through.\n */\nexport const createProtectRolesCollectionHook = ({\n  protectedRoleNames = [],\n}: ProtectRolesCollectionArgs = {}): CollectionBeforeChangeHook => {\n  const protectedNames = new Set(protectedRoleNames)\n  return async ({ data, originalDoc, req }) => {\n    if (!req.user || !data || !('permissions' in data)) {\n      return data\n    }\n\n    const name =\n      typeof originalDoc?.name === 'string'\n        ? originalDoc.name\n        : typeof data.name === 'string'\n          ? data.name\n          : undefined\n    if (name !== undefined && protectedNames.has(name)) {\n      return data\n    }\n\n    const previous = new Set<string>(\n      Array.isArray(originalDoc?.permissions) ? originalDoc.permissions : [],\n    )\n    const added = (Array.isArray(data.permissions) ? data.permissions : []).filter(\n      (permission): permission is string =>\n        typeof permission === 'string' && !previous.has(permission),\n    )\n    if (added.length === 0) {\n      return data\n    }\n\n    const granted = await getUserPermissions(req)\n    const missing = missingPermissions(granted, added)\n    if (missing.length > 0) {\n      throw new APIError(`You cannot grant permissions you do not hold: ${missing.join(', ')}`, 403)\n    }\n\n    return data\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAwBA,MAAa,oCAAoC,EAC/C,qBAAqB,EAAE,KACO,EAAE,KAAiC;CACjE,MAAM,iBAAiB,IAAI,IAAI,mBAAmB;AAClD,QAAO,OAAO,EAAE,MAAM,aAAa,UAAU;AAC3C,MAAI,CAAC,IAAI,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,MAC3C,QAAO;EAGT,MAAM,OACJ,OAAO,aAAa,SAAS,WACzB,YAAY,OACZ,OAAO,KAAK,SAAS,WACnB,KAAK,OACL;AACR,MAAI,SAAS,UAAa,eAAe,IAAI,KAAK,CAChD,QAAO;EAGT,MAAM,WAAW,IAAI,IACnB,MAAM,QAAQ,aAAa,YAAY,GAAG,YAAY,cAAc,EAAE,CACvE;EACD,MAAM,SAAS,MAAM,QAAQ,KAAK,YAAY,GAAG,KAAK,cAAc,EAAE,EAAE,QACrE,eACC,OAAO,eAAe,YAAY,CAAC,SAAS,IAAI,WAAW,CAC9D;AACD,MAAI,MAAM,WAAW,EACnB,QAAO;EAIT,MAAM,UAAU,mBADA,MAAM,mBAAmB,IAAI,EACD,MAAM;AAClD,MAAI,QAAQ,SAAS,EACnB,OAAM,IAAI,SAAS,iDAAiD,QAAQ,KAAK,KAAK,IAAI,IAAI;AAGhG,SAAO"}