Merge fc19945bdc into 3e1cbe12f7

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>

changelogs/client_server/newsfragments/2320.feature

@@ -0,0 +1 @@
+Add the OAuth 2.0 Device Authorization Grant (RFC 8628) as a supported grant type, as per [MSC4341](https://github.com/matrix-org/matrix-spec-proposals/pull/4341).

changelogs/client_server/newsfragments/2336.clarification

@@ -0,0 +1 @@
+Order the common and other error codes alphabetically and remove duplicate `M_THREEPID_IN_USE` definition.

changelogs/identity_service/newsfragments/2336.clarification

@@ -0,0 +1 @@
+Order the standard error codes alphabetically.

content/client-server-api/_index.md

@@ -93,48 +93,27 @@ request being made was invalid.
 
 These error codes can be returned by any API endpoint:
 
-`M_FORBIDDEN`
-: Forbidden access, e.g. joining a room without permission, failed login.
-
-`M_UNKNOWN_TOKEN`
-: The access or refresh token specified was not recognised.
-
-: An additional response parameter, `soft_logout`, might be present on the
-response for 401 HTTP status codes. See [the soft logout
-section](#soft-logout) for more information.
-
-`M_MISSING_TOKEN`
-: No access token was specified for the request.
-
-`M_USER_LOCKED`
-: The account has been [locked](#account-locking) and cannot be used at this time.
-
-`M_USER_SUSPENDED`
-: The account has been [suspended](#account-suspension) and can only be used for
-limited actions at this time.
+<!-- Please keep the error codes below in alphabetical order -->
 
 `M_BAD_JSON`
 : Request contained valid JSON, but it was malformed in some way, e.g.
 missing required keys, invalid values for keys.
 
-`M_NOT_JSON`
-: Request did not contain valid JSON.
-
-`M_NOT_FOUND`
-: No resource was found for this request.
+`M_FORBIDDEN`
+: Forbidden access, e.g. joining a room without permission, failed login.
 
 `M_LIMIT_EXCEEDED`
 : Too many requests have been sent in a short period of time. Wait a while
 then try again. See [Rate limiting](#rate-limiting).
 
-`M_UNRECOGNIZED`
-: The server did not understand the request. This is expected to be returned with
-a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
-code if the endpoint is implemented, but the incorrect HTTP method is used.
+`M_MISSING_TOKEN`
+: No access token was specified for the request.
 
-`M_UNKNOWN_DEVICE`
-: {{% added-in v="1.17" %}} The device ID supplied by the application service does
-not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
+`M_NOT_FOUND`
+: No resource was found for this request.
+
+`M_NOT_JSON`
+: Request did not contain valid JSON.
 
 `M_RESOURCE_LIMIT_EXCEEDED`
 : The request cannot be completed because the homeserver has reached a
@@ -181,39 +160,85 @@ limit is a hard limit that cannot be increased.
 `M_UNKNOWN`
 : An unknown error has occurred.
 
+`M_UNKNOWN_DEVICE`
+: {{% added-in v="1.17" %}} The device ID supplied by the application service does
+not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
+
+`M_UNKNOWN_TOKEN`
+: The access or refresh token specified was not recognised.
+
+: An additional response parameter, `soft_logout`, might be present on the
+response for 401 HTTP status codes. See [the soft logout
+section](#soft-logout) for more information.
+
+`M_UNRECOGNIZED`
+: The server did not understand the request. This is expected to be returned with
+a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
+code if the endpoint is implemented, but the incorrect HTTP method is used.
+
+`M_USER_LOCKED`
+: The account has been [locked](#account-locking) and cannot be used at this time.
+
+`M_USER_SUSPENDED`
+: The account has been [suspended](#account-suspension) and can only be used for
+limited actions at this time.
+
+<!-- Please keep the error codes above in alphabetical order -->
+
 #### Other error codes
 
 The following error codes are specific to certain endpoints.
 
 <!-- TODO: move them to the endpoints that return them -->
 
-`M_UNAUTHORIZED`
-: The request was not correctly authorized. Usually due to login failures.
+<!-- Please keep the error codes below in alphabetical order -->
 
-`M_USER_DEACTIVATED`
-: The user ID associated with the request has been deactivated. Typically
-for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
+`M_BAD_STATE`
+: The state change requested cannot be performed, such as attempting to
+unban a user who is not banned.
 
-`M_USER_IN_USE`
-: Encountered when trying to register a user ID which has been taken.
+`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
+: The user is unable to reject an invite to join the server notices room.
+See the [Server Notices](#server-notices) module for more information.
+
+`M_CAPTCHA_INVALID`
+: The Captcha provided did not match what was expected.
+
+`M_CAPTCHA_NEEDED`
+: A Captcha is required to complete the request.
+
+`M_EXCLUSIVE`
+: The resource being requested is reserved by an application service, or
+the application service making the request has not created the resource.
+
+`M_GUEST_ACCESS_FORBIDDEN`
+: The room or resource does not permit guests to access it.
+
+`M_INCOMPATIBLE_ROOM_VERSION`
+: The client attempted to join a room that has a version the server does
+not support. Inspect the `room_version` property of the error response
+for the room's version.
+
+`M_INVALID_PARAM`
+: A parameter that was specified has the wrong value. For example, the
+server expected an integer and instead received a string.
+
+`M_INVALID_ROOM_STATE`
+: Sent when the initial state given to the `createRoom` API is invalid.
 
 `M_INVALID_USERNAME`
 : Encountered when trying to register a user ID which is not valid.
 
+`M_MISSING_PARAM`
+: A required parameter was missing from the request.
+
 `M_ROOM_IN_USE`
 : Sent when the room alias given to the `createRoom` API is already in
 use.
 
-`M_INVALID_ROOM_STATE`
-: Sent when the initial state given to the `createRoom` API is invalid.
-
-`M_THREEPID_IN_USE`
-: Sent when a threepid given to an API cannot be used because the same
-threepid is already in use.
-
-`M_THREEPID_NOT_FOUND`
-: Sent when a threepid given to an API cannot be used because no record
-matching the threepid was found.
+`M_SERVER_NOT_TRUSTED`
+: The client's request used a third-party server, e.g. identity server,
+that this server does not trust.
 
 `M_THREEPID_AUTH_FAILED`
 : Authentication could not be performed on the third-party identifier.
@@ -223,56 +248,35 @@ matching the threepid was found.
 if the server only permits, for example, email addresses from a
 particular domain.
 
-`M_SERVER_NOT_TRUSTED`
-: The client's request used a third-party server, e.g. identity server,
-that this server does not trust.
+`M_THREEPID_IN_USE`
+: The third party identifier specified by the client is not acceptable because it is
+already in use in some way.
+
+`M_THREEPID_MEDIUM_NOT_SUPPORTED`
+: The homeserver does not support adding a third party identifier of the given medium.
+
+`M_THREEPID_NOT_FOUND`
+: Sent when a threepid given to an API cannot be used because no record
+matching the threepid was found.
+
+`M_TOO_LARGE`
+: The request or entity was too large.
+
+`M_UNAUTHORIZED`
+: The request was not correctly authorized. Usually due to login failures.
 
 `M_UNSUPPORTED_ROOM_VERSION`
 : The client's request to create a room used a room version that the
 server does not support.
 
-`M_INCOMPATIBLE_ROOM_VERSION`
-: The client attempted to join a room that has a version the server does
-not support. Inspect the `room_version` property of the error response
-for the room's version.
+`M_USER_DEACTIVATED`
+: The user ID associated with the request has been deactivated. Typically
+for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
 
-`M_BAD_STATE`
-: The state change requested cannot be performed, such as attempting to
-unban a user who is not banned.
+`M_USER_IN_USE`
+: Encountered when trying to register a user ID which has been taken.
 
-`M_GUEST_ACCESS_FORBIDDEN`
-: The room or resource does not permit guests to access it.
-
-`M_CAPTCHA_NEEDED`
-: A Captcha is required to complete the request.
-
-`M_CAPTCHA_INVALID`
-: The Captcha provided did not match what was expected.
-
-`M_MISSING_PARAM`
-: A required parameter was missing from the request.
-
-`M_INVALID_PARAM`
-: A parameter that was specified has the wrong value. For example, the
-server expected an integer and instead received a string.
-
-`M_TOO_LARGE`
-: The request or entity was too large.
-
-`M_EXCLUSIVE`
-: The resource being requested is reserved by an application service, or
-the application service making the request has not created the resource.
-
-`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
-: The user is unable to reject an invite to join the server notices room.
-See the [Server Notices](#server-notices) module for more information.
-
-`M_THREEPID_MEDIUM_NOT_SUPPORTED`
-: The homeserver does not support adding a third party identifier of the given medium.
-
-`M_THREEPID_IN_USE`
-: The third party identifier specified by the client is not acceptable because it is
-already in use in some way.
+<!-- Please keep the error codes above in alphabetical order -->
 
 #### Rate limiting
 
@@ -556,7 +560,7 @@ endpoint.
 
 With the OAuth 2.0 API, a client can obtain an access token by using one of the
 [grant types](#grant-types) supported by the homeserver and authorizing the
-proper [scope](#scope), as demonstrated in the [login flow](#login-flow). To
+proper [scope](#scope), as demonstrated in the [login flows](#login-flows). To
 invalidate the access token the client must use [token revocation](#token-revocation).
 
 ### Using access tokens
@@ -1753,19 +1757,31 @@ authentication type.
 
 1. [Discover the OAuth 2.0 server metadata](#server-metadata-discovery).
 2. [Register the client with the homeserver](#client-registration).
-3. [Obtain an access token](#login-flow) by authorizing a [scope](#scope) for the client with the [authorization code grant](#authorization-code-grant).
+3. [Obtain an access token](#login-flows) by authorizing a [scope](#scope) for
+   the client with the [authorization code grant](#authorization-code-grant) or
+   [device authorization grant](#device-authorization-grant).
 4. [Refresh the access token](#token-refresh-flow) with the [refresh token grant](#refresh-token-grant) when it expires.
 5. [Revoke the tokens](#token-revocation) when the users wants to log out of the client.
 
-#### Login flow
+#### Login flows
 
-Logging in with the OAuth 2.0 API should be done with the [authorization code
-grant](#authorization-code-grant). In the context of the Matrix specification,
-this means requesting a [scope](#scope) including full client-server API
-read/write access and allocating a device ID.
+Logging in and obtaining an access token with the OAuth 2.0 API should be done
+using either the [authorization code grant](#authorization-code-grant) or
+[device authorization grant](#device-authorization-grant). In the context of the
+Matrix specification, this means requesting a [scope](#scope) including full
+client-server API read/write access and allocating a device ID.
 
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
-it needs to generate the following values:
+##### Authorization code flow
+
+This login flow uses the [authorization code grant](#authorization-code-grant)
+and is suitable for clients where the following criteria are met:
+
+- There is a web browser available for the user to complete authentication and
+  authorization.
+- The client can receive the callback via a redirect from the web browser.
+
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate the following values:
 
 - `device_id`: a unique identifier for this device; see the
   [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
@@ -1906,6 +1922,143 @@ Sample response:
 Finally, the client can call the  [`/whoami`](#get_matrixclientv3accountwhoami)
 endpoint to get the user ID that owns the access token.
 
+##### Device authorization flow
+
+{{% added-in v="1.18" %}}
+
+This flow uses the [device authorization grant](#device-authorization-grant) to
+allow clients to obtain an access token without needing to directly interact
+with a web browser. Instead, the user completes authorization on a web browser
+that can be a separate device.
+
+This is useful for devices with limited input
+capabilities (such as CLI applications or embedded devices) or where the
+redirect handling may be unreliable (such as a desktop applications).
+
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate following value:
+
+- `device_id`: a unique identifier for this device; see the
+  [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
+
+**Device authorization request**
+
+The client sends a `application/x-www-form-urlencoded` encoded `POST` request to
+the `device_authorization_endpoint` as defined in
+[RFC 8628 section 3.1](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1):
+
+| Parameter   | Value                                                          |
+|-------------|----------------------------------------------------------------|
+| `client_id` | The client ID returned from client registration.               |
+| `scope`     | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
+
+Sample device authorization request:
+
+```
+POST /oauth2/device HTTP/1.1
+Host: account.example.com
+Content-Type: application/x-www-form-urlencoded
+
+client_id=s6BhdRkqt3&scope=urn%3Amatrix%3Aclient%3Aapi%3A%2A%20urn%3Amatrix%3Aclient%3Adevice%3AAABBBCCCDDD
+```
+
+**Device authorization response**
+
+The server responds with a JSON object as defined in
+[RFC 8628 section 3.2](https://datatracker.ietf.org/doc/html/rfc8628#section-3.2),
+containing:
+
+| Parameter                    |                                                                                                                                               |
+|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| `device_code`                | The device verification code.                                                                                                                 |
+| `user_code`                  | An end-user verification code.                                                                                                                |
+| `verification_uri`           | The end-user verification URI on the authorization server.                                                                                    |
+| `verification_uri_complete`  | Optionally, the URI which doesn't require the user to manually type the `user_code`, designed for non-textual transmission.                   |
+| `expires_in`                 | The lifetime in seconds of the `device_code` and `user_code`.                                                                                 |
+| `interval`                   | The minimum number of seconds the client should wait between polling requests to the token endpoint. If omitted, clients should default to 5. |
+
+It is RECOMMENDED that the server provides a `verification_uri_complete` such
+that the user does not need to type in the `user_code`.
+
+Sample response:
+
+```json
+{
+  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
+  "user_code": "WDJB-MJHT",
+  "verification_uri": "https://account.example.com/link",
+  "verification_uri_complete": "https://account.example.com/link?user_code=WDJB-MJHT",
+  "expires_in": 1800,
+  "interval": 5
+}
+```
+
+**User interaction**
+
+The client conveys the `verification_uri_complete` (and/or `verification_uri`
+and `user_code`) to the user. How the client does this depends on the
+specific device characteristics and use case. For example:
+
+- A CLI application could display the `verification_uri` and `user_code` as text
+  for the user to type into their browser on another device.
+- An embedded device with a screen could encode the `verification_uri_complete`
+  (with fallback to `verification_uri`) as a QR code for the user to scan with
+  their phone.
+- A desktop application running on a platform that does not support callbacks
+  could launch the `verification_uri_complete` (with fallback to
+  `verification_uri`) in the system browser.
+
+The user opens the verification URI in a web browser, which may be on another
+device, and completes authentication and authorization.
+
+**Token polling**
+
+While the user is completing authorization, the client polls the
+`token_endpoint` for the outcome, at intervals no shorter than the `interval`
+value from the device authorization response.
+
+The poll request is a `POST` to the `token_endpoint` with the following
+parameters, encoded as `application/x-www-form-urlencoded` in the body:
+
+| Parameter     | Value                                                          |
+|---------------|----------------------------------------------------------------|
+| `grant_type`  | `urn:ietf:params:oauth:grant-type:device_code`                 |
+| `device_code` | The `device_code` from the device authorization response.      |
+| `client_id`   | The client ID returned from client registration.               |
+
+Sample token polling request:
+
+```
+POST /oauth2/token HTTP/1.1
+Host: account.example.com
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&client_id=s6BhdRkqt3
+```
+
+The server responds as defined in [RFC 8628 section
+3.5](https://datatracker.ietf.org/doc/html/rfc8628#section-3.5):
+
+- While authorization is pending, the server returns an `authorization_pending`
+  error (or `slow_down` if the client is polling too frequently).
+- If authorization is denied, the server returns an `access_denied` error.
+- If the device code expires, the server returns an `expired_token` error.
+- On successful authorization, the server returns a JSON object containing the
+  access token, token type, expiration time, refresh token, and scope:
+
+```json
+{
+  "access_token": "2YotnFZFEjr1zCsicMWpAA",
+  "token_type": "Bearer",
+  "expires_in": 299,
+  "refresh_token": "tGz3JOkF0XG5Qx2TlKWIA",
+  "scope": "urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD"
+}
+```
+
+Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
+endpoint to get the user ID that owns the access token.
+
 #### Token refresh flow
 
 Refreshing a token with the OAuth 2.0 API should be done with the [refresh token
@@ -2236,6 +2389,7 @@ The client must also have obtained a `client_id` by [registering with the server
 
 This specification supports the following grant types:
 - [Authorization code grant](#authorization-code-grant)
+- {{% added-in v="1.18" %}} [Device authorization grant](#device-authorization-grant)
 - [Refresh token grant](#refresh-token-grant)
 
 ##### Authorization code grant
@@ -2260,18 +2414,34 @@ To use this grant, homeservers and clients MUST:
   Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
   for clients with an HTTPS redirect URI.
 
-###### User registration
+##### Device authorization grant
 
-Clients can signal to the server that the user desires to register a new account
-by initiating the authorization code grant with the `prompt=create` parameter
-set in the authorization request as defined in [Initiating User Registration via
-OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
+{{% added-in v="1.18" %}}
 
-Whether the homeserver supports this parameter is advertised by the
-`prompt_values_supported` authorization server metadata.
+As per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), the device
+authorization grant lets clients on devices with limited input capabilities
+obtain an access token by having the user complete authorization on a separate
+device with a web browser.
 
-Servers that support this parameter SHOULD show the account registration UI in
-the browser.
+This grant requires the client to know the following [authorization server
+metadata](#server-metadata-discovery):
+
+- `device_authorization_endpoint`
+
+To use this grant, homeservers and clients MUST:
+
+- Support the device authorization grant as per
+  [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628).
+- Support the [refresh token grant](#refresh-token-grant).
+
+As with the [authorization code grant](#authorization-code-grant), when
+authorization is granted to a client, the homeserver MUST issue a refresh token
+to the client in addition to the access token. The access token and refresh
+token have the same lifetime constraints as described in the [refresh token
+grant](#refresh-token-grant) section.
+
+The full flow for using this grant is described in the
+[device authorization flow](#device-authorization-flow).
 
 ##### Refresh token grant
 
@@ -2378,6 +2548,22 @@ The server SHOULD return one of the following responses:
 - For other errors, the server returns a `400 Bad Request` response with error
   details
 
+#### User registration
+
+Clients can signal to the server that the user desires to register a new account
+by initiating the [authorization code grant](#authorization-code-grant) with the `prompt=create` parameter
+set in the authorization request as defined in [Initiating User Registration via
+OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
+
+Whether the homeserver supports this parameter is advertised by the
+`prompt_values_supported` authorization server metadata.
+
+Servers that support this parameter SHOULD show the account registration UI in
+the browser.
+
+The `prompt=create` parameter is not supported when using the [device
+authorization grant](#device-authorization-grant).
+
 #### Account management {id="oauth-20-account-management"}
 
 {{% added-in v="1.18" %}}

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

@@ -17,8 +17,8 @@ for added protection.
 {{% /boxes/note %}}
 
 A room's Policy Server is designated by the [`m.room.policy`](#mroompolicy) state
-event described below. If the state event is not set in the room or is incomplete,
-the room does *not* use a Policy Server. Similarly, if the server name in the state
+event described below. If the state event is not set in the room or is missing
+required fields, the room does *not* use a Policy Server. Similarly, if the server name in the state
 event has zero joined users in the room, the room also does *not* use a Policy
 Server.
 

content/identity-service-api.md

@@ -70,26 +70,7 @@ the keys `error` and `errcode` MUST always be present.
 
 Some standard error codes are below:
 
-`M_NOT_FOUND`
-: The resource requested could not be located.
-
-`M_MISSING_PARAMS`
-: The request was missing one or more parameters.
-
-`M_INVALID_PARAM`
-: The request contained one or more invalid parameters.
-
-`M_SESSION_NOT_VALIDATED`
-: The session has not been validated.
-
-`M_NO_VALID_SESSION`
-: A session could not be located for the given parameters.
-
-`M_SESSION_EXPIRED`
-: The session has expired and must be renewed.
-
-`M_INVALID_EMAIL`
-: The email address provided was not valid.
+<!-- Please keep the error codes below in alphabetical order -->
 
 `M_EMAIL_SEND_ERROR`
 : There was an error sending an email. Typically seen when attempting to
@@ -98,10 +79,39 @@ verify ownership of a given email address.
 `M_INVALID_ADDRESS`
 : The provided third-party address was not valid.
 
+`M_INVALID_EMAIL`
+: The email address provided was not valid.
+
+`M_INVALID_PARAM`
+: The request contained one or more invalid parameters.
+
+`M_MISSING_PARAMS`
+: The request was missing one or more parameters.
+
+`M_NO_VALID_SESSION`
+: A session could not be located for the given parameters.
+
+`M_NOT_FOUND`
+: The resource requested could not be located.
+
 `M_SEND_ERROR`
 : There was an error sending a notification. Typically seen when
 attempting to verify ownership of a given third-party address.
 
+`M_SESSION_EXPIRED`
+: The session has expired and must be renewed.
+
+`M_SESSION_NOT_VALIDATED`
+: The session has not been validated.
+
+`M_THREEPID_IN_USE`
+: The third-party identifier is already in use by another user. Typically
+this error will have an additional `mxid` property to indicate who owns
+the third-party identifier.
+
+`M_UNKNOWN`
+: An unknown error has occurred.
+
 `M_UNRECOGNIZED`
 : The request contained an unrecognised value, such as an unknown token or
 medium.
@@ -111,13 +121,7 @@ This is expected to be returned with a 404 HTTP status code if the endpoint is
 not implemented or a 405 HTTP status code if the endpoint is implemented, but
 the incorrect HTTP method is used.
 
-`M_THREEPID_IN_USE`
-: The third-party identifier is already in use by another user. Typically
-this error will have an additional `mxid` property to indicate who owns
-the third-party identifier.
-
-`M_UNKNOWN`
-: An unknown error has occurred.
+<!-- Please keep the error codes above in alphabetical order -->
 
 ## Privacy
 

content/server-server-api.md

@@ -473,6 +473,9 @@ server must ensure that the event:
     otherwise it is rejected.
 6.  Passes authorization rules based on the current state of the room,
     otherwise it is "soft failed".
+7. {{% added-in v="1.18" %}} Is [validated](#validating-policy-server-signatures)
+   by the Policy Server, if the room is [using a Policy Server](#determining-if-a-policy-server-is-enabled-in-a-room),
+   otherwise it is "soft failed".
 
 Further details of these checks, and how to handle failures, are
 described below.
@@ -689,6 +692,11 @@ then any new event `D'` will not reference `C`:
     |
     D'
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events can also be soft failed if they fail [Policy Server checks](#validating-policy-server-signatures).
+{{% /boxes/note %}}
+
 #### Retrieving event authorization information
 
 The homeserver may be missing event authorization information, or wish
@@ -1277,10 +1285,10 @@ endpoint MUST be protected as follows:
         room ID MUST be ignored if the sending server is denied access to
         the room identified by that ID.
 
-{{< added-in v="1.18" >}} The following endpoints MAY be protected:
+The following endpoints MAY be protected:
 
--   [`/_matrix/policy/v1/sign`](#post_matrixpolicyv1sign) - Protected if the server
-    is tracking the DAG and chooses to enforce the ACL.
+-   [`/_matrix/policy/v1/sign`](#post_matrixpolicyv1sign) - {{< added-in v="1.18" >}}
+    Protected if the server is tracking the DAG and chooses to enforce the ACL.
 
 
 ## Policy Servers
@@ -1396,7 +1404,7 @@ allow rooms to revoke the Policy Server's key without cooperation of the Policy
 Server.
 
 If the Policy Server is acting as a normal homeserver and attempting to send an
-event, that event will require the a signature from the server's published signing
+event, that event will require a signature from the server's published signing
 key alongside the Policy Server signature described in this section.
 {{% /boxes/warning %}}
 
@@ -1465,6 +1473,12 @@ The signature is then copied back to the original event object.
 For an example of a signed event, see the [room version
 specification](/rooms).
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events sent in rooms with [Policy Servers](#policy-servers) MUST [ask](#asking-for-a-policy-server-signature-on-an-event)
+the Policy Server for a signature too.
+{{% /boxes/note %}}
+
 ### Validating hashes and signatures on received events
 
 When a server receives an event over federation from another server, the
@@ -1499,6 +1513,12 @@ only been given a redacted version of the event. To enforce this, the
 receiving server should use the redacted copy it calculated rather than
 the full copy it received.
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events sent in rooms with [Policy Servers](#policy-servers) have [additional](#validating-policy-server-signatures)
+signature validation requirements.
+{{% /boxes/note %}}
+
 ### Calculating the reference hash for an event
 
 The *reference hash* of an event covers the essential fields of an

data/api/client-server/oauth_server_metadata.yaml

@@ -67,8 +67,7 @@ paths:
                     type: string
                     format: uri
                     description: |-
-                      URL of the token endpoint, necessary to use the authorization code grant and
-                      the refresh token grant.
+                      URL of the token endpoint, used by the grants.
                   revocation_endpoint:
                     type: string
                     format: uri
@@ -101,6 +100,10 @@ paths:
                       This array MUST contain at least the `authorization_code` and `refresh_token`
                       values, for clients to be able to use the authorization code grant and refresh
                       token grant, respectively.
+
+                      {{% added-in v="1.18" %}} It MAY also contain
+                      `urn:ietf:params:oauth:grant-type:device_code` to indicate support for the
+                      [device authorization grant](/client-server-api/#device-authorization-grant).
                     items:
                       type: string
                       description: A grant type that the server supports.
@@ -165,6 +168,14 @@ paths:
                         - "org.matrix.account_deactivate"
                         - "org.matrix.cross_signing_reset"
                       description: An action that the account management URL supports.
+                  device_authorization_endpoint:
+                    x-addedInMatrixVersion: "1.18"
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the device authorization endpoint, as defined in
+                      [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), necessary to use
+                      the [device authorization grant](/client-server-api/#device-authorization-grant).
                 required:
                   - issuer
                   - authorization_endpoint
@@ -180,9 +191,10 @@ paths:
                   "authorization_endpoint": "https://account.example.com/oauth2/auth",
                   "token_endpoint": "https://account.example.com/oauth2/token",
                   "registration_endpoint": "https://account.example.com/oauth2/clients/register",
+                  "device_authorization_endpoint": "https://account.example.com/oauth2/device",
                   "revocation_endpoint": "https://account.example.com/oauth2/revoke",
                   "response_types_supported": ["code"],
-                  "grant_types_supported": ["authorization_code", "refresh_token"],
+                  "grant_types_supported": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code"],
                   "response_modes_supported": ["query", "fragment"],
                   "code_challenge_methods_supported": ["S256"],
                   "account_management_uri": "https://account.example.com/manage",

data/api/client-server/policy_server.yaml

@@ -24,7 +24,7 @@ paths:
 
         {{% boxes/note %}}
         Like the [well-known discovery URI](/client-server-api/#well-known-uris),
-        this endpoint should be accessed with the hostname of the homeserver's
+        this endpoint should be accessed with the hostname of the Policy Server's
         [server name](/appendices/#server-name) by making a
         GET request to `https://hostname/.well-known/matrix/policy_server`.
         {{% /boxes/note %}}
@@ -48,6 +48,11 @@ paths:
                     description: |-
                       The unpadded base64-encoded public keys for the Policy Server. MUST contain
                       at least `ed25519`.
+                    properties:
+                      ed25519:
+                        type: string
+                        description: The unpadded base64-encoded ed25519 public key for the Policy Server.
+                    required: ['ed25519']
                     additionalProperties:
                       type: string
                       description: The unpadded base64-encoded public key for the key algorithm.

data/event-schemas/schema/m.room.policy.yaml

@@ -19,6 +19,11 @@ properties:
           The unpadded base64-encoded public keys for the Policy Server. MUST contain at
           least `ed25519`.
         type: object
+        properties:
+          ed25519:
+            type: string
+            description: The unpadded base64-encoded ed25519 public key for the Policy Server.
+        required: ['ed25519']
         additionalProperties:
           description: The unpadded base64-encoded public key for the key algorithm.
           type: string