Merge 6f39b946fd into 2baca03e6b

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

changelogs/client_server/newsfragments/2318.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification. Contributed by @HarHarLinks.

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/internal/newsfragments/2318.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification. Contributed by @HarHarLinks.

config/_default/hugo.toml

@@ -65,7 +65,7 @@ description = "Home of the Matrix specification for decentralised communication"
 # Everything below this are Site Params
 
 [params]
-copyright = "The Matrix.org Foundation CIC"
+copyright = "The Matrix.org Foundation C.I.C."
 
 [params.version]
 # must be one of "unstable", "current", "historical"

content/client-server-api/_index.md

@@ -523,7 +523,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
@@ -1720,19 +1720,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
+Logging in and obtaining an access token with the OAuth 2.0 API should be done
-grant](#authorization-code-grant). In the context of the Matrix specification,
+using either the [authorization code grant](#authorization-code-grant) or
-this means requesting a [scope](#scope) including full client-server API
+[device authorization grant](#device-authorization-grant). In the context of the
-read/write access and allocating a device ID.
+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),
+##### Authorization code flow
-it needs to generate the following values:
+
+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.
@@ -1873,6 +1885,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
@@ -2203,6 +2352,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
@@ -2227,18 +2377,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
+{{% added-in v="1.18" %}}
-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).
 
-Whether the homeserver supports this parameter is advertised by the
+As per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), the device
-`prompt_values_supported` authorization server metadata.
+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
+This grant requires the client to know the following [authorization server
-the browser.
+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
 
@@ -2345,6 +2511,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" %}}
@@ -3320,7 +3502,7 @@ PUT /rooms/!roomid:domain/state/m.room.bgd.color
 ### Redactions
 
 Since events are extensible it is possible for malicious users and/or
-servers to add keys that are, for example offensive or illegal. Since
+servers to add keys that are, for example, offensive or illegal. Since
 some events cannot be simply deleted, e.g. membership events, we instead
 'redact' events. This involves removing all keys from an event that are
 not required by the protocol. This stripped down event is thereafter
@@ -3418,7 +3600,7 @@ This specification describes the following relationship types:
 * [Event replacements](#event-replacements).
 * [Event annotations](#event-annotations-and-reactions).
 * [Threads](#threading).
-* [References](#reference-relations)
+* [References](#reference-relations).
 
 #### Aggregations of child events
 

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

@@ -107,7 +107,7 @@ flag to `true`.
 ```
 
 {{% boxes/note %}}
-Clients which are acutely aware of threads (they do not render threads, but are otherwise
+Clients which are aware of threads (they do not render threads, but are otherwise
 aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
 of `m.thread` as a threaded reply, for conversation continuity on the threaded client's side.
 

data/api/client-server/definitions/event_filter.yaml

@@ -23,14 +23,14 @@ properties:
   not_senders:
     description: A list of sender IDs to exclude. If this list is absent then no senders
       are excluded. A matching sender will be excluded even if it is listed in the
-      `'senders'` filter.
+      `senders` filter.
     items:
       type: string
     type: array
   not_types:
     description: A list of event types to exclude. If this list is absent then no
       event types are excluded. A matching type will be excluded even if it is listed
-      in the `'types'` filter. A '*' can be used as a wildcard to match any sequence
+      in the `types` filter. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string
@@ -43,7 +43,7 @@ properties:
     type: array
   types:
     description: A list of event types to include. If this list is absent then all
-      event types are included. A `'*'` can be used as a wildcard to match any sequence
+      event types are included. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string

data/api/client-server/definitions/room_event_filter.yaml

@@ -39,7 +39,7 @@ allOf:
         for more information. Defaults to `false`.
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms
-        are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+        are excluded. A matching room will be excluded even if it is listed in the `rooms`
         filter.
       items:
         type: string

data/api/client-server/definitions/sync_filter.yaml

@@ -17,15 +17,15 @@ properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
       fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths)
-      to include. So ['content.body'] will include the 'body' field of the 'content' object.
+      to include. So `['content.body']` will include the `body` field of the `content` object.
       A server may include more fields than were requested.
     items:
       type: string
     type: array
   event_format:
-    description: The format to use for events. 'client' will return the events in
+    description: The format to use for events. `client` will return the events in
-      a format suitable for clients. 'federation' will return the raw event as received
+      a format suitable for clients. `federation` will return the raw event as received
-      over federation. The default is 'client'.
+      over federation. The default is `client`.
     enum:
     - client
     - federation
@@ -45,7 +45,7 @@ properties:
     properties:
       not_rooms:
         description: A list of room IDs to exclude. If this list is absent then no rooms
-          are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+          are excluded. A matching room will be excluded even if it is listed in the `rooms`
           filter. This filter is applied before the filters in `ephemeral`,
           `state`, `timeline` or `account_data`
         items:
@@ -65,7 +65,7 @@ properties:
           events that appear in the `ephemeral` property in the `/sync`
           response.
       include_leave:
-        description: Include rooms that the user has left in the sync, default false
+        description: Include rooms that the user has left in the sync. Defaults to `false`.
         type: boolean
       state:
         type: object

data/api/client-server/list_public_rooms.yaml

@@ -226,7 +226,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string
@@ -277,4 +277,4 @@ components:
     accessTokenQuery:
       $ref: definitions/security.yaml#/accessTokenQuery
     accessTokenBearer:
-      $ref: definitions/security.yaml#/accessTokenBearer
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/login.yaml

@@ -163,7 +163,7 @@ paths:
                     known client device, a new device will be created. The given
                     device ID must not be the same as a
                     [cross-signing](/client-server-api/#cross-signing) key ID.
-                    The server will auto-generate a device_id
+                    The server will auto-generate a `device_id`
                     if this is not specified.
                 initial_device_display_name:
                   type: string

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
+                      URL of the token endpoint, used by the grants.
-                      the refresh token grant.
                   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/password_management.yaml

@@ -57,7 +57,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether the user's other access tokens, and their associated devices, should be
-                    revoked if the request succeeds. Defaults to true.
+                    revoked if the request succeeds. Defaults to `true`.
 
                     When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
                     for the user's remaining devices.

data/api/client-server/registration.yaml

@@ -126,7 +126,7 @@ paths:
                   description: |-
                     ID of the client device. If this does not correspond to a
                     known client device, a new device will be created. The server
-                    will auto-generate a device_id if this is not specified.
+                    will auto-generate a `device_id` if this is not specified.
                   example: GHTYAJCE
                 initial_device_display_name:
                   type: string
@@ -139,11 +139,11 @@ paths:
                   description: |-
                     If true, an `access_token` and `device_id` should not be
                     returned from this call, therefore preventing an automatic
-                    login. Defaults to false.
+                    login. Defaults to `false`.
                   example: false
                 refresh_token:
                   type: boolean
-                  description: If true, the client supports refresh tokens.
+                  description: If `true`, the client supports refresh tokens.
                   x-addedInMatrixVersion: "1.3"
         required: true
       responses:

data/api/client-server/room_send.yaml

@@ -31,7 +31,7 @@ paths:
 
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
-        [Room Events](/client-server-api/#room-events) for the m. event specification.
+        [Room Events](/client-server-api/#room-events) for the `m.` event specification.
 
         Homeservers MUST allow clients to send `m.room.redaction` events with this
         endpoint for all room versions. In rooms with a version older than 11 they

data/api/server-server/public_rooms.yaml

@@ -49,7 +49,7 @@ paths:
           name: include_all_networks
           description: |-
             Whether or not to include all networks/protocols defined by application
-            services on the homeserver. Defaults to false.
+            services on the homeserver. Defaults to `false`.
           example: false
           schema:
             type: boolean
@@ -121,7 +121,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string

data/event-schemas/schema/core-event-schema/event.yaml

@@ -7,8 +7,7 @@ properties:
       When interacting with the REST API, this is the HTTP body.
     type: object
   type:
-    description: The type of event. This SHOULD be namespaced similar to Java package
+    description: The type of event, as defined by [the event type specification](/client-server-api/#types-of-room-events).
-      naming conventions e.g. 'com.example.subdomain.event.type'
     type: string
 required:
   - type

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

@@ -54,7 +54,7 @@ properties:
         type: boolean
         description: |-
           True to allow server names that are IP address literals. False to
-          deny. Defaults to true if missing or otherwise not a boolean.
+          deny. Defaults to `true` if missing or otherwise not a boolean.
 
           This is strongly recommended to be set to `false` as servers running
           with IP literal names are strongly discouraged in order to require

layouts/_partials/events/render-event.html

@@ -49,7 +49,7 @@
   </tr>
 {{ if $state_key }}
   <tr>
-   <th>State key</th>
+   <th>State key:</th>
    <td>{{ $state_key.description | markdownify }}</td>
  </tr>
 {{ end }}