mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-23 06:23:43 +01:00
Merge upstream main into MSC4133
This commit is contained in:
Tom Foster
commit
569c8aafa3
21
.github/workflows/main.yml
vendored
21
.github/workflows/main.yml
vendored
|
|
@ -2,6 +2,7 @@ name: "Spec"
|
|||
|
||||
env:
|
||||
HUGO_VERSION: 0.139.0
|
||||
PYTHON_VERSION: 3.13
|
||||
|
||||
on:
|
||||
push:
|
||||
|
|
@ -40,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"
|
||||
|
|
@ -59,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"
|
||||
|
|
@ -78,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"
|
||||
|
|
@ -120,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"
|
||||
|
|
@ -154,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
|
||||
|
|
@ -172,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"
|
||||
|
|
@ -283,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 --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
|
||||
hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
|
||||
|
||||
- name: "📥 Spec definition download"
|
||||
uses: actions/download-artifact@v4
|
||||
|
|
|
|||
|
|
@ -316,13 +316,19 @@ Custom SCSS for the Matrix spec
|
|||
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 {
|
||||
|
|
@ -367,11 +373,6 @@ Custom SCSS for the Matrix spec
|
|||
}
|
||||
}
|
||||
|
||||
// add some space between two tables when they are right next to each other
|
||||
& + table {
|
||||
margin-top: 4rem;
|
||||
}
|
||||
|
||||
caption {
|
||||
caption-side: top;
|
||||
color: $dark;
|
||||
|
|
@ -443,6 +444,17 @@ Custom SCSS for the Matrix spec
|
|||
}
|
||||
}
|
||||
|
||||
/* 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;
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Minor fixes to JSON schemas.
|
||||
|
|
@ -1 +0,0 @@
|
|||
The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
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}`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Applying redactions is a SHOULD for clients.
|
||||
|
|
@ -1 +0,0 @@
|
|||
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).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that `format` is required if `formatted_body` is specified.
|
||||
|
|
@ -0,0 +1 @@
|
|||
The `latest_event` in an aggregated set of thread events uses the same format as the event itself.
|
||||
1
changelogs/client_server/newsfragments/2175.feature
Normal file
1
changelogs/client_server/newsfragments/2175.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add `format` query parameter to `GET /state/{eventType}/{stateKey}` to allow fetching metadata of a specific state event.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Minor fixes to JSON schemas.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Generate the changelog release info with Hugo, rather than the changelog generation script.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update release steps documentation.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove unused `release_date` from Hugo config.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that v1.0 of Matrix was a release prior to the current global versioning system.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix the version of the Identity Service API when Matrix 1.0 was introduced.
|
||||
1
changelogs/internal/newsfragments/2157.feature
Normal file
1
changelogs/internal/newsfragments/2157.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add "placeholder MSC" process definition.
|
||||
1
changelogs/internal/newsfragments/2172.clarification
Normal file
1
changelogs/internal/newsfragments/2172.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
GitHub actions are now building the OpenAPI `spec/identity-service-api/api.json` file.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.
|
||||
|
|
@ -23,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'
|
||||
url = 'https://matrix.org/faq'
|
||||
name = 'User Docs'
|
||||
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]
|
||||
|
|
@ -67,7 +67,7 @@ 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.
|
||||
# major = "1"
|
||||
# minor = "13"
|
||||
# minor = "15"
|
||||
|
||||
# User interface configuration
|
||||
[params.ui]
|
||||
|
|
|
|||
|
|
@ -492,10 +492,10 @@ 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
|
||||
defined third-party protocols. These room directories may be accessed by
|
||||
Application services can maintain their own published room directories for
|
||||
their defined third-party protocols. These directories may be accessed by
|
||||
clients through additional parameters on the `/publicRooms`
|
||||
client-server endpoint.
|
||||
|
||||
|
|
|
|||
93
content/changelog/v1.14.md
Normal file
93
content/changelog/v1.14.md
Normal file
|
|
@ -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))
|
||||
97
content/changelog/v1.15.md
Normal file
97
content/changelog/v1.15.md
Normal file
|
|
@ -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))
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -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.
|
||||
|
||||
|
|
@ -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,
|
||||
|
|
@ -1512,40 +1512,11 @@ message.
|
|||
|
||||
The plaintext payload is of the form:
|
||||
|
||||
```json
|
||||
{
|
||||
"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>"
|
||||
}
|
||||
}
|
||||
```
|
||||
{{% definition path="api/client-server/definitions/olm_payload" %}}
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -364,7 +364,7 @@ property under `m.new_content`.
|
|||
|
||||
A particular constraint applies to events which replace a [reply](#rich-replies):
|
||||
in contrast to the original reply, there should be no `m.in_reply_to` property
|
||||
in the the `m.relates_to` object, since it would be redundant (see
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
options for setting history visibility when creating a room.
|
||||
|
||||
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`.
|
||||
Clients may want to display a notice that events may be read by
|
||||
non-joined people if the history visibility is set to `world_readable`.
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
private, encrypted, etc).
|
||||
restrictions on how the rooms can be configured in terms of
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
target user. In large public rooms this could be undesirable.
|
||||
Presence information is published to all users who share a room with the
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -29,3 +29,9 @@ is in before accepting a report.
|
|||
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.
|
||||
|
|
|
|||
|
|
@ -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.name` in `m.room.name`
|
||||
- `content.topic` in `m.room.topic`
|
||||
- `content.body` in [`m.room.message`](/client-server-api/#mroommessage)
|
||||
- `content.name` in [`m.room.name`](/client-server-api/#mroomname)
|
||||
- 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ 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
|
||||
all. When such a client creates a key, it should mark that key as being the
|
||||
default key.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,8 @@
|
|||
|
||||
{{% added-in v="1.2" %}}
|
||||
|
||||
Often used to group rooms of similar subject matter (such as a public "Official
|
||||
matrix.org rooms" space or personal "Work stuff" space), spaces are a way to
|
||||
Often used to group rooms of similar subject matter (such as an "Official
|
||||
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),
|
||||
and [`m.room.join_rules`](#mroomjoin_rules). Public spaces are encouraged to have
|
||||
a similar setup to public rooms: `world_readable` history visibility, published
|
||||
canonical alias, and suitably public `join_rule`. Invites, including third-party
|
||||
invites, still work just as they do in normal rooms as well.
|
||||
govern a room: [`m.room.member`](/client-server-api#mroommember), [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility),
|
||||
and [`m.room.join_rules`](/client-server-api#mroomjoin_rules). Canonical aliases and invites, including
|
||||
third-party invites, still work just as they do in normal rooms as well. Furthermore,
|
||||
spaces can also be published in the [room directory](/client-server-api#published-room-directory) to make them
|
||||
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
|
||||
|
|
@ -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
|
||||
can also be present). This allows for users
|
||||
to define personal/private spaces to organise their own rooms without needing explicit
|
||||
permission from the room moderators/admins.
|
||||
No state events in the child rooms themselves would be required (though they can also
|
||||
be present). This allows for users to define spaces without needing explicit 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`.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
to an external authentication server supporting one of these protocols.
|
||||
In this process, there are three systems involved:
|
||||
This module allows a Matrix homeserver that supports the [legacy authentication
|
||||
API](#legacy-api) to delegate user authentication to an external authentication
|
||||
server supporting one of these protocols. In this process, there are three
|
||||
systems involved:
|
||||
|
||||
- A Matrix client, using the APIs defined 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
|
||||
|
|
|
|||
|
|
@ -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`](#post_matrixclientv3roomsroomidinvite) with the details of the
|
||||
third-party identifier.
|
||||
not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite)
|
||||
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,10 +37,12 @@ A client asks a server to invite a user by their third-party identifier.
|
|||
|
||||
#### Server behaviour
|
||||
|
||||
Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the
|
||||
third-party identifier with the provided identity server. If the lookup
|
||||
yields a result for a Matrix User ID then the normal invite process can
|
||||
be initiated. This process ends up looking like this:
|
||||
Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
|
||||
the server is expected to look up the third-party identifier with the provided
|
||||
identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
|
||||
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:
|
||||
|
||||
```
|
||||
+---------+ +-------------+ +-----------------+
|
||||
|
|
@ -66,10 +68,11 @@ be initiated. This process ends up looking like this:
|
|||
| | |
|
||||
```
|
||||
|
||||
However, if the lookup does not yield a bound User ID, the homeserver
|
||||
must store the invite on the identity server and emit a valid
|
||||
`m.room.third_party_invite` event to the room. This process ends up
|
||||
looking like this:
|
||||
However, if the lookup does not yield a bound User ID, the homeserver must store
|
||||
the invite on the identity server with a call to
|
||||
[`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
|
||||
and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
|
||||
to the room. This process ends up looking like this:
|
||||
|
||||
```
|
||||
+---------+ +-------------+ +-----------------+
|
||||
|
|
@ -101,15 +104,18 @@ looking like this:
|
|||
| | |
|
||||
```
|
||||
|
||||
All homeservers MUST verify the signature in the event's
|
||||
`content.third_party_invite.signed` object.
|
||||
The third-party user will then need to verify their identity, which results in a
|
||||
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
|
||||
results in a call 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` event for `membership: invite` for the user that has
|
||||
bound the third-party identifier.
|
||||
All homeservers MUST verify the signature in the `m.room.member` event's
|
||||
`content.third_party_invite.signed` object.
|
||||
|
||||
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
|
||||
|
|
@ -193,8 +199,8 @@ 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
|
||||
/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
|
||||
done by making a request to the identity server's
|
||||
[`/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.
|
||||
|
|
|
|||
|
|
@ -185,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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their
|
||||
user's trust relationship with the callers and/or where the call was placed. As a starting point, it is
|
||||
suggested that clients ignore call invites from users in public rooms. It is strongly recommended that
|
||||
when clients do not ring for an incoming call invite, they still display the call invite in the room and
|
||||
Clients should consider an incoming call if they see a non-expired invite event
|
||||
where the `invitee` field is either absent or equal to their user's Matrix ID.
|
||||
They should, however, evaluate whether or not to ring based on their user's trust
|
||||
relationship with the callers and/or where the call was placed. As a starting
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ 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 11** as
|
||||
the default room version when creating new rooms.
|
||||
|
||||
The available room versions are:
|
||||
|
|
|
|||
4
content/rooms/fragments/v6-event-format.md
Normal file
4
content/rooms/fragments/v6-event-format.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
|
||||
Events in rooms of this version have the following structure:
|
||||
|
||||
{{% definition path="api/server-server/definitions/pdu_v6" %}}
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -281,7 +281,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### State resolution
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -39,6 +39,13 @@ 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
|
||||
|
|
@ -88,14 +95,20 @@ 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:
|
||||
1. have duplicate entries for a given `type` and `state_key` pair
|
||||
2. have entries whose `type` and `state_key` don't match those
|
||||
2. Considering the event's `auth_events`:
|
||||
1. If there are duplicate entries for a given `type` and `state_key` pair,
|
||||
reject.
|
||||
2. If there are entries whose `type` and `state_key` don't match those
|
||||
specified by the [auth events
|
||||
selection](/server-server-api#auth-events-selection)
|
||||
algorithm described in the server specification.
|
||||
3. If event does not have a `m.room.create` in its `auth_events`,
|
||||
reject.
|
||||
algorithm described in the server specification, reject.
|
||||
3. If there are entries which were themselves rejected under the [checks
|
||||
performed on receipt of a
|
||||
PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
|
||||
4. If there is no `m.room.create` event among the entries, reject.
|
||||
3. If the `content` of the `m.room.create` event in the room state has the
|
||||
property `m.federate` set to `false`, and the `sender` domain of the event
|
||||
does not match the `sender` domain of the create event, reject.
|
||||
4. If type is `m.room.member`:
|
||||
1. If there is no `state_key` property, or no `membership` property in
|
||||
`content`, reject.
|
||||
|
|
@ -223,10 +236,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" %}}
|
||||
|
|
|
|||
|
|
@ -74,14 +74,20 @@ 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:
|
||||
1. have duplicate entries for a given `type` and `state_key` pair
|
||||
2. have entries whose `type` and `state_key` don't match those
|
||||
2. Considering the event's `auth_events`:
|
||||
1. If there are duplicate entries for a given `type` and `state_key` pair,
|
||||
reject.
|
||||
2. If there are entries whose `type` and `state_key` don't match those
|
||||
specified by the [auth events
|
||||
selection](/server-server-api#auth-events-selection)
|
||||
algorithm described in the server specification.
|
||||
3. If event does not have a `m.room.create` in its `auth_events`,
|
||||
reject.
|
||||
algorithm described in the server specification, reject.
|
||||
3. If there are entries which were themselves rejected under the [checks
|
||||
performed on receipt of a
|
||||
PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
|
||||
4. If there is no `m.room.create` event among the entries, reject.
|
||||
3. If the `content` of the `m.room.create` event in the room state has the
|
||||
property `m.federate` set to `false`, and the `sender` domain of the event
|
||||
does not match the `sender` domain of the create event, reject.
|
||||
4. If type is `m.room.member`:
|
||||
1. If there is no `state_key` property, or no `membership` property in
|
||||
`content`, reject.
|
||||
|
|
@ -219,7 +225,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -119,7 +119,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
|
||||
|
|
@ -537,14 +538,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,
|
||||
and the [room version supports restricted rooms](/rooms/#feature-matrix),
|
||||
- If `membership` is `join`, `content.join_authorised_via_users_server`
|
||||
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`.
|
||||
|
||||
|
|
@ -970,9 +971,8 @@ the event to other servers in the room.
|
|||
## Third-party invites
|
||||
|
||||
{{% boxes/note %}}
|
||||
More information about third-party invites is available in the
|
||||
[Client-Server API](/client-server-api) under
|
||||
the Third-party Invites module.
|
||||
More information about third-party invites is available in the Client-Server API
|
||||
under the [Third-party invites](/client-server-api/#third-party-invites) module.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When a user wants to invite another user in a room but doesn't know the
|
||||
|
|
@ -985,38 +985,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
|
||||
request on the identity server will return it. The invite is then
|
||||
processed by the inviting homeserver as a standard `m.room.member`
|
||||
invite event. This is the simplest case.
|
||||
If the third-party identifier is already bound to a Matrix ID, a [lookup
|
||||
request](/identity-service-api/#post_matrixidentityv2lookup) on the identity
|
||||
server will return it. The invite is then processed by the inviting homeserver
|
||||
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
|
||||
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
|
||||
specify a display name, a token and public keys the identity server
|
||||
provided as a response to the invite storage request.
|
||||
homeserver will request the identity server to [store an invite](/identity-service-api/#invitation-storage)
|
||||
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`](/client-server-api/#mroomthird_party_invite)
|
||||
event in the room to specify a display name, a token and public keys the
|
||||
identity server provided as a response to the invite storage request.
|
||||
|
||||
When a third-party identifier with pending invites gets bound to a
|
||||
Matrix ID, the identity server will send a POST request to the ID's
|
||||
homeserver as described in the [Invitation
|
||||
Storage](/identity-service-api#invitation-storage)
|
||||
section of the Identity Service API.
|
||||
When a third-party identifier with pending invites gets bound to a Matrix ID,
|
||||
the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind)
|
||||
endpoint of the the ID's homeserver as described in the [Invitation
|
||||
Storage](/identity-service-api#invitation-storage) section of the Identity
|
||||
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
|
||||
containing a special `third_party_invite` section containing the token
|
||||
and a signed object, both provided by the identity server.
|
||||
The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember)
|
||||
invite event containing a special `third_party_invite` section containing the
|
||||
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 +1048,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
|
||||
API](/client-server-api)'s room directory,
|
||||
homeservers need a way to query the public rooms for another server.
|
||||
To complement the [room directory in the Client-Server API](/client-server-api#published-room-directory),
|
||||
homeservers need a way to query the published rooms of another server.
|
||||
This can be done by making a request to the `/publicRooms` endpoint for
|
||||
the server the room directory should be retrieved for.
|
||||
|
||||
|
|
@ -1337,7 +1339,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.
|
||||
|
|
|
|||
|
|
@ -23,3 +23,4 @@ allOf:
|
|||
type: array
|
||||
items:
|
||||
$ref: protocol_instance.yaml
|
||||
required: ['instances']
|
||||
|
|
|
|||
|
|
@ -77,4 +77,4 @@ properties:
|
|||
"placeholder": "#foobar"
|
||||
}
|
||||
}
|
||||
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']
|
||||
required: ['user_fields', 'location_fields', 'icon', 'field_types']
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ properties:
|
|||
type: string
|
||||
description: A unique, user-defined ID of the application service which will never change.
|
||||
url:
|
||||
type: string
|
||||
type: ["null", "string"]
|
||||
description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
|
||||
as_token:
|
||||
type: string
|
||||
|
|
|
|||
141
data/api/client-server/account_deactivation.yaml
Normal file
141
data/api/client-server/account_deactivation.yaml
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2022 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.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Account Deactivation API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/account/deactivate:
|
||||
post:
|
||||
summary: Deactivate a user's account.
|
||||
description: |-
|
||||
Deactivate the user's account, removing all ability for the user to
|
||||
login again.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
operationId: deactivateAccount
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
auth:
|
||||
description: Additional authentication information for the user-interactive
|
||||
authentication API.
|
||||
allOf:
|
||||
- $ref: definitions/auth_data.yaml
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind all of the user's 3PIDs from.
|
||||
If not provided, the homeserver MUST use the `id_server`
|
||||
that was originally use to bind each identifier. If the
|
||||
homeserver does not know which `id_server` that was,
|
||||
it must return an `id_server_unbind_result` of
|
||||
`no-support`.
|
||||
example: example.org
|
||||
erase:
|
||||
x-addedInMatrixVersion: "1.10"
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the user would like their content to be erased as
|
||||
much as possible from the server.
|
||||
|
||||
Erasure means that any users (or servers) which join the
|
||||
room after the erasure request are served redacted copies of
|
||||
the events sent by this account. Users which had visibility
|
||||
on those events prior to the erasure are still able to see
|
||||
unredacted copies. No redactions are sent and the erasure
|
||||
request is not shared over federation, so other servers
|
||||
might still serve unredacted copies.
|
||||
|
||||
The server should additionally erase any non-event data
|
||||
associated with the user, such as [account data](/client-server-api/#client-config)
|
||||
and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
|
||||
|
||||
Defaults to `false` if not present.
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The account has been deactivated.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
- success
|
||||
- no-support
|
||||
description: |-
|
||||
An indicator as to whether or not the homeserver was able to unbind
|
||||
the user's 3PIDs from the identity server(s). `success` indicates
|
||||
that all identifiers have been unbound from the identity server while
|
||||
`no-support` indicates that one or more identifiers failed to unbind
|
||||
due to the identity server refusing the request or the homeserver
|
||||
being unable to determine an identity server to unbind from. This
|
||||
must be `success` if the homeserver has no identifiers to unbind
|
||||
for the user.
|
||||
example: success
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
"401":
|
||||
description: The homeserver requires additional authentication information.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/auth_response.yaml
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Account management
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- http
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/client/v3
|
||||
components:
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
$ref: definitions/security.yaml#/accessTokenQuery
|
||||
accessTokenBearer:
|
||||
$ref: definitions/security.yaml#/accessTokenBearer
|
||||
|
|
@ -201,6 +201,11 @@ paths:
|
|||
|
||||
Homeservers should prevent the caller from adding a 3PID to their account if it has
|
||||
already been added to another user's account on the homeserver.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
{{% /boxes/warning %}}
|
||||
operationId: add3PID
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -13,18 +13,21 @@
|
|||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Application Service Room Directory API
|
||||
title: Matrix Client-Server Application Service Published Room Directory API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/directory/list/appservice/{networkId}/{roomId}":
|
||||
put:
|
||||
summary: Updates a room's visibility in the application service's room directory.
|
||||
description: |-
|
||||
Updates the visibility of a given room on the application service's room
|
||||
summary: |-
|
||||
Updates a room's visibility in the application service's published room
|
||||
directory.
|
||||
description: |-
|
||||
Updates the visibility of a given room in the application service's
|
||||
published room directory.
|
||||
|
||||
This API is similar to the room directory visibility API used by clients
|
||||
to update the homeserver's more general room directory.
|
||||
This API is similar to the
|
||||
[visibility API](/client-server-api#put_matrixclientv3directorylistroomroomid)
|
||||
used by clients to update the homeserver's more general published room directory.
|
||||
|
||||
This API requires the use of an application service access token (`as_token`)
|
||||
instead of a typical client's access_token. This API cannot be invoked by
|
||||
|
|
|
|||
|
|
@ -87,12 +87,9 @@ paths:
|
|||
- public
|
||||
- private
|
||||
description: |-
|
||||
A `public` visibility indicates that the room will be shown
|
||||
in the published room list. A `private` visibility will hide
|
||||
the room from the published room list. Rooms default to
|
||||
`private` visibility if this key is not included. NB: This
|
||||
should not be confused with `join_rules` which also uses the
|
||||
word `public`.
|
||||
The room's visibility in the server's
|
||||
[published room directory](/client-server-api#published-room-directory).
|
||||
Defaults to `private`.
|
||||
room_alias_name:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
@ -109,15 +106,17 @@ paths:
|
|||
name:
|
||||
type: string
|
||||
description: |-
|
||||
If this is included, an `m.room.name` event will be sent
|
||||
into the room to indicate the name of the room. See Room
|
||||
Events for more information on `m.room.name`.
|
||||
If this is included, an [`m.room.name`](/client-server-api/#mroomname) event
|
||||
will be sent into the room to indicate the name for the room.
|
||||
This overwrites any [`m.room.name`](/client-server-api/#mroomname)
|
||||
event in `initial_state`.
|
||||
topic:
|
||||
type: string
|
||||
description: |-
|
||||
If this is included, an `m.room.topic` event will be sent
|
||||
into the room to indicate the topic for the room. See Room
|
||||
Events for more information on `m.room.topic`.
|
||||
If this is included, an [`m.room.topic`](/client-server-api/#mroomtopic)
|
||||
event with a `text/plain` mimetype will be sent into the room
|
||||
to indicate the topic for the room. This overwrites any
|
||||
[`m.room.topic`](/client-server-api/#mroomtopic) event in `initial_state`.
|
||||
invite:
|
||||
type: array
|
||||
description: |-
|
||||
|
|
@ -131,32 +130,7 @@ paths:
|
|||
A list of objects representing third-party IDs to invite into
|
||||
the room.
|
||||
items:
|
||||
type: object
|
||||
title: Invite3pid
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: The hostname+port of the identity server which should be used for
|
||||
third-party identifier lookups.
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server. Servers
|
||||
can treat this as optional to distinguish between r0.5-compatible clients
|
||||
and this specification version.
|
||||
medium:
|
||||
type: string
|
||||
description: |-
|
||||
The kind of address being passed in the address field, for example `email`
|
||||
(see [the list of recognised values](/appendices/#3pid-types)).
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third-party identifier.
|
||||
required:
|
||||
- id_server
|
||||
- id_access_token
|
||||
- medium
|
||||
- address
|
||||
$ref: definitions/invite_3pid.yaml
|
||||
room_version:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ paths:
|
|||
Publishes cross-signing keys for the user.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
|
||||
User-Interactive Authentication MUST be performed, except in these cases:
|
||||
- there is no existing cross-signing master key uploaded to the homeserver, OR
|
||||
- there is an existing cross-signing master key and it exactly matches the
|
||||
|
|
@ -34,11 +34,16 @@ paths:
|
|||
keys provided in the request (self-signing key, user-signing key) they MUST also
|
||||
match the existing keys stored on the server. In other words, the request contains
|
||||
no new keys.
|
||||
|
||||
|
||||
This allows clients to freely upload one set of keys, but not modify/overwrite keys if
|
||||
they already exist. Allowing clients to upload the same set of keys more than once
|
||||
they already exist. Allowing clients to upload the same set of keys more than once
|
||||
makes this endpoint idempotent in the case where the response is lost over the network,
|
||||
which would otherwise cause a UIA challenge upon retry.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
{{% /boxes/warning %}}
|
||||
operationId: uploadCrossSigningKeys
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
45
data/api/client-server/definitions/invite_3pid.yaml
Normal file
45
data/api/client-server/definitions/invite_3pid.yaml
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# 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.
|
||||
type: object
|
||||
title: Invite3pid
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: The hostname+port of the identity server which should be used for
|
||||
third-party identifier lookups.
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server. Servers
|
||||
can treat this as optional to distinguish between r0.5-compatible clients
|
||||
and this specification version.
|
||||
medium:
|
||||
type: string
|
||||
description: |-
|
||||
The kind of address being passed in the address field, for example `email`
|
||||
(see [the list of recognised values](/appendices/#3pid-types)).
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third-party identifier.
|
||||
required:
|
||||
- id_server
|
||||
- id_access_token
|
||||
- medium
|
||||
- address
|
||||
example: {
|
||||
"id_server": "matrix.org",
|
||||
"id_access_token": "abc123_OpaqueString",
|
||||
"medium": "email",
|
||||
"address": "cheeky@monkey.com"
|
||||
}
|
||||
|
|
@ -23,6 +23,7 @@ properties:
|
|||
type: string
|
||||
description: |-
|
||||
The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`.
|
||||
example: "m.megolm.v1.aes-sha2"
|
||||
forwarding_curve25519_key_chain:
|
||||
type: array
|
||||
items:
|
||||
|
|
@ -30,31 +31,24 @@ properties:
|
|||
description: |-
|
||||
Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](/client-server-api/#mforwarded_room_key)
|
||||
events.
|
||||
example: [ "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" ]
|
||||
sender_key:
|
||||
type: string
|
||||
description: |-
|
||||
Unpadded base64-encoded device Curve25519 key.
|
||||
example: "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
|
||||
sender_claimed_keys:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |-
|
||||
A map from algorithm name (`ed25519`) to the Ed25519 signing key of the sending device.
|
||||
example: { "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y" }
|
||||
session_key:
|
||||
type: string
|
||||
description: |-
|
||||
Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format).
|
||||
example: {
|
||||
"algorithm": "m.megolm.v1.aes-sha2",
|
||||
"forwarding_curve25519_key_chain": [
|
||||
"hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
|
||||
],
|
||||
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
|
||||
"sender_claimed_keys": {
|
||||
"ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
|
||||
},
|
||||
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
|
||||
}
|
||||
example: "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
|
||||
required:
|
||||
- algorithm
|
||||
- forwarding_curve25519_key_chain
|
||||
|
|
|
|||
88
data/api/client-server/definitions/olm_payload.yaml
Normal file
88
data/api/client-server/definitions/olm_payload.yaml
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
# 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.
|
||||
|
||||
|
||||
type: object
|
||||
title: OlmPayload
|
||||
description: |-
|
||||
The plaintext payload of Olm message events.
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: The type of the event.
|
||||
content:
|
||||
type: object
|
||||
description: The event content.
|
||||
sender:
|
||||
type: string
|
||||
description: The user ID of the event sender.
|
||||
recipient:
|
||||
type: string
|
||||
description: The user ID of the intended event recipient.
|
||||
recipient_keys:
|
||||
description: The recipient's signing keys of the encrypted event.
|
||||
$ref: "#/components/schemas/SigningKeys"
|
||||
keys:
|
||||
$ref: "#/components/schemas/SigningKeys"
|
||||
description: The sender's signing keys of the encrypted event.
|
||||
sender_device_keys:
|
||||
$ref: device_keys.yaml
|
||||
description: The sender's device keys.
|
||||
x-addedInMatrixVersion: "1.15"
|
||||
required:
|
||||
- type
|
||||
- content
|
||||
- sender
|
||||
- recipient
|
||||
- recipient_keys
|
||||
- keys
|
||||
components:
|
||||
schemas:
|
||||
SigningKeys:
|
||||
type: object
|
||||
title: SigningKeys
|
||||
description: Public keys used for an `m.olm.v1.curve25519-aes-sha2` event.
|
||||
properties:
|
||||
ed25519:
|
||||
type: string
|
||||
description: The Ed25519 public key encoded using unpadded base64.
|
||||
required:
|
||||
- ed25519
|
||||
example: {
|
||||
"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>"
|
||||
},
|
||||
"sender_device_keys": {
|
||||
"algorithms": ["<supported>", "<algorithms>"],
|
||||
"user_id": "<user_id>",
|
||||
"device_id": "<device_id>",
|
||||
"keys": {
|
||||
"ed25519:<device_id>": "<sender_ed25519_key>",
|
||||
"curve25519:<device_id>": "<sender_curve25519_key>"
|
||||
},
|
||||
"signatures": {
|
||||
"<user_id>": {
|
||||
"ed25519:<device_id>": "<device_signature>",
|
||||
"ed25519:<ssk_id>": "<ssk_signature>",
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -37,7 +37,8 @@ allOf:
|
|||
A unique identifier for this instance on the homeserver. This field is added
|
||||
to the response of [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)
|
||||
by the homeserver.
|
||||
|
||||
|
||||
This is the identifier to use as the `third_party_instance_id` in a request to
|
||||
[`POST /_matrix/client/v3/publicRooms`](/client-server-api/#post_matrixclientv3publicrooms).
|
||||
example: "irc-freenode"
|
||||
required: ['instances']
|
||||
|
|
|
|||
|
|
@ -13,10 +13,12 @@
|
|||
# limitations under the License.
|
||||
|
||||
type: object
|
||||
title: "PublicRoomsChunk"
|
||||
title: "PublishedRoomsChunk"
|
||||
properties:
|
||||
canonical_alias:
|
||||
type: string
|
||||
format: mx-room-alias
|
||||
pattern: "^#"
|
||||
description: The canonical alias of the room, if any.
|
||||
example: "#general:example.org"
|
||||
name:
|
||||
|
|
@ -29,11 +31,15 @@ properties:
|
|||
example: 42
|
||||
room_id:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
description: The ID of the room.
|
||||
example: "!abcdefg:example.org"
|
||||
topic:
|
||||
type: string
|
||||
description: The topic of the room, if any.
|
||||
description: |-
|
||||
The plain text topic of the room. Omitted if no `text/plain` mimetype
|
||||
exists in [`m.room.topic`](/client-server-api/#mroomtopic).
|
||||
example: "All things general"
|
||||
world_readable:
|
||||
type: boolean
|
||||
|
|
@ -59,7 +65,6 @@ properties:
|
|||
example: "public"
|
||||
room_type:
|
||||
type: string
|
||||
x-addedInMatrixVersion: "1.4"
|
||||
description: |-
|
||||
The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
|
||||
required:
|
||||
|
|
|
|||
|
|
@ -13,28 +13,15 @@
|
|||
# limitations under the License.
|
||||
|
||||
type: object
|
||||
description: A list of the rooms on the server.
|
||||
description: A list of the published rooms on the server.
|
||||
required: ["chunk"]
|
||||
properties:
|
||||
chunk:
|
||||
type: array
|
||||
description: |-
|
||||
A paginated chunk of public rooms.
|
||||
A paginated chunk of published rooms.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: "public_rooms_chunk.yaml"
|
||||
- type: object
|
||||
title: PublicRoomsChunk
|
||||
properties:
|
||||
# Override description of join_rule
|
||||
join_rule:
|
||||
type: string
|
||||
description: |-
|
||||
The room's join rule. When not present, the room is assumed to
|
||||
be `public`. Note that rooms with `invite` join rules are not
|
||||
expected here, but rooms with `knock` rules are given their
|
||||
near-public nature.
|
||||
example: "public"
|
||||
$ref: "public_rooms_chunk.yaml"
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
@ -50,7 +37,7 @@ properties:
|
|||
total_room_count_estimate:
|
||||
type: integer
|
||||
description: |-
|
||||
An estimate on the total number of public rooms, if the
|
||||
An estimate on the total number of published rooms, if the
|
||||
server has an estimate.
|
||||
example: {
|
||||
"chunk": [
|
||||
|
|
|
|||
44
data/api/client-server/definitions/room_summary.yaml
Normal file
44
data/api/client-server/definitions/room_summary.yaml
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# 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.
|
||||
|
||||
type: object
|
||||
title: RoomSummary
|
||||
allOf:
|
||||
- $ref: public_rooms_chunk.yaml
|
||||
- type: object
|
||||
properties:
|
||||
room_type:
|
||||
type: string
|
||||
description: The `type` of room (from
|
||||
[`m.room.create`](/client-server-api/#mroomcreate)),
|
||||
if any.
|
||||
allowed_room_ids:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
description: |-
|
||||
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
|
||||
are specified by the join rules. Empty or omitted otherwise.
|
||||
encryption:
|
||||
type: string
|
||||
enum:
|
||||
- "m.megolm.v1.aes-sha2"
|
||||
description: |-
|
||||
The encryption algorithm to be used to encrypt messages sent in the
|
||||
room.
|
||||
room_version:
|
||||
description: The version of the room.
|
||||
type: string
|
||||
|
|
@ -14,8 +14,8 @@
|
|||
accessTokenQuery:
|
||||
type: apiKey
|
||||
description: |-
|
||||
**Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query
|
||||
parameter.
|
||||
**Deprecated.** The `access_token` obtained during [account registration](/client-server-api/#account-registration)
|
||||
or [login](/client-server-api/#login), as a query parameter.
|
||||
|
||||
It can also be the `as_token` of an application service.
|
||||
name: access_token
|
||||
|
|
@ -23,11 +23,11 @@ accessTokenQuery:
|
|||
accessTokenBearer:
|
||||
type: http
|
||||
description: |-
|
||||
The `access_token` returned by a call to `/login` or `/register`, using the
|
||||
`Authorization: Bearer` header.
|
||||
The `access_token` obtained during [account registration](/client-server-api/#account-registration)
|
||||
or [login](/client-server-api/#login), using the `Authorization: Bearer` header.
|
||||
|
||||
It can also be the `as_token` of an application service.
|
||||
|
||||
|
||||
This is the preferred method.
|
||||
scheme: bearer
|
||||
appserviceAccessTokenQuery:
|
||||
|
|
@ -42,6 +42,6 @@ appserviceAccessTokenBearer:
|
|||
description: |-
|
||||
The `as_token` of an application service, using the `Authorization: Bearer`
|
||||
header.
|
||||
|
||||
|
||||
This is the preferred method.
|
||||
scheme: bearer
|
||||
|
|
|
|||
|
|
@ -137,6 +137,11 @@ paths:
|
|||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
Deletes the given device, and invalidates any access token associated with it.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
{{% /boxes/warning %}}
|
||||
operationId: deleteDevice
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -189,6 +194,11 @@ paths:
|
|||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
Deletes the given devices, and invalidates any access token associated with them.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
{{% /boxes/warning %}}
|
||||
operationId: deleteDevices
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -438,22 +438,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"403":
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
|
|
@ -571,22 +556,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"404":
|
||||
description: The backup was not found.
|
||||
content:
|
||||
|
|
@ -644,22 +614,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"403":
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
|
|
@ -778,22 +733,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"404":
|
||||
description: The backup was not found.
|
||||
content:
|
||||
|
|
@ -866,22 +806,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"403":
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
|
|
@ -1007,22 +932,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"404":
|
||||
description: The backup was not found.
|
||||
content:
|
||||
|
|
@ -1056,6 +966,26 @@ servers:
|
|||
basePath:
|
||||
default: /_matrix/client/v3
|
||||
components:
|
||||
schemas:
|
||||
RoomKeysUpdateResponse:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
|
||||
See [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)
|
||||
for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
$ref: definitions/security.yaml#/accessTokenQuery
|
||||
|
|
|
|||
|
|
@ -13,14 +13,15 @@
|
|||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Room Directory API
|
||||
title: Matrix Client-Server Published Room Directory API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/directory/list/room/{roomId}":
|
||||
get:
|
||||
summary: Gets the visibility of a room in the directory
|
||||
description: Gets the visibility of a given room on the server's public room
|
||||
directory.
|
||||
description: |-
|
||||
Gets the visibility of a given room in the server's
|
||||
published room directory.
|
||||
operationId: getRoomVisibilityOnDirectory
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -32,7 +33,7 @@ paths:
|
|||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: The visibility of the room in the directory
|
||||
description: The visibility of the room in the directory.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -50,7 +51,7 @@ paths:
|
|||
"visibility": "public"
|
||||
}
|
||||
"404":
|
||||
description: The room is not known to the server
|
||||
description: The room is not known to the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -64,14 +65,13 @@ paths:
|
|||
tags:
|
||||
- Room discovery
|
||||
put:
|
||||
summary: Sets the visibility of a room in the room directory
|
||||
summary: Sets the visibility of a room in the directory
|
||||
description: |-
|
||||
Sets the visibility of a given room in the server's public room
|
||||
directory.
|
||||
Sets the visibility of a given room in the server's published room directory.
|
||||
|
||||
Servers may choose to implement additional access control checks
|
||||
here, for instance that room visibility can only be changed by
|
||||
the room creator or a server administrator.
|
||||
Servers MAY implement additional access control checks, for instance,
|
||||
to ensure that a room's visibility can only be changed by the room creator
|
||||
or a server administrator.
|
||||
operationId: setRoomVisibilityOnDirectory
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -97,11 +97,11 @@ paths:
|
|||
- public
|
||||
description: |-
|
||||
The new visibility setting for the room.
|
||||
Defaults to 'public'.
|
||||
Defaults to `public`.
|
||||
example: {
|
||||
"visibility": "public"
|
||||
}
|
||||
description: The new visibility for the room on the room directory.
|
||||
description: The new visibility for the room in the published room directory.
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
|
|
@ -114,7 +114,7 @@ paths:
|
|||
response:
|
||||
value: {}
|
||||
"404":
|
||||
description: The room is not known to the server
|
||||
description: The room is not known to the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -129,9 +129,9 @@ paths:
|
|||
- Room discovery
|
||||
/publicRooms:
|
||||
get:
|
||||
summary: Lists the public rooms on the server.
|
||||
summary: Lists a server's published room directory
|
||||
description: |-
|
||||
Lists the public rooms on the server.
|
||||
Lists a server's published room directory.
|
||||
|
||||
This API returns paginated responses. The rooms are ordered by the number
|
||||
of joined members, with the largest rooms first.
|
||||
|
|
@ -154,13 +154,13 @@ paths:
|
|||
- in: query
|
||||
name: server
|
||||
description: |-
|
||||
The server to fetch the public room lists from. Defaults to the
|
||||
local server. Case sensitive.
|
||||
The server to fetch the published room directory from. Defaults
|
||||
to the local server. Case sensitive.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: A list of the rooms on the server.
|
||||
description: A list of the published rooms on the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -168,9 +168,9 @@ paths:
|
|||
tags:
|
||||
- Room discovery
|
||||
post:
|
||||
summary: Lists the public rooms on the server with optional filter.
|
||||
summary: Lists a server's published room directory with an optional filter
|
||||
description: |-
|
||||
Lists the public rooms on the server, with optional filter.
|
||||
Lists a server's published room directory with an optional filter.
|
||||
|
||||
This API returns paginated responses. The rooms are ordered by the number
|
||||
of joined members, with the largest rooms first.
|
||||
|
|
@ -182,8 +182,8 @@ paths:
|
|||
- in: query
|
||||
name: server
|
||||
description: |-
|
||||
The server to fetch the public room lists from. Defaults to the
|
||||
local server. Case sensitive.
|
||||
The server to fetch the published room directory from. Defaults
|
||||
to the local server. Case sensitive.
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
|
|
@ -253,7 +253,7 @@ paths:
|
|||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: A list of the rooms on the server.
|
||||
description: A filtered list of the published rooms on the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ paths:
|
|||
deleted alongside the device.
|
||||
|
||||
This endpoint does not use the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) because
|
||||
User-Interactive Authentication is designed to protect against attacks where the
|
||||
User-Interactive Authentication is designed to protect against attacks where
|
||||
someone gets hold of a single access token then takes over the account. This
|
||||
endpoint invalidates all access tokens for the user, including the token used in
|
||||
the request, and therefore the attacker is unable to take over the account in
|
||||
|
|
|
|||
176
data/api/client-server/oauth_server_metadata.yaml
Normal file
176
data/api/client-server/oauth_server_metadata.yaml
Normal file
|
|
@ -0,0 +1,176 @@
|
|||
# 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.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server OAuth 2.0 Server Metadata Discovery API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/auth_metadata":
|
||||
get:
|
||||
summary: Get the OAuth 2.0 authorization server metadata.
|
||||
description: |-
|
||||
Gets the OAuth 2.0 authorization server metadata, as defined in
|
||||
[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the
|
||||
endpoint URLs and the supported parameters that can be used by the
|
||||
clients.
|
||||
|
||||
This endpoint definition includes only the fields that are meaningful in
|
||||
the context of the Matrix specification. The full list of possible
|
||||
fields is available in the [OAuth Authorization Server Metadata
|
||||
registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),
|
||||
and normative definitions of them are available in their respective
|
||||
RFCs.
|
||||
|
||||
{{% boxes/note %}}
|
||||
The authorization server metadata is relatively large and may change
|
||||
over time. Clients should:
|
||||
|
||||
- Cache the metadata appropriately based on HTTP caching headers
|
||||
- Refetch the metadata if it is stale
|
||||
{{% /boxes/note %}}
|
||||
operationId: getAuthMetadata
|
||||
responses:
|
||||
"200":
|
||||
description: The OAuth 2.0 authorization server metadata.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
issuer:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
The authorization server's issuer identifier, which is a URL that uses the
|
||||
`https` scheme and has no query or fragment components.
|
||||
|
||||
This is not used in the context of the Matrix specification, but is required
|
||||
by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
|
||||
authorization_endpoint:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the authorization endpoint, necessary to use the authorization code
|
||||
grant.
|
||||
token_endpoint:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the token endpoint, necessary to use the authorization code grant and
|
||||
the refresh token grant.
|
||||
revocation_endpoint:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the revocation endpoint, necessary to log out a client by invalidating
|
||||
its access and refresh tokens.
|
||||
registration_endpoint:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the client registration endpoint, necessary to perform dynamic
|
||||
registration of a client.
|
||||
response_types_supported:
|
||||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 response type strings that the server supports at the
|
||||
authorization endpoint.
|
||||
|
||||
This array MUST contain at least the `code` value, for clients to be able to
|
||||
use the authorization code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A response type that the server supports.
|
||||
grant_types_supported:
|
||||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 grant type strings that the server supports at the token
|
||||
endpoint.
|
||||
|
||||
This array MUST contain at least the `authorization_code` and `refresh_token`
|
||||
values, for clients to be able to use the authorization code grant and refresh
|
||||
token grant, respectively.
|
||||
items:
|
||||
type: string
|
||||
description: A grant type that the server supports.
|
||||
response_modes_supported:
|
||||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 response mode strings that the server supports at the
|
||||
authorization endpoint.
|
||||
|
||||
This array MUST contain at least the `query` and `fragment` values, for
|
||||
improved security in the authorization code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A response mode that the server supports.
|
||||
code_challenge_methods_supported:
|
||||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
|
||||
that the server supports at the authorization endpoint.
|
||||
|
||||
This array MUST contain at least the `S256` value, for improved security in
|
||||
the authorization code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A PKCE code challenge method that the server supports.
|
||||
prompt_values_supported:
|
||||
type: array
|
||||
description: |-
|
||||
List of OpenID Connect prompt values that the server supports at the
|
||||
authorization endpoint.
|
||||
|
||||
Only the `create` value defined in [Initiating User Registration via OpenID
|
||||
Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is
|
||||
supported, for a client to signal to the server that the user desires to
|
||||
register a new account.
|
||||
items:
|
||||
type: string
|
||||
description: A prompt value that the server supports.
|
||||
required:
|
||||
- issuer
|
||||
- authorization_endpoint
|
||||
- token_endpoint
|
||||
- revocation_endpoint
|
||||
- registration_endpoint
|
||||
- response_types_supported
|
||||
- grant_types_supported
|
||||
- response_modes_supported
|
||||
- code_challenge_methods_supported
|
||||
example: {
|
||||
"issuer": "https://account.example.com/",
|
||||
"authorization_endpoint": "https://account.example.com/oauth2/auth",
|
||||
"token_endpoint": "https://account.example.com/oauth2/token",
|
||||
"registration_endpoint": "https://account.example.com/oauth2/clients/register",
|
||||
"revocation_endpoint": "https://account.example.com/oauth2/revoke",
|
||||
"response_types_supported": ["code"],
|
||||
"grant_types_supported": ["authorization_code", "refresh_token"],
|
||||
"response_modes_supported": ["query", "fragment"],
|
||||
"code_challenge_methods_supported": ["S256"],
|
||||
}
|
||||
tags:
|
||||
- Session management
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- http
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/client/v1
|
||||
|
|
@ -214,7 +214,7 @@ paths:
|
|||
- public
|
||||
description: |-
|
||||
Whether this room is visible to the `/publicRooms` API
|
||||
or not."
|
||||
or not.
|
||||
account_data:
|
||||
type: array
|
||||
description: |-
|
||||
|
|
|
|||
242
data/api/client-server/password_management.yaml
Normal file
242
data/api/client-server/password_management.yaml
Normal file
|
|
@ -0,0 +1,242 @@
|
|||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2022 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.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Password Management API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/account/password:
|
||||
post:
|
||||
summary: Changes a user's password.
|
||||
description: |-
|
||||
Changes the password for an account on this homeserver.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
|
||||
ensure the user changing the password is actually the owner of the
|
||||
account.
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided. The homeserver SHOULD NOT revoke the
|
||||
access token provided in the request. Whether other access tokens for
|
||||
the user are revoked depends on the request parameters.
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
operationId: changePassword
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
new_password:
|
||||
type: string
|
||||
description: The new password for the account.
|
||||
example: ihatebananas
|
||||
logout_devices:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the user's other access tokens, and their associated devices, should be
|
||||
revoked if the request succeeds. Defaults to true.
|
||||
|
||||
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
|
||||
for the user's remaining devices.
|
||||
example: true
|
||||
auth:
|
||||
description: Additional authentication information for the user-interactive
|
||||
authentication API.
|
||||
allOf:
|
||||
- $ref: definitions/auth_data.yaml
|
||||
required:
|
||||
- new_password
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The password has been changed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"401":
|
||||
description: The homeserver requires additional authentication information.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/auth_response.yaml
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Account management
|
||||
/account/password/email/requestToken:
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given email address for the
|
||||
purpose of resetting a user's password
|
||||
description: |-
|
||||
The homeserver must check that the given email address **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
`/account/password` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
[`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
|
||||
endpoint, except that
|
||||
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
||||
given email address could be found. The server may instead send an
|
||||
email to the given address prompting the user to create an account.
|
||||
`M_THREEPID_IN_USE` may not be returned.
|
||||
|
||||
The homeserver should validate the email itself, either by sending a
|
||||
validation email itself or by using a service it has control over.
|
||||
operationId: requestTokenToResetPasswordEmail
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_email_validation.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: An email was sent to the given address.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_token_response.yaml
|
||||
"400":
|
||||
description: |-
|
||||
The referenced third-party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Email not found"
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
/account/password/msisdn/requestToken:
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given phone number for the
|
||||
purpose of resetting a user's password.
|
||||
description: |-
|
||||
The homeserver must check that the given phone number **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
`/account/password` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
[`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
|
||||
endpoint, except that
|
||||
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
||||
given phone number could be found. The server may instead send the SMS
|
||||
to the given phone number prompting the user to create an account.
|
||||
`M_THREEPID_IN_USE` may not be returned.
|
||||
|
||||
The homeserver should validate the phone number itself, either by sending a
|
||||
validation message itself or by using a service it has control over.
|
||||
operationId: requestTokenToResetPasswordMSISDN
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_msisdn_validation.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: An SMS message was sent to the given phone number.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_token_response.yaml
|
||||
"400":
|
||||
description: |-
|
||||
The referenced third-party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Phone number not found"
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- http
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/client/v3
|
||||
components:
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
$ref: definitions/security.yaml#/accessTokenQuery
|
||||
accessTokenBearer:
|
||||
$ref: definitions/security.yaml#/accessTokenBearer
|
||||
|
|
@ -373,315 +373,6 @@ paths:
|
|||
}
|
||||
tags:
|
||||
- Account management
|
||||
/account/password:
|
||||
post:
|
||||
summary: Changes a user's password.
|
||||
description: |-
|
||||
Changes the password for an account on this homeserver.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
|
||||
ensure the user changing the password is actually the owner of the
|
||||
account.
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided. The homeserver SHOULD NOT revoke the
|
||||
access token provided in the request. Whether other access tokens for
|
||||
the user are revoked depends on the request parameters.
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
operationId: changePassword
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
new_password:
|
||||
type: string
|
||||
description: The new password for the account.
|
||||
example: ihatebananas
|
||||
logout_devices:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the user's other access tokens, and their associated devices, should be
|
||||
revoked if the request succeeds. Defaults to true.
|
||||
|
||||
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
|
||||
for the user's remaining devices.
|
||||
example: true
|
||||
auth:
|
||||
description: Additional authentication information for the user-interactive
|
||||
authentication API.
|
||||
allOf:
|
||||
- $ref: definitions/auth_data.yaml
|
||||
required:
|
||||
- new_password
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The password has been changed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"401":
|
||||
description: The homeserver requires additional authentication information.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/auth_response.yaml
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Account management
|
||||
/account/password/email/requestToken:
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given email address for the
|
||||
purpose of resetting a user's password
|
||||
description: |-
|
||||
The homeserver must check that the given email address **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
`/account/password` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
[`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
|
||||
endpoint, except that
|
||||
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
||||
given email address could be found. The server may instead send an
|
||||
email to the given address prompting the user to create an account.
|
||||
`M_THREEPID_IN_USE` may not be returned.
|
||||
|
||||
The homeserver should validate the email itself, either by sending a
|
||||
validation email itself or by using a service it has control over.
|
||||
operationId: requestTokenToResetPasswordEmail
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_email_validation.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: An email was sent to the given address.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_token_response.yaml
|
||||
"400":
|
||||
description: |-
|
||||
The referenced third-party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Email not found"
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
/account/password/msisdn/requestToken:
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given phone number for the
|
||||
purpose of resetting a user's password.
|
||||
description: |-
|
||||
The homeserver must check that the given phone number **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
`/account/password` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
[`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
|
||||
endpoint, except that
|
||||
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
||||
given phone number could be found. The server may instead send the SMS
|
||||
to the given phone number prompting the user to create an account.
|
||||
`M_THREEPID_IN_USE` may not be returned.
|
||||
|
||||
The homeserver should validate the phone number itself, either by sending a
|
||||
validation message itself or by using a service it has control over.
|
||||
operationId: requestTokenToResetPasswordMSISDN
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_msisdn_validation.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: An SMS message was sent to the given phone number.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_token_response.yaml
|
||||
"400":
|
||||
description: |-
|
||||
The referenced third-party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Phone number not found"
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
/account/deactivate:
|
||||
post:
|
||||
summary: Deactivate a user's account.
|
||||
description: |-
|
||||
Deactivate the user's account, removing all ability for the user to
|
||||
login again.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
operationId: deactivateAccount
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
auth:
|
||||
description: Additional authentication information for the user-interactive
|
||||
authentication API.
|
||||
allOf:
|
||||
- $ref: definitions/auth_data.yaml
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind all of the user's 3PIDs from.
|
||||
If not provided, the homeserver MUST use the `id_server`
|
||||
that was originally use to bind each identifier. If the
|
||||
homeserver does not know which `id_server` that was,
|
||||
it must return an `id_server_unbind_result` of
|
||||
`no-support`.
|
||||
example: example.org
|
||||
erase:
|
||||
x-addedInMatrixVersion: "1.10"
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the user would like their content to be erased as
|
||||
much as possible from the server.
|
||||
|
||||
Erasure means that any users (or servers) which join the
|
||||
room after the erasure request are served redacted copies of
|
||||
the events sent by this account. Users which had visibility
|
||||
on those events prior to the erasure are still able to see
|
||||
unredacted copies. No redactions are sent and the erasure
|
||||
request is not shared over federation, so other servers
|
||||
might still serve unredacted copies.
|
||||
|
||||
The server should additionally erase any non-event data
|
||||
associated with the user, such as [account data](/client-server-api/#client-config)
|
||||
and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
|
||||
|
||||
Defaults to `false` if not present.
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The account has been deactivated.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
- success
|
||||
- no-support
|
||||
description: |-
|
||||
An indicator as to whether or not the homeserver was able to unbind
|
||||
the user's 3PIDs from the identity server(s). `success` indicates
|
||||
that all identifiers have been unbound from the identity server while
|
||||
`no-support` indicates that one or more identifiers failed to unbind
|
||||
due to the identity server refusing the request or the homeserver
|
||||
being unable to determine an identity server to unbind from. This
|
||||
must be `success` if the homeserver has no identifiers to unbind
|
||||
for the user.
|
||||
example: success
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
"401":
|
||||
description: The homeserver requires additional authentication information.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/auth_response.yaml
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Account management
|
||||
/register/available:
|
||||
get:
|
||||
summary: Checks to see if a username is available on the server.
|
||||
|
|
|
|||
|
|
@ -45,7 +45,9 @@ paths:
|
|||
properties:
|
||||
reason:
|
||||
type: string
|
||||
description: The reason the room is being reported.
|
||||
description: The reason the room is being reported. May be blank.
|
||||
required:
|
||||
- reason
|
||||
required: true
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -88,12 +90,11 @@ paths:
|
|||
Reports an event as inappropriate to the server, which may then notify
|
||||
the appropriate people. The caller must be joined to the room to report
|
||||
it.
|
||||
|
||||
It might be possible for clients to deduce whether an event exists by
|
||||
timing the response, as only a report for an event that does exist
|
||||
will require the homeserver to check whether a user is joined to
|
||||
the room. To combat this, homeserver implementations should add
|
||||
a random delay when generating a response.
|
||||
|
||||
Furthermore, it might be possible for clients to deduce whether a reported
|
||||
event exists by timing the response. This is because only a report for an
|
||||
existing event will require the homeserver to do further processing. To
|
||||
combat this, homeservers MAY add a random delay when generating a response.
|
||||
operationId: reportEvent
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -164,6 +165,88 @@ paths:
|
|||
}
|
||||
tags:
|
||||
- Reporting content
|
||||
"/users/{userId}/report":
|
||||
post:
|
||||
x-addedInMatrixVersion: "1.14"
|
||||
summary: Report a user as inappropriate.
|
||||
description: |-
|
||||
Reports a user as inappropriate to the server, which may then notify
|
||||
the appropriate people. How such information is delivered is left up to
|
||||
implementations. The caller is not required to be joined to any rooms
|
||||
that the reported user is joined to.
|
||||
|
||||
Clients may wish to [ignore](#ignoring-users) users after reporting them.
|
||||
|
||||
Clients could infer whether a reported user exists based on the 404 response.
|
||||
Homeservers that wish to conceal this information MAY return 200 responses
|
||||
regardless of the existence of the reported user.
|
||||
|
||||
Furthermore, it might be possible for clients to deduce whether a reported
|
||||
user exists by timing the response. This is because only a report for an
|
||||
existing user will require the homeserver to do further processing. To
|
||||
combat this, homeservers MAY add a random delay when generating a response.
|
||||
operationId: reportUser
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
description: The user being reported.
|
||||
required: true
|
||||
example: "@someguy:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"reason": "this makes me sad"
|
||||
}
|
||||
properties:
|
||||
reason:
|
||||
type: string
|
||||
description: The reason the room is being reported. May be blank.
|
||||
required:
|
||||
- reason
|
||||
required: true
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
responses:
|
||||
"200":
|
||||
description: |
|
||||
The user has been reported successfully or the server chose
|
||||
to not disclose whether the users exists.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"404":
|
||||
description: |-
|
||||
The user was not found on the homeserver.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "The user was not found."
|
||||
}
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Reporting content
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ paths:
|
|||
- public
|
||||
description: |-
|
||||
Whether this room is visible to the `/publicRooms` API
|
||||
or not."
|
||||
or not.
|
||||
account_data:
|
||||
type: array
|
||||
description: The private data that this user has attached to this room.
|
||||
|
|
|
|||
138
data/api/client-server/room_summary.yaml
Normal file
138
data/api/client-server/room_summary.yaml
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
# 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.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Room Summary API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/room_summary/{roomIdOrAlias}":
|
||||
get:
|
||||
x-addedInMatrixVersion: "1.15"
|
||||
summary: Retrieves a summary for a room.
|
||||
description: |-
|
||||
Retrieves a summary for a room.
|
||||
|
||||
Clients should note that requests for rooms where the user's membership
|
||||
is `invite` or `knock` might yield outdated, partial or even no data
|
||||
since the server may not have access to the current state of the room.
|
||||
|
||||
Servers MAY allow unauthenticated access to this API if at least one of
|
||||
the following conditions holds true:
|
||||
|
||||
- The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
|
||||
`knock_restricted`.
|
||||
- The room has a `world_readable` [history visibility](#room-history-visibility).
|
||||
|
||||
Servers should consider rate limiting requests that require a federation
|
||||
request more heavily if the client is unauthenticated.
|
||||
operationId: getRoomSummary
|
||||
security:
|
||||
- signedRequest: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: roomIdOrAlias
|
||||
description: The room identifier or alias to summarise.
|
||||
required: true
|
||||
example: "#monkeys:matrix.org"
|
||||
schema:
|
||||
oneOf:
|
||||
- type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- type: string
|
||||
format: mx-room-alias
|
||||
pattern: "^#"
|
||||
- in: query
|
||||
name: via
|
||||
description: |-
|
||||
The servers to attempt to request the summary from when
|
||||
the local server cannot generate it (for instance, because
|
||||
it has no local user in the room).
|
||||
example:
|
||||
- matrix.org
|
||||
- elsewhere.ca
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
format: mx-server-name
|
||||
responses:
|
||||
"200":
|
||||
description: A summary of the room.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
description: A summary of the room.
|
||||
allOf:
|
||||
- $ref: ../client-server/definitions/room_summary.yaml
|
||||
- type: object
|
||||
properties:
|
||||
membership:
|
||||
description: |-
|
||||
The membership state of the user if the user is joined to the room. Absent
|
||||
if the API was called unauthenticated.
|
||||
enum:
|
||||
- invite
|
||||
- join
|
||||
- knock
|
||||
- leave
|
||||
- ban
|
||||
type: string
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
room_id: "!ol19s:bleecker.street",
|
||||
avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
|
||||
guest_can_join: false,
|
||||
name: "CHEESE",
|
||||
num_joined_members: 37,
|
||||
topic: "Tasty tasty cheese",
|
||||
world_readable: true,
|
||||
join_rule: "public",
|
||||
room_type: "m.space",
|
||||
membership: "invite",
|
||||
encryption: "m.megolm.v1.aes-sha2",
|
||||
room_version: "9001",
|
||||
}
|
||||
"404":
|
||||
description: |-
|
||||
The room could not be found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Room not found."
|
||||
}
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- http
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/client/v1
|
||||
components:
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
$ref: definitions/security.yaml#/accessTokenQuery
|
||||
accessTokenBearer:
|
||||
$ref: definitions/security.yaml#/accessTokenBearer
|
||||
|
|
@ -105,13 +105,31 @@ paths:
|
|||
example: ""
|
||||
schema:
|
||||
type: string
|
||||
- in: query
|
||||
name: format
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
description: |-
|
||||
The format to use for the returned data. `content` (the default) will
|
||||
return only the content of the state event. `event` will return the entire
|
||||
event in the usual format suitable for clients, including fields like event
|
||||
ID, sender and timestamp.
|
||||
example: event
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- content
|
||||
- event
|
||||
responses:
|
||||
"200":
|
||||
description: The content of the state event.
|
||||
description: |-
|
||||
The content of the state event, or the entire client-formatted event
|
||||
if `?format=event` was used.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
oneOf:
|
||||
- type: object
|
||||
- $ref: "../../event-schemas/schema/core-event-schema/state_event.yaml"
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
|
|
|
|||
|
|
@ -88,18 +88,24 @@ paths:
|
|||
properties:
|
||||
rooms:
|
||||
type: array
|
||||
description: The rooms for the current page, with the current filters.
|
||||
description: |-
|
||||
The rooms for the current page, with the current filters.
|
||||
|
||||
The server should return any rooms where at least one of the following conditions is true:
|
||||
|
||||
* The requesting user is currently a member (their [room membership](#room-membership) is `join`).
|
||||
* The requesting user already has permission to join, i.e. one of the following:
|
||||
* The user's room membership is `invite`.
|
||||
* The room's [join rules](#mroomjoin_rules) are set to `public`.
|
||||
* The room's join rules are set to [`restricted`](#restricted-rooms), provided the user meets one of the specified conditions.
|
||||
* The room is "knockable" (the room's join rules are set to `knock`, or `knock_restricted`, in a room version that supports those settings).
|
||||
* The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: definitions/public_rooms_chunk.yaml
|
||||
- $ref: definitions/room_summary.yaml
|
||||
- type: object
|
||||
title: SpaceHierarchyRoomsChunk
|
||||
properties:
|
||||
room_type:
|
||||
type: string
|
||||
description: The `type` of room (from
|
||||
[`m.room.create`](/client-server-api/#mroomcreate)),
|
||||
if any.
|
||||
children_state:
|
||||
type: array
|
||||
description: |-
|
||||
|
|
@ -119,6 +125,14 @@ paths:
|
|||
description: The `origin_server_ts` for the event.
|
||||
required:
|
||||
- origin_server_ts
|
||||
room_type:
|
||||
x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
|
||||
allowed_room_ids:
|
||||
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
|
||||
encryption:
|
||||
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
|
||||
room_version:
|
||||
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
|
||||
required:
|
||||
- children_state
|
||||
next_batch:
|
||||
|
|
|
|||
|
|
@ -22,9 +22,12 @@ paths:
|
|||
description: |-
|
||||
Gets server admin contact and support page of the domain.
|
||||
|
||||
Like the [well-known discovery URI](/client-server-api/#well-known-uri),
|
||||
this should be accessed with the hostname of the homeserver by making a
|
||||
{{% boxes/note %}}
|
||||
Like the [well-known discovery URI](/client-server-api/#well-known-uris),
|
||||
this endpoint should be accessed with the hostname of the homeserver's
|
||||
[server name](/appendices/#server-name) by making a
|
||||
GET request to `https://hostname/.well-known/matrix/support`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Note that this endpoint is not necessarily handled by the homeserver.
|
||||
It may be served by another webserver, used for discovering support
|
||||
|
|
|
|||
|
|
@ -441,17 +441,57 @@ paths:
|
|||
"state": {
|
||||
"events": [
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.member.yaml"
|
||||
"content": {
|
||||
"avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
|
||||
"displayname": "Example user",
|
||||
"membership": "join"
|
||||
},
|
||||
"event_id": "$143273976499sgjks:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@example:example.org",
|
||||
"state_key": "@example:example.org",
|
||||
"type": "m.room.member",
|
||||
"unsigned": {
|
||||
"age": 45603,
|
||||
"membership": "join"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"timeline": {
|
||||
"events": [
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.member.yaml"
|
||||
"content": {
|
||||
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
|
||||
"displayname": "Alice Margatroid",
|
||||
"membership": "join",
|
||||
"reason": "Looking for support"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@alice:example.org",
|
||||
"state_key": "@alice:example.org",
|
||||
"type": "m.room.member",
|
||||
"unsigned": {
|
||||
"age": 1234,
|
||||
"membership": "join"
|
||||
}
|
||||
},
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
|
||||
"content": {
|
||||
"body": "This is an example text message",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "<b>This is an example text message</b>",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@example:example.org",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {
|
||||
"age": 1234,
|
||||
"membership": "join"
|
||||
}
|
||||
}
|
||||
],
|
||||
"limited": true,
|
||||
|
|
|
|||
|
|
@ -57,9 +57,6 @@ paths:
|
|||
- A signature of the token, signed with the identity server's private key
|
||||
|
||||
- The matrix user ID who invited them to the room
|
||||
|
||||
If a token is requested from the identity server, the homeserver will
|
||||
append a `m.room.third_party_invite` event to the room.
|
||||
operationId: inviteBy3PID
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -72,41 +69,13 @@ paths:
|
|||
example: "!d41d8cd:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"id_server": "matrix.org",
|
||||
"id_access_token": "abc123_OpaqueString",
|
||||
"medium": "email",
|
||||
"address": "cheeky@monkey.com"
|
||||
}
|
||||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: The hostname+port of the identity server which should be used for
|
||||
third-party identifier lookups.
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token previously registered with the identity server. Servers
|
||||
can treat this as optional to distinguish between r0.5-compatible clients
|
||||
and this specification version.
|
||||
medium:
|
||||
type: string
|
||||
description: |-
|
||||
The kind of address being passed in the address field, for example
|
||||
`email` (see [the list of recognised values](/appendices/#3pid-types)).
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third-party identifier.
|
||||
required:
|
||||
- id_server
|
||||
- id_access_token
|
||||
- medium
|
||||
- address
|
||||
$ref: definitions/invite_3pid.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
|
|
@ -120,7 +89,9 @@ paths:
|
|||
value: {}
|
||||
"403":
|
||||
description: |-
|
||||
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
|
||||
You do not have permission to invite the user to the room. A
|
||||
meaningful `errcode` and description error text will be returned.
|
||||
Example reasons for rejections are:
|
||||
|
||||
- The invitee has been banned from the room.
|
||||
- The invitee is already a member of the room.
|
||||
|
|
|
|||
|
|
@ -20,10 +20,17 @@ paths:
|
|||
post:
|
||||
summary: Searches the user directory.
|
||||
description: |-
|
||||
Performs a search for users. The homeserver may
|
||||
determine which subset of users are searched, however the homeserver
|
||||
MUST at a minimum consider the users the requesting user shares a
|
||||
room with and those who reside in public rooms (known to the homeserver).
|
||||
Performs a search for users. The homeserver may determine which
|
||||
subset of users are searched. However, the homeserver MUST at a
|
||||
minimum consider users who are visible to the requester based
|
||||
on their membership in rooms known to the homeserver. This means:
|
||||
|
||||
- users that share a room with the requesting user
|
||||
- users who are joined to rooms known to the homeserver that have a
|
||||
`public` [join rule](#mroomjoin_rules)
|
||||
- users who are joined to rooms known to the homeserver that have a
|
||||
`world_readable` [history visibility](#room-history-visibility)
|
||||
|
||||
The search MUST consider local users to the homeserver, and SHOULD
|
||||
query remote users as part of the search.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,6 +26,12 @@ paths:
|
|||
suitably namespaced for each application and reduces the risk of
|
||||
clashes.
|
||||
|
||||
{{% boxes/note %}}
|
||||
This endpoint should be accessed with the hostname of the homeserver's
|
||||
[server name](/appendices/#server-name) by making a
|
||||
GET request to `https://hostname/.well-known/matrix/client`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Note that this endpoint is not necessarily handled by the homeserver,
|
||||
but by another webserver, to be used for discovering the homeserver URL.
|
||||
operationId: getWellknown
|
||||
|
|
|
|||
|
|
@ -43,7 +43,8 @@ paths:
|
|||
properties:
|
||||
public_key:
|
||||
type: string
|
||||
description: Unpadded Base64 encoded public key.
|
||||
description: |-
|
||||
[Unpadded Base64](/appendices/#unpadded-base64)-encoded public key.
|
||||
required:
|
||||
- public_key
|
||||
examples:
|
||||
|
|
@ -74,7 +75,8 @@ paths:
|
|||
- in: query
|
||||
name: public_key
|
||||
required: true
|
||||
description: The unpadded base64-encoded public key to check.
|
||||
description: |-
|
||||
The [unpadded Base64](/appendices/#unpadded-base64)-encoded public key to check.
|
||||
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -105,7 +107,14 @@ paths:
|
|||
- in: query
|
||||
name: public_key
|
||||
required: true
|
||||
description: The unpadded base64-encoded public key to check.
|
||||
description: |-
|
||||
The [unpadded Base64](/appendices/#unpadded-base64)-encoded public
|
||||
key to check.
|
||||
|
||||
This MUST be the exact same encoded string returned in the response
|
||||
of the [`/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
|
||||
endpoint, or found in the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
|
||||
event, so it may use the standard or URL-safe alphabets.
|
||||
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
|
||||
schema:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
(if present) from the request here.
|
||||
|
||||
Also, the generated ephemeral public key will be listed as valid on
|
||||
requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`.
|
||||
requests to [`/_matrix/identity/v2/pubkey/ephemeral/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid).
|
||||
|
||||
Currently, invites may only be issued for 3pids of the `email` medium.
|
||||
|
||||
|
|
@ -70,10 +70,14 @@ paths:
|
|||
room_id:
|
||||
type: string
|
||||
description: The Matrix room ID to which the user is invited
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
example: "!something:example.org"
|
||||
sender:
|
||||
type: string
|
||||
description: The Matrix user ID of the inviting user
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@bob:example.com"
|
||||
room_alias:
|
||||
type: string
|
||||
|
|
@ -81,12 +85,16 @@ paths:
|
|||
The Matrix room alias for the room to which the user is
|
||||
invited. This should be retrieved from the `m.room.canonical_alias`
|
||||
state event.
|
||||
format: mx-room-alias
|
||||
pattern: "^#"
|
||||
example: "#somewhere:example.org"
|
||||
room_avatar_url:
|
||||
type: string
|
||||
description: |-
|
||||
The Content URI for the room to which the user is invited. This should
|
||||
be retrieved from the `m.room.avatar` state event.
|
||||
format: mx-mxc-uri
|
||||
pattern: "^mxc:\\/\\/"
|
||||
example: mxc://example.org/s0meM3dia
|
||||
room_join_rules:
|
||||
type: string
|
||||
|
|
@ -108,6 +116,8 @@ paths:
|
|||
type: string
|
||||
description: The Content URI for the avatar of the user ID initiating the
|
||||
invite.
|
||||
format: mx-mxc-uri
|
||||
pattern: "^mxc:\\/\\/"
|
||||
example: mxc://example.org/an0th3rM3dia
|
||||
room_type:
|
||||
type: string
|
||||
|
|
@ -146,7 +156,7 @@ paths:
|
|||
public_key:
|
||||
type: string
|
||||
description: |
|
||||
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
|
||||
The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
|
||||
key_validity_url:
|
||||
type: string
|
||||
description: |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
# 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.
|
||||
type: object
|
||||
description: |-
|
||||
The auth_events and prev_events fields of PDUs for room version 4
|
||||
and beyond.
|
||||
properties:
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
|
|
@ -12,10 +12,7 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
type: object
|
||||
title: Unsigned Persistent Data Unit
|
||||
description: An unsigned persistent data unit (event)
|
||||
example:
|
||||
$ref: "../examples/unsigned_pdu_base.json"
|
||||
description: Common fields for all PDU versions
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
|
|
@ -44,49 +41,22 @@ properties:
|
|||
type: object
|
||||
description: The content of the event.
|
||||
example: {"key": "value"}
|
||||
prev_events:
|
||||
type: array
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
description: |-
|
||||
Event IDs and reference hashes for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "event_hash.yaml"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "event_hash.yaml"
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
unsigned:
|
||||
type: object
|
||||
title: UnsignedData
|
||||
|
|
@ -99,12 +69,11 @@ properties:
|
|||
description: The number of milliseconds that have passed since this message was sent.
|
||||
example: 4612
|
||||
required:
|
||||
- event_id
|
||||
- room_id
|
||||
- sender
|
||||
- origin_server_ts
|
||||
- type
|
||||
- content
|
||||
- prev_events
|
||||
- depth
|
||||
- auth_events
|
||||
- hashes
|
||||
- signatures
|
||||
77
data/api/server-server/definitions/pdu_v1.yaml
Normal file
77
data/api/server-server/definitions/pdu_v1.yaml
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# 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.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room versions 1 and 2.
|
||||
example:
|
||||
$ref: "../examples/pdu_v1.json"
|
||||
allOf:
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
description: The event ID for the PDU.
|
||||
example: "$a4ecee13e2accdadf56c1025:example.com"
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def456:matrix.org"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "components/event_hash.yaml"
|
||||
prev_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "components/event_hash.yaml"
|
||||
required:
|
||||
- event_id
|
||||
- auth_events
|
||||
- prev_events
|
||||
|
|
@ -17,53 +17,16 @@ description: A persistent data unit (event) for room version 11 and beyond.
|
|||
example:
|
||||
$ref: "../examples/pdu_v11.json"
|
||||
allOf:
|
||||
# v11 is the v4 event, but without redacts. Copy the auth_events/prev_events
|
||||
# from pdu_v4.yaml and hashes and signatures from pdu_v3.yaml.
|
||||
- $ref: "unsigned_pdu_base.yaml"
|
||||
# v11 is the v6 event, but without redacts.
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
description: |-
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
- hashes
|
||||
- signatures
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^53 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
@ -13,17 +13,24 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room version 3 and beyond.
|
||||
description: A persistent data unit (event) for room version 3.
|
||||
example:
|
||||
$ref: "../examples/pdu_v3.json"
|
||||
allOf:
|
||||
- $ref: "unsigned_pdu_base.yaml"
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def/456+oldevent"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
|
|
@ -48,24 +55,6 @@ allOf:
|
|||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$base64EncodedHash", "$AnotherEvent"]
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
description: |-
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
- hashes
|
||||
- signatures
|
||||
|
|
|
|||
|
|
@ -13,41 +13,23 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room version 4 and beyond.
|
||||
description: |-
|
||||
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
|
||||
example:
|
||||
$ref: "../examples/pdu_v4.json"
|
||||
allOf:
|
||||
- $ref: "pdu_v3.yaml"
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def_456-oldevent"
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Copyright 2018 New Vector Ltd
|
||||
# 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.
|
||||
|
|
@ -13,33 +13,24 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room versions 1 and 2.
|
||||
description: |-
|
||||
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
|
||||
example:
|
||||
$ref: "../examples/pdu.json"
|
||||
$ref: "../examples/pdu_v4.json"
|
||||
allOf:
|
||||
- $ref: "unsigned_pdu.yaml"
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def456:matrix.org"
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
example: "$def_456-oldevent"
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
required:
|
||||
- hashes
|
||||
- signatures
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^53 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
# Copyright 2018-2019 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.
|
||||
type: object
|
||||
title: Unsigned Persistent Data Unit
|
||||
description: An unsigned persistent data unit (event)
|
||||
example:
|
||||
$ref: "../examples/unsigned_pdu.json"
|
||||
allOf:
|
||||
- $ref: "unsigned_pdu_base.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
description: The event ID for the PDU.
|
||||
example: "$a4ecee13e2accdadf56c1025:example.com"
|
||||
required:
|
||||
- event_id
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue