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

@@ -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,

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