mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-20 04:53:42 +01:00
Merge branch 'main' into johannes/public-rooms-room-directory
This commit is contained in:
Johannes Marbach
commit
9a0b5ecb11
16
.github/workflows/main.yml
vendored
16
.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"
|
||||
|
|
@ -172,7 +173,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 +284,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 @@
|
|||
Correct null value handling for the AS Registration's `url` property.
|
||||
|
|
@ -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).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify which rooms are returned from `/hierarchy`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clients can choose which history visibility options they offer to users when creating rooms.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
Clarify the format of third-party invites, including the fact that identity
|
||||
server public keys can be encoded using standard or URL-safe base64.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
1
changelogs/client_server/newsfragments/2095.feature
Normal file
1
changelogs/client_server/newsfragments/2095.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
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).
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms in profile look-ups are defined through their join rule and history visibility.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms in user directory queries are defined through their join rule and history visibility.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms with respect to call invites are defined through their join rule.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms have no specific meaning with respect to moderation policy lists.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms with respect to presence are defined through their join rule.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that public keys can be encoded using standard or URL-safe base64.
|
||||
|
|
@ -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 +0,0 @@
|
|||
Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Deduplicate the definition of `RoomKeysUpdateResponse`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Deduplicate the definitions of `Invite3pid`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Support more locations for examples in OpenAPI definitions and JSON schemas.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add link to the git commit for the unstable changelog.
|
||||
1
changelogs/internal/newsfragments/2081.clarification
Normal file
1
changelogs/internal/newsfragments/2081.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Adjust margins in rendered endpoints.
|
||||
1
changelogs/internal/newsfragments/2088.clarification
Normal file
1
changelogs/internal/newsfragments/2088.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Replace Hugo shortcodes in OpenAPI output.
|
||||
1
changelogs/internal/newsfragments/2115.clarification
Normal file
1
changelogs/internal/newsfragments/2115.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.
|
||||
1
changelogs/internal/newsfragments/2123.clarification
Normal file
1
changelogs/internal/newsfragments/2123.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Fix the historical info box when generating the historical spec in CI.
|
||||
|
|
@ -1 +0,0 @@
|
|||
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.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Refactor PDU definitions to reduce duplication.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
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.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove an erroneous `room_id` field in a few examples.
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
Clarify the format of third-party invites, including the fact that identity
|
||||
server public keys can be encoded using standard or URL-safe base64.
|
||||
1
changelogs/server_server/newsfragments/2095.feature
Normal file
1
changelogs/server_server/newsfragments/2095.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
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).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.
|
||||
|
|
@ -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 = "14"
|
||||
|
||||
# User interface configuration
|
||||
[params.ui]
|
||||
|
|
|
|||
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))
|
||||
|
|
@ -371,15 +371,23 @@ valid data was obtained, but no server is available to serve the client.
|
|||
No further guess should be attempted and the user should make a
|
||||
conscientious decision what to do next.
|
||||
|
||||
### Well-known URI
|
||||
### Well-known URIs
|
||||
|
||||
Matrix facilitates automatic discovery for the Client-Server API base URL and more via the
|
||||
[RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) "Well-Known URI" method.
|
||||
This method uses JSON files at a predetermined location on the root path `/.well-known/` to
|
||||
specify parameter values.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Diverging from the rest of the endpoints in the Client-Server spec, these files can not be provided
|
||||
on the base URL that the Client-Server API is reachable on, as it is yet to be discovered.
|
||||
Instead, they can be reached via HTTPS on the [server name](/appendices/#server-name)'s hostname as domain.
|
||||
|
||||
Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
|
||||
as per the [CORS](#web-browser-clients) section in this specification.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
The `.well-known` method uses a JSON file at a predetermined location to
|
||||
specify parameter values. The flow for this method is as follows:
|
||||
The flow for auto-discovery is as follows:
|
||||
|
||||
1. Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the
|
||||
Matrix ID at the first colon.
|
||||
|
|
@ -415,10 +423,17 @@ specify parameter values. The flow for this method is as follows:
|
|||
|
||||
{{% http-api spec="client-server" api="wellknown" %}}
|
||||
|
||||
{{% http-api spec="client-server" api="versions" %}}
|
||||
|
||||
{{% http-api spec="client-server" api="support" %}}
|
||||
|
||||
### API Versions
|
||||
|
||||
Upon connecting, the Matrix client and server need to negotiate which version of the specification
|
||||
they commonly support, as the API evolves over time. The server advertises its supported versions
|
||||
and optionally unstable features to the client, which can then go on to make requests to the
|
||||
endpoints it supports.
|
||||
|
||||
{{% http-api spec="client-server" api="versions" %}}
|
||||
|
||||
## Client Authentication
|
||||
|
||||
Most API endpoints require the user to identify themselves by presenting
|
||||
|
|
@ -2875,10 +2890,15 @@ that are not `world_readable` regardless of their visibility.
|
|||
|
||||
#### Server behaviour
|
||||
|
||||
Homeservers MUST at a minimum allow profile look-up for:
|
||||
Homeservers MUST at a minimum allow profile look-up for 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 that reside in public rooms known to the homeserver
|
||||
- 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)
|
||||
|
||||
In all other cases, homeservers MAY deny profile look-up by responding with
|
||||
403 and an error code of `M_FORBIDDEN`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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" %}}
|
||||
|
|
@ -281,7 +281,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### State resolution
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -229,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" %}}
|
||||
|
|
|
|||
|
|
@ -225,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
|
||||
|
|
@ -543,8 +544,8 @@ the following subset of the room state:
|
|||
`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" %}}
|
||||
|
||||
|
|
@ -1336,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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -105,15 +105,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: |-
|
||||
|
|
|
|||
|
|
@ -33,7 +33,9 @@ properties:
|
|||
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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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,6 +69,8 @@ paths:
|
|||
example: "!d41d8cd:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -90,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: |
|
||||
|
|
|
|||
|
|
@ -41,13 +41,6 @@ properties:
|
|||
type: object
|
||||
description: The content of the event.
|
||||
example: {"key": "value"}
|
||||
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
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
|
|
|
|||
|
|
@ -28,6 +28,13 @@ allOf:
|
|||
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: |-
|
||||
|
|
|
|||
|
|
@ -17,6 +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.
|
||||
# v11 is the v6 event, but without redacts.
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
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
|
||||
|
|
@ -24,6 +24,13 @@ allOf:
|
|||
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:
|
||||
|
|
|
|||
|
|
@ -26,3 +26,10 @@ allOf:
|
|||
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
|
||||
|
|
|
|||
36
data/api/server-server/definitions/pdu_v6.yaml
Normal file
36
data/api/server-server/definitions/pdu_v6.yaml
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# 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: Persistent Data Unit
|
||||
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: "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"
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
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
|
||||
|
|
@ -20,7 +20,7 @@ paths:
|
|||
put:
|
||||
summary: Invites a remote user to a room
|
||||
description: |-
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
homeserver and the invited homeserver, it can be sent to all of the servers in the
|
||||
room by the inviting homeserver.
|
||||
|
||||
|
|
@ -32,6 +32,10 @@ paths:
|
|||
[room version specification](/rooms) for precise event formats. **The request and response
|
||||
bodies here describe the common event fields in more detail and may be missing other
|
||||
required fields for a PDU.**
|
||||
|
||||
Also note that if the remote homeserver is already in the room, it will receive the
|
||||
invite event twice; once through this endpoint, and again through a [federation
|
||||
transaction](/server-server-api/#transactions).
|
||||
operationId: sendInviteV1
|
||||
security:
|
||||
- signedRequest: []
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ paths:
|
|||
This API is nearly identical to the v1 API with the exception of the request
|
||||
body being different, and the response format fixed.
|
||||
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
homeserver and the invited homeserver, it can be sent to all of the servers in the
|
||||
room by the inviting homeserver.
|
||||
|
||||
|
|
@ -36,6 +36,10 @@ paths:
|
|||
[room version specification](/rooms) for precise event formats. **The request and response
|
||||
bodies here describe the common event fields in more detail and may be missing other
|
||||
required fields for a PDU.**
|
||||
|
||||
Also note that if the remote homeserver is already in the room, it will receive the
|
||||
invite event twice; once through this endpoint, and again through a [federation
|
||||
transaction](/server-server-api/#transactions).
|
||||
operationId: sendInviteV2
|
||||
security:
|
||||
- signedRequest: []
|
||||
|
|
|
|||
|
|
@ -35,6 +35,8 @@ paths:
|
|||
example: "!abc123:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -50,16 +52,22 @@ paths:
|
|||
description: |-
|
||||
The room ID the event is for. Must match the ID given in
|
||||
the path.
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
example: "!abc123:matrix.org"
|
||||
sender:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID of the user who sent the original `m.room.third_party_invite`
|
||||
event.
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@joe:matrix.org"
|
||||
state_key:
|
||||
type: string
|
||||
description: The user ID of the invited user
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@someone:example.org"
|
||||
content:
|
||||
type: object
|
||||
|
|
@ -82,45 +90,7 @@ paths:
|
|||
third-party identifier.
|
||||
example: alice
|
||||
signed:
|
||||
type: object
|
||||
description: |-
|
||||
A block of content which has been signed, which servers can use to
|
||||
verify the event.
|
||||
title: Invite Signatures
|
||||
properties:
|
||||
signatures:
|
||||
type: object
|
||||
title: Signatures
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |-
|
||||
The server signatures for this event.
|
||||
|
||||
The signature is calculated using the process
|
||||
described at [Signing JSON](/appendices/#signing-json).
|
||||
example:
|
||||
magic.forest:
|
||||
ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
|
||||
mxid:
|
||||
type: string
|
||||
description: The invited matrix user ID
|
||||
example: "@alice:localhost"
|
||||
token:
|
||||
type: string
|
||||
description: The token used to verify the event
|
||||
example: abc123
|
||||
required:
|
||||
- signatures
|
||||
- mxid
|
||||
- token
|
||||
example:
|
||||
mxid: "@alice:localhost"
|
||||
token: abc123
|
||||
signatures:
|
||||
magic.forest:
|
||||
ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
|
||||
$ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
|
||||
required:
|
||||
- display_name
|
||||
- signed
|
||||
|
|
@ -215,6 +185,8 @@ paths:
|
|||
mxid:
|
||||
type: string
|
||||
description: The user that is now bound to the third-party identifier.
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@alice:matrix.org"
|
||||
invites:
|
||||
type: array
|
||||
|
|
@ -237,59 +209,23 @@ paths:
|
|||
mxid:
|
||||
type: string
|
||||
description: The now-bound user ID that received the invite.
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@alice:matrix.org"
|
||||
room_id:
|
||||
type: string
|
||||
description: The room ID the invite is valid for.
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
example: "!somewhere:example.org"
|
||||
sender:
|
||||
type: string
|
||||
description: The user ID that sent the invite.
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@bob:matrix.org"
|
||||
# TODO (TravisR): Make this reusable when doing IS spec changes
|
||||
# also make sure it isn't lying about anything, like the key version
|
||||
signed:
|
||||
type: object
|
||||
title: Identity Server Signatures
|
||||
description: |-
|
||||
Signature from the identity server using a long-term private
|
||||
key.
|
||||
properties:
|
||||
mxid:
|
||||
type: string
|
||||
description: |-
|
||||
The user ID that has been bound to the third-party
|
||||
identifier.
|
||||
example: "@alice:matrix.org"
|
||||
token:
|
||||
type: string
|
||||
# TODO: What is this actually?
|
||||
description: A token.
|
||||
example: Hello World
|
||||
signatures:
|
||||
type: object
|
||||
title: Identity Server Signature
|
||||
description: |-
|
||||
The signature from the identity server. The `string` key
|
||||
is the identity server's domain name, such as vector.im
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Identity Server Domain Signature
|
||||
description: The signature for the identity server.
|
||||
properties:
|
||||
ed25519:0:
|
||||
type: string
|
||||
description: The signature.
|
||||
example: SomeSignatureGoesHere
|
||||
required:
|
||||
- ed25519:0
|
||||
example:
|
||||
vector.im:
|
||||
ed25519:0: SomeSignatureGoesHere
|
||||
required:
|
||||
- mxid
|
||||
- token
|
||||
- signatures
|
||||
$ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
|
||||
required:
|
||||
- medium
|
||||
- address
|
||||
|
|
|
|||
|
|
@ -24,6 +24,12 @@ paths:
|
|||
Gets information about the delegated server for server-server communication
|
||||
between Matrix homeservers. Servers should follow 30x redirects, carefully
|
||||
avoiding redirect loops, and use normal X.509 certificate validation.
|
||||
|
||||
{{% 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/server`.
|
||||
{{% /boxes/note %}}
|
||||
operationId: getWellKnown
|
||||
responses:
|
||||
"200":
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
{
|
||||
"$ref": "core/state_event.json",
|
||||
"state_key": "@alice:example.org",
|
||||
"sender": "@alice:example.org",
|
||||
"type": "m.room.member",
|
||||
"content": {
|
||||
"membership": "join",
|
||||
|
|
|
|||
|
|
@ -3,6 +3,14 @@
|
|||
"type": "m.room.topic",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"topic": "A room topic"
|
||||
"m.topic": {
|
||||
"m.text": [ {
|
||||
"mimetype": "text/html",
|
||||
"body": "An <em>interesting</em> room topic"
|
||||
}, {
|
||||
"body": "An interesting room topic"
|
||||
}]
|
||||
},
|
||||
"topic": "An interesting room topic"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,28 @@
|
|||
type: array
|
||||
description: |-
|
||||
An ordered array of textual representations in different mimetypes.
|
||||
|
||||
Senders SHOULD specify at least one representation and SHOULD always
|
||||
include a plaintext representation.
|
||||
|
||||
Receivers SHOULD use the first representation in the array that
|
||||
they understand.
|
||||
title: TextContentBlock
|
||||
items:
|
||||
type: object
|
||||
title: TextualRepresentation
|
||||
properties:
|
||||
mimetype:
|
||||
type: string
|
||||
description: The mimetype. Defaults to `text/plain` if omitted.
|
||||
example: "text/html"
|
||||
body:
|
||||
type: string
|
||||
description: |-
|
||||
The string content.
|
||||
|
||||
Clients SHOULD validate and sanitize the content as they do
|
||||
for rich content associated with [`msgtype`](/client-server-api/#mroommessage-msgtypes)
|
||||
of [`m.room.message`](/client-server-api/#mroommessage).
|
||||
required:
|
||||
- body
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
title: SignedThirdPartyInvite
|
||||
description: |-
|
||||
A block of content which has been signed by the identity server, which
|
||||
homeservers can use to verify the event. Clients should ignore this.
|
||||
type: object
|
||||
properties:
|
||||
mxid:
|
||||
description: |-
|
||||
The user ID that has been bound to the third-party identifier.
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@alice:example.org"
|
||||
signatures:
|
||||
title: IdentityServerSignatures
|
||||
description: |-
|
||||
The identity server signatures for this block. This is a map of identity
|
||||
server name to signing key identifier to base64-encoded signature.
|
||||
|
||||
The signatures are calculated using the process described at
|
||||
[Signing JSON](/appendices/#signing-json).
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
example: {
|
||||
"magic.forest": {
|
||||
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
|
||||
}
|
||||
}
|
||||
token:
|
||||
description: |-
|
||||
The token generated by the identity server at the
|
||||
[`/store_invite`](/identity-service-api/#post_matrixidentityv2store-invite)
|
||||
endpoint.
|
||||
|
||||
It matches the `state_key` of the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
|
||||
event.
|
||||
type: string
|
||||
example: "abc123"
|
||||
required:
|
||||
- mxid
|
||||
- signatures
|
||||
- token
|
||||
|
|
@ -2,17 +2,27 @@
|
|||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
description: |-
|
||||
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
|
||||
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs
|
||||
(`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the
|
||||
state directly as there are a restricted set of valid transformations. For example, user A cannot
|
||||
force user B to join a room, and trying to force this state change directly will fail.
|
||||
|
||||
The following membership states are specified:
|
||||
|
||||
- `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
|
||||
- `join` - The user has joined the room (possibly after accepting an invite), and may participate in it.
|
||||
- `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
|
||||
- `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`).
|
||||
- `knock` - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join.
|
||||
- `invite` - The user has been invited to join a room, but has not yet joined it. They may not
|
||||
participate in the room until they join.
|
||||
- `join` - The user has joined the room (possibly after accepting an invite), and may participate
|
||||
in it.
|
||||
- `leave` - The user was once joined to the room, but has since left (possibly by choice, or
|
||||
possibly by being kicked).
|
||||
- `ban` - The user has been banned from the room, and is no longer allowed to join it until they
|
||||
are un-banned from the room (by having their membership state set to a value other than `ban`).
|
||||
- `knock` - The user has knocked on the room, requesting permission to participate. They may not
|
||||
participate in the room until they join.
|
||||
|
||||
The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise.
|
||||
The `third_party_invite` property will be set if this invite is an `invite` event and is the
|
||||
successor of an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) event,
|
||||
and absent otherwise.
|
||||
|
||||
This event may also include an `invite_room_state` key inside the event's `unsigned` data.
|
||||
If present, this contains an array of [stripped state events](/client-server-api/#stripped-state)
|
||||
|
|
@ -57,63 +67,54 @@ properties:
|
|||
- ban
|
||||
type: string
|
||||
is_direct:
|
||||
description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
|
||||
description: |-
|
||||
Flag indicating if the room containing this event was created with the intention of being
|
||||
a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
|
||||
type: boolean
|
||||
join_authorised_via_users_server:
|
||||
x-addedInMatrixVersion: "1.2"
|
||||
type: string
|
||||
description: |-
|
||||
Usually found on `join` events, this field is used to denote which homeserver (through representation of a user with sufficient power level)
|
||||
authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
|
||||
Usually found on `join` events, this field is used to denote which homeserver (through
|
||||
representation of a user with sufficient power level) authorised the user's join. More
|
||||
information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
|
||||
|
||||
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) of including this
|
||||
field in further events: in particular, the event must be signed by the server which
|
||||
owns the user ID in the field. When copying the membership event's `content`
|
||||
(for profile updates and similar) it is therefore encouraged to exclude this
|
||||
field in the copy, as otherwise the event might fail event authorization.
|
||||
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
|
||||
of including this field in further events: in particular, the event must be signed by the
|
||||
server which owns the user ID in the field. When copying the membership event's `content`
|
||||
(for profile updates and similar) it is therefore encouraged to exclude this field in the
|
||||
copy, as otherwise the event might fail event authorization.
|
||||
reason:
|
||||
x-addedInMatrixVersion: "1.1"
|
||||
type: string
|
||||
description: |-
|
||||
Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban.
|
||||
For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such
|
||||
as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day.
|
||||
Optional user-supplied text for why their membership has changed. For kicks and bans,
|
||||
this is typically the reason for the kick or ban. For other membership changes, this is a
|
||||
way for the user to communicate their intent without having to send a message to the
|
||||
room, such as in a case where Bob rejects an invite from Alice about an upcoming concert,
|
||||
but can't make it that day.
|
||||
|
||||
Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the
|
||||
reason behind a button or other component is recommended.
|
||||
Clients are not recommended to show this reason to users when receiving an invite due to
|
||||
the potential for spam and abuse. Hiding the reason behind a button or other component is
|
||||
recommended.
|
||||
third_party_invite:
|
||||
title: ThirdPartyInvite
|
||||
description: |-
|
||||
A third-party invite, if this `m.room.member` is the successor to an
|
||||
[`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
|
||||
event.
|
||||
type: object
|
||||
properties:
|
||||
display_name:
|
||||
description: A name which can be displayed to represent the user instead of their third-party identifier
|
||||
description: |-
|
||||
A name which can be displayed to represent the user instead of their
|
||||
third-party identifier
|
||||
type: string
|
||||
signed:
|
||||
description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.'
|
||||
properties:
|
||||
mxid:
|
||||
description: The invited matrix user ID. Must be equal to the user_id property of the event.
|
||||
type: string
|
||||
signatures:
|
||||
description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.'
|
||||
title: Signatures
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
token:
|
||||
description: The token property of the containing third_party_invite object.
|
||||
type: string
|
||||
required:
|
||||
- mxid
|
||||
- signatures
|
||||
- token
|
||||
title: signed
|
||||
type: object
|
||||
$ref: components/signed_third_party_invite.yaml
|
||||
required:
|
||||
- display_name
|
||||
- signed
|
||||
title: Invite
|
||||
type: object
|
||||
required:
|
||||
- membership
|
||||
title: EventContent
|
||||
|
|
|
|||
|
|
@ -1,28 +1,56 @@
|
|||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room."
|
||||
description: |-
|
||||
Acts as an `m.room.member` invite event, where there isn't a target user_id to
|
||||
invite. This event contains a token and a public key whose private key must be
|
||||
used to sign the token. Any user who can present that signature may use this
|
||||
invitation to join the target room.
|
||||
properties:
|
||||
content:
|
||||
properties:
|
||||
display_name:
|
||||
description: "A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID."
|
||||
description: |-
|
||||
A user-readable string which represents the user who has been invited.
|
||||
This should not contain the user's third-party ID, as otherwise when
|
||||
the invite is accepted it would leak the association between the
|
||||
matrix ID and the third-party ID.
|
||||
type: string
|
||||
key_validity_url:
|
||||
description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'."
|
||||
description: |-
|
||||
A URL which can be fetched, with querystring public_key=public_key, to
|
||||
validate whether the key has been revoked. The URL must return a JSON
|
||||
object containing a boolean property named 'valid'.
|
||||
type: string
|
||||
format: uri
|
||||
public_key:
|
||||
description: A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility.
|
||||
description: |-
|
||||
An Ed25519 key with which the token must be signed (though a signature
|
||||
from any entry in `public_keys` is also sufficient).
|
||||
|
||||
The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
|
||||
using the standard or URL-safe alphabets.
|
||||
|
||||
This exists for backwards compatibility.
|
||||
type: string
|
||||
public_keys:
|
||||
description: Keys with which the token may be signed.
|
||||
items:
|
||||
properties:
|
||||
key_validity_url:
|
||||
description: "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely."
|
||||
description: |-
|
||||
An optional URL which can be fetched, with querystring
|
||||
`public_key=<public_key>`, to validate whether the key has been
|
||||
revoked. The URL must return a JSON object containing a boolean
|
||||
property named `valid`. If this URL is absent, the key must be
|
||||
considered valid indefinitely.
|
||||
type: string
|
||||
public_key:
|
||||
description: A base-64 encoded ed25519 key with which token may be signed.
|
||||
description: |-
|
||||
An Ed25519 key with which the token may be signed.
|
||||
|
||||
The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
|
||||
using the standard or URL-safe alphabets.
|
||||
type: string
|
||||
required:
|
||||
- public_key
|
||||
|
|
@ -35,11 +63,15 @@ properties:
|
|||
- public_key
|
||||
type: object
|
||||
state_key:
|
||||
description: 'The token, of which a signature must be produced in order to join the room.'
|
||||
description: |-
|
||||
The token, of which a signature must be produced in order to join the
|
||||
room.
|
||||
type: string
|
||||
type:
|
||||
enum:
|
||||
- m.room.third_party_invite
|
||||
type: string
|
||||
title: 'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.'
|
||||
title: |-
|
||||
An invitation to a room issued to a third-party identifier, rather than a
|
||||
matrix user ID.
|
||||
type: object
|
||||
|
|
|
|||
|
|
@ -1,13 +1,41 @@
|
|||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.'
|
||||
description: |-
|
||||
A topic is a short message detailing what is currently being discussed
|
||||
in the room. It can also be used as a way to display extra information
|
||||
about the room, which may not be suitable for the room name. The room
|
||||
topic can also be set when creating a room using
|
||||
[`/createRoom`](client-server-api/#post_matrixclientv3createroom), either
|
||||
with the `topic` key or by specifying a full event in `initial_state`.
|
||||
|
||||
If the `topic` property is absent, null, or empty then the topic is unset. In other words,
|
||||
an empty `topic` property effectively resets the room to having no topic.
|
||||
|
||||
In order to prevent formatting abuse in room topics, clients SHOULD
|
||||
limit the length of topics during both entry and display, for instance,
|
||||
by capping the number of displayed lines. Additionally, clients SHOULD
|
||||
ignore things like headings and enumerations (or format them as regular
|
||||
text).
|
||||
properties:
|
||||
content:
|
||||
properties:
|
||||
topic:
|
||||
description: The topic text.
|
||||
description: |-
|
||||
The topic in plain text.
|
||||
|
||||
This SHOULD duplicate the content of the `text/plain`
|
||||
representation in `m.topic` if any exists.
|
||||
type: string
|
||||
m.topic:
|
||||
type: object
|
||||
title: TopicContentBlock
|
||||
x-addedInMatrixVersion: "1.15"
|
||||
description: |-
|
||||
Textual representation of the room topic in different mimetypes.
|
||||
properties:
|
||||
m.text:
|
||||
$ref: components/m_text_content_block.yaml
|
||||
required:
|
||||
- topic
|
||||
type: object
|
||||
|
|
|
|||
|
|
@ -51,6 +51,11 @@ mx-room-id:
|
|||
url: appendices#room-ids
|
||||
# regex: "^!"
|
||||
|
||||
mx-room-alias:
|
||||
title: Room Alias
|
||||
url: appendices#room-aliases
|
||||
# regex: "^#"
|
||||
|
||||
mx-server-name:
|
||||
title: Server Name
|
||||
url: appendices#server-name
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue