openedx-authz 2.4.0__tar.gz → 3.0.0__tar.gz

{openedx_authz-2.4.0 → openedx_authz-3.0.0}/CHANGELOG.rst

@@ -52,6 +52,18 @@ Added
   ``openedx_authz/engine/schema/paragon_icons.py`` and regenerated with
   ``make paragon_icons`` (ADR 0029).
 
+Changed
+========
+
+* Static roles may declare an empty permission list when ``role_extensions`` contribute their permissions. Permission lists used by extension edits remain non-empty.
+* Built-in Content Library and course authorization definitions now live in capability applets. The compiled authorization schema, the permission constants, and the role keys remain unchanged.
+
+Removed
+=======
+
+* Removed the role permission lists from ``openedx_authz.constants.roles``, such as ``COURSE_ADMIN_PERMISSIONS`` and ``LIBRARY_ADMIN_PERMISSIONS``. Role constants now identify a role and have an empty ``permissions`` list. Use ``openedx_authz.api.get_permissions_for_single_role`` or the compiled schema to read a role's permissions.
+* Removed ``COURSES_CREATE_COURSE`` (``courses.create_course``) from ``openedx_authz.constants.permissions``. No schema file defined it, so no role could include it.
+
 Fixed
 =====
 

{openedx_authz-2.4.0 → openedx_authz-3.0.0}/Makefile

@@ -1,5 +1,5 @@
 .PHONY: clean clean_tox compile_translations coverage diff_cover docs dummy_translations \
-        extract_translations fake_translations help pii_check pull_translations paragon_icons \
+        extract_translations fake_translations help pii_check pull_translations paragon_icons compiled_schema \
         paragon_icons_check quality requirements selfcheck test test-all upgrade validate \
         install_transifex_client
 
@@ -43,6 +43,9 @@ paragon_icons: ## regenerate the vendored @openedx/paragon icon-name allow-list
 paragon_icons_check: ## fail if the vendored Paragon icon list is out of date (CI)
 	python scripts/generate_paragon_icons.py --check
 
+compiled_schema: ## regenerate the compiled schema snapshot in docs/references/compiled-schema.yaml
+	python scripts/generate_compiled_schema.py
+
 quality: ## check coding style with pycodestyle and pylint
 	tox -e quality
 

