Merge branch 'main' into patch-10

.github/CODEOWNERS

@@ -1 +1 @@
-*       @matrix-org/spec-core-team
+*       @matrix-org/spec-core-team @zecakeh

changelogs/appendices/newsfragments/2395.clarification

@@ -0,0 +1 @@
+Clarify matrix.to RFC 3986 percent encoding requirements. Contributed by @HarHarLinks.

changelogs/appendices/newsfragments/2398.clarification

@@ -0,0 +1 @@
+Add specification of URL-safe unpadded Base64.

changelogs/client_server/newsfragments/2398.clarification

@@ -0,0 +1 @@
+Clarify definitions of `EncryptedFile` structure.

changelogs/client_server/newsfragments/2403.feature

@@ -0,0 +1 @@
+Specify `unsigned.replaces_state` in client-formatted events. Contributed by @nexy7574.

changelogs/internal/newsfragments/2400.clarification

@@ -0,0 +1 @@
+Update CODEOWNERS file.

changelogs/internal/newsfragments/2402.clarification

@@ -0,0 +1 @@
+Minor fixes to `check-newsfragments` CI script.

changelogs/room_versions/newsfragments/2401.clarification

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

changelogs/server_server/newsfragments/2351.clarification

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

content/appendices.md

@@ -12,7 +12,7 @@ Specifically, where RFC 4648 requires that encoded data be padded to a
 multiple of four characters using `=` characters, unpadded Base64 omits
 this padding.
 
-For reference, RFC 4648 uses the following alphabet for Base 64:
+For reference, RFC 4648 uses the following alphabet for Base64:
 
     Value Encoding  Value Encoding  Value Encoding  Value Encoding
         0 A            17 R            34 i            51 z
@@ -47,6 +47,12 @@ When decoding Base64, implementations SHOULD accept input with or
 without padding characters wherever possible, to ensure maximum
 interoperability.
 
+### URL-safe unpadded Base64
+
+URL-safe unpadded Base64 is identical to standard unpadded Base64, except that
+it uses `-` (minus) as the 62nd character in the alphabet, and `_` (underscore)
+as the 63rd. This matches [RFC4648’s definition of URL-safe base64](https://tools.ietf.org/html/rfc4648#section-5).
+
 ## Binary data
 
 In some cases it is necessary to encapsulate binary data, for example,
@@ -900,9 +906,17 @@ Clients MUST NOT produce incorrectly encoded URIs to avoid ambiguous interpretat
 Examples of matrix.to URIs are:
 
 <!-- Author's note: These examples should be consistent with the matrix scheme counterparts. -->
+* Link to `#somewhere:example.org`: `https://matrix.to/#/%23somewhere:example.org`
+* Link to `!somewhere:example.org`: `https://matrix.to/#/!somewhere:example.org?via=elsewhere.ca`
+* Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/!somewhere:example.org/$event:example.org?via=elsewhere.ca`
+* Link to `@alice:example.org`: `https://matrix.to/#/@alice:example.org`
+
+Note that encoding of characters is REQUIRED by RFC 3986 when they could otherwise be misinterpreted, and OPTIONAL for any other character.
+Hence the following encoding is also valid:
+
 * Link to `#somewhere:example.org`: `https://matrix.to/#/%23somewhere%3Aexample.org`
-* Link to `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org?via=elsewhere.ca`
+* Link to `!somewhere:example.org`: `https://matrix.to/#/%21somewhere%3Aexample.org?via=elsewhere.ca`
-* Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca`
+* Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/%21somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca`
 * Link to `@alice:example.org`: `https://matrix.to/#/%40alice%3Aexample.org`
 
 {{% boxes/note %}}

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

@@ -355,7 +355,7 @@ key, and encrypts the file using AES-CTR. The counter is 64 bits long,
 starting at 0 and prefixed by a random 64-bit Initialization Vector (IV),
 which together form a 128-bit unique counter block.
 
-Clients MUST generate both the AES key and IV using a cryptographically 
+Clients MUST generate both the AES key and IV using a cryptographically
 secure random source and MUST NOT use the same key or IV multiple
 times. The latter 64 bits of the 128-bit counter block MUST start at zero.
 
@@ -385,31 +385,11 @@ Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) format, with a
 ###### Extensions to `m.room.message` msgtypes
 
 This module adds `file` and `thumbnail_file` properties, of type
