Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/application_service/newsfragments/2130.feature

@@ -0,0 +1 @@
+Correct null value handling for the AS Registration's `url` property.

changelogs/client_server/newsfragments/2104.clarification

@@ -0,0 +1 @@
+Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/client_server/newsfragments/2109.clarification

@@ -0,0 +1 @@
+Spaces are subject to the same access mechanisms as rooms.

changelogs/client_server/newsfragments/2122.feature

@@ -0,0 +1 @@
+Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147).

changelogs/client_server/newsfragments/2141.feature

@@ -0,0 +1 @@
+Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/client_server/newsfragments/2144.clarification

@@ -0,0 +1 @@
+Fix typo: as->has.

changelogs/client_server/newsfragments/2151.feature

@@ -0,0 +1 @@
+Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

changelogs/internal/newsfragments/2137.clarification

@@ -0,0 +1 @@
+Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks.

changelogs/server_server/newsfragments/2104.clarification

@@ -0,0 +1 @@
+Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

config/_default/hugo.toml

@@ -23,15 +23,15 @@ description = "Home of the Matrix specification for decentralised communication"
 [menus]
 [[menus.main]]
     name = 'Foundation'
-    url = 'https://matrix.org/foundation/'
+    url = 'https://matrix.org/foundation/about/'
     weight = 10
 [[menus.main]]
-    name = 'FAQs'
-    url = 'https://matrix.org/faq'
+    name = 'User Docs'
+    url = 'https://matrix.org/docs/'
     weight = 20
 [[menus.main]]
     name = 'Blog'
-    url = 'https://matrix.org/blog/posts'
+    url = 'https://matrix.org/blog/'
     weight = 30
 
 [markup]

content/application-service-api.md

@@ -492,10 +492,10 @@ via the query string). It is expected that the application service use
 the transactions pushed to it to handle events rather than syncing with
 the user implied by `sender_localpart`.
 
-#### Application service room directories
+#### Published room directories
 
-Application services can maintain their own room directories for their
-defined third-party protocols. These room directories may be accessed by
+Application services can maintain their own published room directories for
+their defined third-party protocols. These directories may be accessed by
 clients through additional parameters on the `/publicRooms`
 client-server endpoint.
 

content/client-server-api/_index.md

