Merge 8cb0b3e7f6 into d8be2ad942

Fixes: #1990

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

changelogs/client_server/newsfragments/2212.clarification

@@ -0,0 +1 @@
+Add note to each endpoint that uses capability negotiation and document expected response when the capability is not available.

changelogs/client_server/newsfragments/2217.clarification

@@ -0,0 +1 @@
+The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment.

content/client-server-api/modules/content_repo.md

@@ -134,9 +134,14 @@ entity isn't in the room.
 `mxc://` URIs are vulnerable to directory traversal attacks such as
 `mxc://127.0.0.1/../../../some_service/etc/passwd`. This would cause the
 target homeserver to try to access and return this file. As such,
-homeservers MUST sanitise `mxc://` URIs by allowing only alphanumeric
-(`A-Za-z0-9`), `_` and `-` characters in the `server-name` and
-`media-id` values. This set of whitelisted characters allows URL-safe
+homeservers MUST sanitise `mxc://` URIs by:
+
+-   restricting the `server-name` segment to valid
+    [server names](/appendices/#server-name)
+-   allowing only alphanumeric (`A-Za-z0-9`), `_` and `-` characters in
+    the `media-id` segment
+
+The resulting set of whitelisted characters allows URL-safe
 base64 encodings specified in RFC 4648. Applying this character
 whitelist is preferable to blacklisting `.` and `/` as there are
 techniques around blacklisted characters (percent-encoded characters,

data/api/client-server/administrative_contact.yaml

@@ -99,6 +99,10 @@ paths:
         has been removed, making this endpoint behave as though it was `false`.
         This results in this endpoint being an equivalent to `/3pid/bind` rather
         than dual-purpose.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: post3PIDs
       deprecated: true
       security:
@@ -176,6 +180,18 @@ paths:
                   value: {
                     "submit_url": "https://example.org/path/to/submitToken"
                   }
+        "400":
+          description: The 3PID changes capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "3PID changes are disabled on this server."
+                  }
         "403":
           description: The credentials could not be verified with the identity server.
           content:
@@ -202,6 +218,10 @@ paths:
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
 
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
+
         {{% boxes/warning %}}
         Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
@@ -244,6 +264,18 @@ paths:
               examples:
                 response:
                   value: {}
+        "400":
+          description: The 3PID changes capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "3PID changes are disabled on this server."
+                  }
         "401":
           description: The homeserver requires additional authentication information.
           content:
@@ -331,6 +363,10 @@ paths:
         Unlike other endpoints, this endpoint does not take an `id_access_token`
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: delete3pidFromAccount
       security:
         - accessTokenQuery: []
@@ -389,6 +425,18 @@ paths:
                     example: success
                 required:
                   - id_server_unbind_result
+        "400":
+          description: The 3PID changes capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "3PID changes are disabled on this server."
+                  }
       tags:
         - Account management
   /account/3pid/unbind:

data/api/client-server/login_token.yaml

@@ -110,6 +110,18 @@ paths:
             application/json:
               schema:
                 $ref: definitions/auth_response.yaml
+        "404":
+          description: The get login token capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNRECOGNIZED",
+                    "error": "The get login token capability is not available."
+                  }
         "429":
           description: This request was rate-limited.
           content:

data/api/client-server/password_management.yaml

@@ -34,6 +34,10 @@ paths:
         valid access token is provided. The homeserver SHOULD NOT revoke the
         access token provided in the request. Whether other access tokens for
         the user are revoked depends on the request parameters.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability)
+        to determine if this endpoint is available.
       security:
         - {}
         - accessTokenQuery: []
@@ -82,6 +86,18 @@ paths:
             application/json:
               schema:
                 $ref: definitions/auth_response.yaml
+        "403":
+          description: The password change capability is not available.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Password change is disabled."
+                  }
         "429":
           description: This request was rate-limited.
           content:

data/api/client-server/profile.yaml

@@ -29,6 +29,11 @@ paths:
         Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
         them rather than treating `null` as a deletion request. Clients that want to delete a
         field, including its key and value, SHOULD use the `DELETE` endpoint instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation)
+        depending on the `keyName`. Clients SHOULD check the value of the
+        [`m.profile_fields` capability](/client-server-api/#mprofile_fields-capability) to detect
+        which `keyName`s they are allowed to modify.
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -116,6 +121,12 @@ paths:
                       "errcode": "M_INVALID_PARAM",
                       "error": "Invalid profile key.",
                     }
+                capability_disabled:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile modification is disabled on this homeserver.",
+                    }
         "403":
           description: The server is unwilling to perform the operation, either
             due to insufficient permissions or because profile modifications