.github/CODEOWNERS

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

changelogs/appendices/newsfragments/2398.clarification

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

changelogs/client_server/newsfragments/2398.clarification

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

changelogs/identity_service/newsfragments/2401.clarification

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

changelogs/internal/newsfragments/2400.clarification

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

changelogs/room_versions/newsfragments/2401.clarification

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

content/appendices.md

@@ -47,12 +47,6 @@ 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,

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

@@ -385,11 +385,31 @@ 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`](#definition-encryptedfile), to `m.room.message` msgtypes that
+`EncryptedFile`, to `m.room.message` msgtypes that reference files, such
-reference files, such as [m.file](#mfile) and [m.image](#mimage), replacing the
+as [m.file](#mfile) and [m.image](#mimage), replacing the `url` and `thumbnail_url`
-`url` and `thumbnail_url` properties.
+properties.
 
-Example `m.room.message` event containing an encrypted image:
+`EncryptedFile`
+
+| 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
 {
@@ -450,8 +470,6 @@ Example `m.room.message` event containing an encrypted image:
 }
 ```
 
-{{% 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,8 +276,9 @@ 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/#url-safe-unpadded-base64).
+Base64](/appendices#unpadded-base64) (similar to [room version
+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,8 +2,11 @@
 ---
 {{% 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 [URL-safe unpadded
+the event encoded using a variation of [Unpadded
-Base64](/appendices/#url-safe-unpadded-base64).
+Base64](/appendices#unpadded-base64) which replaces the 62nd and
+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/encrypted_file.yaml

@@ -1,87 +0,0 @@
-# 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 unpadded Base64](/appendices/#unpadded-base64) or [URL-safe unpadded Base64](/appendices/#url-safe-unpadded-base64).
+                            The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
                         key_validity_url:
                           type: string
                           description: |

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

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

data/string-formats.yaml

@@ -71,11 +71,6 @@ 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