feat: implement permission validation API and hooks for authz

Author: bra-i-am

docs/how_tos/permissions.md

@@ -0,0 +1,147 @@
+# How to: Query Permissions from openedx-authz
+
+## Overview
+
+`@openedx/frontend-base` provides hooks and utilities to validate user permissions against the
+`openedx-authz` service. Results are cached automatically via TanStack Query to minimize calls
+to the backend.
+
+## Prerequisites
+
+Ensure your app root is wrapped with a `QueryClientProvider` from `@tanstack/react-query`.
+
+---
+
+## Core Concepts
+
+### Permission query shape
+
+Permissions are expressed as a key/value map where:
+- **keys** are arbitrary semantic names you choose (e.g. `canEditGrading`)
+- **values** describe the `action` string and optional `scope` (resource identifier)
+
+```typescript
+import type { PermissionValidationQuery } from '@openedx/frontend-base';
+
+const query: PermissionValidationQuery = {
+  canViewGrading: {
+    action: 'courses.view_grading_settings',
+    scope: 'course-v1:org+course+run',
+  },
+  canEditGrading: {
+    action: 'courses.edit_grading_settings',
+    scope: 'course-v1:org+course+run',
+  },
+};
+```
+
+### Caching
+
+Results are cached using TanStack Query. The cache key includes the query object and the
+resolved `apiBaseUrl`, so different backends and different permission sets are cached
+independently. Results are reused across components that request the same permissions within
+one session.
+
+---
+
+## `usePermissions`
+
+The single hook for querying permissions. Requires a `featureEnabled` boolean — always
+pass the resolved waffle flag value so the caller explicitly opts in or out of authz.
+Permission keys are spread at the top level — no nested `.permissions` object.
+
+```typescript
+import { usePermissions } from '@openedx/frontend-base';
+import { getConfig } from '@edx/frontend-platform';
+
+// featureEnabled is required — always pass the resolved waffle flag boolean:
+const { enableAuthz } = useWaffleFlags(resourceId);
+const { isLoading, isAuthzEnabled, canViewGrading, canEditGrading } = usePermissions(
+  {
+    canViewGrading: { action: 'courses.view_grading_settings', scope: resourceId },
+    canEditGrading: { action: 'courses.edit_grading_settings', scope: resourceId },
+  },
+  enableAuthz ?? false,
+);
+
+// Override the backend URL (e.g. MFEs using @edx/frontend-platform):
+const { isLoading, canViewGrading } = usePermissions(
+  { canViewGrading: { action: 'courses.view_grading_settings', scope: courseId } },
+  enableAuthz ?? false,
+  { apiBaseUrl: getConfig().LMS_BASE_URL },
+);
+
+if (!canViewGrading) { return <PermissionDeniedAlert />; }
+```
+
+When `featureEnabled` is `false`: no API call is made and all keys return `true`,
+preserving the pre-authz behavior during rollout.
+
+---
+
+## Recommended: create an MFE-specific wrapper
+
+Avoid calling `usePermissions` directly in every component. Create a single MFE-level
+wrapper that encapsulates the waffle flag check and base URL:
+
+```typescript
+import { usePermissions } from '@openedx/frontend-base';
+import { getConfig } from '@edx/frontend-platform';
+import { useWaffleFlags } from './waffleHooks'; // your MFE's waffle flag hook
+import type { PermissionValidationQuery } from '@openedx/frontend-base';
+
+export const useResourcePermissions = <Query extends PermissionValidationQuery>(
+  resourceId: string,
+  permissions: Query,
+) => {
+  const { enableAuthz } = useWaffleFlags(resourceId);
+  return usePermissions(
+    permissions,
+    enableAuthz ?? false,
+    { apiBaseUrl: getConfig().LMS_BASE_URL },
+  );
+};
+
+export const getResourcePermissions = (resourceId: string): PermissionValidationQuery => ({
+  canView: { action: 'resources.view', scope: resourceId },
+  canEdit: { action: 'resources.edit', scope: resourceId },
+});
+
+// Usage in any component:
+const { isLoading, canView, canEdit } =
+  useResourcePermissions(resourceId, getResourcePermissions(resourceId));
+```
+
+---
+
+## Best Practices
+
+- **Define permission constants** in your MFE (`COURSE_PERMISSIONS`, etc.) rather than
+  inline strings — prevents typos and makes global renames easy.
+- **Use query builder helpers** (`getGradingPermissions(courseId)`) to build the query
+  object — keeps permission definitions co-located with the feature they belong to.
+- **Do not duplicate `{ action, scope }` pairs** within a single query — only the first
+  matching key is mapped in the response.
+- **Keep `featureEnabled` close to the flag source** — the boolean should come directly
+  from your waffle flag check, not be stored in state or passed through many layers.
+
+---
+
+## Manual Cache Invalidation
+
+If user roles change mid-session and you need to force a refetch:
+
+```typescript
+import { permissionsQueryKeys } from '@openedx/frontend-base';
+import { getConfig } from '@edx/frontend-platform';
+
+// Default — URL comes from getSiteConfig().lmsBaseUrl (set via mergeSiteConfig):
+queryClient.invalidateQueries({
+  queryKey: permissionsQueryKeys.validate(myQuery),
+});
+
+// Explicit URL — use when you passed apiBaseUrl in UsePermissionsOptions:
+queryClient.invalidateQueries({
+  queryKey: permissionsQueryKeys.validate(myQuery, getConfig().LMS_BASE_URL),
+});
+```

