Fixes #37665 - Context-based frontend permission management

Introduce a faster alternative to API based permission management in the frontend
based on ForemanContext

- Add Permitted component
- Add permission hooks
- Add ContextController
- Add JS permission constants
- Add rake task to export permissions
- Add permission management page to developer docs

Author: Thorben-D

app/helpers/application_helper.rb

@@ -418,6 +418,7 @@ def core_app_metadata
       user_settings: {
         lab_features: Setting[:lab_features],
       },
+      permissions: (User.current.admin? ? Permission.all : User.current.permissions).pluck(:name),
     }.compact
   end
 

developer_docs/handling_user_permissions.asciidoc

@@ -0,0 +1,145 @@
+[[handling_user_permissions]]
+
+# Handling user permissions
+:toc: right
+:toclevels: 5
+:source-highlighter: rouge
+
+## Frontend
+
+[IMPORTANT]
+====
+*None* of these solutions are a replacement for authoritative and well-defined permission-management in the backend!
+====
+
+Consider the following:
+
+* A component `MyComponent` that should be rendered if a user is granted the
+* `my_permission` permission and
+* a component `MyUnpermittedComponent` that should be rendered if they aren't
+
+In this section we will explore 4 different approaches to solve this problem.
+
+### Via context-based permission management
+
+#### Component: Permitted
+*Component location*: default export of _/components/Permitted/Permitted.js_
+
+This component abstracts the conditional rendering scheme and provides the following API:
+
+|===
+|Prop |Type |Note
+
+|*requiredPermissions*
+|`Array<String>`
+|An array of permissions required to render `children`.
+
+|*children*
+|`React.ReactNode`
+|A component to be rendered if a user is granted the required permission(s).
+
+|*unpermittedComponent*
+|`React.ReactNode`
+|A component to be rendered if a user is *not* granted the required permission(s). Defaults to PermissionDenied.
+|===
+
+Additionally, the propTypes-check validates the following conditions:
+
+* `requiredPermissions` is given
+* `requiredPermissions` is not an empty array
+
+Our example goal may be achieved as follows:
+[source, jsx]
+----
+import React from 'react';
+import { Permitted } from 'foremanReact/components/Permitted/Permitted';
+
+export const MyComponentWrapper = () => (
+  <Permitted
+    requiredPermissions={["my_permission"]}
+    unpermittedComponent={<MyUnpermittedComponent />}
+  >
+    <MyComponent />
+  </Permitted>
+);
+----
+
+Since the amount of code added is relatively small and trivial, it is rarely necessary to make use of a wrapper component with this approach.
+
+#### Hook: usePermissions
+*Hook location*: export of _/common/hooks/Permissions/permissionHooks.js_
+
+This hook provides an interface with the context and allows checking whether the user is granted *multiple* permissions.
+Returns `true` if the provided permissions are granted to the user and `false` if not. +
+
+The hook provides the following API:
+
+|===
+|Parameter |Type |Note
+
+|*requiredPermissions*
+|`Array<String>`
+|An array of permission names
+|===
+
+Using `usePermissions`, one may solve our initial problem as follows:
+[source, jsx]
+----
+import React from 'react';
+import { usePermissions } from 'foremanReact/common/hooks/Permissions/permissionHooks';
+
+export const MyComponentWrapper = () => {
+  const isUserAuthed = usePermission(['my_permission']);
+
+  if (isUserAuthed) {
+    return <MyComponent />;
+  }
+  return <MyUnpermittedComponent />;
+};
+----
+#### Considerations
+
+The advantage of the context-based approach is that the permission data is essentially cached and available to every component via the React context.
+This context is set every time the ReactApp is mounted.
+This happens when a user navigates from a *server-rendered* page to a *frontend-rendered* page.
+Navigating between frontend-rendered pages does *not* refresh the context.
+Currently (2025-11-14), this does not pose a problem for permission management, as every page that may grant permissions to users is rendered serverside.
+
+
+### Via API-based permission management
+#### Boilerplate
+To keep `MyComponent` clean and free of permission-handling code, it often makes sense to wrap it in a component dedicated to conditionally rendering it.
+
+[source,jsx]
+----
+import React from 'react';
+import { useAPI } from 'foremanReact/common/hooks/API/APIHooks'; // Plugin import | Core import differs
+
+export const MyComponentWrapper = () => {
+  const {
+    response: { results },
+    status,
+  } = useAPI('get', '/api/v2/permissions/current_permissions'); // Current user permissions
+
+  if (status === 'PENDING') {
+    // Handle API pending
+    return null;
+  } else if (status === 'ERROR') {
+    // Handle API error
+    return null;
+  } else if (status === 'RESOLVED') {
+    if (
+      results.some(permission => permission.name === 'my_permission')
+    ) {
+      return <MyComponent />;
+    }
+    return <MyUnpermittedComponent />
+  }
+  return null;
+};
+----
+
+#### Considerations
+The API request will add around *200-250 ms* of load time to your component tree.
+It is advised to structure your component-hierarchy in such a way that this API request is made near the top to avoid re-running it on re-renders.
+Alternatively, check user permissions <<_via_context_based_permission_management>>, which is much faster.