@@ -439,7 +439,7 @@ endpoints it supports.
 Most API endpoints require the user to identify themselves by presenting
 previously obtained credentials in the form of an access token.
 An access token is typically obtained via the [Login](#login) or
-[Registration](#account-registration-and-management) processes. Access tokens
+[Registration](#account-registration) processes. Access tokens
 can expire; a new access token can be generated by using a refresh token.
 
 {{% boxes/note %}}
@@ -494,7 +494,7 @@ used to generate a new access token and refresh token, the new access
 and refresh tokens are now bound to the device associated with the
 initial refresh token.
 
-By default, the [Login](#login) and [Registration](#account-registration-and-management)
+By default, the [Login](#login) and [Registration](#account-registration)
 processes auto-generate a new `device_id`. A client is also free to
 generate its own `device_id` or, provided the user remains the same,
 reuse a device: in either case the client should pass the `device_id` in
@@ -560,9 +560,11 @@ specifying the device ID it is already using to the login API.
 with an `M_USER_LOCKED` error code, cannot obtain a new access token until
 the account has been [unlocked](#account-locking).
 
-### User-Interactive Authentication API
+### Legacy API
 
-#### Overview
+#### User-Interactive Authentication API
+
+##### Overview
 
 Some API endpoints require authentication that interacts with the user.
 The homeserver may provide many different ways of authenticating, such
@@ -586,7 +588,7 @@ the flows in order must result in an HTTP 401 response, as defined
 below. When all stages in a flow are complete, authentication is
 complete and the API call succeeds.
 
-#### User-interactive API in the REST API
+##### User-interactive API in the REST API
 
 In the REST API described in this specification, authentication works by
 the client and server exchanging JSON dictionaries. The server indicates
@@ -764,7 +766,7 @@ auth by offering a stage with only the `m.login.dummy` auth type, but they
 must still give a 401 response to requests with no auth data.
 {{% /boxes/note %}}
 
-#### Example
+**Example**
 
 At a high level, the requests made for an API call completing an auth
 flow with three stages will resemble the following diagram:
@@ -806,7 +808,7 @@ flow with three stages will resemble the following diagram:
     |_______________________|
 ```
 
-#### Authentication types
+##### Authentication types
 
 This specification defines the following auth types:
 -   `m.login.password`
@@ -817,7 +819,7 @@ This specification defines the following auth types:
 -   `m.login.dummy`
 -   `m.login.registration_token`
 
-##### Password-based
+###### Password-based
 
 
 | Type               | Description                                                                    |
@@ -876,7 +878,7 @@ explicitly as follows:
 In the case that the homeserver does not know about the supplied 3PID,
 the homeserver must respond with 403 Forbidden.
 
-##### Google ReCaptcha
+###### Google ReCaptcha
 
 | Type                | Description                                          |
 |---------------------|------------------------------------------------------|
@@ -893,7 +895,7 @@ follows:
 }
 ```
 
-##### Single Sign-On
+###### Single Sign-On
 
 | Type          | Description                                                                          |
 |---------------|--------------------------------------------------------------------------------------|
@@ -903,7 +905,7 @@ A client wanting to complete authentication using SSO should use the
 [Fallback](#fallback) mechanism. See [SSO during User-Interactive
 Authentication](#sso-during-user-interactive-authentication) for more information.
 
-##### Email-based (identity / homeserver)
+###### Email-based (identity / homeserver)
 
 | Type                     | Description                                                                                                      |
 |--------------------------|------------------------------------------------------------------------------------------------------------------|
@@ -932,7 +934,7 @@ follows:
 Note that `id_server` (and therefore `id_access_token`) is optional if
 the [`/requestToken`](#post_matrixclientv3registeremailrequesttoken) request did not include them.
 
-##### Phone number/MSISDN-based (identity / homeserver)
+###### Phone number/MSISDN-based (identity / homeserver)
 
 | Type             | Description                                                                                                    |
 |------------------|----------------------------------------------------------------------------------------------------------------|
@@ -961,7 +963,7 @@ follows:
 Note that `id_server` (and therefore `id_access_token`) is optional if
 the [`/requestToken`](#post_matrixclientv3registermsisdnrequesttoken) request did not include them.
 
-##### Dummy Auth
+###### Dummy Auth
 
 | Type             | Description                                                            |
 |------------------|------------------------------------------------------------------------|
@@ -987,7 +989,7 @@ just the type and session, if provided:
 }
 ```
 
-##### Token-authenticated registration
+###### Token-authenticated registration
 
 {{% added-in v="1.2" %}}
 
@@ -1031,7 +1033,7 @@ in the registration process that their token has expired.
 
 {{% http-api spec="client-server" api="registration_tokens" %}}
 
-##### Terms of service at registration
+###### Terms of service at registration
 
 {{% added-in v="1.11" %}}
 
@@ -1154,7 +1156,7 @@ user during registration, if applicable.
 
 {{% definition path="api/client-server/definitions/m.login.terms_params" %}}
 
-#### Fallback
+##### Fallback
 
 Clients cannot be expected to be able to know how to process every
 single login type. If a client does not know how to handle a given login
@@ -1195,7 +1197,7 @@ with just the session ID:
 }
 ```
 
-##### Example
+**Example**
 
 A client webapp might use the following JavaScript to open a popup
 window which will handle unknown login types:
@@ -1251,7 +1253,7 @@ function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onCo
 }
 ```
 
-#### Identifier types
+##### Identifier types
 
 Some authentication mechanisms use a user identifier object to identify
 a user. The user identifier object has a `type` field to indicate the
@@ -1264,7 +1266,7 @@ This specification defines the following identifier types:
 -   `m.id.thirdparty`
 -   `m.id.phone`
 
-##### Matrix User ID
+###### Matrix User ID
 
 | Type        | Description                                |
 |-------------|--------------------------------------------|
@@ -1281,7 +1283,7 @@ ID.
 }
 ```
 
-##### Third-party ID
+###### Third-party ID
 
 | Type              | Description                                                               |
 |-------------------|---------------------------------------------------------------------------|
@@ -1301,7 +1303,7 @@ ID media.
 }
 ```
 
-##### Phone number
+###### Phone number
 
 | Type         | Description                               |
 |--------------|-------------------------------------------|
@@ -1327,7 +1329,7 @@ The `country` is the two-letter uppercase ISO-3166-1 alpha-2 country
 code that the number in `phone` should be parsed as if it were dialled
 from.
 
-### Login
+#### Login
 
 A client can obtain access tokens using the [`/login`](#post_matrixclientv3login) API.
 
@@ -1399,7 +1401,7 @@ a token for their user ID if supported by the homeserver using
 
 {{% http-api spec="client-server" api="logout" %}}
 
-#### Appservice Login
+##### Appservice Login
 
 {{% added-in v="1.2" %}}
 
@@ -1436,7 +1438,7 @@ If the access token does correspond to an appservice, but the user id does
 not lie within its namespace then the homeserver will respond with an
 errcode of `M_EXCLUSIVE`.
 
-#### Login Fallback
+##### Login Fallback
 
 If a client does not recognize any or all login flows it can use the
 fallback login API:
@@ -1456,11 +1458,13 @@ forwarded to the login endpoint during the login process. For example:
 
     GET /_matrix/static/client/login/?device_id=GHTYAJCE
 
-### Account registration and management
+#### Account registration
 
 {{% http-api spec="client-server" api="registration" %}}
 
-#### Notes on password management
+#### Account management
+
+##### Password management
 
 {{% boxes/warning %}}
 Clients SHOULD enforce that the password provided is suitably complex.
@@ -1469,6 +1473,65 @@ number and a symbol and be at a minimum 8 characters in length. Servers
 MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 {{% /boxes/warning %}}
 
+{{% http-api spec="client-server" api="password_management" %}}
+
+##### Account deactivation
+
+{{% http-api spec="client-server" api="account_deactivation" %}}
+
+### OAuth 2.0 API
+
+#### Token revocation
+
+When a user wants to log out from a client, the client SHOULD use OAuth 2.0
+token revocation as defined in [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009).
+
+The client makes a `POST` request to the `revocation_endpoint` that can be found
+in the authorization server metadata.
+
+The body of the request includes the following parameters, encoded as
+`application/x-www-form-urlencoded`:
+
+- `token`: This parameter MUST contain either the access token or the refresh
+  token to be revoked.
+- `token_type_hint`: This parameter is OPTIONAL, and if present, MUST have a
+  value of either `access_token` or `refresh_token`. The server MAY use this
+  value to optimize the token lookup process.
+- `client_id`: The client identifier obtained during client registration. This
+  parameter is OPTIONAL.
+
+  If the `client_id` is not provided, or does not match the client associated
+  with the token, the server SHOULD still revoke the token. This behavior is
+  meant to help good actors like secret scanning tools to proactively revoke
+  leaked tokens. The server MAY also warn the user that one of their sessions
+  may be compromised in this scenario.
+
+For example, revoking using the access token:
+
+```
+POST /oauth2/revoke HTTP/1.1
+Host: auth.example.com
+Content-Type: application/x-www-form-urlencoded
+
+token=mat_ooreiPhei2wequu9fohkai3AeBaec9oo&
+token_type_hint=access_token&
+client_id=s6BhdRkqt3
+```
+
+The server MUST revoke both the access token and refresh token associated with
+the token provided in the request.
+
+The server SHOULD return one of the following responses:
+
+- If the token is already revoked or invalid, the server returns a `200 OK`
+  response
+- If the client is not authorized to revoke the token, the server returns a
+  `401 Unauthorized` response
+- For other errors, the server returns a `400 Bad Request` response with error
+  details
+
+### Account moderation
+
 #### Account locking
 
 {{% added-in v="1.12" %}}
@@ -2846,7 +2909,35 @@ re-invited.
 
 {{% http-api spec="client-server" api="banning" %}}
 
-### Listing rooms
+### Published room directory
+
+Homeservers MAY publish a room directory to allow users to discover rooms. A room
+can have one of two visibility settings in the directory:
+
+-   `public`: The room will be shown in the published room directory.
+-   `private`: The room will be hidden from the published room directory.
+
+Clients can define a room's initial visibility in the directory via the `visibility`
+parameter in [`/createRoom`](#post_matrixclientv3createroom). Irrespective of room
+creation, clients can query and change a room's visibility in the directory through
+the endpoints listed below, provided that the server permits this.
+
+{{% boxes/warning %}}
+The visibility setting merely defines whether a room is included in the published
+room directory or not. It doesn't make any guarantees about the room's
+[join rule](#mroomjoin_rules) or [history visibility](#room-history-visibility).
+
+In particular, a visibility setting of `public` should not be confused with a `public`
+join rule. Rooms with a join rule of `knock`, for instance, could reasonably be published
+in the directory, too.
+
+Similarly, a visibility setting of `public` does not necessarily imply a `world_readable`
+history visibility.
+
+To increase performance or by preference, servers MAY apply additional filters when listing the
+directory, for instance, by automatically excluding rooms with `invite` join rules
+that are not `world_readable` regardless of their visibility.
+{{% /boxes/warning %}}
 
 {{% http-api spec="client-server" api="list_public_rooms" %}}
 

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

@@ -528,7 +528,7 @@ messages, Alice only sends one request event (an event with type
 `m.room.message` with `msgtype: m.key.verification.request`, rather than an
 event with type `m.key.verification.request`), to the room. In addition, Alice
 does not send an `m.key.verification.cancel` event to tell Bob's other devices
-that the request as already been accepted; instead, when Bob's other devices
+that the request has already been accepted; instead, when Bob's other devices
 see his `m.key.verification.ready` event, they will know that the request has
 already been accepted, and that they should ignore the request.
 
@@ -1512,40 +1512,11 @@ message.
 
 The plaintext payload is of the form:
 
-```json
-{
-  "type": "<type of the plaintext event>",
-  "content": "<content for the plaintext event>",
-  "sender": "<sender_user_id>",
-  "recipient": "<recipient_user_id>",
-  "recipient_keys": {
-    "ed25519": "<our_ed25519_key>"
-  },
-  "keys": {
-    "ed25519": "<sender_ed25519_key>"
-  }
-}
-```
+{{% definition path="api/client-server/definitions/olm_payload" %}}
 
 The type and content of the plaintext message event are given in the
 payload.
 
-Other properties are included in order to prevent an attacker from
-publishing someone else's curve25519 keys as their own and subsequently
-claiming to have sent messages which they didn't. `sender` must
-correspond to the user who sent the event, `recipient` to the local
-user, and `recipient_keys` to the local ed25519 key.
-
-Clients must confirm that the `sender_key` property in the cleartext
-`m.room.encrypted` event body, and the `keys.ed25519` property in the
-decrypted plaintext, match the keys returned by
-[`/keys/query`](#post_matrixclientv3keysquery) for
-the given user. Clients must also verify the signature of the keys from the
-`/keys/query` response. Without this check, a client cannot be sure that
-the sender device owns the private part of the ed25519 key it claims to
-have in the Olm payload. This is crucial when the ed25519 key corresponds
-to a verified device.
-
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully
 decrypted a message. For these purposes, a session that has not received
@@ -1555,6 +1526,68 @@ maximum number of olm sessions that it will maintain for each device,
 and expiring sessions on a Least Recently Used basis. The maximum number
 of olm sessions maintained per device should be at least 4.
 
+###### Validation of incoming decrypted events
+
+{{% changed-in v="1.15" %}} Existing checks made more explicit, and checks for `sender_device_keys` added.
+
+After decrypting an incoming encrypted event, clients MUST apply the
+following checks:
+
+1.  The `sender` property in the decrypted content must match the
+    `sender` of the event.
+2.  The `keys.ed25519` property in the decrypted content must match
+    the `sender_key` property in the cleartext `m.room.encrypted`
+    event body.
+3.  The `recipient` property in the decrypted content must match
+    the user ID of the local user.
+4.  The `recipient_keys.ed25519` property in the decrypted content
+    must match the client device's [Ed25519 signing key](#device-keys).
+5.  Where `sender_device_keys` is present in the decrypted content:
+    1.  `sender_device_keys.user_id` must also match the `sender`
+        of the event.
+    2.  `sender_device_keys.keys.ed25519:<device_id>` must also match
+        the `sender_key` property in the cleartext `m.room.encrypted`
+        event body.
+    3.  `sender_device_keys.keys.curve25519:<device_id>` must match
+        the Curve25519 key used to establish the Olm session.
+    4.  The `sender_device_keys` structure must have a valid signature
+        from the key with ID `ed25519:<device_id>` (i.e., the sending
+        device's Ed25519 key).
+
+Any event that does not comply with these checks MUST be discarded.
+
+###### Verification of the sending user for incoming events
+
+{{% added-in v="1.15" %}}
+
+In addition, for each Olm session, clients MUST verify that the
+Curve25519 key used to establish the Olm session does indeed belong
+to the claimed `sender`. This requires a signed "device keys" structure
+for that Curve25519 key, which can be obtained in one of two ways:
+
+1.  An Olm message may be received with a `sender_device_keys` property
+    in the decrypted content.
+2.  The keys are returned via a [`/keys/query`](#post_matrixclientv3keysquery)
+    request. Note that both the Curve25519 key **and** the Ed25519 key in
+    the returned device keys structure must match those used in an
+    Olm-encrypted event as above. (In particular, the Ed25519 key must
+    be present in the **encrypted** content of an Olm-encrypted event
+    to prevent an attacker from claiming another user's Curve25519 key
+    as their own.)
+
+Ownership of the Curve25519 key is then established in one of two ways:
+
+1.  Via [cross-signing](#cross-signing). For this to be sufficient, the
+    device keys structure must be signed by the sender's self-signing key,
+    and that self-signing key must itself have been validated (either via
+    [explicit verification](#device-verification) or a "trust on first use" (TOFU) mechanism).
+2.  Via explicit verification of the device's Ed25519 signing key, as
+    contained in the device keys structure. This is no longer recommended.
+
+A failure to complete these verifications does not necessarily mean that
+the session is bogus; however it is the case that there is no proof that
+the claimed sender is accurate, and the user should be warned accordingly.
+
 ###### Recovering from undecryptable messages
 
 Occasionally messages may be undecryptable by clients due to a variety

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

@@ -2,8 +2,8 @@
 
 {{% added-in v="1.2" %}}
 
-Often used to group rooms of similar subject matter (such as a public "Official
-matrix.org rooms" space or personal "Work stuff" space), spaces are a way to
+Often used to group rooms of similar subject matter (such as an "Official
+matrix.org rooms" space or a "Work stuff" space), spaces are a way to
 organise rooms while being represented as rooms themselves.
 
 A space is defined by the [`m.space` room type](#types), making it known as a
@@ -18,11 +18,11 @@ In the default power level structure, this would be `100`. Clients might wish to
 go a step further and explicitly ignore notification counts on space-rooms.
 
 Membership of a space is defined and controlled by the existing mechanisms which
-govern a room: [`m.room.member`](#mroommember), [`m.room.history_visibility`](#mroomhistory_visibility),
-and [`m.room.join_rules`](#mroomjoin_rules). Public spaces are encouraged to have
-a similar setup to public rooms: `world_readable` history visibility, published
-canonical alias, and suitably public `join_rule`. Invites, including third-party
-invites, still work just as they do in normal rooms as well.
+govern a room: [`m.room.member`](/client-server-api#mroommember), [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility),
+and [`m.room.join_rules`](/client-server-api#mroomjoin_rules). Canonical aliases and invites, including
+third-party invites, still work just as they do in normal rooms as well. Furthermore,
+spaces can also be published in the [room directory](/client-server-api#published-room-directory) to make them
+discoverable.
 
 All other aspects of regular rooms are additionally carried over, such as the
 ability to set arbitrary state events, hold room account data, etc. Spaces are
@@ -87,10 +87,9 @@ the state of `#space:example.org` would consist of:
 }
 ```
 
-No state events in the child rooms themselves would be required (though they
-can also be present). This allows for users
-to define personal/private spaces to organise their own rooms without needing explicit
-permission from the room moderators/admins.
+No state events in the child rooms themselves would be required (though they can also
+be present). This allows for users to define spaces without needing explicit permission
+from the room moderators/admins.
 
 Child rooms can be removed from a space by omitting the `via` key of `content` on the
 relevant state event, such as through redaction or otherwise clearing the `content`.

content/server-server-api.md

@@ -1048,11 +1048,10 @@ user's Matrix ID and the token delivered when the invite was stored,
 this verification will prove that the `m.room.member` invite event comes
 from the user owning the invited third-party identifier.
 
-## Public Room Directory
+## Published Room Directory
 
-To complement the [Client-Server
-API](/client-server-api)'s room directory,
-homeservers need a way to query the public rooms for another server.
+To complement the [room directory in the Client-Server API](/client-server-api#published-room-directory), 
+homeservers need a way to query the published rooms of another server.
 This can be done by making a request to the `/publicRooms` endpoint for
 the server the room directory should be retrieved for.
 

data/api/application-service/definitions/registration.yaml

@@ -19,7 +19,7 @@ properties:
     type: string
     description: A unique, user-defined ID of the application service which will never change.
   url:
-    type: string
+    type: ["null", "string"]
     description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
   as_token:
     type: string

data/api/client-server/account_deactivation.yaml

@@ -0,0 +1,141 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2022 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Account Deactivation API
+  version: 1.0.0
+paths:
+  /account/deactivate:
+    post:
+      summary: Deactivate a user's account.
+      description: |-
+        Deactivate the user's account, removing all ability for the user to
+        login again.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided.
+
+        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.
+      security:
+        - {}
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      operationId: deactivateAccount
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+                id_server:
+                  type: string
+                  description: |-
+                    The identity server to unbind all of the user's 3PIDs from.
+                    If not provided, the homeserver MUST use the `id_server`
+                    that was originally use to bind each identifier. If the
+                    homeserver does not know which `id_server` that was,
+                    it must return an `id_server_unbind_result` of
+                    `no-support`.
+                  example: example.org
+                erase:
+                  x-addedInMatrixVersion: "1.10"
+                  type: boolean
+                  description: |-
+                    Whether the user would like their content to be erased as
+                    much as possible from the server.
+
+                    Erasure means that any users (or servers) which join the
+                    room after the erasure request are served redacted copies of
+                    the events sent by this account. Users which had visibility
+                    on those events prior to the erasure are still able to see
+                    unredacted copies. No redactions are sent and the erasure
+                    request is not shared over federation, so other servers
+                    might still serve unredacted copies.
+
+                    The server should additionally erase any non-event data
+                    associated with the user, such as [account data](/client-server-api/#client-config)
+                    and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
+
+                    Defaults to `false` if not present.
+        required: true
+      responses:
+        "200":
+          description: The account has been deactivated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id_server_unbind_result:
+                    type: string
+                    enum:
+                      - success
+                      - no-support
+                    description: |-
+                      An indicator as to whether or not the homeserver was able to unbind
+                      the user's 3PIDs from the identity server(s). `success` indicates
+                      that all identifiers have been unbound from the identity server while
+                      `no-support` indicates that one or more identifiers failed to unbind
+                      due to the identity server refusing the request or the homeserver
+                      being unable to determine an identity server to unbind from. This
+                      must be `success` if the homeserver has no identifiers to unbind
+                      for the user.
+                    example: success
+                required:
+                  - id_server_unbind_result
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/appservice_room_directory.yaml

@@ -13,18 +13,21 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Application Service Room Directory API
+  title: Matrix Client-Server Application Service Published Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/appservice/{networkId}/{roomId}":
     put:
-      summary: Updates a room's visibility in the application service's room directory.
-      description: |-
-        Updates the visibility of a given room on the application service's room
+      summary: |-
+        Updates a room's visibility in the application service's published room
         directory.
+      description: |-
+        Updates the visibility of a given room in the application service's
+        published room directory.
 
-        This API is similar to the room directory visibility API used by clients
-        to update the homeserver's more general room directory.
+        This API is similar to the
+        [visibility API](/client-server-api#put_matrixclientv3directorylistroomroomid)
+        used by clients to update the homeserver's more general published room directory.
 
         This API requires the use of an application service access token (`as_token`)
         instead of a typical client's access_token. This API cannot be invoked by

data/api/client-server/create_room.yaml

@@ -87,12 +87,9 @@ paths:
                     - public
                     - private
                   description: |-
-                    A `public` visibility indicates that the room will be shown
-                    in the published room list. A `private` visibility will hide
-                    the room from the published room list. Rooms default to
-                    `private` visibility if this key is not included. NB: This
-                    should not be confused with `join_rules` which also uses the
-                    word `public`.
+                    The room's visibility in the server's
+                    [published room directory](/client-server-api#published-room-directory).
+                    Defaults to `private`.
                 room_alias_name:
                   type: string
                   description: |-

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

@@ -0,0 +1,88 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+type: object
+title: OlmPayload
+description: |-
+  The plaintext payload of Olm message events.
+properties:
+  type:
+    type: string
+    description: The type of the event.
+  content:
+    type: object
+    description: The event content.
+  sender:
+    type: string
+    description: The user ID of the event sender.
+  recipient:
+    type: string
+    description: The user ID of the intended event recipient.
+  recipient_keys:
+    description: The recipient's signing keys of the encrypted event.
+    $ref: "#/components/schemas/SigningKeys"
+  keys:
+    $ref: "#/components/schemas/SigningKeys"
+    description: The sender's signing keys of the encrypted event.
+  sender_device_keys:
+    $ref: device_keys.yaml 
+    description: The sender's device keys.
+    x-addedInMatrixVersion: "1.15"
+required:
+  - type
+  - content
+  - sender
+  - recipient
+  - recipient_keys
+  - keys
+components:
+  schemas:
+    SigningKeys:
+      type: object
+      title: SigningKeys
+      description: Public keys used for an `m.olm.v1.curve25519-aes-sha2` event.
+      properties:
+        ed25519:
+          type: string
+          description: The Ed25519 public key encoded using unpadded base64.
+      required:
+        - ed25519
+example: {
+  "type": "<type of the plaintext event>",
+  "content": "<content for the plaintext event>",
+  "sender": "<sender_user_id>",
+  "recipient": "<recipient_user_id>",
+  "recipient_keys": {
+    "ed25519": "<our_ed25519_key>"
+  },
+  "keys": {
+    "ed25519": "<sender_ed25519_key>"
+  },
+  "sender_device_keys": {
+    "algorithms": ["<supported>", "<algorithms>"],
+    "user_id": "<user_id>",
+    "device_id": "<device_id>",
+    "keys": {
+      "ed25519:<device_id>": "<sender_ed25519_key>",
+      "curve25519:<device_id>": "<sender_curve25519_key>"
+    },
+    "signatures": {
+      "<user_id>": {
+        "ed25519:<device_id>": "<device_signature>",
+        "ed25519:<ssk_id>": "<ssk_signature>",
+      }
+    }
+  }
+}

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

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 type: object
-title: "PublicRoomsChunk"
+title: "PublishedRoomsChunk"
 properties:
   canonical_alias:
     type: string

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

@@ -13,28 +13,15 @@
 # limitations under the License.
 
 type: object
-description: A list of the rooms on the server.
+description: A list of the published rooms on the server.
 required: ["chunk"]
 properties:
   chunk:
     type: array
     description: |-
-      A paginated chunk of public rooms.
+      A paginated chunk of published rooms.
     items:
-      allOf:
-        - $ref: "public_rooms_chunk.yaml"
-        - type: object
-          title: PublicRoomsChunk
-          properties:
-            # Override description of join_rule
-            join_rule:
-              type: string
-              description: |-
-                The room's join rule. When not present, the room is assumed to
-                be `public`. Note that rooms with `invite` join rules are not
-                expected here, but rooms with `knock` rules are given their
-                near-public nature.
-              example: "public"
+      $ref: "public_rooms_chunk.yaml"
   next_batch:
     type: string
     description: |-
@@ -50,7 +37,7 @@ properties:
   total_room_count_estimate:
     type: integer
     description: |-
-        An estimate on the total number of public rooms, if the
+        An estimate on the total number of published rooms, if the
         server has an estimate.
 example: {
   "chunk": [

data/api/client-server/list_public_rooms.yaml

@@ -13,14 +13,15 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Room Directory API
+  title: Matrix Client-Server Published Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/room/{roomId}":
     get:
       summary: Gets the visibility of a room in the directory
-      description: Gets the visibility of a given room on the server's public room
-        directory.
+      description: |-
+        Gets the visibility of a given room in the server's
+        published room directory.
       operationId: getRoomVisibilityOnDirectory
       parameters:
         - in: path
@@ -32,7 +33,7 @@ paths:
             type: string
       responses:
         "200":
-          description: The visibility of the room in the directory
+          description: The visibility of the room in the directory.
           content:
             application/json:
               schema:
@@ -50,7 +51,7 @@ paths:
                     "visibility": "public"
                   }
         "404":
-          description: The room is not known to the server
+          description: The room is not known to the server.
           content:
             application/json:
               schema:
@@ -64,14 +65,13 @@ paths:
       tags:
         - Room discovery
     put:
-      summary: Sets the visibility of a room in the room directory
+      summary: Sets the visibility of a room in the directory
       description: |-
-        Sets the visibility of a given room in the server's public room
-        directory.
+        Sets the visibility of a given room in the server's published room directory.
 
-        Servers may choose to implement additional access control checks
-        here, for instance that room visibility can only be changed by
-        the room creator or a server administrator.
+        Servers MAY implement additional access control checks, for instance,
+        to ensure that a room's visibility can only be changed by the room creator
+        or a server administrator.
       operationId: setRoomVisibilityOnDirectory
       security:
         - accessTokenQuery: []
@@ -97,11 +97,11 @@ paths:
                     - public
                   description: |-
                     The new visibility setting for the room.
-                    Defaults to 'public'.
+                    Defaults to `public`.
               example: {
                 "visibility": "public"
               }
-        description: The new visibility for the room on the room directory.
+        description: The new visibility for the room in the published room directory.
         required: true
       responses:
         "200":
@@ -114,7 +114,7 @@ paths:
                 response:
                   value: {}
         "404":
-          description: The room is not known to the server
+          description: The room is not known to the server.
           content:
             application/json:
               schema:
@@ -129,9 +129,9 @@ paths:
         - Room discovery
   /publicRooms:
     get:
-      summary: Lists the public rooms on the server.
+      summary: Lists a server's published room directory
       description: |-
-        Lists the public rooms on the server.
+        Lists a server's published room directory.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
@@ -154,13 +154,13 @@ paths:
         - in: query
           name: server
           description: |-
-            The server to fetch the public room lists from. Defaults to the
-            local server. Case sensitive.
+            The server to fetch the published room directory from. Defaults
+            to the local server. Case sensitive.
           schema:
             type: string
       responses:
         "200":
-          description: A list of the rooms on the server.
+          description: A list of the published rooms on the server.
           content:
             application/json:
               schema:
@@ -168,9 +168,9 @@ paths:
       tags:
         - Room discovery
     post:
-      summary: Lists the public rooms on the server with optional filter.
+      summary: Lists a server's published room directory with an optional filter
       description: |-
-        Lists the public rooms on the server, with optional filter.
+        Lists a server's published room directory with an optional filter.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
@@ -182,8 +182,8 @@ paths:
         - in: query
           name: server
           description: |-
-            The server to fetch the public room lists from. Defaults to the
-            local server. Case sensitive.
+            The server to fetch the published room directory from. Defaults
+            to the local server. Case sensitive.
           schema:
             type: string
       requestBody:
@@ -253,7 +253,7 @@ paths:
         required: true
       responses:
         "200":
-          description: A list of the rooms on the server.
+          description: A filtered list of the published rooms on the server.
           content:
             application/json:
               schema:

data/api/client-server/password_management.yaml

@@ -0,0 +1,242 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2022 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Password Management API
+  version: 1.0.0
+paths:
+  /account/password:
+    post:
+      summary: Changes a user's password.
+      description: |-
+        Changes the password for an account on this homeserver.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
+        ensure the user changing the password is actually the owner of the
+        account.
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        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.
+      security:
+        - {}
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      operationId: changePassword
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                new_password:
+                  type: string
+                  description: The new password for the account.
+                  example: ihatebananas
+                logout_devices:
+                  type: boolean
+                  description: |-
+                    Whether the user's other access tokens, and their associated devices, should be
+                    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.
+                  example: true
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+              required:
+                - new_password
+        required: true
+      responses:
+        "200":
+          description: The password has been changed.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+  /account/password/email/requestToken:
+    post:
+      summary: Requests a validation token be sent to the given email address for the
+        purpose of resetting a user's password
+      description: |-
+        The homeserver must check that the given email address **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        `/account/password` endpoint.
+
+        This API's parameters and response are identical to that of the
+        [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
+        endpoint, except that
+        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
+        given email address could be found. The server may instead send an
+        email to the given address prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        The homeserver should validate the email itself, either by sending a
+        validation email itself or by using a service it has control over.
+      operationId: requestTokenToResetPasswordEmail
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_email_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: An email was sent to the given address.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            The referenced third-party identifier is not recognised by the
+            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_NOT_FOUND",
+                    "error": "Email not found"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
+      tags:
+        - Account management
+  /account/password/msisdn/requestToken:
+    post:
+      summary: Requests a validation token be sent to the given phone number for the
+        purpose of resetting a user's password.
+      description: |-
+        The homeserver must check that the given phone number **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        `/account/password` endpoint.
+
+        This API's parameters and response are identical to that of the
+        [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
+        endpoint, except that
+        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
+        given phone number could be found. The server may instead send the SMS
+        to the given phone number prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        The homeserver should validate the phone number itself, either by sending a
+        validation message itself or by using a service it has control over.
+      operationId: requestTokenToResetPasswordMSISDN
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_msisdn_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: An SMS message was sent to the given phone number.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            The referenced third-party identifier is not recognised by the
+            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_NOT_FOUND",
+                    "error": "Phone number not found"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
+      tags:
+        - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/registration.yaml

@@ -373,315 +373,6 @@ paths:
                   }
       tags:
         - Account management
-  /account/password:
-    post:
-      summary: Changes a user's password.
-      description: |-
-        Changes the password for an account on this homeserver.
-
-        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
-        ensure the user changing the password is actually the owner of the
-        account.
-
-        An access token should be submitted to this endpoint if the client has
-        an active session.
-
-        The homeserver may change the flows available depending on whether a
-        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.
-      security:
-        - {}
-        - accessTokenQuery: []
-        - accessTokenBearer: []
-      operationId: changePassword
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                new_password:
-                  type: string
-                  description: The new password for the account.
-                  example: ihatebananas
-                logout_devices:
-                  type: boolean
-                  description: |-
-                    Whether the user's other access tokens, and their associated devices, should be
-                    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.
-                  example: true
-                auth:
-                  description: Additional authentication information for the user-interactive
-                    authentication API.
-                  allOf:
-                    - $ref: definitions/auth_data.yaml
-              required:
-                - new_password
-        required: true
-      responses:
-        "200":
-          description: The password has been changed.
-          content:
-            application/json:
-              schema:
-                type: object
-              examples:
-                response:
-                  value: {}
-        "401":
-          description: The homeserver requires additional authentication information.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/auth_response.yaml
-        "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
-      tags:
-        - Account management
-  /account/password/email/requestToken:
-    post:
-      summary: Requests a validation token be sent to the given email address for the
-        purpose of resetting a user's password
-      description: |-
-        The homeserver must check that the given email address **is
-        associated** with an account on this homeserver. This API should be
-        used to request validation tokens when authenticating for the
-        `/account/password` endpoint.
-
-        This API's parameters and response are identical to that of the
-        [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
-        endpoint, except that
-        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
-        given email address could be found. The server may instead send an
-        email to the given address prompting the user to create an account.
-        `M_THREEPID_IN_USE` may not be returned.
-
-        The homeserver should validate the email itself, either by sending a
-        validation email itself or by using a service it has control over.
-      operationId: requestTokenToResetPasswordEmail
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: definitions/request_email_validation.yaml
-        required: true
-      responses:
-        "200":
-          description: An email was sent to the given address.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/request_token_response.yaml
-        "400":
-          description: |-
-            The referenced third-party identifier is not recognised by the
-            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
-            can be returned if the server does not trust/support the identity server
-            provided in the request.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_NOT_FOUND",
-                    "error": "Email not found"
-                  }
-        "403":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_DENIED",
-                    "error": "Third-party identifier is not allowed"
-                  }
-      tags:
-        - Account management
-  /account/password/msisdn/requestToken:
-    post:
-      summary: Requests a validation token be sent to the given phone number for the
-        purpose of resetting a user's password.
-      description: |-
-        The homeserver must check that the given phone number **is
-        associated** with an account on this homeserver. This API should be
-        used to request validation tokens when authenticating for the
-        `/account/password` endpoint.
-
-        This API's parameters and response are identical to that of the
-        [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
-        endpoint, except that
-        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
-        given phone number could be found. The server may instead send the SMS
-        to the given phone number prompting the user to create an account.
-        `M_THREEPID_IN_USE` may not be returned.
-
-        The homeserver should validate the phone number itself, either by sending a
-        validation message itself or by using a service it has control over.
-      operationId: requestTokenToResetPasswordMSISDN
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: definitions/request_msisdn_validation.yaml
-        required: true
-      responses:
-        "200":
-          description: An SMS message was sent to the given phone number.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/request_token_response.yaml
-        "400":
-          description: |-
-            The referenced third-party identifier is not recognised by the
-            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
-            can be returned if the server does not trust/support the identity server
-            provided in the request.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_NOT_FOUND",
-                    "error": "Phone number not found"
-                  }
-        "403":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_DENIED",
-                    "error": "Third-party identifier is not allowed"
-                  }
-      tags:
-        - Account management
-  /account/deactivate:
-    post:
-      summary: Deactivate a user's account.
-      description: |-
-        Deactivate the user's account, removing all ability for the user to
-        login again.
-
-        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
-
-        An access token should be submitted to this endpoint if the client has
-        an active session.
-
-        The homeserver may change the flows available depending on whether a
-        valid access token is provided.
-
-        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.
-      security:
-        - {}
-        - accessTokenQuery: []
-        - accessTokenBearer: []
-      operationId: deactivateAccount
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                auth:
-                  description: Additional authentication information for the user-interactive
-                    authentication API.
-                  allOf:
-                    - $ref: definitions/auth_data.yaml
-                id_server:
-                  type: string
-                  description: |-
-                    The identity server to unbind all of the user's 3PIDs from.
-                    If not provided, the homeserver MUST use the `id_server`
-                    that was originally use to bind each identifier. If the
-                    homeserver does not know which `id_server` that was,
-                    it must return an `id_server_unbind_result` of
-                    `no-support`.
-                  example: example.org
-                erase:
-                  x-addedInMatrixVersion: "1.10"
-                  type: boolean
-                  description: |-
-                    Whether the user would like their content to be erased as
-                    much as possible from the server.
-
-                    Erasure means that any users (or servers) which join the
-                    room after the erasure request are served redacted copies of
-                    the events sent by this account. Users which had visibility
-                    on those events prior to the erasure are still able to see
-                    unredacted copies. No redactions are sent and the erasure
-                    request is not shared over federation, so other servers
-                    might still serve unredacted copies.
-
-                    The server should additionally erase any non-event data
-                    associated with the user, such as [account data](/client-server-api/#client-config)
-                    and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
-
-                    Defaults to `false` if not present.
-        required: true
-      responses:
-        "200":
-          description: The account has been deactivated.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  id_server_unbind_result:
-                    type: string
-                    enum:
-                      - success
-                      - no-support
-                    description: |-
-                      An indicator as to whether or not the homeserver was able to unbind
-                      the user's 3PIDs from the identity server(s). `success` indicates
-                      that all identifiers have been unbound from the identity server while
-                      `no-support` indicates that one or more identifiers failed to unbind
-                      due to the identity server refusing the request or the homeserver
-                      being unable to determine an identity server to unbind from. This
-                      must be `success` if the homeserver has no identifiers to unbind
-                      for the user.
-                    example: success
-                required:
-                  - id_server_unbind_result
-        "401":
-          description: The homeserver requires additional authentication information.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/auth_response.yaml
-        "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
-      tags:
-        - Account management
   /register/available:
     get:
       summary: Checks to see if a username is available on the server.

data/api/server-server/public_rooms.yaml

@@ -13,16 +13,20 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Federation Public Rooms API
+  title: Matrix Federation Published Room Directory API
   version: 1.0.0
 paths:
   /publicRooms:
     get:
-      summary: Get all the public rooms for a homeserver
+      summary: Lists the server's published room directory
       description: |-
-        Gets all the public rooms for the homeserver. This should not return
-        rooms that are listed on another homeserver's directory, just those
-        listed on the receiving homeserver's directory.
+        Lists the server's published room directory.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+
+        This SHOULD not return rooms that are listed on another homeserver's directory,
+        just those listed on the receiving homeserver's directory.
       operationId: getPublicRooms
       security:
         - signedRequest: []
@@ -62,21 +66,18 @@ paths:
             type: string
       responses:
         "200":
-          description: The public room list for the homeserver.
+          description: A list of the published rooms on the server.
           content:
             application/json:
               schema:
                 $ref: ../client-server/definitions/public_rooms_response.yaml
     post:
-      summary: Gets the public rooms on the server with optional filter.
+      summary: Lists the server's published room directory with an optional filter
       description: |-
-        Lists the public rooms on the server, with optional filter.
+        Lists the server's published room directory with an optional filter.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
-
-        Note that this endpoint receives and returns the same format that is seen
-        in the Client-Server API's `POST /publicRooms` endpoint.
       operationId: queryPublicRooms
       security:
         - signedRequest: []
@@ -147,69 +148,11 @@ paths:
         required: true
       responses:
         "200":
-          description: A list of the rooms on the server.
+          description: A filtered list of the published rooms on the server.
           content:
             application/json:
               schema:
-                type: object
-                description: A list of the rooms on the server.
-                required:
-                  - chunk
-                properties:
-                  chunk:
-                    title: PublicRoomsChunks
-                    type: array
-                    description: A paginated chunk of public rooms.
-                    items:
-                      allOf:
-                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
-                        - type: object
-                          properties:
-                            # Override description of join_rule
-                            join_rule:
-                              type: string
-                              description: |-
-                                The room's join rule. When not present, the room is assumed to
-                                be `public`. Note that rooms with `invite` join rules are not
-                                expected here, but rooms with `knock` rules are given their
-                                near-public nature.
-                  next_batch:
-                    type: string
-                    description: |-
-                      A pagination token for the response. The absence of this token
-                      means there are no more results to fetch and the client should
-                      stop paginating.
-                  prev_batch:
-                    type: string
-                    description: |-
-                      A pagination token that allows fetching previous results. The
-                      absence of this token means there are no results before this
-                      batch, i.e. this is the first batch.
-                  total_room_count_estimate:
-                    type: integer
-                    description: |-
-                      An estimate on the total number of public rooms, if the
-                      server has an estimate.
-              examples:
-                response:
-                  value: {
-                    "chunk": [
-                      {
-                        "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
-                        "guest_can_join": false,
-                        "name": "CHEESE",
-                        "num_joined_members": 37,
-                        "room_id": "!ol19s:bleecker.street",
-                        "topic": "Tasty tasty cheese",
-                        "world_readable": true,
-                        "join_rule": "public",
-                        "room_type": "m.space"
-                      }
-                    ],
-                    "next_batch": "p190q",
-                    "prev_batch": "p1902",
-                    "total_room_count_estimate": 115
-                  }
+                $ref: ../client-server/definitions/public_rooms_response.yaml
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables: