From c39e86504ad00dbc8a3edfcd3a58d117137f32fa Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Mon, 7 Oct 2024 16:24:35 -0700 Subject: [PATCH] groups: Rework documentation of permitted values. Ths hardcoded documentation of which values are possible was destined to end up inaccurate and out-of-date; and meanwhile, we do have a part of the API that already has these data in machine-readable format. --- api_docs/group-setting-values.md | 26 ++++++++++++++++++ zerver/openapi/zulip.yaml | 46 ++++++++------------------------ 2 files changed, 37 insertions(+), 35 deletions(-) diff --git a/api_docs/group-setting-values.md b/api_docs/group-setting-values.md index 62a20b8aac..24653c80b4 100644 --- a/api_docs/group-setting-values.md +++ b/api_docs/group-setting-values.md @@ -88,3 +88,29 @@ accidentally reverts the first one without either user noticing. Omitting `old` is appropriate where the intent really is a new complete list rather than an edit, for example in an integration that syncs the list from an external source of truth. + +## Permitted values + +Not every possible group-setting value is a valid configuration for a +given group-based setting. For example, as a security hardening +measure, some administrative permissions should never be exercised by +guest users, and the system group for all users, including guests, +should not be offered to users as an option for those settings. + +Others have restrictions to only permit system groups due to UI +components not yet having been migrated to support a broader set of +values. In order to avoid this configuration ending up hardcoded in +clients, every permission setting using this framework has an entry in +the `server_supported_permission_settings` section of the [`POST +/register`](/api/register-queue) response. + +Clients that support mutating group-settings values must parse that +part of the `register` payload in order to compute the set of +permitted values to offer to the user and avoid server-side errors +when trying to save a value. + +Note specifically that the `allow_everyone_group` field, which +determines whether the setting can have the value of "all user +accounts, including guests" also controls whether guests users can +exercise the permission regardless of their membership in the +group-setting value. diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index e78485ec37..ad1ed2d12f 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -4304,9 +4304,6 @@ paths: the set of users who have permission to create user groups in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - and `"role:nobody"` system groups. - **Changes**: New in Zulip 10.0 (feature level 299). Previously `user_group_edit_policy` field used to control the permission to create user groups. @@ -4318,9 +4315,6 @@ paths: defining the set of users who have permission to administer all existing groups in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - and `"role:nobody"` system groups. - **Changes**: Semantics to change in Zulip 10.0 (feature level TBD). The original implementation of this setting had different semantics, where only users who were a @@ -4348,9 +4342,6 @@ paths: the set of users who have permission to create public channels in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - `"role:owners"` and `"role:nobody"` system groups. - **Changes**: New in Zulip 9.0 (feature level 264). Previously `realm_create_public_stream_policy` field used to control the permission to create public channels. @@ -4362,9 +4353,6 @@ paths: the set of users who have permission to create private channels in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - `"role:owners"` and `"role:nobody"` system groups. - **Changes**: New in Zulip 9.0 (feature level 266). Previously `realm_create_private_stream_policy` field used to control the permission to create private channels. @@ -4376,10 +4364,6 @@ paths: the set of users who have permission to create web-public channels in this organization. - This setting can only be set to `"role:moderators"`, - `"role:administrators"`, `"role:owners"` and - `"role:nobody"` system groups. - **Changes**: New in Zulip 10.0 (feature level 280). Previously `realm_create_web_public_stream_policy` field used to control the permission to create web-public channels. @@ -16121,9 +16105,6 @@ paths: the set of users who have permission to create user groups in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - and `"role:nobody"` system groups. - **Changes**: New in Zulip 10.0 (feature level 299). Previously `realm_user_group_edit_policy` field used to control the permission to create user groups. @@ -16135,9 +16116,6 @@ paths: defining the set of users who have permission to administer all existing groups in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - and `"role:nobody"` system groups. - **Changes**: Semantics to change in Zulip 10.0 (feature level TBD). The original implementation of this setting had different semantics, where only users who were a @@ -16165,9 +16143,6 @@ paths: the set of users who have permission to create public channels in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - `"role:owners"` and `"role:nobody"` system groups. - **Changes**: New in Zulip 9.0 (feature level 264). Previously `realm_create_public_stream_policy` field used to control the permission to create public channels. @@ -16179,9 +16154,6 @@ paths: the set of users who have permission to create private channels in this organization. - This setting cannot be set to `"role:internet"`, `"role:everyone"`, - `"role:owners"` and `"role:nobody"` system groups. - **Changes**: New in Zulip 9.0 (feature level 266). Previously `realm_create_private_stream_policy` field used to control the permission to create private channels. @@ -16193,10 +16165,6 @@ paths: the set of users who have permission to create web-public channels in this organization. - This setting can only be set to `"role:moderators"`, - `"role:administrators"`, `"role:owners"` and - `"role:nobody"` system groups. - Has no effect and should not be displayed in settings UI unless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED` server-level setting enabled and the organization has enabled @@ -18073,10 +18041,15 @@ paths: description: | Present if `realm` is present in `fetch_event_types`. - Configuration for various group permission settings. + Metadata detailing the valid values for permission settings that + use [group-setting values](/api/group-setting-values). Clients + should use these data as explained in the + [main documentation](/api/group-setting-values#permitted-values) + to determine what values to present as possible values for these + settings in UI components. - We consider this part of the Zulip API to be unstable - and may change significantly in future versions. + This part of the Zulip API is unstable and may change + significantly in future versions. **Changes**: New in Zulip 8.0 (feature level 221). type: object @@ -23049,6 +23022,9 @@ components: type: boolean description: | Whether the setting can be set to `role:everyone` system group. + + If false, guest users cannot exercise this permission even if they are part of + the [group-setting value](/api/group-setting-values) for this setting. default_group_name: type: string description: |