Replace Twitter link in footer with Masto/Bluesky (#2282)

Fixes #784

Add a collapsible list of endpoints to the top of the page for each distinct spec. We do this by storing endpoint metadata on $page and creating a new partial, endpoints-toc.html, which renders it.

.github/workflows/main.yml

@@ -1,4 +1,9 @@
 name: "Spec"
+
+env:
+  HUGO_VERSION: 0.148.1
+  PYTHON_VERSION: 3.13
+
 on:
   push:
     branches:
@@ -36,7 +41,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -55,7 +60,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -74,7 +79,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -116,7 +121,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -150,6 +155,11 @@ jobs:
               --api server-server \
               -r "$RELEASE" \
               -o spec/server-server-api/api.json
+          scripts/dump-openapi.py \
+              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
+              --api identity \
+              -r "$RELEASE" \
+              -o spec/identity-service-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
         uses: actions/upload-artifact@v4
@@ -168,7 +178,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
@@ -193,7 +203,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.117.0'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
@@ -255,7 +265,7 @@ jobs:
       - name: "Run htmltest"
         uses: wjdp/htmltest-action@master
         with:
-          config: .htmltest.yaml
+          config: .htmltest.yml
 
   build-historical-spec:
     name: "📖 Build the historical backup spec"
@@ -270,8 +280,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          # Cannot build the spec with Hugo 0.125.0 because of https://github.com/google/docsy/issues/1930
+          hugo-version: ${{ env.HUGO_VERSION }}
-          hugo-version: '0.124.1'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
@@ -280,10 +289,11 @@ jobs:
           npm i
           npm run get-proposals
       - name: "⚙️ hugo"
+        env:
+          HUGO_PARAMS_VERSION_STATUS: "historical"
         # Create a baseURL like `/v1.2` out of the `v1.2` tag
         run: |
-          echo -e '[params.version]\nstatus="historical"' > historical.toml
+          hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
-          hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
         uses: actions/download-artifact@v4

.github/workflows/release.yaml

@@ -12,6 +12,9 @@ jobs:
     defaults:
       run:
         working-directory: packages/npm
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - name: 🧮 Checkout code
         uses: actions/checkout@v4
@@ -23,6 +26,10 @@ jobs:
           cache-dependency-path: packages/npm/yarn.lock
           registry-url: "https://registry.npmjs.org"
 
+      # Ensure npm 11.5.1 or later is installed
+      - name: Update npm
+        run: npm install -g npm@latest
+
       - name: 🔨 Install dependencies
         run: "yarn install --frozen-lockfile"
 
@@ -33,10 +40,4 @@ jobs:
           VERSION: ${{ github.event.release.tag_name }}.0
 
       - name: 🚀 Publish to npm
-        id: npm-publish
+        run: npm publish --provenance --access public --tag latest
-        uses: JS-DevTools/npm-publish@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1
-        with:
-          token: ${{ secrets.NPM_TOKEN }}
-          package: packages/npm
-          access: public
-          ignore-scripts: false

.gitignore

@@ -14,3 +14,4 @@ _rendered.rst
 /spec/
 changelogs/rendered.*
 .hugo_build.lock
+hugo_stats.json

README.md

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

assets/css/fonts/Inter.css

@@ -0,0 +1,63 @@
+/* cyrillic-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-cyrillic-ext-normal.woff2) format('woff2');
+  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
+}
+/* cyrillic */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-cyrillic-normal.woff2) format('woff2');
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+/* greek-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-greek-ext-normal.woff2) format('woff2');
+  unicode-range: U+1F00-1FFF;
+}
+/* greek */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-greek-normal.woff2) format('woff2');
+  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
+}
+/* vietnamese */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-vietnamese-normal.woff2) format('woff2');
+  unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
+}
+/* latin-ext */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-latin-ext-normal.woff2) format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: local('Inter'), url(../../fonts/Inter-latin-normal.woff2) format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

assets/css/fonts/README.md

@@ -3,7 +3,7 @@
 ## Inter.css
 
 `Inter.css` is a local copy of
-https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i, modified to pull
+https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,100..900&display=swap, modified to pull
 font files (`.woff2`) from local sources. It was created
 using `download_google_fonts_css.py`.
   
@@ -15,8 +15,8 @@ load them. Example call:
 
 ```sh
 python3 download_google_fonts_css.py \
-  "https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i" \
+  "https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,100..900&display=swap" \
-  ../../fonts \
+  ../../../static/fonts \
   ../../fonts
 ```
   

assets/css/fonts/download_google_fonts_css.py

@@ -84,7 +84,6 @@ new_css_file_lines = []
 font_lang = None
 font_family = None
 font_style = None
-font_weight = 0
 for line in original_contents:
     # Check if this line contains a font URL
     match = re.match(r".*url\((.*)\) format.*", line)
@@ -96,16 +95,17 @@ for line in original_contents:
         resp = requests.get(font_url)
         if resp.status_code == 200:
             # Save the font file
-            filename = "%s-%s-%s-%d.woff2" % (
+            filename = "%s-%s-%s.woff2" % (
-                font_family, font_lang, font_style, font_weight
+                font_family, font_lang, font_style
             )
             font_filepath = font_output_dir + filename
             with open(font_filepath, "wb") as f:
                 print("Writing font file:", font_filepath)
                 f.write(resp.content)
 
-            # Replace google URL with local URL
+            # Replace google URL with local URL and allow the browser to load the
-            line = re.sub(r"url\(.+\)", f"url({css_font_path + filename})", line)
+            # local font if it exists.
+            line = re.sub(r"url\(.+?\)", f"local('{font_family}'), url({css_font_path + filename})", line)
         else:
             print("Warning: failed to download font file:", font_url)
 
@@ -121,9 +121,6 @@ for line in original_contents:
     font_style_match = re.match(r".*font-style: (.+);$", line)
     if font_style_match:
         font_style = font_style_match.group(1)
-    font_weight_match = re.match(r".*font-weight: (.+);$", line)
-    if font_weight_match:
-        font_weight = int(font_weight_match.group(1))
 
     # Append the potentially modified line to the new css file
     new_css_file_lines.append(line)

assets/diagrams/README.md

@@ -7,11 +7,17 @@ https://www.diagrams.net/ is a great ([open source](https://github.com/jgraph/dr
 tool for these sorts of things - include your `.drawio` file next to your diagram.
 
 Suggested settings for diagrams.net:
-* Export as PNG.
+* Export as WebP.
-* 100% size.
+* 200% size.
 * `20` for a border width.
-* No transparent background, shadow, or grid.
+* Light appearance.
-* Include a copy of the diagram.
+* No shadow, or grid.
 
-To reference a diagram, use the absolute path when compiled. For example,
+To reference a diagram, use the `diagram` shortcode. For example:
-`![membership-flow-diagram](/diagrams/membership.png)`
+
+```
+{{% diagram name="membership" alt="Diagram presenting the possible membership state transitions" %}}
+```
+
+Where `name` is the file name without extension, and `alt` is a textual
+replacement for the image, useful for accessibility.

assets/icons/favicon.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
+   <style>
+      path { fill: #000000; }
+      @media (prefers-color-scheme: dark) {
+          path { fill: #ffffff; }
+      }
+   </style>
+   <path d="M 30,2.0000001 V 30 h -1 -2 v 2 h 5 V -3.3333334e-8 L 27,0 v 2 z"/>
+   <path d="M 9.9515939,10.594002 V 12.138 h 0.043994 c 0.3845141,-0.563728 0.8932271,-1.031728 1.4869981,-1.368 0.580003,-0.322998 1.244999,-0.485 1.993002,-0.485 0.72,0 1.376999,0.139993 1.971998,0.42 0.595,0.279004 1.047001,0.771001 1.355002,1.477001 0.338003,-0.500001 0.795999,-0.941 1.376999,-1.323001 0.579999,-0.382998 1.265998,-0.574 2.059998,-0.574 0.602003,0 1.160002,0.074 1.674002,0.220006 0.514,0.148006 0.953998,0.382998 1.321999,0.706998 0.36601,0.322999 0.653001,0.746 0.859,1.268002 0.205001,0.521998 0.307994,1.15 0.307994,1.887001 v 7.632997 h -3.127 v -6.463997 c 0,-0.383002 -0.01512,-0.743002 -0.04399,-1.082003 -0.02079,-0.3072 -0.103219,-0.607113 -0.242003,-0.881998 -0.133153,-0.25081 -0.335962,-0.457777 -0.584001,-0.596002 -0.257008,-0.146003 -0.605998,-0.220006 -1.046997,-0.220006 -0.440002,0 -0.796003,0.085 -1.068,0.253002 -0.272013,0.170003 -0.485001,0.390002 -0.639001,0.662003 -0.159119,0.287282 -0.263585,0.601602 -0.307994,0.926997 -0.05197,0.346923 -0.07801,0.697217 -0.07801,1.048002 v 6.353999 h -3.128005 v -6.398 c 0,-0.338003 -0.0072,-0.673001 -0.02116,-1.004001 -0.01134,-0.313663 -0.07487,-0.623229 -0.187994,-0.915999 -0.107943,-0.276623 -0.300435,-0.512126 -0.550001,-0.673001 -0.25799,-0.168 -0.636,-0.253002 -1.134999,-0.253002 -0.198123,0.0083 -0.394383,0.04195 -0.584002,0.100006 -0.258368,0.07446 -0.498455,0.201827 -0.704999,0.373985 -0.227981,0.183987 -0.421999,0.449 -0.583997,0.794003 -0.161008,0.345978 -0.242003,0.797998 -0.242003,1.356998 v 6.618999 H 6.99942 V 10.590001 Z"/>
+   <path d="M 2,2.0000001 V 30 h 3 v 2 H 0 V 9.2650922e-8 L 5,0 v 2 z"/>
+</svg>

assets/js/toc.js

@@ -0,0 +1,169 @@
+/*
+Copyright 2020, 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/*
+  Only call the given function once every 250 milliseconds to avoid impacting
+  the performance of the browser.
+  Source: https://remysharp.com/2010/07/21/throttling-function-calls
+*/
+function throttle(fn) {
+  const threshold = 250;
+  let last = null;
+  let deferTimer = null;
+
+  return function (...args) {
+    const now = new Date();
+
+    if (last && now < last + threshold) {
+      // Hold on to it.
+      clearTimeout(deferTimer);
+      deferTimer = setTimeout(() => {
+        last = now;
+        fn.apply(this, args);
+      }, threshold);
+    } else {
+      last = now;
+      fn.apply(this, args);
+    }
+  }
+}
+
+/*
+  Get the list of headings that appear in the ToC.
+  This is not as simple as querying all the headings in the content, because
+  some headings are not rendered in the ToC (e.g. in the endpoint definitions).
+*/
+function getHeadings() {
+  let headings = [];
+
+  // First get the anchors in the ToC.
+  const toc_anchors = document.querySelectorAll("#toc nav a");
+
+  for (const anchor of toc_anchors) {
+    // Then get the heading from its selector in the anchor's href.
+    const selector = anchor.getAttribute("href");
+    if (!selector) {
+      console.error("Got ToC anchor without href");
+      continue;
+    }
+    
+    const heading = document.querySelector(selector);
+    if (!heading) {
+      console.error("Heading not found for selector:", selector);
+      continue;
+    }
+
+    headings.push(heading);
+  }
+
+  return headings;
+}
+
+/*
+  Get the heading of the text visible at the top of the viewport.
+  This is the first heading above or at the top of the viewport.
+*/
+function getCurrentHeading(headings, headerOffset) {
+  const scrollTop = document.documentElement.scrollTop;
+  let prevHeading = null;
+  let currentHeading = null;
+  let index = 0;
+
+  for (const heading of headings) {
+    // Compute the position compared to the viewport.
+    const rect = heading.getBoundingClientRect();
+
+    if (rect.top >= headerOffset && rect.top <= headerOffset + 30) {
+      // This heading is at the top of the viewport, this is the current heading.
+      currentHeading = heading;
+      break;
+    }
+    if (rect.top >= headerOffset) {
+      // This is in or below the viewport, the current heading should be the
+      // previous one.
+      if (prevHeading) {
+        currentHeading = prevHeading;
+      } else {
+        // The first heading does not have a prevHeading.
+        currentHeading = heading;
+      }
+      break;
+    }
+
+    prevHeading = heading;
+    index += 1;
+  }
+
+  // At the bottom of the page we might not have a heading.
+  if (!currentHeading) {
+    currentHeading = prevHeading;
+  }
+
+  return currentHeading;
+}
+
+/*
+  Select the ToC entry that points to the given ID.
+  Clear any previously highlighted ToC items, select the new one,
+  and adjust the ToC scroll position.
+*/
+function selectTocEntry(id) {
+  // Deselect previously selected entries.
+  const activeEntries = document.querySelectorAll("#toc nav a.active");
+  for (const activeEntry of activeEntries) {
+    activeEntry.classList.remove('active');
+  }
+
+  // Find the new entry and select it.
+  const newEntry = document.querySelector(`#toc nav a[href="#${id}"]`);
+  if (!newEntry) {
+    console.error("ToC entry not found for ID:", id);
+    return;
+  }
+  newEntry.classList.add('active');
+
+  // Don't scroll the sidebar nav if the main content is not scrolled
+  const nav = document.querySelector("#td-section-nav");
+  const content = document.querySelector("html");
+  if (content.scrollTop !== 0) {
+    nav.scrollTop = newEntry.offsetTop - 100;
+  } else {
+    nav.scrollTop = 0;
+  }
+}
+
+/*
+  Track when the view is scrolled, and use this to update the highlight for the
+  corresponding ToC entry.
+*/
+window.addEventListener('DOMContentLoaded', () => {
+  // Part of the viewport is below the header so we should take it into account.
+  const headerOffset = document.querySelector("body > header > nav").clientHeight;
+  const headings = getHeadings();
+
+  const onScroll = throttle((_e) => {
+    // Update the ToC.
+    let heading = getCurrentHeading(headings, headerOffset);
+    selectTocEntry(heading.id);
+  });
+
+  // Initialize the state of the ToC.
+  onScroll();
+
+  // Listen to scroll and resizing changes.
+  document.addEventListener('scroll', onScroll, false);
+  document.addEventListener('resize', onScroll, false);
+});

assets/js/versions.template.js

@@ -0,0 +1,114 @@
+/*
+Copyright 2025 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Determine the current version as defined in hugo.toml. This will either be
+// "unstable" or "vX.X" and doesn't depend on the current URL.
+//
+// The oddity below is an attempt at producing a readable Hugo template while
+// avoiding JS syntax errors in your IDE.
+const currentVersion = `{{ if eq .Site.Params.version.status "unstable" }}
+    {{- /**/ -}}
+    unstable
+    {{- /**/ -}}
+{{ else }}
+    {{- /**/ -}}
+    {{ printf "v%s.%s" .Site.Params.version.major .Site.Params.version.minor }}
+    {{- /**/ -}}
+{{ end }}`;
+
+// Determine the current version segment by regex matching the URL. This will either
+// be "unstable", "latest", "vX.X" (production) or undefined (local & netlify).
+const href = window.location.href;
+const segmentMatches = href.match(/(?<=\/)unstable|latest|v\d+.\d+(?=\/)/);
+const currentSegment = segmentMatches ? segmentMatches[0] : undefined;
+
+// Determine the selected menu element. If we were able to obtain the version
+// segment from the URL (production), use that. Otherwise (local & netlify),
+// fall back to the version as defined in Hugo.
+const selected = currentSegment ?? currentVersion;
+
+function appendVersion(parent, name, segment, url) {
+    // The list item
+    const li = document.createElement("li");
+    if (segment === selected) {
+        li.classList.add("version-picker-selected");
+    }
+    if (segment === "latest") {
+        li.classList.add("version-picker-latest");
+    }
+    parent.appendChild(li);
+
+    // The link
+    const a = document.createElement("a");
+    a.classList.add("dropdown-item");
+    a.setAttribute("href", url);
+    li.appendChild(a);
+
+    // Handle clicks manually to preserve the current path / fragment
+    a.addEventListener("click", (ev) => {
+        // If the URL is a relative link (i.e. the historical versions changelog), just
+        // let the browser load it
+        if (url.startsWith("/")) {
+            return;
+        }
+
+        // If we couldn't determine the current segment, we cannot safely replace
+        // it and have to let the browser load the (root) URL instead
+        if (!currentSegment) {
+            return;
+        }
+
+        // Otherwise, stop further event handling and replace the segment
+        ev.preventDefault();
+        ev.stopPropagation();
+        window.location.href = href.replace(`/${currentSegment}/`, `/${segment}/`);
+    });
+
+    // The link text
+    const text = document.createTextNode(name);
+    a.appendChild(text);
+}
+
+// If we're in the unstable version, we're the latest thing and can just load
+// versions.json from our own resources. Otherwise, we fall back to loading it
+// from /unstable/versions.json, assuming we are on the spec.matrix.org deployment.
+const url = currentVersion === "unstable"
+    ? '{{ .Site.Home.Permalink }}versions.json'
+    : "/unstable/versions.json";
+
+fetch(url)
+    .then(r => r.json())
+    .then(versions => {
+        // Find the surrounding list element
+        const ul = document.querySelector("ul#version-selector");
+        if (!ul) {
+            console.error("Cannot populate version selector: ul element not found");
+            return;
+        }
+
+        // Add a entries for the unstable version and the "latest" shortcut
+        appendVersion(ul, "unstable", "unstable", "https://spec.matrix.org/unstable");
+        const latestName = versions?.length ? `latest (${versions[0].name})` : "latest";
+        appendVersion(ul, latestName, "latest", "https://spec.matrix.org/latest");
+
+        // Add an entry for each proper version
+        for (const version of versions) {
+            appendVersion(ul, version.name, version.name, `https://spec.matrix.org/${version.name}`);
+        }
+
+        // For historical versions, simply link to the changelog
+        appendVersion(ul, "historical", "historical", '{{ (site.GetPage "changelog/historical").RelPermalink }}');
+    });

assets/scss/_styles_project.scss

@@ -26,12 +26,6 @@ Custom SCSS for the Matrix spec
  */
 @import "syntax.scss";
 
-/* Workaround for https://github.com/google/docsy/issues/1116:
- * fix scroll-anchoring */
-.td-outer {
-    height: auto;
-}
-
 /* Overrides for the navbar */
 .td-navbar {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
@@ -56,6 +50,20 @@ Custom SCSS for the Matrix spec
   a {
     color: $black;
   }
+
+  /* Make the version dropdown scroll if it's too large */
+  ul#version-selector {
+    max-height: 80vh;
+    overflow-y: auto;
+  }
+
+  ul#version-selector li.version-picker-selected a {
+    font-weight: bold;
+  }
+
+  ul#version-selector li.version-picker-latest a {
+    color: $secondary;
+  }
 }
 
 /* Styles for the sidebar nav */
@@ -128,8 +136,11 @@ Custom SCSS for the Matrix spec
 }
 
 /* Customise footer */