-`EncryptedFile`, to `m.room.message` msgtypes that reference files, such
+[`EncryptedFile`](#definition-encryptedfile), to `m.room.message` msgtypes that
-as [m.file](#mfile) and [m.image](#mimage), replacing the `url` and `thumbnail_url`
+reference files, such as [m.file](#mfile) and [m.image](#mimage), replacing the
-properties.
+`url` and `thumbnail_url` properties.
 
-`EncryptedFile`
+Example `m.room.message` event containing an encrypted image:
-
-| Parameter | Type             | Description                                                                                    |
-|-----------|------------------|------------------------------------------------------------------------------------------------|
-| url       | string           | **Required.** The URL to the file.                                                             |
-| key       | JWK              | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.       |
-| iv        | string           | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.    |
-| hashes    | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients MUST support the SHA-256 hash, which uses the key `sha256`. |
-| v         | string           | **Required.** Version of the encrypted attachment's protocol. Must be `v2`.                    |
-
-`JWK`
-
-| Parameter | Type     | Description                                                                                                              |
-| --------- |----------|--------------------------------------------------------------------------------------------------------------------------|
-| kty       | string   | **Required.** Key type. Must be `oct`.                                                                                   |
-| key_ops   | [string] | **Required.** Key operations. Must at least contain `encrypt` and `decrypt`.                                             |
-| alg       | string   | **Required.** Algorithm. Must be `A256CTR`.                                                                              |
-| k         | string   | **Required.** The key, encoded as urlsafe unpadded base64.                                                               |
-| ext       | boolean  | **Required.** Extractable. Must be `true`. This is a [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk). |
-
-Example:
 
 ```json
 {
@@ -470,6 +450,8 @@ Example:
 }
 ```
 
+{{% definition path="api/client-server/definitions/encrypted_file" %}}
+
 #### Device verification
 
 Before Alice sends Bob encrypted data, or trusts data received from him,
@@ -764,7 +746,7 @@ The process between Alice and Bob verifying each other would be:
 15. Assuming they match, Alice and Bob's devices each calculate Message
     Authentication Codes (MACs) for:
     * {{% changed-in v="1.18" %}} Each of the keys that they wish the other user
-      to verify (usually their device ed25519 key and their master signing key, 
+      to verify (usually their device ed25519 key and their master signing key,
       see below). The master signing key SHOULD be included when two different
       users are verifying each other. Verifying individual devices of other
       users is deprecated.

content/identity-service-api.md

@@ -276,9 +276,8 @@ internal state of the hash function.
 
 After formatting each query, the string is run through SHA-256 as
 defined by [RFC 4634](https://tools.ietf.org/html/rfc4634). The
-resulting bytes are then encoded using URL-Safe [Unpadded
+resulting bytes are then encoded using [URL-Safe unpadded
-Base64](/appendices#unpadded-base64) (similar to [room version
+Base64](/appendices/#url-safe-unpadded-base64).
-4's event ID format](/rooms/v4#event-ids)).
 
 An example set of queries when using the pepper `matrixrocks` would be:
 

content/rooms/fragments/v4-event-ids.md

@@ -2,11 +2,8 @@
 ---
 {{% added-in v=4 %}} The event ID is the [reference
 hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
-the event encoded using a variation of [Unpadded
+the event encoded using [URL-safe unpadded
-Base64](/appendices#unpadded-base64) which replaces the 62nd and
+Base64](/appendices/#url-safe-unpadded-base64).
-63rd characters with `-` and `_` instead of using `+` and `/`. This
-matches [RFC4648's definition of URL-safe
-base64](https://tools.ietf.org/html/rfc4648#section-5).
 
 Event IDs are still prefixed with `$` and might result in looking like
 `$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`.

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

@@ -124,6 +124,8 @@ properties:
           by the local homeserver, and is only returned if the event is a state event.
           Unlike `prev_content`, this field is included regardless of history visibility.
         type: string
+        format: mx-event-id
+        pattern: "^\\$"
         x-addedInMatrixVersion: "1.19"
       membership:
         description: |

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

@@ -0,0 +1,87 @@
+# Copyright 2018-2026 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: EncryptedFile
+description: |
+  Information on an encrypted media blob, including its location in the
+  [content repository](/client-server-api/#content-repository), and the keys
+  necessary to decrypt it.
+properties:
+  url:
+    type: string
+    format: mx-mxc-uri
+    description: The URL to the file.
+    example: "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
+  key:
+    type: object
+    title: JWK
+    description: A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
+    properties:
+      kty:
+        type: string
+        description: Key type. Must be `oct`.
+        example: "oct"
+      key_ops:
+        type: array
+        items:
+          type: string
+        description: Key operations. Must at least contain `encrypt` and `decrypt`.
+        example: ["encrypt", "decrypt"]
+      alg:
+        type: string
+        description: Algorithm. Must be `A256CTR`.
+        example: A256CTR
+      k:
+        type: string
+        format: mx-urlsafe-unpadded-base64
+        description: The key, encoded as [URL-safe unpadded Base64](/appendices/#url-safe-unpadded-base64).
+        example: "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0"
+      ext:
+        type: boolean
+        description: "Extractable. Must be `true`. This is a [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk)."
+        example: true
+    required:
+      - kty
+      - key_ops
+      - alg
+      - k
+      - ext
+  iv:
+    type: string
+    format: mx-unpadded-base64
+    description: The 128-bit unique counter block used by AES-CTR, encoded as [unpadded Base64](/appendices/#unpadded-base64).
+    example: "w+sE15fzSc0AAAAAAAAAAA"
+  hashes:
+    type: object
+    title: EncryptedFileHashes
+    description:
+      A map from an algorithm name to a hash of the ciphertext. Clients MUST support the SHA-256 hash, which uses the key `sha256`.
+    properties:
+      sha256:
+        type: string
+        format: mx-unpadded-base64
+        description: The hash of the ciphertext. encoded as [unpadded Base64](/appendices/#unpadded-base64).
+        example: "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA"
+    required: ['sha256']
+  v:
+    type: string
+    description: Version of the encrypted attachment’s protocol. Must be `v2`.
+    example: v2
+required:
+  - url
+  - key
+  - iv
+  - hashes
+  - v

data/api/identity/v2_store_invite.yaml

@@ -156,7 +156,7 @@ paths:
                         public_key:
                           type: string
                           description: |
-                            The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
+                            The public key, encoded using [standard unpadded Base64](/appendices/#unpadded-base64) or [URL-safe unpadded Base64](/appendices/#url-safe-unpadded-base64).
                         key_validity_url:
                           type: string
                           description: |

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

@@ -27,8 +27,7 @@ properties:
     pattern: "^mxc:\\/\\/"
   thumbnail_file:
     description: |-
-      Information on the encrypted thumbnail file, as specified in
+      An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-      [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
       Only present if the thumbnail is encrypted.
     title: EncryptedFile
     type: object

data/event-schemas/schema/m.room.message$m.audio.yaml

@@ -58,9 +58,7 @@ properties:
         pattern: "^mxc:\\/\\/"
       file:
         description: |-
-          Required if the file is encrypted. Information on the encrypted
+          Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-          file, as specified in
-          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/event-schemas/schema/m.room.message$m.file.yaml

@@ -48,8 +48,7 @@ properties:
             pattern: "^mxc:\\/\\/"
           thumbnail_file:
             description: |-
-              Information on the encrypted thumbnail file, as specified in
+              An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
               Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
@@ -72,9 +71,7 @@ properties:
         pattern: "^mxc:\\/\\/"
       file:
         description: |-
-          Required if the file is encrypted. Information on the encrypted
+          Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-          file, as specified in
-          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/event-schemas/schema/m.room.message$m.image.yaml

@@ -48,9 +48,7 @@ properties:
         pattern: "^mxc:\\/\\/"
       file:
         description: |-
-          Required if the file is encrypted. Information on the encrypted
+          Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-          file, as specified in
-          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/event-schemas/schema/m.room.message$m.location.yaml

@@ -31,8 +31,7 @@ properties:
             pattern: "^mxc:\\/\\/"
           thumbnail_file:
             description: |-
-              Information on the encrypted thumbnail file, as specified in
+              An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
               Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object

data/event-schemas/schema/m.room.message$m.video.yaml

@@ -58,8 +58,7 @@ properties:
             pattern: "^mxc:\\/\\/"
           thumbnail_file:
             description: |-
-              Information on the encrypted thumbnail file, as specified in
+              An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
               Only present if the thumbnail is encrypted.
             title: EncryptedFile
             type: object
@@ -82,9 +81,7 @@ properties:
         pattern: "^mxc:\\/\\/"
       file:
         description: |-
-          Required if the file is encrypted. Information on the encrypted
+          Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
-          file, as specified in
-          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
         title: EncryptedFile
         type: object
     required:

data/string-formats.yaml

@@ -71,6 +71,11 @@ mx-unpadded-base64:
   url: appendices#unpadded-base64
   # no regex
 
+mx-urlsafe-unpadded-base64:
+  title: URL-safe unpadded Base64
+  url: appendices/#url-safe-unpadded-base64
+  # no regex
+
 uri:
   title: URI
   url: https://datatracker.ietf.org/doc/html/rfc3986

scripts/check-newsfragments

@@ -26,6 +26,7 @@ while read f; do
     # check that each changelog file has a known extension
     if ! [[ "$extension" == "new" || "$extension" == "feature" || "$extension" == "clarification" || "$extension" == "breaking" || "$extension" == "deprecation" ]]; then
         echo -e "\e[31mERROR: newsfragment $f does not have one of the required file extensions for a changelog entry: .new, .feature, .clarification, .breaking, .deprecation\e[39m" >&2
+        failed=1
     fi
 
     # check that there is nothing that looks like a newsfile outside one of the