Rename "recovery key" to "backup decryption key" (#1819)

Also, some other editorial improvements, including factoring out our two definitions of the same key encoding algorithm.

Co-authored-by: Travis Ralston <travisr@matrix.org>

.github/ISSUE_TEMPLATE/release.md

@@ -16,6 +16,7 @@ Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
 
 Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
 
+* [ ] Ensure the social media account holders are available for the release day.
 * [ ] Blog post written
 * [ ] Check for release blockers that may have been missed
 * [ ] Review/fix the changelog

.github/_typos.toml

@@ -10,3 +10,4 @@ au1ba7o = "au1ba7o"
 [default.extend-words]
 Appy = "Appy"
 fo = "fo"
+Iy = "Iy"

.github/workflows/main.yml

@@ -20,9 +20,9 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
       - name: "🔎 Run validator"
         run: |
           npx @redocly/cli@latest lint data/api/*/*.yaml
@@ -34,7 +34,7 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -45,15 +45,15 @@ jobs:
       - name: "🔎 Run validator"
         run: |
           python scripts/check-event-schema-examples.py
-  
+
   check-openapi-examples:
     name: "🔎 Check OpenAPI definitions examples"
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -70,9 +70,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -99,11 +99,11 @@ jobs:
         # the asterisk matching behaviour, not the literal string.
         run: |
           if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo ::set-output name=baseURL::/
+              echo "baseURL=/" >> "$GITHUB_OUTPUT"
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
+              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
           else
-              echo ::set-output name=baseURL::/unstable
+              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
           fi
 
   build-openapi:
@@ -114,7 +114,7 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -152,7 +152,7 @@ jobs:
               -o spec/server-server-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: openapi-artifact
           path: openapi.tar.gz
@@ -166,13 +166,15 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
         run: ./scripts/generate-changelog.sh vUNSTABLE
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: changelog-artifact
           path: content/changelog/vUNSTABLE.md
@@ -185,11 +187,11 @@ jobs:
     if: ${{ always() }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
           hugo-version: '0.113.0'
           extended: true
@@ -201,7 +203,7 @@ jobs:
           npm run get-proposals
       - name: "📥 Download generated changelog"
         if: "needs.generate-changelog.result == 'success'"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: changelog-artifact
           path: content/changelog
@@ -212,7 +214,7 @@ jobs:
       # https://spec.matrix.org/latest/client-server-api/api.json
       # Works for /unstable/ and /v1.1/ as well.
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -222,7 +224,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: spec-artifact
           path: spec.tar.gz
@@ -236,7 +238,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: "📥 Fetch built spec"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: spec-artifact
 
@@ -262,13 +264,14 @@ jobs:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.93.3'
+          # Cannot build the spec with Hugo 0.125.0 because of https://github.com/google/docsy/issues/1930
+          hugo-version: '0.124.1'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
@@ -283,7 +286,7 @@ jobs:
           hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -293,7 +296,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec-historical.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -32,10 +32,10 @@ jobs:
           pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |
                jq -r '.[] | .number')
           echo "PR number: $pr_number"
-          echo "::set-output name=prnumber::$pr_number"
+          echo "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
         
       - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@268677152d06ba59fcec7a7f0b5d961b6ccd7e1e # v2.28.0
+        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
         with:
           workflow: main.yaml
           run_id: ${{ github.event.workflow_run.id }}
@@ -46,8 +46,7 @@ jobs:
         
       - name: "📤 Deploy to Netlify"
         id: netlify
-        # v2.1.0
-        uses: nwtgck/actions-netlify@7a92f00dde8c92a5a9e8385ec2919775f7647352
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: 🔧 Yarn cache
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           cache: "yarn"
           cache-dependency-path: packages/npm/yarn.lock
@@ -26,14 +26,15 @@ jobs:
       - name: 🔨 Install dependencies
         run: "yarn install --frozen-lockfile"
 
+      # We bump the package.json version to git, we just need it for publish to do the right thing
       - name: 🎖 Bump package.json version
-        run: "yarn version $VERSION"
+        run: "yarn version --new-version ${VERSION#v} --no-git-tag-version"
         env:
           VERSION: ${{ github.event.release.tag_name }}.0
 
       - name: 🚀 Publish to npm
         id: npm-publish
-        uses: JS-DevTools/npm-publish@5a85faf05d2ade2d5b6682bfe5359915d5159c6c # v2.2.1
+        uses: JS-DevTools/npm-publish@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1
         with:
           token: ${{ secrets.NPM_TOKEN }}
           package: packages/npm

.github/workflows/spell-check.yaml

@@ -14,6 +14,6 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@ff3f309513469397e1094520fb7a054e057589e1
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
       with:
-        config: ${{github.workspace}}/.github/_typos.toml
+        config: ${{github.workspace}}/.github/_typos.toml

.gitmodules

@@ -1,7 +0,0 @@
-[submodule "themes/docsy"]
-	path = themes/docsy
-	# We use our own forked version of the Docsy theme,
-	# to avoid loading fonts from CDNs, which Docsy currently
-	# doesn't support (see https://github.com/google/docsy/issues/605).
-	url = https://github.com/matrix-org/docsy.git
-	branch = master

CONTRIBUTING.rst

@@ -12,7 +12,7 @@ The documentation style is described at
 https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst.
 
 Matrix-spec workflows
---------------------
+---------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -72,7 +72,7 @@ ask.
 Adding to the changelog
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-All API specifications require a changelog entry. Adding to the changelog can only
+All changes to the contents of this repository require a changelog entry. Adding to the changelog can only
 be done after you've opened your pull request, so be sure to do that first.
 
 The changelog is managed by `Towncrier <https://github.com/twisted/towncrier>`_ in the
@@ -117,7 +117,7 @@ license - in our case, this is Apache Software License v2 (see LICENSE).
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach used by the `Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_,
-`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md`_, and many other
+`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md>`_, and many other
 projects: the `Developer Certificate of Origin <http://developercertificate.org/>`_
 (DCO). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::

README.md

@@ -61,13 +61,12 @@ 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.93.0 is required.
+   v0.113.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
    to process the SCSS.)
-2. Run `npm i` to install the dependencies and fetch the docsy git submodule.
-   Note that this will require NodeJS to be installed.
+2. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
 3. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
    page and is not required.
 4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313

assets/scss/_styles_project.scss

@@ -18,9 +18,6 @@ limitations under the License.
 Custom SCSS for the Matrix spec
 */
 
-@import "variables_project";
-@import "variables";
-
 /* Import the CSS classes for the syntax highlighter.
  *
  * This is generated with:
@@ -43,10 +40,17 @@ Custom SCSS for the Matrix spec
   .navbar-brand {
     font-size: 1.1rem;
 
+    /* Allow the text to wrap if it is wider than the viewport */
+    text-align: center;
+    white-space: normal;
+
     .navbar-version {
       color: $secondary;
     }
+  }
 
+  .nav-link {
+    font-weight: normal;
   }
 
   a {
@@ -114,7 +118,7 @@ Custom SCSS for the Matrix spec
   }
 }
 