lib/tasks/export_permissions.rake

@@ -0,0 +1,11 @@
+require File.join(Rails.root, 'db', 'seeds.d', '020-permissions_list.rb')
+
+desc 'Export Foreman permissions to JavaScript'
+task export_permissions: :environment do
+  formatted = PermissionsList.permissions.map { |permission| "export const #{permission[1].upcase} = '#{permission[1]}';\n" }
+  File.open(File.join(Rails.root, 'webpack/assets/javascripts/react_app/permissions.js'), 'w') do |f|
+    f.puts '/* eslint-disable */'
+    f.puts '/* This file is automatically generated. Run "bundle exec rake export_permissions" to regenerate it. */'
+    formatted.each { |line| f.puts line }
+  end
+end

webpack/assets/javascripts/react_app/Root/Context/ForemanContext.js

@@ -16,6 +16,7 @@ export const useForemanDocUrl = () => useForemanMetadata().docUrl;
 export const useForemanOrganization = () => useForemanMetadata().organization;
 export const useForemanLocation = () => useForemanMetadata().location;
 export const useForemanUser = () => useForemanMetadata().user;
+export const useForemanPermissions = () => useForemanMetadata().permissions;
 
 export const getHostsPageUrl = displayNewHostsPage =>
   displayNewHostsPage ? '/new/hosts' : '/hosts';

webpack/assets/javascripts/react_app/Root/ReactApp.js

