Merge 8947eaf0b2 into 48051c3450

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>
Co-authored-by: Tulir Asokan <tulir@maunium.net>
Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>

.github/workflows/main.yml

@@ -1,7 +1,7 @@
 name: "Spec"
 
 env:
-  HUGO_VERSION: 0.153.3
+  HUGO_VERSION: 0.155.3
   PYTHON_VERSION: 3.13
   NODE_VERSION: 24
 

README.md

@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.146.0 is required.
+   v0.155.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required

changelogs/client_server/newsfragments/2345.feature

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

changelogs/client_server/newsfragments/2352.clarification

@@ -0,0 +1 @@
+Clarify how to find `via` parameter when following room upgrades.

changelogs/client_server/newsfragments/2354.feature

@@ -0,0 +1 @@
+Specify `m.key_backup` account data, as per [MSC4287](https://github.com/matrix-org/matrix-spec-proposals/pull/4287).

changelogs/internal/newsfragments/2346.clarification

@@ -0,0 +1 @@
+Upgrade Docsy theme to v0.14.3.

changelogs/server_server/newsfragments/2326.clarification

@@ -0,0 +1 @@
+Clarify the behaviour and response format of `GET /_matrix/federation/v1/query/profile`.

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

@@ -1479,6 +1479,43 @@ potential new key backup algorithm version that would fix this issue.
 
 {{% http-api spec="client-server" api="key_backup" %}}
 
+###### Key backup enabled preference
+
+{{% added-in v="1.19" %}}
+
+This enables clients to track a user's preference about enabling or
+disabling [server-side backups of room keys](#server-side-key-backups). The data
+is stored in the [`m.key_backup`](#mkey_backup) global
+[account data](#client-config).
+
+{{% event event="m.key_backup" %}}
+
+When a user signs in to a client which supports encryption and key backup:
+
+* If this event type exists in account data and contains the specified property
+  in the correct format, clients which support key backup MUST take account of
+  its contents in their behaviour. For example, clients may automatically turn
+  on/off key backup based on the property, or prompt the user, using the
+  property value as a default. (Because this property is server-controlled,
+  clients may wish to confirm the user's intention.)
+
+* If this event type does not exist in account data, or if it does not contain
+  the `enabled` property, or if the value of `enabled` is not a boolean value,
+  clients MUST ignore the existing value and MAY decide whether or not to
+  perform key backup, possibly based on user input.
+
+If the user turns on key backups, clients MUST set this event type in account
+data, to `"enabled": true`.
+
+If the user turns off key backups, clients MUST set this event type in account
+data, to `"enabled": false`.
+
+Clients are not required to monitor the `m.key_backup` account data actively.
+Clients MAY monitor the setting but should be aware that changing this setting
+without user interaction based on choices made in a different client (or a
+compromised homeserver) may cause unforeseen security problems or simply be
+unexpected by users.
+
 ##### Key exports
 
 Keys can be manually exported from one device to an encrypted file,

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

@@ -20,6 +20,10 @@ old room. Another approach may be to virtually merge the rooms such that
 the old room's timeline seamlessly continues into the new timeline
 without the user having to jump between the rooms.
 
+When joining a room using the room ID in an `m.room.tombstone` event or
+`predecessor` field on `m.room.create`, clients SHOULD parse the event
+`sender` and use the resulting server name as a `via` parameter.
+
 {{% http-api spec="client-server" api="room_upgrades" %}}
 
 #### Server behaviour

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

@@ -105,9 +105,10 @@ properties:
         type: string
       prev_content:
         description: |
-          The previous `content` for this event. This field is generated
-          by the local homeserver, and is only returned if the event is a state event,
-          and the client has permission to see the previous content.
+          The `content` of the previous state event that was replaced by this event.
+          This field is generated by the local homeserver, and is only returned if
+          the event is a state event, and the client has permission to see the
+          previous event.
         x-changedInMatrixVersion:
           "1.2": |
             Previously, this field was specified at the top level of returned
@@ -117,6 +118,13 @@ properties:
             this.
         title: EventContent
         type: object
+      replaces_state:
+        description: |
+          The event ID of the state event replaced by this event. This field is generated
+          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
+        x-addedInMatrixVersion: "1.19"
       membership:
         description: |
           The room membership of the user making the request, at the time of the event.

data/api/server-server/query.yaml

@@ -111,22 +111,26 @@ paths:
       summary: Query for profile information about a given user
       description: |-
         Performs a query to get profile information, such as a display name or avatar,
-        for a given user. Homeservers should only query profiles for users that belong
+        for a given user. Homeservers MUST only query profiles for users that belong
         to the target server (identified by the [server name](/appendices/#server-name)
         in the user ID).
 
-        Servers may wish to cache the response to this query to avoid requesting the
-        information too often.
+        Responding servers MAY:
+          - Include arbitrary key/value pairs in the profile in addition to the
+            specified pairs.
+          - Deny profile look-up over federation by responding with 403 and an error code of
+            `M_FORBIDDEN`.
+          - Omit certain key/value pairs in the response.
 
-        Servers MAY deny profile look-up over federation by responding with 403 and an
-        error code of `M_FORBIDDEN`.
+        Requesting servers MAY wish to cache the response to this query to avoid requesting the
+        information too often.
       operationId: queryProfile
       security:
         - signedRequest: []
       parameters:
         - in: query
           name: user_id
-          description: The user ID to query. Must be a user local to the receiving homeserver.
+          description: The user ID to query. MUST be a user local to the receiving homeserver.
           required: true
           example: "@someone:example.org"
           schema:
@@ -134,24 +138,26 @@ paths:
         - in: query
           name: field
           description: |-
-            The field to query. If specified, the server will only return the given field
-            in the response. If not specified, the server will return the full profile for
-            the user.
+            The field of the profile to query. If specified, the server MUST only return the
+            given field in the response. If not specified, the server MUST return the full,
+            public, profile for the user.
+
+            Defined values are `displayname`, `avatar_url` and `m.tz`. In addition to these
+            servers MAY allow users to set additional key/value pairs.
           schema:
             type: string
-            enum:
-              - displayname
-              - avatar_url
       responses:
         "200":
           description: |-
-            The profile for the user. If a `field` is specified in the request, only the
-            matching field should be included in the response. If no `field` was specified,
-            the response should include the fields of the user's profile that can be made
-            public, such as the display name and avatar.
+            The profile for the user. If a `field` is specified in the request, the response
+            MUST only include the specified `field`. If no `field` was specified, the response
+            SHOULD include all of the fields of the user's profile, which can be made public.
+
+            If a field in the user's profile can't be made public over the federation, the
+            responding server MAY choose to exclude it in the response.
 
             If the user does not have a particular field set on their profile, the server
-            should exclude it from the response body or give it the value `null`.
+            MUST either exclude it from the response body or give it the value `null`.
           content:
             application/json:
               schema:
@@ -160,20 +166,28 @@ paths:
                   displayname:
                     type: string
                     description: |-
-                      The display name of the user. May be omitted if the user does not have a
-                      display name set.
+                      The display name of the user. MUST either be omitted or set to `null` if
+                      the user does not have a display name set.
                     example: John Doe
                   avatar_url:
                     type: string
                     description: |-
-                      The avatar URL for the user's avatar. May be omitted if the user does not
-                      have an avatar set.
-                    example: mxc://matrix.org/MyC00lAvatar
+                      The avatar URL for the user's avatar. MUST either be omitted or set to
+                      `null` if the user does not have an avatar set.
+                    example: mxc://example.org/MyC00lAvatar
+                  m.tz:
+                    type: string
+                    description: The name of the user's time zone. The name SHOULD be registered in
+                      the [IANA Time Zone Database](https://www.iana.org/time-zones). Requesting
+                      servers MUST tolerate invalid or unknown values.
+                    x-addedInMatrixVersion: "1.16"
+                additionalProperties:
+                  description: Additional profile fields.
               examples:
                 response:
                   value: {
                     "displayname": "John Doe",
-                    "avatar_url": "mxc://matrix.org/MyC00lAvatar"
+                    "avatar_url": "mxc://example.org/MyC00lAvatar"
                   }
         "403":
           x-addedInMatrixVersion: "1.12"
@@ -190,7 +204,7 @@ paths:
                     "error": "Profile lookup over federation is disabled on this homeserver"
                   }
         "404":
-          description: The user does not exist or does not have a profile.
+          description: The user does not exist, does not have a profile or the queried field does not exist.
           content:
             application/json:
               schema:

data/event-schemas/examples/m.key_backup.yaml

@@ -0,0 +1,7 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.key_backup",
+  "content": {
+    "enabled": false
+  }
+}

data/event-schemas/schema/m.key_backup.yaml

@@ -0,0 +1,24 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  Allows clients to track user preferences about key backup.
+properties:
+  content:
+    type: object
+    properties:
+      enabled:
+        type: boolean
+        description: |-
+          True if the user chose to enable key backup. False if the user chose
+          to disable key backup.
+    required:
+      - enabled
+  type:
+    type: string
+    enum:
+      - m.key_backup
+title: Key Backup Event
+type: object

go.mod

@@ -2,4 +2,4 @@ module github.com/matrix-org/matrix-spec
 
 go 1.12
 
-require github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a // indirect
+require github.com/matrix-org/docsy v0.0.0-20260331222549-f318855c7886 // indirect

go.sum

@@ -1,4 +1,4 @@
 github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
-github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a h1:WB3unuZJy7ewAf33sxbtEwYnC+i+Jt1sJpAR3BtzvEo=
-github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a/go.mod h1:mdn1m5HJug6ZddQgrOyCrXNegbtdl5evHiqqbEQLzdI=
+github.com/matrix-org/docsy v0.0.0-20260331222549-f318855c7886 h1:+Qowx/XQ8sQGTeVyoyIpcwOcdlB+Ft6x+QJkJEPDIpg=
+github.com/matrix-org/docsy v0.0.0-20260331222549-f318855c7886/go.mod h1:mdn1m5HJug6ZddQgrOyCrXNegbtdl5evHiqqbEQLzdI=
 github.com/twbs/bootstrap v5.3.8+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

layouts/_markup/render-heading.html

@@ -1,7 +1,7 @@
 {{- /*
 
     This is a heading render hook (https://gohugo.io/render-hooks/headings/)
-    using Docsy's heading self-links hook (https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links).
+    using Docsy's heading self-links hook (https://www.docsy.dev/docs/content/navigation/#heading-self-links).
 
     This is used when a heading is encountered in markdown content to generate
     the HTML for that heading. A self-link anchor is added at the end of the

layouts/_partials/navbar.html

@@ -2,7 +2,6 @@
 
   A copy of the navbar.html partial in Docsy, modified to:
 
-  * remove `data-bs-theme` at L20, otherwise the title disappears on hover.
   * replace the site title with "specification" at L31.
   * include the spec version from the config at L34-35, which is calculated
     using an inline `version-string` partial.
@@ -16,7 +15,8 @@
 {{ $baseURL := urls.Parse $.Site.Params.Baseurl -}}
 
 <nav class="td-navbar js-navbar-scroll
-            {{- if $cover }} td-navbar-cover {{- end }}">
+      {{- if $cover }} td-navbar-cover td-navbar-transparent {{- end }}"
+      {{- if eq (.Param "ui.navbar_theme") "dark" }} data-bs-theme="dark" {{- end }}>
 <div class="td-navbar-container container-fluid flex-column flex-md-row">
   <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
     {{- /**/ -}}
@@ -35,7 +35,7 @@
 	  <span class="navbar-version"> &mdash; {{ partial "version-string" . }}</span>
     {{- /**/ -}}
   </a>
-  <div class="td-navbar-nav-scroll td-navbar-nav-scroll--indicator" id="main_navbar">
+  <div class="td-navbar__main td-navbar-nav-scroll td-navbar-nav-scroll--indicator" id="main_navbar">
     <div class="scroll-indicator scroll-left"></div>
     <ul class="navbar-nav">
       {{ $p := . -}}
@@ -80,7 +80,7 @@
     </ul>
     <div class="scroll-indicator scroll-right"></div>
   </div>
-  <div class="d-none d-lg-block td-navbar__search">
+  <div class="td-navbar__search d-none d-lg-block">
     {{ partial "search-input.html" . }}
   </div>
 </div>

layouts/_partials/sidebar-tree.html

@@ -14,6 +14,7 @@
 {{ $cacheSidebar := .cacheSidebar -}}
 
 {{ with $context -}}
+
 {{/* When the sidebar is cached, "active" class is set client side. */ -}}
 {{ $shouldDelayActive := $cacheSidebar -}}
 
@@ -174,7 +175,7 @@
       {{- end -}}
       <span class="
         {{- if $active }}td-sidebar-nav-active-item{{ end -}}
-        {{- if and $s.Params.sidebar_root_for site.Params.ui.sidebar_root_enabled }} td-sidebar-root-up-icon{{ end -}}
+        {{- if and $treeRoot $s.Params.sidebar_root_for site.Params.ui.sidebar_root_enabled }} td-sidebar-root-up-icon{{ end -}}
       ">
         {{- $s.LinkTitle -}}
       </span></a>
@@ -190,4 +191,4 @@
     </ul>
     {{- end }}
   </li>
-{{- end }}
+{{- end -}}