-@media (min-width: 768px) {
+@include media-breakpoint-up(md) {
   @supports (position: sticky) {
     .td-sidebar-nav {
       /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */
@@ -171,6 +175,13 @@ footer {
 
 }
 
+/* Remove some padding before the main content, when the sidebar is disabled */
+.td-main main {
+  @include media-breakpoint-down(md) {
+    padding-top: 0;
+  }
+}
+
 /* Adjust the scroll margin for everything in the main content, so that
  * it doesn't disappear behind the header bar */
 .td-content * {
@@ -292,7 +303,7 @@ footer {
 }
 
 /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
-.rendered-data {
+.td-content .rendered-data {
   background-color: $secondary-lightest-background;
   padding: 0.85rem;
   margin: 0.85rem 0;
@@ -346,7 +357,7 @@ footer {
   }
 
   p code, table code {
-    background-color: inherit;
+    background-color: transparent;
   }
 
   table {
@@ -396,6 +407,7 @@ footer {
 
     th, td, caption {
       padding: 1rem;
+      border-top: 1px $table-border-color solid;
     }
 
     &.object-table, &.response-table, &.content-type-table {
@@ -408,14 +420,12 @@ footer {
 
             // ... but avoid double border between caption and table
             border-bottom: 0;
-        }
 
-        caption, tbody tr {
-            background-color: $table-row-default;
+            background-color: $secondary-lighter-background;
         }
 
-        tbody tr:nth-child(even) {
-            background-color: $table-row-alternate;
+        tbody tr {
+            --bs-table-striped-bg: #{$secondary-lighter-background};
         }
     }
 
@@ -427,6 +437,31 @@ footer {
     &.basic-info th {
       width: 15rem;
     }
+
+    /* Arrange rows vertically when horizontal space is constrained to avoid overflowing */
+    @include media-breakpoint-down(sm) {
+      /* Make cells full width without vertical margin */
+      &.basic-info th, &.basic-info td {
+        width: 100%;
+        display: inline-block;
+        margin-top: 0;
+        margin-bottom: 0;
+      }
+
+      /* Remove border and padding between header & data cells to make them appear like a single cell */
+      &.basic-info td {
+        padding-top: 0;
+        border-top: none;
+      }
+      &.basic-info th {
+        border-bottom: none;
+      }
+
+      /* Remove top border on all but the first header cell to prevent double borders between rows */
+      &.basic-info tr + tr th {
+        border-top: none;
+      }
+    }
   }
 
   pre {
@@ -471,12 +506,18 @@ of .td-content. This applies the same style to any blockquotes that descend from
 Make padding symmetrical (this selector is used in the default styles to apply padding-left: 3rem)
 */
 .pl-md-5, .px-md-5 {
-  padding-right: 3rem;
+  @include media-breakpoint-up(md) {
+    padding-right: 3rem;
+  }
 }
 
 /* Adjust default styles for info banner */
 .pageinfo-primary {
-  max-width: 80%;
+  @include media-breakpoint-up(lg) {
+    max-width: 80%;
+  }
+  margin-top: 0;
+  margin-right: 0;
   margin-left: 0;
   border: 0;
   border-left: solid 5px $secondary;
@@ -517,3 +558,15 @@ dd {
     border-radius: 0.25rem;  // was $border-radius, but that var isn't accessible here.
   }
 }
+
+/* Style for breadcrumbs */
+.td-breadcrumbs {
+  padding: .75rem 1rem;
+  background-color: #eee;
+  border-radius: .25rem;
+  margin-bottom: 1rem;
+
+  .breadcrumb {
+    margin: 0;
+  }
+}

assets/scss/_variables_project.scss

@@ -20,7 +20,7 @@ $dark: #333;
 $gray-100: #FBFBFB;
 
 $secondary-background: #E5F5FB;
-$secondary-lighter-background: #F4FaFC;
+$secondary-lighter-background: #F4FAFC;
 $secondary-lightest-background: #FBFDFD;
 
 
@@ -33,8 +33,7 @@ $warning-background: #FFE0E0;
 // colours for definition tables.
 // the border colour matches that used for "highlight" divs
 $table-border-color: rgba(black, .125);
-$table-row-alternate: $secondary-lightest-background;
-$table-row-default: $secondary-lighter-background;
+$table-bg: $secondary-lightest-background;
 
 /* Configure docsy to use the default system fonts instead of Google Fonts.
  * See https://www.docsy.dev/docs/adding-content/lookandfeel/#fonts */
@@ -50,3 +49,6 @@ $td-enable-google-fonts: false;
  * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html.
  */
 $font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+
+// Disable smooth scrolling as it makes TOC highlighting jump during the transition.
+$enable-smooth-scroll: false;

changelogs/appendices/newsfragments/1791.clarification

@@ -0,0 +1 @@
+Define 'Opaque Identifier Grammar'.

changelogs/appendices/newsfragments/1819.clarification

@@ -0,0 +1 @@
+Define common cryptographic key representation.

changelogs/application_service/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/application_service/newsfragments/1810.clarification

@@ -0,0 +1 @@
+Clarify that appservices should be notified of events relating to the sender_localpart user.

changelogs/client_server/newsfragments/1755.clarification

@@ -0,0 +1 @@
+Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291).

changelogs/client_server/newsfragments/1757.feature

@@ -0,0 +1 @@
+Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).

changelogs/client_server/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/client_server/newsfragments/1776.clarification

@@ -0,0 +1 @@
+Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response.

changelogs/client_server/newsfragments/1808.clarification

@@ -0,0 +1 @@
+Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).

changelogs/client_server/newsfragments/1812.feature

@@ -0,0 +1 @@
+Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692).

changelogs/client_server/newsfragments/1813.clarification

@@ -0,0 +1 @@
+Use `patternProperties` in more places with supported formats.

changelogs/client_server/newsfragments/1819.clarification

@@ -0,0 +1 @@
+Rename "recovery key" to "backup decryption key".

changelogs/identity_service/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/identity_service/newsfragments/1808.clarification

@@ -0,0 +1 @@
+Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).

changelogs/internal/newsfragments/1765.clarification

@@ -0,0 +1 @@
+Fix npm release script for `@matrix-org/spec`.

changelogs/internal/newsfragments/1769.clarification

@@ -0,0 +1 @@
+Formatting fixes in CONTRIBUTING.rst.

changelogs/internal/newsfragments/1770.clarification

@@ -0,0 +1 @@
+Reduce whitespace on mobile viewports

changelogs/internal/newsfragments/1771.clarification

@@ -0,0 +1 @@
+Arrange rows in `.basic-info` tables vertically when horizontal space is constrained.

changelogs/internal/newsfragments/1773.clarification

@@ -0,0 +1 @@
+Simplify uses of `resolve-refs` partial.

changelogs/internal/newsfragments/1775.clarification

@@ -0,0 +1 @@
+Fix Hugo warnings.

changelogs/internal/newsfragments/1781.clarification

@@ -0,0 +1 @@
+Fix `github-labels.rst`

changelogs/internal/newsfragments/1786.clarification

@@ -0,0 +1 @@
+Upgrade jsonschema and python-jsonpath CI scripts dependencies.

changelogs/internal/newsfragments/1787.clarification

@@ -0,0 +1 @@
+Solve `allOf` recursively in OpenAPI and JSON Schemas.

changelogs/internal/newsfragments/1788.clarification

@@ -0,0 +1 @@
+Fix Hugo warnings.

changelogs/internal/newsfragments/1789.clarification

@@ -0,0 +1 @@
+Fix property type resolution in `render-object-table` partial.

changelogs/internal/newsfragments/1793.misc

@@ -0,0 +1 @@
+Factor out common definition of `Tag` type.

changelogs/internal/newsfragments/1794.clarification

@@ -0,0 +1 @@
+Update the version of Hugo used to render the spec to v0.124.1.

changelogs/internal/newsfragments/1796.clarification

@@ -0,0 +1 @@
+Add support for pattern formats for `patternProperties`.

changelogs/internal/newsfragments/1797.clarification

@@ -0,0 +1 @@
+Clean up unnecessary `allOf`s in OpenAPI definitions.

changelogs/internal/newsfragments/1798.clarification

@@ -0,0 +1 @@
+Show information about "Additional Properties" in object tables.

changelogs/internal/newsfragments/1799.clarification

@@ -0,0 +1 @@
+Fix anchors for schemas under `oneOf`.

changelogs/internal/newsfragments/1800.clarification

@@ -0,0 +1 @@
+Use reference to `OneTimeKeys` schema in OpenAPI definitions.

changelogs/internal/newsfragments/1801.clarification

@@ -0,0 +1 @@
+Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`.

changelogs/internal/newsfragments/1802.clarification

@@ -0,0 +1 @@
+Add anchors in `definition` shortcode.

changelogs/internal/newsfragments/1803.clarification

@@ -0,0 +1 @@
+Update most CI actions.

changelogs/internal/newsfragments/1804.clarification

@@ -0,0 +1 @@
+Update typos CI action.

changelogs/internal/newsfragments/1805.clarification

@@ -0,0 +1 @@
+Set python version for the Towncrier CI job.

changelogs/internal/newsfragments/1806.clarification

@@ -0,0 +1 @@
+Replace `set-output` with environment files in CI.

changelogs/internal/newsfragments/1809.clarification

@@ -0,0 +1 @@
+Render response headers.

changelogs/internal/newsfragments/1814.clarification

@@ -0,0 +1 @@
+Add support for rendering string formats.

changelogs/server_server/newsfragments/1772.clarification

@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.

changelogs/server_server/newsfragments/1813.clarification

@@ -0,0 +1 @@
+Use `patternProperties` in more places with supported formats.

changelogs/server_server/newsfragments/1818.clarification

@@ -0,0 +1 @@
+Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list.

config.toml

@@ -7,21 +7,34 @@ canonifyURLs = true
 
 enableRobotsTXT = true
 
-# Hugo allows theme composition (and inheritance). The precedence is from left to right.
-theme = ["docsy"]
-
 # We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
 # links to it when used with a --baseURL (for example, https://spec.matrix.org/v1.4/
 # contains `<link rel="alternate" type="application/rss&#43;xml" href="/v1.4/v1.4/index.xml">`).
-disableKinds = ["taxonomy", "taxonomyTerm", "RSS"]
+disableKinds = ["taxonomy", "RSS"]
 
 [languages]
 [languages.en]
 title = "Matrix Specification"
-description = "Home of the Matrix specification for decentralised communication"
 languageName ="English"
 # Weight used for sorting.
 weight = 1
+[languages.en.params]
+description = "Home of the Matrix specification for decentralised communication"
+
+# Entries in the main menu in the header.
+[menus]
+[[menus.main]]
+    name = 'Foundation'
+    url = 'https://matrix.org/foundation/'
+    weight = 10
+[[menus.main]]
+    name = 'FAQs'
+    url = 'https://matrix.org/faq'
+    weight = 20
+[[menus.main]]
+    name = 'Blog'
+    url = 'https://matrix.org/blog/posts'
+    weight = 30
 
 [markup]
   [markup.goldmark]
@@ -47,14 +60,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice"
 [params.version]
 # must be one of "unstable", "current", "historical"
 # this is used to decide whether to show a banner pointing to the current release
-status = "stable"
+status = "unstable"
 # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
 current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
-major = "1"
-minor = "9"
-release_date = "November 29, 2023"
+# major = "1"
+# minor = "10"
+# release_date = "March 22, 2024"
 
 # User interface configuration
 [params.ui]
@@ -111,3 +124,13 @@ sidebar_menu_compact = true
     X-Frame-Options = "sameorigin"
     Access-Control-Allow-Origin = "*"
     Access-Control-Allow-Methods = "GET"
+
+# hugo module configuration
+
+[module]
+  [module.hugoVersion]
+    extended = true
+    min = "0.113.0"
+  [[module.imports]]
+    path = "github.com/matrix-org/docsy"
+    disable = false

content/appendices.md

@@ -921,6 +921,50 @@ unique servers based on the following criteria:
     specify the servers it can. For example, a room with only 2 users in
     it would result in maximum 2 `via` parameters.
 
+### Opaque Identifiers
+
+The specification defines some identifiers to use the *Opaque Identifier
+Grammar*. This is a common grammar intended for non-user-visible identifiers
+which do not require parsing or interpretation (other than as a unique
+identifier).
+
+The grammar is defined as:
+
+* Identifiers must be entirely composed of the characters `[0-9]`, `[A-Z]`,
+  `[a-z]`, `-`, `.`, `_`, and `~`.
+* Unless otherwise specified, identifiers must be at least one character and at
+  most 255 characters in length.
+
+{{% boxes/note %}}
+The acceptable character set matches the unreserved character set in [RFC
+3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
+{{% /boxes/note %}}
+
+## Cryptographic key representation
+
+Sometimes it is necessary to present a private cryptographic key in the user
+interface.
+
+When this happens, the key SHOULD be presented as a string formatted as
+follows:
+
+1.  A byte array is created, consisting of two bytes `0x8B` and `0x01`,
+    followed by the raw key.
+2.  All the bytes in the array above, including the two header bytes,
+    are XORed together to form a parity byte. This parity byte is
+    appended to the byte array.
+3.  The byte array is encoded using base58, using the the alphabet
+    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
+4.  A space is added after every 4th character.
+
+When reading in a key, clients should disregard whitespace, and
+perform the reverse of steps 1 through 4.
+
+{{% boxes/note %}}
+The base58 alphabet is the same as that used for [Bitcoin
+addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart).
+{{% /boxes/note %}}
+
 ## 3PID Types
 
 Third-party Identifiers (3PIDs) represent identifiers on other

content/application-service-api.md

@@ -436,6 +436,12 @@ an application service-defined namespace will receive the same
 `M_EXCLUSIVE` error code, but only if the application service has
 defined the namespace as `exclusive`.
 
+If `/register` or `/login` is called with the `m.login.application_service`
+login type, but without a valid `as_token`, the endpoints will return an error
+with the `M_MISSING_TOKEN` or `M_UNKNOWN_TOKEN` error code and 401 as the HTTP
+status code. This is the same behavior as invalid auth in the client-server API
+(see [Using access tokens](/client-server-api/#using-access-tokens)).
+
 #### Pinging
 
 {{% added-in v="1.7" %}}

content/changelog/v1.10.md

@@ -0,0 +1,102 @@
+---
+date: 2024-03-22T09:59:45-06:00
+---
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    v1.10  = Replaced by the version number (eg: v1.2)
+    March 22, 2024     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## v1.10
+
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.10">https://github.com/matrix-org/matrix-spec/tree/v1.10</a></td>
+<tr><th>Release date</th><td>March 22, 2024</td>
+</table>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
+
+### Client-Server API
+
+**Backwards Compatible Changes**
+
+- Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026). ([#1728](https://github.com/matrix-org/matrix-spec/issues/1728))
+- Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025). ([#1730](https://github.com/matrix-org/matrix-spec/issues/1730))
+- Use the `body` field as optional media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530). ([#1731](https://github.com/matrix-org/matrix-spec/issues/1731))
+- Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929). ([#1733](https://github.com/matrix-org/matrix-spec/issues/1733))
+- Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077). ([#1735](https://github.com/matrix-org/matrix-spec/issues/1735))
+- Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041). ([#1737](https://github.com/matrix-org/matrix-spec/issues/1737))
+- Add support for recursion on the `GET /relations` endpoints, as per [MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981). ([#1746](https://github.com/matrix-org/matrix-spec/issues/1746))
+
+**Spec Clarifications**
+
+- The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead. ([#1629](https://github.com/matrix-org/matrix-spec/issues/1629))
+- Clarify that read receipts should be batched by thread as well as by room. ([#1685](https://github.com/matrix-org/matrix-spec/issues/1685))
+- Clarify that threads can be created based on replies. ([#1687](https://github.com/matrix-org/matrix-spec/issues/1687))
+- Clarify in the reply fallbacks example that the prefix sequence should be repeated for each line. ([#1690](https://github.com/matrix-org/matrix-spec/issues/1690))
+- Clarify the format of account data objects for secret storage. ([#1695](https://github.com/matrix-org/matrix-spec/issues/1695), [#1734](https://github.com/matrix-org/matrix-spec/issues/1734))
+- Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. ([#1712](https://github.com/matrix-org/matrix-spec/issues/1712))
+- Clarify one-time key and fallback key types in examples. ([#1715](https://github.com/matrix-org/matrix-spec/issues/1715))
+- Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes. ([#1719](https://github.com/matrix-org/matrix-spec/issues/1719))
+- Clarify how to perform the ECDH exchange in step 12 of the SAS process. ([#1720](https://github.com/matrix-org/matrix-spec/issues/1720))
+- Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077). ([#1732](https://github.com/matrix-org/matrix-spec/issues/1732))
+- The [font](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font) element is deprecated in the HTML spec. Clients should prefer [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) with the `data-mx-bg-color` and `data-mx-color` attributes instead. ([#1739](https://github.com/matrix-org/matrix-spec/issues/1739))
+- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
+- Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`. ([#1742](https://github.com/matrix-org/matrix-spec/issues/1742))
+- Fix various typos throughout the specification. ([#1748](https://github.com/matrix-org/matrix-spec/issues/1748))
+- Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses. ([#1756](https://github.com/matrix-org/matrix-spec/issues/1756))
+- Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763))
+
+
+### Server-Server API
+
+**Spec Clarifications**
+
+- Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies. ([#1721](https://github.com/matrix-org/matrix-spec/issues/1721))
+- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
+- Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741))
+
+
+### Application Service API
+
+**Spec Clarifications**
+
+- Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744))
+
+
+### Identity Service API
+
+No significant changes.
+
+
+### Push Gateway API
+
+No significant changes.
+
+
+### Room Versions
+
+**Spec Clarifications**
+
+- For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717))
+
+
+### Appendices
+
+No significant changes.
+
+
+### Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Update the spec release process. ([#1680](https://github.com/matrix-org/matrix-spec/issues/1680))
+- Minor clarifications to the contributing guide. ([#1697](https://github.com/matrix-org/matrix-spec/issues/1697))
+- Update Docsy to v0.8.0. ([#1699](https://github.com/matrix-org/matrix-spec/issues/1699), [#1762](https://github.com/matrix-org/matrix-spec/issues/1762))
+- Fix npm release script for `@matrix-org/spec`. ([#1713](https://github.com/matrix-org/matrix-spec/issues/1713))
+- Add some clarifications around implementation requirements for MSCs. ([#1718](https://github.com/matrix-org/matrix-spec/issues/1718))
+- Update HTML templates to include links to object schema definitions. ([#1724](https://github.com/matrix-org/matrix-spec/issues/1724))
+- Factor out all the common parameters of the various `/relations` apis. ([#1745](https://github.com/matrix-org/matrix-spec/issues/1745))
+- Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas. ([#1751](https://github.com/matrix-org/matrix-spec/issues/1751), [#1754](https://github.com/matrix-org/matrix-spec/issues/1754))

content/client-server-api/_index.md

@@ -106,7 +106,7 @@ No resource was found for this request.
 
 `M_LIMIT_EXCEEDED`
 Too many requests have been sent in a short period of time. Wait a while
-then try again.
+then try again. See [Rate limiting](#rate-limiting).
 
 `M_UNRECOGNIZED`
 The server did not understand the request. This is expected to be returned with
@@ -212,6 +212,28 @@ only read state (e.g.: `/sync`, get account data, etc).
 The user is unable to reject an invite to join the server notices room.
 See the [Server Notices](#server-notices) module for more information.
 
+#### Rate limiting
+
+Homeservers SHOULD implement rate limiting to reduce the risk of being
+overloaded. If a request is refused due to rate limiting, it should
+return a standard error response of the form:
+
+```json
+{
+  "errcode": "M_LIMIT_EXCEEDED",
+  "error": "string",
+  "retry_after_ms": integer (optional, deprecated)
+}
+```
+
+Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after)
+for any response with a 429 status code.
+
+The `retry_after_ms` property MAY be included to tell the client how long
+they have to wait in milliseconds before they can try again. This property is
+deprecated, in favour of the `Retry-After` header.
+
+{{< changed-in v="1.10" >}}: `retry_after_ms` property deprecated in favour of `Retry-After` header.
 ### Transaction identifiers
 
 The client-server API typically uses `HTTP PUT` to submit requests with
@@ -363,11 +385,12 @@ specify parameter values. The flow for this method is as follows:
 
 {{% http-api spec="client-server" api="versions" %}}
 
+{{% http-api spec="client-server" api="support" %}}
+
 ## Client Authentication
 
 Most API endpoints require the user to identify themselves by presenting
-previously obtained credentials in the form of an `access_token` query
-parameter or through an Authorization Header of `Bearer $access_token`.
+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
 can expire; a new access token can be generated by using a refresh token.
@@ -381,16 +404,19 @@ investigate [macaroons](http://research.google.com/pubs/pub41892.html).
 
 ### Using access tokens
 
-Access tokens may be provided in two ways, both of which the homeserver
-MUST support:
+Access tokens may be provided via a request header, using the Authentication
+Bearer scheme: `Authorization: Bearer TheTokenHere`.
 
-1.  Via a query string parameter, `access_token=TheTokenHere`.
-2.  Via a request header, `Authorization: Bearer TheTokenHere`.
+Clients may alternatively provide the access token via a query string parameter:
+`access_token=TheTokenHere`. This method is deprecated to prevent the access
+token being leaked in access/HTTP logs and SHOULD NOT be used by clients.
 
-Clients are encouraged to use the `Authorization` header where possible
-to prevent the access token being leaked in access/HTTP logs. The query
-string should only be used in cases where the `Authorization` header is
-inaccessible for the client.
+Homeservers MUST support both methods.
+
+{{% boxes/note %}}
+{{% changed-in v="1.11" %}}
+Sending the access token as a query string parameter is now deprecated.
+{{% /boxes/note %}}
 
 When credentials are required but missing or invalid, the HTTP call will
 return with a status of 401 and the error code, `M_MISSING_TOKEN` or
@@ -520,8 +546,10 @@ request parameter.
 A client should first make a request with no `auth` parameter.
 The homeserver returns an HTTP 401 response, with a JSON body, as follows:
 
-    HTTP/1.1 401 Unauthorized
-    Content-Type: application/json
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -564,8 +592,10 @@ given. It also contains other keys dependent on the auth type being
 attempted. For example, if the client is attempting to complete auth
 type `example.type.foo`, it might submit something like this:
 
-    POST /_matrix/client/v3/endpoint HTTP/1.1
-    Content-Type: application/json
+```
+POST /_matrix/client/v3/endpoint HTTP/1.1
+Content-Type: application/json
+```
 
 ```json
 {
@@ -585,8 +615,10 @@ along with the same object as when no authentication was attempted, with
 the addition of the `completed` key which is an array of auth types the
 client has completed successfully:
 
-    HTTP/1.1 401 Unauthorized
-    Content-Type: application/json
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -617,8 +649,10 @@ but the client may make a second attempt, it returns the same HTTP
 status 401 response as above, with the addition of the standard
 `errcode` and `error` fields describing the error. For example:
 
-    HTTP/1.1 401 Unauthorized
-    Content-Type: application/json
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -645,8 +679,10 @@ status 401 response as above, with the addition of the standard
 If the request fails for a reason other than authentication, the server
 returns an error message in the standard format. For example:
 
-    HTTP/1.1 400 Bad request
-    Content-Type: application/json
+```
+HTTP/1.1 400 Bad request
+Content-Type: application/json
+```
 
 ```json
 {
@@ -919,11 +955,12 @@ or completely closed registration (where the homeserver administrators create
 and distribute accounts).
 
 The token required for this authentication type is shared out of band from
-Matrix and is an opaque string with maximum length of 64 characters in the
-range `[A-Za-z0-9._~-]`. The server can keep any number of tokens for any
-length of time/validity. Such cases might be a token limited to 100 uses or
-for the next 2 hours - after the tokens expire, they can no longer be used
-to create accounts.
+Matrix and is an opaque string using the [Opaque Identifier
+Grammar](/appendices#opaque-identifiers), with maximum length of 64
+characters. The server can keep any number of tokens for any length of
+time/validity. Such cases might be a token limited to 100 uses or for the next
+2 hours - after the tokens expire, they can no longer be used to create
+accounts.
 
 To use this authentication type, clients should submit an auth dict with just
 the type, token, and session:
@@ -943,6 +980,129 @@ in the registration process that their token has expired.
 
 {{% http-api spec="client-server" api="registration_tokens" %}}
 
+##### Terms of service at registration
+
+{{% added-in v="1.11" %}}
+
+| Type                     | Description                                                              |
+|--------------------------|--------------------------------------------------------------------------|
+| `m.login.terms`          | Authentication requires the user to accept a set of policy documents. |
+
+{{% boxes/note %}}
+The `m.login.terms` authentication type is only valid on the
+[`/register`](#post_matrixclientv3register) endpoint.
+{{% /boxes/note %}}
+
+This authentication type is used when the homeserver requires new users to
+accept a given set of policy documents, such as a terms of service and a privacy
+policy. There may be many different types of documents, all of which are
+versioned and presented in (potentially) multiple languages.
+
+When the server requires the user to accept some terms, it does so by returning
+a 401 response to the `/register` request, where the response body includes
+`m.login.terms` in the `flows` list, and the `m.login.terms` property in the
+`params` object has the structure [shown below](#definition-mloginterms-params).
+
+If a client encounters an invalid parameter, registration should stop with an
+error presented to the user.
+
+The client should present the user with a checkbox to accept each policy,
+including a link to the provided URL. Once the user has done so, the client
+submits an `auth` dict with just the `type` and `session`, as follows, to
+indicate that all of the policies have been accepted:
+
+```json
+{
+  "type": "m.login.terms",
+  "session": "<session ID>"
+}
+```
+
+The server is expected to track which document versions it presented to the
+user during registration, if applicable.
+
+
+**Example**
+
+1. A client might submit a registration request as follows:
+
+   ```
+   POST /_matrix/client/v3/register
+   ```
+   ```json
+   {
+     "username": "cheeky_monkey",
+     "password": "ilovebananas"
+   }
+   ```
+
+2. The server requires the user to accept some terms of service before
+   registration, so returns the following response:
+
+   ```
+   HTTP/1.1 401 Unauthorized
+   Content-Type: application/json
+   ```
+   ```json
+   {
+     "flows": [
+       { "stages": [ "m.login.terms" ] }
+     ],
+     "params": {
+       "m.login.terms": {
+         "policies": {
+           "terms_of_service": {
+             "version": "1.2",
+             "en": {
+                 "name": "Terms of Service",
+                 "url": "https://example.org/somewhere/terms-1.2-en.html"
+             },
+             "fr": {
+                 "name": "Conditions d'utilisation",
+                 "url": "https://example.org/somewhere/terms-1.2-fr.html"
+             }
+           }
+         }
+       }
+     },
+     "session": "kasgjaelkgj"
+   }
+   ```
+
+3. The client presents the list of documents to the user, inviting them to
+   accept the polices.
+
+4. The client repeats the registration request, confirming that the user has
+   accepted the documents:
+   ```
+   POST /_matrix/client/v3/register
+   ```
+   ```json
+   {
+     "username": "cheeky_monkey",
+     "password": "ilovebananas",
+     "auth": {
+       "type": "m.login.terms",
+       "session": "kasgjaelkgj"
+     }
+   }
+   ```
+
+5. All authentication steps have now completed, so the request is successful:
+   ```
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+   ```
+   ```json
+   {
+     "access_token": "abc123",
+     "device_id": "GHTYAJCE",
+     "user_id": "@cheeky_monkey:matrix.org"
+   }
+   ```
+
+{{% definition path="api/client-server/definitions/m.login.terms_params" %}}
+
 #### Fallback
 
 Clients cannot be expected to be able to know how to process every
@@ -1177,7 +1337,7 @@ is complete, the client will need to submit a `/login` request matching
 `m.login.token`.
 
 {{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
-a token for their user ID if supported by the homeserver using 
+a token for their user ID if supported by the homeserver using
 [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
 
 {{% http-api spec="client-server" api="login" %}}
@@ -2156,6 +2316,19 @@ following endpoint.
 This endpoint is particularly useful if the client has lost context on the aggregation for
 a parent event and needs to rebuild/verify it.
 
+When using the `recurse` parameter, note that there no way for a client to
+control how far the server recurses. If the client decides that the server's
+recursion level is insufficient, it could, for example, perform the recursion
+itself, or disable whatever feature requires more recursion.
+
+Filters specified via `event_type` or `rel_type` will be applied to all events
+returned, whether direct or indirect relations. Events that would match the filter,
+but whose only relation to the original given event is through a non-matching
+intermediate event, will not be included. This means that supplying a `rel_type`
+parameter of `m.thread` is not appropriate for fetching all events in a thread since
+relations to the threaded events would be filtered out. For this purpose, clients should
+omit the `rel_type` parameter and perform any necessary filtering on the client side.
+
 {{% boxes/note %}}
 Because replies do not use `rel_type`, they will not be accessible via this API.
 {{% /boxes/note %}}
@@ -2521,25 +2694,6 @@ users, they should include the display name and avatar URL fields in
 these events so that clients already have these details to hand, and do
 not have to perform extra round trips to query it.
 
-## Security
-
-### Rate limiting
-
-Homeservers SHOULD implement rate limiting to reduce the risk of being
-overloaded. If a request is refused due to rate limiting, it should
-return a standard error response of the form:
-
-```json
-{
-  "errcode": "M_LIMIT_EXCEEDED",
-  "error": "string",
-  "retry_after_ms": integer (optional)
-}
-```
-
-The `retry_after_ms` key SHOULD be included to tell the client how long
-they have to wait in milliseconds before they can try again.
-
 ## Modules
 
 Modules are parts of the Client-Server API which are not universal to

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

@@ -26,6 +26,15 @@ These events can also be received in a `/events` response or in the
 
 #### Server Behaviour
 
-Servers MUST reject clients from setting account data for event types
-that the server manages. Currently, this only includes
-[m.fully\_read](#mfully_read).
+Servers MUST reject setting account data for event types
+that the server manages by using a 405 error response.
+Currently, this only includes [`m.fully_read`](#mfully_read)
+and [`m.push_rules`](#push-rules-events). This applies to
+both global and room-specific account data.
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}} `m.push_rules` was added to the rejection
+list.
+{{% /boxes/note %}}
+
+Servers must allow clients to read the above event types as normal.

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

@@ -660,10 +660,12 @@ The process between Alice and Bob verifying each other would be:
 11. Alice's device receives Bob's message and verifies the commitment
     hash from earlier matches the hash of the key Bob's device just sent
     and the content of Alice's `m.key.verification.start` message.
-12. Both Alice and Bob's devices perform an Elliptic-curve
-    Diffie-Hellman
-    (*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)),
-    using the result as the shared secret.
+12. Both Alice's and Bob's devices perform an Elliptic-curve Diffie-Hellman using
+    their private ephemeral key, and the other device's ephemeral public key
+    (*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)
+    for Alice's device and
+    *ECDH(K<sub>B</sub><sup>private</sup>*, *K<sub>A</sub><sup>public</sup>*)
+    for Bob's device), using the result as the shared secret.
 13. Both Alice and Bob's devices display a SAS to their users, which is
     derived from the shared key using one of the methods in this
     section. If multiple SAS methods are available, clients should allow
@@ -672,7 +674,7 @@ The process between Alice and Bob verifying each other would be:
     their devices if they match or not.
 15. Assuming they match, Alice and Bob's devices each calculate Message
     Authentication Codes (MACs) for:
-    * Each of the keys that they wish the other user to verify (usually their 
+    * Each of the keys that they wish the other user to verify (usually their
       device ed25519 key and their master cross-signing key).
     * The complete list of key IDs that they wish the other user to verify.
 
@@ -836,15 +838,15 @@ is the concatenation of:
 -   The Device ID of the device which sent the
     `m.key.verification.start` message, followed by `|`.
 -   The public key from the `m.key.verification.key` message sent by
-    the device which sent the `m.key.verification.start` message,
-    followed by `|`.
+    the device which sent the `m.key.verification.start` message, encoded as
+    unpadded base64, followed by `|`.
 -   The Matrix ID of the user who sent the `m.key.verification.accept`
     message, followed by `|`.
 -   The Device ID of the device which sent the
     `m.key.verification.accept` message, followed by `|`.
 -   The public key from the `m.key.verification.key` message sent by
-    the device which sent the `m.key.verification.accept` message,
-    followed by `|`.
+    the device which sent the `m.key.verification.accept` message, encoded as
+    unpadded base64, followed by `|`.
 -   The `transaction_id` being used.
 
 When the `key_agreement_protocol` is the deprecated method `curve25519`,
@@ -1269,10 +1271,10 @@ tries to read a message that it does not have keys for, it may request
 the key from the server and decrypt it. Backups are per-user, and users
 may replace backups with new backups.
 
-In contrast with [Key requests](#key-requests), Server-side key backups
-do not require another device to be online from which to request keys.
-However, as the session keys are stored on the server encrypted, it
-requires users to enter a decryption key to decrypt the session keys.
+In contrast with [key requests](#key-requests), server-side key backups do not
+require another device to be online from which to request keys. However, as
+the session keys are stored on the server encrypted, the client requires a
+[decryption key](#decryption-key) to decrypt the session keys.
 
 To create a backup, a client will call [POST
 /\_matrix/client/v3/room\_keys/version](#post_matrixclientv3room_keysversion) and define how the keys are to
@@ -1293,7 +1295,7 @@ Clients must only store keys in backups after they have ensured that the
 
 - checking that it is signed by the user's [master cross-signing
   key](#cross-signing) or by a verified device belonging to the same user, or
-- by deriving the public key from a private key that it obtained from a trusted
+- deriving the public key from a private key that it obtained from a trusted
   source. Trusted sources for the private key include the user entering the
   key, retrieving the key stored in [secret storage](#secret-storage), or
   obtaining the key via [secret sharing](#sharing) from a verified device
@@ -1310,31 +1312,24 @@ replace it with the new key based on the key metadata as follows:
 -   and finally, if `is_verified` and `first_message_index` are equal,
     then it will keep the key with a lower `forwarded_count`.
 
-###### Recovery key
+###### Decryption key
 
-If the recovery key (the private half of the backup encryption key) is
-presented to the user to save, it is presented as a string constructed
-as follows:
+Normally, the decryption key (i.e. the secret part of the encryption key) is
+stored on the server or shared with other devices using the [Secrets](#secrets)
+module. When doing so, it is identified using the name `m.megolm_backup.v1`,
+and the key is base64-encoded before being encrypted.
 
-1.  The 256-bit curve25519 private key is prepended by the bytes `0x8B`
-    and `0x01`
-2.  All the bytes in the string above, including the two header bytes,
-    are XORed together to form a parity byte. This parity byte is
-    appended to the byte string.
-3.  The byte string is encoded using base58, using the same [mapping as
-    is used for Bitcoin
-    addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
-    that is, using the alphabet
-    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
-4.  A space should be added after every 4th character.
+If the backup decryption key is given directly to the user, the key should be
+presented as a string using the common [cryptographic key
+representation](/appendices/#cryptographic-key-representation).
 
-When reading in a recovery key, clients must disregard whitespace, and
-perform the reverse of steps 1 through 3.
-
-The recovery key can also be stored on the server or shared with other devices
-using the [Secrets](#secrets) module. When doing so, it is identified using the
-name `m.megolm_backup.v1`, and the key is base64-encoded before being
-encrypted.
+{{% boxes/note %}}
+The backup decryption key was previously referred to as a "recovery
+key". However, this conflicted with common practice in client user
+interfaces, which often use the term "recovery key" to refer to the [secret
+storage](#storage) key. The term "recovery key" is no longer used in this
+specification.
+{{% /boxes/note %}}
 
 ###### Backup algorithm: `m.megolm_backup.v1.curve25519-aes-sha2`
 
@@ -1364,10 +1359,18 @@ The `session_data` field in the backups is constructed as follows:
     PKCS\#7 padding. This encrypted data, encoded using unpadded base64,
     becomes the `ciphertext` property of the `session_data`.
 
-5.  Pass the raw encrypted data (prior to base64 encoding) through
-    HMAC-SHA-256 using the MAC key generated above. The first 8 bytes of
-    the resulting MAC are base64-encoded, and become the `mac` property
-    of the `session_data`.
+5.  Pass an empty string through HMAC-SHA-256 using the MAC key generated above.
+    The first 8 bytes of the resulting MAC are base64-encoded, and become the
+    `mac` property of the `session_data`.
+
+{{% boxes/warning %}}
+Step 5 was intended to pass the raw encrypted data, but due to a bug in libolm,
+all implementations have since passed an empty string instead.
+
+Future versions of the spec will fix this problem. See
+[MSC4048](https://github.com/matrix-org/matrix-spec-proposals/pull/4048) for a
+potential new key backup algorithm version that would fix this issue.
+{{% /boxes/warning %}}
 
 {{% definition path="api/client-server/definitions/key_backup_session_data" %}}
 
@@ -1768,9 +1771,9 @@ Example response:
     ],
   },
   "device_one_time_keys_count": {
-    "curve25519": 10,
     "signed_curve25519": 20
-  }
+  },
+  "device_unused_fallback_key_types": ["signed_curve25519"]
 }
 ```
 

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

@@ -27,18 +27,41 @@ instead.
 
 Some message types support HTML in the event content that clients should
 prefer to display if available. Currently `m.text`, `m.emote`, `m.notice`,
-and `m.key.verification.request` support an additional `format` parameter of
-`org.matrix.custom.html`. When this field is present, a `formatted_body`
-with the HTML must be provided. The plain text version of the HTML
-should be provided in the `body`.
+`m.image`, `m.file`, `m.audio`, `m.video` and `m.key.verification.request`
+support an additional `format` parameter of `org.matrix.custom.html`. When this
+field is present, a `formatted_body` with the HTML must be provided. The plain
+text version of the HTML should be provided in the `body`.
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}}
+In previous versions of the specification, the `format` and `formatted` fields
+were limited to `m.text`, `m.emote`, `m.notice`, and
+`m.key.verification.request`. This list is expanded to include `m.image`,
+`m.file`, `m.audio` and `m.video` for [media captions](#media-captions).
+{{% /boxes/note %}}
 
 Clients should limit the HTML they render to avoid Cross-Site Scripting,
 HTML injection, and similar attacks. The strongly suggested set of HTML
 tags to permit, denying the use and rendering of anything else, is:
-`font`, `del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`,
-`a`, `ul`, `ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`,
-`strike`, `code`, `hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`,
-`th`, `td`, `caption`, `pre`, `span`, `img`, `details`, `summary`.
+`del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`, `a`, `ul`,
+`ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`, `s`, `code`,
+`hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`, `th`, `td`,
+`caption`, `pre`, `span`, `img`, `details`, `summary`.
+
+{{% boxes/note %}}
+{{% added-in v="1.10" %}}
+HTML features MAY be deprecated and replaced by their modern equivalent without
+requiring a [Spec Change Proposal](/proposals) when they are deprecated in the
+[WHATWG HTML Living Standard](https://html.spec.whatwg.org/multipage/).
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}}
+In previous versions of the specification, the `font` tag was suggested with the
+`data-mx-bg-color`, `data-mx-color` and `color` attributes. This tag is now
+deprecated in favor of the `span` tag with the `data-mx-bg-color` and
+`data-mx-color` attributes in new messages.
+{{% /boxes/note %}}
 
 Not all attributes on those tags should be permitted as they may be
 avenues for other disruption attempts, such as adding `onclick` handlers
@@ -50,7 +73,6 @@ the tag.
 
 | Tag    | Permitted Attributes                                                                                                                       |
 |--------|--------------------------------------------------------------------------------------------------------------------------------------------|
-| `font` | `data-mx-bg-color`, `data-mx-color`, `color`                                                                                               |
 | `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages))                                         |
 | `a`    | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) |
 | `img`  | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (`mxc://`) URI](#matrix-content-mxc-uris))                      |
@@ -320,6 +342,49 @@ to the media repository, then reference the `mxc://` URI in a markdown-style lin
 Clients SHOULD render spoilers differently with some sort of disclosure. For example, the
 client could blur the actual text and ask the user to click on it for it to be revealed.
 
+##### Media captions
+
+{{% added-in v="1.10" %}}
+
+Media messages, comprised of `m.image`, `m.file`, `m.audio` and `m.video`, can
+include a caption to convey additional information about the media.
+
+To send captions, clients MUST use the `filename` and the `body`, and optionally
+the `formatted_body` with the `org.matrix.custom.html` format, described above.
+
+If the `filename` is present, and its value is different than `body`, then
+`body` is considered to be a caption, otherwise `body` is a filename. `format`
+and `formatted_body` are only used for captions.
+
+{{% boxes/note %}}
+In previous versions of the specification, `body` was usually used to set the
+filename of the uploaded file, and `filename` was only present on `m.file` with
+the same purpose.
+{{% /boxes/note %}}
+
+An example of a media message with a caption is:
+
+```json
+{
+    "msgtype": "m.image",
+    "url": "mxc://example.org/abc123",
+    "filename": "dog.jpg",
+    "body": "this is a ~~cat~~ picture :3",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "this is a <s>cat</s> picture :3",
+    "info": {
+        "w": 479,
+        "h": 640,
+        "mimetype": "image/jpeg",
+        "size": 27253
+    },
+    "m.mentions": {}
+}
+```
+
+Clients MUST render the caption alongside the media and SHOULD prefer its
+formatted representation.
+
 #### Server behaviour
 
 Homeservers SHOULD reject `m.room.message` events which don't have a

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

@@ -208,7 +208,7 @@ event when the user expands that thread.
 
 #### Server behaviour
 
-For efficiency, receipts SHOULD be batched into one event per room
+For efficiency, receipts SHOULD be batched into one event per room and thread
 before delivering them to clients.
 
 Some receipts are sent across federation as EDUs with type `m.receipt`. The

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

@@ -60,7 +60,8 @@ specific fallback text is different for each `msgtype`, however the
 general format for the `body` is:
 
 ```text
-> <@alice:example.org> This is the original body
+> <@alice:example.org> This is the first line of the original body
+> This is the second line
 
 This is where the reply goes
 ```

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

@@ -66,6 +66,70 @@ default key.
 |------------|-----------|------------------------------------------|
 | key        | string    | **Required.** The ID of the default key. |
 
+
+###### `m.secret_storage.v1.aes-hmac-sha2`
+
+For the purposes of allowing clients to check whether a user has correctly
+entered the key, keys for use with the `m.secret_storage.v1.aes-hmac-sha2`
+algorithm are stored with some additional data.
+
+When storing a key, clients SHOULD:
+
+1.  Given the secret storage key, generate 64 bytes by performing an
+    HKDF with SHA-256 as the hash, a salt of 32 bytes of 0, and the empty
+    string as the info. The first 32 bytes are used as the AES key,
+    and the next 32 bytes are used as the MAC key.
+
+2.  Generate 16 random bytes, set bit 63 to 0 (in order to work around
+    differences in AES-CTR implementations), and use this as the AES
+    initialization vector (IV).
+
+3.  Encrypt a message consisting of 32 bytes of 0, using AES-CTR-256 using the
+    AES key and IV generated above.
+
+4.  Pass the raw encrypted data through HMAC-SHA-256 using the MAC key
+    generated above.
+
+5.  Encode the IV from step 2, and the MAC from step 4, using [unpadded
+    base64](/appendices/#unpadded-base64), and store the results in the `iv`
+    and `mac` properties respectively in the `m.secret_storage.key.[key ID]`
+    account-data. (The ciphertext from step 3 is discarded after passing
+    through the MAC calculation.)
+
+This process can be repeated by a client checking if the key is correct: the
+MAC should match if the key is correct. Note, however, that these properties
+are **optional**. If they are not present, clients must assume that the key is
+valid.
+
+Note also, that although clients SHOULD use unpadded base64 as specified above,
+some existing implementations use standard [RFC4648-compliant
+base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) with padding,
+so clients must accept either encoding.
+
+The structure of a `m.secret_storage.key.[key ID]` account data object for use
+with this algorithm is therefore as follows:
+
+`AesHmacSha2KeyDescription`
+
+| Parameter   | Type   | Description                                                                                          |
+|-------------|--------|------------------------------------------------------------------------------------------------------|
+| name        | string | Optional. The name of the key.                                                                       |
+| algorithm   | string | **Required.** The encryption algorithm to be used for this key: `m.secret_storage.v1.aes-hmac-sha2`. |
+| passphrase  | object | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. |
+| iv          | string | Optional. The 16-byte initialization vector for the validation check, encoded as base64.             |
+| mac         | string | Optional. The MAC of the result of encrypting 32 bytes of 0, encoded as base64.                      |
+
+For example, it could look like:
+
+```json
+{
+  "name": "m.default",
+  "algorithm": "m.secret_storage.v1.aes-hmac-sha2",
+  "iv": "random+data",
+  "mac": "mac+of+encrypted+zeros"
+}
+```
+
 ##### Secret storage
 
 Encrypted data is stored in the user's account data using the event
@@ -82,7 +146,7 @@ of the data.
 
 | Parameter | Type             | Description |
 |-----------|------------------|-------------|
-| encrypted | {string: object} | **Required.** Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of `AesHmacSha2EncryptedData` in the [m.secret_storage.v1.aes-hmac-sha2](#msecret_storagev1aes-hmac-sha2) section. |
+| encrypted | {string: object} | **Required.** Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of `AesHmacSha2EncryptedData` in the [m.secret_storage.v1.aes-hmac-sha2](#msecret_storagev1aes-hmac-sha2-1) section. |
 
 Example:
 
@@ -147,58 +211,41 @@ HMAC-SHA-256. The secret is encrypted as follows:
 1.  Given the secret storage key, generate 64 bytes by performing an
     HKDF with SHA-256 as the hash, a salt of 32 bytes of 0, and with the
     secret name as the info. The first 32 bytes are used as the AES key,
-    and the next 32 bytes are used as the MAC key
+    and the next 32 bytes are used as the MAC key.
+
 2.  Generate 16 random bytes, set bit 63 to 0 (in order to work around
     differences in AES-CTR implementations), and use this as the AES
-    initialization vector. This becomes the `iv` property, encoded using
-    base64.
-3.  Encrypt the data using AES-CTR-256 using the AES key generated
-    above. This encrypted data, encoded using base64, becomes the
-    `ciphertext` property.
-4.  Pass the raw encrypted data (prior to base64 encoding) through
-    HMAC-SHA-256 using the MAC key generated above. The resulting MAC is
-    base64-encoded and becomes the `mac` property.
+    initialization vector (IV).
 
-`AesHmacSha2EncryptedData`
+3.  Encrypt the data using AES-CTR-256 using the AES key and IV generated
+    above.
 
-| Parameter  | Type    | Description
-|------------|---------|------------------------------------------------------------------------|
-| iv         | string  |   **Required.** The 16-byte initialization vector, encoded as base64.  |
-| ciphertext | string  |   **Required.** The AES-CTR-encrypted data, encoded as base64.         |
-| mac        | string  |   **Required.** The MAC, encoded as base64.                            |
+4.  Pass the raw encrypted data through HMAC-SHA-256 using the MAC key
+    generated above.
 
-For the purposes of allowing clients to check whether a user has
-correctly entered the key, clients should:
+5.  Encode the IV from step 2, the ciphertext from step 3, and MAC from step 4,
+    using [unpadded base64](/appendices/#unpadded-base64), and store them as
+    the `iv`, `ciphertext`, and `mac` properties respectively in the account
+    data object.
 
-1.  encrypt and MAC a message consisting of 32 bytes of 0 as described
-    above, using the empty string as the info parameter to the HKDF in
-    step 1.
-2.  store the `iv` and `mac` in the `m.secret_storage.key.[key ID]`
-    account-data.
+    **Note**: some existing implementations encode these properties using
+    standard [RFC4648-compliant
+    base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) with
+    padding, so clients must accept either encoding.
 
-`AesHmacSha2KeyDescription`
+The structure of the `encrypted` property of an account data object encrypted
+with this algorithm is therefore as follows:
 
-| Parameter   | Type   | Description                                                                                                                       |
-|-------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|
-| name        | string | Optional. The name of the key.                                                                                                    |
-| algorithm   | string | **Required.** The encryption algorithm to be used for this key. Currently, only `m.secret_storage.v1.aes-hmac-sha2` is supported. |
-| passphrase  | object | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property.                 |
-| iv          | string | The 16-byte initialization vector, encoded as base64.                                                                             |
-| mac         | string | The MAC of the result of encrypting 32 bytes of 0, encoded as base64.                                                             |
+`AesHmacSha2EncryptedData`
 
-For example, the `m.secret_storage.key.key_id` for a key using this
-algorithm could look like:
+| Parameter  | Type    | Description
+|------------|---------|------------------------------------------------------------------------|
+| iv         | string  |  **Required.** The 16-byte initialization vector, encoded as base64.  |
+| ciphertext | string  |  **Required.** The AES-CTR-encrypted data, encoded as base64.          |
+| mac        | string  |  **Required.** The MAC, encoded as base64.                             |
 
-```json
-{
-  "name": "m.default",
-  "algorithm": "m.secret_storage.v1.aes-hmac-sha2",
-  "iv": "random+data",
-  "mac": "mac+of+encrypted+zeros"
-}
-```
 
-and data encrypted using this algorithm could look like this:
+For example, data encrypted using this algorithm could look like this:
 
 ```json
 {
@@ -212,27 +259,13 @@ and data encrypted using this algorithm could look like this:
 }
 ```
 
-###### Key representation
+##### Key representation
 
 When a user is given a raw key for `m.secret_storage.v1.aes-hmac-sha2`,
-it will be presented as a string constructed as follows:
-
-1.  The key is prepended by the two bytes `0x8b` and `0x01`
-2.  All the bytes in the string above, including the two header bytes,
-    are XORed together to form a parity byte. This parity byte is
-    appended to the byte string.
-3.  The byte string is encoded using base58, using the same [mapping as
-    is used for Bitcoin
-    addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
-    that is, using the alphabet
-    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
-4.  The string is formatted into groups of four characters separated by
-    spaces.
-
-When decoding a raw key, the process should be reversed, with the
-exception that whitespace is insignificant in the user's input.
-
-###### Deriving keys from passphrases
+the key should be presented as a string using the common [cryptographic key
+representation](/appendices/#cryptographic-key-representation).
+
+##### Deriving keys from passphrases
 
 A user may wish to use a chosen passphrase rather than a randomly
 generated key. In this case, information on how to generate the key from

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

@@ -10,7 +10,7 @@ This module allows a Matrix homeserver to delegate user authentication
 to an external authentication server supporting one of these protocols.
 In this process, there are three systems involved:
 
--   A Matrix client, using the APIs defined this specification, which
+-   A Matrix client, using the APIs defined in this specification, which
     is seeking to authenticate a user to a Matrix homeserver.
 -   A Matrix homeserver, implementing the APIs defined in this
     specification, but which is delegating user authentication to the

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

@@ -14,9 +14,11 @@ history behind a disclosure.
 Threads are established using a `rel_type` of `m.thread` and reference the
 *thread root* (the main timeline event to which the thread events refer). It is not possible to create a thread from an event which itself
 is the child of an event relationship (i.e., one with an `m.relates_to`
-property). It is therefore also not possible to nest threads. All events in a
-thread reference the thread root instead of the most recent message, unlike rich
-reply chains.
+property with a `rel_type` property - see [Relationship types](#relationship-types)).
+It is therefore also not possible to nest threads. 
+
+Unlike rich reply chains, all events in a thread reference the thread root
+instead of the most recent message.
 
 As a worked example, the following represents a thread and how it would be formed:
 

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

@@ -96,13 +96,8 @@ Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of A
 in the RTP payload.
 
 #### Grammar for VoIP IDs
-`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting
-of the characters `[0-9a-zA-Z._~-]`.
 
-(Note that this matches the grammar of 'opaque IDs' from
-[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids),
-and that of the `id` property of the
- [`m.login.sso` flow schema](#definition-mloginsso-flow-schema).)
+`call_id`s and `party_id` must follow the [Opaque Identifier Grammar](/appendices#opaque-identifiers).
 
 #### Behaviour on Room Leave
 If the client sees the user it is in a call with leave the room, the client should treat this
@@ -171,18 +166,35 @@ In response to an incoming invite, a client may do one of several things:
 
 ##### Streams
 
-Clients are expected to send one stream with one track of kind `audio` (creating a
-voice call). They can optionally send a second track in the same stream of kind
-`video` (creating a video call).
-
-Clients implementing this specification use the first stream and will ignore
-any streamless tracks. Note that in the JavaScript WebRTC API, this means
-`addTrack()` must be passed two parameters: a track and a stream, not just a
-track, and in a video call the stream must be the same for both audio and video
-track.
-
-A client may send other streams and tracks but the behaviour of the other party
-with respect to presenting such streams and tracks is undefined.
+Clients may send more than one stream in a VoIP call. The streams should be
+differentiated by including metadata in the [`m.call.invite`](/client-server-api/#mcallinvite),
+[`m.call.answer`](/client-server-api/#mcallanswer) and [`m.call.negotiate`](/client-server-api/#mcallnegotiate)
+events, using the `sdp_stream_metadata` property. An [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed)
+event can be sent when the metadata changes but no negotiation is required.
+
+Clients are recommended to not mute the audio of WebRTC tracks locally when an
+incoming stream has the `audio_muted` field set to `true`. This is because when
+the other user unmutes themselves, there may be a slight delay between their
+client sending audio and the [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed)
+event arriving and any audio sent in between will not be heard. The other user
+will still stop transmitting audio once they mute on their side, so no audio is
+sent without the user's knowledge.
+
+The same suggestion does not apply to `video_muted`. Clients _should_ mute video
+locally, so that the receiving side doesn't see a black video.
+
+If `sdp_stream_metadata` is present and an incoming stream is not listed in it,
+the stream should be ignored. If a stream has a `purpose` of an unknown type, it
+should also be ignored.
+
+For backwards compatibility, if `sdp_stream_metadata` is not present in the
+initial [`m.call.invite`](/client-server-api/#mcallinvite) or [`m.call.answer`](/client-server-api/#mcallanswer)
+event sent by the other party, the client should assume that this property is
+not supported by the other party. It means that multiple streams cannot be
+differentiated: the client should only use the first incoming stream and
+shouldn't send more than one stream.
+
+Clients implementing this specification should ignore any streamless tracks.
 
 ##### Invitees
 The `invitee` field should be added whenever the call is intended for one

content/identity-service-api.md

@@ -162,15 +162,20 @@ of access tokens to authenticate users. The access tokens provided by an
 Identity Server cannot be used to authenticate Client-Server API
 requests.
 
-An access token is provided to an endpoint in one of two ways:
+Access tokens may be provided via a request header, using the
+Authentication Bearer scheme: `Authorization: Bearer TheTokenHere`.
 
-1.  Via a query string parameter, `access_token=TheTokenHere`.
-2.  Via a request header, `Authorization: Bearer TheTokenHere`.
+Clients may alternatively provide the access token via a query string
+parameter: `access_token=TheTokenHere`. This method is deprecated to
+prevent the access token being leaked in access/HTTP logs and SHOULD NOT
+be used by clients.
 
-Clients are encouraged to the use the `Authorization` header where
-possible to prevent the access token being leaked in access/HTTP logs.
-The query string should only be used in cases where the `Authorization`
-header is inaccessible for the client.
+Identity Servers MUST support both methods.
+
+{{% boxes/note %}}
+{{% changed-in v="1.11" %}}
+Sending the access token as a query string parameter is now deprecated.
+{{% /boxes/note %}}
 
 When credentials are required but missing or invalid, the HTTP call will
 return with a status of 401 and the error code `M_UNAUTHORIZED`.

content/proposals.md

@@ -380,9 +380,18 @@ As part of the proposal process the Spec Core Team will require evidence
 of the MSC working in order for it to move into FCP. This can usually be
 a branch/pull request to whichever implementation of choice that proves
 the MSC works in practice, though in some cases the MSC itself will be
-small enough to be considered proven. Where it's unclear if an MSC will
-require an implementation proof, ask in
-[\#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org).
+small enough to be considered proven. Implementations do not need to be
+merged or released, but must be of sufficient quality to show that the
+MSC works. Where it's unclear if an MSC will require an implementation
+proof, ask in [\#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org).
+Proposals may require both server-side and client-side implementations.
+
+Proposals that have not yet been implemented will have the
+`needs-implementation` label. After an implementation has been made, add a
+comment in the GitHub issue indicating so. After an implementation has been
+made, we will check it to verify that it implements the MSC. Proposals that
+have implementations that have not yet been checked will have the
+`implementation-needs-checking` label.
 
 ### Early release of an MSC/idea
 

content/rooms/fragments/v8-auth-rules.md

@@ -117,7 +117,8 @@ The rules are as follows:
     7. If `membership` is `knock`:
         1.  If the `join_rule` is anything other than `knock`, reject.
         2.  If `sender` does not match `state_key`, reject.
-        3.  If the `sender`'s current membership is not `ban` or `join`, allow.
+        3.  If the `sender`'s current membership is not `ban`, `invite`,
+            or `join`, allow.
         4.  Otherwise, reject.
     8.  Otherwise, the membership is unknown. Reject.
 5.  If the `sender`'s current membership state is not `join`, reject.

content/rooms/v10.md

@@ -194,7 +194,8 @@ The rules are as follows:
             If the `join_rule` is anything other than `knock` or
             `knock_restricted`, reject.
         2.  If `sender` does not match `state_key`, reject.
-        3.  If the `sender`'s current membership is not `ban` or `join`, allow.
+        3.  If the `sender`'s current membership is not `ban`, `invite`,
+            or `join`, allow.
         4.  Otherwise, reject.
     8.  Otherwise, the membership is unknown. Reject.
 5.  If the `sender`'s current membership state is not `join`, reject.

content/rooms/v11.md

@@ -200,7 +200,8 @@ The rules are as follows:
         1.  If the `join_rule` is anything other than `knock` or
             `knock_restricted`, reject.
         2.  If `sender` does not match `state_key`, reject.
-        3.  If the `sender`'s current membership is not `ban` or `join`, allow.
+        3.  If the `sender`'s current membership is not `ban`, `invite`,
+            or `join`, allow.
         4.  Otherwise, reject.
     8.  Otherwise, the membership is unknown. Reject.
 5.  If the `sender`'s current membership state is not `join`, reject.

content/rooms/v7.md

@@ -139,7 +139,8 @@ The rules are as follows:
         If `membership` is `knock`:
         1.  If the `join_rule` is anything other than `knock`, reject.
         2.  If `sender` does not match `state_key`, reject.
-        3.  If the `sender`'s current membership is not `ban` or `join`, allow.
+        3.  If the `sender`'s current membership is not `ban`, `invite`,
+            or `join`, allow.
         4.  Otherwise, reject.
     7.  Otherwise, the membership is unknown. Reject.
 5.  If the `sender`'s current membership state is not `join`, reject.

content/server-server-api.md

@@ -290,7 +290,7 @@ Step 1 sign JSON:
 
 ```
 {
-    "method": "GET",
+    "method": "POST",
     "uri": "/target",
     "origin": "origin.hs.example.com",
     "destination": "destination.hs.example.com",
@@ -311,7 +311,7 @@ condition applies throughout the request signing process.
 
 Step 2 add Authorization header:
 
-    GET /target HTTP/1.1
+    POST /target HTTP/1.1
     Authorization: X-Matrix origin="origin.hs.example.com",destination="destination.hs.example.com",key="ed25519:key1",sig="ABCDEF..."
     Content-Type: application/json
 
@@ -350,9 +350,10 @@ def authorization_headers(origin_name, origin_signing_key,
 
 The format of the Authorization header is given in
 [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In
-summary, the header begins with authorization scheme `X-Matrix`, followed by
-one or more spaces, followed by a comma-separated list of parameters written as
-name=value pairs. The names are case insensitive and order does not matter. The
+summary, the header begins with authorization scheme `X-Matrix`, followed by one
+or more spaces, followed by a comma-separated list of parameters written as
+name=value pairs. Zero or more spaces and tabs around each comma are allowed.
+The names are case insensitive and order does not matter. The
 values must be enclosed in quotes if they contain characters that are not
 allowed in `token`s, as defined in
 [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a
@@ -363,8 +364,9 @@ replaced by the character that follows the backslash.
 
 For compatibility with older servers, the sender should
 - only include one space after `X-Matrix`,
-- only use lower-case names, and
-- avoid using backslashes in parameter values.
+- only use lower-case names,
+- avoid using backslashes in parameter values, and
+- avoid including whitespace around the commas between name=value pairs.
 
 For compatibility with older servers, the recipient should allow colons to be
 included in values without requiring the value to be enclosed in quotes.

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

@@ -29,7 +29,9 @@ properties:
     description: A secret token that the homeserver will use authenticate requests to the application service.
   sender_localpart:
     type: string
-    description: The localpart of the user associated with the application service.
+    description: |-
+      The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or
+      is a joined member of the room where the event occurred.
   namespaces:
     type: object
     title: Namespaces
@@ -40,9 +42,10 @@ properties:
           - $ref: namespace_list.yaml
           - description: |-
               A list of namespaces defining the user IDs that the application
-              service is interested in. Events will be sent to the AS if a
-              local user matching one of the namespaces is the target of the event,
-              or is a joined member of the room where the event occurred.
+              service is interested in, in addition to its `sender_localpart`.
+              Events will be sent to the AS if a local user matching one of the
+              namespaces is the target of the event, or is a joined member of
+              the room where the event occurred.
       rooms:
         allOf:
           - $ref: namespace_list.yaml

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

@@ -13,7 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 homeserverAccessToken:
-  type: apiKey
-  name: Authorization
-  in: header
+  type: http
+  scheme: bearer
   description: The `Bearer` `hs_token` provided by the application service's registration.

data/api/application-service/ping.yaml

@@ -69,4 +69,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/protocols.yaml

@@ -339,4 +339,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/query_room.yaml

@@ -103,4 +103,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/query_user.yaml

@@ -100,4 +100,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/application-service/transactions.yaml

@@ -88,4 +88,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken

data/api/client-server/account-data.yaml

@@ -26,7 +26,8 @@ paths:
         [/sync](#get_matrixclientv3sync).
       operationId: setAccountData
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -117,7 +118,8 @@ paths:
         that set the account data.
       operationId: getAccountData
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -186,7 +188,8 @@ paths:
         clients in the per-room entries via [/sync](#get_matrixclientv3sync).
       operationId: setAccountDataPerRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -285,7 +288,8 @@ paths:
         visible to the user that set the account data.
       operationId: getAccountDataPerRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -379,4 +383,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/admin.yaml

@@ -27,7 +27,8 @@ paths:
         specified in this document.
       operationId: getWhoIs
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -120,4 +121,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/administrative_contact.yaml

@@ -31,7 +31,8 @@ paths:
         identifiers that it will accept to reset the user's account password.
       operationId: getAccount3PIDs
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The lookup was successful.
@@ -101,7 +102,8 @@ paths:
       operationId: post3PIDs
       deprecated: true
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -201,7 +203,8 @@ paths:
         already been added to another user's account on the homeserver.
       operationId: add3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -263,7 +266,8 @@ paths:
         Homeservers should track successful binds so they can be unbound later.
       operationId: bind3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -324,7 +328,8 @@ paths:
         identity server instead.
       operationId: delete3pidFromAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -393,7 +398,8 @@ paths:
         identity server instead.
       operationId: unbind3pidFromAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -584,4 +590,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/appservice_ping.yaml

@@ -57,8 +57,8 @@ paths:
                   example: mautrix-go_1683636478256400935_123
         required: true
       security:
-        # again, this is the appservice's token - not a typical client's
-        - accessToken: []
+        - appserviceAccessTokenQuery: []
+        - appserviceAccessTokenBearer: []
       responses:
         "200":
           description: The ping was successful.
@@ -177,6 +177,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    # Note: this is the same access_token definition used elsewhere in the client
-    # server API, however this expects an access token for an application service.
-    $ref: definitions/security.yaml
+    appserviceAccessTokenQuery:
+      $ref: definitions/security.yaml#/appserviceAccessTokenQuery
+    appserviceAccessTokenBearer:
+      $ref: definitions/security.yaml#/appserviceAccessTokenBearer

data/api/client-server/appservice_room_directory.yaml

@@ -67,8 +67,8 @@ paths:
                 - visibility
         required: true
       security:
-        # again, this is the appservice's token - not a typical client's
-        - accessToken: []
+        - appserviceAccessTokenQuery: []
+        - appserviceAccessTokenBearer: []
       responses:
         "200":
           description: The room's directory visibility has been updated.
@@ -95,6 +95,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    # Note: this is the same access_token definition used elsewhere in the client
-    # server API, however this expects an access token for an application service.
-    $ref: definitions/security.yaml
+    appserviceAccessTokenQuery:
+      $ref: definitions/security.yaml#/appserviceAccessTokenQuery
+    appserviceAccessTokenBearer:
+      $ref: definitions/security.yaml#/appserviceAccessTokenBearer

data/api/client-server/banning.yaml

@@ -27,7 +27,8 @@ paths:
         The caller must have the required power level in order to perform this operation.
       operationId: ban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -96,7 +97,8 @@ paths:
         The caller must have the required power level in order to perform this operation.
       operationId: unban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -169,4 +171,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/capabilities.yaml

@@ -24,7 +24,8 @@ paths:
         and other relevant capabilities.
       operationId: getCapabilities
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The capabilities of the server.
@@ -120,4 +121,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/content-repo.yaml

@@ -22,7 +22,8 @@ paths:
       summary: Upload some content to the content repository.
       operationId: uploadContent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: header
           name: Content-Type
@@ -234,7 +235,8 @@ paths:
       operationId: createContent
       x-addedInMatrixVersion: "1.7"
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       # empty json object
       responses:
         "200":
@@ -633,6 +635,28 @@ paths:
           schema:
             type: boolean
             default: false
+        - in: query
+          name: animated
+          x-addedInMatrixVersion: "1.11"
+          required: false
+          description: |
+            Indicates preference for an animated thumbnail from the server, if possible. Animated
+            thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
+            `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`
+            content types.
+
+            When `true`, the server SHOULD return an animated thumbnail if possible and supported.
+            When `false`, the server MUST NOT return an animated thumbnail. For example, returning a
+            static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT
+            return an animated thumbnail.
+
+            Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
+
+            When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
+            server should behave as though `animated` is `false`.
+          example: false
+          schema:
+            type: boolean
       responses:
         "200":
           description: A thumbnail of the requested content.
@@ -644,6 +668,9 @@ paths:
                 enum:
                   - image/jpeg
                   - image/png
+                  - image/apng
+                  - image/gif
+                  - image/webp
           content:
             image/jpeg:
               schema:
@@ -651,7 +678,23 @@ paths:
                 description: "**Required.** The bytes for the thumbnail."
             image/png:
               schema:
-                description: "**Required.** The bytes for the thumbnail."
+                x-changedInMatrixVersion:
+                  "1.11": The PNG may be of the APNG variety if animation is supported and requested.
+                description: |
+                  **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated
+                  format if `animated=true`.
+            image/apng:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/gif:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/webp:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
         "307":
           description: A redirect to the thumbnail of the requested content.
           headers:
@@ -741,7 +784,8 @@ paths:
         being shared should also not be shared with the homeserver.
       operationId: getUrlPreview
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: url
@@ -816,7 +860,8 @@ paths:
         than is advertised by the server on this endpoint.
       operationId: getConfig
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The public content repository configuration for the matrix server.
@@ -859,4 +904,7 @@ servers:
         default: /_matrix
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/create_room.yaml

@@ -64,7 +64,8 @@ paths:
         `creation_content`.
       operationId: createRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -290,4 +291,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/cross_signing.yaml

@@ -26,7 +26,8 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
       operationId: uploadCrossSigningKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -155,7 +156,8 @@ paths:
         property, which contains the new signature(s) to add.
       operationId: uploadCrossSigningSignatures
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -163,10 +165,12 @@ paths:
               type: object
               description: |-
                 A map of user ID to a map of key ID to signed JSON object.
-              additionalProperties:
-                type: object
-                additionalProperties:
+              patternProperties:
+                "^@":
+                  x-pattern-format: mx-user-id
                   type: object
+                  additionalProperties:
+                    type: object
               example: {
                 "@alice:example.com": {
                   "HIJKLMN": {
@@ -236,11 +240,13 @@ paths:
                       A map from user ID to key ID to an error for any signatures
                       that failed.  If a signature was invalid, the `errcode` will
                       be set to `M_INVALID_SIGNATURE`.
-                    additionalProperties:
-                      type: object
-                      additionalProperties:
+                    patternProperties:
+                      "^@":
                         type: object
-                        title: Error
+                        x-pattern-format: mx-user-id
+                        additionalProperties:
+                          type: object
+                          title: Error
                     example:
                       "@alice:example.com":
                         HIJKLMN:
@@ -262,4 +268,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

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

@@ -53,10 +53,12 @@ properties:
        `<algorithm>:<device_id>` to the signature.
 
        The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
-    additionalProperties:
-      type: object
-      additionalProperties:
-        type: string
+    patternProperties:
+      "^@":
+        x-pattern-format: mx-user-id
+        type: object
+        additionalProperties:
+          type: string
     example:
       "@alice:example.com":
         "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"

data/api/client-server/definitions/m.login.terms_params.yaml

@@ -0,0 +1,82 @@
+# Copyright 2024 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: m.login.terms params
+description: Schema for `m.login.terms` entry in the `params` object in a User-Interactive Authentication response.
+required: ['policies']
+properties:
+  policies:
+    type: object
+    description: |
+      A map from "Policy ID" to the current definition of this policy document. The Policy ID is a unique
+      identifier for a given policy document, using the [Opaque Identifier Grammar](/appendices/#opaque-identifiers).
+    additionalProperties:
+      type: object
+      title: Policy Definition
+      required: [version]
+      properties:
+        version:
+          type: string
+          description: |
+            The version of this policy document. This is provided as a convenience for the client,
+            and uses the [Opaque Identifier Grammar](/appendices/#opaque-identifiers).
+      additionalProperties:
+        type: object
+        title: Policy Translation
+        required: [name, url]
+        description: |
+          Map from language codes to details of the document in that language.
+          Language codes SHOULD be formatted as per [Section 2.2 of RFC
+          5646](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2),
+          though some implementations may use an underscore instead of dash
+          (for example, `en_US` instead of `en-US`).
+        properties:
+          name:
+            type: string
+            description: |
+              The name of this document, in the appropriate language. An
+              arbitrary string with no specified maximum length.
+          url:
+            type: string
+            description: |
+              A link to the text of this document, in the appropriate
+              language. MUST be a valid URI with scheme `https://` or
+              `http://`. Insecure HTTP is discouraged.
+example: {
+    "policies": {
+        "terms_of_service": {
+            "version": "1.2",
+            "en": {
+                "name": "Terms of Service",
+                "url": "https://example.org/somewhere/terms-1.2-en.html"
+            },
+            "fr": {
+                "name": "Conditions d'utilisation",
+                "url": "https://example.org/somewhere/terms-1.2-fr.html"
+            }
+        },
+        "privacy_policy": {
+            "version": "1.2",
+            "en": {
+                "name": "Privacy Policy",
+                "url": "https://example.org/somewhere/privacy-1.2-en.html"
+            },
+            "fr": {
+                "name": "Politique de confidentialité",
+                "url": "https://example.org/somewhere/privacy-1.2-fr.html"
+            }
+        }
+    }
+}

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

@@ -9,6 +9,7 @@ additionalProperties:
   oneOf:
     - type: string
     - type: object
+      title: KeyObject
       properties:
         key:
           type: string
@@ -18,7 +19,9 @@ additionalProperties:
           description: |-
             Signature for the device. Mapped from user ID to signature object,
             containing mapping from _key signing identifier_ to the signature
-            (see also: https://spec.matrix.org/v1.2/appendices/#signing-json)
-          additionalProperties:
-            type: object
+            (see also: [Signing JSON](/appendices/#signing-json))
+          patternProperties:
+            "^@":
+              x-pattern-format: mx-user-id
+              type: object
       required: ['key', 'signatures']

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

@@ -14,37 +14,22 @@
 properties:
   content:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   override:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   room:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   sender:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   underride:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
 type: object

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

@@ -20,8 +20,7 @@ properties:
     type: object
     description: "A map of session IDs to key data."
     additionalProperties:
-      allOf:
-        - $ref: "key_backup_data.yaml"
+      $ref: "key_backup_data.yaml"
     example: {
       "sessionid1": {
         "first_message_index": 1,

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

@@ -11,8 +11,37 @@
 # 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.
-accessToken:
+accessTokenQuery:
   type: apiKey
-  description: The access_token returned by a call to `/login` or `/register`
+  description: |-
+    **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query
+    parameter.
+
+    It can also be the `as_token` of an application service.
   name: access_token
   in: query
+accessTokenBearer:
+  type: http
+  description: |-
+    The `access_token` returned by a call to `/login` or `/register`, using the
+    `Authorization: Bearer` header.
+
+    It can also be the `as_token` of an application service.
+    
+    This is the preferred method.
+  scheme: bearer
+appserviceAccessTokenQuery:
+  type: apiKey
+  description: |-
+    **Deprecated.** The `as_token` of an application service, as a query
+    parameter.
+  name: access_token
+  in: query
+appserviceAccessTokenBearer:
+  type: http
+  description: |-
+    The `as_token` of an application service, using the `Authorization: Bearer`
+    header.
+    
+    This is the preferred method.
+  scheme: bearer

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

@@ -40,10 +40,7 @@ properties:
           description: |-
             Opaque string chosen by the homeserver, uniquely identifying
             the IdP from other IdPs the homeserver might support. Should
-            be between 1 and 255 characters in length, containing unreserved
-            characters under [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt)
-            (`ALPHA  DIGIT  "-" / "." / "_" / "~"`). Clients are not intended
-            to parse or infer meaning from opaque strings.
+            use the [Opaque identifier Grammar](/appendices#opaque-identifiers).
           example: "com.example.idp.github"
         name:
           type: string

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

@@ -0,0 +1,24 @@
+# Copyright 2020-2024 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.
+
+title: Tag
+type: object
+properties:
+  order:
+    type: number
+    format: float
+    description: |-
+      A number in a range `[0,1]` describing a relative
+      position of the room under the given tag.
+    example: 0.25