diff --git a/CHANGELOG.rst b/CHANGELOG.rst index cca84522..f38d2f14 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -17,6 +17,10 @@ Unreleased Added ===== +* Added an optional ``hidden`` flag to permission categories and permissions in the authorization + schema. Hidden permissions, and the permissions of hidden categories, are left out of the + role and permission catalog, including each role's permission list, but keep their role grants + and permission checks. * Added the static authorization schema, a versioned YAML format for declaring permissions, permission categories, roles, and role extensions (ADR 0017). The permissions and roles previously defined in ``authz.policy`` are expressed as schema files under diff --git a/docs/references/authorization-schema-json.rst b/docs/references/authorization-schema-json.rst index 0fdaf32a..80f835e9 100644 --- a/docs/references/authorization-schema-json.rst +++ b/docs/references/authorization-schema-json.rst @@ -45,6 +45,9 @@ Permission category fields .. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission_category/properties/icon :lift_description: +.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission_category/properties/hidden + :lift_description: + Permission fields ***************** @@ -69,6 +72,9 @@ Permission fields .. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/icon :lift_description: +.. jsonschema:: ../../src/openedx_authz/engine/schema/authz-schema-v1.json#/$defs/permission/properties/hidden + :lift_description: + Role fields *********** diff --git a/docs/references/compiled-schema.yaml b/docs/references/compiled-schema.yaml index 051a81b1..9d8adfd7 100644 --- a/docs/references/compiled-schema.yaml +++ b/docs/references/compiled-schema.yaml @@ -271,6 +271,7 @@ permissions: scopes: - lib icon: Plus + hidden: false content_libraries.delete_library: applet: content_libraries namespace: content_libraries @@ -281,6 +282,7 @@ permissions: scopes: - lib icon: Delete + hidden: false content_libraries.delete_library_collection: applet: content_libraries namespace: content_libraries @@ -291,6 +293,7 @@ permissions: scopes: - lib icon: Delete + hidden: false content_libraries.edit_library_collection: applet: content_libraries namespace: content_libraries @@ -301,6 +304,7 @@ permissions: scopes: - lib icon: EditOutline + hidden: false content_libraries.edit_library_content: applet: content_libraries namespace: content_libraries @@ -311,6 +315,7 @@ permissions: scopes: - lib icon: EditOutline + hidden: false content_libraries.manage_library_tags: applet: content_libraries namespace: content_libraries @@ -321,6 +326,7 @@ permissions: scopes: - lib icon: Settings + hidden: false content_libraries.manage_library_team: applet: content_libraries namespace: content_libraries @@ -331,6 +337,7 @@ permissions: scopes: - lib icon: Settings + hidden: false content_libraries.publish_library_content: applet: content_libraries namespace: content_libraries @@ -341,6 +348,7 @@ permissions: scopes: - lib icon: DownloadDone + hidden: false content_libraries.reuse_library_content: applet: content_libraries namespace: content_libraries @@ -351,6 +359,7 @@ permissions: scopes: - lib icon: SpinnerIcon + hidden: false content_libraries.view_library: applet: content_libraries namespace: content_libraries @@ -361,6 +370,7 @@ permissions: scopes: - lib icon: RemoveRedEye + hidden: false content_libraries.view_library_team: applet: content_libraries namespace: content_libraries @@ -371,6 +381,7 @@ permissions: scopes: - lib icon: RemoveRedEye + hidden: false courses.create_files: applet: course_authoring namespace: courses @@ -381,6 +392,7 @@ permissions: scopes: - course-v1 icon: Plus + hidden: false courses.delete_files: applet: course_authoring namespace: courses @@ -391,6 +403,7 @@ permissions: scopes: - course-v1 icon: Delete + hidden: false courses.edit_course_content: applet: course_authoring namespace: courses @@ -401,6 +414,7 @@ permissions: scopes: - course-v1 icon: EditOutline + hidden: false courses.edit_details: applet: course_authoring namespace: courses @@ -411,6 +425,7 @@ permissions: scopes: - course-v1 icon: EditOutline + hidden: false courses.edit_files: applet: course_authoring namespace: courses @@ -421,6 +436,7 @@ permissions: scopes: - course-v1 icon: EditOutline + hidden: false courses.edit_grading_settings: applet: course_authoring namespace: courses @@ -431,6 +447,7 @@ permissions: scopes: - course-v1 icon: EditOutline + hidden: false courses.edit_schedule: applet: course_authoring namespace: courses @@ -441,6 +458,7 @@ permissions: scopes: - course-v1 icon: EditOutline + hidden: false courses.enroll_learners: applet: enrollments namespace: courses @@ -451,6 +469,7 @@ permissions: scopes: - course-v1 icon: PersonAdd + hidden: false courses.export_course: applet: course_authoring namespace: courses @@ -461,6 +480,7 @@ permissions: scopes: - course-v1 icon: Upload + hidden: false courses.export_tags: applet: course_authoring namespace: courses @@ -471,6 +491,7 @@ permissions: scopes: - course-v1 icon: Upload + hidden: false courses.import_course: applet: course_authoring namespace: courses @@ -481,6 +502,7 @@ permissions: scopes: - course-v1 icon: Download + hidden: false courses.legacy_beta_tester_permissions: applet: course_team_roles namespace: courses @@ -491,6 +513,7 @@ permissions: scopes: - course-v1 icon: DrawShapes + hidden: false courses.legacy_data_researcher_permissions: applet: course_team_roles namespace: courses @@ -501,6 +524,7 @@ permissions: scopes: - course-v1 icon: DrawShapes + hidden: false courses.legacy_instructor_role_permissions: applet: course_team_roles namespace: courses @@ -511,6 +535,7 @@ permissions: scopes: - course-v1 icon: DrawShapes + hidden: false courses.legacy_limited_staff_role_permissions: applet: course_team_roles namespace: courses @@ -521,6 +546,7 @@ permissions: scopes: - course-v1 icon: DrawShapes + hidden: false courses.legacy_staff_role_permissions: applet: course_team_roles namespace: courses @@ -531,6 +557,7 @@ permissions: scopes: - course-v1 icon: DrawShapes + hidden: false courses.manage_advanced_settings: applet: course_authoring namespace: courses @@ -541,6 +568,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_certificates: applet: course_authoring namespace: courses @@ -551,6 +579,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_cohorts: applet: learner_administration namespace: courses @@ -561,6 +590,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_course_team: applet: course_authoring namespace: courses @@ -571,6 +601,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_course_updates: applet: course_authoring namespace: courses @@ -581,6 +612,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_group_configurations: applet: course_authoring namespace: courses @@ -591,6 +623,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_learner_extensions: applet: learner_administration namespace: courses @@ -601,6 +634,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_learner_grading: applet: learner_grading namespace: courses @@ -611,6 +645,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_library_updates: applet: course_authoring namespace: courses @@ -621,6 +656,7 @@ permissions: scopes: - course-v1 icon: Checklist + hidden: false courses.manage_pages_and_resources: applet: course_authoring namespace: courses @@ -631,6 +667,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_tags: applet: course_authoring namespace: courses @@ -641,6 +678,7 @@ permissions: scopes: - course-v1 icon: Settings + hidden: false courses.manage_taxonomies: applet: course_authoring namespace: courses @@ -651,6 +689,7 @@ permissions: scopes: - course-v1 icon: LocalOffer + hidden: false courses.publish_course_content: applet: course_authoring namespace: courses @@ -661,6 +700,7 @@ permissions: scopes: - course-v1 icon: DownloadDone + hidden: false courses.unenroll_learners: applet: enrollments namespace: courses @@ -671,6 +711,7 @@ permissions: scopes: - course-v1 icon: PersonRemove + hidden: false courses.view_advanced_settings: applet: course_authoring namespace: courses @@ -681,6 +722,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_certificates: applet: course_authoring namespace: courses @@ -691,6 +733,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_checklists: applet: course_authoring namespace: courses @@ -701,6 +744,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_cohorts: applet: learner_administration namespace: courses @@ -711,6 +755,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_course: applet: course_authoring namespace: courses @@ -721,6 +766,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_course_info: applet: learner_administration namespace: courses @@ -731,6 +777,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_course_team: applet: course_authoring namespace: courses @@ -741,6 +788,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_course_updates: applet: course_authoring namespace: courses @@ -751,6 +799,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_enrollments: applet: enrollments namespace: courses @@ -761,6 +810,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_files: applet: course_authoring namespace: courses @@ -771,6 +821,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_gradebook: applet: learner_grading namespace: courses @@ -781,6 +832,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_grading_settings: applet: course_authoring namespace: courses @@ -791,6 +843,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_group_configurations: applet: course_authoring namespace: courses @@ -801,6 +854,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_learner_extensions: applet: learner_administration namespace: courses @@ -811,6 +865,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_library_updates: applet: course_authoring namespace: courses @@ -821,6 +876,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_pages_and_resources: applet: course_authoring namespace: courses @@ -831,6 +887,7 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false courses.view_schedule_and_details: applet: course_authoring namespace: courses @@ -841,114 +898,137 @@ permissions: scopes: - course-v1 icon: RemoveRedEye + hidden: false categories: course_access_content: applet: course_authoring display_name: Course access & content description: Permissions related to accessing the course and managing core course content, including creating, editing, and publishing materials. icon: BookOpen + hidden: false course_advanced_certificates: applet: course_authoring display_name: Advanced & certificates description: Permissions for managing advanced course settings and course certificates. icon: CheckCircle + hidden: false course_cohorts: applet: learner_administration display_name: Cohorts description: Permissions for viewing and managing course cohorts and their members. icon: Groups + hidden: false course_enrollments: applet: enrollments display_name: Enrollments description: Permissions for viewing course enrollments and for enrolling or unenrolling learners. icon: People + hidden: false course_files: applet: course_authoring display_name: Files description: Permissions for viewing and managing files and assets uploaded to the course. icon: Folder + hidden: false course_grading: applet: course_authoring display_name: Grading description: Permissions related to viewing and managing grading configuration and grading policies. icon: Award + hidden: false course_import_export: applet: course_authoring display_name: Import / export description: Permissions for importing and exporting course content and related data. icon: Download + hidden: false course_information: applet: learner_administration display_name: Course information description: Permissions for viewing general course information. icon: Info + hidden: false course_learner_extensions: applet: learner_administration display_name: Learner extensions description: Permissions for viewing and managing due date extensions for individual learners. icon: Event + hidden: false course_learner_grading: applet: learner_grading display_name: Learner grading description: Permissions for viewing learner grades and using grading tools for individual learners or all learners. icon: Grading + hidden: false course_legacy: applet: course_team_roles display_name: Legacy compatibility description: Internal compatibility permissions that map legacy course roles to the authorization system. Not shown as individually assignable permissions. icon: DrawShapes + hidden: true course_library_updates: applet: course_authoring display_name: Library updates description: Permissions for reviewing and managing updates made to content libraries connected to the course. icon: LibraryBooks + hidden: false course_other: applet: course_authoring display_name: Other description: Additional permissions not included in other categories, such as viewing checklists. icon: DrawShapes + hidden: false course_pages_resources: applet: course_authoring display_name: Pages & resources description: Permissions for viewing and managing course pages and additional learning resources. icon: Article + hidden: false course_schedule_details: applet: course_authoring display_name: Schedule & details description: Permissions for viewing and editing the course schedule and course information. icon: Calendar + hidden: false course_tags_taxonomies: applet: course_authoring display_name: Tags description: Permissions for managing tags used to organize course content. icon: LocalOffer + hidden: false course_team_group: applet: course_authoring display_name: Course team & groups description: Permissions for viewing and managing the course team, learner groups, and group configurations. icon: Group + hidden: false course_updates_handouts: applet: course_authoring display_name: Course updates & handouts description: Permissions for viewing and managing course updates and handouts that are visible to learners. icon: Sync + hidden: false library: applet: content_libraries display_name: Library description: Permissions related to viewing, managing, and publishing the library structure and metadata. icon: CollectionsBookmark + hidden: false library_collection: applet: content_libraries display_name: Collection description: Permissions for creating and managing content collections within the library. icon: AutoAwesomeMosaic + hidden: false library_content: applet: content_libraries display_name: Content description: Permissions for editing, publishing, and reusing content within the library. icon: Notes + hidden: false library_team: applet: content_libraries display_name: Team description: Permissions for viewing and managing users who have access to the library. icon: Group + hidden: false diff --git a/src/openedx_authz/api/catalog.py b/src/openedx_authz/api/catalog.py index 6c65f7d9..de9fd15c 100644 --- a/src/openedx_authz/api/catalog.py +++ b/src/openedx_authz/api/catalog.py @@ -17,8 +17,9 @@ def get_permission_catalog(scope_types: list[str]) -> list[AuthzPermissionDefinition]: """Return the permissions that can be granted in any of the scope types. - A permission qualifies when any of the scope types is among its supported ``scopes``. Each - permission is loaded with its category. + A permission qualifies when any of the scope types is among its supported ``scopes`` and it is + visible: neither the permission nor its category is hidden. Each permission is loaded with its + category. Args: scope_types (list[str]): The scope types (e.g., ['course-v1', 'lib']). @@ -27,7 +28,8 @@ def get_permission_catalog(scope_types: list[str]) -> list[AuthzPermissionDefini list[AuthzPermissionDefinition]: The matching permissions, ordered by namespace and name """ return list( - AuthzPermissionDefinition.objects.supporting_scope_types(scope_types) + AuthzPermissionDefinition.objects.visible() + .supporting_scope_types(scope_types) .select_related("category") .order_by("namespace", "name") ) @@ -56,7 +58,8 @@ def get_role_catalog(scope_types: list[str]) -> list[dict]: """Return the roles that can be assigned in any of the scope types, with their grants in them. A role is included when it has at least one permission grant in any of the scope types and is - not hidden. Roles and their grants are read only from the stored schema definitions, never + not hidden. Hidden permissions, and permissions in hidden categories, are left out of + ``permissions``. Roles and their grants are read only from the stored schema definitions, never from the Casbin policy, so a role without a stored definition is not listed. Hidden roles are never included, even if they are assigned to users. diff --git a/src/openedx_authz/applets/course_team_roles/schema/legacy_permissions.yaml b/src/openedx_authz/applets/course_team_roles/schema/legacy_permissions.yaml index 7e3549a0..730de3ea 100644 --- a/src/openedx_authz/applets/course_team_roles/schema/legacy_permissions.yaml +++ b/src/openedx_authz/applets/course_team_roles/schema/legacy_permissions.yaml @@ -6,6 +6,7 @@ permission_categories: display_name: Legacy compatibility description: Internal compatibility permissions that map legacy course roles to the authorization system. Not shown as individually assignable permissions. icon: DrawShapes + hidden: true permissions: - namespace: courses diff --git a/src/openedx_authz/engine/renderer.py b/src/openedx_authz/engine/renderer.py index ff959045..97e94e91 100644 --- a/src/openedx_authz/engine/renderer.py +++ b/src/openedx_authz/engine/renderer.py @@ -456,6 +456,7 @@ def _diff_definitions(self, schema: CompiledSchema) -> dict[str, DefinitionDiff] definition.display_name == obj.display_name and (definition.description or "") == obj.description and definition.icon == obj.icon + and definition.hidden == obj.hidden ), ), "permissions": self._diff_kind( @@ -470,6 +471,7 @@ def _diff_definitions(self, schema: CompiledSchema) -> dict[str, DefinitionDiff] and definition.icon == obj.icon and list(definition.scopes) == list(obj.scopes or []) and definition.category_id == (obj.category.category_id if obj.category_id else "") + and definition.hidden == obj.hidden ), ), "roles": self._diff_kind( @@ -583,6 +585,7 @@ def source_obj(record): "display_name": definition.display_name, "description": definition.description or "", "icon": definition.icon, + "hidden": definition.hidden, }, ) category_objs[cid] = obj @@ -604,6 +607,7 @@ def source_obj(record): "category": category_objs.get(definition.category_id), "scopes": list(definition.scopes), "icon": definition.icon, + "hidden": definition.hidden, }, ) permission_objs[pid] = obj diff --git a/src/openedx_authz/engine/schema/authz-schema-v1.json b/src/openedx_authz/engine/schema/authz-schema-v1.json index 61583055..7a81522b 100644 --- a/src/openedx_authz/engine/schema/authz-schema-v1.json +++ b/src/openedx_authz/engine/schema/authz-schema-v1.json @@ -195,6 +195,13 @@ "title": "Category icon", "examples": ["Article"], "$ref": "#/$defs/icon" + }, + "hidden": { + "title": "Category hidden", + "description": "Whether normal discovery and selection interfaces omit this category and all of its permissions.", + "type": "boolean", + "default": false, + "examples": [false] } } }, @@ -243,6 +250,13 @@ "title": "Permission icon", "examples": ["Visibility"], "$ref": "#/$defs/icon" + }, + "hidden": { + "title": "Permission hidden", + "description": "Whether normal discovery and selection interfaces, and role details, omit this permission.", + "type": "boolean", + "default": false, + "examples": [false] } } }, diff --git a/src/openedx_authz/engine/schema/loading.py b/src/openedx_authz/engine/schema/loading.py index bf7e85de..ed754bd9 100644 --- a/src/openedx_authz/engine/schema/loading.py +++ b/src/openedx_authz/engine/schema/loading.py @@ -84,6 +84,7 @@ def _build_category(self, item: dict, source: SourceRecord) -> PermissionCategor display_name=item.get("display_name", ""), description=item.get("description", ""), icon=item.get("icon"), + hidden=bool(item.get("hidden", False)), ) def _build_permission(self, item: dict, source: SourceRecord) -> PermissionDefinition: @@ -97,6 +98,7 @@ def _build_permission(self, item: dict, source: SourceRecord) -> PermissionDefin category_id=item.get("category_id", ""), scopes=self._as_tuple(item.get("scopes")), icon=item.get("icon"), + hidden=bool(item.get("hidden", False)), ) def _build_role(self, item: dict, source: SourceRecord) -> RoleDefinition: diff --git a/src/openedx_authz/engine/schema/types/definitions.py b/src/openedx_authz/engine/schema/types/definitions.py index 91e61720..f906246b 100644 --- a/src/openedx_authz/engine/schema/types/definitions.py +++ b/src/openedx_authz/engine/schema/types/definitions.py @@ -15,12 +15,18 @@ @dataclass(frozen=True) class PermissionCategory: - """A display/grouping category for permissions. Grants no access.""" + """A display/grouping category for permissions. Grants no access. + + A hidden category is excluded from normal discovery/selection, and so are + all of its permissions. It keeps its definition, role grants, and permission + checks. + """ id: str display_name: str description: str icon: str | None = None + hidden: bool = False @dataclass(frozen=True) @@ -29,6 +35,9 @@ class PermissionDefinition: The complete permission ID (used by role definitions, extensions, app checks, and API responses) is :attr:`identifier`. + + A hidden permission is excluded from normal discovery/selection and from + role details. It keeps its role grants and permission checks. """ namespace: str @@ -43,6 +52,7 @@ class PermissionDefinition: category_id: str scopes: tuple[str, ...] icon: str | None = None + hidden: bool = False @property def identifier(self) -> str: diff --git a/src/openedx_authz/migrations/0013_add_hidden_to_categories_and_permissions.py b/src/openedx_authz/migrations/0013_add_hidden_to_categories_and_permissions.py new file mode 100644 index 00000000..25700cb4 --- /dev/null +++ b/src/openedx_authz/migrations/0013_add_hidden_to_categories_and_permissions.py @@ -0,0 +1,22 @@ +# Generated by Django 5.2.19 on 2026-11-17 01:49 + +from django.db import migrations, models + + +class Migration(migrations.Migration): + dependencies = [ + ("openedx_authz", "0012_move_builtin_schema_sources_to_applets"), + ] + + operations = [ + migrations.AddField( + model_name="authzpermissioncategory", + name="hidden", + field=models.BooleanField(default=False), + ), + migrations.AddField( + model_name="authzpermissiondefinition", + name="hidden", + field=models.BooleanField(default=False), + ), + ] diff --git a/src/openedx_authz/models/schema.py b/src/openedx_authz/models/schema.py index 33081ce9..ddd937c4 100644 --- a/src/openedx_authz/models/schema.py +++ b/src/openedx_authz/models/schema.py @@ -147,6 +147,10 @@ def __str__(self): class AuthzPermissionDefinitionQuerySet(models.QuerySet): """QuerySet for AuthzPermissionDefinition with catalog lookups.""" + def visible(self) -> "AuthzPermissionDefinitionQuerySet": + """Return the permissions that are not hidden, nor in a hidden category.""" + return self.filter(hidden=False).exclude(category__hidden=True) + def supporting_scope_types(self, scope_types: list[str]) -> "AuthzPermissionDefinitionQuerySet": """Return permissions that can be granted in any of the scope types. @@ -162,12 +166,16 @@ class AuthzPermissionCategory(TimeStampedModel): """A display/grouping category for permissions (grants no access). .. no_pii: + + A hidden category is excluded from normal discovery/selection together with + all of its permissions; it keeps its definition and role grants. """ category_id = models.CharField(max_length=255, unique=True) display_name = models.CharField(max_length=255) description = models.TextField(blank=True, default="") icon = models.CharField(max_length=128, blank=True, null=True) + hidden = models.BooleanField(default=False) sources = models.ManyToManyField(AuthzSchemaSource, through="AuthzCategorySource", related_name="categories") class Meta: @@ -201,6 +209,7 @@ class AuthzPermissionDefinition(TimeStampedModel): ) scopes = models.JSONField(default=list) icon = models.CharField(max_length=128, blank=True, null=True) + hidden = models.BooleanField(default=False) sources = models.ManyToManyField(AuthzSchemaSource, through="AuthzPermissionSource", related_name="permissions") class Meta: @@ -232,9 +241,14 @@ def visible(self) -> "AuthzRoleDefinitionQuerySet": def with_grants_in_scope_types(self, scope_types: list[str]) -> "AuthzRoleDefinitionQuerySet": """Return the roles with a permission grant in any of the scope types, with those grants loaded. - Each role gets its grants in the scope types, with their permission, in ``grants``. + Each role gets its grants in the scope types, with their permission, in ``grants``. Grants of + hidden permissions, or of permissions in hidden categories, are not loaded. """ - grants = AuthzRolePermission.objects.filter(scope__in=scope_types).select_related("permission") + grants = ( + AuthzRolePermission.objects.filter(scope__in=scope_types, permission__hidden=False) + .exclude(permission__category__hidden=True) + .select_related("permission") + ) return ( self.filter(role_permissions__scope__in=scope_types) .distinct() diff --git a/src/openedx_authz/tests/api/test_catalog.py b/src/openedx_authz/tests/api/test_catalog.py index 948451ec..6e4d5683 100644 --- a/src/openedx_authz/tests/api/test_catalog.py +++ b/src/openedx_authz/tests/api/test_catalog.py @@ -80,6 +80,43 @@ def test_loads_category_without_extra_queries(self): self.assertEqual(sorted(c.category_id for c in categories if c), ["content", "team"]) +class TestHiddenPermissionsAndCategories(CatalogTestCase): + """Hidden permissions and categories are left out of the catalog.""" + + def test_hidden_permission_is_excluded(self): + """A hidden permission is not in the permission catalog or in role details.""" + AuthzPermissionDefinition.objects.filter(pk=self.view_course.pk).update(hidden=True) + + assert [p.identifier for p in get_permission_catalog(["course-v1"])] == ["common.manage_team"] + (role,) = get_role_catalog(["course-v1"]) + assert role["permissions"] == ["common.manage_team"] + + def test_hidden_category_hides_its_permissions(self): + """Permissions of a hidden category are excluded even when they are not hidden themselves.""" + AuthzPermissionCategory.objects.filter(pk=self.team.pk).update(hidden=True) + + permissions = get_permission_catalog(["course-v1", "lib"]) + + assert [p.identifier for p in permissions] == ["content_libraries.view_library", "courses.view_course"] + assert [c.category_id for c in get_category_catalog(permissions)] == ["content"] + (role,) = get_role_catalog(["course-v1", "lib"]) + assert role["permissions"] == ["content_libraries.view_library", "courses.view_course"] + + def test_category_with_only_hidden_permissions_is_excluded(self): + """A visible category whose permissions are all hidden is not returned.""" + AuthzPermissionDefinition.objects.filter(pk=self.view_course.pk).update(hidden=True) + + categories = get_category_catalog(get_permission_catalog(["course-v1"])) + + assert [c.category_id for c in categories] == ["team"] + + def test_hiding_keeps_grants(self): + """Hiding a permission does not remove its role grants.""" + AuthzPermissionDefinition.objects.filter(pk=self.view_course.pk).update(hidden=True) + + assert AuthzRolePermission.objects.filter(permission=self.view_course).exists() + + class TestGetCategoryCatalog(CatalogTestCase): """Tests for get_category_catalog.""" diff --git a/src/openedx_authz/tests/schema/factories.py b/src/openedx_authz/tests/schema/factories.py index eac9bd0a..ac500d87 100644 --- a/src/openedx_authz/tests/schema/factories.py +++ b/src/openedx_authz/tests/schema/factories.py @@ -58,6 +58,7 @@ def category(cid: str = "cat", **kwargs) -> PermissionCategory: display_name=kwargs.get("display_name", "Cat"), description=kwargs.get("description", "desc"), icon=kwargs.get("icon"), + hidden=kwargs.get("hidden", False), ) @@ -70,6 +71,7 @@ def permission(namespace="courses", name="view_course", *, cat="cat", scopes=("c category_id=cat, scopes=tuple(scopes), icon=kwargs.get("icon"), + hidden=kwargs.get("hidden", False), ) diff --git a/src/openedx_authz/tests/schema/test_apply.py b/src/openedx_authz/tests/schema/test_apply.py index 423d9023..4373b9c7 100644 --- a/src/openedx_authz/tests/schema/test_apply.py +++ b/src/openedx_authz/tests/schema/test_apply.py @@ -524,6 +524,33 @@ def test_hidden_flag_change_is_reported(self): assert plan.roles.updated == ["course_editor"] + def test_category_hidden_flag_change_is_reported(self): + """Flipping a category's ``hidden`` flag is reported as an update.""" + enforcer = FakeEnforcer() + _apply(enforcer, _editor(("courses.view_course",))) + + after = _doc( + roles=[role(rid="course_editor", permissions=("courses.view_course",))], + categories=[category(cid="cat", hidden=True)], + permissions=[permission(name="view_course", cat="cat")], + ) + plan = self._plan(enforcer, after) + + assert plan.categories.updated == ["cat"] + + def test_permission_hidden_flag_change_is_reported(self): + """Flipping a permission's ``hidden`` flag is reported as an update.""" + enforcer = FakeEnforcer() + _apply(enforcer, _editor(("courses.view_course",))) + + after = _doc( + roles=[role(rid="course_editor", permissions=("courses.view_course",))], + permissions=[permission(name="view_course", cat="cat", hidden=True)], + ) + plan = self._plan(enforcer, after) + + assert plan.permissions.updated == ["courses.view_course"] + def test_permission_metadata_change_is_reported(self): """Editing a permission's display name is reported as an update.""" enforcer = FakeEnforcer() diff --git a/src/openedx_authz/tests/schema/test_loading.py b/src/openedx_authz/tests/schema/test_loading.py index 52ee0595..453e4969 100644 --- a/src/openedx_authz/tests/schema/test_loading.py +++ b/src/openedx_authz/tests/schema/test_loading.py @@ -29,6 +29,7 @@ display_name: Course content description: Course content permissions. icon: Article + hidden: true permissions: - namespace: courses @@ -37,6 +38,14 @@ description: View a course. category_id: course_content scopes: [course-v1] + hidden: true + + - namespace: courses + name: edit_course + display_name: Edit course + description: Edit a course. + category_id: course_content + scopes: [course-v1] roles: - id: course_observer @@ -77,6 +86,9 @@ def test_loads_all_blocks_into_typed_objects(self): assert doc.categories[0].id == "course_content" assert doc.permissions[0].identifier == "courses.view_course" assert doc.permissions[0].scopes == ("course-v1",) + assert doc.categories[0].hidden is True + assert doc.permissions[0].hidden is True + assert doc.permissions[1].hidden is False assert doc.roles[0].hidden is True assert doc.roles[0].permissions == ("courses.view_course",) assert doc.role_extensions[0].role_id == "course_editor" @@ -695,7 +707,7 @@ def test_trailing_separator_is_ignored(self): def test_empty_document_between_separators_is_skipped(self): """An empty ``---`` block between contributions is silently dropped.""" - contents = b"schema_version: '1.0'\npriority: 1\n" b"---\n" b"---\n" b"schema_version: '1.0'\npriority: 2\n" + contents = b"schema_version: '1.0'\npriority: 1\n---\n---\nschema_version: '1.0'\npriority: 2\n" docs = _load(contents) diff --git a/src/openedx_authz/tests/schema/test_snapshot.py b/src/openedx_authz/tests/schema/test_snapshot.py index 754a803c..d9945cbd 100644 --- a/src/openedx_authz/tests/schema/test_snapshot.py +++ b/src/openedx_authz/tests/schema/test_snapshot.py @@ -98,12 +98,14 @@ def test_definition_renderers_shape_each_snapshot_section(self): "category_id": "course_content", "scopes": ["course"], "icon": None, + "hidden": False, } assert render_category(category) == { "applet": "course_authoring", "display_name": "Course content", "description": "Course content operations", "icon": None, + "hidden": False, } def test_snapshot_data_orders_definition_identifiers(self): diff --git a/src/openedx_authz/tests/schema/test_source_storage.py b/src/openedx_authz/tests/schema/test_source_storage.py index f06763c3..a143f495 100644 --- a/src/openedx_authz/tests/schema/test_source_storage.py +++ b/src/openedx_authz/tests/schema/test_source_storage.py @@ -275,6 +275,28 @@ def test_hidden_flag_can_be_cleared(self): self.assertFalse(AuthzRoleDefinition.objects.get(role_id="course_auditor").hidden) + def test_category_and_permission_hidden_flags_reach_the_database(self): + """``hidden`` on categories and permissions is persisted and can be cleared.""" + + def doc(hidden): + return make_document( + "core", + priority=100, + categories=[category("cat", hidden=hidden)], + permissions=[permission(name="view_course", cat="cat", hidden=hidden)], + roles=[role(rid="course_admin", permissions=("courses.view_course",))], + ) + + _store(doc(True)) + + assert AuthzPermissionCategory.objects.get(category_id="cat").hidden + assert AuthzPermissionDefinition.objects.get(namespace="courses", name="view_course").hidden + + _store(doc(False)) + + assert not AuthzPermissionCategory.objects.get(category_id="cat").hidden + assert not AuthzPermissionDefinition.objects.get(namespace="courses", name="view_course").hidden + class TestDefinitionDisplay(TestCase): """Human-readable identifiers used by the Django admin fallback (ADR 0018 ยง7).""" diff --git a/src/openedx_authz/tests/schema/test_syntax.py b/src/openedx_authz/tests/schema/test_syntax.py index bda7340e..5d1e0aa3 100644 --- a/src/openedx_authz/tests/schema/test_syntax.py +++ b/src/openedx_authz/tests/schema/test_syntax.py @@ -167,6 +167,16 @@ def test_non_pascalcase_icon_is_error(self, icon): """An icon name that is not PascalCase is rejected before the export check.""" assert validation_messages(category_data(icon=icon)) + @pytest.mark.parametrize("builder", [category_data, permission_data]) + def test_hidden_flag_must_be_a_boolean(self, builder): + """Categories and permissions accept boolean ``hidden`` values only.""" + valid = builder() + block = next(key for key in valid if key not in ("schema_version", "priority")) + + for value, ok in ((True, True), (False, True), ("yes", False), (1, False)): + data = {**valid, block: [{**valid[block][0], "hidden": value}]} + assert (not validation_messages(data)) is ok + def test_non_string_icon_is_error(self): """Icon values must be strings before semantic membership validation.""" messages = validation_messages(category_data(icon=123))