feat: implement permission validation API and hooks for frontend-authz

[bra-i-am]

Context

This PR implements the @openedx/frontend-authz standalone package, proposed in openedx/frontend-base#269 (comment) as the solution to openedx/frontend-base#150.

The original implementation was ported from openedx/frontend-base#269, which added permission-validation hooks directly into frontend-base. During review, it was proposed that these utils should live in a standalone package instead, so both MFEs still on frontend-platform/frontend-build and those migrated to frontend-base can consume the authz utilities without introducing cross-dependencies between base libraries.

What's added

src/types.ts

• PermissionValidationRequestItem — shape of a single permission check sent to the backend (action, scope)
• PermissionValidationResponseItem — same shape coming back, plus allowed: boolean
• PermissionValidationQuery — the key/value map the caller builds ({ canEdit: { action: '...', scope: '...' } })
• PermissionValidationAnswer<Query> — maps every key from the caller's query to a boolean

src/api.ts

• PERMISSIONS_VALIDATE_PATH — endpoint path constant
• validatePermissions(apiBaseUrl, query) — POSTs to /api/authz/v1/permissions/validate/me, maps response back to caller keys; missing keys default to false

src/hooks.ts

• permissionsQueryKeys — stable TanStack Query cache key factory for deduplication and invalidation
• usePermissions(query, featureEnabled, options?) — React hook; when featureEnabled is false it skips the API call and returns all keys as true (gradual rollout safe); when true it calls the authz API and spreads permission keys at the top level alongside isLoading, isError, and isAuthzEnabled

docs/how_tos/permissions.md — usage, caching, MFE-level wrapper pattern, best practices, and cache invalidation. Includes a reference to the full list of available actions and scopes.

.github/workflows/ci.yml — removed the i18n_extract step inherited from the template; frontend-authz is a headless utility library with no translatable UI strings.

How to test locally

This package uses frontend-build's module.config.js for local development, which resolves the package directly from source without requiring a build step.

1. Clone this repo next to the consuming MFE

# peer directory of frontend-app-authoring
git clone https://github.com/bra-i-am/frontend-authz-test frontend-authz

2. Configure module.config.js in the consuming MFE

In frontend-app-authoring/module.config.js:

module.exports = {
  localModules: [
    { moduleName: '@openedx/frontend-authz', dir: './frontend-authz', dist: 'src' },
  ],
};

3. Wrap usePermissions in an MFE-level hook

import { usePermissions } from '@openedx/frontend-authz';
import { useWaffleFlags } from '@src/data/apiHooks';

export const useCourseUserPermissions = (courseId, permissions) => {
  const waffleFlags = useWaffleFlags(courseId);
  const isAuthzEnabled = waffleFlags?.enableAuthzCourseAuthoring ?? false;
  return usePermissions(permissions, isAuthzEnabled);
};

A working integration can be found in eduNEXT/frontend-app-authoring branch bc/generalize-authz-validation.

4. Verify at runtime

1. Enable the waffle flag authz.enable_course_authoring in Django admin
2. Navigate to a course in the Authoring MFE
3. Open DevTools → Network → filter by validate
4. You should see a POST to /api/authz/v1/permissions/validate/me

When the flag is off, no request should appear and all permissions default to true.

LLM usage notice

Built with assistance from Claude.