-footer {
+.td-footer {
   box-shadow: 0px 0px 8px rgba(179, 179, 179, 0.25);
+  padding-top: 2rem;
+  color: var(--bs-body-color);
+  background-color: var(--bs-body-color-bg);
 }
 
 /* Auto numbering for headings */
@@ -246,6 +257,69 @@ footer {
 
 }
 
+.endpoints-toc {
+  summary {
+    cursor: pointer;
+    font-weight: $font-weight-bold;
+    font-size: 1.05rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .endpoint-list {
+    list-style: none;
+    padding-left: 0;
+    margin: 0;
+  }
+
+  .endpoint-list li {
+    margin: 0.2rem 0;
+  }
+
+  .endpoint-list a {
+    text-decoration: none;
+    color: inherit;
+    padding: 0.05rem 0.25rem;
+    border-radius: 0.2rem;
+
+    &:hover {
+      background-color: $secondary-background;
+    }
+  }
+
+  .endpoint-list .http-api-method {
+    margin-right: 0.35rem;
+    font-weight: $font-weight-bold;
+  }
+
+  .endpoint-path {
+    font-family: $font-family-monospace;
+    color: $secondary;
+  }
+
+  .endpoint-deprecated {
+    color: $danger;
+    font-weight: $font-weight-bold;
+    margin-left: 0.35rem;
+  }
+
+  .endpoint-module {
+    &:not(:first-child) {
+      margin-top: 0.75rem;
+    }
+  }
+
+  .endpoint-module-title {
+    // font-weight: $font-weight-bold;
+    font-size: 1.20rem;
+    margin-bottom: 0.35rem;
+  }
+}
+
+.page-description {
+  margin-bottom: 1rem;
+  color: inherit;
+}
+
 /* Styles for alert boxes */
 .alert {
   &.note {
@@ -277,29 +351,6 @@ footer {
     border-left-width: 5px;
     background: $warning-background;
   }
-
-  // XXX: See the added-in-paragraph.html shortcode for more information on these styles.
-  &.added-in-paragraph {
-    // Remove the padding and margin to remove the box look
-    margin: 0 !important; // !important on both to override table-related rules
-    padding: 0 !important;
-
-    // Make pairs of "added-in" and content inline to each other. We do pairs so authors can
-    // describe two paragraphs with added-in prefixes within a single box, reducing DOM
-    // complexity. Each paragraph is expected to be prefixed with an added-in, however.
-    //
-    // XXX: We assume the added-in and text will be rendered as paragraph elements.
-    > p {
-      display: inline;
-    }
-    > p:nth-child(2n) { // "even" rule to target just the content paragraphs
-      // Force a paragraph break after the content (insert a couple <br /> tags)
-      &::after {
-        content: '\A\A';
-        white-space: pre;
-      }
-    }
-  }
 }
 
 /* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
@@ -342,13 +393,19 @@ footer {
   h2 {
     font-weight: $font-weight-bold;
     font-size: 1.3rem;
-    margin: 3rem 0 .5rem 0;
+    margin: 1.5rem 0 1rem 0;
   }
 
   h3 {
     font-weight: $font-weight-bold;
     font-size: 1.1rem;
-    margin: 1.5rem 0 .75rem 0;
+    margin: 1.5rem 0 1rem 0;
+
+  }
+
+  /* Reduce top margin of h3 if previous sibling is a h2 */
+  h2 + h3 {
+    margin-top: 1rem;
   }
 
   hr {
@@ -393,11 +450,6 @@ footer {
       }
     }
 
-    // add some space between two tables when they are right next to each other
-    & + table {
-        margin-top: 4rem;
-    }
-
     caption {
       caption-side: top;
       color: $dark;
@@ -410,6 +462,11 @@ footer {
       border-top: 1px $table-border-color solid;
     }
 
+    td > p:last-child {
+      // Avoid unnecessary space at the bottom of the cells.
+      margin-bottom: 0;
+    }
+
     &.object-table, &.response-table, &.content-type-table {
         border: 1px $table-border-color solid;
 
@@ -464,6 +521,17 @@ footer {
     }
   }
 
+  /* Have consistent spacing around tables and examples */
+  table, .highlight {
+    margin-top: 0;
+    margin-bottom: 2rem;
+
+    /* We don't need the margin on the last child of the .rendered-data block */
+    &:last-child {
+      margin-bottom: 0;
+    } 
+  }
+
   pre {
     border: 0;
     border-left: solid 5px $secondary;
@@ -511,6 +579,13 @@ Make padding symmetrical (this selector is used in the default styles to apply p
   }
 }
 
+/* Adjust the width of math to match normal paragraphs */
+@include media-breakpoint-up(lg) {
+  .katex-display {
+    max-width: 80%;
+  }
+}
+
 /* Adjust default styles for info banner */
 .pageinfo-primary {
   @include media-breakpoint-up(lg) {

changelogs/header.md

@@ -1,15 +0,0 @@
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    VERSION  = Replaced by the version number (eg: v1.2)
-    DATE     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/VERSION">https://github.com/matrix-org/matrix-spec/tree/VERSION</a></td>
-<tr><th>Release date</th><td>DATE</td>
-<tr><th>Checklist</th><td><a href="/changelog/VERSION/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->

changelogs/internal/newsfragments/2282.clarification

@@ -0,0 +1 @@
+Replace the Twitter link in the footer with our BlueSky and Mastodon socials.

config/_default/hugo.toml

@@ -1,16 +1,14 @@
+# Default settings.
+
 baseURL = "/"
 title = "Matrix Specification"
 
-# Prepends absolute URLs with the baseURL. Useful when hosting on non-root
-# paths, such as /unstable.
-canonifyURLs = true
-
 enableRobotsTXT = true
 
 # 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", "RSS"]
+disableKinds = ["taxonomy", "rss"]
 
 [languages]
 [languages.en]
@@ -25,15 +23,15 @@ description = "Home of the Matrix specification for decentralised communication"
 [menus]
 [[menus.main]]
     name = 'Foundation'
-    url = 'https://matrix.org/foundation/'
+    url = 'https://matrix.org/foundation/about/'
     weight = 10
 [[menus.main]]
-    name = 'FAQs'
+    name = 'User Docs'
-    url = 'https://matrix.org/faq'
+    url = 'https://matrix.org/docs/'
     weight = 20
 [[menus.main]]
     name = 'Blog'
-    url = 'https://matrix.org/blog/posts'
+    url = 'https://matrix.org/blog/'
     weight = 30
 
 [markup]
@@ -45,6 +43,15 @@ description = "Home of the Matrix specification for decentralised communication"
     [markup.goldmark.renderer]
       # Enables us to render raw HTML
       unsafe = true
+    [markup.goldmark.extensions]
+      # Tell Goldmark to pass delimited blocks through the `render-passthrough` render hook.
+      # This is used to render the maths in the Olm spec.
+      # See: https://gohugo.io/functions/transform/tomath/#step-1.
+      [markup.goldmark.extensions.passthrough]
+        enable = true
+        [markup.goldmark.extensions.passthrough.delimiters]
+          block = [['\[', '\]']]
+          inline = [['\(', '\)']]
   [markup.highlight]
       # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
       # If the style is changed, remember to regenerate the CSS with:
@@ -59,24 +66,24 @@ description = "Home of the Matrix specification for decentralised communication"
 
 [params]
 copyright = "The Matrix.org Foundation CIC"
-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.
+# of the spec.
-major = "1"
+#major = "1"
-minor = "12"
+#minor = "17"
-release_date = "October 07, 2024"
+
+[[params.versions]]
+# We must include this parameter to enable docsy's version picker in the navbar. The picker
+# is populated automatically in navbar-version-selector.html.
 
 # User interface configuration
 [params.ui]
-# Set to true to disable the About link in the site footer
-footer_about_disable = false
 # Collapse HTTP API and event <details> elements
 rendered_data_collapsed = false
 # Hide the search entry in the sidebar
@@ -92,26 +99,37 @@ sidebar_menu_compact = true
 # 	icon = "fa fa-envelope"
 #         desc = "Discussion and help from your fellow users"
 # Developer relevant links. These will show up on right side of footer and in the community page if you have one.
-[[params.links.developer]]
+# [[params.links.developer]]
-	name = "GitHub"
+# 	name = "GitHub"
-	url = "https://github.com/matrix-org"
+# 	url = "https://github.com/matrix-org"
-	icon = "fab fa-github"
+# 	icon = "fab fa-github"
+#   desc = "Matrix on GitHub"
+# Custom links shown in the center of the footer. (Only supported by our fork of docsy's 'footer/central' partial.)
+[[params.links.bottom]]
+  name = "GitHub"
+  url = "https://github.com/matrix-org"
+  icon = "fab fa-github"
   desc = "Matrix on GitHub"
-[[params.links.developer]]
+[[params.links.bottom]]
-	name = "GitLab"
+  name = "GitLab"
-	url = "https://gitlab.matrix.org/matrix-org"
+  url = "https://gitlab.matrix.org/matrix-org"
-	icon = "fab fa-gitlab"
+  icon = "fab fa-gitlab"
   desc = "Matrix on GitLab"
-[[params.links.developer]]
+[[params.links.bottom]]
-	name = "YouTube"
+  name = "YouTube"
-	url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
+  url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
-	icon = "fab fa-youtube"
+  icon = "fab fa-youtube"
   desc = "Matrix YouTube channel"
-[[params.links.developer]]
+[[params.links.bottom]]
-	name = "Twitter"
+  name = "Mastodon"
-	url = "https://twitter.com/matrixdotorg"
+  url = "https://mastodon.matrix.org/@matrix"
-	icon = "fab fa-twitter"
+  icon = "fab fa-mastodon"
-  desc = "Matrix on Twitter"
+  desc = "Matrix on Mastodon"
+[[params.links.bottom]]
+  name = "Bluesky"
+  url = "https://bsky.app/profile/matrix.org"
+  icon = "fab fa-bluesky"
+  desc = "Matrix on Bluesky"
 
 
 # configuration for the hugo development server
@@ -121,7 +139,9 @@ sidebar_menu_compact = true
 [[server.headers]]
   for = '/**'
   [server.headers.values]
-    Content-Security-Policy = "default-src 'self'; style-src 'self'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
+    # `style-src 'unsafe-inline'` is needed to correctly render the maths in the Olm spec:
+    # https://github.com/KaTeX/KaTeX/issues/4096
+    Content-Security-Policy = "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
     X-XSS-Protection = "1; mode=block"
     X-Content-Type-Options = "nosniff"
     # Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
@@ -134,7 +154,7 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.117.0"
+    min = "0.146.0"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false
@@ -146,4 +166,3 @@ sidebar_menu_compact = true
     mediaType = "text/markdown"
     isPlainText = true
     baseName = "checklist"
-    notAlternative = true

config/production/hugo.toml

@@ -0,0 +1,6 @@
+# Settings only required when the website is built for production.
+
+# Enable stats to use them to optimize the CSS.
+[build]
+  [build.buildStats]
+    enable = true

content/_index.md

@@ -25,6 +25,7 @@ The specification consists of the following parts:
 * [Identity Service API](/identity-service-api)
 * [Push Gateway API](/push-gateway-api)
 * [Room Versions](/rooms)
+* [Olm & Megolm](/olm-megolm)
 * [Appendices](/appendices)
 
 Additionally, this introduction page contains the key baseline
@@ -56,9 +57,6 @@ The principles that Matrix attempts to follow are:
         the global Matrix network
     -   Fully open standard - publicly documented standard with no IP or
         patent licensing encumbrances
-    -   Fully open source reference implementation - liberally-licensed
-        example implementations with no IP or patent licensing
-        encumbrances
 -   Empowering the end-user
     -   The user should be able to choose the server and clients they
         use
@@ -154,7 +152,7 @@ request.
 
 How data flows between clients:
 
-```
+```nohighlight
     { Matrix client A }                             { Matrix client B }
         ^          |                                    ^          |
         |  events  |  Client-Server API                 |  events  |
@@ -507,18 +505,23 @@ For historical reference, the APIs were versioned as `rX.Y.Z` where `X`
 roughly represents a breaking change, `Y` a backwards-compatible change, and
 `Z` a patch or insignificant alteration to the API.
 
-`v1.0` of Matrix was released on June 10th, 2019 with the following API
+The current global versioning system was introduced with `v1.1`.
-versions:
+[Matrix 1.0](https://matrix.org/blog/2019/06/11/introducing-matrix-1-0-and-the-matrix-org-foundation/)
+did not correspond directly to a specification version; instead, it was based on
+the following versions for the individual APIs:
 
-| API/Specification       | Version |
+| API/Specification        | Version       |
-|-------------------------|---------|
+|--------------------------|---------------|
-| Client-Server API       | r0.5.0  |
+| Client-Server API        | r0.5.0        |
-| Server-Server API       | r0.1.2  |
+| Server-Server API        | r0.1.2        |
-| Application Service API | r0.1.1  |
+| Application Service API  | r0.1.1        |
-| Identity Service API    | r0.1.1  |
+| Identity Service API     | r0.2.0        |
-| Push Gateway API        | r0.1.0  |
+| Push Gateway API         | r0.1.0        |
-| Room Version            | v5      |
+| Room Versions            | 1, 2, 3, 4, 5 |
 
+`v1.0` should **not** be returned by servers in the
+[`GET /_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
+response.
 
 ## License
 

content/appendices.md

@@ -611,10 +611,18 @@ characters permitted in user ID localparts. There are currently active
 users whose user IDs do not conform to the permitted character set, and
 a number of rooms whose history includes events with a `sender` which
 does not conform. In order to handle these rooms successfully, clients
-and servers MUST accept user IDs with localparts from the expanded
+and servers MUST accept user IDs with localparts consisting of any legal
-character set:
+non-surrogate Unicode code points except for `:` and `NUL` (U+0000), including other control
+characters and the empty string.
 
-    extended_user_id_char = %x21-39 / %x3B-7E  ; all ASCII printing chars except :
+User IDs with localparts containing characters outside the range U+0021 to U+007E, or with
+an empty localpart, are considered non-compliant. For current room versions, servers must
+still accept events using such user IDs over federation; however they SHOULD NOT forward
+such user IDs to clients when referenced outside the context of an event. For example,
+device list updates from non-compliant user IDs would be dropped by the receiving server.
+
+A future room version may prevent users using a historical character set
+from participating. Use of the historical character set is *deprecated*.
 
 ##### Mapping from other character sets
 
@@ -649,22 +657,48 @@ provides no way to encode ASCII punctuation).
 
 #### Room IDs
 
-A room has exactly one room ID. A room ID has the format:
+{{% changed-in v="1.16" %}} Room IDs can now appear without a domain depending on
+the room version.
+
+A room has exactly one room ID. Room IDs take the form:
+
+    !opaque_id
+
+However, the precise format depends upon the [room version specification](/rooms):
+some room versions included a `domain` component, whereas more recent room versions
+omit the domain and use a base64-encoded hash instead.
+
+Room IDs are case-sensitive and not meant to be human-readable. They are intended
+to be used as fully opaque strings by clients, even when a `domain` component is
+present.
+
+If the room version requires a `domain` component, room IDs take the following
+form:
 
     !opaque_id:domain
 
-The `domain` of a room ID is the [server name](#server-name) of the
+In such a form, the `opaque_id` is a localpart. The localpart MUST only contain
-homeserver which created the room. The domain is used only for
+valid non-surrogate Unicode code points, including control characters, except `:`
-namespacing to avoid the risk of clashes of identifiers between
+and `NUL` (U+0000). The localpart SHOULD only consist of alphanumeric characters
-different homeservers. There is no implication that the room in
+(`A-Z`, `a-z`, `0-9`) when generating them. The `domain` is the [server name](#server-name)
-question is still available at the corresponding homeserver.
+of the homeserver which created the room - it is only used to reduce namespace
+collisions. There is no implication that the room in question is still available
+at the corresponding homeserver. Combined, the localpart, domain, and `!` sigil
+MUST NOT exceed 255 bytes.
 
-Room IDs are case-sensitive. They are not meant to be
+When a room version requires the `domain`-less format, room IDs are simply the
-human-readable. They are intended to be treated as fully opaque strings
+[event ID](#event-ids) of the `m.room.create` event using `!` as the sigil instead
-by clients.
+of `$`. The grammar is otherwise inherited verbatim.
 
-The length of a room ID, including the `!` sigil and the domain, MUST
+{{% boxes/note %}}
-NOT exceed 255 bytes.
+Applications which previously relied upon the `domain` in a room ID can instead
+parse the [user IDs](#user-identifiers) found in the `m.room.create` event's `sender`.
+
+Though the `m.room.create` event's `additional_creators` (in `content`) may be
+used when present, applications should take care when parsing or interpreting the
+list. The user IDs in `additional_creators` will have correct grammar, but may
+not be real users or may not belong to actual Matrix homeservers.
+{{% /boxes/note %}}
 
 #### Room Aliases
 
@@ -676,6 +710,9 @@ The `domain` of a room alias is the [server name](#server-name) of the
 homeserver which created the alias. Other servers may contact this
 homeserver to look up the alias.
 
+The localpart of a room alias may contain any valid non-surrogate Unicode codepoints
+except `:` and `NUL`.
+
 The length of a room alias, including the `#` sigil and the domain, MUST
 NOT exceed 255 bytes.
 
@@ -712,13 +749,13 @@ history (a permalink).
 
 The Matrix URI scheme is defined as follows (`[]` enclose optional parts, `{}`
 enclose variables):
-```
+```nohighlight
 matrix:[//{authority}/]{type}/{id without sigil}[/{type}/{id without sigil}...][?{query}][#{fragment}]
 ```
 
 As a schema, this can be represented as:
 
-```
+```nohighlight
 MatrixURI = "matrix:" hier-part [ "?" query ] [ "#" fragment ]
 hier-part = [ "//" authority "/" ] path
 path = entity-descriptor ["/" entity-descriptor]
@@ -761,7 +798,7 @@ wish to consider handling them as `u`, `r`, and `e` respectively.
 {{% /boxes/note %}}
 
 {{% boxes/note %}}
-{{< changed-in v="1.11" >}}
+{{% changed-in v="1.11" %}}
 Referencing event IDs within a room identified by room alias (`r`) rather than room ID
 (`roomid`) is now deprecated.  We are not aware of these ever having been used in
 practice, and are nonsensical given room aliases are mutable.
@@ -828,7 +865,7 @@ below for more details.
 A matrix.to URI has the following format, based upon the specification
 defined in [RFC 3986](https://tools.ietf.org/html/rfc3986):
 
-```
+```nohighlight
 https://matrix.to/#/<identifier>/<extra parameter>?<additional arguments>
 ```
 
@@ -858,7 +895,7 @@ Examples of matrix.to URIs are:
 * Link to `@alice:example.org`: `https://matrix.to/#/%40alice%3Aexample.org`
 
 {{% boxes/note %}}
-{{< changed-in v="1.11" >}}
+{{% changed-in v="1.11" %}}
 Referencing event IDs within a room identified by room alias rather than room ID
 is now deprecated.  We are not aware of these ever having been used in
 practice, and are nonsensical given room aliases are mutable.
@@ -900,8 +937,8 @@ A room (or room permalink) which isn't using a room alias should supply
 at least one server using `via` in the URI's query string. Multiple servers
 can be specified by including multuple `via` parameters.
 
-The values of `via` are intended to be passed along as the `server_name`
+The values of `via` are intended to be passed along on the
-parameters on the [Client Server `/join/{roomIdOrAlias}` API](/client-server-api/#post_matrixclientv3joinroomidoralias).
+[Client Server `/join/{roomIdOrAlias}` API](/client-server-api/#post_matrixclientv3joinroomidoralias).
 
 When generating room links and permalinks, the application should pick
 servers which have a high probability of being in the room in the

content/application-service-api.md

@@ -2,16 +2,14 @@
 title: "Application Service API"
 weight: 30
 type: docs
+description: |
+  The Matrix client-server API and server-server APIs provide a consistent,
+  self-contained federated messaging fabric but leave little room for custom
+  server-side behaviour such as gateways, filters, or extensible hooks. The
+  Application Service API defines a standard way to add this extensible
+  functionality, independent of the underlying homeserver implementation.
 ---
 
-The Matrix client-server API and server-server APIs provide the means to
-implement a consistent self-contained federated messaging fabric.
-However, they provide limited means of implementing custom server-side
-behaviour in Matrix (e.g. gateways, filters, extensible hooks etc). The
-Application Service API (AS API) defines a standard API to allow such
-extensible functionality to be implemented irrespective of the
-underlying homeserver implementation.
-
 ## Application Services
 
 Application services are passive and can only observe events from the
@@ -178,13 +176,13 @@ The application service API provides a transaction API for sending a
 list of events. Each list of events includes a transaction ID, which
 works as follows:
 
-```
+```nohighlight
     Typical
     HS ---> AS : Homeserver sends events with transaction ID T.
        <---    : Application Service sends back 200 OK.
 ```
 
-```
+```nohighlight
     AS ACK Lost
     HS ---> AS : Homeserver sends events with transaction ID T.
        <-/-    : AS 200 OK is lost.
@@ -207,6 +205,39 @@ processed the events.
 
 {{% http-api spec="application-service" api="transactions" %}}
 
+##### Pushing ephemeral data
+
+{{% added-in v="1.13" %}}
+
+If the `receive_ephemeral` settings is enabled in the [registration](#registration)
+file, homeservers MUST send ephemeral data that is relevant to the application
+service via the transaction API, using the `ephemeral` property of the request's
+body. This property is an array that is effectively a combination of the
+`presence` and `ephemeral` sections of the client-server [`/sync`](/client-server-api/#get_matrixclientv3sync)
+API.
+
+There are currently three event types that can be delivered to an application
+service:
+
+- **[`m.presence`](/client-server-api/#mpresence)**: MUST be sent to the
+application service if the data would apply contextually. For example, a
+presence update for a user an application service shares a room with, or
+matching one of the application service's namespaces.
+- **[`m.typing`](/client-server-api/#mtyping)**: MUST be sent to the application
+service under the same rules as regular events, meaning that the application
+service must have registered interest in the room itself, or in a user that is
+in the room. The data MUST use the same format as the client-server API, with
+the addition of a `room_id` property at the top level to identify the room that
+they were sent in.
+- **[`m.receipt`](/client-server-api/#mreceipt)**: MUST be sent to the
+application service under the same rules as regular events, meaning that the
+application service must have registered interest in the room itself, or in a
+user that is in the room. The data MUST use the same format as the client-server
+API, with the addition of a `room_id` property at the top level to identify the
+room that they were sent in. [Private read receipts](/client-server-api/#private-read-receipts)
+MUST only be sent for users matching one of the application service's
+namespaces. Normal read receipts and threaded read receipts are always sent.
+
 #### Pinging
 
 {{% added-in v="1.7" %}}
@@ -225,7 +256,7 @@ have been omitted for brevity):
 
 **Typical**
 
-```
+```nohighlight
 AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
     HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
     HS <--- AS : 200 OK {}
@@ -234,7 +265,7 @@ AS <--- HS : 200 OK {"duration_ms": 123}
 
 **Incorrect `hs_token`**
 
-```
+```nohighlight
 AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
     HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
     HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"}
@@ -243,7 +274,7 @@ AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body":
 
 **Can't connect to appservice**
 
-```
+```nohighlight
 AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
     HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
 AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"}
@@ -323,6 +354,7 @@ service would like to masquerade as.
 Inputs:
 -   Application service token (`as_token`)
 -   User ID in the AS namespace to act as.
+-   Device ID belonging to the User ID to act with.
 
 Notes:
 -   This applies to all aspects of the Client-Server API, except for
@@ -342,9 +374,19 @@ service's `user` namespaces. If the parameter is missing, the homeserver
 is to assume the application service intends to act as the user implied
 by the `sender_localpart` property of the registration.
 
+{{% added-in v="1.17" %}} Application services MAY similarly masquerade
+as a specific device ID belonging the user ID through use of the `device_id`
+query string parameter on the request. If the given device ID is not known
+to belong to the user, the server will return a 400 `M_UNKNOWN_DEVICE` error.
+If no `user_id` is supplied, the `device_id` MUST belong to the user implied
+by the `sender_localpart` property of the application service's registration.
+If no `device_id` is supplied, the homeserver is to assume the request is
+being made without a device ID and will fail to complete operations which
+require a device ID (such as uploading one-time keys).
+
 An example request would be:
 
-    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org
+    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org&device_id=ABC123
     Authorization: Bearer YourApplicationServiceTokenHere
 
 #### Timestamp massaging
@@ -384,6 +426,8 @@ imports and similar behaviour).
 
 #### Server admin style permissions
 
+{{% changed-in v="1.17" %}}
+
 The homeserver needs to give the application service *full control* over
 its namespace, both for users and for room aliases. This means that the
 AS should be able to manage any users and room alias in its namespace. No additional API
@@ -400,33 +444,59 @@ achieved by including the `as_token` on a `/register` request, along
 with a login type of `m.login.application_service` to set the desired
 user ID without a password.
 
-    POST /_matrix/client/v3/register
+```http
-    Authorization: Bearer YourApplicationServiceTokenHere
+POST /_matrix/client/v3/register
+Authorization: Bearer YourApplicationServiceTokenHere
+```
 
-    Content:
+```json
-    {
+{
-      type: "m.login.application_service",
+  "type": "m.login.application_service",
-      username: "_irc_example"
+  "username": "_irc_example"
-    }
+}
+```
 
-Similarly, logging in as users needs API changes in order to allow the AS to
+{{% boxes/note %}}
-log in without needing the user's password. This is achieved by including the
+{{% added-in v="1.17" %}}
-`as_token` on a `/login` request, along with a login type of
+Servers MUST still allow application services to use the `/register` endpoint
-`m.login.application_service`:
+with a login type of `m.login.application_service` even if they don't support
+the [Legacy Authentication API](/client-server-api/#legacy-api).
+
+In that case application services MUST set the `"inhibit_login": true` parameter
+as they cannot use it to log in as users. If the `inhibit_login` parameter is
+not set to `true`, the server MUST return a 400 HTTP status code with an
+`M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
+{{% /boxes/note %}}
+
+Similarly, logging in as users using the [Legacy authentication API](/client-server-api/#legacy-api)
+needs API changes in order to allow the AS to log in without needing the user's
+password. This is achieved by including the `as_token` on a `/login` request,
+along with a login type of `m.login.application_service`:
 
 {{% added-in v="1.2" %}}
 
-    POST /_matrix/client/v3/login
+```http
-    Authorization: Bearer YourApplicationServiceTokenHere
+POST /_matrix/client/v3/login
+Authorization: Bearer YourApplicationServiceTokenHere
+```
 
-    Content:
+```json
-    {
+{
-      type: "m.login.application_service",
+  "type": "m.login.application_service",
-      "identifier": {
+  "identifier": {
-        "type": "m.id.user",
+    "type": "m.id.user",
-        "user": "_irc_example"
+    "user": "_irc_example"
-      }
+  }
-    }
+}
+```
+
+{{% boxes/note %}}
+{{% added-in v="1.17" %}}
+Application services MUST NOT use the `/login` endpoint if the server doesn't
+support the Legacy authentication API. If `/login` is called with the
+`m.login.application_service` login type the server MUST return a 400 HTTP
+status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
+{{% /boxes/note %}}
 
 Application services which attempt to create users or aliases *outside*
 of their defined namespaces, or log in as users outside of their defined
@@ -459,15 +529,47 @@ via the query string). It is expected that the application service use
 the transactions pushed to it to handle events rather than syncing with
 the user implied by `sender_localpart`.
 
-#### Application service room directories
+#### Published room directories
 
-Application services can maintain their own room directories for their
+Application services can maintain their own published room directories for
-defined third-party protocols. These room directories may be accessed by
+their defined third-party protocols. These directories may be accessed by
 clients through additional parameters on the `/publicRooms`
 client-server endpoint.
 
 {{% http-api spec="client-server" api="appservice_room_directory" %}}
 
+#### Device management
+
+{{% added-in v="1.17" %}}
+
+Application services need to be able to create and delete devices to manage the
+encryption for their users without having to rely on `/login`, which also
+generates an access token for the user, and which might not be available for
+homeservers that only support the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+
+##### Creating devices
+
+Application services can use the [`PUT /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#put_matrixclientv3devicesdeviceid)
+endpoint to create new devices.
+
+##### Deleting devices
+
+The following endpoints used to delete devices MUST NOT require [User-Interactive
+Authentication](/client-server-api/#user-interactive-authentication-api) when
+used by an application service:
+
+* [`DELETE /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#delete_matrixclientv3devicesdeviceid)
+* [`POST /_matrix/client/v3/delete_devices`](/client-server-api/#post_matrixclientv3delete_devices)
+
+#### Cross-signing
+
+{{% added-in v="1.17" %}}
+
+Appservices need to be able to verify themselves and replace their cross-signing
+keys, so the [`POST /_matrix/client/v3/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload)
+endpoint MUST NOT require [User-Interactive Authentication](/client-server-api/#user-interactive-authentication-api)
+when used by an application service, even if cross-signing keys already exist.
+
 ### Referencing messages from a third-party network
 
 Application services should include an `external_url` in the `content`

content/changelog/_index.md

@@ -1,7 +1,8 @@
 ---
 title: Changelog
 type: docs
+layout: changelog-index
 weight: 1000
 ---
 
-{{% changelog/changelogs %}}
+<!-- This page will be redirected to the latest version's changelog -->

content/changelog/v1.1.md

@@ -2,26 +2,13 @@
 title: v1.1 Changelog
 linkTitle: v1.1
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2021-11-09T00:00:00+0000
+date: 2021-11-09
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.1  = Replaced by the version number (eg: v1.2)
-    November 09, 2021     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.1">https://github.com/matrix-org/matrix-doc/tree/v1.1</a></td>
-<tr><th>Release date</th><td>November 09, 2021</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.1/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.10.md

@@ -2,26 +2,12 @@
 title: v1.10 Changelog
 linkTitle: v1.10
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2024-03-22T09:59:45-06:00
+date: 2024-03-22
 ---
-<!--
-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)
--->
-
-<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>
-<tr><th>Checklist</th><td><a href="/changelog/v1.10/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.11.md

@@ -2,26 +2,12 @@
 title: v1.11 Changelog
 linkTitle: v1.11
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2024-06-20T10:20:43-06:00
+date: 2024-06-20
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.11  = Replaced by the version number (eg: v1.2)
-    June 20, 2024     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.11">https://github.com/matrix-org/matrix-spec/tree/v1.11</a></td>
-<tr><th>Release date</th><td>June 20, 2024</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.11/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.12.md

@@ -2,26 +2,12 @@
 title: v1.12 Changelog
 linkTitle: v1.12
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2024-10-07T13:32:03-06:00
+date: 2024-10-07
 ---
-<!--
-This is a header file for the generated changelog.
-
-Variables:
-    v1.12  = Replaced by the version number (eg: v1.2)
-    October 07, 2024     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.12">https://github.com/matrix-org/matrix-spec/tree/v1.12</a></td>
-<tr><th>Release date</th><td>October 07, 2024</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.12/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.13.md

@@ -0,0 +1,108 @@
+---
+title: v1.13 Changelog
+linkTitle: v1.13
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2024-12-19
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `POST /_matrix/client/v3/rooms/{roomId}/report`, as per [MSC4151](https://github.com/matrix-org/matrix-spec-proposals/pull/4151). ([#1938](https://github.com/matrix-org/matrix-spec/issues/1938), [#2028](https://github.com/matrix-org/matrix-spec/issues/2028))
+
+**Backwards Compatible Changes**
+
+- Add error codes to requestToken endpoints, as per [MSC4178](https://github.com/matrix-org/matrix-spec-proposals/pull/4178). ([#1944](https://github.com/matrix-org/matrix-spec/issues/1944))
+- Remove reply fallbacks, as per [MSC2781](https://github.com/matrix-org/matrix-spec-proposals/issues/2781). ([#1994](https://github.com/matrix-org/matrix-spec/issues/1994))
+- Clarify the allowed HTTP methods in CORS responses, as per [MSC4138](https://github.com/matrix-org/matrix-spec-proposals/pull/4138). ([#1995](https://github.com/matrix-org/matrix-spec/issues/1995), [#2011](https://github.com/matrix-org/matrix-spec/issues/2011))
+- Add new `M_USER_SUSPENDED` error code behaviour, as per [MSC3823](https://github.com/matrix-org/matrix-spec-proposals/pull/3823). ([#2014](https://github.com/matrix-org/matrix-spec/issues/2014))
+
+**Spec Clarifications**
+
+- The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank, as per [MSC2414](https://github.com/matrix-org/matrix-spec-proposals/pull/2414). ([#1938](https://github.com/matrix-org/matrix-spec/issues/1938))
+- Correct OpenAPI specification for query parameters to `GET /_matrix/client/v3/thirdparty/location/{protocol}` endpoint. ([#1947](https://github.com/matrix-org/matrix-spec/issues/1947))
+- Sort VoIP events semantically. ([#1967](https://github.com/matrix-org/matrix-spec/issues/1967))
+- Clarify that servers must forward custom keys in `PusherData` when sending notifications to the push gateway. ([#1973](https://github.com/matrix-org/matrix-spec/issues/1973))
+- Clarify formats of string types. ([#1978](https://github.com/matrix-org/matrix-spec/issues/1978), [#1979](https://github.com/matrix-org/matrix-spec/issues/1979), [#1980](https://github.com/matrix-org/matrix-spec/issues/1980))
+- Clarify that the async upload endpoint will return 404 in some cases. ([#1983](https://github.com/matrix-org/matrix-spec/issues/1983))
+- Remove distinction between `StateFilter` and `RoomEventFilter`. ([#2015](https://github.com/matrix-org/matrix-spec/issues/2015))
+- Add hyperlinks throughout the specification. ([#2016](https://github.com/matrix-org/matrix-spec/issues/2016))
+- Use `json` instead of `json5` for syntax highlighting. ([#2017](https://github.com/matrix-org/matrix-spec/issues/2017))
+- Specify order that one-time keys are issued by `/keys/claim`, as per [MSC4225](https://github.com/matrix-org/matrix-spec-proposals/pull/4225). ([#2029](https://github.com/matrix-org/matrix-spec/issues/2029))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Make ACLs apply to EDUs, as per [MSC4163](https://github.com/matrix-org/matrix-spec-proposals/pull/4163). ([#2004](https://github.com/matrix-org/matrix-spec/issues/2004))
+
+**Spec Clarifications**
+
+- Add 403 error response to `/_matrix/federation/v1/state_ids/{roomId}`. ([#1926](https://github.com/matrix-org/matrix-spec/issues/1926))
+
+
+## Application Service API
+
+**Backwards Compatible Changes**
+
+- Allow sending ephemeral data to application services, as per [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409). ([#2018](https://github.com/matrix-org/matrix-spec/issues/2018))
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+**Spec Clarifications**
+
+- Document the schema of `PusherData`. ([#1968](https://github.com/matrix-org/matrix-spec/issues/1968))
+- The path of HTTP pusher URLs is fixed to `/_matrix/push/v1/notify`. ([#1974](https://github.com/matrix-org/matrix-spec/issues/1974))
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- Clarify rule 4.3.1 of the auth rules in room version 11 to state which event's `sender` the `state_key` needs to match. ([#2024](https://github.com/matrix-org/matrix-spec/issues/2024))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Remove note about reference implementations. ([#1966](https://github.com/matrix-org/matrix-spec/issues/1966))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Add `x-weight` property for sorting events rendered with the `event-group` shortcode. ([#1967](https://github.com/matrix-org/matrix-spec/issues/1967))
+- Enforce consistent vertical spacing between paragraphs in endpoint definitions. ([#1969](https://github.com/matrix-org/matrix-spec/issues/1969), [#2005](https://github.com/matrix-org/matrix-spec/issues/2005))
+- Remove `boxes/added-in-paragraph` shortcode. ([#1970](https://github.com/matrix-org/matrix-spec/issues/1970))
+- Remove `withVersioning` parameter of `rver-fragment` shortcode. ([#1971](https://github.com/matrix-org/matrix-spec/issues/1971))
+- Remove `span` element from `added-in` and `changed-in` shortcodes. ([#1972](https://github.com/matrix-org/matrix-spec/issues/1972))
+- Fix formatting of `added-in` and `changed-in` shortcodes by using `%` delimiter. ([#1975](https://github.com/matrix-org/matrix-spec/issues/1975))
+- Remove CSS workaround for scroll-anchoring. ([#1976](https://github.com/matrix-org/matrix-spec/issues/1976))
+- Rename `custom-formats.yaml` to `string-formats.yaml` and update its docs. ([#1977](https://github.com/matrix-org/matrix-spec/issues/1977))
+- Fix relative URLs when serving the specification with a custom `baseURL`. ([#1984](https://github.com/matrix-org/matrix-spec/issues/1984), [#1997](https://github.com/matrix-org/matrix-spec/issues/1997))
+- Rename `.htmltest.yaml` to `.htmltest.yml`. ([#1985](https://github.com/matrix-org/matrix-spec/issues/1985))
+- Improve the JS script to highlight the current ToC entry. ([#1991](https://github.com/matrix-org/matrix-spec/issues/1991), [#2002](https://github.com/matrix-org/matrix-spec/issues/2002))
+- Upgrade docsy to 0.11.0 and hugo to 0.139.0. ([#1996](https://github.com/matrix-org/matrix-spec/issues/1996), [#2007](https://github.com/matrix-org/matrix-spec/issues/2007))
+- Improve the quality of the rendered diagrams ([#1999](https://github.com/matrix-org/matrix-spec/issues/1999))
+- Update the Inter font and allow the browser to render the page before it is loaded ([#2000](https://github.com/matrix-org/matrix-spec/issues/2000))
+- Use a proper Matrix favicon ([#2001](https://github.com/matrix-org/matrix-spec/issues/2001))
+- Clean up unused CSS classes in `openapi/render-operation` partial. ([#2003](https://github.com/matrix-org/matrix-spec/issues/2003))
+- Fix `changed-in` partial when used with multiple paragraphs. ([#2006](https://github.com/matrix-org/matrix-spec/issues/2006))
+- Optimize generated CSS by removing unused selectors. ([#2008](https://github.com/matrix-org/matrix-spec/issues/2008))
+- Remove trailing slash on void HTML elements. ([#2009](https://github.com/matrix-org/matrix-spec/issues/2009))
+- Remove `type` and `language` attributes of `script` element. ([#2021](https://github.com/matrix-org/matrix-spec/issues/2021))
+- Change the accessible role of info boxes to `note`. ([#2022](https://github.com/matrix-org/matrix-spec/issues/2022))

content/changelog/v1.14.md

@@ -0,0 +1,93 @@
+---
+title: v1.14 Changelog
+linkTitle: v1.14
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-03-27
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093))
+
+**Removed Endpoints**
+
+- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059))
+
+**Spec Clarifications**
+
+- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036))
+- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038))
+- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046))
+- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091))
+- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051))
+- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055))
+- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064))
+- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072))
+
+
+## Server-Server API
+
+**Spec Clarifications**
+
+- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050))
+- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063))
+- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
+
+
+## Application Service API
+
+No significant changes.
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Backwards Compatible Changes**
+
+- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105))
+
+**Spec Clarifications**
+
+- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
+- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
+- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
+- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033))
+- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041))
+- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042))
+- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045))
+- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049))
+- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061))
+- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069))
+- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073))
+- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074))
+- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
+- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078))

content/changelog/v1.15.md

@@ -0,0 +1,97 @@
+---
+title: v1.15 Changelog
+linkTitle: v1.15
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-06-26
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `GET /_matrix/client/v1/room_summary/{roomIdOrAlias}`, as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+- Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965). ([#2147](https://github.com/matrix-org/matrix-spec/issues/2147))
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147). ([#2122](https://github.com/matrix-org/matrix-spec/issues/2122))
+- Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125), [#2158](https://github.com/matrix-org/matrix-spec/issues/2158))
+- Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals. ([#2141](https://github.com/matrix-org/matrix-spec/issues/2141), [#2148](https://github.com/matrix-org/matrix-spec/issues/2148), [#2149](https://github.com/matrix-org/matrix-spec/issues/2149), [#2150](https://github.com/matrix-org/matrix-spec/issues/2150), [#2151](https://github.com/matrix-org/matrix-spec/issues/2151), [#2159](https://github.com/matrix-org/matrix-spec/issues/2159), [#2164](https://github.com/matrix-org/matrix-spec/issues/2164))
+
+**Spec Clarifications**
+
+- Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty. ([#2068](https://github.com/matrix-org/matrix-spec/issues/2068))
+- Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places. ([#2077](https://github.com/matrix-org/matrix-spec/issues/2077))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- "Public" rooms in profile look-ups are defined through their join rule and history visibility. ([#2101](https://github.com/matrix-org/matrix-spec/issues/2101))
+- "Public" rooms in user directory queries are defined through their join rule and history visibility. ([#2102](https://github.com/matrix-org/matrix-spec/issues/2102))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- "Public" rooms with respect to call invites are defined through their join rule. ([#2106](https://github.com/matrix-org/matrix-spec/issues/2106))
+- "Public" rooms have no specific meaning with respect to moderation policy lists. ([#2107](https://github.com/matrix-org/matrix-spec/issues/2107))
+- "Public" rooms with respect to presence are defined through their join rule. ([#2108](https://github.com/matrix-org/matrix-spec/issues/2108))
+- Spaces are subject to the same access mechanisms as rooms. ([#2109](https://github.com/matrix-org/matrix-spec/issues/2109))
+- Fix various typos throughout the specification. ([#2121](https://github.com/matrix-org/matrix-spec/issues/2121), [#2144](https://github.com/matrix-org/matrix-spec/issues/2144))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+- Add missing fields in example for `ExportedSessionData`. ([#2154](https://github.com/matrix-org/matrix-spec/issues/2154))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+
+**Spec Clarifications**
+
+- Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room. ([#2067](https://github.com/matrix-org/matrix-spec/issues/2067))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`. ([#2100](https://github.com/matrix-org/matrix-spec/issues/2100))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- Fix various typos throughout the specification. ([#2128](https://github.com/matrix-org/matrix-spec/issues/2128))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Clarify in the application service registration schema the `url: null` behaviour. ([#2130](https://github.com/matrix-org/matrix-spec/issues/2130))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Clarify that public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+No significant changes.
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Adjust margins in rendered endpoints. ([#2081](https://github.com/matrix-org/matrix-spec/issues/2081))
+- Replace Hugo shortcodes in OpenAPI output. ([#2088](https://github.com/matrix-org/matrix-spec/issues/2088))
+- Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks. ([#2115](https://github.com/matrix-org/matrix-spec/issues/2115))
+- Fix the historical info box when generating the historical spec in CI. ([#2123](https://github.com/matrix-org/matrix-spec/issues/2123))
+- Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks. ([#2137](https://github.com/matrix-org/matrix-spec/issues/2137))

content/changelog/v1.16.md

@@ -0,0 +1,103 @@
+---
+title: v1.16 Changelog
+linkTitle: v1.16
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-09-17
+---
+
+## Client-Server API
+
+**Deprecations**
+
+- Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
+
+**Removed Endpoints**
+
+- Remove unintentional intentional mentions in replies, as per [MSC4142](https://github.com/matrix-org/matrix-spec-proposals/pull/4142). ([#2210](https://github.com/matrix-org/matrix-spec/issues/2210))
+
+**Backwards Compatible Changes**
+
+- Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
+- Add `format` query parameter to `GET /state/{eventType}/{stateKey}` to allow fetching metadata of a specific state event. ([#2175](https://github.com/matrix-org/matrix-spec/issues/2175))
+- Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222). ([#2187](https://github.com/matrix-org/matrix-spec/issues/2187))
+- When upgrading rooms to [room version 12](/rooms/v12), `additional_creators` may be specified on the [`POST /_matrix/client/v3/rooms/{roomId}/upgrade`](/client-server-api/#post_matrixclientv3roomsroomidupgrade) endpoint, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- When creating rooms with [room version 12](/rooms/v12), the `trusted_private_chat` preset should merge the invitees into the supplied `content.additional_creators` in the resulting room, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- In [room version 12](/rooms/v12), the power level of room creators is now infinitely high as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- In [room version 12](/rooms/v12), room IDs no longer have a domain component as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- When creating rooms with [room version 12](/rooms/v12), the initial power levels will restrict the ability to upgrade rooms by default, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Add a profile field for a user's time zone, as per [MSC4175](https://github.com/matrix-org/matrix-spec-proposals/pull/4175). ([#2206](https://github.com/matrix-org/matrix-spec/issues/2206))
+- Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
+
+**Spec Clarifications**
+
+- Clarify that `format` is required if `formatted_body` is specified. ([#2167](https://github.com/matrix-org/matrix-spec/issues/2167))
+- The `latest_event` in an aggregated set of thread events uses the same format as the event itself. ([#2169](https://github.com/matrix-org/matrix-spec/issues/2169))
+- Fix various typos throughout the specification. ([#2171](https://github.com/matrix-org/matrix-spec/issues/2171), [#2177](https://github.com/matrix-org/matrix-spec/issues/2177), [#2179](https://github.com/matrix-org/matrix-spec/issues/2179))
+- Clarify that clients should replace events with the most recent replacement by `origin_server_ts`. ([#2190](https://github.com/matrix-org/matrix-spec/issues/2190))
+- Fix `/sync` flow referencing incorrect parameter to use with `/messages`. ([#2195](https://github.com/matrix-org/matrix-spec/issues/2195))
+- Clarify wording around the `world_readable` history visibility setting. Contributed by @HarHarLinks. ([#2204](https://github.com/matrix-org/matrix-spec/issues/2204))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- `invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
+
+
+## Application Service API
+
+No significant changes.
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Backwards Compatible Changes**
+
+- Room IDs in room version 12 are now the event ID of the create event with the normal room ID sigil (`!`), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Room creators are formalized in room version 12 and have infinitely high power level, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- State Resolution is updated in room version 12 to reduce the opportunity for "state resets", as per [MSC4297](https://github.com/matrix-org/matrix-spec-proposals/pull/4297). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- The default room version is now room version 12, though servers SHOULD keep using room version 11 for a little while, as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193), [#2199](https://github.com/matrix-org/matrix-spec/issues/2199))
+
+**Spec Clarifications**
+
+- In room versions 1 through 12, an event's `auth_events` have always needed to belong to the same room as per [MSC4307](https://github.com/matrix-org/matrix-spec-proposals/pull/4307). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+
+
+## Appendices
+
+**Backwards Compatible Changes**
+
+- Room IDs can now appear without a domain component in [room version 12](/rooms/v12), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+
+
+## Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Add "placeholder MSC" process definition. ([#2157](https://github.com/matrix-org/matrix-spec/issues/2157))
+
+**Spec Clarifications**
+
+- Declare the Application Service Registration schema to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
+- Declare the event schemas to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
+- Upgrade the docsy theme to version 0.12.0. ([#2160](https://github.com/matrix-org/matrix-spec/issues/2160))
+- GitHub actions are now building the OpenAPI `spec/identity-service-api/api.json` file. ([#2172](https://github.com/matrix-org/matrix-spec/issues/2172))
+- Minor fixes to JSON schemas. ([#2182](https://github.com/matrix-org/matrix-spec/issues/2182))
+- Specify a correct spelling for "display name". ([#2189](https://github.com/matrix-org/matrix-spec/issues/2189))
+- Fix a grammatical typo on the Matrix Spec Process documentation page. ([#2205](https://github.com/matrix-org/matrix-spec/issues/2205))

content/changelog/v1.17.md

@@ -0,0 +1,91 @@
+---
+title: v1.17 Changelog
+linkTitle: v1.17
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-12-18
+---
+
+## Client-Server API
+
+**Removed Endpoints**
+
+- Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210). ([#2186](https://github.com/matrix-org/matrix-spec/issues/2186))
+
+**Backwards Compatible Changes**
+
+- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
+- Add the `m.oauth` authentication type for User-Interactive Authentication, as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312). ([#2234](https://github.com/matrix-org/matrix-spec/issues/2234))
+- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
+
+**Spec Clarifications**
+
+- Push rule IDs are globally unique within their kind. ([#2214](https://github.com/matrix-org/matrix-spec/issues/2214))
+- Don't advertise `creator` field in description of room creation. ([#2215](https://github.com/matrix-org/matrix-spec/issues/2215))
+- `room_id` is required for peeking via `/_matrix/client/v3/events`. ([#2216](https://github.com/matrix-org/matrix-spec/issues/2216))
+- The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment. ([#2217](https://github.com/matrix-org/matrix-spec/issues/2217))
+- Add note to each endpoint that uses capability negotiation. ([#2223](https://github.com/matrix-org/matrix-spec/issues/2223))
+- Additional OpenGraph properties can be present in URL previews. ([#2225](https://github.com/matrix-org/matrix-spec/issues/2225))
+- Clarify the special casing of membership events and redactions in power levels. ([#2231](https://github.com/matrix-org/matrix-spec/issues/2231))
+- `M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code. ([#2232](https://github.com/matrix-org/matrix-spec/issues/2232))
+- Add `m.login.terms` to enumeration of authentication types. ([#2233](https://github.com/matrix-org/matrix-spec/issues/2233))
+- Clarify how to use `state_after` ahead of declaring full support for its spec version. ([#2240](https://github.com/matrix-org/matrix-spec/issues/2240))
+- `device_one_time_keys_count` is only optional if no unclaimed one-time keys exist. ([#2245](https://github.com/matrix-org/matrix-spec/issues/2245))
+- Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users. ([#2246](https://github.com/matrix-org/matrix-spec/issues/2246))
+- Usage of the `event_id_only` format for push notifications is not mandatory. ([#2255](https://github.com/matrix-org/matrix-spec/issues/2255))
+- Fix various typos throughout the specification. ([#2224](https://github.com/matrix-org/matrix-spec/issues/2224), [#2227](https://github.com/matrix-org/matrix-spec/issues/2227), [#2250](https://github.com/matrix-org/matrix-spec/issues/2250))
+
+
+## Server-Server API
+
+No significant changes.
+
+
+## Application Service API
+
+**Backwards Compatible Changes**
+
+- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
+- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
+
+**Spec Clarifications**
+
+- Fix JSON formatting in the "Server admin style permissions" examples. ([#2213](https://github.com/matrix-org/matrix-spec/issues/2213))
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room. ([#2220](https://github.com/matrix-org/matrix-spec/issues/2220))
+- In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send. ([#2249](https://github.com/matrix-org/matrix-spec/issues/2249))
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Swapped icon for X (fka. twitter) to updated logo in footer. ([#2219](https://github.com/matrix-org/matrix-spec/issues/2219))
+- Inline Olm & Megolm specifications. ([#2226](https://github.com/matrix-org/matrix-spec/issues/2226), [#2241](https://github.com/matrix-org/matrix-spec/issues/2241), [#2242](https://github.com/matrix-org/matrix-spec/issues/2242))
+- Silence failing redocly-cli rule. ([#2238](https://github.com/matrix-org/matrix-spec/issues/2238))
+- Use NPM Trusted Publishers for publishing `@matrix-org/spec` to npm. ([#2239](https://github.com/matrix-org/matrix-spec/issues/2239))
+- Add version picker in the navbar. ([#2256](https://github.com/matrix-org/matrix-spec/issues/2256), [#2258](https://github.com/matrix-org/matrix-spec/issues/2258), [#2259](https://github.com/matrix-org/matrix-spec/issues/2259), [#2260](https://github.com/matrix-org/matrix-spec/issues/2260), [#2261](https://github.com/matrix-org/matrix-spec/issues/2261), [#2264](https://github.com/matrix-org/matrix-spec/issues/2264), [#2268](https://github.com/matrix-org/matrix-spec/issues/2268))
+- Add a list of endpoints to the top of each spec page. ([#2262](https://github.com/matrix-org/matrix-spec/issues/2262))

content/changelog/v1.2.md

@@ -2,26 +2,13 @@
 title: v1.2 Changelog
 linkTitle: v1.2
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-02-02T00:00:00+0000
+date: 2022-02-02
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.2  = Replaced by the version number (eg: v1.2)
-    February 02, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-doc/tree/v1.2">https://github.com/matrix-org/matrix-doc/tree/v1.2</a></td>
-<tr><th>Release date</th><td>February 02, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.2/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.3.md

@@ -2,26 +2,13 @@
 title: v1.3 Changelog
 linkTitle: v1.3
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-06-15T00:00:00+0100
+date: 2022-06-15
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.3  = Replaced by the version number (eg: v1.2)
-    June 15, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.3">https://github.com/matrix-org/matrix-spec/tree/v1.3</a></td>
-<tr><th>Release date</th><td>June 15, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.3/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.4.md

@@ -2,26 +2,13 @@
 title: v1.4 Changelog
 linkTitle: v1.4
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-09-29T00:00:00+0100
+date: 2022-09-29
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.4  = Replaced by the version number (eg: v1.2)
-    September 29, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.4">https://github.com/matrix-org/matrix-spec/tree/v1.4</a></td>
-<tr><th>Release date</th><td>September 29, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.4/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.5.md

@@ -2,26 +2,13 @@
 title: v1.5 Changelog
 linkTitle: v1.5
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2022-11-17T08:22:11-07:00
+date: 2022-11-17
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.5  = Replaced by the version number (eg: v1.2)
-    November 17, 2022     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.5">https://github.com/matrix-org/matrix-spec/tree/v1.5</a></td>
-<tr><th>Release date</th><td>November 17, 2022</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.5/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.6.md

@@ -2,26 +2,13 @@
 title: v1.6 Changelog
 linkTitle: v1.6
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-02-14T08:25:40-07:00
+date: 2023-02-14
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.6  = Replaced by the version number (eg: v1.2)
-    February 14, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.6">https://github.com/matrix-org/matrix-spec/tree/v1.6</a></td>
-<tr><th>Release date</th><td>February 14, 2023</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.6/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.7.md

@@ -2,26 +2,13 @@
 title: v1.7 Changelog
 linkTitle: v1.7
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-05-25T09:47:21-06:00
+date: 2023-05-25
 ---
-<!--
-This is a header file for the generated changelog.
 
-Variables:
-    v1.7  = Replaced by the version number (eg: v1.2)
-    May 25, 2023     = Replaced by the date (eg: April 01, 2021)
--->
-
-<table class="release-info">
-<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.7">https://github.com/matrix-org/matrix-spec/tree/v1.7</a></td>
-<tr><th>Release date</th><td>May 25, 2023</td>
-<tr><th>Checklist</th><td><a href="/changelog/v1.7/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 ## Client-Server API
 
 

content/changelog/v1.8.md

@@ -2,26 +2,12 @@
 title: v1.8 Changelog
 linkTitle: v1.8
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-08-23T09:23:53-06:00
+date: 2023-08-23
 ---
-<!--
-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)
--->
-
-<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>
-<tr><th>Checklist</th><td><a href="/changelog/v1.8/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

content/changelog/v1.9.md

@@ -2,26 +2,12 @@
 title: v1.9 Changelog
 linkTitle: v1.9
 type: docs
+layout: changelog
 outputs:
   - html
   - checklist
-date: 2023-11-29T10:04:26-07:00
+date: 2023-11-29
 ---
-<!--
-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)
--->
-
-<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>
-<tr><th>Checklist</th><td><a href="/changelog/v1.9/checklist.md">checklist.md</a></td>
-</table>
-
-<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
 
 ## Client-Server API
 

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

@@ -16,7 +16,7 @@ data with the same `type`.
 The client receives the account data as events in the `account_data`
 sections of a [`/sync`](#get_matrixclientv3sync) response.
 
-These events can also be received in a `/events` response or in the
+These events can also be received in a [`/events`](#get_matrixclientv3events) response or in the
 `account_data` section of a room in a `/sync` response. `m.tag` events appearing in
 `/events` will have a `room_id` with the room the tags are for.
 

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

@@ -16,28 +16,24 @@ When serving content, the server SHOULD provide a
 `Content-Security-Policy` header. The recommended policy is
 `sandbox; default-src 'none'; script-src 'none'; plugin-types application/pdf; style-src 'unsafe-inline'; object-src 'self';`.
 
-{{% boxes/added-in-paragraph %}}
+{{% added-in v="1.4" %}} The server SHOULD additionally provide
-{{< added-in v="1.4" >}} The server SHOULD additionally provide
 `Cross-Origin-Resource-Policy: cross-origin` when serving content to allow
 (web) clients to access restricted APIs such as `SharedArrayBuffer` when
 interacting with the media repository.
-{{% /boxes/added-in-paragraph %}}
 
-{{% boxes/added-in-paragraph %}}
+{{% changed-in v="1.11" %}} The unauthenticated download endpoints have been
-{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been
 deprecated in favour of newer, authenticated, ones. This change includes updating
 the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`,
 with the exception of the `/upload` and `/create` endpoints. The upload/create
 endpoints are expected to undergo a similar transition in a later version of the
 specification.
-{{% /boxes/added-in-paragraph %}}
 
 #### Matrix Content (`mxc://`) URIs
 
 Content locations are represented as Matrix Content (`mxc://`) URIs. They
 look like:
 
-```
+```nohighlight
 mxc://<server-name>/<media-id>
 
 <server-name> : The name of the homeserver where this content originated, e.g. matrix.org
@@ -48,11 +44,9 @@ mxc://<server-name>/<media-id>
 
 Clients can access the content repository using the following endpoints.
 
-{{% boxes/added-in-paragraph %}}
+{{% changed-in v="1.11" %}} A number of endpoints under the /_matrix/media hierarchy
-{{< changed-in v="1.11" >}} A number of endpoints under the /_matrix/media hierarchy
 have been deprecated and replaced with new endpoints which require authentication.
 The deprecated endpoints are marked in the section below.
-{{% /boxes/added-in-paragraph %}}
 
 {{% boxes/warning %}}
 By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints
@@ -140,9 +134,14 @@ entity isn't in the room.
 `mxc://` URIs are vulnerable to directory traversal attacks such as
 `mxc://127.0.0.1/../../../some_service/etc/passwd`. This would cause the
 target homeserver to try to access and return this file. As such,
-homeservers MUST sanitise `mxc://` URIs by allowing only alphanumeric
+homeservers MUST sanitise `mxc://` URIs by:
-(`A-Za-z0-9`), `_` and `-` characters in the `server-name` and
+
-`media-id` values. This set of whitelisted characters allows URL-safe
+-   restricting the `server-name` segment to valid
+    [server names](/appendices/#server-name)
+-   allowing only alphanumeric (`A-Za-z0-9`), `_` and `-` characters in
+    the `media-id` segment
+
+The resulting set of whitelisted characters allows URL-safe
 base64 encodings specified in RFC 4648. Applying this character
 whitelist is preferable to blacklisting `.` and `/` as there are
 techniques around blacklisted characters (percent-encoded characters,
@@ -212,6 +211,6 @@ HTML page. Therefore, there is no risk in trusting the user-defined content type
 as long as the `Content-Disposition` is calculated based on that type.
 
 Clients SHOULD NOT rely on servers returning `inline` rather than `attachment`
-on `/download`. Server implementations might decide out of an abundance of
+on [`/download`](#get_matrixclientv1mediadownloadservernamemediaid). Server implementations might decide out of an abundance of
 caution that all downloads are responded to with `attachment`, regardless of
 content type - clients should not be surprised by this behaviour.

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

@@ -18,7 +18,7 @@ exchange fingerprints between users to build a web of trust.
 device. This may include long-term identity keys, and/or one-time
 keys.
 
-```
+```nohighlight
       +----------+  +--------------+
       | Bob's HS |  | Bob's Device |
       +----------+  +--------------+
@@ -29,7 +29,7 @@ keys.
 
 2) Alice requests Bob's public identity keys and supported algorithms.
 
-```
+```nohighlight
       +----------------+  +------------+  +----------+
       | Alice's Device |  | Alice's HS |  | Bob's HS |
       +----------------+  +------------+  +----------+
@@ -40,7 +40,7 @@ keys.
 
 3) Alice selects an algorithm and claims any one-time keys needed.
 
-```
+```nohighlight
       +----------------+  +------------+  +----------+
       | Alice's Device |  | Alice's HS |  | Bob's HS |
       +----------------+  +------------+  +----------+
@@ -491,7 +491,7 @@ this example, Bob's device sends the `m.key.verification.start`, Alice's device
 could also send that message. As well, the order of the
 `m.key.verification.done` messages could be reversed.
 
-```
+```nohighlight
     +---------------+ +---------------+                    +-------------+ +-------------+
     | AliceDevice1  | | AliceDevice2  |                    | BobDevice1  | | BobDevice2  |
     +---------------+ +---------------+                    +-------------+ +-------------+
@@ -528,7 +528,7 @@ messages, Alice only sends one request event (an event with type
 `m.room.message` with `msgtype: m.key.verification.request`, rather than an
 event with type `m.key.verification.request`), to the room. In addition, Alice
 does not send an `m.key.verification.cancel` event to tell Bob's other devices
-that the request as already been accepted; instead, when Bob's other devices
+that the request has already been accepted; instead, when Bob's other devices
 see his `m.key.verification.ready` event, they will know that the request has
 already been accepted, and that they should ignore the request.
 
@@ -695,7 +695,7 @@ The process between Alice and Bob verifying each other would be:
 The wire protocol looks like the following between Alice and Bob's
 devices:
 
-```
+```nohighlight
     +-------------+                    +-----------+
     | AliceDevice |                    | BobDevice |
     +-------------+                    +-----------+
@@ -969,7 +969,7 @@ she can trust Bob's device if:
 
 The following diagram illustrates how keys are signed:
 
-```
+```nohighlight
     +------------------+                ..................   +----------------+
     | +--------------+ |   ..................            :   | +------------+ |
     | |              v v   v            :   :            v   v v            | |
@@ -1000,7 +1000,7 @@ the user who created them.
 The following diagram illustrates Alice's view, hiding the keys and
 signatures that she cannot see:
 
-```
+```nohighlight
     +------------------+                +----------------+   +----------------+
     | +--------------+ |                |                |   | +------------+ |
     | |              v v                |                v   v v            | |
@@ -1124,7 +1124,7 @@ The process between Alice and Bob verifying each other would be:
    framework as described above.
 3. Alice's client displays a QR code that Bob is able to scan if Bob's client
    indicated the ability to scan, an option to scan Bob's QR code if her client
-   is able to scan.  Bob's client prompts displays a QR code that Alice can
+   is able to scan. Bob's client displays a QR code that Alice can
    scan if Alice's client indicated the ability to scan, and an option to scan
    Alice's QR code if his client is able to scan. The format for the QR code
    is described below. Other options, like starting SAS Emoji verification,
@@ -1218,7 +1218,7 @@ The binary segment MUST be of the following form:
 
 For example, if Alice displays a QR code encoding the following binary data:
 
-```
+```nohighlight
       "MATRIX"    |ver|mode| len   | event ID
  4D 41 54 52 49 58  02  00   00 2D   21 41 42 43 44 ...
 | user's cross-signing key    | other user's cross-signing key | shared secret
@@ -1457,8 +1457,8 @@ readers without adding any useful extra information.
 ##### `m.olm.v1.curve25519-aes-sha2`
 
 The name `m.olm.v1.curve25519-aes-sha2` corresponds to version 1 of the
-Olm ratchet, as defined by the [Olm
+Olm ratchet, as defined by the [Olm specification](/olm-megolm/olm).
-specification](http://matrix.org/docs/spec/olm.html). This uses:
+This uses:
 
 -   Curve25519 for the initial key agreement.
 -   HKDF-SHA-256 for ratchet key derivation.
@@ -1512,40 +1512,11 @@ message.
 
 The plaintext payload is of the form:
 
-```json
+{{% definition path="api/client-server/definitions/olm_payload" %}}
-{
-  "type": "<type of the plaintext event>",
-  "content": "<content for the plaintext event>",
-  "sender": "<sender_user_id>",
-  "recipient": "<recipient_user_id>",
-  "recipient_keys": {
-    "ed25519": "<our_ed25519_key>"
-  },
-  "keys": {
-    "ed25519": "<sender_ed25519_key>"
-  }
-}
-```
 
 The type and content of the plaintext message event are given in the
 payload.
 
-Other properties are included in order to prevent an attacker from
-publishing someone else's curve25519 keys as their own and subsequently
-claiming to have sent messages which they didn't. `sender` must
-correspond to the user who sent the event, `recipient` to the local
-user, and `recipient_keys` to the local ed25519 key.
-
-Clients must confirm that the `sender_key` property in the cleartext
-`m.room.encrypted` event body, and the `keys.ed25519` property in the
-decrypted plaintext, match the keys returned by
-[`/keys/query`](#post_matrixclientv3keysquery) for
-the given user. Clients must also verify the signature of the keys from the
-`/keys/query` response. Without this check, a client cannot be sure that
-the sender device owns the private part of the ed25519 key it claims to
-have in the Olm payload. This is crucial when the ed25519 key corresponds
-to a verified device.
-
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully
 decrypted a message. For these purposes, a session that has not received
@@ -1555,6 +1526,68 @@ maximum number of olm sessions that it will maintain for each device,
 and expiring sessions on a Least Recently Used basis. The maximum number
 of olm sessions maintained per device should be at least 4.
 
+###### Validation of incoming decrypted events
+
+{{% changed-in v="1.15" %}} Existing checks made more explicit, and checks for `sender_device_keys` added.
+
+After decrypting an incoming encrypted event, clients MUST apply the
+following checks:
+
+1.  The `sender` property in the decrypted content must match the
+    `sender` of the event.
+2.  The `keys.ed25519` property in the decrypted content must match
+    the `sender_key` property in the cleartext `m.room.encrypted`
+    event body.
+3.  The `recipient` property in the decrypted content must match
+    the user ID of the local user.
+4.  The `recipient_keys.ed25519` property in the decrypted content
+    must match the client device's [Ed25519 signing key](#device-keys).
+5.  Where `sender_device_keys` is present in the decrypted content:
+    1.  `sender_device_keys.user_id` must also match the `sender`
+        of the event.
+    2.  `sender_device_keys.keys.ed25519:<device_id>` must also match
+        the `sender_key` property in the cleartext `m.room.encrypted`
+        event body.
+    3.  `sender_device_keys.keys.curve25519:<device_id>` must match
+        the Curve25519 key used to establish the Olm session.
+    4.  The `sender_device_keys` structure must have a valid signature
+        from the key with ID `ed25519:<device_id>` (i.e., the sending
+        device's Ed25519 key).
+
+Any event that does not comply with these checks MUST be discarded.
+
+###### Verification of the sending user for incoming events
+
+{{% added-in v="1.15" %}}
+
+In addition, for each Olm session, clients MUST verify that the
+Curve25519 key used to establish the Olm session does indeed belong
+to the claimed `sender`. This requires a signed "device keys" structure
+for that Curve25519 key, which can be obtained in one of two ways:
+
+1.  An Olm message may be received with a `sender_device_keys` property
+    in the decrypted content.
+2.  The keys are returned via a [`/keys/query`](#post_matrixclientv3keysquery)
+    request. Note that both the Curve25519 key **and** the Ed25519 key in
+    the returned device keys structure must match those used in an
+    Olm-encrypted event as above. (In particular, the Ed25519 key must
+    be present in the **encrypted** content of an Olm-encrypted event
+    to prevent an attacker from claiming another user's Curve25519 key
+    as their own.)
+
+Ownership of the Curve25519 key is then established in one of two ways:
+
+1.  Via [cross-signing](#cross-signing). For this to be sufficient, the
+    device keys structure must be signed by the sender's self-signing key,
+    and that self-signing key must itself have been validated (either via
+    [explicit verification](#device-verification) or a "trust on first use" (TOFU) mechanism).
+2.  Via explicit verification of the device's Ed25519 signing key, as
+    contained in the device keys structure. This is no longer recommended.
+
+A failure to complete these verifications does not necessarily mean that
+the session is bogus; however it is the case that there is no proof that
+the claimed sender is accurate, and the user should be warned accordingly.
+
 ###### Recovering from undecryptable messages
 
 Occasionally messages may be undecryptable by clients due to a variety
@@ -1598,8 +1631,8 @@ This is due to a deprecation of the fields. See
 {{% changed-in v="1.3" %}}
 
 The name `m.megolm.v1.aes-sha2` corresponds to version 1 of the Megolm
-ratchet, as defined by the [Megolm
+ratchet, as defined by the [Megolm specification](/olm-megolm/megolm).
-specification](http://matrix.org/docs/spec/megolm.html). This uses:
+This uses:
 
 -   HMAC-SHA-256 for the hash ratchet.
 -   HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256
@@ -1742,19 +1775,18 @@ property is required for inclusion, though previous versions of the
 specification did not have it. In addition to `/versions`, this can be
 a way to identify the server's support for fallback keys.
 
-
+| Parameter                        | Type              | Description                                                                                                            |
-| Parameter                        | Type               | Description                                                                                                            |
+|----------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------|
-|----------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
+| device_lists                     | DeviceLists       | Optional. Information on e2e device updates. Note: only present on an incremental sync.                                |
-| device_lists                     | DeviceLists        | Optional. Information on e2e device updates. Note: only present on an incremental sync.                                |
+| device_one_time_keys_count       | {string: integer} | **Required if any unclaimed one-time keys exist.** For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. If the count for an algorithm is zero, servers MAY omit that algorithm. If the count for all algorithms is zero, servers MAY omit this parameter entirely. |
-| device_one_time_keys_count       | {string: integer}  | Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device.  If an algorithm is unlisted, the count for that algorithm is assumed to be zero.  If this entire parameter is missing, the count for all algorithms is assumed to be zero.  |
+| device_unused_fallback_key_types | [string]          | **Required.** The unused fallback key algorithms.                                                                      |
-| device_unused_fallback_key_types | [string]           | **Required.** The unused fallback key algorithms.                                                                      |
 
 `DeviceLists`
 
-| Parameter  | Type      | Description                                                                                                                                                      |
+| Parameter | Type     | Description                                                                                                                                                      |
-|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| changed    | [string]  | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
+| changed   | [string] | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
-| left       | [string]  | List of users with whom we do not share any encrypted rooms anymore since the previous sync response.                                                            |
+| left      | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response.                                                            |
 
 {{% boxes/note %}}
 For optimal performance, Alice should be added to `changed` in Bob's

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

@@ -188,14 +188,14 @@ replacement event.
 
 ##### Server-side aggregation of `m.replace` relationships
 
-{{< changed-in v="1.7" >}}
+{{% changed-in v="1.7" %}}
 
 Note that there can be multiple events with an `m.replace` relationship to a
 given event (for example, if an event is edited multiple times). These should
 be [aggregated](#aggregations-of-child-events) by the homeserver.
 
 The aggregation format of `m.replace` relationships gives the **most recent**
-replacement event, formatted [as normal](#room-event-format).
+valid replacement event, formatted [as normal](#room-event-format).
 
 The most recent event is determined by comparing `origin_server_ts`; if two or
 more replacement events have identical `origin_server_ts`, the event with the
@@ -268,6 +268,11 @@ Client authors are reminded to take note of the requirements for [Validity of
 replacement events](#validity-of-replacement-events), and to ignore any
 invalid replacement events that are received.
 
+Clients should render the content of the **most recent** valid replacement event. The
+most recent event is determined by comparing `origin_server_ts`; if two or more
+replacement events have identical `origin_server_ts`, the event with the
+lexicographically largest `event_id` is treated as more recent.
+
 ##### Permalinks
 
 When creating [links](/appendices/#uris) to events (also known as permalinks),
@@ -309,7 +314,7 @@ for re-notifying if the sending client feels a large enough revision was made).
 
 For example, if there is an event mentioning Alice:
 
-```json5
+```json
 {
     "event_id": "$original_event",
     "type": "m.room.message",
@@ -324,7 +329,7 @@ For example, if there is an event mentioning Alice:
 
 And an edit to also mention Bob:
 
-```json5
+```json
 {
   "content": {
     "body": "* Hello Alice & Bob!",
@@ -362,21 +367,19 @@ property under `m.new_content`.
 
 #### Edits of replies
 
-Some particular constraints apply to events which replace a
+A particular constraint applies to events which replace a [reply](#rich-replies):
-[reply](#rich-replies). In particular:
+in contrast to the original reply, there should be no `m.in_reply_to` property
+in the `m.relates_to` object, since it would be redundant (see
+[Applying `m.new_content`](#applying-mnew_content) above, which notes that the
+original event's `m.relates_to` is preserved), as well as being contrary to the
+spirit of the event relationships mechanism which expects only one "parent" per
+event.
 
- * In contrast to the original reply, there should be no `m.in_reply_to`
+{{% boxes/note %}}
-   property in the the `m.relates_to` object, since it would be redundant (see
+{{% changed-in v="1.13" %}}
-   [Applying `m.new_content`](#applying-mnew_content) above, which notes that
+In previous versions of the specification, events which replace a [reply](#rich-replies)
-   the original event's `m.relates_to` is preserved), as well as being contrary
+could include a fallback in the `content`. This is no longer the case.
-   to the spirit of the event relationships mechanism which expects only one
+{{% /boxes/note %}}
-   "parent" per event.
-
- * `m.new_content` should **not** contain any [reply
-   fallback](#fallbacks-for-rich-replies),
-   since it is assumed that any client which can handle edits can also display
-   replies natively. However, the `content` of the replacement event should provide
-   fallback content for clients which support neither rich replies nor edits.
 
 An example of an edit to a reply is as follows:
 
@@ -385,15 +388,11 @@ An example of an edit to a reply is as follows:
   "type": "m.room.message",
   // irrelevant fields not shown
   "content": {
-    "body": "> <@alice:example.org> question\n\n* reply",
+    "body": "* reply",
     "msgtype": "m.text",
-    "format": "org.matrix.custom.html",
-    "formatted_body": "<mx-reply><blockquote><a href=\"https://matrix.to/#/!somewhere:example.org/$event:example.org\">In reply to</a> <a href=\"https://matrix.to/#/@alice:example.org\">@alice:example.org</a><br />question</blockquote></mx-reply>* reply",
     "m.new_content": {
       "body": "reply",
       "msgtype": "m.text",
-      "format": "org.matrix.custom.html",
-      "formatted_body": "reply"
     },
     "m.relates_to": {
       "rel_type": "m.replace",

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

@@ -40,13 +40,13 @@ for retrieving events and associated media:
 * [GET /rooms/{roomId}/event/{eventId}](#get_matrixclientv3roomsroomideventeventid)
 * [GET /rooms/{roomId}/state/{eventType}/{stateKey}](#get_matrixclientv3roomsroomidstateeventtypestatekey)
 * [GET /rooms/{roomId}/messages](#get_matrixclientv3roomsroomidmessages)
-* {{< added-in v="1.1" >}} [GET /rooms/{roomId}/members](#get_matrixclientv3roomsroomidmembers)
+* {{% added-in v="1.1" %}} [GET /rooms/{roomId}/members](#get_matrixclientv3roomsroomidmembers)
 * [GET /rooms/{roomId}/initialSync](#get_matrixclientv3roomsroomidinitialsync)
 * [GET /sync](#get_matrixclientv3sync)
 * [GET /events](#get_matrixclientv3events) as used for room previews.
-* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid)
+* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid)
-* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename)
+* {{% added-in v="1.12" %}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename)
-* {{< added-in v="1.12" >}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid)
+* {{% added-in v="1.12" %}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid)
 
 The following API endpoints are allowed to be accessed by guest accounts
 for sending events:
@@ -55,19 +55,20 @@ for sending events:
 * [POST /rooms/{roomId}/leave](#post_matrixclientv3roomsroomidleave)
 * [PUT /rooms/{roomId}/send/{eventType}/{txnId}](#put_matrixclientv3roomsroomidsendeventtypetxnid)
 
-    * {{< changed-in v="1.2" >}} Guests can now send *any* event type rather than just `m.room.message` events.
+    * {{% changed-in v="1.2" %}} Guests can now send *any* event type rather than just `m.room.message` events.
 
-* {{< added-in v="1.2" >}} [PUT /rooms/{roomId}/state/{eventType}/{stateKey}](#put_matrixclientv3roomsroomidstateeventtypestatekey)
+* {{% added-in v="1.2" %}} [PUT /rooms/{roomId}/state/{eventType}/{stateKey}](#put_matrixclientv3roomsroomidstateeventtypestatekey)
 * [PUT /sendToDevice/{eventType}/{txnId}](#put_matrixclientv3sendtodeviceeventtypetxnid)
 
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseriddisplayname)
+* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname). Guest users may only modify their display name; other profile fields may not be changed.
+* {{% added-in v="1.16" %}} [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname). Again, guest users may delete their display name but not other profile fields.
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)
-* {{< added-in v="1.2" >}} [GET /account/whoami](#get_matrixclientv3accountwhoami)
+* {{% added-in v="1.2" %}} [GET /account/whoami](#get_matrixclientv3accountwhoami)
 
 The following API endpoints are allowed to be accessed by guest accounts
 for end-to-end encryption:

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

@@ -16,8 +16,8 @@ The four options for the `m.room.history_visibility` event are:
 
 -   `world_readable` - All events while this is the
     `m.room.history_visibility` value may be shared by any participating
-    homeserver with anyone, regardless of whether they have ever joined
+    homeserver with any authenticated user, regardless of whether they have
-    the room.
+    ever joined the room. This includes [guest users](#guest-access).
 -   `shared` - Previous events are always accessible to newly joined
     members. All events in the room are accessible, even those sent when
     the member was not a part of the room.
@@ -43,11 +43,8 @@ setting at that time was more restrictive.
 
 #### Client behaviour
 
-Clients that implement this module MUST present to the user the possible
+Clients may want to display a notice that events may be read by
-options for setting history visibility when creating a room.
+non-joined users if the history visibility is set to `world_readable`.
-
-Clients may want to display a notice that their events may be read by
-non-joined people if the value is set to `world_readable`.
 
 #### Server behaviour
 

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

@@ -13,10 +13,10 @@ and servers can implement the ignoring of users.
 
 To ignore a user, effectively blocking them, the client should add the
 target user to the `m.ignored_user_list` event in their account data
-using [`/user/<user_id>/account_data/<type>`](/client-server-api/#put_matrixclientv3useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by
+using [`/user/<user_id>/account_data/<type>`](#put_matrixclientv3useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by
 that user, with the exception of state events. The client should either
 hide previous content sent by the newly ignored user or perform a new
-`/sync` with no previous token.
+[`/sync`](#get_matrixclientv3sync) with no previous token.
 
 Invites to new rooms by ignored users will not be sent to the client.
 The server may optionally reject the invite on behalf of the client.

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

@@ -98,14 +98,12 @@ having appropriate closing tags, appropriate attributes (considering the
 custom ones defined in this specification), and generally valid
 structure.
 
-A special tag, `mx-reply`, may appear on rich replies (described below)
+{{% boxes/note %}}
-and should be allowed if, and only if, the tag appears as the very first
+{{% changed-in v="1.13" %}}
-tag in the `formatted_body`. The tag cannot be nested and cannot be
+In previous versions of the specification, [rich replies](#rich-replies) could
-located after another tag in the tree. Because the tag contains HTML, an
+use a special tag, `mx-reply`. This is no longer the case. Clients SHOULD strip
-`mx-reply` is expected to have a partner closing tag and should be
+this tag and its content. See the "Rich replies" section for more information.
-treated similar to a `div`. Clients that support rich replies will end
+{{% /boxes/note %}}
-up stripping the tag and its contents and therefore may wish to exclude
-the tag entirely.
 
 {{% boxes/note %}}
 A future iteration of the specification will support more powerful and

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

@@ -3,6 +3,9 @@
 
 {{% changed-in v="1.7" %}}
 
+{{% changed-in v="1.17" %}}: the legacy push rules that looked for mentions in
+the `body` of the event were removed.
+
 This module allows users to "mention" other users and rooms within a room event.
 This is primarily used as an indicator that the recipient should receive a notification
 about the event.
@@ -38,19 +41,18 @@ encrypted as normal. To properly process mentions in encrypted rooms, events
 must be decrypted first. See [receiving notifications](#receiving-notifications).
 {{% /boxes/warning %}}
 
-Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
+{{% boxes/note %}}
-[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
-[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to  match if the `body` of
-the event contains the user's display name or ID. To avoid unintentional notifications,
-**it is recommended that clients include a `m.mentions` property on each event**.
-(If there are no mentions to include it can be an empty object.)
-
-{{% boxes/rationale %}}
 In previous versions of the specification, mentioning users was done by
 including the user's display name or the localpart of their Matrix ID and room
 mentions were done by including the string "@room" in the plaintext `body` of
-the event. This was prone to confusing and buggy behaviour.
+the event. When the `m.mentions` field was introduced, those push rules were
-{{% /boxes/rationale %}}
+disabled if the `m.mentions` field was present.
+
+To avoid unintentional notifications with clients and servers that still use
+those push rules, **it is recommended that clients still include a `m.mentions`
+property on each event**. (If there are no mentions to include it can be an
+empty object.)
+{{% /boxes/note %}}
 
 #### Client behaviour
 

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

@@ -18,8 +18,9 @@ the entity making the decisions on filtering is best positioned to
 interpret the rules how it sees fit.
 
 Moderation policy lists are stored as room state events. There are no
-restrictions on how the rooms can be configured (they could be public,
+restrictions on how the rooms can be configured in terms of
-private, encrypted, etc).
+[join rules](#mroomjoin_rules), [history visibility](#room-history-visibility),
+encryption, etc.
 
 There are currently 3 kinds of entities which can be affected by rules:
 `user`, `server`, and `room`. All 3 are described with

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

@@ -68,5 +68,7 @@ will cause the server to automatically set their presence to `online`.
 
 #### Security considerations
 
-Presence information is shared with all users who share a room with the
+Presence information is published to all users who share a room with the
-target user. In large public rooms this could be undesirable.
+target user. If the target user is a member of a room with a `public`
+[join rule](#mroomjoin_rules), any other user in the federation is
+able to gain access to the target user's presence. This could be undesirable.

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

@@ -1,7 +1,7 @@
 
 ### Push Notifications
 
-```
+```nohighlight
                                    +--------------------+  +-------------------+
                   Matrix HTTP      |                    |  |                   |
              Notification Protocol |   App Developer    |  |   Device Vendor   |
@@ -83,7 +83,7 @@ Push Ruleset
 :   A push ruleset *scopes a set of rules according to some criteria*. For
     example, some rules may only be applied for messages from a particular
     sender, a particular room, or by default. The push ruleset contains the
-    entire set of scopes and rules.
+    entire set of rules.
 
 #### Push Rules
 
@@ -91,10 +91,8 @@ A push rule is a single rule that states under what *conditions* an
 event should be passed onto a push gateway and *how* the notification
 should be presented. There are different "kinds" of push rules and each
 rule has an associated priority. Every push rule MUST have a `kind` and
-`rule_id`. The `rule_id` is a unique string within the kind of rule and
+`rule_id`. The `rule_id` is a unique string within the kind of rule.
-its' scope: `rule_ids` do not need to be unique between rules of the
+Rules may have extra keys depending on the value of `kind`.
-same kind on different devices. Rules may have extra keys depending on
-the value of `kind`.
 
 The different `kind`s of rule, in the order that they are checked, are:
 
@@ -382,6 +380,9 @@ The following `alt_aliases` values will NOT match:
 
 **`contains_display_name`**
 
+{{% changed-in v="1.17" %}}: this condition is deprecated and **should not be
+used in new push rules**.
+
 This matches messages where `content.body` contains the owner's display name in
 that room. This is a separate condition because display names may change and as such
 it would be hard to maintain a rule that matched the user's display name. This
@@ -413,6 +414,9 @@ Parameters:
 
 #### Predefined Rules
 
+{{% changed-in v="1.17" %}}: the legacy default push rules that looked for
+mentions in the `body` of the event were removed.
+
 Homeservers can specify "server-default rules". They operate at a lower
 priority than "user-defined rules", except for the `.m.rule.master` rule
 which has always a higher priority than any other rule. The `rule_id`
@@ -525,7 +529,7 @@ Definition:
 
 <a id="_m_rule_is_user_mention"></a> **`.m.rule.is_user_mention`**
 
-{{< added-in v="1.7" >}}
+{{% added-in v="1.7" %}}
 
 Matches any message which contains the user's Matrix ID in the list of `user_ids`
 under the `m.mentions` property.
@@ -557,44 +561,9 @@ Definition:
 }
 ```
 
-<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message whose content contains the user's current display name
-in the room in which it was sent.
-
-Definition:
-
-```json
-{
-    "rule_id": ".m.rule.contains_display_name",
-    "default": true,
-    "enabled": true,
-    "conditions": [
-        {
-            "kind": "contains_display_name"
-        }
-    ],
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "sound",
-            "value": "default"
-        },
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 <a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
 
-{{< added-in v="1.7" >}}
+{{% added-in v="1.7" %}}
 
 Matches any message from a sender with the proper power level with the `room`
 property of the `m.mentions` property set to `true`.
@@ -626,44 +595,6 @@ Definition:
 }
 ```
 
-<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message from a sender with the proper power level whose content
-contains the text `@room`, signifying the whole room should be notified of
-the event.
-
-Definition:
-
-```json
-{
-    "rule_id": ".m.rule.roomnotif",
-    "default": true,
-    "enabled": true,
-    "conditions": [
-        {
-            "kind": "event_match",
-            "key": "content.body",
-            "pattern": "@room"
-        },
-        {
-            "kind": "sender_notification_permission",
-            "key": "room"
-        }
-    ],
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 **<a id="mruletombstone"></a>`.m.rule.tombstone`**
 
 Matches any state event whose type is `m.room.tombstone`. This is
@@ -776,39 +707,6 @@ Definition:
 }
 ```
 
-##### Default Content Rules
-
-<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message whose content contains the local part of the user's
-Matrix ID, separated by word boundaries.
-
-Definition (as a `content` rule):
-
-```json
-{
-    "rule_id": ".m.rule.contains_user_name",
-    "default": true,
-    "enabled": true,
-    "pattern": "[the local part of the user's Matrix ID]",
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "sound",
-            "value": "default"
-        },
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 ##### Default Underride Rules
 
 **`.m.rule.call`**
@@ -1044,7 +942,7 @@ messages they have received.
 ##### Receiving notifications
 
 Servers MUST include the number of unread notifications in a client's
-`/sync` stream, and MUST update it as it changes. Notifications are
+[`/sync`](#get_matrixclientv3sync) stream, and MUST update it as it changes. Notifications are
 determined by the push rules which apply to an event.
 
 For encrypted events, the homeserver has limited access to the event content
@@ -1072,7 +970,7 @@ 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
+{{% 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
@@ -1091,7 +989,7 @@ users in the room (excluding the sender). This may result in:
 * Generating a new number of unread notifications for the user.
 * Making a request to the configured push gateway.
 
-The updated notification count from a new event MUST appear in the same `/sync`
+The updated notification count from a new event MUST appear in the same [`/sync`](#get_matrixclientv3sync)
 response as the event itself.
 
 #### Push Gateway behaviour

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

@@ -29,7 +29,7 @@ The client cannot update fully read markers by directly modifying the
 `m.fully_read` account data event. Instead, the client must make use of
 the read markers API to change the values.
 
-{{< changed-in v="1.4" >}} `m.read.private` receipts can now be sent from
+{{% changed-in v="1.4" %}} `m.read.private` receipts can now be sent from
 `/read_markers`.
 
 The read markers API can additionally update the user's read receipt

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

@@ -1,7 +1,7 @@
 
 ### Receipts
 
-{{< changed-in v="1.4" >}} Added private read receipts.
+{{% changed-in v="1.4" %}} Added private read receipts.
 
 This module adds in support for receipts. These receipts are a form of
 acknowledgement of an event. This module defines the `m.read` receipt
@@ -19,7 +19,7 @@ that the user had read all events *up to* the referenced event. See the
 [Receiving notifications](#receiving-notifications) section for more
 information on how read receipts affect notification counts.
 
-{{< added-in v="1.4" >}} Read receipts exist in three major forms:
+{{% added-in v="1.4" %}} Read receipts exist in three major forms:
 * Unthreaded: Denotes a read-up-to receipt regardless of threads. This is how
   pre-threading read receipts worked.
 * Threaded, main timeline: Denotes a read-up-to receipt for events not in a
@@ -31,7 +31,7 @@ Threaded read receipts are discussed in further detail [below](#threaded-read-re
 
 #### Events
 
-{{< changed-in v="1.4" >}} Each `user_id`, `receipt_type`, and categorisation
+{{% changed-in v="1.4" %}} Each `user_id`, `receipt_type`, and categorisation
 (unthreaded, or `thread_id`) tuple must be associated with only a single
 `event_id`.
 
@@ -39,9 +39,9 @@ Threaded read receipts are discussed in further detail [below](#threaded-read-re
 
 #### Client behaviour
 
-{{< changed-in v="1.4" >}} Altered to support threaded read receipts.
+{{% changed-in v="1.4" %}} Altered to support threaded read receipts.
 
-In `/sync`, receipts are listed under the `ephemeral` array of events
+In [`/sync`](#get_matrixclientv3sync), receipts are listed under the `ephemeral` array of events
 for a given room. New receipts that come down the event streams are
 deltas which update existing mappings. Clients should replace older
 receipt acknowledgements based on `user_id`, `receipt_type`, and the
@@ -155,12 +155,12 @@ 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.
 
-![threaded-dag](/diagrams/threaded-dag.png)
+{{% diagram name="threaded-dag" alt="Diagram presenting a DAG with thread relationships as a single timeline" %}}
 
 This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread
 roots:
 
-![threaded-dag-threads](/diagrams/threaded-dag-threads.png)
+{{% diagram name="threaded-dag-threads" alt="Diagram presenting a DAG with thread relationships as 3 related timelines" %}}
 
 With this, we can demonstrate that:
 * A threaded read receipt on `I` would mark `A`, `B`, and `I` as read.
@@ -214,7 +214,7 @@ before delivering them to clients.
 Some receipts are sent across federation as EDUs with type `m.receipt`. The
 format of the EDUs are:
 
-```
+```nohighlight
 {
     <room_id>: {
         <receipt_type>: {

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

@@ -5,9 +5,6 @@ Users may encounter content which they find inappropriate and should be
 able to report it to the server administrators or room moderators for
 review. This module defines a way for users to report content.
 
-Content is reported based upon a negative score, where -100 is "most
-offensive" and 0 is "inoffensive".
-
 #### Client behaviour
 
 {{% http-api spec="client-server" api="report_content" %}}
@@ -19,6 +16,22 @@ 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 
+Particularly during waves of harmful content, users may report whole
-reporting the event is currently joined to the room the event is 
+rooms instead of individual events. Server administrators and safety teams
-in before accepting a report.
+should, therefore, be cautious not to shut down rooms that might otherwise
+be legitimate.
+
+{{% changed-in v="1.8" %}} When processing event reports, servers MUST
+verify that the reporting user is currently joined to the room the event
+is in before accepting a report.
+
+{{% added-in v="1.13" %}} Contrarily, servers MUST NOT restrict room reports
+based on whether or not the reporting user is joined to the room. This is
+because users can be exposed to harmful content without being joined to a
+room. For instance, through room directories or invites.
+
+{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports
+based on whether or not the reporting user is joined to any rooms that the
+reported user is joined to. This is because users can be exposed to harmful
+content without being joined to a room. For instance, through user
+directories or invites.

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

@@ -1,14 +1,13 @@
 
 ### Rich replies
 
-{{% changed-in v="1.3" %}}
-
 Rich replies are a
 special kind of [relationship](#forming-relationships-between-events) which
 effectively quotes the referenced event for the client to render/process how
 it wishes. They are normally used with [`m.room.message`](#mroommessage) events.
 
 {{% boxes/note %}}
+{{% changed-in v="1.3" %}}
 Until v1.3 of the spec, rich replies were limited to `m.room.message` events
 which could represent an HTML-formatted body. As of v1.3 this is now expanded
 to *all* event types by dropping the requirement that an HTML-formatted body
@@ -18,9 +17,24 @@ Additionally, a rich reply can reference any other event type as of v1.3.
 Previously, a rich reply could only reference another `m.room.message` event.
 {{% /boxes/note %}}
 
-When possible, events SHOULD include a [fallback representation](#fallbacks-for-rich-replies)
+{{% boxes/note %}}
-to allow clients which do not render rich replies to still see something which
+{{% changed-in v="1.13" %}}
-appears to be a quoted reply.
+In previous versions of the specification, rich replies could include a fallback
+representation of the original message in the `body` (using a prefix sequence)
+and `formatted_body` (using a custom HTML element) for clients that do not
+support rich replies. This is no longer the case, but clients SHOULD still
+remove this fallback before rendering the event.
+
+To strip the fallback on the `body`, the client should iterate over each
+line of the string, removing any lines that start with the fallback
+prefix sequence (`> `, including the trailing space) and stopping when
+a line is encountered without the prefix.
+
+To strip the fallback on the `formatted_body` of an `m.room.message` event with
+a `format` of `org.matrix.custom.html`: if the`formatted_body` begins with an
+`<mx-reply>` start tag, the client  should remove the entirety of the
+`<mx-reply>` element.
+{{% /boxes/note %}}
 
 Though rich replies form a relationship to another event, they do not
 use `rel_type` to create this relationship. Instead, a subkey named `m.in_reply_to`
@@ -31,7 +45,7 @@ the `rel_type` and `event_id` properties of `m.relates_to` become *optional*.
 
 An example reply would be:
 
-```json5
+```json
 {
   "content": {
     "m.relates_to": {
@@ -48,146 +62,20 @@ An example reply would be:
 Note that the `event_id` of the `m.in_reply_to` object has the same requirements
 as if it were to be under `m.relates_to` directly instead.
 
-#### Fallbacks for rich replies
-
-Some clients may not have support for rich replies and therefore need a
-fallback to use instead. Clients that do not support rich replies should
-render the event as if rich replies were not special.
-
-Clients that do support rich replies SHOULD provide the fallback format on
-replies, and MUST strip the fallback before rendering the reply. The
-specific fallback text is different for each `msgtype`, however the
-general format for the `body` is:
-
-```text
-> <@alice:example.org> This is the first line of the original body
-> This is the second line
-
-This is where the reply goes
-```
-
-The `formatted_body`, if present and using an associated `format` of
-`org.matrix.custom.html`, should use the following template:
-
-```html
-<mx-reply>
-  <blockquote>
-    <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
-    <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
-    <br />
-    <!-- This is where the related event's HTML would be. -->
-  </blockquote>
-</mx-reply>
-This is where the reply goes.
-```
-
-If the related event does not have a `formatted_body`, the event's
-`body` should be considered after encoding any HTML special characters.
-Note that the `href` in both of the anchors use a [matrix.to
-URI](/appendices#matrixto-navigation).
-
-##### Stripping the fallback
-
-Clients which support rich replies MUST strip the fallback from the
-event before rendering the event. This is because the text provided in
-the fallback cannot be trusted to be an accurate representation of the
-event. After removing the fallback, clients are recommended to represent
-the event referenced by `m.in_reply_to` similar to the fallback's
-representation, although clients do have creative freedom for their user
-interface. Clients should prefer the `formatted_body` over the `body`,
-just like with other `m.room.message` events.
-
-To strip the fallback on the `body`, the client should iterate over each
-line of the string, removing any lines that start with the fallback
-prefix ("&gt; ", including the space, without quotes) and stopping when
-a line is encountered without the prefix. This prefix is known as the
-"fallback prefix sequence".
-
-To strip the fallback on the `formatted_body`, the client should remove
-the entirety of the `mx-reply` tag.
-
-##### Fallback for `m.text`, `m.notice`, and unrecognised message types
-
-Using the prefix sequence, the first line of the related event's `body`
-should be prefixed with the user's ID, followed by each line being
-prefixed with the fallback prefix sequence. For example:
-
-```text
-> <@alice:example.org> This is the first line
-> This is the second line
-
-This is the reply
-```
-
-The `formatted_body` uses the template defined earlier in this section.
-
-##### Fallback for `m.emote`
-
-Similar to the fallback for `m.text`, each line gets prefixed with the
-fallback prefix sequence. However an asterisk should be inserted before
-the user's ID, like so:
-
-```text
-> * <@alice:example.org> feels like today is going to be a great day
-
-This is the reply
-```
-
-The `formatted_body` has a subtle difference for the template where the
-asterisk is also inserted ahead of the user's ID:
-
-```html
-<mx-reply>
-  <blockquote>
-    <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
-    * <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
-    <br />
-    <!-- This is where the related event's HTML would be. -->
-  </blockquote>
-</mx-reply>
-This is where the reply goes.
-```
-
-##### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file`
-
-The related event's `body` would be a file name, which may not be very
-descriptive. The related event should additionally not have a `format`
-or `formatted_body` in the `content` - if the event does have a `format`
-and/or `formatted_body`, those fields should be ignored. Because the
-filename alone may not be descriptive, the related event's `body` should
-be considered to be `"sent a file."` such that the output looks similar
-to the following:
-
-```text
-> <@alice:example.org> sent a file.
-
-This is the reply
-```
-```html
-<mx-reply>
-  <blockquote>
-    <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
-    <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
-    <br />
-    sent a file.
-  </blockquote>
-</mx-reply>
-This is where the reply goes.
-```
-
-For `m.image`, the text should be `"sent an image."`. For `m.video`, the
-text should be `"sent a video."`. For `m.audio`, the text should be
-`"sent an audio file"`.
-
 #### Mentioning the replied to user
 
-In order to notify users of the reply, it may be desirable to include the `sender`
+{{% boxes/note %}}
-of the replied to event and any users mentioned in that event. See
+{{% changed-in v="1.16" %}}
-[user and room mentions](#user-and-room-mentions) for additional information.
+Clients SHOULD no longer propagate mentioned users in the replied to event.
+{{% /boxes/note %}}
 
-An example including mentioning the original sender and other users:
+In order to notify users of the reply, it MAY be desirable to include the `sender`
+of the replied to event. See [user and room mentions](#user-and-room-mentions) for
+additional information.
 
-```json5
+An example including mentioning the original sender:
+
+```json
 {
   "content": {
     "m.relates_to": {
@@ -200,8 +88,6 @@ An example including mentioning the original sender and other users:
       "user_ids": [
         // The sender of $another_event.
         "@alice:example.org",
-        // Another Matrix ID copied from the m.mentions property of $another_event.
-        "@bob:example.org"
       ]
     }
   },

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

@@ -6,14 +6,14 @@ It is sometimes desirable to offer a preview of a room, where a user can
 This can be particularly effective when combined with [Guest Access](#guest-access).
 
 Previews are implemented via the `world_readable` [Room History
-Visibility](#room-history-visibility). setting, along with a special version of the [GET
+Visibility](#room-history-visibility) setting, along with a special version of the [GET
 /events](#get_matrixclientv3events) endpoint.
 
 #### Client behaviour
 
 A client wishing to view a room without joining it should call [GET
 /rooms/:room\_id/initialSync](#get_matrixclientv3roomsroomidinitialsync),
-followed by [GET /events](#get_matrixclientv3events). Clients will need to do
+followed by [GET /events](#peeking_get_matrixclientv3events). Clients will need to do
 this in parallel for each room they wish to view.
 
 Clients can of course also call other endpoints such as [GET

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

@@ -30,12 +30,23 @@ server:
 1.  Checks that the user has permission to send `m.room.tombstone`
     events in the room.
 
-2.  {{< changed-in v="1.4" >}} Creates a replacement room with a `m.room.create` event containing a
+2.  {{% changed-in v="1.4" %}} Creates a replacement room with a `m.room.create` event containing a
     `predecessor` field, the applicable `room_version`, and a `type` field
     which is copied from the `predecessor` room. If no `type` is set on the
     previous room, no `type` is specified on the new room's create event
     either.
 
+{{% boxes/note %}}
+{{% added-in v="1.16" %}} If both the new and old [room version](/rooms) support
+additional creators, the server will not transfer those additional creators automatically.
+They must be explicitly set during the `/upgrade` call.
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+{{% added-in v="1.16" %}} When upgrading to room version 12 or later, the `predecessor` field MAY NOT contain
+an `event_id`.
+{{% /boxes/note %}}
+
 3.  Replicates transferable state events to the new room. The exact
     details for what is transferred is left as an implementation detail,
     however the recommended state events to transfer are:

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

@@ -26,9 +26,10 @@ on certain keys of certain event types.
 
 The supported keys to search over are:
 
--   `content.body` in `m.room.message`
+-   `content.body` in [`m.room.message`](/client-server-api/#mroommessage)
--   `content.name` in `m.room.name`
+-   `content.name` in [`m.room.name`](/client-server-api/#mroomname)
--   `content.topic` in `m.room.topic`
+-   In [`m.room.topic`](/client-server-api/#mroomtopic), `content.topic`
+    as well as the `body` of the `text/plain` representation in `content['m.topic']`.
 
 The search will *not* include rooms that are end to end encrypted.
 

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

@@ -58,8 +58,8 @@ available on all their clients. Unless the user specifies otherwise,
 clients will try to use the default key to decrypt secrets.
 
 Clients that want to present a simplified interface to users by not supporting
-multiple keys should use the default key if one is specified. If not default
+multiple keys should use the default key if one is specified. If no default
-key is specified, the client may behave as if there is no key is present at
+key is specified, the client may behave as if no key is present at
 all. When such a client creates a key, it should mark that key as being the
 default key.
 
@@ -157,7 +157,7 @@ Some secret is encrypted using keys with ID `key_id_1` and `key_id_2`:
 
 `org.example.some.secret`:
 
-```
+```nohighlight
 {
   "encrypted": {
     "key_id_1": {
@@ -177,7 +177,7 @@ and the key descriptions for the keys would be:
 
 `m.secret_storage.key.key_id_1`:
 
-```
+```nohighlight
 {
   "name": "Some key",
   "algorithm": "m.secret_storage.v1.aes-hmac-sha2",
@@ -187,7 +187,7 @@ and the key descriptions for the keys would be:
 
 `m.secret_storage.key.key_id_2`:
 
-```
+```nohighlight
 {
   "name": "Some other key",
   "algorithm": "m.secret_storage.v1.aes-hmac-sha2",
@@ -199,7 +199,7 @@ If `key_id_1` is the default key, then we also have:
 
 `m.secret_storage.default_key`:
 
-```
+```nohighlight
 {
   "key": "key_id_1"
 }
@@ -294,7 +294,7 @@ in the `iterations` parameter.
 
 Example:
 
-```
+```nohighlight
 {
     "passphrase": {
         "algorithm": "m.pbkdf2",

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

@@ -2,8 +2,8 @@
 
 {{% added-in v="1.2" %}}
 
-Often used to group rooms of similar subject matter (such as a public "Official
+Often used to group rooms of similar subject matter (such as an "Official
-matrix.org rooms" space or personal "Work stuff" space), spaces are a way to
+matrix.org rooms" space or a "Work stuff" space), spaces are a way to
 organise rooms while being represented as rooms themselves.
 
 A space is defined by the [`m.space` room type](#types), making it known as a
@@ -18,11 +18,11 @@ In the default power level structure, this would be `100`. Clients might wish to
 go a step further and explicitly ignore notification counts on space-rooms.
 
 Membership of a space is defined and controlled by the existing mechanisms which
-govern a room: [`m.room.member`](#mroommember), [`m.room.history_visibility`](#mroomhistory_visibility),
+govern a room: [`m.room.member`](/client-server-api#mroommember), [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility),
-and [`m.room.join_rules`](#mroomjoin_rules). Public spaces are encouraged to have
+and [`m.room.join_rules`](/client-server-api#mroomjoin_rules). Canonical aliases and invites, including
-a similar setup to public rooms: `world_readable` history visibility, published
+third-party invites, still work just as they do in normal rooms as well. Furthermore,
-canonical alias, and suitably public `join_rule`. Invites, including third-party
+spaces can also be published in the [room directory](/client-server-api#published-room-directory) to make them
-invites, still work just as they do in normal rooms as well.
+discoverable.
 
 All other aspects of regular rooms are additionally carried over, such as the
 ability to set arbitrary state events, hold room account data, etc. Spaces are
@@ -58,7 +58,7 @@ parent to the room. The `state_key` for the event is the child room's ID.
 
 For example, to achieve the following:
 
-```
+```nohighlight
 #space:example.org
     #general:example.org (!abcdefg:example.org)
     !private:example.org
@@ -87,10 +87,9 @@ the state of `#space:example.org` would consist of:
 }
 ```
 
-No state events in the child rooms themselves would be required (though they
+No state events in the child rooms themselves would be required (though they can also
-can also be present). This allows for users
+be present). This allows for users to define spaces without needing explicit permission
-to define personal/private spaces to organise their own rooms without needing explicit
+from the room moderators/admins.
-permission from the room moderators/admins.
 
 Child rooms can be removed from a space by omitting the `via` key of `content` on the
 relevant state event, such as through redaction or otherwise clearing the `content`.

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

@@ -6,9 +6,10 @@ allow users to log into applications via a single web-based
 authentication portal. Examples include OpenID Connect, "Central
 Authentication Service" (CAS) and SAML.
 
-This module allows a Matrix homeserver to delegate user authentication
+This module allows a Matrix homeserver that supports the [legacy authentication
-to an external authentication server supporting one of these protocols.
+API](#legacy-api) to delegate user authentication to an external authentication
-In this process, there are three systems involved:
+server supporting one of these protocols. In this process, there are three
+systems involved:
 
 -   A Matrix client, using the APIs defined in this specification, which
     is seeking to authenticate a user to a Matrix homeserver.
@@ -24,7 +25,7 @@ used to communicate with the authentication server. Different Matrix
 homeserver implementations might support different SSO protocols.
 
 Clients and homeservers implementing the SSO flow will need to consider
-both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
+both [login](#legacy-login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
 similar in both cases, but there are slight differences.
 
 Typically, SSO systems require a single "callback" URI to be configured
@@ -66,7 +67,7 @@ opening an embedded web view.
 
 These steps are illustrated as follows:
 
-```
+```nohighlight
     Matrix Client                        Matrix Homeserver      Auth Server
         |                                       |                   |
         |-------------(0) GET /login----------->|                   |

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

@@ -16,7 +16,7 @@ when the sticker image is clicked.
 #### Events
 
 Sticker events are received as a single `m.sticker` event in the
-`timeline` section of a room, in a `/sync`.
+`timeline` section of a room, in a [`/sync`](#get_matrixclientv3sync).
 
 {{% event event="m.sticker" %}}
 

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

@@ -5,8 +5,8 @@ This module adds in support for inviting new members to a room where
 their Matrix user ID is not known, instead addressing them by a third-party
 identifier such as an email address. There are two flows here; one
 if a Matrix user ID is known for the third-party identifier, and one if
-not. Either way, the client calls `/invite` with the details of the
+not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite)
-third-party identifier.
+with the details of the third-party identifier.
 
 The homeserver asks the identity server whether a Matrix user ID is
 known for that identifier:
@@ -37,12 +37,14 @@ A client asks a server to invite a user by their third-party identifier.
 
 #### Server behaviour
 
-Upon receipt of an `/invite`, the server is expected to look up the
+Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
-third-party identifier with the provided identity server. If the lookup
+the server is expected to look up the third-party identifier with the provided
-yields a result for a Matrix User ID then the normal invite process can
+identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
-be initiated. This process ends up looking like this:
+If the lookup yields a result for a Matrix User ID then the normal [invite
+process](/server-server-api/#inviting-to-a-room) can be initiated. This process
+ends up looking like this:
 
-```
+```nohighlight
     +---------+                         +-------------+                                    +-----------------+
     | Client  |                         | Homeserver  |                                    | IdentityServer  |
     +---------+                         +-------------+                                    +-----------------+
@@ -66,12 +68,13 @@ be initiated. This process ends up looking like this:
         |                                     |                                                    |
 ```
 
-However, if the lookup does not yield a bound User ID, the homeserver
+However, if the lookup does not yield a bound User ID, the homeserver must store
-must store the invite on the identity server and emit a valid
+the invite on the identity server with a call to
-`m.room.third_party_invite` event to the room. This process ends up
+[`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
-looking like this:
+and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
+to the room. This process ends up looking like this:
 
-```
+```nohighlight
     +---------+                         +-------------+                                               +-----------------+
     | Client  |                         | Homeserver  |                                               | IdentityServer  |
     +---------+                         +-------------+                                               +-----------------+
@@ -101,15 +104,18 @@ looking like this:
         |                                     |                                                               |
 ```
 
-All homeservers MUST verify the signature in the event's
+The third-party user will then need to verify their identity, which results in a
-`content.third_party_invite.signed` object.
+request to [`/_matrix/federation/v1/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind)
+from the identity server to the homeserver that bound the third-party identifier
+to a user. The homeserver then exchanges the `m.room.third_party_invite` event
+in the room for a complete [`m.room.member`](#mroommember) event with
+`content.membership: invite` and a `content.third_party_invite` property for the
+user that has bound the third-party identifier. If the invitee is on a different
+homeserver than the inviting user, the invitee's homeserver makes a request to
+[`/_matrix/federation/v1/exchange_third_party_invite/{roomId}`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid).
 
-The third-party user will then need to verify their identity, which
+All homeservers MUST verify the signature in the `m.room.member` event's
-results in a call from the identity server to the homeserver that bound
+`content.third_party_invite.signed` object.
-the third-party identifier to a user. The homeserver then exchanges the
-`m.room.third_party_invite` event in the room for a complete
-`m.room.member` event for `membership: invite` for the user that has
-bound the third-party identifier.
 
 If a homeserver is joining a room for the first time because of an
 `m.room.third_party_invite`, the server which is already participating
@@ -127,7 +133,7 @@ and an identity server IS, the full sequence for a third-party invite
 would look like the following. This diagram assumes H1 and H2 are
 residents of the room while H3 is attempting to join.
 
-```
+```nohighlight
     +-------+ +-----------------+         +-----+                                          +-----+           +-----+                      +-----+
     | UserA | | ThirdPartyUser  |         | H1  |                                          | H2  |           | H3  |                      | IS  |
     +-------+ +-----------------+         +-----+                                          +-----+           +-----+                      +-----+
@@ -186,15 +192,15 @@ residents of the room while H3 is attempting to join.
 
 Note that when H1 sends the `m.room.member` event to H2 and H3 it does
 not have to block on either server's receipt of the event. Likewise, H1
-may complete the `/exchange_third_party_invite/:roomId` request at the
+may complete the [`/exchange_third_party_invite`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid) request at the
 same time as sending the `m.room.member` event to H2 and H3.
-Additionally, H3 may complete the `/3pid/onbind` request it got from IS
+Additionally, H3 may complete the [`/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind) request it got from IS
 at any time - the completion is not shown in the diagram.
 
 H1 MUST verify the request from H3 to ensure the `signed` property is
 correct as well as the `key_validity_url` as still being valid. This is
-done by making a request to the [identity server
+done by making a request to the identity server's
-/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
+[`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
 endpoint, using the provided URL rather than constructing a new one. The
 query string and response for the provided URL must match the Identity
 Service Specification.

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

@@ -106,10 +106,6 @@ flag to `true`.
 }
 ```
 
-For `m.room.message` events represented this way, no [reply fallback](#fallbacks-for-rich-replies)
-is specified. This allows thread-aware clients to discard the `m.in_reply_to` object entirely
-when `is_falling_back` is `true`.
-
 {{% boxes/note %}}
 Clients which are acutely aware of threads (they do not render threads, but are otherwise
 aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
@@ -189,7 +185,7 @@ included under the `m.relations` property in `unsigned` for the thread root. For
 ```
 
 `latest_event` is the most recent event (topologically to the server) in the thread sent by an
-un-[ignored user](#ignoring-users).
+un-[ignored user](#ignoring-users). It should be serialized in the same form as the event itself.
 
 Note that, as in the example above, child events of the `latest_event` should
 themselves be aggregated and included under `m.relations` for that event. The

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

@@ -129,7 +129,7 @@ or not there have been any changes to the Matrix spec.
 
 A call is set up with message events exchanged as follows:
 
-```
+```nohighlight
     Caller                    Callee
     [Place Call]
     m.call.invite ----------->
@@ -144,7 +144,7 @@ A call is set up with message events exchanged as follows:
 
 Or a rejected call:
 
-```
+```nohighlight
     Caller                      Callee
     m.call.invite ------------>
     m.call.candidate --------->
@@ -202,11 +202,13 @@ specific user, and should be set to the Matrix user ID of that user. Invites
 without an `invitee` field are defined to be intended for any member of the
 room other than the sender of the event.
 
-Clients should consider an incoming call if they see a non-expired invite event where the `invitee` field is either
+Clients should consider an incoming call if they see a non-expired invite event
-absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their
+where the `invitee` field is either absent or equal to their user's Matrix ID.
-user's trust relationship with the callers and/or where the call was placed. As a starting point, it is
+They should, however, evaluate whether or not to ring based on their user's trust
-suggested that clients ignore call invites from users in public rooms. It is strongly recommended that
+relationship with the callers and/or where the call was placed. As a starting
-when clients do not ring for an incoming call invite, they still display the call invite in the room and
+point, it is RECOMMENDED that clients ignore call invites in rooms with a
+[join rule](#mroomjoin_rules) of `public`. When clients suppress ringing for an
+incoming call invite, they SHOULD still display the call invite in the room and
 annotate that it was ignored.
 
 ##### Glare

content/identity-service-api.md

@@ -2,17 +2,15 @@
 title: "Identity Service API"
 weight: 40
 type: docs
+description: |
+  The Matrix client-server and server-server APIs are largely expressed in
+  Matrix user identifiers. Sometimes it is useful to refer to users by other
+  (“third-party”) identifiers such as email addresses or phone numbers. The
+  Identity Service API describes how mappings between 3PIDs and Matrix user
+  IDs can be established, validated, and used; in practice this has been
+  applied to email addresses and phone numbers.
 ---
 
-The Matrix client-server and server-server APIs are largely expressed in
-Matrix user identifiers. From time to time, it is useful to refer to
-users by other ("third-party") identifiers, or "3PID"s, e.g. their email
-address or phone number. This Identity Service Specification describes
-how mappings between third-party identifiers and Matrix user identifiers
-can be established, validated, and used. This description technically
-may apply to any 3PID, but in practice has only been applied
-specifically to email addresses and phone numbers.
-
 ## General principles
 
 The purpose of an identity server is to validate, store, and answer

content/olm-megolm/_index.md

@@ -0,0 +1,10 @@
+---
+title: "Olm & Megolm"
+weight: 61
+type: docs
+---
+
+Matrix uses the Olm and Megolm cryptographic ratchets for [end-to-end encryption](../client-server-api/#end-to-end-encryption).
+
+-   [Olm: A Cryptographic Ratchet](/olm-megolm/olm/)
+-   [Megolm group ratchet](/olm-megolm/megolm/)

content/olm-megolm/megolm.md

@@ -0,0 +1,378 @@
+---
+title: "Megolm group ratchet"
+weight: 20
+type: docs
+---
+
+An AES-based cryptographic ratchet intended for group communications.
+
+## Background
+
+The Megolm ratchet is intended for encrypted messaging applications where there
+may be a large number of recipients of each message, thus precluding the use of
+peer-to-peer encryption systems such as [Olm][].
+
+It also allows a recipient to decrypt received messages multiple times. For
+instance, in client/server applications, a copy of the ciphertext can be stored
+on the (untrusted) server, while the client need only store the session keys.
+
+## Overview
+
+Each participant in a conversation uses their own outbound session for
+encrypting messages. A session consists of a ratchet and an [Ed25519][] keypair.
+
+Secrecy is provided by the ratchet, which can be wound forwards but not
+backwards, and is used to derive a distinct message key for each message.
+
+Authenticity is provided via Ed25519 signatures.
+
+The value of the ratchet, and the public part of the Ed25519 key, are shared
+with other participants in the conversation via secure peer-to-peer
+channels. Provided that peer-to-peer channel provides authenticity of the
+messages to the participants and deniability of the messages to third parties,
+the Megolm session will inherit those properties.
+
+## The Megolm ratchet algorithm
+
+The Megolm ratchet \(R_i\) consists of four parts, \(R_{i,j}\) for
+\(j \in {0,1,2,3}\). The length of each part depends on the hash function
+in use (256 bits for this version of Megolm).
+
+The ratchet is initialised with cryptographically-secure random data, and
+advanced as follows:
+
+\[
+\begin{aligned}
+R_{i,0} &=
+  \begin{cases}
+  H_0\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
+  R_{i-1,0} &\text{otherwise}
+  \end{cases}\\
+R_{i,1} &=
+  \begin{cases}
+  H_1\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
+  H_1\left(R_{2^{16}(m-1),1}\right) &\text{if }\exists m | i = 2^{16}m\\
+  R_{i-1,1} &\text{otherwise}
+  \end{cases}\\
+R_{i,2} &=
+  \begin{cases}
+  H_2\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
+  H_2\left(R_{2^{16}(m-1),1}\right) &\text{if }\exists m | i = 2^{16}m\\
+  H_2\left(R_{2^8(p-1),2}\right) &\text{if }\exists p | i = 2^8p\\
+  R_{i-1,2} &\text{otherwise}
+  \end{cases}\\
+R_{i,3} &=
+  \begin{cases}
+  H_3\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
+  H_3\left(R_{2^{16}(m-1),1}\right) &\text{if }\exists m | i = 2^{16}m\\
+  H_3\left(R_{2^8(p-1),2}\right) &\text{if }\exists p | i = 2^8p\\
+  H_3\left(R_{i-1,3}\right) &\text{otherwise}
+  \end{cases}
+\end{aligned}
+\]
+
+where \(H_0\), \(H_1\), \(H_2\), and \(H_3\) are different hash
+functions. In summary: every \(2^8\) iterations, \(R_{i,3}\) is
+reseeded from \(R_{i,2}\). Every \(2^{16}\) iterations, \(R_{i,2}\)
+and \(R_{i,3}\) are reseeded from \(R_{i,1}\). Every \(2^{24}\)
+iterations, \(R_{i,1}\), \(R_{i,2}\) and \(R_{i,3}\) are reseeded
+from \(R_{i,0}\).
+
+The complete ratchet value, \(R_{i}\), is hashed to generate the keys used
+to encrypt each message. This scheme allows the ratchet to be advanced an
+arbitrary amount forwards while needing at most 1020 hash computations.  A
+client can decrypt chat history onwards from the earliest value of the ratchet
+it is aware of, but cannot decrypt history from before that point without
+reversing the hash function.
+
+This allows a participant to share its ability to decrypt chat history with
+another from a point in the conversation onwards by giving a copy of the
+ratchet at that point in the conversation.
+
+
+## The Megolm protocol
+
+### Session setup
+
+Each participant in a conversation generates their own Megolm session. A
+session consists of three parts:
+
+* a 32 bit counter, \(i\).
+* an [Ed25519][] keypair, \(K\).
+* a ratchet, \(R_i\), which consists of four 256-bit values,
+  \(R_{i,j}\) for \(j \in {0,1,2,3}\).
+
+The counter \(i\) is initialised to \(0\). A new Ed25519 keypair is
+generated for \(K\). The ratchet is simply initialised with 1024 bits of
+cryptographically-secure random data.
+
+A single participant may use multiple sessions over the lifetime of a
+conversation. The public part of \(K\) is used as an identifier to
+discriminate between sessions.
+
+### Sharing session data
+
+To allow other participants in the conversation to decrypt messages, the
+session data is formatted as described in [Session-sharing format](#session-sharing-format). It is then
+shared with other participants in the conversation via a secure peer-to-peer
+channel (such as that provided by [Olm][]).
+
+When the session data is received from other participants, the recipient first
+checks that the signature matches the public key. They then store their own
+copy of the counter, ratchet, and public key.
+
+### Message encryption
+
+This version of Megolm uses [AES-256][] in [CBC][] mode with [PKCS#7][] padding and
+[HMAC-SHA-256][] (truncated to 64 bits). The 256 bit AES key, 256 bit HMAC key,
+and 128 bit AES IV are derived from the megolm ratchet \(R_i\):
+
+\[
+\begin{aligned}
+ \mathit{AES\_KEY}_{i}\;\parallel\;\mathit{HMAC\_KEY}_{i}\;\parallel\;\mathit{AES\_IV}_{i}
+    &= \operatorname{HKDF}\left(0,\,R_{i},\text{"MEGOLM\_KEYS"},\,80\right) \\
+\end{aligned}
+\]
+
+where \(\parallel\) represents string splitting, and
+\(\operatorname{HKDF}\left(\mathit{salt},\,\mathit{IKM},\,\mathit{info},\,L\right)\)
+refers to the [HMAC-based key
+derivation function][] using using [SHA-256][] as the hash function
+([HKDF-SHA-256][]) with a salt value of \(\mathit{salt}\), input key material of
+\(\mathit{IKM}\), context string \(\mathit{info}\), and output keying material length of
+\(L\) bytes.
+
+The plain-text is encrypted with AES-256, using the key \(\mathit{AES\_KEY}_{i}\)
+and the IV \(\mathit{AES\_IV}_{i}\) to give the cipher-text, \(X_{i}\).
+
+The ratchet index \(i\), and the cipher-text \(X_{i}\), are then packed
+into a message as described in [Message format](#message-format). Then the entire message
+(including the version bytes and all payload bytes) are passed through
+HMAC-SHA-256. The first 8 bytes of the MAC are appended to the message.
+
+Finally, the authenticated message is signed using the Ed25519 keypair; the 64
+byte signature is appended to the message.
+
+The complete signed message, together with the public part of \(K\) (acting
+as a session identifier), can then be sent over an insecure channel. The
+message can then be authenticated and decrypted only by recipients who have
+received the session data.
+
+### Advancing the ratchet
+
+After each message is encrypted, the ratchet is advanced. This is done as
+described in [The Megolm ratchet algorithm](#the-megolm-ratchet-algorithm), using the following definitions:
+
+\[
+\begin{aligned}
+    H_0(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x00"}) \\
+    H_1(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x01"}) \\
+    H_2(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x02"}) \\
+    H_3(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x03"}) \\
+\end{aligned}
+\]
+
+where \(\operatorname{HMAC}(A, T)\) is the HMAC-SHA-256 of ``T``, using ``A`` as the
+key.
+
+For outbound sessions, the updated ratchet and counter are stored in the
+session.
+
+In order to maintain the ability to decrypt conversation history, inbound
+sessions should store a copy of their earliest known ratchet value (unless they
+explicitly want to drop the ability to decrypt that history - see [Partial
+Forward Secrecy](#partial-forward-secrecy)). They may also choose to cache calculated ratchet values,
+but the decision of which ratchet states to cache is left to the application.
+
+## Data exchange formats
+
+### Session sharing format
+
+This format is used for the initial sharing of a Megolm session with other
+group participants who need to be able to read messages encrypted by this
+session.
+
+The session sharing format is as follows:
+
+```nohighlight
++---+----+--------+--------+--------+--------+------+-----------+
+| V | i  | R(i,0) | R(i,1) | R(i,2) | R(i,3) | Kpub | Signature |
++---+----+--------+--------+--------+--------+------+-----------+
+0   1    5        37       69      101      133    165         229   bytes
+```
+
+The version byte, ``V``, is ``"\x02"``.
+
+This is followed by the ratchet index, \(i\), which is encoded as a
+big-endian 32-bit integer; the ratchet values \(R_{i,j}\); and the public
+part of the Ed25519 keypair \(K\).
+
+The data is then signed using the Ed25519 keypair, and the 64-byte signature is
+appended.
+
+### Session export format
+
+Once the session is initially shared with the group participants, each
+participant needs to retain a copy of the session if they want to maintain
+their ability to decrypt messages encrypted with that session.
+
+For forward-secrecy purposes, a participant may choose to store a ratcheted
+version of the session. But since the ratchet index is covered by the
+signature, this would invalidate the signature. So we define a similar format,
+called the *session export format*, which is identical to the [session sharing
+format](#session-sharing-format) except for dropping the signature.
+
+The Megolm session export format is thus as follows:
+
+```nohighlight
++---+----+--------+--------+--------+--------+------+
+| V | i  | R(i,0) | R(i,1) | R(i,2) | R(i,3) | Kpub |
++---+----+--------+--------+--------+--------+------+
+0   1    5        37       69      101      133    165   bytes
+```
+
+The version byte, ``V``, is ``"\x01"``.
+
+This is followed by the ratchet index, \(i\), which is encoded as a
+big-endian 32-bit integer; the ratchet values \(R_{i,j}\); and the public
+part of the Ed25519 keypair \(K\).
+
+### Message format
+
+Megolm messages consist of a one byte version, followed by a variable length
+payload, a fixed length message authentication code, and a fixed length
+signature.
+
+```nohighlight
++---+------------------------------------+-----------+------------------+
+| V | Payload Bytes                      | MAC Bytes | Signature Bytes  |
++---+------------------------------------+-----------+------------------+
+0   1                                    N          N+8                N+72   bytes
+```
+
+The version byte, ``V``, is ``"\x03"``.
+
+The payload uses a format based on the [Protocol Buffers encoding][]. It
+consists of the following key-value pairs:
+
+**Name**|**Tag**|**Type**|**Meaning**
+:-----:|:-----:|:-----:|:-----:
+Message-Index|0x08|Integer|The index of the ratchet, i
+Cipher-Text|0x12|String|The cipher-text, Xi, of the message
+
+Within the payload, integers are encoded using a variable length encoding. Each
+integer is encoded as a sequence of bytes with the high bit set followed by a
+byte with the high bit clear. The seven low bits of each byte store the bits of
+the integer. The least significant bits are stored in the first byte.
+
+Strings are encoded as a variable-length integer followed by the string itself.
+
+Each key-value pair is encoded as a variable-length integer giving the tag,
+followed by a string or variable-length integer giving the value.
+
+The payload is followed by the MAC. The length of the MAC is determined by the
+authenticated encryption algorithm being used (8 bytes in this version of the
+protocol). The MAC protects all of the bytes preceding the MAC.
+
+The length of the signature is determined by the signing algorithm being used
+(64 bytes in this version of the protocol). The signature covers all of the
+bytes preceding the signature.
+
+## Limitations
+
+### Message Replays
+
+A message can be decrypted successfully multiple times. This means that an
+attacker can re-send a copy of an old message, and the recipient will treat it
+as a new message.
+
+To mitigate this it is recommended that applications track the ratchet indices
+they have received and that they reject messages with a ratchet index that
+they have already decrypted.
+
+### Lack of Transcript Consistency
+
+In a group conversation, there is no guarantee that all recipients have
+received the same messages. For example, if Alice is in a conversation with Bob
+and Charlie, she could send different messages to Bob and Charlie, or could
+send some messages to Bob but not Charlie, or vice versa.
+
+Solving this is, in general, a hard problem, particularly in a protocol which
+does not guarantee in-order message delivery. For now it remains the subject of
+future research.
+
+### Lack of Backward Secrecy
+
+[Backward secrecy](https://intensecrypto.org/public/lec_08_hash_functions_part2.html#sec-forward-and-backward-secrecy)
+(also called 'future secrecy' or 'post-compromise security') is the property
+that if current private keys are compromised, an attacker cannot decrypt
+future messages in a given session.  In other words, when looking
+**backwards** in time at a compromise which has already happened, **current**
+messages are still secret.
+
+By itself, Megolm does not possess this property: once the key to a Megolm
+session is compromised, the attacker can decrypt any message that was
+encrypted using a key derived from the compromised or subsequent ratchet
+values.
+
+In order to mitigate this, the application should ensure that Megolm sessions
+are not used indefinitely. Instead it should periodically start a new session,
+with new keys shared over a secure channel.
+
+<!-- TODO: Can we recommend sensible lifetimes for Megolm sessions? Probably
+   depends how paranoid we're feeling, but some guidelines might be useful. -->
+
+### Partial Forward Secrecy
+
+[Forward secrecy](https://intensecrypto.org/public/lec_08_hash_functions_part2.html#sec-forward-and-backward-secrecy)
+(also called 'perfect forward secrecy') is the property that if the current
+private keys are compromised, an attacker cannot decrypt *past* messages in
+a given session. In other words, when looking **forwards** in time towards a
+potential future compromise, **current** messages will be secret.
+
+In Megolm, each recipient maintains a record of the ratchet value which allows
+them to decrypt any messages sent in the session after the corresponding point
+in the conversation. If this value is compromised, an attacker can similarly
+decrypt past messages which were encrypted by a key derived from the
+compromised or subsequent ratchet values. This gives 'partial' forward
+secrecy.
+
+To mitigate this issue, the application should offer the user the option to
+discard historical conversations, by winding forward any stored ratchet values,
+or discarding sessions altogether.
+
+### Dependency on secure channel for key exchange
+
+The design of the Megolm ratchet relies on the availability of a secure
+peer-to-peer channel for the exchange of session keys. Any vulnerabilities in
+the underlying channel are likely to be amplified when applied to Megolm
+session setup.
+
+For example, if the peer-to-peer channel is vulnerable to an unknown key-share
+attack, the entire Megolm session become similarly vulnerable. For example:
+Alice starts a group chat with Eve, and shares the session keys with Eve. Eve
+uses the unknown key-share attack to forward the session keys to Bob, who
+believes Alice is starting the session with him. Eve then forwards messages
+from the Megolm session to Bob, who again believes they are coming from
+Alice. Provided the peer-to-peer channel is not vulnerable to this attack, Bob
+will realise that the key-sharing message was forwarded by Eve, and can treat
+the Megolm session as a forgery.
+
+A second example: if the peer-to-peer channel is vulnerable to a replay
+attack, this can be extended to entire Megolm sessions.
+
+## License
+
+The Megolm specification (this document) is licensed under the Apache License,
+Version 2.0 http://www.apache.org/licenses/LICENSE-2.0.
+
+[Ed25519]: http://ed25519.cr.yp.to/
+[HMAC-based key derivation function]: https://tools.ietf.org/html/rfc5869
+[HKDF-SHA-256]: https://tools.ietf.org/html/rfc5869
+[HMAC-SHA-256]: https://tools.ietf.org/html/rfc2104
+[SHA-256]: https://tools.ietf.org/html/rfc6234
+[AES-256]: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
+[CBC]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+[PKCS#7]: https://tools.ietf.org/html/rfc2315
+[Olm]: https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/olm.md
+[Protocol Buffers encoding]: https://developers.google.com/protocol-buffers/docs/encoding

content/olm-megolm/olm.md

@@ -0,0 +1,334 @@
+---
+title: "Olm: A Cryptographic Ratchet"
+weight: 10
+type: docs
+---
+
+An implementation of the double cryptographic ratchet described by
+https://whispersystems.org/docs/specifications/doubleratchet/.
+
+## Notation
+
+This document uses \(\parallel\) to represent string concatenation. When
+\(\parallel\) appears on the right hand side of an \(=\) it means that
+the inputs are concatenated. When \(\parallel\) appears on the left hand
+side of an \(=\) it means that the output is split.
+
+When this document uses \(\operatorname{ECDH}\left(K_A,K_B\right)\) it means
+that each party computes a Diffie-Hellman agreement using their private key 
+and the remote party's public key.
+So party \(A\) computes \(\operatorname{ECDH}\left(K_B^{public},K_A^{private}\right)\)
+and party \(B\) computes \(\operatorname{ECDH}\left(K_A^{public},K_B^{private}\right)\).
+
+Where this document uses \(\operatorname{HKDF}\left(salt,IKM,info,L\right)\) it
+refers to the [HMAC-based key derivation function][] with a salt value of
+\(salt\), input key material of \(IKM\), context string \(info\),
+and output keying material length of \(L\) bytes.
+
+## The Olm Algorithm
+
+### Initial setup
+
+The setup takes four [Curve25519][] inputs: Identity keys for Alice and Bob,
+\(I_A\) and \(I_B\), and one-time keys for Alice and Bob,
+\(E_A\) and \(E_B\). A shared secret, \(S\), is generated using
+[Triple Diffie-Hellman][]. The initial 256 bit root key, \(R_0\), and 256
+bit chain key, \(C_{0,0}\), are derived from the shared secret using an
+HMAC-based Key Derivation Function using [SHA-256][] as the hash function
+([HKDF-SHA-256][]) with default salt and ``"OLM_ROOT"`` as the info.
+
+\[
+\begin{aligned}
+    S&=\operatorname{ECDH}\left(I_A,E_B\right)\;\parallel\;
+       \operatorname{ECDH}\left(E_A,I_B\right)\;\parallel\;
+       \operatorname{ECDH}\left(E_A,E_B\right)\\
+    R_0\;\parallel\;C_{0,0}&=
+        \operatorname{HKDF}\left(0,S,\text{``OLM\_ROOT"},64\right)
+\end{aligned}
+\]
+
+### Advancing the root key
+
+Advancing a root key takes the previous root key, \(R_{i-1}\), and two
+Curve25519 inputs: the previous ratchet key, \(T_{i-1}\), and the current
+ratchet key \(T_i\). The even ratchet keys are generated by Alice.
+The odd ratchet keys are generated by Bob. A shared secret is generated
+using Diffie-Hellman on the ratchet keys. The next root key, \(R_i\), and
+chain key, \(C_{i,0}\), are derived from the shared secret using
+[HKDF-SHA-256][] using \(R_{i-1}\) as the salt and ``"OLM_RATCHET"`` as the
+info.
+
+\[
+\begin{aligned}
+    R_i\;\parallel\;C_{i,0}&=
+        \operatorname{HKDF}\left(
+            R_{i-1},
+            \operatorname{ECDH}\left(T_{i-1},T_i\right),
+            \text{``OLM\_RATCHET"},
+            64
+        \right)
+\end{aligned}
+\]
+
+### Advancing the chain key
+
+Advancing a chain key takes the previous chain key, \(C_{i,j-1}\). The next
+chain key, \(C_{i,j}\), is the [HMAC-SHA-256][] of ``"\x02"`` using the
+previous chain key as the key.
+
+\[
+\begin{aligned}
+    C_{i,j}&=\operatorname{HMAC}\left(C_{i,j-1},\text{``\char`\\x02"}\right)
+\end{aligned}
+\]
+
+### Creating a message key
+
+Creating a message key takes the current chain key, \(C_{i,j}\). The
+message key, \(M_{i,j}\), is the [HMAC-SHA-256][] of ``"\x01"`` using the
+current chain key as the key. The message keys where \(i\) is even are used
+by Alice to encrypt messages. The message keys where \(i\) is odd are used
+by Bob to encrypt messages.
+
+\[
+\begin{aligned}
+    M_{i,j}&=\operatorname{HMAC}\left(C_{i,j},\text{``\char`\\x01"}\right)
+\end{aligned}
+\]
+
+## The Olm Protocol
+
+### Creating an outbound session
+
+Bob publishes the public parts of his identity key, \(I_B\), and some
+single-use one-time keys \(E_B\).
+
+Alice downloads Bob's identity key, \(I_B\), and a one-time key,
+\(E_B\). She generates a new single-use key, \(E_A\), and computes a
+root key, \(R_0\), and a chain key \(C_{0,0}\). She also generates a
+new ratchet key \(T_0\).
+
+### Sending the first pre-key messages
+
+Alice computes a message key, \(M_{0,j}\), and a new chain key,
+\(C_{0,j+1}\), using the current chain key. She replaces the current chain
+key with the new one.
+
+Alice encrypts her plain-text with the message key, \(M_{0,j}\), using an
+authenticated encryption scheme (see below) to get a cipher-text,
+\(X_{0,j}\).
+
+She then sends the following to Bob:
+ * The public part of her identity key, \(I_A\)
+ * The public part of her single-use key, \(E_A\)
+ * The public part of Bob's single-use key, \(E_B\)
+ * The current chain index, \(j\)
+ * The public part of her ratchet key, \(T_0\)
+ * The cipher-text, \(X_{0,j}\)
+
+Alice will continue to send pre-key messages until she receives a message from
+Bob.
+
+### Creating an inbound session from a pre-key message
+
+Bob receives a pre-key message as above.
+
+Bob looks up the private part of his single-use key, \(E_B\). He can now
+compute the root key, \(R_0\), and the chain key, \(C_{0,0}\), from
+\(I_A\), \(E_A\), \(I_B\), and \(E_B\).
+
+Bob then advances the chain key \(j\) times, to compute the chain key used
+by the message, \(C_{0,j}\). He now creates the
+message key, \(M_{0,j}\), and attempts to decrypt the cipher-text,
+\(X_{0,j}\). If the cipher-text's authentication is correct then Bob can
+discard the private part of his single-use one-time key, \(E_B\).
+
+Bob stores Alice's initial ratchet key, \(T_0\), until he wants to
+send a message.
+
+### Sending normal messages
+
+Once a message has been received from the other side, a session is considered
+established, and a more compact form is used.
+
+To send a message, the user checks if they have a sender chain key,
+\(C_{i,j}\). Alice uses chain keys where \(i\) is even. Bob uses chain
+keys where \(i\) is odd. If the chain key doesn't exist then a new ratchet
+key \(T_i\) is generated and a new root key \(R_i\) and chain key
+\(C_{i,0}\) are computed using \(R_{i-1}\), \(T_{i-1}\) and
+\(T_i\).
+
+A message key,
+\(M_{i,j}\) is computed from the current chain key, \(C_{i,j}\), and
+the chain key is replaced with the next chain key, \(C_{i,j+1}\). The
+plain-text is encrypted with \(M_{i,j}\), using an authenticated encryption
+scheme (see below) to get a cipher-text, \(X_{i,j}\).
+
+The user then sends the following to the recipient:
+ * The current chain index, \(j\)
+ * The public part of the current ratchet key, \(T_i\)
+ * The cipher-text, \(X_{i,j}\)
+
+### Receiving messages
+
+The user receives a message as above with the sender's current chain index, \(j\),
+the sender's ratchet key, \(T_i\), and the cipher-text, \(X_{i,j}\).
+
+The user checks if they have a receiver chain with the correct
+\(i\) by comparing the ratchet key, \(T_i\). If the chain doesn't exist
+then they compute a new root key, \(R_i\), and a new receiver chain, with
+chain key \(C_{i,0}\), using \(R_{i-1}\), \(T_{i-1}\) and
+\(T_i\).
+
+If the \(j\) of the message is less than
+the current chain index on the receiver then the message may only be decrypted
+if the receiver has stored a copy of the message key \(M_{i,j}\). Otherwise
+the receiver computes the chain key, \(C_{i,j}\). The receiver computes the
+message key, \(M_{i,j}\), from the chain key and attempts to decrypt the
+cipher-text, \(X_{i,j}\).
+
+If the decryption succeeds the receiver updates the chain key for \(T_i\)
+with \(C_{i,j+1}\) and stores the message keys that were skipped in the
+process so that they can decode out of order messages. If the receiver created
+a new receiver chain then they discard their current sender chain so that
+they will create a new chain when they next send a message.
+
+## The Olm Message Format
+
+Olm uses two types of messages. The underlying transport protocol must provide
+a means for recipients to distinguish between them.
+
+### Normal Messages
+
+Olm messages start with a one byte version followed by a variable length
+payload followed by a fixed length message authentication code.
+
+```nohighlight
+ +--------------+------------------------------------+-----------+
+ | Version Byte | Payload Bytes                      | MAC Bytes |
+ +--------------+------------------------------------+-----------+
+```
+
+The version byte is ``"\x03"``.
+
+The payload consists of key-value pairs where the keys are integers and the
+values are integers and strings. The keys are encoded as a variable length
+integer tag where the 3 lowest bits indicates the type of the value:
+0 for integers, 2 for strings. If the value is an integer then the tag is
+followed by the value encoded as a variable length integer. If the value is
+a string then the tag is followed by the length of the string encoded as
+a variable length integer followed by the string itself.
+
+Olm uses a variable length encoding for integers. Each integer is encoded as a
+sequence of bytes with the high bit set followed by a byte with the high bit
+clear. The seven low bits of each byte store the bits of the integer. The least
+significant bits are stored in the first byte.
+
+**Name**|**Tag**|**Type**|**Meaning**
+:-----:|:-----:|:-----:|:-----:
+Ratchet-Key|0x0A|String|The public part of the ratchet key, Ti, of the message
+Chain-Index|0x10|Integer|The chain index, j, of the message
+Cipher-Text|0x22|String|The cipher-text, Xi, j, of the message
+
+The length of the MAC is determined by the authenticated encryption algorithm
+being used. (Olm version 1 uses [HMAC-SHA-256][], truncated to 8 bytes). The
+MAC protects all of the bytes preceding the MAC.
+
+### Pre-Key Messages
+
+Olm pre-key messages start with a one byte version followed by a variable
+length payload.
+
+```nohighlight
+ +--------------+------------------------------------+
+ | Version Byte | Payload Bytes                      |
+ +--------------+------------------------------------+
+```
+
+The version byte is ``"\x03"``.
+
+The payload uses the same key-value format as for normal messages.
+
+**Name**|**Tag**|**Type**|**Meaning**
+:-----:|:-----:|:-----:|:-----:
+One-Time-Key|0x0A|String|The public part of Bob's single-use key, Eb.
+Base-Key|0x12|String|The public part of Alice's single-use key, Ea.
+Identity-Key|0x1A|String|The public part of Alice's identity key, Ia.
+Message|0x22|String|An embedded Olm message with its own version and MAC.
+
+## Olm Authenticated Encryption
+
+### Version 1
+
+Version 1 of Olm uses [AES-256][] in [CBC][] mode with [PKCS#7][] padding for
+encryption and [HMAC-SHA-256][] (truncated to 64 bits) for authentication.  The
+256 bit AES key, 256 bit HMAC key, and 128 bit AES IV are derived from the
+message key using [HKDF-SHA-256][] using the default salt and an info of
+``"OLM_KEYS"``.
+
+\[
+\begin{aligned}
+    AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j}
+    &= \operatorname{HKDF}\left(0,M_{i,j},\text{``OLM\_KEYS"},80\right)
+\end{aligned}
+\]
+
+The plain-text is encrypted with AES-256, using the key \(AES\_KEY_{i,j}\)
+and the IV \(AES\_IV_{i,j}\) to give the cipher-text, \(X_{i,j}\).
+
+Then the entire message (including the Version Byte and all Payload Bytes) are
+passed through [HMAC-SHA-256][]. The first 8 bytes of the MAC are appended to the message.
+
+## Message authentication concerns
+
+To avoid unknown key-share attacks, the application must include identifying
+data for the sending and receiving user in the plain-text of (at least) the
+pre-key messages. Such data could be a user ID, a telephone number;
+alternatively it could be the public part of a keypair which the relevant user
+has proven ownership of.
+
+### Example attacks
+
+1. Alice publishes her public [Curve25519][] identity key, \(I_A\). Eve
+   publishes the same identity key, claiming it as her own. Bob downloads
+   Eve's keys, and associates \(I_A\) with Eve. Alice sends a message to
+   Bob; Eve intercepts it before forwarding it to Bob. Bob believes the
+   message came from Eve rather than Alice.
+
+   This is prevented if Alice includes her user ID in the plain-text of the
+   pre-key message, so that Bob can see that the message was sent by Alice
+   originally.
+
+2. Bob publishes his public [Curve25519][] identity key, \(I_B\). Eve
+   publishes the same identity key, claiming it as her own. Alice downloads
+   Eve's keys, and associates \(I_B\) with Eve. Alice sends a message to
+   Eve; Eve cannot decrypt it, but forwards it to Bob. Bob believes the
+   Alice sent the message to him, whereas Alice intended it to go to Eve.
+
+   This is prevented by Alice including the user ID of the intended recpient
+   (Eve) in the plain-text of the pre-key message. Bob can now tell that the
+   message was meant for Eve rather than him.
+
+## IPR
+
+The Olm specification (this document) is hereby placed in the public domain.
+
+## Feedback
+
+Can be sent to olm at matrix.org.
+
+## Acknowledgements
+
+The ratchet that Olm implements was designed by Trevor Perrin and Moxie
+Marlinspike - details at https://whispersystems.org/docs/specifications/doubleratchet/. Olm is
+an entirely new implementation written by the Matrix.org team.
+
+[Curve25519]: http://cr.yp.to/ecdh.html
+[Triple Diffie-Hellman]: https://whispersystems.org/blog/simplifying-otr-deniability/
+[HMAC-based key derivation function]: https://tools.ietf.org/html/rfc5869
+[HKDF-SHA-256]: https://tools.ietf.org/html/rfc5869
+[HMAC-SHA-256]: https://tools.ietf.org/html/rfc2104
+[SHA-256]: https://tools.ietf.org/html/rfc6234
+[AES-256]: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
+[CBC]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+[PKCS#7]: https://tools.ietf.org/html/rfc2315

content/proposals.md

@@ -1,6 +1,6 @@
 ---
 title: "Spec Change Proposals"
-weight: 60
+weight: 62
 type: docs
 ---
 
@@ -185,6 +185,10 @@ is as follows:
     -   Take care in creating your proposal. Specify your intended
         changes, and give reasoning to back them up. Changes without
         justification will likely be poorly received by the community.
+    -   At the time of creating your draft you will not yet know the PR number, so you
+        should use a placeholder number to name your file and edit that
+        after PR submission. The suggested steps are described in
+        detail [in the proposals guide](https://github.com/matrix-org/matrix-spec-proposals#1-writing-the-proposal).
 -   Fork and make a PR to the
     [matrix-spec-proposals](https://github.com/matrix-org/matrix-spec-proposals) repository.
     The ID of your PR will become the MSC ID for the lifetime of your
@@ -277,7 +281,7 @@ corresponding labels for each stage on the
 [matrix-spec-proposals](https://github.com/matrix-org/matrix-spec-proposals)
 pull request trackers.
 
-```
+```nohighlight
                            +                          +
          Proposals         |          Spec PRs        |  Additional States
          +-------+         |          +------+        |  +---------------+
@@ -493,6 +497,42 @@ In summary:
     a small table at the bottom mapping the various values from stable
     to unstable.
 
+### Placeholder MSCs
+
+Some proposals may contain security-sensitive or private context which can't be
+publicly disclosed until a later stage in the idea or solution process. Typically,
+the initial idea is validated using some amount of implementation or experimentation
+and may require an MSC number to make that implementation easier.
+
+Placeholder MSCs are used to represent proposals in a state where implementation
+is ongoing, but the MSC details can't yet be disclosed. Authors which feel as
+though their MSC could be highly sensitive MUST get in contact with the Spec Core
+Team or [Security Team](https://matrix.org/security-disclosure-policy/) prior to
+opening their MSC. If either team determines that a placeholder MSC is required,
+it may be opened as such.
+
+There are a few expectations attached to placeholder MSCs:
+
+* They have a title which marks them WIP, and are in the "draft" state.
+* They have the following labels: `[proposal-placeholder, action-required, needs-implementation]`.
+  * Notably, *not* `proposal`.
+* They are relatively short-lived (ideally less than 6-12 months in placeholder).
+* They propose solutions which are reasonably likely to be accepted. If a placeholder
+  needs to be closed because the idea won't work, isn't needed, etc, then the MSC's
+  content MUST be published ahead of that closure.
+  * Note: the MSC's publication (and therefore closure) may be delayed until an
+    appropriate point in the security disclosure cycle. For example, an alternative
+    MSC being published, or a stream of work being completed.
+* When they are updated to receive real content, the following happens:
+  1. The Spec Core Team or the author leaves a comment to cause a notification
+     that the MSC has been replaced with real content.
+  2. The `proposal` label (or its equivalent) is added to trigger chat notifications
+     in the public Matrix rooms. The `proposal-placeholder` and `action-required`
+     labels should be removed at this stage as well. Other labels are removed/applied
+     per normal process.
+* The Spec Core Team is aware of the intended MSC's title and purpose. This is
+  especially important if the Security Team approved the use of a placeholder MSC.
+
 ## Proposal Tracking
 
 This is a living document generated from the list of proposals on the
@@ -515,7 +555,7 @@ resolve to the desired MSC, whether it started as an issue or a PR.
 Other metadata:
 
 -   The MSC number is taken from the GitHub Pull Request ID. This is
-    carried for the lifetime of the proposal. These IDs do not necessary
+    carried for the lifetime of the proposal. These IDs do not necessarily
     represent a chronological order.
 -   The GitHub PR title will act as the MSC's title.
 -   Please link to the spec PR (if any) by adding a "PRs: \#1234" line

content/push-gateway-api.md

@@ -2,19 +2,18 @@
 title: "Push Gateway API"
 weight: 50
 type: docs
+description: |
+  Clients may want to receive push notifications when events are received at the
+  homeserver. This is managed by a distinct entity called the Push Gateway.
 ---
 
-Clients may want to receive push notifications when events are received
-at the homeserver. This is managed by a distinct entity called the Push
-Gateway.
-
 ## Overview
 
 A client's homeserver forwards information about received events to the
 push gateway. The gateway then submits a push notification to the push
 notification provider (e.g. APNS, GCM).
 
-```
+```nohighlight
                                    +--------------------+  +-------------------+
                   Matrix HTTP      |                    |  |                   |
              Notification Protocol |   App Developer    |  |   Device Vendor   |

content/rooms/_index.md

@@ -36,11 +36,12 @@ 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 | 11 |
+| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
-|-------------------|---|---|---|---|---|---|---|---|---|----|----|
+|-------------------|---|---|---|---|---|---|---|---|---|----|----|----|
-| **Knocking**      | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ |
+| **Knocking**      | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ |
+| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| **`knock_restricted` join rule** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ |
+| **`knock_restricted` join rule** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ |
+| **Additional room creators** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ |
 
 ## Complete list of room versions
 
@@ -52,9 +53,22 @@ stable and unstable periodically for a variety of reasons, including
 discovered security vulnerabilities and age.
 
 Clients should not ask room administrators to upgrade their rooms if the
-room is running a stable version. Servers SHOULD use **room version 10** as
+room is running a stable version. Servers SHOULD use **room version 12** as
 the default room version when creating new rooms.
 
+{{% boxes/note %}}
+
+{{% added-in v="1.16" %}}
+
+Room version 12 is introduced and made default in this specification release.
+Servers are encouraged to continue using room version 11 as the default room
+version for the early days and weeks following this specification release,
+and then gradually switch the default over when they deem appropriate.
+
+<!-- TODO(SCT): Remove this note box in Matrix 1.17 -->
+
+{{% /boxes/note %}}
+
 The available room versions are:
 
 -   [Version 1](/rooms/v1) - **Stable**. The initial room version.
@@ -76,6 +90,9 @@ The available room versions are:
 -   [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.
+-   [Version 12](/rooms/v12) - **Stable**. Changes room IDs to be hashes of the
+    create event, formalizes room creators with infinite power level, and iterates
+    on state resolution.
 
 ## Room version grammar
 

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

@@ -30,16 +30,20 @@ The rules are as follows:
         specified by the [auth events
         selection](/server-server-api#auth-events-selection)
         algorithm described in the server specification, reject.
+
+        **Note**: This room version requires an `m.room.create` event to be selected.
     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.
+    5. If any event in `auth_events` has a `room_id` which does not match that of
+       the event being authorised, 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.aliases`:
     1.  If event has no `state_key`, reject.
-    2.  If sender's domain doesn't matches `state_key`, reject.
+    2.  If sender's domain doesn't match `state_key`, reject.
     3.  Otherwise, allow.
 5.  If type is `m.room.member`:
     1.  If there is no `state_key` property, or no `membership` property in

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

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

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

@@ -1,6 +1,6 @@
 ---
 ---
-{{< added-in v=3 >}} In room versions 1 and 2, events need a
+{{% added-in v=3 %}} In room versions 1 and 2, events need a
 signature from the domain of the `event_id` in order to be considered
 valid. This room version does not include an `event_id` over federation
 in the same respect, so does not need a signature from that server.
@@ -38,16 +38,20 @@ The complete list of rules, as of room version 3, is as follows:
         specified by the [auth events
         selection](/server-server-api#auth-events-selection)
         algorithm described in the server specification, reject.
+
+        **Note**: This room version requires an `m.room.create` event to be selected.
     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.
+    5. If any event in `auth_events` has a `room_id` which does not match that of
+       the event being authorised, 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.aliases`:
     1.  If event has no `state_key`, reject.
-    2.  If sender's domain doesn't matches `state_key`, reject.
+    2.  If sender's domain doesn't match `state_key`, reject.
     3.  Otherwise, allow.
 5.  If type is `m.room.member`:
     1.  If there is no `state_key` property, or no `membership` property in

content/rooms/fragments/v3-handling-redactions.md

@@ -17,6 +17,9 @@ is met:
 2. The domain of the redaction event's `sender` matches that of the
    original event's `sender`.
 
+Note that the first condition holds true even when the `sender` doesn't have a
+high enough power level to send the type of event that they're redacting.
+
 If the server would apply a redaction, the redaction event is also sent
 to clients. Otherwise, the server simply waits for a valid partner event
 to arrive where it can then re-check the above.

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

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

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

@@ -44,17 +44,21 @@ The rules are as follows:
         specified by the [auth events
         selection](/server-server-api#auth-events-selection)
         algorithm described in the server specification, reject.
+
+        **Note**: This room version requires an `m.room.create` event to be selected.
     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.
+    5. If any event in `auth_events` has a `room_id` which does not match that of
+       the event being authorised, 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.  {{< added-in v=8 >}}
+    2.  {{% added-in v=8 %}}
         If `content` has a `join_authorised_via_users_server` property:
         1.  If the event is not validly signed by the homeserver of the user ID denoted
             by the key, reject.
@@ -65,12 +69,12 @@ The rules are as follows:
         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.  {{< added-in v=8 >}}
+        5.  {{% added-in v=8 %}}
             If the `join_rule` is `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.
+                users or is not a joined member of the room, reject.
             3.  Otherwise, allow.
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.

content/rooms/v1.md

@@ -51,7 +51,7 @@ inconsistencies may occur.
 
 Events in version 1 rooms have the following structure:
 
-{{% definition path="api/server-server/definitions/pdu" %}}
+{{% definition path="api/server-server/definitions/pdu_v1" %}}
 
 #### Deprecated event content schemas
 

content/rooms/v10.md

@@ -18,7 +18,7 @@ refined in [room version 9](/rooms/v9)).
 
 Clients should render the new join rule accordingly for such rooms. For example:
 
-```
+```nohighlight
 This room is:
 [ ] Public
 [x] Private
@@ -120,10 +120,14 @@ The rules are as follows:
         specified by the [auth events
         selection](/server-server-api#auth-events-selection)
         algorithm described in the server specification, reject.
+
+        **Note**: This room version requires an `m.room.create` event to be selected.
     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.
+    5. If any event in `auth_events` has a `room_id` which does not match that of
+       the event being authorised, 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.
@@ -141,12 +145,12 @@ The rules are as follows:
         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.  {{< changed-in v=10 >}}
+        5.  {{% changed-in v=10 %}}
             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.
+                users or is not a joined member of the room, reject.
             3.  Otherwise, allow.
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.
@@ -197,7 +201,7 @@ The rules are as follows:
             than the `sender`'s power level, allow.
         3.  Otherwise, reject.
     7. If `membership` is `knock`:
-        1.  {{< changed-in v=10 >}}
+        1.  {{% changed-in v=10 %}}
             If the `join_rule` is anything other than `knock` or
             `knock_restricted`, reject.
         2.  If `sender` does not match `state_key`, reject.
@@ -214,11 +218,11 @@ The rules are as follows:
 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.  {{< added-in v=10 >}}
+    1.  {{% added-in v=10 %}}
         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.  {{< added-in v=10 >}}
+    2.  {{% added-in v=10 %}}
         If either of the properties `events` or `notifications` in `content`
         are present and not an object with values that are integers,
         reject.
@@ -281,7 +285,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}
 
 ### State resolution
 

content/rooms/v11.md

@@ -12,7 +12,7 @@ rules.
 
 ### Redactions
 
-{{< added-in v=11 >}} The top-level `origin`, `membership`, and `prev_state` properties
+{{% added-in v=11 %}} 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
@@ -21,7 +21,7 @@ event keeps the `redacts` property under `content`. The
 
 The full redaction algorithm follows.
 
-{{% rver-fragment name="v11-redactions" withVersioning="true" %}}
+{{% rver-fragment name="v11-redactions" %}}
 
 ### Event format
 
@@ -112,7 +112,7 @@ the [Handling redactions](#handling-redactions) section.
 
 The rules are as follows:
 
-1.  {{< changed-in v=11 >}}
+1.  {{% changed-in v=11 %}}
     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
@@ -127,10 +127,14 @@ The rules are as follows:
         specified by the [auth events
         selection](/server-server-api#auth-events-selection)
         algorithm described in the server specification, reject.
+
+        **Note**: This room version requires an `m.room.create` event to be selected.
     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.
+    5. If any event in `auth_events` has a `room_id` which does not match that of
+       the event being authorised, 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.
@@ -142,9 +146,9 @@ The rules are as follows:
         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 v=11 >}}
+        1.  {{% changed-in v=11 %}}
             If the only previous event is an `m.room.create` and the
-            `state_key` is the sender, allow.
+            `state_key` is the sender of the `m.room.create`, 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
@@ -153,7 +157,7 @@ The rules are as follows:
             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.
+                users or is not a joined member of the room, reject.
             3.  Otherwise, allow.
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.

content/rooms/v12.md

@@ -0,0 +1,501 @@
+---
+title: Room Version 12
+type: docs
+weight: 100
+version: 12
+---
+
+This room version builds on [version 11](/rooms/v11), iterating on the state resolution
+algorithm, giving room creators infinite power level, and changing the format of room
+IDs to be a hash of the create event.
+
+## Client considerations
+
+### Event format
+
+Clients SHOULD observe the following changes to events in this room version:
+
+* Room IDs no longer include a domain component and are instead a hash of the
+  `m.room.create` event, per below. See the [room ID grammar](/appendices#room-ids)
+  for more information.
+
+* A concept of "room creators" is formally defined as the `sender` of the `m.room.create`
+  event *plus* any `additional_creators` from the `m.room.create` event's `content`,
+  if present. In prior room versions, the only creator was the `sender` of the
+  `m.room.create` event (or `creator` in much older room versions).
+
+* Room creators have infinitely high power level and cannot be specified in the
+  `m.room.power_levels` event, nor can they be changed after the room is created.
+
+## 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 %}}
+
+Room version 12 is based upon room version 11 with the following considerations.
+
+### Event format
+
+{{% rver-fragment name="v12-event-format" %}}
+
+### Authorization rules
+
+Events must be signed by the server denoted by the `sender` property.
+
+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 %}}
+
+{{% boxes/note %}}
+{{% added-in v=12 %}} The power level of "room creators" is infinitely high.
+
+Room creators include:
+* The user ID denoted by the `sender` of the `m.room.create` event in the room.
+* Any user IDs contained in the `additional_creators` array in `content` of the
+  `m.room.create` event in the room, if `additional_creators` is present.
+
+Room creators cannot be demoted to a lower power level, even through `m.room.power_levels`.
+This is reflected in rule 10.4 below.
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+`m.room.redaction` events are subject to auth rules in the same way as any other event.
+In practice, that means they will normally be allowed by the auth rules, unless the
+`m.room.power_levels` event sets a power level requirement for `m.room.redaction`
+events via the `events` or `events_default` properties. In particular, the _redact
+level_ is **not** considered by the auth rules.
+
+The ability to send a redaction event does not mean that the redaction itself should
+be performed. Receiving servers must perform additional checks, as described in
+the [Handling redactions](#handling-redactions) section.
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+The `m.room.create` event MUST NOT be selected for `auth_events` on events. The
+`room_id` (being the `m.room.create` event's ID) implies this instead. This is
+reflected in a change to rule 3.2 below.
+{{% /boxes/note %}}
+
+The rules are as follows:
+
+1.  If type is `m.room.create`:
+    1.  If it has any `prev_events`, reject.
+    2.  {{% changed-in v=12 %}} If the event has a `room_id`, reject.
+
+        **Note**: The room ID is the event ID of the event with sigil `!` instead
+        of `$`.
+    3.  If `content.room_version` is present and is not a recognised
+        version, reject.
+    4.  {{% added-in v=12 %}} If `additional_creators` is present in `content` and
+        is not an array of strings where each string passes the same [user ID](/appendices#user-identifiers)
+        validation applied to `sender`, reject.
+    5.  Otherwise, allow.
+2. {{% added-in v=12 %}} If the event's `room_id` is not an event ID for an accepted
+   (not rejected) `m.room.create` event, with the sigil `!` instead of `$`, reject.
+3.  Considering the event's `auth_events`:
+    1.  If there are duplicate entries for a given `type` and `state_key` pair,
+        reject.
+    2.  {{% changed-in v=12 %}} 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.
+
+        **Note**: In this room version, `m.room.create` MUST NOT be selected.
+    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.
+    5.  If any event in `auth_events` has a `room_id` which does not match that of
+        the event being authorised, reject.
+4. 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.
+5.  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.  If the only previous event is an `m.room.create` and the
+            `state_key` is the sender of the `m.room.create`, 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 or is not a joined member of the room, 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.
+6.  If the `sender`'s current membership state is not `join`, reject.
+7.  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*.
+8.  If the event type's *required power level* is greater than the
+    `sender`'s power level, reject.
+9.  If the event has a `state_key` that starts with an `@` and does not
+    match the `sender`, reject.
+10. 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 object with keys that
+        are valid user IDs with values that are integers, reject.
+    4.  {{% added-in v=12 %}} If the `users` property in `content` contains the
+        `sender` of the `m.room.create` event or any of the `additional_creators`
+        array (if present) from the `content` of the `m.room.create` event, reject.
+    5.  If there is no previous `m.room.power_levels` event in the room,
+        allow.
+    6.  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.
+    7.  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.
+    8.  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.
+    9.  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.
+    10. 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.
+11. 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 %}}
+
+### State resolution
+
+{{% boxes/note %}}
+{{% added-in v=12 %}} This state resolution algorithm is largely the same as the
+algorithm found in [room version 2](/rooms/v2) with the following modifications:
+
+1. The *iterative auth checks algorithm* in the [Algorithm](#algorithm) subsection
+   now starts with an *empty* state map instead of the unconflicted state map.
+
+2. A new [definition](#definitions) for *conflicted state subgraph* has been added
+   which describes events that are required to authorize events during iterative
+   auth checks.
+
+3. To ensure the new conflicted state subgraph is actually referenced, the definition
+   for *full conflicted set* additionally includes the subgraph.
+{{% /boxes/note %}}
+
+The room state *S′(E)* after an event *E* is defined in terms of the
+room state *S(E)* before *E*, and depends on whether *E* is a state
+event or a message event:
+
+-   If *E* is a message event, then *S′(E)* = *S(E)*.
+-   If *E* is a state event, then *S′(E)* is *S(E)*, except that its
+    entry corresponding to the `event_type` and `state_key` of *E* is
+    replaced by the `event_id` of *E*.
+
+The room state *S(E)* before *E* is the *resolution* of the set of
+states {*S′(E*<sub>1</sub>*)*, *S′(E*<sub>2</sub>*)*, …}
+after the `prev_event`s {*E*<sub>1</sub>, *E*<sub>2</sub>, …} of *E*.
+The resolution of a set of states is given in the algorithm below.
+
+#### Definitions
+
+The state resolution algorithm for version 2 rooms uses the following
+definitions, given the set of room states
+{*S*<sub>1</sub>, *S*<sub>2</sub>, …}:
+
+**Power events.**
+A *power event* is a state event with type `m.room.power_levels` or
+`m.room.join_rules`, or a state event with type `m.room.member` where
+the `membership` is `leave` or `ban` and the `sender` does not match the
+`state_key`. The idea behind this is that power events are events that
+might remove someone's ability to do something in the room.
+
+**Unconflicted state map and conflicted state set.**
+The keys of the state maps *S<sub>i</sub>* are 2-tuples of strings of the form
+*K* = `(event_type, state_key)`. The values *V* are state events.
+The key-value pairs (*K*, *V*) across all state maps *S<sub>i</sub>* can be
+divided into two collections.
+If a given key *K* is present in every *S<sub>i</sub>* with the same value *V*
+in each state map, then the pair (*K*, *V*) belongs to the *unconflicted state map*.
+Otherwise, *V* belongs to the *conflicted state set*.
+
+Note that the unconflicted state map only has one event for each key *K*,
+whereas the conflicted state set may contain multiple events with the same key.
+
+**Auth chain.**
+The *auth chain* of an event *E* is the set containing all of *E*'s auth events,
+all of *their* auth events, and so on recursively, stretching back to the
+start of the room. Put differently, these are the events reachable by walking
+the graph induced by an event's `auth_events` links.
+
+**Auth difference.**
+The *auth difference* is calculated by first calculating the full auth
+chain for each state *S*<sub>*i*</sub>, that is the union of the auth
+chains for each event in *S*<sub>*i*</sub>, and then taking every event
+that doesn't appear in every auth chain. If *C*<sub>*i*</sub> is the
+full auth chain of *S*<sub>*i*</sub>, then the auth difference is
+∪ *C*<sub>*i*</sub> − ∩ *C*<sub>*i*</sub>.
+
+{{% added-in v=12 %}} **Conflicted state subgraph.**
+Starting from an event in the *conflicted state set* and following `auth_events`
+edges may lead to another event in the conflicted state set. The union of all
+such paths between any pair of events in the conflicted state set (including
+endpoints) forms a subgraph of the original `auth_event` graph, called the
+*conflicted state subgraph*.
+
+{{% changed-in v=12 %}} **Full conflicted set.**
+The *full conflicted set* is the union of the conflicted state set, the conflicted
+state subgraph, and the auth difference.
+
+**Reverse topological power ordering.**
+The *reverse topological power ordering* of a set of events is the
+lexicographically smallest topological ordering based on the DAG formed
+by auth events. The reverse topological power ordering is ordered from
+earliest event to latest. For comparing two topological orderings to
+determine which is the lexicographically smallest, the following
+comparison relation on events is used: for events *x* and *y*,
+*x* &lt; *y* if
+
+1.  *x*'s sender has *greater* power level than *y*'s sender, when
+    looking at their respective `auth_event`s; or
+2.  the senders have the same power level, but *x*'s `origin_server_ts`
+    is *less* than *y*'s `origin_server_ts`; or
+3.  the senders have the same power level and the events have the same
+    `origin_server_ts`, but *x*'s `event_id` is *less* than *y*'s
+    `event_id`.
+
+The reverse topological power ordering can be found by sorting the
+events using Kahn's algorithm for topological sorting, and at each step
+selecting, among all the candidate vertices, the smallest vertex using
+the above comparison relation.
+
+**Mainline ordering.**
+Let *P* = *P*<sub>0</sub> be an `m.room.power_levels` event.
+Starting with *i* = 0, repeatedly fetch *P*<sub>*i*+1</sub>, the
+`m.room.power_levels` event in the `auth_events` of *P<sub>i</sub>*.
+Increment *i* and repeat until *P<sub>i</sub>* has no `m.room.power_levels`
+event in its `auth_events`.
+The *mainline of P*<sub>0</sub> is the list of events
+    [*P*<sub>0</sub> , *P*<sub>1</sub>, ... , *P<sub>n</sub>*],
+fetched in this way.
+
+Let *e* = *e<sub>0</sub>* be another event (possibly another
+`m.room.power_levels` event). We can compute a similar list of events
+    [*e*<sub>1</sub>, ..., *e<sub>m</sub>*],
+where *e*<sub>*j*+1</sub> is the `m.room.power_levels` event in the
+`auth_events` of *e<sub>j</sub>* and where *e<sub>m</sub>* has no
+`m.room.power_levels` event in its `auth_events`. (Note that the event we
+started with, *e<sub>0</sub>*, is not included in this list. Also note that it
+may be empty, because *e* may not cite an `m.room.power_levels` event in its
+`auth_events` at all.)
+
+Now compare these two lists as follows.
+* Find the smallest index *j* ≥ 1 for which *e<sub>j</sub>* belongs to the
+   mainline of *P*.
+* If such a *j* exists, then *e<sub>j</sub>* = *P<sub>i</sub>* for some unique
+  index *i* ≥ 0. Otherwise set *i* = ∞, where ∞ is a sentinel value greater
+  than any integer.
+* In both cases, the *mainline position* of *e* is *i*.
+
+Given mainline positions calculated from *P*, the *mainline ordering based on* *P* of a set of events is the ordering,
+from smallest to largest, using the following comparison relation on
+events: for events *x* and *y*, *x* &lt; *y* if
+
+1.  the mainline position of *x* is **greater** than
+    the mainline position of *y* (i.e. the auth chain of
+    *x* is based on an earlier event in the mainline than *y*); or
+2.  the mainline positions of the events are the same, but *x*'s
+    `origin_server_ts` is *less* than *y*'s `origin_server_ts`; or
+3.  the mainline positions of the events are the same and the events have the
+    same `origin_server_ts`, but *x*'s `event_id` is *less* than *y*'s
+    `event_id`.
+
+**Iterative auth checks.**
+The *iterative auth checks algorithm* takes as input an initial room
+state and a sorted list of state events, and constructs a new room state
+by iterating through the event list and applying the state event to the
+room state if the state event is allowed by the [authorization
+rules](/server-server-api#authorization-rules).
+If the state event is not allowed by the authorization rules, then the
+event is ignored. If a `(event_type, state_key)` key that is required
+for checking the authorization rules is not present in the state, then
+the appropriate state event from the event's `auth_events` is used if
+the auth event is not rejected.
+
+#### Algorithm
+
+The *resolution* of a set of states is obtained as follows:
+
+1.  Select the set *X* of all *power events* that appear in the *full
+    conflicted set*. For each such power event *P*, enlarge *X* by adding
+    the events in the auth chain of *P* which also belong to the full
+    conflicted set. Sort *X* into a list using the *reverse topological
+    power ordering*.
+2.  {{% changed-in v=12 %}} Apply the *iterative auth checks algorithm*,
+    starting from an *empty* state map, to the list of events from the previous
+    step to get a partially resolved state.
+3.  Take all remaining events that weren't picked in step 1 and order
+    them by the mainline ordering based on the power level in the
+    partially resolved state obtained in step 2.
+4.  Apply the *iterative auth checks algorithm* on the partial resolved
+    state and the list of events from the previous step.
+5.  Update the result by replacing any event with the event with the
+    same key from the *unconflicted state map*, if such an event exists,
+    to get the final resolved state.
+
+#### Rejected events
+
+Events that have been rejected due to failing auth based on the state at
+the event (rather than based on their auth chain) are handled as usual
+by the algorithm, unless otherwise specified.
+
+Note that no events rejected due to failure to auth against their auth
+chain should appear in the process, as they should not appear in state
+(the algorithm only uses events that appear in either the state sets or
+in the auth chain of the events in the state sets).
+
+{{% boxes/rationale %}}
+This helps ensure that different servers' view of state is more likely
+to converge, since rejection state of an event may be different. This
+can happen if a third server gives an incorrect version of the state
+when a server joins a room via it (either due to being faulty or
+malicious). Convergence of state is a desirable property as it ensures
+that all users in the room have a (mostly) consistent view of the state
+of the room. If the view of the state on different servers diverges it
+can lead to bifurcation of the room due to e.g. servers disagreeing on
+who is in the room.
+
+Intuitively, using rejected events feels dangerous, however:
+
+1.  Servers cannot arbitrarily make up state, since they still need to
+    pass the auth checks based on the event's auth chain (e.g. they
+    can't grant themselves power levels if they didn't have them
+    before).
+2.  For a previously rejected event to pass auth there must be a set of
+    state that allows said event. A malicious server could therefore
+    produce a fork where it claims the state is that particular set of
+    state, duplicate the rejected event to point to that fork, and send
+    the event. The duplicated event would then pass the auth checks.
+    Ignoring rejected events would therefore not eliminate any potential
+    attack vectors.
+{{% /boxes/rationale %}}
+
+Rejected auth events are deliberately excluded from use in the iterative
+auth checks, as auth events aren't re-authed (although non-auth events
+are) during the iterative auth checks.
+
+## Unchanged from v11
+
+The following sections have not been modified since v11, but are included for
+completeness.
+
+### Redactions
+
+{{% rver-fragment name="v11-redactions" %}}
+
+### Handling redactions
+
+{{% rver-fragment name="v3-handling-redactions" %}}
+
+### Event IDs
+
+{{% rver-fragment name="v4-event-ids" %}}
+
+### Canonical JSON
+
+{{% rver-fragment name="v6-canonical-json" %}}
+
+### Signing key validity period
+
+{{% rver-fragment name="v5-signing-requirements" %}}

content/rooms/v2.md

@@ -49,7 +49,7 @@ completeness.
 
 Events in rooms of this version have the following structure:
 
-{{% definition path="api/server-server/definitions/pdu" %}}
+{{% definition path="api/server-server/definitions/pdu_v1" %}}
 
 #### Deprecated event content schemas
 

content/rooms/v3.md

@@ -90,7 +90,7 @@ The complete structure of a event in a v3 room is shown below.
 ### Authorization rules
 
 {{% boxes/note %}}
-{{< added-in v=3 >}} `m.room.redaction` events are subject to auth rules in
+{{% added-in v=3 %}} `m.room.redaction` events are subject to auth rules in
 the same way as any other event. In practice, that means they will normally be allowed
 by the auth rules, unless the `m.room.power_levels` event sets a power level requirement
 for `m.room.redaction`events via the `events` or `events_default` properties. In

content/rooms/v6.md

@@ -16,7 +16,7 @@ which implement the redaction algorithm locally should refer to the
 
 ### Redactions
 
-{{< added-in v=6 >}} All significant meaning for `m.room.aliases`
+{{% added-in v=6 %}} All significant meaning for `m.room.aliases`
 has been removed from the redaction algorithm. The remaining rules are
 the same as past room versions.
 
@@ -39,13 +39,20 @@ in [room version 5](/rooms/v5).
 
 [See above](#redactions).
 
+### Event format
+
+{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
+the `depth` limit has been reduced in this room version.
+
+{{% rver-fragment name="v6-event-format" %}}
+
 ### Authorization rules
 
-{{< added-in v=6 >}} Rule 4, which related specifically to events
+{{% added-in v=6 %}} Rule 4, which related specifically to events
 of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass
 authorization checks relating to state events.
 
-{{< added-in v=6 >}} Additionally, the authorization rules for events of
+{{% added-in v=6 %}} Additionally, the authorization rules for events of
 type `m.room.power_levels` now include a `notifications` property under
 `content`.  This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked
 the `events` property.
@@ -88,14 +95,24 @@ The rules are as follows:
         version, reject.
     4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
-2.  Reject if event has `auth_events` that:
+2.  Considering the event's `auth_events`:
-    1.  have duplicate entries for a given `type` and `state_key` pair
+    1.  If there are duplicate entries for a given `type` and `state_key` pair,
-    2.  have entries whose `type` and `state_key` don't match those
+        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.
+        algorithm described in the server specification, reject.
-3.  If event does not have a `m.room.create` in its `auth_events`,
+
-    reject.
+        **Note**: This room version requires an `m.room.create` event to be selected.
+    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.
+    5. If any event in `auth_events` has a `room_id` which does not match that of
+       the event being authorised, 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.
@@ -175,12 +192,12 @@ The rules are as follows:
             power level, reject.
         2.  If the new value is higher than the `sender`'s current power
             level, reject.
-    4.  {{< changed-in v=6 >}}
+    4.  {{% changed-in v=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.
-    5.  {{< changed-in v=6 >}}
+    5.  {{% changed-in v=6 %}}
         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
@@ -223,10 +240,6 @@ completeness.
 
 {{% rver-fragment name="v4-event-ids" %}}
 
-### Event format
-
-{{% rver-fragment name="v4-event-format" %}}
-
 #### Deprecated event content schemas
 
 {{% rver-fragment name="v1-deprecated-formatting-off-spec" %}}

content/rooms/v7.md

@@ -33,7 +33,7 @@ as do the versions v6 is based upon.
 
 ### Authorization rules
 
-{{< added-in v=7 >}} For checks performed upon `m.room.member` events, a
+{{% added-in v=7 %}} For checks performed upon `m.room.member` events, a
 new point for `membership=knock` is added.
 
 Events must be signed by the server denoted by the `sender` property.
@@ -74,14 +74,24 @@ The rules are as follows:
         version, reject.
     4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
-2.  Reject if event has `auth_events` that:
+2.  Considering the event's `auth_events`:
-    1.  have duplicate entries for a given `type` and `state_key` pair
+    1.  If there are duplicate entries for a given `type` and `state_key` pair,
-    2.  have entries whose `type` and `state_key` don't match those
+        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.
+        algorithm described in the server specification, reject.
-3.  If event does not have a `m.room.create` in its `auth_events`,
+
-    reject.
+        **Note**: This room version requires an `m.room.create` event to be selected.
+    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.
+    5. If any event in `auth_events` has a `room_id` which does not match that of
+       the event being authorised, 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.
@@ -90,7 +100,7 @@ The rules are as follows:
             `state_key` is the creator, allow.
         2.  If the `sender` does not match `state_key`, reject.
         3.  If the `sender` is banned, reject.
-        4.  {{< changed-in v=7 >}}
+        4.  {{% changed-in v=7 %}}
             If the `join_rule` is `invite` or `knock` then allow if
             membership state is `invite` or `join`.
         5.  If the `join_rule` is `public`, allow.
@@ -122,7 +132,7 @@ The rules are as follows:
             the *invite level*, allow.
         5.  Otherwise, reject.
     4.  If `membership` is `leave`:
-        1.  {{< changed-in v=7 >}}
+        1.  {{% changed-in v=7 %}}
             If the `sender` matches `state_key`, allow if and only if
             that user's current membership state is `invite`, `join`,
             or `knock`.
@@ -142,7 +152,7 @@ The rules are as follows:
             the *ban level*, and the *target user*'s power level is less
             than the `sender`'s power level, allow.
         3.  Otherwise, reject.
-    6.  {{< added-in v=7 >}}
+    6.  {{% added-in v=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.
@@ -219,7 +229,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}
 
 #### Deprecated event content schemas
 

content/rooms/v8.md

@@ -84,7 +84,7 @@ room without invite. Otherwise, the room version inherits all properties of
 
 ### Authorization rules
 
-{{< added-in v=8 >}} For checks performed upon `m.room.member` events, new
+{{% added-in v=8 %}} For checks performed upon `m.room.member` events, new
 points for handling `content.join_authorised_via_users_server` are added (Rule 4.2
 and 4.3.5).
 
@@ -109,7 +109,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}
 
 #### Deprecated event content schemas
 

content/rooms/v9.md

@@ -18,7 +18,7 @@ Clients which implement the redaction algorithm locally should refer to the
 
 ### Redactions
 
-{{< added-in v=9 >}} [`m.room.member`](/client-server-api#mroommember) events
+{{% added-in v=9 %}} [`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.
 
@@ -74,7 +74,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}
 
 #### Deprecated event content schemas
 

content/server-server-api.md

@@ -2,49 +2,46 @@
 title: "Server-Server API"
 weight: 20
 type: docs
+description: |
+  Matrix homeservers use the Federation APIs (also known as server-server APIs)
+  to communicate with each other. Homeservers use these APIs to push messages in
+  real-time, retrieve historic messages, and query profile or presence
+  information about users on other servers. The APIs are implemented over HTTPS,
+  with authentication provided by public key signatures both at the TLS
+  transport layer and in HTTP Authorization headers.
+
+  There are three main kinds of communication that occur between
+  homeservers:
+
+  Persistent Data Units (PDUs):
+  These events are broadcast from one homeserver to any others that have
+  joined the same room (identified by Room ID). They are persisted in
+  long-term storage and record the history of messages and state for a
+  room.
+
+  Like email, it is the responsibility of the originating server of a PDU
+  to deliver that event to its recipient servers. However PDUs are signed
+  using the originating server's private key so that it is possible to
+  deliver them through third-party servers.
+
+  Ephemeral Data Units (EDUs):
+  These events are pushed between pairs of homeservers. They are not
+  persisted and are not part of the history of a room, nor does the
+  receiving homeserver have to reply to them.
+
+  Queries:
+  These are single request/response interactions between a given pair of
+  servers, initiated by one side sending an HTTPS GET request to obtain
+  some information, and responded by the other. They are not persisted and
+  contain no long-term significant history. They simply request a snapshot
+  state at the instant the query is made.
+
+  EDUs and PDUs are further wrapped in an envelope called a Transaction,
+  which is transferred from the origin to the destination homeserver using
+  an HTTPS PUT request.
+
 ---
 
-Matrix homeservers use the Federation APIs (also known as server-server
-APIs) to communicate with each other. Homeservers use these APIs to push
-messages to each other in real-time, to retrieve historic messages from
-each other, and to query profile and presence information about users on
-each other's servers.
-
-The APIs are implemented using HTTPS requests between each of the
-servers. These HTTPS requests are strongly authenticated using public
-key signatures at the TLS transport layer and using public key
-signatures in HTTP Authorization headers at the HTTP layer.
-
-There are three main kinds of communication that occur between
-homeservers:
-
-Persistent Data Units (PDUs):
-These events are broadcast from one homeserver to any others that have
-joined the same room (identified by Room ID). They are persisted in
-long-term storage and record the history of messages and state for a
-room.
-
-Like email, it is the responsibility of the originating server of a PDU
-to deliver that event to its recipient servers. However PDUs are signed
-using the originating server's private key so that it is possible to
-deliver them through third-party servers.
-
-Ephemeral Data Units (EDUs):
-These events are pushed between pairs of homeservers. They are not
-persisted and are not part of the history of a room, nor does the
-receiving homeserver have to reply to them.
-
-Queries:
-These are single request/response interactions between a given pair of
-servers, initiated by one side sending an HTTPS GET request to obtain
-some information, and responded by the other. They are not persisted and
-contain no long-term significant history. They simply request a snapshot
-state at the instant the query is made.
-
-EDUs and PDUs are further wrapped in an envelope called a Transaction,
-which is transferred from the origin to the destination homeserver using
-an HTTPS PUT request.
-
 ## API standards
 
 The mandatory baseline for server-server communication in Matrix is
@@ -119,7 +116,8 @@ to send. The process overall is as follows:
     server must present a valid certificate for the hostname.
 
 3.  If the hostname is not an IP literal, a regular HTTPS request is
-    made to `https://<hostname>/.well-known/matrix/server`, expecting
+    made to `https://<hostname>/.well-known/matrix/server` (according to
+    [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)), expecting
     the schema defined later in this section. 30x redirects should be
     followed, however redirection loops should be avoided. Responses
     (successful or otherwise) to the `/.well-known` endpoint should be
@@ -148,7 +146,7 @@ to send. The process overall is as follows:
         Requests must be made with a `Host` header of
         `<delegated_hostname>:<delegated_port>`. The target server must
         present a valid certificate for `<delegated_hostname>`.
-    3.  {{< added-in v="1.8" >}} 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.
@@ -171,7 +169,7 @@ to send. The process overall is as follows:
         `<delegated_hostname>`. The target server must present a valid
         certificate for `<delegated_hostname>`.
 
-4.  {{< added-in v="1.8" >}} If the `/.well-known` request resulted in an error response, a server is
+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`
@@ -288,7 +286,7 @@ and any query parameters if present, but should not include the leading
 
 Step 1 sign JSON:
 
-```
+```nohighlight
 {
     "method": "POST",
     "uri": "/target",
@@ -375,7 +373,7 @@ The authorization parameters to include are:
 
 - `origin`: the server name of the sending server. This is the same as the
   `origin` field from JSON described in step 1.
-- `destination`: {{< added-in v="1.3" >}} the server name of the receiving
+- `destination`: {{% added-in v="1.3" %}} the server name of the receiving
   server. This is the same as the `destination` field from the JSON described
   in step 1. For compatibility with older servers, recipients should accept
   requests without this parameter, but MUST always send it. If this property
@@ -389,7 +387,7 @@ The authorization parameters to include are:
 Unknown parameters are ignored.
 
 {{% boxes/note %}}
-{{< changed-in v="1.11" >}}
+{{% changed-in v="1.11" %}}
 This section used to reference [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1)
 and [RFC 7230](https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2), that
 were obsoleted by RFC 9110 without changes to the sections of interest here.
@@ -460,9 +458,12 @@ specification](/rooms).
 Whenever a server receives an event from a remote server, the receiving
 server must ensure that the event:
 
-1.  Is a valid event, otherwise it is dropped. For an event to be valid, it
+1.  {{% changed-in v="1.16" %}} Is a valid event, otherwise it is dropped. For
-    must contain a `room_id`, and it must comply with the event format of
+    an event to be valid, it must comply with the event format of that [room version](/rooms).
-    that [room version](/rooms).
+    For some room versions, a `room_id` may also be required on the event in order
+    to determine the room version to check the event against. See the event format
+    section of the [room version specifications](/rooms) for details on when it
+    is required.
 2.  Passes signature checks, otherwise it is dropped.
 3.  Passes hash checks, otherwise it is redacted before being processed
     further.
@@ -528,7 +529,8 @@ the sender permission to send the event. The `auth_events` for the
 `m.room.create` event in a room is empty; for other events, it should be
 the following subset of the room state:
 
-- The `m.room.create` event.
+- {{% changed-in v="1.16" %}} Depending on the [room version](/rooms), the
+  `m.room.create` event.
 
 - The current `m.room.power_levels` event, if any.
 
@@ -537,14 +539,14 @@ the following subset of the room state:
 - If type is `m.room.member`:
 
     - The target's current `m.room.member` event, if any.
-    - If `membership` is `join` or `invite`, the current
+    - If `membership` is `join`, `invite` or `knock`, the current
       `m.room.join_rules` event, if any.
     - If membership is `invite` and `content` contains a
       `third_party_invite` property, the current
       `m.room.third_party_invite` event with `state_key` matching
       `content.third_party_invite.signed.token`, if any.
-    - If `content.join_authorised_via_users_server` is present,
+    - If `membership` is `join`, `content.join_authorised_via_users_server`
-      and the [room version supports restricted rooms](/rooms/#feature-matrix),
+      is present, and the [room version supports restricted rooms](/rooms/#feature-matrix),
       then the `m.room.member` event with `state_key` matching
       `content.join_authorised_via_users_server`.
 
@@ -817,7 +819,7 @@ ResidentServer->JoiningServer: send_join response
 JoiningServer->Client: join response
 -->
 
-```
+```nohighlight
 +---------+          +---------------+            +-----------------+ +-----------------+
 | Client  |          | JoiningServer |            | DirectoryServer | | ResidentServer  |
 +---------+          +---------------+            +-----------------+ +-----------------+
@@ -940,6 +942,18 @@ Note that invites are used to indicate that knocks were accepted. As such,
 receiving servers should be prepared to manually link up a previous knock
 to an invite if the invite event does not directly reference the knock.
 
+{{% boxes/note %}}
+{{% added-in v="1.16" %}} `invite_room_state` MUST now have its entries formatted
+according to the room's version (see [room version specification](/rooms)). However,
+servers SHOULD consider their local ecosystems before returning the described
+`400 M_MISSING_PARAM` error code. While migrating, servers SHOULD warn about
+invites which fail the validation rather than error in room versions 1 through 11.
+All invites to other room versions which fail validation SHOULD result in an error.
+
+The specification suggests that servers finish their migration no later than
+January 2026, though servers may extend this as required to support their users.
+{{% /boxes/note %}}
+
 {{% http-api spec="server-server" api="invites-v1" %}}
 
 {{% http-api spec="server-server" api="invites-v2" %}}
@@ -970,9 +984,8 @@ the event to other servers in the room.
 ## Third-party invites
 
 {{% boxes/note %}}
-More information about third-party invites is available in the
+More information about third-party invites is available in the Client-Server API
-[Client-Server API](/client-server-api) under
+under the [Third-party invites](/client-server-api/#third-party-invites) module.
-the Third-party Invites module.
 {{% /boxes/note %}}
 
 When a user wants to invite another user in a room but doesn't know the
@@ -985,38 +998,41 @@ API](/identity-service-api).
 
 ### Cases where an association exists for a third-party identifier
 
-If the third-party identifier is already bound to a Matrix ID, a lookup
+If the third-party identifier is already bound to a Matrix ID, a [lookup
-request on the identity server will return it. The invite is then
+request](/identity-service-api/#post_matrixidentityv2lookup) on the identity
-processed by the inviting homeserver as a standard `m.room.member`
+server will return it. The invite is then processed by the inviting homeserver
-invite event. This is the simplest case.
+as a [standard `m.room.member` invite event](#inviting-to-a-room). This is the
+simplest case.
 
 ### Cases where an association doesn't exist for a third-party identifier
 
 If the third-party identifier isn't bound to any Matrix ID, the inviting
-homeserver will request the identity server to store an invite for this
+homeserver will request the identity server to [store an invite](/identity-service-api/#invitation-storage)
-identifier and to deliver it to whoever binds it to its Matrix ID. It
+for this identifier and to deliver it to whoever binds it to its Matrix ID. It
-will also send an `m.room.third_party_invite` event in the room to
+will also send an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
-specify a display name, a token and public keys the identity server
+event in the room to specify a display name, a token and public keys the
-provided as a response to the invite storage request.
+identity server provided as a response to the invite storage request.
 
-When a third-party identifier with pending invites gets bound to a
+When a third-party identifier with pending invites gets bound to a Matrix ID,
-Matrix ID, the identity server will send a POST request to the ID's
+the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind)
-homeserver as described in the [Invitation
+endpoint of the the ID's homeserver as described in the [Invitation
-Storage](/identity-service-api#invitation-storage)
+Storage](/identity-service-api#invitation-storage) section of the Identity
-section of the Identity Service API.
+Service API.
 
 The following process applies for each invite sent by the identity
 server:
 
-The invited homeserver will create an `m.room.member` invite event
+The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember)
-containing a special `third_party_invite` section containing the token
+invite event containing a special `third_party_invite` section containing the
-and a signed object, both provided by the identity server.
+token and a `signed` object, both provided by the identity server.
 
 If the invited homeserver is in the room the invite came from, it can
 auth the event and send it.
 
 However, if the invited homeserver isn't in the room the invite came
-from, it will need to request the room's homeserver to auth the event.
+from, it will need to request the inviting homeserver to auth the event
+at the [`/exchange_third_party_invite`](#put_matrixfederationv1exchange_third_party_inviteroomid)
+endpoint.
 
 {{% http-api spec="server-server" api="third_party_invite" %}}
 
@@ -1045,11 +1061,10 @@ user's Matrix ID and the token delivered when the invite was stored,
 this verification will prove that the `m.room.member` invite event comes
 from the user owning the invited third-party identifier.
 
-## Public Room Directory
+## Published Room Directory
 
-To complement the [Client-Server
+To complement the [room directory in the Client-Server API](/client-server-api#published-room-directory),
-API](/client-server-api)'s room directory,
+homeservers need a way to query the published rooms of another server.
-homeservers need a way to query the public rooms for another server.
 This can be done by making a request to the `/publicRooms` endpoint for
 the server the room directory should be retrieved for.
 
@@ -1204,8 +1219,7 @@ Servers MUST use the server described in the [Matrix Content URI](/client-server
 Formatted as `mxc://{ServerName}/{MediaID}`, servers MUST download the media from
 `ServerName` using the below endpoints.
 
-{{% boxes/added-in-paragraph %}}
+{{% changed-in v="1.11" %}} Servers were previously advised to use the `/_matrix/media/*`
-{{< changed-in v="1.11" >}} Servers were previously advised to use the `/_matrix/media/*`
 endpoints described by the [Content Repository module in the Client-Server API](/client-server-api/#content-repository),
 however, those endpoints have been deprecated. New endpoints are introduced which
 require authentication. Naturally, as a server is not a user, they cannot provide
@@ -1213,7 +1227,6 @@ the required access token to those endpoints. Instead, servers MUST try the endp
 described below before falling back to the deprecated `/_matrix/media/*` endpoints
 when they receive a `404 M_UNRECOGNIZED` error. When falling back, servers MUST
 be sure to set `allow_remote` to `false`.
-{{% /boxes/added-in-paragraph %}}
 
 {{% http-api spec="server-server" api="content_repository" %}}
 
@@ -1230,7 +1243,6 @@ of `M_FORBIDDEN`.
 
 The following endpoint prefixes MUST be protected:
 
--   `/_matrix/federation/v1/send` (on a per-PDU basis)
 -   `/_matrix/federation/v1/make_join`
 -   `/_matrix/federation/v1/make_leave`
 -   `/_matrix/federation/v1/send_join`
@@ -1247,6 +1259,22 @@ The following endpoint prefixes MUST be protected:
 -   `/_matrix/federation/v1/event_auth`
 -   `/_matrix/federation/v1/get_missing_events`
 
+Additionally the [`/_matrix/federation/v1/send/{txnId}`](#put_matrixfederationv1sendtxnid)
+endpoint MUST be protected as follows:
+
+-   ACLs MUST be applied to all PDUs on a per-PDU basis. If the sending
+    server is denied access to the room identified by `room_id`, the PDU
+    MUST be ignored with an appropriate error included in the response
+    for the respective event ID.
+-   ACLs MUST be applied to all EDUs that are local to a specific room:
+
+    -   For [typing notifications (`m.typing`)](#typing-notifications), if
+        the sending server is denied access to the room identified by
+        `room_id`, the EDU MUST be ignored.
+    -   For [receipts (`m.receipt`)](#receipts), all receipts for a particular
+        room ID MUST be ignored if the sending server is denied access to
+        the room identified by that ID.
+
 ## Signing Events
 
 Signing events is complicated by the fact that servers can choose to
@@ -1324,7 +1352,7 @@ calculated as follows.
 The *content hash* of an event covers the complete event including the
 *unredacted* contents. It is calculated as follows.
 
-First, any existing `unsigned`, `signature`, and `hashes` members are
+First, any existing `unsigned`, `signatures`, and `hashes` properties are
 removed. The resulting object is then encoded as [Canonical
 JSON](/appendices#canonical-json), and the JSON is hashed using
 SHA-256.

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

@@ -11,6 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+$schema: https://json-schema.org/draft/2020-12/schema
 
 type: array
 items:

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

@@ -11,101 +11,16 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-title: Protocol
+allOf:
-type: object
+- $ref: protocol_base.yaml
-properties:
+- type: object
-  user_fields:
+  properties:
-    description: |-
+    instances:
-      Fields which may be used to identify a third-party user. These should be
+      description: |-
-      ordered to suggest the way that entities may be grouped, where higher
+        A list of objects representing independent instances of configuration.
-      groupings are ordered first. For example, the name of a network should be
+        For example, multiple networks on IRC if multiple are provided by the
-      searched before the nickname of a user.
+        same application service.
-    type: array
+      type: array
-    items:
+      items:
-      type: string
+        $ref: protocol_instance.yaml
-      description: Field used to identify a third-party user.
+  required: ['instances']
-    example: ["network", "nickname"]
-  location_fields:
-    description: |-
-      Fields which may be used to identify a third-party location. These should be
-      ordered to suggest the way that entities may be grouped, where higher
-      groupings are ordered first. For example, the name of a network should be
-      searched before the name of a channel.
-    type: array
-    items:
-      type: string
-      description: Field used to identify a third-party location.
-    example: ["network", "channel"]
-  icon:
-    description: A content URI representing an icon for the third-party protocol.
-    type: string
-    example: "mxc://example.org/aBcDeFgH"
-  field_types:
-    description: |-
-      The type definitions for the fields defined in `user_fields` and
-      `location_fields`. Each entry in those arrays MUST have an entry here.
-      The `string` key for this object is the field name itself.
-
-      May be an empty object if no fields are defined.
-    type: object
-    additionalProperties:
-      title: Field Type
-      description: Definition of valid values for a field.
-      type: object
-      properties:
-        regexp:
-          description: |-
-            A regular expression for validation of a field's value. This may be relatively
-            coarse to verify the value as the application service providing this protocol
-            may apply additional validation or filtering.
-          type: string
-        placeholder:
-          description: A placeholder serving as a valid example of the field value.
-          type: string
-      required: ['regexp', 'placeholder']
-    example: {
-      "network": {
-        "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
-        "placeholder": "irc.example.org"
-      },
-      "nickname": {
-        "regexp": "[^\\s#]+",
-        "placeholder": "username"
-      },
-      "channel": {
-        "regexp": "#[^\\s]+",
-        "placeholder": "#foobar"
-      }
-    }
-  instances:
-    description: |-
-      A list of objects representing independent instances of configuration.
-      For example, multiple networks on IRC if multiple are provided by the
-      same application service.
-    type: array
-    items:
-      type: object
-      title: Protocol Instance
-      properties:
-        desc:
-          type: string
-          description: A human-readable description for the protocol, such as the name.
-          example: "Freenode"
-        icon:
-          type: string
-          description: |-
-            An optional content URI representing the protocol. Overrides the one provided
-            at the higher level Protocol object.
-          example: "mxc://example.org/JkLmNoPq"
-        fields:
-          type: object
-          description: Preset values for `fields` the client may use to search by.
-          example: {
-            "network": "freenode"
-          }
-        network_id:
-          type: string
-          description: A unique identifier across all instances.
-          example: "freenode"
-      required: ['desc', 'fields', 'network_id']
-required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

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

@@ -0,0 +1,80 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+title: Protocol
+type: object
+properties:
+  user_fields:
+    description: |-
+      Fields which may be used to identify a third-party user. These should be
+      ordered to suggest the way that entities may be grouped, where higher
+      groupings are ordered first. For example, the name of a network should be
+      searched before the nickname of a user.
+    type: array
+    items:
+      type: string
+      description: Field used to identify a third-party user.
+    example: ["network", "nickname"]
+  location_fields:
+    description: |-
+      Fields which may be used to identify a third-party location. These should be
+      ordered to suggest the way that entities may be grouped, where higher
+      groupings are ordered first. For example, the name of a network should be
+      searched before the name of a channel.
+    type: array
+    items:
+      type: string
+      description: Field used to identify a third-party location.
+    example: ["network", "channel"]
+  icon:
+    description: A content URI representing an icon for the third-party protocol.
+    type: string
+    example: "mxc://example.org/aBcDeFgH"
+  field_types:
+    description: |-
+      The type definitions for the fields defined in `user_fields` and
+      `location_fields`. Each entry in those arrays MUST have an entry here.
+      The `string` key for this object is the field name itself.
+
+      May be an empty object if no fields are defined.
+    type: object
+    additionalProperties:
+      title: Field Type
+      description: Definition of valid values for a field.
+      type: object
+      properties:
+        regexp:
+          description: |-
+            A regular expression for validation of a field's value. This may be relatively
+            coarse to verify the value as the application service providing this protocol
+            may apply additional validation or filtering.
+          type: string
+        placeholder:
+          description: A placeholder serving as a valid example of the field value.
+          type: string
+      required: ['regexp', 'placeholder']
+    example: {
+      "network": {
+        "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
+        "placeholder": "irc.example.org"
+      },
+      "nickname": {
+        "regexp": "[^\\s#]+",
+        "placeholder": "username"
+      },
+      "channel": {
+        "regexp": "#[^\\s]+",
+        "placeholder": "#foobar"
+      }
+    }
+required: ['user_fields', 'location_fields', 'icon', 'field_types']