0029: Maintaining the Vendored Paragon Icon Allow-List

0029: Maintaining the Vendored Paragon Icon Allow-List#

Status#

Draft

Context#

ADR 0017 §4 requires schema validation to reject icon values that are not valid names exported by @openedx/paragon/icons. Categories, permissions, roles, and role extensions each carry an optional Paragon icon name (for example BookOpen or RemoveRedEye), and those names are used by frontends to render the schema.

openedx-authz is a Python backend with no Node or Paragon dependency, so the JavaScript icon package cannot be imported at validation time. There is no Python-side source of truth for the set of valid icon names, and the set changes whenever Paragon adds, renames, or removes an icon.

Paragon publishes its icons as component exports from @openedx/paragon/icons. The built export barrel (icons/es5/index.js in a published release) lists every icon as export { default as <IconName> } from "./<file>";, which is a stable, machine-readable source for the name set.

Decision#

We vendor the icon-name allow-list as a generated Python module, openedx_authz/engine/schema/paragon_icons.py, exposing PARAGON_ICON_NAMES: frozenset[str]. The schema validator imports this frozenset and rejects any icon value that is not a member (ADR 0017 §4).

The list is generated by scripts/generate_paragon_icons.py, run via make paragon_icons. The script fetches the icon export barrel for a pinned Paragon version from the public npm CDN, parses the exported names, and writes the vendored module. The generated file is committed to the repository so that validation is deterministic and needs no network access at runtime.

Pinned version. The generator pins the Paragon version to match the @openedx/paragon major that frontend-app-admin-console declares on its master branch (currently ^23, generated from 23.21.3). That MFE is the primary consumer that renders these icons, so aligning the allow-list with the version it ships keeps validation honest: an icon that validates here is one the console can actually render.

Update process. Regenerate the list whenever frontend-app-admin-console changes its @openedx/paragon version:

  1. Update PARAGON_VERSION in scripts/generate_paragon_icons.py to the new pinned release.

  2. Run make paragon_icons to rewrite paragon_icons.py.

  3. Commit the regenerated file together with the version bump.

make paragon_icons_check regenerates the list into memory and fails if the committed file is stale; wire it into CI to catch a forgotten refresh after a version bump.

Deprecation. When Paragon renames or removes an icon, the change lands in the allow-list at the next regeneration. Any schema icon value that no longer exists then fails validation as an error, following the same deprecation path as other consumers of @openedx/paragon/icons (ADR 0017 §4).

Consequences#

  • Icon validation is deterministic, offline, and requires no Node dependency in the Python backend.

  • The allow-list can drift from the latest Paragon release between refreshes. This is intentional: it tracks the version the console consumes, not the newest published icons, and the paragon_icons_check target surfaces staleness.

  • Bumping the console’s Paragon version is now a two-repo change: someone must refresh the vendored list here so newly available icons validate and removed icons are rejected.

  • paragon_icons.py is a generated artifact; it must not be edited by hand.

References#