{openedx_authz-2.4.0/src/openedx_authz.egg-info → openedx_authz-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openedx-authz
-Version: 2.4.0
+Version: 3.0.0
 Summary: Open edX AuthZ provides the architecture and foundations of the authorization framework.
 Author-email: Open edX Project <oscm@openedx.org>
 License-Expression: AGPL-3.0-or-later

{openedx_authz-2.4.0 → openedx_authz-3.0.0}/docs/concepts/core_roles_and_permissions/course_roles.rst

@@ -36,7 +36,6 @@ The following permissions are associated with the course roles:
 Course Access & Content
 =========================
 - **View course** (``courses.view_course``): Allows users to view the course and access the course outline in read-only mode.
-- **Create course** (``courses.create_course``): Allows users to create a new course in Studio.
 - **Edit course content** (``courses.edit_course_content``): Allows users to edit course content, outline, units, and components.
 - **Publish course content** (``courses.publish_course_content``): Allows users to publish course content.
 
@@ -132,7 +131,6 @@ Roles and Permissions Summary Table
    **Access & Content**
    --------------------------------------------- -------------- -------------- --------------------- --------------
    courses.view_course                           ✅             ✅             ✅                    ✅
-   courses.create_course                         ❌             ❌             ❌                    ❌
    courses.publish_course_content                ✅             ✅             ❌                    ❌
    courses.edit_course_content                   ✅             ✅             ✅                    ❌
    **Files**

{openedx_authz-2.4.0 → openedx_authz-3.0.0}/docs/decisions/0026-rest-api-domain-ownership-boundary.rst

@@ -105,6 +105,11 @@ Rejected Alternatives
 **Adding application-specific visibility rules to reusable endpoint code**
   This would make reusable authorization code interpret data that authorization does not own. A general hook keeps the rule in a separate implementation, and `openedx_catalog`_ follows a related approach for installation-specific visibility rules.
 
+Addendum 2026-10-20
+*******************
+
+`ADR 0032`_ replaces the package layout in decisions 4, 6, and 8, so client-specific and cross-domain endpoints now belong in the applet for the capability they serve, while the ownership rules in this ADR still apply.
+
 References
 **********
 
@@ -115,6 +120,7 @@ References
 * `Issue #377`_
 * `PR #361`_
 * `openedx_catalog`_
+* `ADR 0032`_
 
 .. _edX DDD Bounded Contexts: https://openedx.atlassian.net/wiki/spaces/AC/pages/663224968/edX+DDD+Bounded+Contexts
 .. _ADR 0018 in openedx-events: https://github.com/openedx/openedx-events/blob/main/docs/decisions/0018-supporting-subdomain-modules.rst
@@ -123,3 +129,4 @@ References
 .. _Issue #377: https://github.com/openedx/openedx-authz/issues/377
 .. _PR #361: https://github.com/openedx/openedx-authz/pull/361
 .. _openedx_catalog: https://github.com/openedx/openedx-core/blob/main/src/openedx_catalog/api.py
+.. _ADR 0032: 0032-applets-for-built-in-authorization-capabilities.rst

openedx_authz-3.0.0/docs/decisions/0032-applets-for-built-in-authorization-capabilities.rst

@@ -0,0 +1,202 @@
+0032: Applets for Built-In Authorization Capabilities
+#####################################################
+
+Status
+******
+
+**Draft**
+
+Context
+*******
+
+`ADR 0005`_ defines ``openedx_authz.api`` as the public API for the reusable authorization framework, although the package also ships the Open edX-specific roles and permissions that the platform uses, as YAML schema files and Python constants. These definitions are grouped by type, so ``authz/schema/course_permissions.yaml`` defines every course permission and ``authz/schema/course_roles.yaml`` lists the complete permissions for each course role.
+
+Grouping by type keeps roles apart from permissions, but it also puts definitions from unrelated responsibilities into the same course-level files, so a reader can see that a permission applies to a course without being able to tell whether enrollments, grading, or another area owns it.
+
+`Issue #484`_ defines permissions for the Instructor Dashboard, which brings together several areas of course administration, including enrollments, the gradebook, learner extensions, and cohorts. The `edX DDD Bounded Contexts`_ map places those areas in different parts of the platform, so adding their permissions to the shared files would mix definitions from several bounded contexts and make those files the place where every new contribution has to be added.
+
+The existing decisions do not say where these definitions belong, because `ADR 0026`_ defines ownership and placement rules only for REST endpoints, while `PR #421`_ raised the same ownership question for constants and schema definitions.
+
+`ADR 0010 in openedx-core`_ answers a similar question for a single Django app by giving each bounded responsibility its own internal package, which it calls an applet. The authorization schema can already support that structure, since `ADR 0019`_ allows a package to load several schema directories and `ADR 0023`_ allows one schema contribution to extend a role defined by another.
+
+Decision
+********
+
+We will organize built-in Open edX authorization capabilities as applets under ``openedx_authz.applets``, while the existing public API and import paths remain stable, since ``openedx_authz.constants`` re-exports each applet's constants and the ``authz.schema`` provider lists each applet's schema directory.
+
+1. Applet boundaries
+====================
+
+An applet is an internal Python package that gives one bounded responsibility a concrete place inside the existing ``openedx_authz`` Django app and keeps the related YAML definitions, Python constants, REST endpoints, filters, and tests together when those elements exist:
+
+.. code-block:: text
+
+   openedx_authz/applets/
+       course_team_roles/
+           constants.py
+           schema/
+       enrollments/
+           constants.py
+           schema/
+       course_authoring/
+           constants.py
+           schema/
+           rest_api/
+       ...
+
+The `edX DDD Bounded Contexts`_ map says where each responsibility belongs, but it does not prescribe a package layout inside one Django app, so applets turn those boundaries into Python packages that keep the code and definitions for each responsibility together. Reusable schema handling, enforcement, persistence, and public APIs stay in their existing top-level packages, since every applet depends on them.
+
+Dependencies point in one direction, from clients to the public modules, from those modules to the applets, and from the applets to the shared packages:
+
+.. code-block:: text
+
+   clients, such as openedx-platform
+     └── openedx_authz.api, openedx_authz.constants
+           └── openedx_authz.applets.<applet>
+                 └── openedx_authz.api.data, openedx_authz.data
+
+Applets do not import each other, since role extensions in YAML already connect their definitions. Applets are internal, so clients import constants from ``openedx_authz.constants``, and an applet can change or move without changing client code.
+
+2. Definition ownership
+=======================
+
+A permission belongs to the applet responsible for the action or data that the permission controls. For example, the ``enrollments`` applet defines the permissions for viewing or changing enrollments, along with their metadata, constants, and contributions to shared roles, so code elsewhere may check those permissions through the public API while their definitions remain in ``enrollments``.
+
+A role belongs to the applet for the bounded context where it is assigned, as with the library roles, and other applets add the permissions they own through ``role_extensions``. Roles that cut across several contexts need a specific decision about where they live, which `ADR 0033`_ makes for the course-team roles.
+
+Both rules rely on the `edX DDD Bounded Contexts`_ map, which shows the context that owns each action or data even when a user interface combines several capabilities. To place a new permission, we find the bounded context that owns its action or data in the map and add the permission to that context's applet, or create an applet when the context has none yet. Applet names describe the definitions they hold, so the following table records which bounded context each one stands for:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Applet
+     - Bounded context
+     - Definitions
+   * - ``course_authoring``
+     - Course Run Authoring and Learning Content Authoring
+     - Course authoring and course-team permissions
+   * - ``content_libraries``
+     - Learning Content Authoring and Learning Content Repository
+     - Library roles and permissions
+   * - ``enrollments``
+     - Content Access / Enrollments
+     - Viewing and changing course enrollments
+   * - ``learner_grading``
+     - Consuming Learning Content
+     - The gradebook and grading tools for individual learners
+   * - ``learner_administration``
+     - Support Learning
+     - Course information, learner extensions, and cohorts
+   * - ``course_team_roles``
+     - Shared by several bounded contexts
+     - Roles held by members of a course team
+   * - ``role_management``
+     - Authorization
+     - Admin Console role assignment workflows
+
+3. Course roles
+===============
+
+Following `ADR 0033`_, ``course_team_roles`` defines the identifiers and metadata for the course-team roles, and their base definitions list only the permissions that ``course_team_roles`` owns, such as the legacy compatibility permissions, while each capability applet adds the permissions it owns through ``role_extensions``:
+
+.. code-block:: yaml
+
+   # course_team_roles/schema/roles.yaml
+   roles:
+     - id: course_admin
+       display_name: Course Admin
+       description: Can manage the course team and all course settings.
+       scopes:
+         - course-v1
+       permissions:
+         - courses.legacy_instructor_role_permissions
+
+   # enrollments/schema/role_extensions.yaml
+   role_extensions:
+     - role_id: course_admin
+       add_permissions:
+         - courses.view_enrollments
+         - courses.enroll_learners
+
+Roles such as ``course_editor`` have no permissions of their own, so schema version 1 will accept an empty permission list, while the compiled roles will still contain the complete permission lists contributed by the applets.
+
+4. REST endpoints
+=================
+
+REST endpoints continue to follow the ownership rules in `ADR 0026`_, and applets now give those rules a package boundary. The Admin Console endpoints therefore move to ``role_management``, since they support the same role-management workflow, although this placement does not settle the ownership of the organization data returned by ``AdminConsoleOrgsAPIView``, and ``WaffleFlagStatesAPIView`` moves to ``course_authoring``. In both cases, the existing URLs and route names remain unchanged.
+
+5. Imports
+==========
+
+Although applets are internal packages, ``openedx_authz.constants.permissions`` and ``openedx_authz.constants.roles`` continue to export every existing constant, while ``COURSE_ADMIN`` and ``COURSE_STAFF`` continue to contain their complete permission lists, so existing import paths remain valid when code moves into an applet.
+
+YAML remains the source of truth for static definitions, although each applet will maintain its Python constants manually for now, so tests compare those constants with the applet's YAML definitions, and generating them from YAML may replace this process in later work.
+
+6. Future extraction
+====================
+
+The applets remain inside ``openedx-authz`` for this work, so implementing the ownership model and the permissions from `Issue #484`_ does not require coordinated changes across the services that use the library, and since their definitions describe the underlying actions and data rather than one user interface, another client can reuse the same permissions when it exposes the same responsibility.
+
+An applet may later move to the service that owns its responsibility and contribute its definitions through the existing ``authz.schema`` entry point, although this decision does not include that extraction because the service boundary, package dependency, and compatibility path for the Python constants would need to be agreed first.
+
+Consequences
+************
+
+1. Each built-in definition has an explicit owner based on the capability it protects.
+2. Adding a capability does not require adding its definitions to shared course permission and role files.
+3. The complete permission list for a course role is assembled from several schema contributions, so readers use the compiled schema or the public role constants to inspect that list.
+4. Each permission identifier appears in YAML and Python until generated constants replace the manually maintained files.
+5. The schema accepts an empty base permission list for applets that define roles whose permissions come from other applets. Validation logs a warning so contributors can confirm that the empty list is intentional and that ``role_extensions`` provide the role's permissions.
+6. The Admin Console and course-authoring endpoints move again after `ADR 0026`_, although their public URLs, route names, request and response contracts, and import paths remain stable.
+7. Reviewers must identify unwanted dependencies between applets because this decision does not add automated import-boundary checks.
+8. Applets create boundaries that can support later extraction, although moving one to another service requires a separate decision about dependencies and compatibility.
+
+Rejected Alternatives
+*********************
+
+**Keeping all definitions in the shared files**
+  Definitions would remain grouped by type, leaving ownership implicit and continuing the growth of the shared course files.
+
+**One applet for each screen, such as the Instructor Dashboard**
+  A permission that Studio and the dashboard both use would have two possible owners.
+
+**A separate Django app for each feature**
+  Each feature would gain a separate app label and installation boundary, which the definitions and integrations covered by this decision do not require.
+
+**Moving the definitions to their owning services now**
+  This would place the definitions at their eventual service boundary, but it would also require coordinating package dependencies and compatibility imports before implementing the permissions in `Issue #484`_, while the existing schema contribution mechanism leaves that move available after those boundaries are agreed.
+
+References
+**********
+
+* `Issue #484`_
+* `PR #421`_
+* `ADR 0005`_
+* `ADR 0010 in openedx-core`_
+* `edX DDD Bounded Contexts`_
+* `ADR 0019`_
+* `ADR 0023`_
+* `ADR 0026`_
+* `ADR 0033`_
+
+Addendum: 2026-11-04
+********************
+
+Each applet keeps the permission and role constants it owns in one ``constants.py`` file. Clients import these constants from ``openedx_authz.authz``, while ``openedx_authz.constants.permissions`` and ``openedx_authz.constants.roles`` remain compatibility exports.
+
+``ActionData``, ``PermissionData``, and ``RoleData`` live in ``openedx_authz.data``. This keeps the dependency direction from ``openedx_authz.api.data`` to ``openedx_authz.authz``, then to the applet constants, and finally to the low-level data classes. It also avoids the circular import that previously required action and permission data classes to move below the public API layer in `commit 2b732c3`_.
+
+YAML remains the source of truth for role composition. Role constants identify roles without listing their permissions, so callers use the public API or the compiled schema to read a role's complete permission list.
+
+This addendum replaces the import paths, dependency direction, and role constant behavior described earlier in this decision. The :doc:`Built-In Python Constants <../references/built-in-constants>` reference documents the public imports.
+
+.. _Issue #484: https://github.com/openedx/openedx-authz/issues/484
+.. _PR #421: https://github.com/openedx/openedx-authz/pull/421
+.. _ADR 0005: 0005-architecture-and-data-modeling.rst
+.. _ADR 0010 in openedx-core: https://github.com/openedx/openedx-core/blob/6a26b3a4181815a44e9d724c16857b61b484b0ea/docs/openedx_content/decisions/0010-merge-authoring-apps-into-openedx-content.rst
+.. _edX DDD Bounded Contexts: https://openedx.atlassian.net/wiki/spaces/AC/pages/663224968/edX+DDD+Bounded+Contexts
+.. _ADR 0019: 0019-authorization-schema-discovery.rst
+.. _ADR 0023: 0023-extend-static-roles.rst
+.. _ADR 0026: 0026-rest-api-domain-ownership-boundary.rst
+.. _ADR 0033: 0033-shared-applet-for-course-team-roles.rst
+.. _commit 2b732c3: https://github.com/openedx/openedx-authz/commit/2b732c3560b6392b82a5f835e2bf254eefe70d7c

openedx_authz-3.0.0/docs/decisions/0033-shared-applet-for-course-team-roles.rst

@@ -0,0 +1,43 @@
+0033: Shared Applet for Course-Team Roles
+#########################################
+
+Status
+******
+
+**Draft**
+
+Context
+*******
+
+`ADR 0032`_ places a role in the applet for the bounded context where it is assigned, while roles that cut across several contexts need a specific decision about where they live. The course-team roles are the first case, since they are assigned to members of a course team and combine permissions from course authoring, enrollments, grading, and learner administration.
+
+These roles do not all combine permissions in the same way today. ``course_admin`` and ``course_staff`` receive permissions from several applets, ``course_editor`` and ``course_auditor`` receive every permission from ``course_authoring``, and the legacy roles such as ``course_limited_staff`` only list their legacy compatibility permission. However, the `Instructor Dashboard Permissions`_ proposal allows more restricted roles to receive a subset of the dashboard permissions, so the roles that rely on one applet today may combine several later.
+
+Decision
+********
+
+The course-team roles are cross-cutting, so they live in the shared ``course_team_roles`` applet regardless of which applets currently provide their permissions. Their base definitions list only the permissions that ``course_team_roles`` owns, such as the legacy compatibility permissions, while every other applet adds the permissions it owns through ``role_extensions``.
+
+Any other group of cross-cutting roles needs its own decision about where it lives.
+
+Consequences
+************
+
+1. A course-team role keeps its owner when another applet starts adding permissions to it.
+2. Every role that a course team can assign is defined in one place, next to the legacy role equivalences.
+3. Base definitions such as ``course_editor`` may list no permissions, so the schema has to accept an empty permission list.
+
+Rejected Alternatives
+*********************
+
+**Placing each course-team role in the applet that provides its permissions**
+  ``course_editor`` and ``course_auditor`` would move to ``course_authoring``, splitting one group of roles across applets, and each role would have to move again once another applet added permissions to it.
+
+References
+**********
+
+* `ADR 0032`_
+* `Instructor Dashboard Permissions`_
+
+.. _ADR 0032: 0032-applets-for-built-in-authorization-capabilities.rst
+.. _Instructor Dashboard Permissions: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/6789234689/Instructor+Dashboard+Permissions

openedx_authz-3.0.0/docs/how-tos/index.rst

@@ -0,0 +1,7 @@
+How-tos
+#######
+
+.. toctree::
+   :maxdepth: 1
+
+   use-built-in-constants

openedx_authz-3.0.0/docs/how-tos/use-built-in-constants.rst

@@ -0,0 +1,25 @@
+Use Built-In Permission and Role Constants
+##########################################
+
+Import built-in permissions and roles from ``openedx_authz.authz``. Pass their external keys to the convenience functions in ``openedx_authz.api``:
+
+.. code-block:: python
+
+   from openedx_authz.api import assign_role_to_user_in_scope, is_user_allowed
+   from openedx_authz.authz import COURSE_ADMIN, COURSES_VIEW_COURSE
+
+   can_view_course = is_user_allowed(
+       user_external_key="alice",
+       action_external_key=COURSES_VIEW_COURSE.identifier,
+       scope_external_key="course-v1:edX+DemoX+2026",
+   )
+
+   assign_role_to_user_in_scope(
+       user_external_key="alice",
+       role_external_key=COURSE_ADMIN.external_key,
+       scope_external_key="course-v1:edX+DemoX+2026",
+   )
+
+Role constants identify roles without containing their complete permission lists. Use ``get_permissions_for_single_role`` or the compiled schema when a client needs to inspect the permissions assigned to a role.
+
+See :doc:`Built-In Python Constants <../references/built-in-constants>` for the import and compatibility paths.

openedx_authz-3.0.0/docs/references/built-in-constants.rst

@@ -0,0 +1,13 @@
+Built-In Python Constants
+#########################
+
+Applications import built-in permission and role constants from ``openedx_authz.authz``:
+
+.. code-block:: python
+
+   from openedx_authz.authz import COURSE_ADMIN, COURSES_VIEW_COURSE
+
+Each applet keeps the permission and role constants it owns in one ``constants.py`` file. The YAML schema remains the source of truth for role composition, so role constants identify roles without copying their complete permission lists.
+
+``openedx_authz.constants.permissions`` and ``openedx_authz.constants.roles`` remain available as compatibility imports. New code should use ``openedx_authz.authz``.
+

openedx_authz-3.0.0/docs/references/compiled-schema.rst

@@ -0,0 +1,11 @@
+.. _Compiled Authorization Schema:
+
+Compiled Authorization Schema
+#############################
+
+The built-in applets each contribute part of the authorization schema, so a role's complete permission list only exists after the schema pipeline composes the base definitions with the ``role_extensions`` from every applet. This page shows that compiled result for the built-in applets, where each role lists its permissions grouped by the applet that adds them, and each permission and category names the applet that defines it. Installations may add more definitions through their own schema contributions, which this snapshot does not include.
+
+The snapshot is generated from the applet schemas with ``make compiled_schema``, and a test fails when it no longer matches the compiled schema, so any change to an applet schema also shows its effect on the compiled roles in the same diff. You can also :download:`download the snapshot <compiled-schema.yaml>`.
+
+.. literalinclude:: compiled-schema.yaml
+   :language: yaml