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/checks.yaml

@@ -10,7 +10,7 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - run: scripts/check-newsfragments

.github/workflows/main.yml

@@ -18,30 +18,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
-      - name: "⚙️ npm"
-        working-directory: "./scripts"
-        run: |
-          npm install
+          node-version: '20'
       - name: "🔎 Run validator"
-        working-directory: "./scripts"
         run: |
-          node validator.js -s "../data/api/application-service"
-          node validator.js -s "../data/api/client-server"
-          node validator.js -s "../data/api/push-gateway"
+          npx @redocly/cli@latest lint data/api/*/*.yaml
 
-  check-examples:
+  check-event-examples:
     name: "🔎 Check Event schema 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'
@@ -52,7 +45,45 @@ 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@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-openapi-sources.py
+
+  check-schemas-examples:
+    name: "🔎 Check JSON Schemas inline examples"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "📥 Source checkout"
+        uses: actions/checkout@v4
+      - name: "➕ Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+          cache-dependency-path: scripts/requirements.txt
+      - name: "➕ Install dependencies"
+        run: |
+          pip install -r scripts/requirements.txt
+      - name: "🔎 Run validator"
+        run: |
+          python scripts/check-json-schemas.py
+
   calculate-baseurl:
     name: "⚙️ Calculate baseURL for later jobs"
     runs-on: ubuntu-latest
@@ -68,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:
@@ -81,9 +112,9 @@ jobs:
     needs: [calculate-baseurl]
     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'
@@ -93,22 +124,35 @@ jobs:
           pip install -r scripts/requirements.txt
       - name: "📦 Asset creation"
         run: |
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            export RELEASE="${GITHUB_REF/refs\/tags\//}"
+          else
+            export RELEASE="unstable"
+          fi
           # The output path matches the final deployment path at spec.matrix.org
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api application-service \
+            -r "$RELEASE" \
             -o spec/application-service-api/api.json
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api client-server \
+            -r "$RELEASE" \
             -o spec/client-server-api/api.json
-          scripts/dump-swagger.py \
+          scripts/dump-openapi.py \
             --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
             --api push-gateway \
+            -r "$RELEASE" \
             -o spec/push-gateway-api/api.json
+          scripts/dump-openapi.py \
+              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
+              --api server-server \
+              -r "$RELEASE" \
+              -o spec/server-server-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: openapi-artifact
           path: openapi.tar.gz
@@ -120,15 +164,17 @@ 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'
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
         run: ./scripts/generate-changelog.sh vUNSTABLE
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: changelog-artifact
           path: content/changelog/vUNSTABLE.md
@@ -141,23 +187,23 @@ jobs:
     if: ${{ always() }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.93.3'
+          hugo-version: '0.113.0'
           extended: true
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           npm i
           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
@@ -168,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@v2
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -178,7 +224,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: spec-artifact
           path: spec.tar.gz
@@ -189,10 +235,10 @@ jobs:
     needs: [calculate-baseurl, build-spec]
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: "📥 Fetch built spec"
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v4
         with:
           name: spec-artifact
 
@@ -218,16 +264,17 @@ jobs:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: '14'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
+        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@v2
+        uses: actions/checkout@v4
       - name: "⚙️ npm"
         run: |
           npm i
@@ -239,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@v2
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -249,7 +296,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec-historical.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v2
+        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@af92a8455a59214b7b932932f2662fdefbd78126 # v2.15.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
-        # v1.2.2
-        uses: nwtgck/actions-netlify@f517512ae75beec8896aa7b027c1c72f01816200
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"

.github/workflows/release.yaml

@@ -0,0 +1,42 @@
+name: Release packages
+on:
+  release:
+    types: [published]
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+jobs:
+  # Releases to npm after bumping the package.json version from 0.0.0 to $TAG.0 as the tags only contain MAJOR.MINOR
+  npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    if: github.event.release.prerelease == false
+    defaults:
+      run:
+        working-directory: packages/npm
+    steps:
+      - name: 🧮 Checkout code
+        uses: actions/checkout@v4
+
+      - name: 🔧 Yarn cache
+        uses: actions/setup-node@v4
+        with:
+          cache: "yarn"
+          cache-dependency-path: packages/npm/yarn.lock
+          registry-url: "https://registry.npmjs.org"
+
+      - 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 --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@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1
+        with:
+          token: ${{ secrets.NPM_TOKEN }}
+          package: packages/npm
+          access: public
+          ignore-scripts: false

.github/workflows/spell-check.yaml

@@ -11,9 +11,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Actions Repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@9be36f97fdbe645ee9a12449fb13aca856c2516a
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
       with:
-        config: ${{github.workspace}}/.github/_typos.toml
+        config: ${{github.workspace}}/.github/_typos.toml

.gitignore

@@ -2,7 +2,7 @@ node_modules
 /data/msc
 /env*
 /resources
-/scripts/swagger
+/scripts/openapi
 /scripts/tmp
 /hugo-config.toml
 /public

.gitmodules

@@ -1,4 +0,0 @@
-[submodule "themes/docsy"]
-	path = themes/docsy
-	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

@@ -22,7 +22,7 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener
 
 * `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as
   [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and
-  parse them. This is also where our Swagger/OpenAPI definitions and schemas are.
+  parse them. This is also where our OpenAPI definitions and schemas are.
 
 * `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of
   a page: for example, whether it has header, footer, sidebar, and so on.
@@ -52,6 +52,7 @@ Additionally, the following directories may be of interest:
 * `/data-definitions`: Bits of structured data consumable by Matrix implementations.
 * `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
 * `/scripts`: Various scripts for generating the spec and validating its contents.
+* `/packages`: Various packages for shipping spec files like OpenAPI bindings and data definitions.
 
 ## Authoring changes to the spec
 
@@ -60,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
@@ -86,13 +86,13 @@ steps for authoring changes to the specification and instead of `hugo serve` run
 spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"`
 to the `hugo -d "spec"` command.
 
-For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
-and finally `python ./scripts/dump-swagger.py` to generate it to `./scripts/swagger/api-docs.json`. To make use of the generated file,
+For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
+and finally `python ./scripts/dump-openapi.py` to generate it to `./scripts/openapi/api-docs.json`. To make use of the generated file,
 there are a number of options:
 
-* You can open `./scripts/swagger-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
-* You can run a local HTTP server by running `./scripts/swagger-http-server.py`, and then view the documentation by
-  opening `./scripts/swagger-preview.html` in your browser.
+* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
+* You can run a local HTTP server by running `./scripts/openapi-http-server.py`, and then view the documentation by
+  opening `./scripts/openapi-preview.html` in your browser.
 
 ## Issue tracking
 

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 {
@@ -68,9 +72,8 @@ Custom SCSS for the Matrix spec
     margin-top: 1rem;
   }
 
-  &>.td-sidebar-nav__section > li > a.td-sidebar-link {
-      font-weight: $font-weight-bold;
-      font-size: 1.3rem;
+  .td-sidebar-nav__section .ul-1 ul {
+    padding-left: 0;
   }
 
   /* This is to make the width of the items that have sub-items (like room versions)
@@ -79,12 +82,20 @@ Custom SCSS for the Matrix spec
     padding-right: 0 !important;
   }
 
-  a.indent-1 {
+  .ul-1 > li > a {
     padding-left: 1rem !important;
   }
 
-  a.indent-2 {
-    padding-left: 2rem;
+  .ul-2 > li > a {
+    padding-left: 2rem !important;
+  }
+
+  a.td-sidebar-link.tree-root {
+    color: $gray-800;
+    font-weight: $font-weight-bold;
+    font-size: 1.3rem;
+    margin-bottom: 0;
+    border-bottom: none;
   }
 
   a, a.td-sidebar-link {
@@ -103,12 +114,11 @@ Custom SCSS for the Matrix spec
 
     &.active, &active:hover {
       background-color: $secondary-background;
-      font-weight: $font-weight-normal;
     }
   }
 }
 
-@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 */
@@ -165,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 * {
@@ -286,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;
@@ -340,23 +357,41 @@ footer {
   }
 
   p code, table code {
-    background-color: inherit;
+    background-color: transparent;
   }
 
   table {
-    /* Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
-     * tables with a "display" property of "block".
-     *
-     * However, for "table-layout: fixed" to be effective, an element must have a
-     * "display" property of "table".
-     *
-     * Thus, we override the "display" property here. This may no longer be necessary once
-     * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
-     * For more details, see
-     * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
-    display: table;
-    table-layout: fixed;
-    width: 100%;
+    @media (max-width: 800px) {
+      /* Docsy by default applies `overflow-x: auto;` to tables, which
+       * results in annoying horizontal scrolling on mobile, so we instead
+       * switch to a fixed table layout on a narrow browser width.
+       * (On a wider width the default auto table-layout provides better readability.)
+       *
+       * Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
+       * tables with a "display" property of "block".
+       * However, for "table-layout: fixed" to be effective, an element must have a
+       * "display" property of "table".
+       *
+       * Thus, we override the "display" property here. This may no longer be necessary once
+       * Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
+       * For more details, see
+       * https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
+      display: table;
+      table-layout: fixed;
+      width: 100%;
+
+      .col-name, .col-type, .col-status {
+        width: 25%;
+      }
+
+      .col-description {
+        width: 50%;
+      }
+
+      .col-status-description {
+        width: 75%;
+      }
+    }
 
     // add some space between two tables when they are right next to each other
     & + table {
@@ -372,9 +407,10 @@ footer {
 
     th, td, caption {
       padding: 1rem;
+      border-top: 1px $table-border-color solid;
     }
 
-    &.object-table, &.response-table {
+    &.object-table, &.response-table, &.content-type-table {
         border: 1px $table-border-color solid;
 
         caption {
@@ -384,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};
         }
     }
 
@@ -404,18 +438,30 @@ footer {
       width: 15rem;
     }
 
-    .col-name, .col-type, .col-status {
-      width: 25%;
-    }
+    /* 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;
+      }
 
-    .col-description {
-      width: 50%;
-    }
+      /* 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;
+      }
 
-    .col-status-description {
-      width: 75%;
+      /* 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 {
@@ -460,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;
@@ -506,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/pyproject.toml

@@ -1,39 +1,66 @@
 [tool.towncrier]
     version = "unused"
-    filename = "../rendered.md"
-    issue_format = "[#{issue}](https://github.com/matrix-org/matrix-spec/issues/{issue})"
-    title_format = "### {name}"  # Matches rendered spec, even if awkward
-    underlines = "   "  # 3 spaces intentionally to hide RST headings
-
-    # Note: The names below have the <strong> tag built-in so the rendered spec *and* the generated
-    # changelog can benefit from sane headings.
+    filename = "rendered.md"
+    template = "template.md.jinja"
 
     [[tool.towncrier.type]]
         directory = "breaking"
-        name = "<strong>Breaking Changes</strong>"
+        name = "Breaking Changes"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "deprecation"
-        name = "<strong>Deprecations</strong>"
+        name = "Deprecations"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "new"
-        name = "<strong>New Endpoints</strong>"
+        name = "New Endpoints"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "removal"
-        name = "<strong>Removed Endpoints</strong>"
+        name = "Removed Endpoints"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "feature"
-        name = "<strong>Backwards Compatible Changes</strong>"
+        name = "Backwards Compatible Changes"
         showcontent = true
 
     [[tool.towncrier.type]]
         directory = "clarification"
-        name = "<strong>Spec Clarifications</strong>"
+        name = "Spec Clarifications"
         showcontent = true
+
+    [[tool.towncrier.section]]
+        name = "Client-Server API"
+        path = "client_server"
+
+    [[tool.towncrier.section]]
+        name = "Server-Server API"
+        path = "server_server"
+    
+    [[tool.towncrier.section]]
+        name = "Application Service API"
+        path = "application_service"
+
+    [[tool.towncrier.section]]
+        name = "Identity Service API"
+        path = "identity_service"
+    
+    [[tool.towncrier.section]]
+        name = "Push Gateway API"
+        path = "push_gateway"
+    
+    [[tool.towncrier.section]]
+        name = "Room Versions"
+        path = "room_versions"
+    
+    [[tool.towncrier.section]]
+        name = "Appendices"
+        path = "appendices"
+
+    [[tool.towncrier.section]]
+        name = "Internal Changes/Tooling"
+        path = "internal"

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.

changelogs/template.md.jinja

@@ -0,0 +1,24 @@
+{% for section_name, section in sections.items() %}
+{% if section_name %}
+
+### {{section_name}}
+{% endif %}
+
+{% if section %}
+{% for category, val in definitions.items() if category in section %}
+**{{ definitions[category]['name'] }}**
+
+{% for content, issues in section[category].items() %}
+- {{ content }} (
+{%- for issue in issues %}
+[{{issue}}](https://github.com/matrix-org/matrix-spec/issues/{{issue|trim('#')}}){% if not loop.last %}, {% endif %}
+{%- endfor %}
+)
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+{% endif %}
+{% endfor %}

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 = "7"
-release_date = "May 25, 2023"
+# major = "1"
+# minor = "10"
+# release_date = "March 22, 2024"
 
 # User interface configuration
 [params.ui]
@@ -62,6 +75,10 @@ release_date = "May 25, 2023"
 footer_about_disable = false
 # Collapse HTTP API and event <details> elements
 rendered_data_collapsed = false
+# Hide the search entry in the sidebar
+sidebar_search_disable = true
+# Only show the current page's ancestors, siblings and direct descendants in the sidebar menu
+sidebar_menu_compact = true
 
 [params.links]
 # End user relevant links. These will show up on left side of footer and in the community page if you have one.
@@ -107,3 +124,13 @@ rendered_data_collapsed = false
     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/_index.md

@@ -419,9 +419,16 @@ into the `m.` namespace.
 
 ### Timestamps
 
-Unless otherwise stated, timestamps are measured as milliseconds since
-the Unix epoch. Throughout the specification this may be referred to as
-POSIX, Unix, or just "time in milliseconds".
+Unless otherwise stated, timestamps are the number of milliseconds
+elapsed since the unix epoch (1970-01-01 00:00:00 UTC), but not counting
+leap seconds, so that each day is precisely 86,400,000 milliseconds.
+
+This means that timestamps can repeat during leap seconds. Most
+programming languages provide timestamps in that format natively, e.g.
+[ECMAScript](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-time-values-and-time-range).
+Throughout the specification this may be referred to as POSIX,
+[Unix](https://en.wikipedia.org/wiki/Unix_time), or just "time in
+milliseconds".
 
 ## Specification Versions
 

content/appendices.md

@@ -90,7 +90,8 @@ To ensure that all implementations use the same JSON encoding we define
 We define this encoding for a value to be the shortest
 UTF-8 JSON encoding with dictionary keys lexicographically sorted by
 Unicode codepoint. Numbers in the JSON must be integers in the range
-`[-(2**53)+1, (2**53)-1]`.
+`[-(2**53)+1, (2**53)-1]`, represented without exponents or decimal
+places, and negative zero `-0` MUST NOT appear.
 
 We pick UTF-8 as the encoding as it should be available to all platforms
 and JSON received from the network is likely to be already encoded using
@@ -135,12 +136,12 @@ removing insignificant whitespace, fractions, exponents and redundant
 character escapes.
 
     value     = false / null / true / object / array / number / string
-    false     = %x66.61.6c.73.65
-    null      = %x6e.75.6c.6c
+    false     = %x66.61.6C.73.65
+    null      = %x6E.75.6C.6C
     true      = %x74.72.75.65
-    object    = %x7B [ member *( %x2C member ) ] %7D
+    object    = %x7B [ member *( %x2C member ) ] %x7D
     member    = string %x3A value
-    array     = %x5B [ value *( %x2C value ) ] %5B
+    array     = %x5B [ value *( %x2C value ) ] %x5D
     number    = [ %x2D ] int
     int       = %x30 / ( %x31-39 *digit )
     digit     = %x30-39
@@ -304,6 +305,21 @@ The following canonical JSON should be produced:
 {"a":null}
 ```
 
+Given the following JSON object:
+
+```json
+{
+    "a": -0,
+    "b": 1e10
+}
+```
+
+The following canonical JSON should be produced:
+
+```json
+{"a":0,"b":10000000000}
+```
+
 ### Signing Details
 
 JSON is signed by encoding the JSON object without `signatures` or keys
@@ -524,6 +540,8 @@ be represented with a `domain` component under some conditions - see the
 
 #### User Identifiers
 
+{{% changed-in v="1.8" %}}
+
 Users within Matrix are uniquely identified by their Matrix user ID. The
 user ID is namespaced to the homeserver which allocated the account and
 has the form:
@@ -532,7 +550,7 @@ has the form:
 
 The `localpart` of a user ID is an opaque identifier for that user. It
 MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`,
-`.`, `_`, `=`, `-`, and `/`.
+`.`, `_`, `=`, `-`, `/`, and `+`.
 
 The `domain` of a user ID is the [server name](#server-name) of the
 homeserver which allocated the account.
@@ -546,7 +564,7 @@ The complete grammar for a legal user ID is:
     user_id_localpart = 1*user_id_char
     user_id_char = DIGIT
                  / %x61-7A                   ; a-z
-                 / "-" / "." / "=" / "_" / "/"
+                 / "-" / "." / "=" / "_" / "/" / "+"
 
 {{% boxes/rationale %}}
 A number of factors were considered when defining the allowable
@@ -903,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/changelog/v1.8.md

@@ -0,0 +1,122 @@
+---
+date: 2023-08-23T09:23:53-06:00
+---
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    v1.8  = Replaced by the version number (eg: v1.2)
+    August 23, 2023     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## v1.8
+
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.8">https://github.com/matrix-org/matrix-spec/tree/v1.8</a></td>
+<tr><th>Release date</th><td>August 23, 2023</td>
+</table>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
+
+### Client-Server API
+
+**Backwards Compatible Changes**
+
+- Require callers to be joined to the room to report its events, as per [MSC2249](https://github.com/matrix-org/matrix-spec-proposals/pull/2249). ([#1517](https://github.com/matrix-org/matrix-spec/issues/1517))
+
+**Spec Clarifications**
+
+- Fix missing `type` property in the JSON schema definition of the `m.reaction` event.  Contributed by @chebureki. ([#1552](https://github.com/matrix-org/matrix-spec/issues/1552))
+- Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563))
+- Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas. ([#1564](https://github.com/matrix-org/matrix-spec/issues/1564))
+- Fix broken header formatting. Contributed by @midnightveil. ([#1578](https://github.com/matrix-org/matrix-spec/issues/1578))
+- Render binary request and response bodies. ([#1579](https://github.com/matrix-org/matrix-spec/issues/1579))
+- Fix description of MAC calculation in SAS verification. ([#1590](https://github.com/matrix-org/matrix-spec/issues/1590))
+- Update link to SAS emoji definition data. ([#1593](https://github.com/matrix-org/matrix-spec/issues/1593))
+- Fix various typos throughout the specification. ([#1597](https://github.com/matrix-org/matrix-spec/issues/1597))
+
+
+### Server-Server API
+
+**Deprecations**
+
+- Deprecate `matrix` SRV lookup steps during server discovery, as per [MSC4040](https://github.com/matrix-org/matrix-spec-proposals/pull/4040). ([#1624](https://github.com/matrix-org/matrix-spec/issues/1624))
+
+**Backwards Compatible Changes**
+
+- Add `matrix-fed` SRV lookup steps to server discovery, as per [MSC4040](https://github.com/matrix-org/matrix-spec-proposals/pull/4040). ([#1624](https://github.com/matrix-org/matrix-spec/issues/1624))
+
+**Spec Clarifications**
+
+- Document why `/state_ids` can respond with a 404. ([#1521](https://github.com/matrix-org/matrix-spec/issues/1521))
+- Fix response definition for `POST /_matrix/federation/v1/user/keys/claim`. ([#1559](https://github.com/matrix-org/matrix-spec/issues/1559))
+- Fix examples in server keys definition. ([#1560](https://github.com/matrix-org/matrix-spec/issues/1560))
+- Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563))
+- Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas. ([#1564](https://github.com/matrix-org/matrix-spec/issues/1564))
+- Fix broken header formatting. Contributed by @midnightveil. ([#1578](https://github.com/matrix-org/matrix-spec/issues/1578))
+- Remove spurious mention of a "default port" with respect to SRV record lookup. ([#1615](https://github.com/matrix-org/matrix-spec/issues/1615))
+- Switch to ordered list for server name resolution steps. ([#1623](https://github.com/matrix-org/matrix-spec/issues/1623))
+
+
+### Application Service API
+
+**Spec Clarifications**
+
+- Fix type of custom `fields` in thirdparty lookup queries. ([#1584](https://github.com/matrix-org/matrix-spec/issues/1584))
+
+
+### Identity Service API
+
+**Spec Clarifications**
+
+- Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563))
+
+
+### Push Gateway API
+
+No significant changes.
+
+
+### Room Versions
+
+**Backwards Compatible Changes**
+
+- Add room version 11 as per [MSC3820](https://github.com/matrix-org/matrix-spec-proposals/pull/3820). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Move `redacts` from top level to `content` on `m.room.redaction` events in room version 11, as per [MSC2174](https://github.com/matrix-org/matrix-spec-proposals/pull/2174). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Remove `creator` from `m.room.creator` events in room version 11, as per [MSC2175](https://github.com/matrix-org/matrix-spec-proposals/pull/2175). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Remove remaining usage of `origin` from events in room version 11, as per [MSC3989](https://github.com/matrix-org/matrix-spec-proposals/pull/3989). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+- Update the redaction rules in room version 11, as per [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) and [MSC3821](https://github.com/matrix-org/matrix-spec-proposals/pull/3821). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604))
+
+
+### Appendices
+
+**Backwards Compatible Changes**
+
+- Allow `+` in Matrix IDs, as per [MSC4009](https://github.com/matrix-org/matrix-spec-proposals/pull/4009). ([#1583](https://github.com/matrix-org/matrix-spec/issues/1583))
+
+**Spec Clarifications**
+
+- Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten. ([#1573](https://github.com/matrix-org/matrix-spec/issues/1573))
+
+
+### Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Upgrade Swagger data to OpenAPI 3.1. ([#1310](https://github.com/matrix-org/matrix-spec/issues/1310))
+- Create `@matrix-org/spec` npm package to ship the SAS Emoji data definitions & translations. ([#1620](https://github.com/matrix-org/matrix-spec/issues/1620))
+
+**Spec Clarifications**
+
+- Update the CI to validate the file extension of changelog entries. ([#1542](https://github.com/matrix-org/matrix-spec/issues/1542))
+- Disclosure sections now only display their title when collapsed. ([#1549](https://github.com/matrix-org/matrix-spec/issues/1549))
+- Fix the sidebar in recent versions of Hugo. ([#1551](https://github.com/matrix-org/matrix-spec/issues/1551))
+- Bump jsonschema to validate JSON Schemas against Draft 2020-12. ([#1556](https://github.com/matrix-org/matrix-spec/issues/1556))
+- Use Redocly CLI to validate OpenAPI definitions. ([#1558](https://github.com/matrix-org/matrix-spec/issues/1558))
+- Use tag name as the OpenAPI definition version. ([#1561](https://github.com/matrix-org/matrix-spec/issues/1561))
+- Make sure version in `x-changedInMatrixVersion` is a string. ([#1562](https://github.com/matrix-org/matrix-spec/issues/1562))
+- Clarify usage of ABNF for grammar in the documentation style guide. ([#1582](https://github.com/matrix-org/matrix-spec/issues/1582))
+- Remove unnecessary `oneOf`s in JSON schemas. ([#1585](https://github.com/matrix-org/matrix-spec/issues/1585))
+- Update the version of Hugo used to render the spec to v0.113.0. ([#1591](https://github.com/matrix-org/matrix-spec/issues/1591))
+- Fix rendered changelog with new version of towncrier. ([#1598](https://github.com/matrix-org/matrix-spec/issues/1598))
+- Improve the layout of tables on desktop displays. Contributed by Martin Fischer. ([#1601](https://github.com/matrix-org/matrix-spec/issues/1601))

content/changelog/v1.9.md

@@ -0,0 +1,93 @@
+---
+date: 2023-11-29T10:04:26-07:00
+---
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    v1.9  = Replaced by the version number (eg: v1.2)
+    November 29, 2023     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## v1.9
+
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.9">https://github.com/matrix-org/matrix-spec/tree/v1.9</a></td>
+<tr><th>Release date</th><td>November 29, 2023</td>
+</table>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
+
+### Client-Server API
+
+**Backwards Compatible Changes**
+
+- Add the `m.rule.suppress_edits` default push rule, as per [MSC3958](https://github.com/matrix-org/matrix-spec-proposals/pull/3958). ([#1617](https://github.com/matrix-org/matrix-spec/issues/1617))
+
+**Spec Clarifications**
+
+- Fix `m.call.negotiate` schema and example. ([#1546](https://github.com/matrix-org/matrix-spec/issues/1546))
+- Clarify that the `via` property is required for `m.space.parent` and `m.space.child` as per [MSC1772](https://github.com/matrix-org/matrix-spec-proposals/pull/1772). Contributed by @PaarthShah. ([#1618](https://github.com/matrix-org/matrix-spec/issues/1618))
+- Add a note to the `/publicRooms` API that the server name is case sensitive. ([#1638](https://github.com/matrix-org/matrix-spec/issues/1638))
+- Clarify that an `m.room.name` event with an absent `name` field is not expected behavior. ([#1639](https://github.com/matrix-org/matrix-spec/issues/1639))
+- Fix schemas used for account data and presence events in `GET /initialSync`. ([#1647](https://github.com/matrix-org/matrix-spec/issues/1647))
+- Fix various typos throughout the specification. ([#1658](https://github.com/matrix-org/matrix-spec/issues/1658), [#1661](https://github.com/matrix-org/matrix-spec/issues/1661), [#1665](https://github.com/matrix-org/matrix-spec/issues/1665))
+- Fix `.m.rule.suppress_notices` push rule not being valid JSON. ([#1671](https://github.com/matrix-org/matrix-spec/issues/1671))
+- Add missing properties for `event_property_is` and `event_property_contains` push conditions to `PushConditions` object. ([#1673](https://github.com/matrix-org/matrix-spec/issues/1673))
+- Indicate that fallback keys should have a `fallback` property set to `true`. ([#1676](https://github.com/matrix-org/matrix-spec/issues/1676))
+- Clarify that thread roots are not considered within the thread. ([#1677](https://github.com/matrix-org/matrix-spec/issues/1677))
+
+
+### Server-Server API
+
+**Spec Clarifications**
+
+- Fix schema of `m.receipt` EDU. ([#1636](https://github.com/matrix-org/matrix-spec/issues/1636))
+- Fix various typos throughout the specification. ([#1661](https://github.com/matrix-org/matrix-spec/issues/1661))
+- Clarify that federation requests for non-local users are invalid. ([#1672](https://github.com/matrix-org/matrix-spec/issues/1672))
+
+
+### Application Service API
+
+No significant changes.
+
+
+### Identity Service API
+
+No significant changes.
+
+
+### Push Gateway API
+
+No significant changes.
+
+
+### Room Versions
+
+No significant changes.
+
+
+### Appendices
+
+**Spec Clarifications**
+
+- Clarify timestamp specification with respect to leap seconds. ([#1627](https://github.com/matrix-org/matrix-spec/issues/1627))
+- Fix various typos throughout the specification. ([#1652](https://github.com/matrix-org/matrix-spec/issues/1652))
+
+
+### Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Add more CI checks for OpenAPI definitions and JSON Schemas. ([#1656](https://github.com/matrix-org/matrix-spec/issues/1656))
+- Generate server-server OpenAPI definition. ([#1657](https://github.com/matrix-org/matrix-spec/issues/1657))
+
+**Spec Clarifications**
+
+- Replace all mentions of Swagger by OpenAPI. ([#1633](https://github.com/matrix-org/matrix-spec/issues/1633))
+- Fix enum types in JSON schemas. ([#1634](https://github.com/matrix-org/matrix-spec/issues/1634))
+- Fix schema of `m.mentions` object. ([#1635](https://github.com/matrix-org/matrix-spec/issues/1635))
+- Fix rendering of `m.receipt` event in Client-Server API. ([#1637](https://github.com/matrix-org/matrix-spec/issues/1637))
+- Remove required `fieldname` in appservice Protocol definition. ([#1646](https://github.com/matrix-org/matrix-spec/issues/1646))
+- Fix github action workflow responsible for releasing of @matrix-org/spec package. ([#1648](https://github.com/matrix-org/matrix-spec/issues/1648))
+- Upgrade GitHub actions. ([#1660](https://github.com/matrix-org/matrix-spec/issues/1660))

content/client-server-api/_index.md

@@ -62,7 +62,7 @@ error message e.g.  `M_FORBIDDEN`. Error codes should have their namespace
 first in ALL CAPS, followed by a single `_`. For example, if there was a custom
 namespace `com.mydomain.here`, and a `FORBIDDEN` code, the error code should
 look like `COM.MYDOMAIN.HERE_FORBIDDEN`. Error codes defined by this
-specification should start `M_`.
+specification should start with `M_`.
 
 Some `errcode`s define additional keys which should be present in the error
 response object, but the keys `error` and `errcode` MUST always be present.
@@ -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

@@ -77,6 +77,7 @@ algorithm is represented by an object with the following properties:
 |------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
 | key        | string     | **Required.** The unpadded Base64-encoded 32-byte Curve25519 public key.                                                                          |
 | signatures | Signatures | **Required.** Signatures of the key object. The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). |
+| fallback   | boolean    | Indicates whether this is a [fallback key](#one-time-and-fallback-keys). Defaults to `false`.                                                     |
 
 Example:
 
@@ -134,8 +135,7 @@ are offline/unable to upload additional keys, though sessions started using
 fallback keys could be vulnerable to replay attacks.
 {{% /boxes/warning %}}
 
-Devices will be informed, [via
-`/sync`](#a-namee2e-extensions-to-sync-extensions-to-sync), about the number of
+Devices will be informed, [via `/sync`](#e2e-extensions-to-sync), about the number of
 one-time keys remaining that can be claimed, as well as whether the fallback
 keys have been used. The device can thus ensure that, while it is online, there
 is a sufficient supply of one-time keys available, and that the fallback keys
@@ -151,7 +151,9 @@ JSON](/appendices/#signing-json).
 
 One-time and fallback keys are also uploaded to the homeserver using the
 [`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) API. New
-one-time and fallback keys are uploaded as needed.
+one-time and fallback keys are uploaded as needed.  Fallback keys for key
+algorithms whose format is a signed JSON object should contain a property named
+`fallback` with a value of `true`.
 
 Devices must store the private part of each key they upload. They can
 discard the private part of a one-time key when they receive a message
@@ -306,7 +308,7 @@ properties.
 | key       | JWK              | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.       |
 | iv        | string           | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.    |
 | hashes    | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. |
-| v         | string           | **Required.** Version of the encrypted attachments protocol. Must be `v2`.                     |
+| v         | string           | **Required.** Version of the encrypted attachment's protocol. Must be `v2`.                    |
 
 `JWK`
 
@@ -658,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
@@ -670,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.
 
@@ -777,33 +781,37 @@ The method used to calculate these MACs depends upon the value of the
 message. All current implementations should use the `hkdf-hmac-sha256.v2` method which is
 defined as follows:
 
-The MAC used is HMAC as defined in [RFC
-5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash
-function. The shared secret is supplied as the input keying material. No salt
-is used, and in the info parameter is the concatenation of:
-
--   The string `MATRIX_KEY_VERIFICATION_MAC`.
--   The Matrix ID of the user whose key is being MAC-ed.
--   The Device ID of the device sending the MAC.
--   The Matrix ID of the other user.
--   The Device ID of the device receiving the MAC.
--   The `transaction_id` being used.
--   The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
-    item being MAC-ed is the list of key IDs.
-
-If a key is being MACed, the MAC is performed on the public key as encoded
-according to the [key algorithm](#key-algorithms).  For example, for `ed25519`
-keys, it is the unpadded base64-encoded key.
-
-If the key list is being MACed, the list is sorted lexicographically and
-comma-separated with no extra whitespace added, with each key written in the
-form `{algorithm}:{keyId}`. For example, the key list could look like:
-`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can
-reconstruct the list from the names in the `mac` property of the
-`m.key.verification.mac` message and ensure that no keys were added or removed.
-
-The MAC values are base64-encoded and sent in a
-[`m.key.verification.mac`](#mkeyverificationmac) message.
+1. An HMAC key is generated using HKDF, as defined in [RFC
+   5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash
+   function. The shared secret is supplied as the input keying material. No salt
+   is used, and in the info parameter is the concatenation of:
+
+   -   The string `MATRIX_KEY_VERIFICATION_MAC`.
+   -   The Matrix ID of the user whose key is being MAC-ed.
+   -   The Device ID of the device sending the MAC.
+   -   The Matrix ID of the other user.
+   -   The Device ID of the device receiving the MAC.
+   -   The `transaction_id` being used.
+   -   The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
+       item being MAC-ed is the list of key IDs.
+
+2. A MAC is then generated using HMAC as defined in [RFC
+   2104](https://tools.ietf.org/html/rfc2104) with the key generated above and
+   using SHA-256 as the hash function.
+
+   If a key is being MACed, the MAC is performed on the public key as encoded
+   according to the [key algorithm](#key-algorithms).  For example, for `ed25519`
+   keys, it is the unpadded base64-encoded key.
+
+   If the key list is being MACed, the list is sorted lexicographically and
+   comma-separated with no extra whitespace added, with each key written in the
+   form `{algorithm}:{keyId}`. For example, the key list could look like:
+   `ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can
+   reconstruct the list from the names in the `mac` property of the
+   `m.key.verification.mac` message and ensure that no keys were added or removed.
+
+3. The MAC values are base64-encoded and sent in a
+   [`m.key.verification.mac`](#mkeyverificationmac) message.
 
 {{% boxes/note %}}
 The MAC method `hkdf-hmac-sha256` used an incorrect base64 encoding, due to a
@@ -830,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`,
@@ -892,7 +900,7 @@ following table to get the corresponding emoji:
 
 {{% boxes/note %}}
 This table is available as JSON at
-<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json>
+<https://github.com/matrix-org/matrix-spec/blob/main/data-definitions/sas-emoji.json>.
 {{% /boxes/note %}}
 
 {{% boxes/rationale %}}
@@ -1263,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
@@ -1287,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
@@ -1304,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
-
-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:
+###### Decryption key
 
-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.
+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.
 
-When reading in a recovery key, clients must disregard whitespace, and
-perform the reverse of steps 1 through 3.
+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).
 
-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`
 
@@ -1358,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" %}}
 
@@ -1699,7 +1708,7 @@ When a client is updating a Megolm session in its store, the client MUST ensure:
 
 {{% http-api spec="client-server" api="keys" %}}
 
-##### <a name="e2e-extensions-to-sync"> Extensions to /sync
+##### Extensions to /sync {#e2e-extensions-to-sync}
 
 This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientv3sync)  response,
 as specified below. The server need only populate this property for an
@@ -1762,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/event_annotations.md

@@ -14,7 +14,7 @@ event with the corresponding emoji (👍). Another potential usage is to allow
 bots to send an event indicating the success or failure of a command.
 
 Along with the normal properties `event_id` and `rel_type`, an `m.relates_to`
-property with `rel_type: m.annotion` should contain a `key` that indicates the
+property with `rel_type: m.annotation` should contain a `key` that indicates the
 annotation being applied. For example, when reacting with emojis, the key
 contains the emoji being used.
 

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/mentions.md

@@ -13,6 +13,20 @@ the event to reference the entity being mentioned.
 
 {{% definition path="api/client-server/definitions/m.mentions" %}}
 
+An event's content will then look like this:
+
+```json
+{
+    "body": "Hello Alice!",
+    "msgtype": "m.text",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
+    "m.mentions": {
+        "user_ids": ["@alice:example.org"]
+    }
+}
+```
+
 Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
 [`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
 Users should not add their own Matrix ID to the `m.mentions` property as outgoing

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

@@ -454,7 +454,7 @@ Definition:
         {
             "kind": "event_match",
             "key": "content.msgtype",
-            "pattern": "m.notice",
+            "pattern": "m.notice"
         }
     ],
     "actions": []
@@ -750,6 +750,30 @@ Definition:
 }
 ```
 
+**`.m.rule.suppress_edits`**
+
+{{% added-in v="1.9" %}}
+
+Suppresses notifications related to [event replacements](#event-replacements).
+
+Definition:
+
+```json
+{
+    "rule_id": ".m.rule.suppress_edits",
+    "default": true,
+    "enabled": true,
+    "conditions": [
+        {
+            "kind": "event_property_is",
+            "key": "content.m\\.relates_to.rel_type",
+            "value": "m.replace"
+        }
+    ],
+    "actions": []
+}
+```
+
 ##### Default Content Rules
 
 <a id="_m_rule_contains_user_name"/> **`.m.rule.contains_user_name`**
@@ -1046,16 +1070,16 @@ ahead), however if the `m.read.private` receipt were to be updated to
 event D then the user has read up to D (the `m.read` receipt is now
 behind the `m.read.private` receipt).
 
-{{< added-in v="1.4" >}} When handling threaded read receipts, the server
-is to partition the notification count to each thread (with the main timeline
-being its own thread). To determine if an event is part of a thread the
-server follows the [event relationship](#forming-relationships-between-events)
-until it finds a thread root (as specified by the [threading module](#threading)),
-however it is not recommended that the server traverse infinitely. Instead,
-implementations are encouraged to do a maximum of 3 hops to find a thread
-before deciding that the event does not belong to a thread. This is primarily
-to ensure that future events, like `m.reaction`, are correctly considered
-"part of" a given thread.
+{{< added-in v="1.4" >}} When handling threaded read receipts, the server is to
+partition the notification count to each thread (with the main timeline being
+its own thread). To determine if an event is part of a thread the server follows
+the [event relationship](#forming-relationships-between-events) until it finds a
+thread root via an `m.thread` relation (as specified by the [threading
+module](#threading)), however it is not recommended that the server traverse
+infinitely. Instead, implementations are encouraged to do a maximum of 3 hops to
+find a thread before deciding that the event does not belong to a thread. This
+is primarily to ensure that future events, like `m.reaction`, are correctly
+considered "part of" a given thread.
 
 #### Server behaviour
 

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

@@ -137,16 +137,20 @@ either a thread root's event ID or `main` for the main timeline.
 
 Threading introduces a concept of multiple conversations being held in the same
 room and thus deserve their own read receipts and notification counts. An event is
-considered to be "in a thread" if it meets any of the following criteria:
-* It has a `rel_type` of `m.thread`.
-* It has child events with a `rel_type` of `m.thread` (in which case it'd be the
-  thread root).
-* Following the event relationships, it has a parent event which qualifies for
-  one of the above. Implementations should not recurse infinitely, though: a
-  maximum of 3 hops is recommended to cover indirect relationships.
+considered to be "in a thread" if:
 
-Events not in a thread but still in the room are considered to be part of the
-"main timeline", or a special thread with an ID of `main`.
+* It has a `rel_type` of `m.thread`, or
+* Following the event relationships, it has a parent event which references
+  the thread root with a `rel_type` of `m.thread`. Implementations should
+  not recurse infinitely, though: a maximum of 3 hops is recommended to
+  cover indirect relationships.
+
+Events not in a thread but still in the room are considered to be in the "main
+timeline". When referring to the main timeline as a thread (e.g. in receipts
+and notifications counts) a special thread ID of `main` is used.
+
+Thread roots are considered to be in the main timeline, as are events that are
+related to a thread root via non-thread relations.
 
 The following is an example DAG for a room, with dotted lines showing event
 relationships and solid lines showing topological ordering.
@@ -204,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/report_content.md

@@ -18,3 +18,7 @@ Servers are free to handle the reported content however they desire.
 This may be a dedicated room to alert server administrators to the
 reported content or some other mechanism for notifying the appropriate
 people.
+
+{{< changed-in v="1.8" >}} The server MUST verify that the user 
+reporting the event is currently joined to the room the event is 
+in before accepting a report.

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

@@ -12,11 +12,13 @@ as by providing some context to what is going on in the thread but keeping the f
 history behind a disclosure.
 
 Threads are established using a `rel_type` of `m.thread` and reference the
-*thread root* (the first event in a thread). 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.
+*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 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/_index.md

@@ -36,11 +36,11 @@ Alternatively, consider flipping the column/row organization to be features
 up top and versions on the left.
 -->
 
-| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
-|-------------------|---|---|---|---|---|---|---|---|---|----|
-| **Knocking**      | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ |
-| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ |
-| **`knock_restricted` join rule** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ |
+| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
+|-------------------|---|---|---|---|---|---|---|---|---|----|----|
+| **Knocking**      | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ |
+| **`knock_restricted` join rule** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ |
 
 ## Complete list of room versions
 
@@ -57,8 +57,7 @@ the default room version when creating new rooms.
 
 The available room versions are:
 
--   [Version 1](/rooms/v1) - **Stable**. The current version of most
-    rooms.
+-   [Version 1](/rooms/v1) - **Stable**. The initial room version.
 -   [Version 2](/rooms/v2) - **Stable**. Implements State Resolution
     Version 2.
 -   [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs
@@ -76,6 +75,7 @@ The available room versions are:
     redacting some membership events.
 -   [Version 10](/rooms/v10) - **Stable**. Enforces integer-only power levels
     and adds `knock_restricted` join rule.
+-   [Version 11](/rooms/v11) - **Stable**. Clarifies the redaction algorithm.
 
 ## Room version grammar
 

content/rooms/fragments/v1-redactions.md

@@ -19,12 +19,14 @@ not in the following list:
 -   `membership`
 
 The content object must also be stripped of all keys, unless it is one
-of one of the following event types:
+of the following event types:
 
--   `m.room.member` allows key `membership`.
--   `m.room.create` allows key `creator`.
--   `m.room.join_rules` allows key `join_rule`.
--   `m.room.power_levels` allows keys `ban`, `events`, `events_default`,
-    `kick`, `redact`, `state_default`, `users`, `users_default`.
--   `m.room.aliases` allows key `aliases`.
--   `m.room.history_visibility` allows key `history_visibility`.
+-   [`m.room.member`](/client-server-api#mroommember) allows key `membership`.
+-   [`m.room.create`](/client-server-api#mroomcreate) allows key `creator`.
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows key `join_rule`.
+-   [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys
+    `ban`, `events`, `events_default`, `kick`, `redact`, `state_default`, `users`,
+    `users_default`.
+-   [`m.room.aliases`](/client-server-api#historical-events) allows key `aliases`.
+-   [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility) allows
+    key `history_visibility`.

content/rooms/fragments/v11-event-format.md

@@ -0,0 +1,4 @@
+
+Events in rooms of this version have the following structure:
+
+{{% definition path="api/server-server/definitions/pdu_v11" %}}

content/rooms/fragments/v11-redactions.md

@@ -0,0 +1,30 @@
+
+Upon receipt of a redaction event, the server must strip off any keys
+not in the following list:
+
+-   `event_id`
+-   `type`
+-   `room_id`
+-   `sender`
+-   `state_key`
+-   `content`
+-   `hashes`
+-   `signatures`
+-   `depth`
+-   `prev_events`
+-   `auth_events`
+-   `origin_server_ts`
+
+The content object must also be stripped of all keys, unless it is one
+of the following event types:
+
+-   [`m.room.member`](/client-server-api#mroommember) allows keys `membership`, `join_authorised_via_users_server`.
+    Additionally, it allows the `signed` key of the `third_party_invite` key.
+-   [`m.room.create`](/client-server-api#mroomcreate) allows all keys.
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows keys `join_rule`, `allow`.
+-   [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys
+    `ban`, `events`, `events_default`, `invite`, `kick`, `redact`, `state_default`,
+    `users`, `users_default`.
+-   [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility)
+    allows key `history_visibility`.
+-   [`m.room.redaction`](/client-server-api#mroomredaction) allows key `redacts`.

content/rooms/fragments/v6-redactions.md

@@ -19,11 +19,13 @@ not in the following list:
 -   `membership`
 
 The content object must also be stripped of all keys, unless it is one
-of one of the following event types:
+of the following event types:
 
--   `m.room.member` allows key `membership`.
--   `m.room.create` allows key `creator`.
--   `m.room.join_rules` allows key `join_rule`.
--   `m.room.power_levels` allows keys `ban`, `events`, `events_default`,
-    `kick`, `redact`, `state_default`, `users`, `users_default`.
--   `m.room.history_visibility` allows key `history_visibility`.
+-   [`m.room.member`](/client-server-api#mroommember) allows key `membership`.
+-   [`m.room.create`](/client-server-api#mroomcreate) allows key `creator`.
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows key `join_rule`.
+-   [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys
+    `ban`, `events`, `events_default`, `kick`, `redact`, `state_default`, `users`,
+    `users_default`.
+-   [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility) allows
+    key `history_visibility`.

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/fragments/v9-redactions.md

@@ -1,24 +1,3 @@
----
----
-
-{{% added-in this=true %}} `m.room.member` events now keep `join_authorised_via_users_server`
-in addition to other keys in `content` when being redacted.
-
-{{% boxes/rationale %}}
-Without the `join_authorised_via_users_server` property, redacted join events
-can become invalid when verifying the auth chain of a given event, thus creating
-a split-brain scenario where the user is able to speak from one server's
-perspective but most others will continually reject their events.
-
-This can theoretically be worked around with a rejoin to the room, being careful
-not to use the faulty events as `prev_events`, though instead it is encouraged
-to use v9 rooms over v8 rooms to outright avoid the situation.
-
-[Issue #3373](https://github.com/matrix-org/matrix-doc/issues/3373) has further
-information.
-{{% /boxes/rationale %}}
-
-The full redaction algorithm follows.
 
 Upon receipt of a redaction event, the server must strip off any keys
 not in the following list:
@@ -40,11 +19,15 @@ not in the following list:
 -   `membership`
 
 The content object must also be stripped of all keys, unless it is one
-of one of the following event types:
-
--   `m.room.member` allows keys `membership`, `join_authorised_via_users_server`.
--   `m.room.create` allows key `creator`.
--   `m.room.join_rules` allows keys `join_rule`, `allow`.
--   `m.room.power_levels` allows keys `ban`, `events`, `events_default`,
-    `kick`, `redact`, `state_default`, `users`, `users_default`.
--   `m.room.history_visibility` allows key `history_visibility`.
+of the following event types:
+
+-   [`m.room.member`](/client-server-api#mroommember) allows keys `membership`,
+    `join_authorised_via_users_server`.
+-   [`m.room.create`](/client-server-api#mroomcreate) allows key `creator`.
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules) allows keys `join_rule`,
+    `allow`.
+-   [`m.room.power_levels`](/client-server-api#mroompower_levels) allows keys
+    `ban`, `events`, `events_default`, `kick`, `redact`, `state_default`, `users`,
+    `users_default`.
+-   [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility)
+    allows key `history_visibility`.

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

@@ -0,0 +1,285 @@
+---
+title: Room Version 11
+type: docs
+weight: 100
+---
+
+This room version builds on [version 10](/rooms/v10) while clarifying redaction
+rules.
+
+## Client considerations
+
+### Redactions
+
+{{< added-in this=true >}} The top-level `origin`, `membership`, and `prev_state` properties
+are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate)
+event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction)
+event keeps the `redacts` property under `content`. The
+[`m.room.power_levels`](/client-server-api#mroompower_levels) event keeps the
+`invite` property under `content`.
+
+The full redaction algorithm follows.
+
+{{% rver-fragment name="v11-redactions" withVersioning="true" %}}
+
+### Event format
+
+Clients should no longer depend on the `creator` property in the `content` of
+[`m.room.create`](/client-server-api#mroomcreate) events.  In all room versions,
+clients can rely on `sender` instead to determine a room creator.
+
+The format of [`m.room.redaction`](/client-server-api#mroomredaction)
+events has been modified. Client should look for the `redacts` key under `content`
+instead of a top-level event property.
+
+The `third_party_invite` key of [`m.room.member`](/client-server-api#mroommember)
+events is no longer redacted, *but* will only contain the `signed` key after redaction.
+
+## Server implementation components
+
+{{% boxes/warning %}}
+The information contained in this section is strictly for server
+implementors. Applications which use the Client-Server API are generally
+unaffected by the intricacies contained here. The section above
+regarding client considerations is the resource that Client-Server API
+use cases should reference.
+{{% /boxes/warning %}}
+
+This room version updates the redaction algorithm and modifies how servers should
+create `m.room.create` and `m.room.redaction` events.
+
+Room version 11 is based upon room version 10 with the following considerations.
+
+### Redactions
+
+[See above](#redactions).
+
+### Event format
+
+The core event format is the same as [room version 10](/rooms/v10#event-format).
+However, this room version changes some properties of some event types.
+
+{{% rver-fragment name="v11-event-format" %}}
+
+#### Remove the `creator` property of `m.room.create` events
+
+The `content` of a `m.room.create` event no longer has a `creator` property,
+which previously was always equivalent to the `sender` of the event.
+
+#### Moving the `redacts` property of `m.room.redaction` events to a `content` property
+
+The `redacts` property of `m.room.redaction` events is moved from a top-level
+event property to a property under the event `content`.
+
+For backwards-compatibility with older clients, servers should add a `redacts` property
+to the top level of `m.room.redaction` events in when serving such events over the
+Client-Server API.
+
+For improved compatibility with newer clients, servers should add a `redacts` property
+to the `content` of `m.room.redaction` events in *older* room versions when serving
+such events over the Client-Server API.
+
+### Authorization rules
+
+Events must be signed by the server denoted by the `sender` property.
+
+`m.room.redaction` events are not explicitly part of the auth rules.
+They are still subject to the minimum power level rules, but should always
+fall into "10. Otherwise, allow". Instead of being authorized at the time
+of receipt, they are authorized at a later stage: see the
+[Redactions](#redactions) section below for more information.
+
+The types of state events that affect authorization are:
+
+-   [`m.room.create`](/client-server-api#mroomcreate)
+-   [`m.room.member`](/client-server-api#mroommember)
+-   [`m.room.join_rules`](/client-server-api#mroomjoin_rules)
+-   [`m.room.power_levels`](/client-server-api#mroompower_levels)
+-   [`m.room.third_party_invite`](/client-server-api#mroomthird_party_invite)
+
+{{% boxes/note %}}
+Power levels are inferred from defaults when not explicitly supplied.
+For example, mentions of the `sender`'s power level can also refer to
+the default power level for users in the room.
+{{% /boxes/note %}}
+
+The rules are as follows:
+
+1.  {{< changed-in this="true" >}}
+    If type is `m.room.create`:
+    1.  If it has any `prev_events`, reject.
+    2.  If the domain of the `room_id` does not match the domain of the
+        `sender`, reject.
+    3.  If `content.room_version` is present and is not a recognised
+        version, reject.
+    4.  Otherwise, allow.
+2.  Considering the event's `auth_events`:
+    1.  If there are duplicate entries for a given `type` and `state_key` pair,
+        reject.
+    2.  If there are entries whose `type` and `state_key` don't match those
+        specified by the [auth events
+        selection](/server-server-api#auth-events-selection)
+        algorithm described in the server specification, reject.
+    3.  If there are entries which were themselves rejected under the [checks
+        performed on receipt of a
+        PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
+    4. If there is no `m.room.create` event among the entries, reject.
+3. If the `content` of the `m.room.create` event in the room state has the
+   property `m.federate` set to `false`, and the `sender` domain of the event
+   does not match the `sender` domain of the create event, reject.
+4.  If type is `m.room.member`:
+    1.  If there is no `state_key` property, or no `membership` property in
+        `content`, reject.
+    2.  If `content` has a `join_authorised_via_users_server`
+        key:
+        1.  If the event is not validly signed by the homeserver of the user ID denoted
+            by the key, reject.
+    3.  If `membership` is `join`:
+        1.  {{< changed-in this="true" >}}
+            If the only previous event is an `m.room.create` and the
+            `state_key` is the sender, allow.
+        2.  If the `sender` does not match `state_key`, reject.
+        3.  If the `sender` is banned, reject.
+        4.  If the `join_rule` is `invite` or `knock` then allow if
+            membership state is `invite` or `join`.
+        5.  If the `join_rule` is `restricted` or `knock_restricted`:
+            1.  If membership state is `join` or `invite`, allow.
+            2.  If the `join_authorised_via_users_server` key in `content`
+                is not a user with sufficient permission to invite other
+                users, reject.
+            3.  Otherwise, allow.
+        6.  If the `join_rule` is `public`, allow.
+        7.  Otherwise, reject.
+    4.  If `membership` is `invite`:
+        1.  If `content` has a `third_party_invite` property:
+            1.  If *target user* is banned, reject.
+            2.  If `content.third_party_invite` does not have a `signed`
+                property, reject.
+            3.  If `signed` does not have `mxid` and `token` properties,
+                reject.
+            4.  If `mxid` does not match `state_key`, reject.
+            5.  If there is no `m.room.third_party_invite` event in the
+                current room state with `state_key` matching `token`,
+                reject.
+            6.  If `sender` does not match `sender` of the
+                `m.room.third_party_invite`, reject.
+            7.  If any signature in `signed` matches any public key in
+                the `m.room.third_party_invite` event, allow. The public
+                keys are in `content` of `m.room.third_party_invite` as:
+                1.  A single public key in the `public_key` property.
+                2.  A list of public keys in the `public_keys` property.
+            8.  Otherwise, reject.
+        2.  If the `sender`'s current membership state is not `join`,
+            reject.
+        3.  If *target user*'s current membership state is `join` or
+            `ban`, reject.
+        4.  If the `sender`'s power level is greater than or equal to
+            the *invite level*, allow.
+        5.  Otherwise, reject.
+    5.  If `membership` is `leave`:
+        1.  If the `sender` matches `state_key`, allow if and only if
+            that user's current membership state is `invite`, `join`,
+            or `knock`.
+        2.  If the `sender`'s current membership state is not `join`,
+            reject.
+        3.  If the *target user*'s current membership state is `ban`,
+            and the `sender`'s power level is less than the *ban level*,
+            reject.
+        4.  If the `sender`'s power level is greater than or equal to
+            the *kick level*, and the *target user*'s power level is
+            less than the `sender`'s power level, allow.
+        5.  Otherwise, reject.
+    6.  If `membership` is `ban`:
+        1.  If the `sender`'s current membership state is not `join`,
+            reject.
+        2.  If the `sender`'s power level is greater than or equal to
+            the *ban level*, and the *target user*'s power level is less
+            than the `sender`'s power level, allow.
+        3.  Otherwise, reject.
+    7. If `membership` is `knock`:
+        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`, `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.
+6.  If type is `m.room.third_party_invite`:
+    1.  Allow if and only if `sender`'s current power level is greater
+        than or equal to the *invite level*.
+7.  If the event type's *required power level* is greater than the
+    `sender`'s power level, reject.
+8.  If the event has a `state_key` that starts with an `@` and does not
+    match the `sender`, reject.
+9. If type is `m.room.power_levels`:
+    1.  If any of the properties `users_default`, `events_default`, `state_default`,
+        `ban`, `redact`, `kick`, or `invite` in `content` are present and
+        not an integer, reject.
+    2.  If either of the properties `events` or `notifications` in `content`
+        are present and not an object with values that are integers,
+        reject.
+    3.  If the `users` property in `content` is not an obiect with keys that
+        are valid user IDs with values that are integers, reject.
+    4.  If there is no previous `m.room.power_levels` event in the room,
+        allow.
+    5.  For the properties `users_default`, `events_default`, `state_default`,
+        `ban`, `redact`, `kick`, `invite` check if they were added,
+        changed or removed. For each found alteration:
+        1.  If the current value is higher than the `sender`'s current
+            power level, reject.
+        2.  If the new value is higher than the `sender`'s current power
+            level, reject.
+    6.  For each entry being changed in, or removed from, the `events` or
+        `notifications` properties:
+        1.  If the current value is greater than the `sender`'s current
+            power level, reject.
+    7.  For each entry being added to, or changed in, the `events` or
+        `notifications` properties:
+        1.  If the new value is greater than the `sender`'s current power
+            level, reject.
+    8.  For each entry being changed in, or removed from, the `users` property,
+        other than the `sender`'s own entry:
+        1.  If the current value is greater than or equal to the `sender`'s
+            current power level, reject.
+    9.  For each entry being added to, or changed in, the `users` property:
+        1.  If the new value is greater than the `sender`'s current power
+            level, reject.
+    10. Otherwise, allow.
+10. Otherwise, allow.
+
+{{% boxes/note %}}
+Some consequences of these rules:
+
+-   Unless you are a member of the room, the only permitted operations
+    (apart from the initial create/join) are: joining a public room;
+    accepting or rejecting an invitation to a room.
+-   To unban somebody, you must have power level greater than or equal
+    to both the kick *and* ban levels, *and* greater than the target
+    user's power level.
+{{% /boxes/note %}}
+
+## Unchanged from v10
+
+The following sections have not been modified since v10, but are included for
+completeness.
+
+### Handling redactions
+
+{{% rver-fragment name="v3-handling-redactions" %}}
+
+### Event IDs
+
+{{% rver-fragment name="v4-event-ids" %}}
+
+### State resolution
+
+{{% rver-fragment name="v2-state-res" %}}
+
+### Canonical JSON
+
+{{% rver-fragment name="v6-canonical-json" %}}
+
+### Signing key validity period
+
+{{% rver-fragment name="v5-signing-requirements" %}}

content/rooms/v6.md

@@ -15,7 +15,7 @@ which implement the redaction algorithm locally should refer to the
 
 ### Redactions
 
-{{% added-in this=true %}} All significant meaning for `m.room.aliases`
+{{< added-in this=true >}} All significant meaning for `m.room.aliases`
 has been removed from the redaction algorithm. The remaining rules are
 the same as past room versions.
 

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/rooms/v9.md

@@ -17,6 +17,27 @@ Clients which implement the redaction algorithm locally should refer to the
 
 ### Redactions
 
+{{< added-in this=true >}} [`m.room.member`](/client-server-api#mroommember) events
+now keep `join_authorised_via_users_server` in addition to other keys in `content`
+when being redacted.
+
+{{% boxes/rationale %}}
+Without the `join_authorised_via_users_server` property, redacted join events
+can become invalid when verifying the auth chain of a given event, thus creating
+a split-brain scenario where the user is able to speak from one server's
+perspective but most others will continually reject their events.
+
+This can theoretically be worked around with a rejoin to the room, being careful
+not to use the faulty events as `prev_events`, though instead it is encouraged
+to use v9 rooms over v8 rooms to outright avoid the situation.
+
+[Issue #3373](https://github.com/matrix-org/matrix-doc/issues/3373) has further
+information.
+{{% /boxes/rationale %}}
+
+The full redaction algorithm follows.
+
+
 {{% rver-fragment name="v9-redactions" withVersioning="true" %}}
 
 ## Server implementation components

content/server-server-api.md

@@ -110,7 +110,7 @@ to send. The process overall is as follows:
     given. The target server must present a valid certificate for the IP
     address. The `Host` header in the request should be set to the
     server name, including the port if the server name included one.
-    
+
 2.  If the hostname is not an IP literal, and the server name includes an
     explicit port, resolve the hostname to an IP address using CNAME, AAAA or A
     records.
@@ -135,43 +135,59 @@ to send. The process overall is as follows:
     to step 4. If the response is valid, the `m.server` property is
     parsed as `<delegated_hostname>[:<delegated_port>]` and processed as
     follows:
-    -   If `<delegated_hostname>` is an IP literal, then that IP address
+    1.   If `<delegated_hostname>` is an IP literal, then that IP address
         should be used together with the `<delegated_port>` or 8448 if
         no port is provided. The target server must present a valid TLS
         certificate for the IP address. Requests must be made with a
         `Host` header containing the IP address, including the port if
         one was provided.
-    -   If `<delegated_hostname>` is not an IP literal, and
+    2.   If `<delegated_hostname>` is not an IP literal, and
         `<delegated_port>` is present, an IP address is discovered by
         looking up CNAME, AAAA or A records for `<delegated_hostname>`.  The
         resulting IP address is used, alongside the `<delegated_port>`.
         Requests must be made with a `Host` header of
         `<delegated_hostname>:<delegated_port>`. The target server must
         present a valid certificate for `<delegated_hostname>`.
-    -   If `<delegated_hostname>` is not an IP literal and no
+    3.  {{< added-in v="1.8" >}} If `<delegated_hostname>` is not an IP literal and no
         `<delegated_port>` is present, an SRV record is looked up for
+        `_matrix-fed._tcp.<delegated_hostname>`. This may result in another
+        hostname (to be resolved using AAAA or A records) and port.
+        Requests should be made to the resolved IP address and port with
+        a `Host` header containing the `<delegated_hostname>`. The
+        target server must present a valid certificate for
+        `<delegated_hostname>`.
+    4.  **[Deprecated]** If `<delegated_hostname>` is not an IP literal, no
+        `<delegated_port>` is present, and a `_matrix-fed._tcp.<delegated_hostname>`
+        SRV record was not found, an SRV record is looked up for
         `_matrix._tcp.<delegated_hostname>`. This may result in another
         hostname (to be resolved using AAAA or A records) and port.
         Requests should be made to the resolved IP address and port with
         a `Host` header containing the `<delegated_hostname>`. The
         target server must present a valid certificate for
         `<delegated_hostname>`.
-    -   If no SRV record is found, an IP address is resolved using CNAME, AAAA
+    5.   If no SRV record is found, an IP address is resolved using CNAME, AAAA
         or A records. Requests are then made to the resolve IP address
         and a port of 8448, using a `Host` header of
         `<delegated_hostname>`. The target server must present a valid
         certificate for `<delegated_hostname>`.
 
-4.  If the `/.well-known` request resulted in an error response, a
-    server is found by resolving an SRV record for
-    `_matrix._tcp.<hostname>`. This may result in a hostname (to be
-    resolved using AAAA or A records) and port. Requests are made to the
-    resolved IP address and port, using 8448 as a default port, with a
-    `Host` header of `<hostname>`. The target server must present a
-    valid certificate for `<hostname>`.
-
-5.  If the `/.well-known` request returned an error response, and the
-    SRV record was not found, an IP address is resolved using CNAME, AAAA and A
+4.  {{< added-in v="1.8" >}} If the `/.well-known` request resulted in an error response, a server is
+    found by resolving an SRV record for `_matrix-fed._tcp.<hostname>`. This may
+    result in a hostname (to be resolved using AAAA or A records) and
+    port. Requests are made to the resolved IP address and port, with a `Host`
+    header of `<hostname>`. The target server must present a valid certificate
+    for `<hostname>`.
+
+5.  **[Deprecated]** If the `/.well-known` request resulted in an error response,
+    and a `_matrix-fed._tcp.<hostname>` SRV record was not found, a server is
+    found by resolving an SRV record for `_matrix._tcp.<hostname>`. This may
+    result in a hostname (to be resolved using AAAA or A records) and
+    port. Requests are made to the resolved IP address and port, with a `Host`
+    header of `<hostname>`. The target server must present a valid certificate
+    for `<hostname>`.
+
+6.  If the `/.well-known` request returned an error response, and
+    no SRV records were found, an IP address is resolved using CNAME, AAAA and A
     records. Requests are made to the resolved IP address using port
     8448 and a `Host` header containing the `<hostname>`. The target
     server must present a valid certificate for `<hostname>`.
@@ -192,6 +208,14 @@ mandated by [RFC2782](https://www.rfc-editor.org/rfc/rfc2782.html):
 > the name MUST NOT be an alias (in the sense of RFC 1034 or RFC 2181)
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+Steps 3.4 and 5 are deprecated because they use a service name not registered by IANA.
+They may be removed in a future version of the specification. Server admins are encouraged
+to use `.well-known` over any form of SRV records.
+
+The IANA registration for port 8448 and `matrix-fed` can be found [here](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=matrix-fed).
+{{% /boxes/note %}}
+
 {{% http-api spec="server-server" api="wellknown" %}}
 
 ### Server implementation
@@ -266,7 +290,7 @@ Step 1 sign JSON:
 
 ```
 {
-    "method": "GET",
+    "method": "POST",
     "uri": "/target",
     "origin": "origin.hs.example.com",
     "destination": "destination.hs.example.com",
@@ -287,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
 
@@ -326,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
@@ -339,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.
@@ -877,8 +903,7 @@ on the resulting `m.room.member` event.
 If the joining server fails all conditions then a 403 `M_FORBIDDEN` error
 is used by the resident server.
 
-<a name="knocking-rooms">
-## Knocking upon a room
+## Knocking upon a room {#knocking-rooms}
 
 Rooms can permit knocking through the join rules, and if permitted this
 gives users a way to request to join (be invited) to the room. Users who

data-definitions/sas-emoji-v1-i18n/ar.json

@@ -50,17 +50,17 @@
     "Flower": "زَهرَة",
     "Butterfly": "فَرَاشَة",
     "Octopus": "أُخطُبُوط",
-    "Fish": "سَمَكَة",
+    "Fish": "سَمَكة",
     "Turtle": "سُلحفاة",
-    "Penguin": "بِطريق",
+    "Penguin": "بطريق",
     "Rooster": "دِيك",
     "Panda": "باندَا",
     "Rabbit": "أَرنَب",
     "Elephant": "فِيل",
     "Pig": "خِنزِير",
-    "Unicorn": "حِصَانٌ بِقَرن",
+    "Unicorn": "حصان وحيد القرن",
     "Horse": "حِصَان",
     "Lion": "أَسَد",
     "Cat": "هِرَّة",
-    "Dog": "كَلب"
+    "Dog": "كلب"
 }

data-definitions/sas-emoji-v1-i18n/cs.json

@@ -15,7 +15,7 @@
     "Flag": "Vlajka",
     "Telephone": "Telefon",
     "Hammer": "Kladivo",
-    "Key": "Klíč",
+    "Key": "Klíč ke dveřím",
     "Lock": "Zámek",
     "Scissors": "Nůžky",
     "Paperclip": "Sponka",

data-definitions/sas-emoji-v1-i18n/es.json

@@ -11,7 +11,7 @@
     "Pencil": "Lápiz",
     "Key": "Llave",
     "Hammer": "Martillo",
-    "Telephone": "Telefono",
+    "Telephone": "Teléfono",
     "Train": "Tren",
     "Bicycle": "Bicicleta",
     "Ball": "Bola",

data-definitions/sas-emoji-v1-i18n/fa.json

@@ -0,0 +1,66 @@
+{
+    "Pin": "سنجاق",
+    "Folder": "پوشه",
+    "Headphones": "هدفون",
+    "Anchor": "لنگر",
+    "Bell": "زنگ",
+    "Trumpet": "شیپور",
+    "Guitar": "گیتار",
+    "Ball": "توپ",
+    "Trophy": "جام",
+    "Rocket": "موشک",
+    "Aeroplane": "هواپیما",
+    "Bicycle": "دوچرخه",
+    "Train": "قطار",
+    "Flag": "پرچم",
+    "Telephone": "تلفن",
+    "Hammer": "چکش",
+    "Key": "کلید",
+    "Lock": "قفل",
+    "Scissors": "قیچی",
+    "Paperclip": "گیره کاغذ",
+    "Pencil": "مداد",
+    "Book": "کتاب",
+    "Light Bulb": "لامپ",
+    "Gift": "هدیه",
+    "Clock": "ساعت",
+    "Hourglass": "ساعت شنی",
+    "Umbrella": "چتر",
+    "Thumbs Up": "لایک",
+    "Santa": "بابا نوئل",
+    "Spanner": "آچار",
+    "Glasses": "عینک",
+    "Hat": "کلاه",
+    "Robot": "ربات",
+    "Smiley": "خنده",
+    "Heart": "قلب",
+    "Cake": "کیک",
+    "Pizza": "پیتزا",
+    "Corn": "ذرت",
+    "Strawberry": "توت فرنگی",
+    "Apple": "سیب",
+    "Banana": "موز",
+    "Fire": "آتش",
+    "Cloud": "ابر",
+    "Moon": "ماه",
+    "Globe": "زمین",
+    "Mushroom": "قارچ",
+    "Cactus": "کاکتوس",
+    "Tree": "درخت",
+    "Flower": "گل",
+    "Butterfly": "پروانه",
+    "Octopus": "اختاپوس",
+    "Fish": "ماهی",
+    "Turtle": "لاک‌پشت",
+    "Penguin": "پنگوئن",
+    "Rooster": "خروس",
+    "Panda": "پاندا",
+    "Rabbit": "خرگوش",
+    "Elephant": "فیل",
+    "Pig": "خوک",
+    "Unicorn": "تک شاخ",
+    "Horse": "اسب",
+    "Lion": "شیر",
+    "Cat": "گربه",
+    "Dog": "سگ"
+}

data-definitions/sas-emoji-v1-i18n/ja.json

@@ -9,14 +9,14 @@
     "Moon": "月",
     "Apple": "リンゴ",
     "Cake": "ケーキ",
-    "Robot": "ロボと",
+    "Robot": "ロボット",
     "Glasses": "めがね",
     "Book": "本",
     "Telephone": "電話機",
     "Train": "電車",
     "Bicycle": "自転車",
     "Pin": "ピン",
-    "Folder": "フォルダ",
+    "Folder": "フォルダー",
     "Headphones": "ヘッドホン",
     "Anchor": "いかり",
     "Bell": "ベル",

data-definitions/sas-emoji-v1-i18n/pt.json

@@ -0,0 +1,66 @@
+{
+    "Thumbs Up": "Polegar para cima",
+    "Pin": "Pionés",
+    "Folder": "Pasta",
+    "Headphones": "Fones",
+    "Anchor": "Âncora",
+    "Bell": "Sino",
+    "Trumpet": "Trompete",
+    "Guitar": "Guitarra",
+    "Ball": "Bola",
+    "Trophy": "Troféu",
+    "Rocket": "Foguetão",
+    "Aeroplane": "Avião",
+    "Bicycle": "Bicicleta",
+    "Train": "Comboio",
+    "Flag": "Bandeira",
+    "Telephone": "Telefone",
+    "Hammer": "Martelo",
+    "Key": "Chave",
+    "Lock": "Cadeado",
+    "Scissors": "Tesoura",
+    "Paperclip": "Clipe",
+    "Pencil": "Lápis",
+    "Book": "Livro",
+    "Light Bulb": "Lâmpada",
+    "Gift": "Presente",
+    "Clock": "Relógio",
+    "Hourglass": "Ampulheta",
+    "Umbrella": "Guarda-chuva",
+    "Santa": "Pai Natal",
+    "Spanner": "Chave inglesa",
+    "Glasses": "Óculos",
+    "Hat": "Chapéu",
+    "Robot": "Robô",
+    "Smiley": "Sorriso",
+    "Heart": "Coração",
+    "Cake": "Bolo",
+    "Pizza": "Piza",
+    "Corn": "Milho",
+    "Strawberry": "Morango",
+    "Apple": "Maçã",
+    "Banana": "Banana",
+    "Fire": "Fogo",
+    "Cloud": "Nuvem",
+    "Moon": "Lua",
+    "Globe": "Globo",
+    "Mushroom": "Cogumelo",
+    "Cactus": "Cato",
+    "Tree": "Árvore",
+    "Flower": "Flor",
+    "Butterfly": "Borboleta",
+    "Octopus": "Polvo",
+    "Fish": "Peixe",
+    "Turtle": "Tartaruga",
+    "Penguin": "Pinguim",
+    "Rooster": "Galo",
+    "Panda": "Panda",
+    "Rabbit": "Coelho",
+    "Elephant": "Elefante",
+    "Pig": "Porco",
+    "Unicorn": "Unicórnio",
+    "Horse": "Cavalo",
+    "Lion": "Leão",
+    "Cat": "Gato",
+    "Dog": "Cão"
+}