feat: add granular group-based permissions with category restrictions

Groups can now have their permissions scoped to specific categories.
When no category restrictions are set, rights apply globally (backward
compatible). This enables controlled external contributions where users
can be restricted to specific categories via group membership.

New table faqgroup_right_category links group rights to categories.
Added API endpoints for managing category restrictions, admin UI panel
for configuring restrictions per permission, and hasPermissionForCategory()
for category-scoped permission checks.

This feature implements and closes #3780.

Author: thorsten

phpmyfaq/admin/assets/src/api/group.test.ts

@@ -1,9 +1,19 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { fetchAllGroups, fetchAllUsersForGroups, fetchAllMembers, fetchGroup, fetchGroupRights } from './group';
+import {
+  fetchAllGroups,
+  fetchAllUsersForGroups,
+  fetchAllMembers,
+  fetchGroup,
+  fetchGroupRights,
+  fetchGroupCategoryRestrictions,
+  saveGroupCategoryRestrictions,
+  fetchCategoriesForRestrictions,
+} from './group';
 import * as fetchWrapperModule from './fetch-wrapper';
 
 vi.mock('./fetch-wrapper', () => ({
   fetchJson: vi.fn(),
+  fetchWrapper: vi.fn(),
 }));
 
 describe('fetchAllGroups', () => {
@@ -164,3 +174,92 @@ describe('fetchGroupRights', () => {
     await expect(fetchGroupRights(groupId)).rejects.toThrow('Network response was not ok.');
   });
 });
+
+describe('fetchGroupCategoryRestrictions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should fetch category restrictions for a group', async () => {
+    const mockResponse = { '1': [10, 20], '3': [30] };
+    vi.spyOn(fetchWrapperModule, 'fetchJson').mockResolvedValue(mockResponse);
+
+    const groupId = '5';
+    const result = await fetchGroupCategoryRestrictions(groupId);
+
+    expect(result).toEqual(mockResponse);
+    expect(fetchWrapperModule.fetchJson).toHaveBeenCalledWith(`./api/group/category-restrictions/${groupId}`, {
+      method: 'GET',
+      cache: 'no-cache',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      redirect: 'follow',
+      referrerPolicy: 'no-referrer',
+    });
+  });
+
+  it('should throw an error if the network response is not ok', async () => {
+    vi.spyOn(fetchWrapperModule, 'fetchJson').mockRejectedValue(new Error('Network response was not ok.'));
+
+    await expect(fetchGroupCategoryRestrictions('5')).rejects.toThrow('Network response was not ok.');
+  });
+});
+
+describe('saveGroupCategoryRestrictions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should save category restrictions for a group right', async () => {
+    const mockResponse = { ok: true, status: 200 } as Response;
+    vi.spyOn(fetchWrapperModule, 'fetchWrapper').mockResolvedValue(mockResponse);
+
+    const result = await saveGroupCategoryRestrictions('5', '1', [10, 20]);
+
+    expect(result).toEqual(mockResponse);
+    expect(fetchWrapperModule.fetchWrapper).toHaveBeenCalledWith('./api/group/category-restrictions', {
+      method: 'POST',
+      cache: 'no-cache',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ groupId: 5, rightId: 1, categoryIds: [10, 20] }),
+      redirect: 'follow',
+      referrerPolicy: 'no-referrer',
+    });
+  });
+});
+
+describe('fetchCategoriesForRestrictions', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should fetch all categories for restriction picker', async () => {
+    const mockResponse = [
+      { id: 1, name: 'General', parent_id: 0 },
+      { id: 2, name: 'Technical', parent_id: 0 },
+    ];
+    vi.spyOn(fetchWrapperModule, 'fetchJson').mockResolvedValue(mockResponse);
+
+    const result = await fetchCategoriesForRestrictions();
+
+    expect(result).toEqual(mockResponse);
+    expect(fetchWrapperModule.fetchJson).toHaveBeenCalledWith('./api/group/categories', {
+      method: 'GET',
+      cache: 'no-cache',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      redirect: 'follow',
+      referrerPolicy: 'no-referrer',
+    });
+  });
+
+  it('should throw an error if the network response is not ok', async () => {
+    vi.spyOn(fetchWrapperModule, 'fetchJson').mockRejectedValue(new Error('Network response was not ok.'));
+
+    await expect(fetchCategoriesForRestrictions()).rejects.toThrow('Network response was not ok.');
+  });
+});

phpmyfaq/admin/assets/src/api/group.ts

@@ -13,8 +13,8 @@
  * @since     2023-01-02
  */
 