runtime/authz/api.test.ts

@@ -0,0 +1,80 @@
+import { getAuthenticatedHttpClient } from '../auth';
+import { validatePermissions, PERMISSIONS_VALIDATE_PATH } from './api';
+
+jest.mock('../auth', () => ({
+  getAuthenticatedHttpClient: jest.fn(),
+}));
+
+const BASE_URL = 'http://lms.example.com';
+const QUERY = {
+  canRead: { action: 'example.read', scope: 'lib:org:test' },
+  canWrite: { action: 'example.write', scope: 'lib:org:test' },
+};
+
+describe('validatePermissions', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('posts to the correct URL', async () => {
+    const postMock = jest.fn().mockResolvedValue({ data: [] });
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({ post: postMock });
+
+    await validatePermissions(BASE_URL, QUERY);
+
+    expect(postMock).toHaveBeenCalledWith(
+      `${BASE_URL}${PERMISSIONS_VALIDATE_PATH}`,
+      expect.any(Array),
+    );
+  });
+
+  it('sends all query items as an array in the request body', async () => {
+    const postMock = jest.fn().mockResolvedValue({ data: [] });
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({ post: postMock });
+
+    await validatePermissions(BASE_URL, QUERY);
+
+    const body = postMock.mock.calls[0][1];
+    expect(body).toHaveLength(2);
+    expect(body).toEqual(expect.arrayContaining([
+      { action: 'example.read', scope: 'lib:org:test' },
+      { action: 'example.write', scope: 'lib:org:test' },
+    ]));
+  });
+
+  it('maps response array back to caller keys', async () => {
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn().mockResolvedValue({
+        data: [
+          { action: 'example.read', scope: 'lib:org:test', allowed: true },
+          { action: 'example.write', scope: 'lib:org:test', allowed: false },
+        ],
+      }),
+    });
+
+    const result = await validatePermissions(BASE_URL, QUERY);
+
+    expect(result).toEqual({ canRead: true, canWrite: false });
+  });
+
+  it('defaults missing keys to false', async () => {
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn().mockResolvedValue({ data: [] }),
+    });
+
+    const result = await validatePermissions(BASE_URL, QUERY);
+
+    expect(result).toEqual({ canRead: false, canWrite: false });
+  });
+
+  it('defaults a partially missing key to false', async () => {
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn().mockResolvedValue({
+        data: [{ action: 'example.read', scope: 'lib:org:test', allowed: true }],
+      }),
+    });
+
+    const result = await validatePermissions(BASE_URL, QUERY);
+
+    expect(result.canRead).toBe(true);
+    expect(result.canWrite).toBe(false);
+  });
+});

runtime/authz/api.ts

