feat: validate Paragon icons on authz schemas

[rodmgwgu]

Problem

Authorization schema definitions may carry a Paragon icon name on categories, permissions, roles, and role extensions, but nothing validated those names. ADR 0017 §4 requires schema validation to reject icon values that are not valid names exported by @openedx/paragon/icons. Without this check, a typo or a removed/renamed icon reaches the frontend and fails to render.

Approach

Adds icon-name validation to the schema validate step, backed by a vendored allow-list:

• openedx_authz/engine/schema/paragon_icons.py — generated PARAGON_ICON_NAMES frozenset (the component exports of @openedx/paragon/icons).
• scripts/generate_paragon_icons.py — regenerates that list from a pinned Paragon version; make paragon_icons writes it and make paragon_icons_check fails if it is stale (for CI).
• openedx_authz/engine/schema/validation.py — new _check_icon helper (PascalCase format + membership check), wired into validate_document for categories, permissions, roles, and role extensions. Both a malformed name and an unknown name are error-level, so an invalid icon blocks deployment through the existing validation gate.
• docs/decisions/0026-paragon-icon-list-maintenance.rst — ADR describing why the list is vendored and how it is refreshed.
• tests under openedx_authz/tests/schema/.

The pinned version is the @openedx/paragon major that frontend-app-admin-console declares on master (^23, generated from 23.21.3), since that MFE is the consumer that renders these icons. The list is regenerated whenever the console bumps its Paragon version (see ADR 0026).

Manual testing instructions

Run in a tutor dev environment with this repo mounted. Every command below is shown for cms; lms works identically.

1. A valid schema still applies cleanly

tutor dev run cms ./manage.py cms load_authz_schema --dry-run

Expect the same definition sections as before (17 categories, 48 permissions, 11 roles, 132 role-permission grants) with no icon errors — every icon shipped in the schema is a valid Paragon name.

2. An unknown icon name stops deployment

Edit a category or permission in openedx_authz/authz/schema/course_permissions.yaml and set icon: to a name Paragon does not export (for example icon: NotARealParagonIcon), then run:

tutor dev run cms ./manage.py cms load_authz_schema

Expect a CommandError; the log lists the icon error with its source file, ending with "is not a valid @openedx/paragon/icons name", and the database is untouched.

3. A malformed icon name is rejected with a distinct message

Set an icon to a non-PascalCase value (for example icon: remove_red_eye) and run the command again. The reported error ends with "must be a PascalCase Paragon icon name". Remove the edit and confirm the command succeeds again.

4. The vendored list is current

make paragon_icons_check

Prints ... is up to date (2317 icons). and exits 0. Running make paragon_icons rewrites the file from the pinned Paragon version and leaves it unchanged.

Automated coverage

openedx_authz/tests/schema/test_validation.py adds TestIconRules (11 tests): valid icon passes, missing/empty icon is allowed, non-PascalCase names error, unknown well-formed names error, and the permission/role/role-extension icon paths are each exercised. The full schema suite (230 tests) passes, with validation.py and paragon_icons.py at 100% coverage.

Rollback plan

Revert this PR. The vendored list and validation are self-contained; nothing else depends on them. The schema YAML files and prior pipeline are unaffected. No migration is involved.

Retro compatibility

No authorization behavior changed. The check only runs during schema validation (load_authz_schema), and the shipped schema already uses valid icon names, so existing deployments are unaffected. The new rule is error-level, so any future schema that references an icon outside the pinned Paragon set will fail validation until the icon is corrected or the vendored list is refreshed.

Follow up work required

1. Wire make paragon_icons_check into CI so a forgotten refresh after a Paragon bump is caught automatically.
2. Once the JSON Schema validation from docs: add authorization schema reference #431 lands, fold the icon rule into the shared field reference if appropriate (Extend schema loader validation to use schema reference defined in #431 #459).

AI Usage

Kiro was used to assist on feature planning and implementation. Implementation was done step by step with human guidance and validation, based on the ADRs.

---

Stack (4/4):

1. docs: add ADR for authorization schema source tracking #444 — ADR doc
2. feat: add authz schema definition files #445 — authz schema YAML files
3. feat: add authz schema pipeline and load_authz_schema command #446 — schema loading pipeline
4. This PR — Paragon icon validation (base: rod/authz-schema-loader)

Base is the PR 3 branch (#446); review only the incremental diff. Merge last, after #444, #445, and #446.

Merge checklist:

• Version bumped — 1.25.0 -> 1.26.0
• Changelog record added
• Documentation updated (not only docstrings)
• Fixup commits are squashed away
• Unit tests added/updated
• Manual testing instructions provided
• Noted any: Concerns, dependencies, migration issues, deadlines, tickets — depends on feat: add authz schema pipeline and load_authz_schema command #446; no migration

[openedx-webhooks]

Thanks for the pull request, @rodmgwgu!

This repository is currently maintained by @openedx/committers-openedx-authz.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.