-import { Group, Member, User } from '../interfaces';
-import { fetchJson } from './fetch-wrapper';
+import { CategoryItem, CategoryRestrictions, Group, Member, User } from '../interfaces';
+import { fetchJson, fetchWrapper } from './fetch-wrapper';
 
 export const fetchAllGroups = async (): Promise<Group[]> => {
   return (await fetchJson('./api/group/groups', {
@@ -75,3 +75,44 @@ export const fetchGroupRights = async (groupId: string): Promise<string[]> => {
     referrerPolicy: 'no-referrer',
   })) as string[];
 };
+
+export const fetchGroupCategoryRestrictions = async (groupId: string): Promise<CategoryRestrictions> => {
+  return (await fetchJson(`./api/group/category-restrictions/${groupId}`, {
+    method: 'GET',
+    cache: 'no-cache',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    redirect: 'follow',
+    referrerPolicy: 'no-referrer',
+  })) as CategoryRestrictions;
+};
+
+export const saveGroupCategoryRestrictions = async (
+  groupId: string,
+  rightId: string,
+  categoryIds: number[]
+): Promise<Response> => {
+  return await fetchWrapper('./api/group/category-restrictions', {
+    method: 'POST',
+    cache: 'no-cache',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ groupId: parseInt(groupId), rightId: parseInt(rightId), categoryIds }),
+    redirect: 'follow',
+    referrerPolicy: 'no-referrer',
+  });
+};
+
+export const fetchCategoriesForRestrictions = async (): Promise<CategoryItem[]> => {
+  return (await fetchJson('./api/group/categories', {
+    method: 'GET',
+    cache: 'no-cache',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    redirect: 'follow',
+    referrerPolicy: 'no-referrer',
+  })) as CategoryItem[];
+};

phpmyfaq/admin/assets/src/group/groups.ts

@@ -15,9 +15,18 @@
  * @since     2023-01-04
  */
 
-import { fetchAllGroups, fetchAllMembers, fetchAllUsersForGroups, fetchGroup, fetchGroupRights } from '../api';
+import {
+  fetchAllGroups,
+  fetchAllMembers,
+  fetchAllUsersForGroups,
+  fetchCategoriesForRestrictions,
+  fetchGroup,
+  fetchGroupCategoryRestrictions,
+  fetchGroupRights,
+  saveGroupCategoryRestrictions,
+} from '../api';
 import { selectAll, unSelectAll } from '../utils';