@@ -13,6 +13,7 @@ import ErrorBoundary from '../components/common/ErrorBoundary';
 import ConfirmModal from '../components/ConfirmModal';
 
 const ReactApp = ({ layout, metadata, toasts }) => {
+  metadata.permissions = new Set(metadata.permissions);
   const [context, setContext] = useState({ metadata });
   const contextData = { context, setContext };
   const ForemanContext = getForemanContext(contextData);

webpack/assets/javascripts/react_app/common/hooks/Permissions/permissionHooks.fixtures.js

@@ -0,0 +1,5 @@
+
+export const validPermission = "test_permission_one"
+export const validPermissionsArray = [validPermission, "test_permission_two"]
+export const invalidPermission = "test_permission_one_invalid"
+export const invalidPermissionsArray = [invalidPermission, "test_permission_two_invalid"]

webpack/assets/javascripts/react_app/common/hooks/Permissions/permissionHooks.js

@@ -0,0 +1,14 @@
+import { useForemanPermissions } from '../../../Root/Context/ForemanContext';
+
+/**
+ * Custom hook to check whether a user is granted an array of permissions.
+ *
+ * @param requiredPermissions An array of permission names.
+ * @returns {boolean} Indicates whether the current user is granted the given permissions.
+ */
+export const usePermissions = (requiredPermissions = []) => {
+  const userPermissions = useForemanPermissions();
+  return requiredPermissions.every(permission =>
+    userPermissions.has(permission)
+  );
+};

webpack/assets/javascripts/react_app/common/hooks/Permissions/permissionHooks.test.js

@@ -0,0 +1,21 @@
+import '@testing-library/jest-dom'
+import {usePermissions} from "./permissionHooks";
+import {
+  invalidPermissionsArray,
+  validPermissionsArray
+} from "./permissionHooks.fixtures";
+
+
+describe('permissionHooks', () => {
+
+  describe('usePermissions', () => {
+    it('should correctly evaluate multiple valid permissions', () => {
+      const result = usePermissions(validPermissionsArray)
+      expect(result).toBe(true)
+    })
+    it('should correctly evaluate multiple invalid permissions', () => {
+      const result = usePermissions(invalidPermissionsArray)
+      expect(result).toBe(false)
+    })
+  });
+})

webpack/assets/javascripts/react_app/components/Permitted/Permitted.fixtures.js

@@ -0,0 +1,13 @@
+
+export const testString = "Unambiguous test string"
+export const unPermittedTestString = "Unambiguous unpermitted test string"
+export const permissionString = "test_permission_one"
+export const permissionsArray = [permissionString, "test_permission_two"]
+export const invalidPermissionString = "some_other_permission_one"
+export const invalidPermissionsArray = [invalidPermissionString, "some_other_permission_two"]
+
+// Console warnings
+export const noPermissionPropWarning =
+         'Warning: Failed prop type: The prop \"requiredPermissions\" must be set in Permitted.\n    in Permitted';
+export const requiredPermissionsEmptyWarning = "Warning: Failed prop type: requiredPermissions can not be an empty array.\n    in Permitted"
+export const requiredPermissionsTypeWarning = "Warning: Failed prop type: Invalid prop `requiredPermissions` of type `string` supplied to `Permitted`, expected `array`."

webpack/assets/javascripts/react_app/components/Permitted/Permitted.js

@@ -0,0 +1,78 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+
+import { useForemanPermissions } from '../../Root/Context/ForemanContext';
+import PermissionDenied from '../PermissionDenied';
+
+/**
+ * Component to conditionally render a node if the current user has the requested permissions.
+ * Multiple permissions may be required by passing an array via **requiredPermissions**.
+ *
+ * @param {array<string>} requiredPermissions: An array of permission string.
+ * @param {node} children: The node to be conditionally rendered
+ * @param {node} unpermittedComponent: Component to be rendered if the desired permission is not met. Defaults to null.
+ */
+const Permitted = ({ requiredPermissions, children, unpermittedComponent }) => {
+  const userPermissions = useForemanPermissions();
+
+  const isPermitted =
+    requiredPermissions &&
+    requiredPermissions.every(permission => userPermissions.has(permission));
+  return (
+    <>
+      {' '}
+      {isPermitted
+        ? children
+        : unpermittedComponent || (
+            <PermissionDenied
+              missingPermissions={
+                typeof requiredPermissions === 'object'
+                  ? requiredPermissions.filter(
+                      rPerm => !userPermissions.has(rPerm)
+                    )
+                  : []
+              }
+            />
+          )}{' '}
+    </>
+  );
+};
+
+const propsCheck = (props, propName, componentName) => {
+  if (props.requiredPermissions === undefined) {
+    return new Error(
+      `The prop "requiredPermissions" must be set in ${componentName}.`
+    );
+  }
+
+  PropTypes.checkPropTypes(
+    {
+      requiredPermissions: PropTypes.array,
+    },
+    { requiredPermissions: props.requiredPermissions },
+    'prop',
+    'Permitted'
+  );
+  if (
+    typeof props.requiredPermissions === 'object' &&
+    props.requiredPermissions.length === 0
+  ) {
+    return new Error('requiredPermissions can not be an empty array.');
+  }
+
+  return null;
+};
+
+/* eslint-disable react/require-default-props */
+Permitted.propTypes = {
+  requiredPermissions: propsCheck,
+  children: PropTypes.node,
+  unpermittedComponent: PropTypes.node,
+};
+/* eslint-enable react/require-default-props */
+Permitted.defaultProps = {
+  children: null,
+  unpermittedComponent: null,
+};
+
+export default Permitted;