@@ -0,0 +1,54 @@
+import { getAuthenticatedHttpClient } from '../auth';
+import type {
+  PermissionValidationQuery,
+  PermissionValidationAnswer,
+  PermissionValidationRequestItem,
+  PermissionValidationResponseItem,
+} from './types';
+
+export const PERMISSIONS_VALIDATE_PATH = '/api/authz/v1/permissions/validate/me';
+
+/**
+ * Validates whether the currently authenticated user holds the requested permissions
+ * against the openedx-authz backend.
+ *
+ * @param apiBaseUrl - Base URL of the backend running openedx-authz (e.g. getConfig().LMS_BASE_URL).
+ * @param query      - Key/value map of permission check descriptors.
+ * @returns Map of the same keys to boolean allowed values.
+ *          Any key absent from the server response resolves to false.
+ *
+ * Known limitation: if two entries in the query share identical { action, scope },
+ * only the first matching key is mapped. Do not duplicate { action, scope } pairs.
+ */
+export const validatePermissions = async <Query extends PermissionValidationQuery>(
+  apiBaseUrl: string,
+  query: Query,
+): Promise<PermissionValidationAnswer<Query>> => {
+  const request: PermissionValidationRequestItem[] = Object.values(query);
+
+  const { data }: { data: PermissionValidationResponseItem[] }
+    = await getAuthenticatedHttpClient().post(
+      `${apiBaseUrl}${PERMISSIONS_VALIDATE_PATH}`,
+      request,
+    );
+
+  const result = {} as PermissionValidationAnswer<Query>;
+
+  data.forEach((item) => {
+    const key = Object.keys(query).find(
+      (k) => query[k].action === item.action && query[k].scope === item.scope,
+    ) as keyof Query | undefined;
+    if (key !== undefined) {
+      result[key] = item.allowed;
+    }
+  });
+
+  // Default any key absent from the server response to false
+  (Object.keys(query) as (keyof Query)[]).forEach((key) => {
+    if (!(key in result)) {
+      result[key] = false;
+    }
+  });
+
+  return result;
+};

runtime/authz/hooks.test.tsx

@@ -0,0 +1,105 @@
+import React from 'react';
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { getAuthenticatedHttpClient } from '../auth';
+import { usePermissions, permissionsQueryKeys } from './hooks';
+
+jest.mock('../auth', () => ({
+  getAuthenticatedHttpClient: jest.fn(),
+}));
+
+const BASE_URL = 'http://lms.example.com';
+const QUERY = {
+  canView: { action: 'courses.view_grading_settings', scope: 'course-v1:org+course+run' },
+  canEdit: { action: 'courses.edit_grading_settings', scope: 'course-v1:org+course+run' },
+};
+
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+};
+
+describe('usePermissions', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('returns actual server values when featureEnabled is true', async () => {
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn().mockResolvedValue({
+        data: [
+          { action: 'courses.view_grading_settings', scope: 'course-v1:org+course+run', allowed: true },
+          { action: 'courses.edit_grading_settings', scope: 'course-v1:org+course+run', allowed: false },
+        ],
+      }),
+    });
+
+    const { result } = renderHook(
+      () => usePermissions(QUERY, true, { apiBaseUrl: BASE_URL }),
+      { wrapper: createWrapper() },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.canView).toBe(true);
+    expect(result.current.canEdit).toBe(false);
+    expect(result.current.isAuthzEnabled).toBe(true);
+  });
+
+  it('returns all keys as true and makes no API call when featureEnabled is false', () => {
+    const postMock = jest.fn();
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({ post: postMock });
+
+    const { result } = renderHook(
+      () => usePermissions(QUERY, false, { apiBaseUrl: BASE_URL }),
+      { wrapper: createWrapper() },
+    );
+
+    expect(postMock).not.toHaveBeenCalled();
+    expect(result.current.canView).toBe(true);
+    expect(result.current.canEdit).toBe(true);
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isAuthzEnabled).toBe(false);
+  });
+
+  it('defaults absent server keys to false when featureEnabled is true', async () => {
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn().mockResolvedValue({ data: [] }),
+    });
+
+    const { result } = renderHook(
+      () => usePermissions(QUERY, true, { apiBaseUrl: BASE_URL }),
+      { wrapper: createWrapper() },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.canView).toBe(false);
+    expect(result.current.canEdit).toBe(false);
+  });
+
+  it('spreads permission keys at the top level — no nested .permissions object', async () => {
+    (getAuthenticatedHttpClient as jest.Mock).mockReturnValue({
+      post: jest.fn().mockResolvedValue({
+        data: [
+          { action: 'courses.view_grading_settings', scope: 'course-v1:org+course+run', allowed: true },
+        ],
+      }),
+    });
+
+    const { result } = renderHook(
+      () => usePermissions(QUERY, true, { apiBaseUrl: BASE_URL }),
+      { wrapper: createWrapper() },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect('canView' in result.current).toBe(true);
+    expect('permissions' in result.current).toBe(false);
+  });
+
+  it('scopes cache by apiBaseUrl — different base URLs produce distinct query keys', () => {
+    const keyA = permissionsQueryKeys.validate(QUERY, 'http://lms-a.example.com');
+    const keyB = permissionsQueryKeys.validate(QUERY, 'http://lms-b.example.com');
+    expect(keyA).not.toEqual(keyB);
+  });
+});