-import { Group, Member, User } from '../interfaces';
+import { CategoryItem, CategoryRestrictions, Group, Member, User } from '../interfaces';
 
 export const handleGroups = async (): Promise<void> => {
   clearGroupList();
@@ -74,6 +83,26 @@ export const handleGroups = async (): Promise<void> => {
   unSelectAllMembers.addEventListener('click', (): void => {
     unSelectAll('group_member_list');
   });
+
+  // Category restrictions save button
+  const saveCategoryRestrictions = document.getElementById('saveCategoryRestrictions') as HTMLButtonElement;
+  if (saveCategoryRestrictions) {
+    saveCategoryRestrictions.addEventListener('click', async (event: Event): Promise<void> => {
+      event.preventDefault();
+      await handleCategoryRestrictionsSave();
+    });
+  }
+
+  // Update category restrictions panel when rights checkboxes change
+  document.getElementById('groupRights')?.addEventListener('change', (event: Event): void => {
+    const target = event.target as HTMLInputElement;
+    if (target.type === 'checkbox' && target.classList.contains('permission')) {
+      const container = document.getElementById('categoryRestrictionsBody');
+      if (container) {
+        renderCategoryRestrictions(container);
+      }
+    }
+  });
 };
 
 const handleGroupSelect = async (event: Event): Promise<void> => {
@@ -88,6 +117,7 @@ const handleGroupSelect = async (event: Event): Promise<void> => {
     await getUserList();
     clearMemberList();
     await getMemberList(groupId);
+    await loadCategoryRestrictions(groupId);
 
     // Activate user inputs
     const saveGroupDetails = document.getElementById('saveGroupDetails') as HTMLButtonElement;
@@ -96,13 +126,17 @@ const handleGroupSelect = async (event: Event): Promise<void> => {
     const deleteGroup = document.getElementById('deleteGroup') as HTMLButtonElement;
     const groupAddMember = document.getElementById('groupAddMember') as HTMLButtonElement;
     const groupRemoveMember = document.getElementById('groupRemoveMember') as HTMLButtonElement;
+    const saveCategoryRestrictions = document.getElementById('saveCategoryRestrictions') as HTMLButtonElement;
 
     saveGroupDetails.disabled = false;
     saveMembersList.disabled = false;
     saveGroupRights.disabled = false;
     deleteGroup.disabled = false;
     groupAddMember.disabled = false;
     groupRemoveMember.disabled = false;
+    if (saveCategoryRestrictions) {
+      saveCategoryRestrictions.disabled = false;
+    }
 
     document.querySelectorAll<HTMLInputElement>('.permission').forEach((item: HTMLInputElement): void => {
       item.disabled = false;
@@ -279,3 +313,101 @@ const removeGroupMembers = (): void => {
     }
   }
 };
+
+let cachedCategories: CategoryItem[] = [];
+let currentRestrictions: CategoryRestrictions = {};
+
+const loadCategoryRestrictions = async (groupId: string): Promise<void> => {
+  const container = document.getElementById('categoryRestrictionsBody');
+  if (!container) {
+    return;
+  }
+
+  if (cachedCategories.length === 0) {
+    cachedCategories = await fetchCategoriesForRestrictions();
+  }
+
+  currentRestrictions = await fetchGroupCategoryRestrictions(groupId);
+
+  renderCategoryRestrictions(container);
+};
+
+const renderCategoryRestrictions = (container: HTMLElement): void => {
+  const checkedRights = document.querySelectorAll<HTMLInputElement>('#groupRights input[type=checkbox]:checked');
+
+  container.innerHTML = '';
+
+  if (checkedRights.length === 0) {
+    container.innerHTML = '<p class="text-muted">No permissions assigned to this group.</p>';
+    return;
+  }
+
+  checkedRights.forEach((checkbox: HTMLInputElement): void => {
+    const rightId = checkbox.value;
+    const label = checkbox.closest('.form-check')?.querySelector('label')?.textContent?.trim() || `Right ${rightId}`;
+    const restrictedCategoryIds = currentRestrictions[rightId] || [];
+
+    const wrapper = document.createElement('div');
+    wrapper.className = 'mb-3';
+
+    const labelElement = document.createElement('label');
+    labelElement.className = 'form-label fw-semibold';
+    labelElement.textContent = label;
+    wrapper.appendChild(labelElement);
+
+    const select = document.createElement('select');
+    select.className = 'form-select form-select-sm';
+    select.multiple = true;
+    select.size = 4;
+    select.dataset.rightId = rightId;
+
+    cachedCategories.forEach((cat: CategoryItem): void => {
+      const option = document.createElement('option');
+      option.value = String(cat.id);
+      option.textContent = cat.name;
+      option.selected = restrictedCategoryIds.includes(cat.id);
+      select.appendChild(option);
+    });
+
+    wrapper.appendChild(select);
+
+    const helpText = document.createElement('div');
+    helpText.className = 'form-text';
+    helpText.textContent = 'Select categories to restrict this permission. Leave empty for unrestricted access.';
+    wrapper.appendChild(helpText);
+
+    container.appendChild(wrapper);
+  });
+};
+
+export const handleCategoryRestrictionsSave = async (): Promise<void> => {
+  const groupListSelect = document.getElementById('group_list_select') as HTMLSelectElement;
+  if (!groupListSelect) {
+    return;
+  }
+
+  const groupId = groupListSelect.value;
+  if (!groupId) {
+    return;
+  }
+
+  const container = document.getElementById('categoryRestrictionsBody');
+  if (!container) {
+    return;
+  }
+
+  const selects = container.querySelectorAll<HTMLSelectElement>('select[data-right-id]');
+
+  for (const select of selects) {
+    const rightId = select.dataset.rightId;
+    if (!rightId) {
+      continue;
+    }
+
+    const selectedCategoryIds = [...select.options]
+      .filter((option: HTMLOptionElement): boolean => option.selected)
+      .map((option: HTMLOptionElement): number => parseInt(option.value));
+
+    await saveGroupCategoryRestrictions(groupId, rightId, selectedCategoryIds);
+  }
+};

phpmyfaq/admin/assets/src/interfaces/Group.ts

@@ -4,3 +4,13 @@ export interface Group {
   description?: string;
   auto_join?: string;
 }
+
+export interface CategoryItem {
+  id: number;
+  name: string;
+  parent_id: number;
+}
+
+export interface CategoryRestrictions {
+  [rightId: string]: number[];
+}

phpmyfaq/assets/templates/admin/user/group.twig

@@ -204,6 +204,22 @@
           </div>
         </form>
       </div>
+
+      <div id="groupCategoryRestrictions" class="card shadow mb-4">
+        <h5 class="card-header py-3">
+          <i aria-hidden="true" class="bi bi-folder-check"></i> {{ 'ad_group_category_restrictions' | translate }}
+        </h5>
+        <div class="card-body" id="categoryRestrictionsBody">
+          <p class="text-muted">{{ 'ad_group_category_restrictions_help' | translate }}</p>
+        </div>
+        <div class="card-footer">
+          <div class="card-button text-end">
+            <button id="saveCategoryRestrictions" class="btn btn-primary" type="button" disabled>
+              {{ 'ad_gen_save' | translate }}
+            </button>
+          </div>
+        </div>
+      </div>
     </div>
   </div>
 {% endblock %}