├── .gitignore ├── proposals ├── 1501-split-dag.png ├── images │ ├── state-res.png │ ├── 2858-login.png │ ├── 4297-msc-1.png │ ├── 4297-msc-2.png │ ├── 4297-msc-3.png │ ├── 4297-msc-sol-1.png │ ├── 4297-msc-sol-2.png │ ├── 1756-graph1.dot.png │ ├── 1756-graph2.dot.png │ ├── 2244-redaction-spam.png │ ├── state-res-rejected.png │ ├── 2010-spoiler-example.gif │ ├── 4297-msc-problem-a-1.png │ ├── 4297-msc-problem-a-2.png │ ├── 4297-msc-problem-a-3.png │ ├── 4297-msc-problem-b-1.png │ ├── 4297-msc-problem-b-2.png │ ├── 4297-msc-problem-b-3.png │ ├── 4291-creator-chicken-egg.png │ ├── 1756-graph1.dot │ ├── 1756-graph2.dot │ ├── state-res-rejected.dot │ └── 1730-seq-diagram.txt ├── 1759-rooms-v2.md ├── 3582-remove-room-feedback.md ├── 2582-remove-mimetype-from-encrypted-file.md ├── 1866-invite-unsupported-version-error-code.md ├── 3844-remove-mjolnir-sharing.md ├── 2526-add-delete-backup.md ├── 3289-rooms-v8.md ├── 2077-rooms-v5.md ├── 2240-rooms-v6.md ├── 2175-remove-creator-field.md ├── 1812-federation-make-membership.md ├── 2557-spoiler-clarifications.md ├── 2788-v6-default-version.md ├── 2689-fix-e2ee-for-guests.md ├── 3069-guests-whoami.md ├── 2174-move-redacts-key.md ├── 2713-remove-deprecated-identity-endpoints.md ├── 2320-identity-versions.md ├── 2832-appservice-auth-fix.md ├── 3375-room-v9.md ├── 2334-default-room-version-v5.md ├── 1831-srv-after-wellknown.md ├── 2033-whoami-device-id.md ├── 1721-rename-cas-to-sso.md ├── 2284-optional-identity-server-discovery.md ├── 1930-tombstone-notifications.md ├── 3122-deprecate-starting-verifications-without-request.md ├── 3938-remove-keyid-from-keys-endpoints.md ├── 3550-allow-403-response-profile-lookup.md ├── 2663-errors-nonexistent-push-rules.md ├── 3419-guest-state-events.md ├── 2604-login-fallback-device-info.md ├── 3820-rooms-v11.md ├── 2998-rooms-v7.md ├── 1802-standardised-federation-response-format.md ├── 2610-remove-oauth2-auth-type.md ├── 1983-leave-reasons.md ├── 3604-rooms-v10.md ├── 3786-acl-notifs.md ├── 4213-remove-server-name.md ├── 2765-widget-avatars.md ├── 4178-threepid-medium-not-supported.md ├── 1466-soft-logout.md ├── 1704-matrix.to-permalinks.md ├── 3818-copy-room-type-on-upgrade.md ├── 2611-remove-login-auth-type.md ├── 3283-enable_set_displayname-capabilities.md ├── 2414-optional-content-reporting-reason.md ├── 2076-enforce-validity-periods.md ├── 3821-update-redaction-rules-again.md ├── 4163-make-acls-apply-to-edus.md ├── 4138-update-cors-methods.md ├── 2457-password-modification-invalidating-devices.md ├── 3966-exact-event-property-contains-push-condition.md ├── 2422-allow-color-attribute-on-font-tag.md ├── 3904-room-version-10-as-a-default.md ├── 4307-auth-events-in-correct-room.md ├── 2181-user-deactivated-errcode.md ├── 4041-retry-after-header-rate-limiting.md ├── 3667-enforce-integer-power-levels.md ├── 1804-advertising-capable-room-versions.md ├── 4142-fix-reply-intentional-mentions.md ├── 2451-remove-query_auth-federation-endpoint.md ├── 3758-expand-push-rule-conditions.md ├── 1819-remove-presence-lists.md ├── 3980-dotted-fields-consistency.md ├── 2705-thumbnail-requirements.md ├── 4239-v11-default-version.md ├── 3288-pass_room_type_in_3pid_invite.md ├── 2184-allow-html-details.md ├── 4026-optional-authed-versions.md ├── 2630-sas-check-public-keys.md ├── 2002-rooms-v4.md ├── 2249-report-require-joined.md ├── 3316-appservice-timestamp-massaging.md ├── 2540-stricter-event-validation.md ├── 4189-guest-access-media-routes.md ├── 3567-optional-from-on-messages.md ├── 3783-fixed-base64-sas-verification.md ├── 4210-remove-legacy-mentions.md ├── 1961-integrations-auth.md ├── 2874-single-ssss.md ├── 1719-olm_unwedging.md ├── 2758-textual-id-grammar.md ├── 3589-v9-default-version.md ├── 3828-content-repository-corp-headers.md ├── 4156-server-name-to-via.md ├── 3987-push-actions-clean-up.md ├── 1794-federation-v2-invites.md ├── 3860-media-download-redirect.md ├── 2367-membership-reasons.md ├── 2263-homeserver-pw-resets.md ├── 3666-bundled-aggregations-for-search.md ├── 4132-deprecate-event-on-room-alias-uris.md ├── 4077-process-deprecated-html.md └── 1929-admin-contact.md ├── .editorconfig ├── .github ├── _typos.toml ├── workflows │ └── spell-check.yaml └── PULL_REQUEST_TEMPLATE │ ├── ready-proposal.md │ └── wip-proposal.md └── MSC_CHECKLIST.md /.gitignore: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /proposals/1501-split-dag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/1501-split-dag.png -------------------------------------------------------------------------------- /proposals/images/state-res.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/state-res.png -------------------------------------------------------------------------------- /proposals/images/2858-login.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/2858-login.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-1.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-2.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-3.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-sol-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-sol-1.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-sol-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-sol-2.png -------------------------------------------------------------------------------- /proposals/images/1756-graph1.dot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/1756-graph1.dot.png -------------------------------------------------------------------------------- /proposals/images/1756-graph2.dot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/1756-graph2.dot.png -------------------------------------------------------------------------------- /proposals/images/2244-redaction-spam.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/2244-redaction-spam.png -------------------------------------------------------------------------------- /proposals/images/state-res-rejected.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/state-res-rejected.png -------------------------------------------------------------------------------- /proposals/images/2010-spoiler-example.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/2010-spoiler-example.gif -------------------------------------------------------------------------------- /proposals/images/4297-msc-problem-a-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-problem-a-1.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-problem-a-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-problem-a-2.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-problem-a-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-problem-a-3.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-problem-b-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-problem-b-1.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-problem-b-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-problem-b-2.png -------------------------------------------------------------------------------- /proposals/images/4297-msc-problem-b-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4297-msc-problem-b-3.png -------------------------------------------------------------------------------- /proposals/images/4291-creator-chicken-egg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/matrix-org/matrix-spec-proposals/HEAD/proposals/images/4291-creator-chicken-egg.png -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig is awesome: https://EditorConfig.org 2 | root = true 3 | 4 | [*] 5 | insert_final_newline = true 6 | charset = utf-8 7 | max_line_length = 120 8 | -------------------------------------------------------------------------------- /.github/_typos.toml: -------------------------------------------------------------------------------- 1 | [default] 2 | check-filename = true 3 | 4 | [default.extend-identifiers] 5 | OTK = "OTK" 6 | OTKs = "OTKs" 7 | 8 | [default.extend-words] 9 | OTK = "OTK" 10 | OTKs = "OTKs" 11 | Iy = "Iy" 12 | -------------------------------------------------------------------------------- /proposals/images/1756-graph1.dot: -------------------------------------------------------------------------------- 1 | graph { 2 | A1 [label="A's PDP-11"] 3 | AV [label="A's virtual device"] 4 | A2 [label="A's Osborne 2"] 5 | B1 [label="B's Dynabook"] 6 | BV [label="B's virtual device"] 7 | B2 [label="B's VAX"] 8 | A1 -- AV 9 | AV -- A2 10 | A2 -- B1 11 | B1 -- BV 12 | BV -- B2 13 | } -------------------------------------------------------------------------------- /proposals/1759-rooms-v2.md: -------------------------------------------------------------------------------- 1 | # MSC 1759 - Rooms V2 2 | 3 | This MSC proposes creating a new room version to allow servers and users to opt 4 | in to using the new state resolution algorithm. 5 | 6 | 7 | ## Proposal 8 | 9 | The new room version is called "2". The only difference between v2 and v1 is 10 | that v2 rooms use the v2 state resolution algorithm, as defined in MSC 1442 and 11 | MSC 1693. 12 | 13 | It is not proposed that servers change the default room version used when 14 | creating new rooms. 15 | -------------------------------------------------------------------------------- /proposals/images/1756-graph2.dot: -------------------------------------------------------------------------------- 1 | digraph { 2 | A1 [label="A's PDP-11"] 3 | A2 [label="A's Osborne 2"] 4 | AM [label="A's master key"] 5 | AS [label="A's self-signing key"] 6 | AU [label="A's user-signing key"] 7 | BM [label="B's master key"] 8 | BU [label="B's user-signing key"] 9 | BS [label="B's self-signing key"] 10 | B1 [label="B's Dynabook"] 11 | B2 [label="B's VAX"] 12 | AS -> A1 13 | AS -> A2 14 | AM -> AS 15 | AM -> AU 16 | AU -> BM 17 | BM -> BS 18 | BM -> BU 19 | BU -> AM 20 | BS -> B1 21 | BS -> B2 22 | } 23 | -------------------------------------------------------------------------------- /.github/workflows/spell-check.yaml: -------------------------------------------------------------------------------- 1 | name: Spell Check 2 | on: 3 | push: 4 | branches: 5 | - main 6 | pull_request: 7 | 8 | jobs: 9 | run: 10 | name: Spell Check with Typos 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Check out repository 14 | uses: actions/checkout@v4 15 | 16 | - name: Check spelling of proposals 17 | uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10 18 | with: 19 | config: ${{github.workspace}}/.github/_typos.toml 20 | -------------------------------------------------------------------------------- /proposals/3582-remove-room-feedback.md: -------------------------------------------------------------------------------- 1 | # MSC3582: Remove m.room.message.feedback 2 | 3 | The spec defines an 4 | [`m.room.message.feedback`](https://spec.matrix.org/unstable/client-server-api/#mroommessagefeedback) 5 | event that 6 | 7 | - is obsoleted by read receipts, 8 | - is not used by anyone anywhere, and 9 | - is discouraged by the spec. 10 | 11 | See also: https://github.com/matrix-org/matrix-doc/issues/3318 12 | 13 | ## Proposal 14 | 15 | The `m.room.message.feedback` event should be removed from the spec. 16 | -------------------------------------------------------------------------------- /proposals/2582-remove-mimetype-from-encrypted-file.md: -------------------------------------------------------------------------------- 1 | # Remove `mimetype` from `EncryptedFile` object 2 | 3 | 4 | ## Proposal 5 | The example in the spec currently lists `mimetype` in the [examples for `EncryptedFile`](https://matrix.org/docs/spec/client_server/r0.6.1#extensions-to-m-message-msgtypes) but not in 6 | the object definition. As that is duplicate information of the `info` block of file events, the 7 | mimetype should just be removed altogether. 8 | 9 | 10 | ## Potential issues 11 | Some clients might depend on this. However, as of August 2021, all known clients have 12 | been confirmed to not use this. 13 | -------------------------------------------------------------------------------- /proposals/images/state-res-rejected.dot: -------------------------------------------------------------------------------- 1 | digraph Rejected { 2 | rankdir=BT; 3 | 4 | // Events 5 | A[label="A: Alice ops Bob"]; 6 | B[label="B: Alice deops Bob"]; 7 | D[label="D: Bob sets topic"]; 8 | E[label="E: Alice reops Bob"]; 9 | 10 | // Prev events 11 | B -> A; 12 | C -> B; 13 | D -> C; 14 | E -> C; 15 | F -> D; 16 | F -> E; 17 | 18 | // Auth Events 19 | 20 | B -> A [color=blue,style=bold]; 21 | D -> A [color=blue,style=bold]; 22 | E -> B [color=blue,style=bold]; 23 | } 24 | -------------------------------------------------------------------------------- /proposals/1866-invite-unsupported-version-error-code.md: -------------------------------------------------------------------------------- 1 | # MSC 1866 - Unsupported Room Version Error Code for Invites 2 | 3 | It is currently unspecified what error code should be relayed to clients when 4 | they attempt to invite a user on a remote server that does not support the room 5 | version. 6 | 7 | The proposal is to reuse the `M_UNSUPPORTED_ROOM_VERSION` error code that is 8 | currently returned by the create room API. 9 | 10 | Strictly, the error returned by the create room API would mean the local server 11 | didn't support the room version, while for the invite API it would mean the 12 | remote server didn't. However, there is sufficient overlap that it makes sense 13 | to reuse the same error code and rely on the context to differentiate the two 14 | cases. 15 | -------------------------------------------------------------------------------- /proposals/3844-remove-mjolnir-sharing.md: -------------------------------------------------------------------------------- 1 | # MSC3844: Remove "Mjolnir" (policy room) sharing mechanism 2 | 3 | Way back when [MSC2313](https://github.com/matrix-org/matrix-spec-proposals/pull/2313) was written, 4 | it included a [sharing](https://spec.matrix.org/v1.3/client-server-api/#sharing-1) mechanism that 5 | never got used. 6 | 7 | That sharing mechanism is to be removed from the specification due to lack of use and questionable 8 | technical approach. In practice, users and implementations have been handing out room aliases to 9 | policy rooms just fine. 10 | 11 | Normally an MSC would propose deprecation followed by eventual removal, however seeing as the core 12 | team is aware of exactly zero implementations of this feature it feels safe to just outright remove. 13 | -------------------------------------------------------------------------------- /proposals/2526-add-delete-backup.md: -------------------------------------------------------------------------------- 1 | # MSC2526: Add ability to delete key backups 2 | 3 | [MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219) defined a 4 | mechanism for key backups. However, it inadvertently omitted the endpoint to 5 | delete an entire key backup. This proposal adds the endpoint. 6 | 7 | ## Proposal 8 | 9 | An endpoint is added, `DELETE /room_keys/version/{version}`, that deletes a 10 | backup version. Both the information about the key backup, as well as all keys 11 | associated with the backup should be deleted. If the specified version was 12 | previously deleted, the endpoint succeeds, returning an HTTP code of 200. If 13 | the specified version never existed, the endpoint returns an HTTP code of 404 14 | with a Matrix `errcode` of `M_NOT_FOUND`. 15 | -------------------------------------------------------------------------------- /proposals/3289-rooms-v8.md: -------------------------------------------------------------------------------- 1 | # MSC3289: Room Version 8 2 | 3 | A new room version, `8`, is proposed using [room version 7](https://spec.matrix.org/unstable/rooms/v7/) 4 | as a base and incorporating the following MSCs: 5 | 6 | * [MSC3083](https://github.com/matrix-org/matrix-doc/pull/3083) - Restricting room 7 | membership based on membership in other rooms 8 | 9 | Though other MSCs are capable of being included in this version, they do not have 10 | sufficient implementation to be considered for this room version. A future room 11 | version may include them. 12 | 13 | Room version `8` upon being added to the specification shall be considered stable. 14 | No other room versions are affected by this MSC. Before room version `8` can enter 15 | the specification, MSC3083 needs to complete its final comment period. 16 | -------------------------------------------------------------------------------- /proposals/2077-rooms-v5.md: -------------------------------------------------------------------------------- 1 | # MSC2077 - Room version 5 2 | 3 | This MSC proposes creating room version 5, which will enforce the signing key 4 | `valid_until_ts` timestamps proposed in 5 | [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). 6 | 7 | ## Proposal 8 | 9 | The new room version is called `5`. The only difference between v5 and v4 is 10 | that v5 rooms enforce the `valid_until_ts` timestamp on signing keys as 11 | proposed in [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). 12 | 13 | It is not yet proposed to change the default room version to v5. Version 5 will 14 | be considered a "stable" version. 15 | 16 | ## Notes 17 | 18 | See also [MSC2002](./2002-rooms-v4.md), which proposed room v4 but also 19 | mentioned that a v5 was anticipated and gave some context for this change. 20 | -------------------------------------------------------------------------------- /proposals/2240-rooms-v6.md: -------------------------------------------------------------------------------- 1 | # MSC2240: Room Version 6 2 | 3 | A new room version, `6`, is proposed using [room version 5](https://matrix.org/docs/spec/rooms/v5.html) as a base 4 | and incorporating the following MSCs: 5 | 6 | * [MSC2209](https://github.com/matrix-org/matrix-doc/pull/2209) - Including notifications in power level auth rules. 7 | * [MSC2432](https://github.com/matrix-org/matrix-doc/pull/2432) - Alias event authorisation and redaction. 8 | * [MSC2540](https://github.com/matrix-org/matrix-doc/pull/2540) - Integers in canonical JSON compliance. 9 | 10 | Though other MSCs are capable of being included in this version, they do not have sufficient implementation to be 11 | considered stable enough for v6 rooms. A future room version may still include them. 12 | 13 | Room version 6 upon being added to the specification shall be considered stable. No other room versions are affected 14 | by this MSC. 15 | -------------------------------------------------------------------------------- /proposals/2175-remove-creator-field.md: -------------------------------------------------------------------------------- 1 | # MSC2175: Remove the `creator` field from `m.room.create` events 2 | 3 | [`m.room.create`](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-create) 4 | events have a mandatory `creator` property giving the ID of the user who 5 | created the room. This field is redundant as it is always identical to the 6 | `sender` of the create event. 7 | 8 | This MSC proposes that, in a future room version, this field should be removed 9 | and that the `sender` field be used instead. 10 | 11 | Note that `creator` is mentioned in the [auth 12 | rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules). It can 13 | safely be replaced with a check against the `sender` instead. 14 | 15 | `creator` is also mentioned as a key to be preserved during [Event 16 | redaction](https://matrix.org/docs/spec/client_server/r0.5.0#redactions). It 17 | should be removed from that list. 18 | -------------------------------------------------------------------------------- /proposals/1812-federation-make-membership.md: -------------------------------------------------------------------------------- 1 | # MSC 1813 - Federation Make Membership Room Version 2 | 3 | This proposal adds a new `room_version` field to the responses of `/make_leave` 4 | and `/make_join` APIs. 5 | 6 | ## Motivation 7 | 8 | It is planned for future room versions to be able to change the format of events 9 | in various ways. To support this, all servers must know the room version 10 | whenever they need to parse an event. Currently the `/make_*` APIs do not 11 | include the room version in the response, so the requesting server is unable to 12 | parse the event included in the response body. 13 | 14 | ## Proposal 15 | 16 | Add a new `room_version` field to the response body of the `v1` `/make_join` and 17 | `/make_leave` APIs, which describes the room version. 18 | 19 | For backwards compatibility servers must correctly handle responses that do not 20 | include the new field. In which case the room version is assumed to be one of 21 | either `1` or `2`. 22 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/ready-proposal.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Proposal ready for review 3 | about: A proposal that is ready for review by the core team and community. 4 | title: '' 5 | labels: proposal, proposal-in-review 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | 12 | ### Pull Request Checklist 13 | 14 | 15 | 16 | * [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec-proposals/blob/master/CONTRIBUTING.md#sign-off) 17 | * [ ] Update the title and file name of your proposal to match this PR's number (after opening). 18 | * [ ] Pull request includes a ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above. 19 | * [ ] Your MSC adheres to each point in the [MSC Checklist](MSC_CHECKLIST.md). 20 | * [ ] Ask in 21 | [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to 22 | get feedback on this PR. 23 | -------------------------------------------------------------------------------- /proposals/2557-spoiler-clarifications.md: -------------------------------------------------------------------------------- 1 | # MSC2557: Clarifications on spoilers 2 | 3 | Spoiler messages are described in [MSC2010](https://github.com/matrix-org/matrix-doc/pull/2010) 4 | though the MSC is unclear if the fallback is required to be sent by clients. 5 | 6 | ## Proposal 7 | 8 | The fallback for spoiler messages is optional, though recommended to be sent by clients. Clients 9 | should make reasonable efforts to represent the spoiler in the `body` field of a message. 10 | 11 | The recommended fallback format is unchanged. 12 | 13 | Additionally, this proposal opens up spoilers to any HTML-supporting message types. Currently 14 | this includes `m.text` (already included by MSC2010), `m.notice`, and `m.emote`. 15 | 16 | ## Potential issues 17 | 18 | Clients could inadvertently spoil parts of a message by not representing the spoiler correctly 19 | in the `body` of the message. The author believes this would quickly show up as a bug report 20 | on the client due to the nature of spoilers. 21 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/wip-proposal.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: WIP Proposal 3 | about: A proposal that isn't quite ready for formal review yet. 4 | title: '[WIP] Your Proposal Title' 5 | labels: proposal 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | 12 | ### Pull Request Checklist 13 | 14 | 15 | 16 | * [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec-proposals/blob/master/CONTRIBUTING.md#sign-off) 17 | * [ ] Update the title and file name of your proposal to match this PR's number (after opening). 18 | * [ ] Pull request includes a ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above. 19 | * [ ] Have a look at the [MSC Checklist](MSC_CHECKLIST.md) for guidelines on various aspects of your MSC. 20 | 21 | 22 | -------------------------------------------------------------------------------- /proposals/2788-v6-default-version.md: -------------------------------------------------------------------------------- 1 | # MSC2788: Room version 6 as a default 2 | 3 | Enough time has passed to allow the public federation to upgrade their servers to support room 4 | version 6. This proposal aims to make v6 the default room version. 5 | 6 | ## Proposal 7 | 8 | The specification adopts v6 as the suggested default room version, making no changes to the stability 9 | of any room versions. As of writing, v5 is currently the suggested room version. 10 | 11 | Room version 6 has the following specification: https://matrix.org/docs/spec/rooms/v6 12 | 13 | ## Potential issues 14 | 15 | Servers will be encouraged to update their config/internal defaults to use v6 instead of v5. This 16 | is considered a good problem to have. 17 | 18 | ## Alternatives 19 | 20 | None relevant. 21 | 22 | ## Security considerations 23 | 24 | None relevant. 25 | 26 | ## Unstable prefix 27 | 28 | None relevant - servers can already choose a different default room version legally. This MSC 29 | just formalizes v6 as the default. 30 | -------------------------------------------------------------------------------- /proposals/2689-fix-e2ee-for-guests.md: -------------------------------------------------------------------------------- 1 | # MSC2689: Allow guests to operate in encrypted rooms 2 | 3 | [#751](https://github.com/matrix-org/matrix-doc/pull/751) granted guest users access to several endpoints in order to allow them to use E2EE. 4 | I found that guests are able to join encrypted rooms and read messages from other members. But when the 5 | guest wants to send an event into the room the client receives a "guest access not allowed" error 6 | for the `/rooms/{room_id}/members` endpoint. I assume the client tries to read the list of room members 7 | to prepare the encryption of the event for the present members. Tests with a patched Synapse showed that 8 | allowing guests to use this endpoint results in a normal behaviour and enables guests to communicate in 9 | encrypted rooms. 10 | 11 | 12 | ## Proposal 13 | 14 | Allow guests to use the `GET /_matrix/client/r0/rooms/{room_id}/members` endpoint to enable them to 15 | operate properly in encrypted rooms. 16 | 17 | 18 | ## Alternatives 19 | 20 | The list of room members could also be read from the sync. However that would not work with Lazy Loading. 21 | -------------------------------------------------------------------------------- /proposals/3069-guests-whoami.md: -------------------------------------------------------------------------------- 1 | # MSC3069: Allow guests to use /account/whoami 2 | 3 | Currently the [/account/whoami](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-account-whoami) 4 | endpoint does not mention anything about guests, which is a bit of an oversight. The implementation 5 | of the endpoint got created such that guest access was declined. 6 | 7 | ## Proposal 8 | 9 | Guests are allowed to use `/account/whoami`. When a guest makes a request, the response will have 10 | an added `is_guest: true` field - this field is optional (default `false`) otherwise. 11 | 12 | ## Potential issues 13 | 14 | None forseen. This corrects a mistake. 15 | 16 | ## Alternatives 17 | 18 | None relevant. 19 | 20 | ## Security considerations 21 | 22 | Guests will be able to know their user ID, as they would when they registered in the first place. 23 | 24 | ## Unstable prefix 25 | 26 | While this MSC is not in a stable version of the specification, implementations should use 27 | `org.matrix.msc3069.is_guest` in place of `is_guest`. Callers should note that they might see 28 | `M_GUEST_ACCESS_FORBIDDEN` errors if the server is not implementing this MSC. 29 | -------------------------------------------------------------------------------- /proposals/2174-move-redacts-key.md: -------------------------------------------------------------------------------- 1 | # MSC2174: move the `redacts` property to `content` 2 | 3 | [`m.room.redaction`](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-redaction) 4 | events currently have an *event-level* property `redacts` which gives the event 5 | ID of the event being redacted. 6 | 7 | The presence of this field at the event level, rather than under the `content` 8 | key, is anomalous. This MSC proposes that, in a future room version, the 9 | `redacts` property be moved under the `content` key. 10 | 11 | For backwards-compatibility with *older* clients, servers should add a `redacts` 12 | property to the top level of `m.room.redaction` events in *newer* room versions 13 | when serving such events over the Client-Server API. 14 | 15 | For improved compatibility with *newer* clients, servers should add a `redacts` 16 | property to the `content` of `m.room.redaction` events in *older* room versions 17 | when serving such events over the Client-Server API. 18 | 19 | ## Unstable prefix 20 | 21 | Implementations should use `org.matrix.msc2174` for the room version containing 22 | this change until assigned to a specified room version. That room version should 23 | use room version 6 as a base. 24 | -------------------------------------------------------------------------------- /proposals/2713-remove-deprecated-identity-endpoints.md: -------------------------------------------------------------------------------- 1 | # MSC2713: Remove deprecated Identity Service endpoints 2 | 3 | Implementations will have had plenty of time to adopt the new v2 API for Identity Servers, so 4 | we should clean out the old endpoints. 5 | 6 | All deprecated endpoints in the r0.3.0 Identity Service API specification are to be removed. 7 | 8 | For completeness, this includes: 9 | 10 | * `GET /_matrix/identity/api/v1` 11 | * `GET /_matrix/identity/api/v1/pubkey/{keyId}` 12 | * `GET /_matrix/identity/api/v1/pubkey/isvalid` 13 | * `GET /_matrix/identity/api/v1/pubkey/ephemeral/isvalid` 14 | * `GET /_matrix/identity/api/v1/lookup` 15 | * `POST /_matrix/identity/api/v1/bulk_lookup` 16 | * `POST /_matrix/identity/api/v1/validate/email/requestToken` 17 | * `POST /_matrix/identity/api/v1/validate/email/submitToken` 18 | * `GET /_matrix/identity/api/v1/validate/email/submitToken` 19 | * `POST /_matrix/identity/api/v1/validate/msisdn/requestToken` 20 | * `POST /_matrix/identity/api/v1/validate/msisdn/submitToken` 21 | * `GET /_matrix/identity/api/v1/validate/msisdn/submitToken` 22 | * `GET /_matrix/identity/api/v1/3pid/getValidated3pid` 23 | * `POST /_matrix/identity/api/v1/3pid/bind` 24 | * `POST /_matrix/identity/api/v1/3pid/unbind` 25 | * `POST /_matrix/identity/api/v1/store-invite` 26 | * `POST /_matrix/identity/api/v1/sign-ed25519` 27 | -------------------------------------------------------------------------------- /proposals/2320-identity-versions.md: -------------------------------------------------------------------------------- 1 | # Versions information for identity servers 2 | 3 | The client-server API currently specifies a `/versions` endpoint that allows 4 | clients to know what version of that API are implemented by the server. 5 | Identity servers could benefit from that endpoint as both homeservers and 6 | clients interact with them, and therefore could know which features they can 7 | expect a given identity server to implement by looking at the versions of the 8 | API it claims to support. 9 | 10 | ## Proposal 11 | 12 | This proposal adds the following endpoint to the identity server API. 13 | 14 | ### `GET /_matrix/identity/versions` 15 | 16 | This endpoint serves information about the versions of the identity server API 17 | this identity server supports. Its response uses the following format: 18 | 19 | ```json 20 | { 21 | "versions": [ 22 | "r0.1.0", 23 | "r0.2.0", 24 | "r0.2.1", 25 | ] 26 | } 27 | ``` 28 | 29 | ## Alternative solutions 30 | 31 | Another solution which was considered was using the status check endpoint ([`GET 32 | /_matrix/api/v1`](https://matrix.org/docs/spec/identity_service/r0.2.0#get-matrix-identity-api-v1)) 33 | to serve this information. This solution was discarded because it's using a 34 | versioned endpoint, which doesn't make sense to advertise the supported versions 35 | of the API to use. 36 | -------------------------------------------------------------------------------- /proposals/2832-appservice-auth-fix.md: -------------------------------------------------------------------------------- 1 | # MSC2832: Homeserver -> Application Service authorization header 2 | Most of the auth tokens in the spec are passed in the `Authorization` header, 3 | with the `access_token` query parameter supported for backwards-compatibility. 4 | For some reason, the application service spec was not updated in the same way 5 | and it still requires using the archaic query parameter when the homeserver 6 | pushes transactions to the appservice. 7 | 8 | ## Proposal 9 | The `access_token` query parameter is removed from all requests made by the 10 | homeserver to appservice and is replaced with the `Authorization` header with 11 | `Bearer ` as the value. 12 | 13 | ### Backwards-compatibility 14 | Homeservers which want to support old spec versions in the appservice API may 15 | send both the query parameter and header. Similarly, appservices may accept the 16 | token from either source. 17 | 18 | ## Security considerations 19 | Not fixing this causes access tokens to be logged in many bridges. 20 | 21 | ## Alternatives 22 | We could add a way for appservices to explicitly specify which spec version 23 | they want in order to implement backwards-compatibility without sending both 24 | tokens. 25 | 26 | ## Unstable prefix 27 | The authorization header is already used in the client-server spec, and an 28 | unstable prefix would just unnecessarily complicate things. 29 | -------------------------------------------------------------------------------- /proposals/3375-room-v9.md: -------------------------------------------------------------------------------- 1 | # MSC3375: Room Version 9 2 | 3 | A new room version, `9`, is proposed using [room version 8](https://spec.matrix.org/unstable/rooms/v8/) 4 | as a base and incorporating the following: 5 | 6 | The redaction rules for room version 9 are updated, such that `m.room.member` 7 | events allow the `join_authorised_via_users_server` key in addition to the 8 | `membership` key. 9 | 10 | Though other MSCs are capable of being included in this version, they do not have 11 | sufficient implementation to be considered for this room version. A future room 12 | version may include them. 13 | 14 | Room version `9` upon being added to the specification shall be considered stable. 15 | No other room versions are affected by this MSC. 16 | 17 | ## Background 18 | 19 | Protecting this key from redaction was missing in [MSC3083](https://github.com/matrix-org/matrix-doc/blob/main/proposals/3083-restricted-rooms.md). 20 | By redacting it, new servers which join a room are unable to properly authorise 21 | `m.room.member` events which include the `join_authorised_via_users_server` key 22 | and have been redacted. This can cause a split-brained room where some servers 23 | believe a member is joined and other servers do not see the member in the room. 24 | 25 | Note that a new room version is necessary since this will change that event ID 26 | calculation of the `m.room.member` event (and thus is not backwards compatible). 27 | -------------------------------------------------------------------------------- /proposals/2334-default-room-version-v5.md: -------------------------------------------------------------------------------- 1 | # [MSC2334](https://github.com/matrix-org/matrix-doc/pull/2334) - Change default room version to v5 2 | 3 | This MSC proposes changing the recommended default room version from v4 to v5. 4 | This implements steps 5 and 6 of the plan from 5 | [MSC2002](https://github.com/matrix-org/matrix-doc/issues/2002). 6 | 7 | Room version 5 enforces the `valid_until_ts` timestamp on signing keys as 8 | proposed in [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). 9 | 10 | ## Proposal 11 | 12 | When [MSC2077](https://github.com/matrix-org/matrix-doc/issues/2077) proposed 13 | room version 5, the default version continued to be v4 to allow old servers to 14 | continue to chat in newly created rooms. Server-Server API r0.1.2 (which 15 | contains the details on room version 5) and Synapse 1.0.0 (with support for room 16 | version 5) were both released more than 4 months ago which has given people 17 | plenty of time to update. Room version 5 should be the default room version so 18 | that newly created rooms enforce key-validity periods. 19 | 20 | ## Potential issues 21 | 22 | Servers which do not support room version 5 will not be able to participate in 23 | newly created rooms on other servers. Hopefully this will encourage them to 24 | update their server. 25 | 26 | ## Security considerations 27 | 28 | Room version 5 fixes known security vulnerabilities but that doesn't do much 29 | good if newly created rooms aren't using room version 5 by default. -------------------------------------------------------------------------------- /proposals/1831-srv-after-wellknown.md: -------------------------------------------------------------------------------- 1 | # Proposal to do SRV lookups after .well-known to discover homeservers 2 | 3 | Currently there is a logistical error proposed by [MSC1708](https://github.com/matrix-org/matrix-doc/pull/1708) 4 | which results in some homeservers unable to migrate to the new functionality 5 | proposed by [MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711). This 6 | can happen if the delegated homeserver cannot obtain a valid TLS certificate for 7 | the domain, and an SRV record is used for backwards compatibility reasons. 8 | 9 | Specifically, in order to be compatible with requests from both Synapse 0.34 and 1.0, 10 | servers can have both a SRV and a .well-known file, with Synapse presenting a certificate 11 | corresponding to the target of the .well-known. Synapse 0.34 is then happy because it 12 | will follow the SRV (and won't care about the incorrect certificate); Synapse 1.0 is 13 | happy because it will follow the .well-known (and will see the correct cert). 14 | 15 | ## Proposal 16 | 17 | We change the order of operations to perform a .well-known lookup before falling 18 | back to resolving the SRV record. This allows for domains to delegate to other 19 | hostnames and maintains backwards compatibility with older homeservers. 20 | 21 | ## Tradeoffs 22 | 23 | More HTTP hits will be made due to the .well-known lookup being first. This is 24 | somewhat mitigated by servers caching the responses appropriately, and using 25 | connection pools where possible. 26 | -------------------------------------------------------------------------------- /proposals/2033-whoami-device-id.md: -------------------------------------------------------------------------------- 1 | # Proposal to include device IDs in `/account/whoami` 2 | 3 | There are some use cases (namely using 4 | [Pantalaimon with bots](https://github.com/matrix-org/pantalaimon/issues/14)) 5 | which could benefit from knowing the `device_id` associated with a token. 6 | 7 | 8 | ## Proposal 9 | 10 | The `/account/whoami` endpoint receives an additional response field for the `device_id` 11 | associated with the access token. The field is optional because appservice users may not 12 | have a real device associated with them. Non-appservice users should always have a device 13 | associated with them. 14 | 15 | Access tokens are already associated with at most 1 device, and devices are associated with 16 | exactly 1 access token. Because of this, we do not need to worry about multiple devices 17 | causing problems. For more information, see 18 | https://matrix.org/docs/spec/client_server/r0.4.0.html#relationship-between-access-tokens-and-devices 19 | 20 | *Note*: Pantalaimon would likely require a `device_id` be returned and error requests 21 | otherwise. This should be considered expected behaviour by Pantalaimon in the MSC author's 22 | opinion. 23 | 24 | 25 | ## Tradeoffs 26 | 27 | We could introduce a `/device/whoami` endpoint, however that is a less superior option. Most 28 | calls to `/device/whoami` would additionally need to call `/account/whoami` to determine the 29 | user ID of the account. We had might as well bundle the two pieces of information into the 30 | same request. 31 | -------------------------------------------------------------------------------- /proposals/1721-rename-cas-to-sso.md: -------------------------------------------------------------------------------- 1 | # MSC1721: Rename `m.login.cas` to `m.login.sso` 2 | 3 | The Matrix Client-Server spec includes a [section on client login using Central 4 | Authentication Service 5 | (CAS)](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login). 6 | 7 | The spec currently fails to mention it, but this process is triggered when [`GET 8 | /login`](https://matrix.org/docs/spec/client_server/r0.4.0.html#get-matrix-client-r0-login) 9 | returns a flow type of `m.login.cas`. 10 | 11 | Nothing in this flow is specific to CAS - it is equally applicable for other 12 | web-based single-sign-on processes, such as SAML. 13 | 14 | Accordingly, we should rename `cas` to `sso`. 15 | 16 | ## Proposal 17 | 18 | 1. `m.login.sso` should be defined as a valid login type for return from `GET 19 | /login`. (We should probably mention `m.login.cas` in the spec while we are 20 | there.) 21 | 22 | 2. When a client wishes to use the SSO login type, it should redirect to 23 | `/_matrix/client/r0/login/sso/redirect` (instead of 24 | `/_matrix/client/r0/login/cas/redirect`). 25 | 26 | 3. Servers should treat `/_matrix/client/r0/login/sso/redirect` identically to 27 | `/_matrix/client/r0/login/cas/redirect`: they should issue a redirect to 28 | their configured single-sign-on system. 29 | 30 | 4. Servers which support `m.login.sso` should make sure they update their [login 31 | fallback page](https://matrix.org/docs/spec/client_server/r0.4.0.html#login-fallback) 32 | to understand the new login type. 33 | -------------------------------------------------------------------------------- /proposals/2284-optional-identity-server-discovery.md: -------------------------------------------------------------------------------- 1 | # MSC2284: Making the identity server optional during discovery 2 | 3 | Currently the specification requires that clients `FAIL_ERROR` (hard failure - do not continue) 4 | when the `.well-known` file for `m.identity_server` points to somewhere invalid or is invalid 5 | itself. This can cause problems for clients if they either don't need an identity server to 6 | function (and are forced to validate it anyways) or the client ends up having to disable all 7 | their login UX because the identity server is misconfigured/down. 8 | 9 | This proposal aims to change that by allowing clients to make a conscious decision to continue 10 | with the invalid identity server configuration, provided the homeserver configuration is valid. 11 | 12 | ## Proposal 13 | 14 | Instead of `FAIL_ERROR` for an invalid `m.identity_server` schema/server, clients are to move 15 | to the `FAIL_PROMPT` (inform the user, ask for input if applicable) state. Clients can decide 16 | to show a warning that the identity server is unavailable and allow the user to continue with 17 | the invalid (or client's default) configuration. 18 | 19 | ## Tradeoffs 20 | 21 | Clients can end up being configured with an invalid or inoperable identity server. This is 22 | considered a feature by this proposal to allow for less intelligent clients to have their 23 | identity server disabled. Intelligent clients could interpret the lack of identity server 24 | as the homeserver/user asking that identity server functionality be disabled in the client. 25 | -------------------------------------------------------------------------------- /proposals/1930-tombstone-notifications.md: -------------------------------------------------------------------------------- 1 | # Proposal to add a default push rule for m.room.tombstone events 2 | 3 | Currently users are unaware of when a room becomes upgraded, leaving them potentially in the old room 4 | without knowing until they visit the room again. By having a notification for when the room is upgraded, 5 | users are able to ensure they are able to stay relevant in rooms by joining the upgraded room. 6 | 7 | 8 | ## Proposal 9 | 10 | A new default override rule is to be added which is similar to `@room` notifications: 11 | 12 | ```json 13 | { 14 | "rule_id": ".m.rule.tombstone", 15 | "default": true, 16 | "enabled": true, 17 | "conditions": [ 18 | { 19 | "kind": "event_match", 20 | "key": "type", 21 | "pattern": "m.room.tombstone" 22 | }, 23 | { 24 | "kind": "event_match", 25 | "key": "state_key", 26 | "pattern": "" 27 | } 28 | ], 29 | "actions": [ 30 | "notify", 31 | { 32 | "set_tweak": "highlight", 33 | "value": true 34 | } 35 | ] 36 | } 37 | ``` 38 | 39 | 40 | ## Tradeoffs 41 | 42 | Clients could calculate this on their own and show some sort of "room upgraded" notification instead, 43 | however by doing it this way it means that all clients would need to be aware of room upgrades. Having 44 | a default push rule means that clients get this notification for free. Clients which want a more diverse 45 | UX can still do so by ignoring this push rule locally. 46 | -------------------------------------------------------------------------------- /proposals/3122-deprecate-starting-verifications-without-request.md: -------------------------------------------------------------------------------- 1 | # MSC3122: Deprecate starting key verifications without requesting first 2 | 3 | Currently, the [Key verification 4 | framework](https://matrix.org/docs/spec/client_server/r0.6.1#key-verification-framework) 5 | allows a device to begin a verification via to-device messages by sending an 6 | `m.key.verification.start` event without first sending or receiving an 7 | `m.key.verification.request` message. (The last sentence of the 5th paragraph 8 | of the Key verification framework in the unstable spec, as of the time of 9 | writing.) However, doing so does not provide a good user experience, and 10 | allowing this adds unnecessary complexity to implementations. 11 | 12 | We propose to deprecate allowing this behaviour. 13 | 14 | Note that verifications in DMs do not allow this behaviour. Currently, Element 15 | Web is the only client known to do this. 16 | 17 | ## Proposal 18 | 19 | The ability to begin a key verification by sending an 20 | `m.key.verification.start` event as a to-device event without a prior 21 | `m.key.verification.request` is deprecated. New clients should not begin 22 | verifications in this way, but will still need to accept verifications begun in 23 | this way, until it is removed from the spec. 24 | 25 | ## Potential issues 26 | 27 | None. 28 | 29 | ## Alternatives 30 | 31 | We could do nothing and leave it in the spec. But we should clean up cruft when 32 | possible. 33 | 34 | ## Security considerations 35 | 36 | None. 37 | 38 | ## Unstable prefix 39 | 40 | No unstable prefix is required since we are simply deprecating behaviour. 41 | -------------------------------------------------------------------------------- /proposals/3938-remove-keyid-from-keys-endpoints.md: -------------------------------------------------------------------------------- 1 | # MSC3938: Remove deprecated `keyId` parameters from `/keys` endpoints 2 | 3 | The `keyId` path parameter on 4 | [`GET /_matrix/key/v2/server/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2serverkeyid) 5 | and [`GET /_matrix/key/v2/query/{serverName}/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2queryservernamekeyid) 6 | has been deprecated since before the Matrix spec was formally versioned 7 | ([pull request](https://github.com/matrix-org/matrix-spec-proposals/pull/1423)). 8 | 9 | The reason for deprecation was primarily that it was never implemented 10 | correctly: making a request with a `keyId` had the same effect as making a 11 | request without one. 12 | 13 | ## Proposal 14 | 15 | The deprecated `keyId` path parameter should be removed from 16 | [`GET /_matrix/key/v2/server/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2serverkeyid) 17 | and [`GET /_matrix/key/v2/query/{serverName}/{keyId}`](https://spec.matrix.org/v1.5/server-server-api/#get_matrixkeyv2queryservernamekeyid). 18 | 19 | Furthermore, a trailing slash at the end of the endpoint path will no longer be permitted. 20 | 21 | The new endpoints will simply be `GET /_matrix/key/v2/server` and `GET 22 | /_matrix/key/v2/query/{serverName}` respectively, and they will return all 23 | available keys for the given server. 24 | 25 | ## Potential issues 26 | 27 | This is a breaking change: some servers (such as Synapse, until [very 28 | recently](https://github.com/matrix-org/synapse/pull/14525)) may include the 29 | `{keyId}` in outgoing requests. 30 | 31 | 32 | -------------------------------------------------------------------------------- /proposals/3550-allow-403-response-profile-lookup.md: -------------------------------------------------------------------------------- 1 | # MSC3550: Add HTTP 403 to possible profile lookup responses 2 | 3 | # Background 4 | In the current spec, the only response codes listed for [GET /_matrix/client/v3/profile/{userId}](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3profileuserid) 5 | are `200` and `404`. However, some servers may not allow profile lookup over federation, and thus 6 | respond to [GET /_matrix/client/v3/profile/{userId}](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3profileuserid) with an HTTP 403. 7 | 8 | For example, Synapse can be configured to behave in this way by setting: 9 | 10 | ``` 11 | allow_profile_lookup_over_federation=false 12 | ``` 13 | 14 | Thus, this behavior already exists in Synapse, and may cause issues for 15 | clients such as [vector-im/element-web#17269](https://github.com/vector-im/element-web/issues/17269). 16 | 17 | # Proposal 18 | The proposal is to allow HTTP 403 as an option for responding to [GET /_matrix/client/v3/profile/{userId}](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3profileuserid) 19 | requests. Allowing HTTP 403 gives clients more specific information as to why a request has 20 | failed, thus enabling more precise error handling. The 403 would be accompanied by an 21 | `M_FORBIDDEN` error code. 22 | 23 | # Potential Issues 24 | The change to the spec may conflict with other existing server implementations. 25 | 26 | # Alternatives 27 | The spec could remain as-is and Synapse could alter its current behavior and return an HTTP 28 | 404 rather than 403 in this case. 29 | 30 | # Security Considerations 31 | None at this time. 32 | -------------------------------------------------------------------------------- /proposals/2663-errors-nonexistent-push-rules.md: -------------------------------------------------------------------------------- 1 | # MSC2663: Errors for dealing with non-existent push rules 2 | 3 | This MSC proposes that homeservers respond with a HTTP 404 ('Not Found') status 4 | code and an `errcode` of `M_NOT_FOUND` when a client attempts to read or write 5 | the `enabled` status or `actions` of a non-existent push rule. 6 | 7 | ## Background 8 | 9 | The current revision of the Client-Server specification does not make clear what 10 | a homeserver implementation is meant to do when getting or setting the `enabled` 11 | or `actions` properties of a supposed push rule that does not exist. 12 | 13 | ## Motivation 14 | 15 | This change is considered minor and the proposed error code is deemed 16 | unsurprising as it matches the remainder of the specification. 17 | 18 | ## Proposal 19 | 20 | The following endpoints of the Client-Server specification are affected: 21 | 22 | - `GET /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}` 23 | - `DELETE /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}` 24 | - `PUT /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}` 25 | - `GET /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/enabled` 26 | - `PUT /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/enabled` 27 | - `GET /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/actions` 28 | - `PUT /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/actions` 29 | 30 | The affected endpoints will have the following response status code added: 31 | 32 | **Status code 404:** 33 | 34 | The push rule does not exist. 35 | 36 | **Example** 37 | ```json 38 | { 39 | "errcode": "M_NOT_FOUND" 40 | } 41 | ``` 42 | 43 | This error response is to be returned when the push rule represented by 44 | `{scope}/{kind}/{ruleId}` does not exist. 45 | -------------------------------------------------------------------------------- /proposals/3419-guest-state-events.md: -------------------------------------------------------------------------------- 1 | # Guest State Events 2 | 3 | ## Problem 4 | 5 | Currently guest users are not allowed to create arbitrary state events. This is 6 | a problem for [MSC3401](https://github.com/matrix-org/matrix-doc/pull/3401), 7 | where it would be useful for guests to be able to create `m.call.member` events 8 | in order to participate in a call. 9 | 10 | ## Proposal 11 | 12 | Let guests send arbitrary state events much like a normal user. Servers may rate 13 | limit state events from guests much more aggressively to mitigate abuse. 14 | 15 | We also relax the existing requirement that guests are only allowed to send 16 | `m.room.message` events, instead allowing them to send any kind of event 17 | allowed by the room's power level configuration as if they were a normal user. 18 | 19 | ## Security considerations 20 | 21 | The only reason that guests are denied from performing certain operations is to 22 | avoid malicious unauthorised users consuming resources and causing a DoS. In 23 | this instance, sending state events can be quite resource intensive, so if we 24 | didn't have a good use case that needed them it'd be right to veto them. 25 | 26 | Also, by default, users (guest or otherwise) can't send state events, which 27 | further reduces the risk of abuse. Instead, a room intended for guest-capable 28 | voice/video rooms as per MSC3401 would explicitly set a powerlevel to let users 29 | send `m.call.member` events. This MSC would simply make it then permissible 30 | for guests to send as well as non-guests, subject to the powerlevels. 31 | 32 | ## Alternatives 33 | 34 | Rather than using guest access, apps could use shared secret registration to 35 | work around this limitation. However, that feels like a different MSC. 36 | -------------------------------------------------------------------------------- /proposals/2604-login-fallback-device-info.md: -------------------------------------------------------------------------------- 1 | # Parameters for Login Fallback 2 | 3 | The [login fallback](https://matrix.org/docs/spec/client_server/r0.6.1#login-fallback) 4 | API can be used by clients to support logins that they do not recognize. It is 5 | expected to be loaded in a web view and calls a JavaScript function 6 | (`window.onLogin`) when the login process is complete. 7 | 8 | Since the login fallback page does the full login process there is no 9 | opportunity for the application to provide a device ID (to re-authenticate 10 | an expired session in the [case of soft-logout](https://matrix.org/docs/spec/client_server/r0.6.1#soft-logout)) 11 | or an [initial device display name](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-login) 12 | (in the case of an initial login). This causes a few issues: 13 | 14 | * It can make it difficult for a user to manage their sessions (as additional 15 | sessions get created for each soft-logout). 16 | * Cross-signing information gets reset when a new device ID is returned from the 17 | login process. This results in users needing to re-validate their device. 18 | 19 | ## Proposal 20 | 21 | The login fallback page will accept query parameters for non-credential related 22 | parameters of the login endpoint. These will be forwarded by the login fallback 23 | API to the login API throughout the login process. Currently the following 24 | parameters should be accepted: 25 | 26 | * `device_id` 27 | * `initial_device_display_name` 28 | 29 | 30 | ## Potential issues 31 | 32 | There are no backwards compatibility concerns: if a client provides the query 33 | parameters to a homeserver that does not check for them than the current 34 | behavior will occur. 35 | 36 | 37 | ## Security considerations 38 | 39 | None. 40 | -------------------------------------------------------------------------------- /proposals/3820-rooms-v11.md: -------------------------------------------------------------------------------- 1 | # MSC3820: Room Version 11 2 | 3 | A new room version, `11`, is proposed using [room version 10](https://spec.matrix.org/v1.7/rooms/v10/) as a base 4 | and incorporating the following MSCs: 5 | 6 | * [MSC2174](https://github.com/matrix-org/matrix-spec-proposals/pull/2174) - Move `redacts` to sane place 7 | * [MSC2175](https://github.com/matrix-org/matrix-spec-proposals/pull/2175) - Remove `creator` field from `m.room.create` events 8 | * [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) - Updates to redaction rules 9 | * [MSC3989](https://github.com/matrix-org/matrix-spec-proposals/pull/3989) - Redact `origin` on events 10 | * [MSC3821](https://github.com/matrix-org/matrix-spec-proposals/pull/3821) - More updates to redaction rules 11 | 12 | Though other MSCs are capable of being included in this version, they do not have sufficient implementation to be 13 | considered stable enough for v11 rooms. A future room version may still include them. Such examples of ineligible MSCs 14 | are: 15 | 16 | * [MSC2244](https://github.com/matrix-org/matrix-spec-proposals/pull/2244) - Mass redactions 17 | * A number of MSCs which have not yet been accepted (they are not iterated here). 18 | 19 | Room version 11 upon being added to the specification shall be considered stable. No other room versions are affected 20 | by this MSC. 21 | 22 | ## Unstable prefix 23 | 24 | Implementations looking to test v11 before written into the specification should use `org.matrix.msc3820.opt2` 25 | as the room version, treating it as unstable. 26 | 27 | Note: `org.matrix.msc3820.opt1` is from a prior draft of this proposal, consisting of different MSCs than the 28 | current iteration. Implementations should not treat opt1 the same as other unstable-for-MSC3820 versions. 29 | -------------------------------------------------------------------------------- /proposals/2998-rooms-v7.md: -------------------------------------------------------------------------------- 1 | # MSC2998: Room Version 7 2 | 3 | A new room version, `7`, is proposed using [room version 6](https://matrix.org/docs/spec/rooms/v6.html) as a base 4 | and incorporating the following MSCs: 5 | 6 | * [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403) - Add "knock" feature. 7 | 8 | Though other MSCs are capable of being included in this version, they do not have sufficient implementation to be 9 | considered for v7 rooms. A future room version may still include them. 10 | 11 | Room version 7 upon being added to the specification shall be considered stable. No other room versions are affected 12 | by this MSC. Before v7 can enter the specification, MSC2403 needs sufficient review to be eligible to enter the spec 13 | itself. This MSC is reserving the room version for use in broader testing of MSC2403 - this does not make MSC2403 14 | stable for use in most implementations. 15 | 16 | ## A note on spec process 17 | 18 | The spec core team has accepted "knocking" as a concept, and is generally aligned on the ideas proposed by MSC2403. As 19 | such, we're going ahead with reserving a room version number early for some broader testing given MSC2403 is near to the 20 | point of being stable itself. Typically the team would declare a room version number once all the included MSCs are 21 | eligible for becoming stable, however in this case it's ideal to push ahead and reserve the version number. 22 | 23 | If MSC2403 were to be replaced or otherwise be rejected for some reason, we'd ultimately have a gap in room versions 24 | which might look weird but does not necessarily have an impact on the specification: room versions have no associative 25 | ordering, so skipping a perceived sequential version is valid. The sequential versioning is a human ideal, not one of 26 | the spec. 27 | -------------------------------------------------------------------------------- /proposals/1802-standardised-federation-response-format.md: -------------------------------------------------------------------------------- 1 | # Remove the '200' value from some federation responses 2 | 3 | Some responses formats in the federation API specifications use the form `[200, 4 | res]` in which `res` is the JSON object containing the actual response for the 5 | affected endpoints. This was due to a mishap while building synapse's federation 6 | features, and has been left as is because fixing it would induce backward 7 | incompatibility. 8 | 9 | This proposal proposes a backward compatible alternative 10 | 11 | ## Proposal 12 | 13 | Add a new version of the following endpoints under the prefix 14 | `/_matrix/federation/v2`: 15 | 16 | * `PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}` 17 | * `PUT /_matrix/federation/v2/send_leave/{roomId}/{eventId}` 18 | 19 | Which are the exact same endpoints as their equivalents under the `v1` prefix, 20 | except for the response format, which changes from: 21 | 22 | ``` 23 | [ 24 | 200, 25 | res 26 | ] 27 | ``` 28 | 29 | To: 30 | 31 | ``` 32 | res 33 | ``` 34 | 35 | Where `res` is the JSON object containing the response to a request directed at 36 | one of the affected endpoints. 37 | 38 | This proposal doesn't address the `PUT 39 | /_matrix/federation/v1/invite/{roomId}/{eventId}` endpoint since 40 | [MSC1794](https://github.com/matrix-org/matrix-doc/pull/1794) already takes care 41 | of it. 42 | 43 | If a call to any of the `v2` endpoints described in this proposal results in an 44 | unrecognised request exception (i.e. in a response with a 400 or a 404 status 45 | code), then the sending server should retry the request with the `v1` API. 46 | 47 | ## Alternative solutions 48 | 49 | An alternative solution would be to make the change in the `v1` federation API, 50 | but would break backward compatibility, thus would be harder to manage. 51 | -------------------------------------------------------------------------------- /proposals/2610-remove-oauth2-auth-type.md: -------------------------------------------------------------------------------- 1 | # MSC2610: Remove `m.login.oauth2` User-Interactive Authentication type from the specification 2 | 3 | The client-server API specification 4 | [defines](https://matrix.org/docs/spec/client_server/r0.6.1#authentication-types) 5 | a number of "authentication types" for use with the User-Interactive 6 | Authentication protocol. 7 | 8 | Of these, `m.login.oauth2` is underspecified and of no 9 | real use. This MSC proposes removing them. 10 | 11 | ## Proposal 12 | 13 | The definition of 14 | [OAuth2-based](https://matrix.org/docs/spec/client_server/r0.6.1#oauth2-based) 15 | authentication is incomplete. [OAuth2](https://oauth.net/2/) is best considered 16 | as a framework for implementing authentication protocols rather than a protocol 17 | in its own right, and this section says nothing about the grant types, flows 18 | and scopes which a compliant implementation should understand. 19 | 20 | A better candidate for OAuth2-based authentication of matrix clients is via 21 | [OpenID Connect](https://openid.net/connect/), but this has already been 22 | implemented in Matrix via the `m.login.sso` authentication type. 23 | 24 | The `m.login.oauth2` section is therefore unimplementable in its current form, 25 | and redundant. It should be removed from the specification to reduce confusion. 26 | 27 | ## Alternatives 28 | 29 | It would be possible to extend the definition so that it is complete: as 30 | mentioned above, a likely implementation would be based on OpenID 31 | Connect. Matrix clients could then follow the standardised OpenID Connect flow 32 | rather than the matrix-specific `m.login.sso` flow. However, this would require 33 | significant design work, and development in both clients and servers, which 34 | currently feels hard to justify when a working solution exists via 35 | `m.login.sso`. 36 | -------------------------------------------------------------------------------- /proposals/1983-leave-reasons.md: -------------------------------------------------------------------------------- 1 | # Proposal to add reasons for leaving a room 2 | 3 | This proposal intends to solve [#1295](https://github.com/matrix-org/matrix-doc/issues/1295). Currently 4 | people can be kicked from a room for a human-readable reason, but when voluntarily leaving the `reason` 5 | is not considered. 6 | 7 | ## Proposal 8 | 9 | Like when kicking someone, `m.room.member` events with `membership: leave` can have a string `reason`. 10 | The reason is a human-readable string of text which clients should display to users of the room, providing 11 | users with the ability to leave a room for a reason of their choosing. The field is optional. 12 | 13 | Having such a field gives Matrix better compatibility with other networks such as IRC which use the leave 14 | reason to communicate connection problems ("ping timeout", etc). Although Matrix doesn't have a need for a 15 | persistent connection to remain in the room, having a reason can improve the bridge experience. 16 | 17 | An example of a partial leave event with reason would be: 18 | ```json 19 | { 20 | "type": "m.room.member", 21 | "sender": "@travis:t2l.io", 22 | "state_key": "@travis:t2l.io", 23 | "content": { 24 | "membership": "leave", 25 | "reason": "I'm in too many rooms and never talk here" 26 | } 27 | } 28 | ``` 29 | 30 | 31 | ## Potential issues 32 | 33 | There is a chance that quality of communication may deteriorate as a result of adding this field. Arguments 34 | in rooms may result in the leave reason having personal attacks against other room members or rude remarks. 35 | Moderators would be expected to handle these situations for these cases, including redacting the state event 36 | if needed. 37 | 38 | This also opens up an avenue for spam by having a very large reason for leaving. Clients are encouraged to 39 | trim/hide the reason at a reasonable length. 40 | -------------------------------------------------------------------------------- /proposals/3604-rooms-v10.md: -------------------------------------------------------------------------------- 1 | # MSC3604: Room Version 10 2 | 3 | A new room version, `10`, is proposed using [room version 9](https://spec.matrix.org/v1.2/rooms/v9/) as a base 4 | and incorporating the following MSCs: 5 | 6 | * [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667) - Enforcing integer parsing on power levels 7 | * [MSC3787](https://github.com/matrix-org/matrix-spec-proposals/pull/3787) - Allowing knocks to restricted rooms 8 | 9 | Though other MSCs are capable of being included in this version, they do not have sufficient implementation to be 10 | considered stable enough for v10 rooms. A future room version may still include them. Such examples of ineligible MSCs 11 | are: 12 | 13 | * [MSC2244](https://github.com/matrix-org/matrix-spec-proposals/pull/2244) - Mass redactions 14 | * [MSC2174](https://github.com/matrix-org/matrix-spec-proposals/pull/2174) - Move `redacts` to sane place 15 | * [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) - Update to redaction rules 16 | * [MSC2175](https://github.com/matrix-org/matrix-spec-proposals/pull/2175) - Remove extraneous `creator` field 17 | * [MSC2828](https://github.com/matrix-org/matrix-spec-proposals/pull/2828) - Restrict allowed user IDs over federation 18 | * [MSC1229](https://github.com/matrix-org/matrix-spec-proposals/issues/1229) - Mitigating abuse of `depth` 19 | 20 | Room version 10 upon being added to the specification shall be considered stable. No other room versions are affected 21 | by this MSC. 22 | 23 | ## Unstable prefix 24 | 25 | Implementations looking to test v10 before written into the specification should use `org.matrix.msc3604.opt3` 26 | as the room version, treating it as unstable. 27 | 28 | Other prefixes in the wild: 29 | * `org.matrix.msc3604.opt1`: `v9` + MSC2176 (https://github.com/matrix-org/synapse/pull/11662) 30 | * `org.matrix.msc3604.opt2`: `v9` + MSC2176 + MSC3667 (https://github.com/matrix-org/synapse/pull/11885) 31 | -------------------------------------------------------------------------------- /proposals/3786-acl-notifs.md: -------------------------------------------------------------------------------- 1 | # MSC3786: Add a default push rule to ignore `m.room.server_acl` events 2 | 3 | `m.room.server_acl` events allow for expressing which servers can participate in 4 | a room. Room server ACLs aren't something the user should have to worry about, 5 | so these events should not trigger notifications; however right now they *do* 6 | trigger notifications, if the user has the room rule set to `notify` (`All 7 | messages` in Element). 8 | 9 | Additionally, these events are often sent quite frequently during spam attacks, 10 | which causes the users to be overwhelmed by 11 | notifications. (See .) 12 | 13 | Due to these problems, this MSC proposes a new push rule to ignore these events. 14 | The new push rule is analogous to `.m.rule.member_event` (see ), or `.m.rule.reaction` 15 | (from [MSC2153](https://github.com/matrix-org/matrix-spec-proposals/pull/2153) 16 | or [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677)). 17 | 18 | ## Proposal 19 | 20 | A new [default override 21 | rule](https://spec.matrix.org/v1.2/client-server-api/#default-override-rules) is 22 | to be added that ignores `m.room.server_acl` events: 23 | 24 | ```json 25 | { 26 | "rule_id": ".m.rule.room.server_acl", 27 | "default": true, 28 | "enabled": true, 29 | "conditions": [ 30 | { 31 | "kind": "event_match", 32 | "key": "type", 33 | "pattern": "m.room.server_acl" 34 | }, 35 | { 36 | "kind": "event_match", 37 | "key": "state_key", 38 | "pattern": "" 39 | } 40 | ], 41 | "actions": [] 42 | } 43 | ``` 44 | 45 | This new push rule is inserted immediately after `.m.rule.tombstone`. 46 | 47 | ## Unstable prefix 48 | 49 | During development, `.org.matrix.msc3786.rule.room.server_acl` is to be used 50 | instead of `.m.rule.room.server_acl`. 51 | -------------------------------------------------------------------------------- /proposals/4213-remove-server-name.md: -------------------------------------------------------------------------------- 1 | # MSC4213: Remove `server_name` parameter 2 | 3 | [MSC4156] deprecated the `server_name` parameter on [`/_matrix/client/v3/join/{roomIdOrAlias}`] 4 | and [`/_matrix/client/v3/knock/{roomIdOrAlias}`] in favor of a new parameter `via`. This change 5 | shipped in [Matrix v1.12]. In line with the [deprecation policy], the `server_name` parameter 6 | is now eligible for removal from the spec. 7 | 8 | 9 | ## Proposal 10 | 11 | The deprecated `server_name` parameter is removed from [`/_matrix/client/v3/join/{roomIdOrAlias}`] 12 | and [`/_matrix/client/v3/knock/{roomIdOrAlias}`]. 13 | 14 | 15 | ## Potential issues 16 | 17 | None. Servers can continue advertising support for earlier versions of the spec that included 18 | `server_name` via [`/_matrix/client/versions`]. 19 | 20 | As of writing, the following stable implementations of [MSC4156] are known to the author: 21 | 22 | - synapse: https://github.com/element-hq/synapse/pull/17650 23 | - dendrite: https://github.com/matrix-org/dendrite/pull/3438 24 | - matrix-js-sdk: https://github.com/matrix-org/matrix-js-sdk/pull/4381 25 | - ruma: https://github.com/ruma/ruma/pull/1891 26 | - trixnity: https://gitlab.com/trixnity/trixnity/-/merge_requests/478 27 | 28 | 29 | ## Alternatives 30 | 31 | None. 32 | 33 | 34 | ## Security considerations 35 | 36 | None. 37 | 38 | 39 | ## Unstable prefix 40 | 41 | None. 42 | 43 | 44 | ## Dependencies 45 | 46 | None. 47 | 48 | 49 | [`/_matrix/client/v3/join/{roomIdOrAlias}`]: https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3joinroomidoralias 50 | [`/_matrix/client/v3/knock/{roomIdOrAlias}`]: https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3knockroomidoralias 51 | [`/_matrix/client/versions`]: https://spec.matrix.org/v1.10/client-server-api/#get_matrixclientversions 52 | [Matrix v1.12]: https://spec.matrix.org/v1.12/changelog/v1.12/ 53 | [MSC4156]: https://github.com/matrix-org/matrix-spec-proposals/pull/4156 54 | [deprecation policy]: https://spec.matrix.org/v1.12/#deprecation-policy 55 | -------------------------------------------------------------------------------- /proposals/2765-widget-avatars.md: -------------------------------------------------------------------------------- 1 | # MSC2765: Widget avatars 2 | 3 | Currently widgets have a name and title associated with them, though no opportunity for avatars 4 | for a favicon-like experience. This proposal introduces such a concept. 5 | 6 | ## Proposal 7 | 8 | A new optional parameter named `avatar_url` is added to the widget definition. This parameter is 9 | an MXC URI to an image clients can use to associate with the widget, likely alongside the `name` 10 | and/or `title`. 11 | 12 | Widget avatars SHOULD be legible at small sizes, such as 20x20. The MXC URI in the `avatar_url` 13 | should be the source material to allow clients to use the `/thumbnail` API to get a size for their 14 | use case. 15 | 16 | Rendering avatars is optional for clients, much like how clients are not required to use the `name` 17 | or `title` of a widget. 18 | 19 | An example widget would be: 20 | 21 | ```json 22 | { 23 | "creatorUserId": "@alice:example.org", 24 | "data": { 25 | "custom_key": "This is a custom key", 26 | "title": "This is a witty description for the widget" 27 | }, 28 | "id": "20200827_WidgetExample", 29 | "name": "My Cool Widget", 30 | "type": "m.custom", 31 | "url": "https://example.org/my/widget.html?roomId=$matrix_room_id", 32 | "waitForIframeLoad": true, 33 | "avatar_url": "mxc://example.org/abc123" 34 | } 35 | ``` 36 | 37 | ## Alternatives 38 | 39 | We could define a whole structured system for different thumbnail sizes, though we have a thumbnail 40 | API which can be used to request whatever size is needed by the client. 41 | 42 | ## Security considerations 43 | 44 | Widget avatars could be non-images. Clients should use the thumbnail API to encourage error responses 45 | from the server when a widget avatar is a non-image. 46 | 47 | ## Unstable prefix 48 | 49 | While this MSC is not in a released version of the specification, clients should use an alternative 50 | event type for widgets or use `org.matrix.msc2765.avatar_url` when using `m.widget` or `m.widgets` 51 | as an event type. 52 | -------------------------------------------------------------------------------- /proposals/4178-threepid-medium-not-supported.md: -------------------------------------------------------------------------------- 1 | # MSC4178: Error codes for requestToken 2 | 3 | There are a number of ways that sending a token to validate a third party identifier can go wrong. 4 | The requestToken API, however, has a very limited number of error codes that it can return. 5 | 6 | Firstly, homeservers may not always support adding email addresses or phone numbers to a user's account, 7 | however, there is no error code to signal this situation. Synapse currently returns `M_UNKNOWN` 8 | which leads to bad, untranslatable error messages. 9 | 10 | Secondly, the supplied third party identifier may be invalid. 11 | 12 | ## Proposal 13 | 14 | Firstly, Add the `M_THREEPID_MEDIUM_NOT_SUPPORTED` code to be returned by both 15 | [`POST /account/3pid/email/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidemailrequesttoken) 16 | and 17 | [`POST /account/3pid/msisdn/requestToken`](https://spec.matrix.org/v1.11/client-server-api/#post_matrixclientv3account3pidmsisdnrequesttoken), 18 | defined to mean that the homeserver does not support adding a third party identifier of that medium. 19 | 20 | Secondly, allow these endpoints to also return `M_INVALID_PARAM`, to indicate that the third party address 21 | was not valid for that medium (eg. not a valid phone number). 22 | 23 | For both of these codes, HTTP status code 400 should be used. 24 | 25 | ## Potential issues 26 | 27 | None foreseen. 28 | 29 | ## Alternatives 30 | 31 | A better UX would be for servers to advertise what third party identifiers they support adding so that clients can 32 | inform users before they try to do so. This should be in addition rather than as alternative though: the clearest 33 | possible API will come from having both. 34 | 35 | ## Security considerations 36 | 37 | None foreseen. 38 | 39 | ## Unstable prefix 40 | 41 | This is sufficiently simple that proving it on a large scale is unnecessary. The code should not be used in the open 42 | before the MSC has been accepted. 43 | 44 | ## Dependencies 45 | 46 | None 47 | -------------------------------------------------------------------------------- /proposals/1466-soft-logout.md: -------------------------------------------------------------------------------- 1 | # Soft Remote Logout Proposal 2 | 3 | ## Motivation 4 | 5 | Currently when a user logs out of riot, the app will destroy things like 6 | encryption keys. If the logout was done by the user in local app then it will 7 | have first prompted the user to export the encryption keys. However, when the 8 | app is logged out remotely (i.e. it received a 401 from the server) there is no 9 | opportunity to ask the user to backup the keys, resulting in those keys being 10 | lost. 11 | 12 | While this behaviour is useful in many circumstances, e.g. remote logging out a 13 | stolen/lost device, it also means that the server shouldn't automatically 14 | log out devices, to avoid users losing encryption keys. 15 | 16 | 17 | ## Proposal 18 | 19 | A new parameter is added to the JSON body of 401 responses, called 20 | `soft_logout`. This is a boolean flag (defaulting to `false`) that signals to 21 | the client whether it should keep local data and simply prompt to reauth (when 22 | `true`) or to destroy the current data like it does today (when `false`). 23 | 24 | The major disadvantage with this approach is that once the client is logged 25 | out, the user can no longer remotely cause the client to destroy the local 26 | data. However, this is not substantially different from today where the app has 27 | to be opened to receive remote logout requests (via 401), as it allows 28 | attackers to get at encryption keys even after remote logout if they simply 29 | avoid opening the app. 30 | 31 | 32 | ### Example Client UX 33 | 34 | When handling a soft logout the client could show a "re-login" dialogue, rather 35 | than back to the default logged out screen. This new dialogue would then have 36 | several options including logging out, exporting keys and logging out fully. 37 | 38 | 39 | ## Alternatives 40 | 41 | One alternative is to force the user to enter a password for backing up keys 42 | when they enter the app, and then have the app keep secure backups of they 43 | keys. This then means its safer to not delete the secure backups when the app 44 | is logged out remotely. 45 | 46 | -------------------------------------------------------------------------------- /proposals/1704-matrix.to-permalinks.md: -------------------------------------------------------------------------------- 1 | # matrix.to permalink navigation 2 | 3 | Currently Matrix uses matrix.to URIs to reference rooms and other entities in a 4 | permanent manner. With just a room ID, users can't get into rooms if their server 5 | is not already aware of the room. This makes permalinks to rooms or events difficult 6 | as the user won't actually be able to join. A matrix.to link generated using a 7 | room's alias is not a permanent link due to aliases being transferable. 8 | 9 | In lieu of an improved way to reference entities permanently in Matrix, a new parameter 10 | is to be added to matrix.to URIs to assist clients and servers receiving permanent links 11 | in joining the room. 12 | 13 | For reference, existing permalinks look like this: 14 | 15 | ``` 16 | https://matrix.to/#/!somewhere:example.org 17 | https://matrix.to/#/!somewhere:example.org/$something:example.org 18 | ``` 19 | 20 | By adding a new parameter to the end, receivers can more easily join the room: 21 | 22 | ``` 23 | https://matrix.to/#/!somewhere:example.org?via=example-1.org&via=example-2.org 24 | https://matrix.to/#/!somewhere:example.org/$something:example.org?via=example-1.org&via=example-2.org 25 | ``` 26 | 27 | Clients can pass the servers directly to `/join` in the form of `server_name` 28 | parameters. 29 | 30 | When generating the permalinks, clients should pick servers that have a reasonably 31 | high chance of being in the room in the distant future. The current recommendation 32 | is to pick up to 3 unique servers where the first one is that of the user with the 33 | highest power level in the room, provided that power level is 50 or higher. The other 34 | 2 servers should be the most popular servers in the room based on the number of joined 35 | users. This same heuristic should apply to the first server if no user meets the power 36 | level requirements. Servers blocked by server ACLs should not be picked because they 37 | are unlikely to continue being residents of the room. Similarly, IP addresses should 38 | not be picked because they cannot be redirected to another location like domain names 39 | can, making them a higher risk option. 40 | -------------------------------------------------------------------------------- /proposals/3818-copy-room-type-on-upgrade.md: -------------------------------------------------------------------------------- 1 | # MSC3818: Copy room type on upgrade 2 | 3 | Unless the room upgrade API specifies that room type must be copied over, clients cannot rely on 4 | rooms staying the same type leading to trouble. 5 | 6 | 7 | ## Proposal 8 | 9 | This MSC proposes that the room upgrade API MUST copy the [room type](https://spec.matrix.org/v1.2/client-server-api/#types) 10 | over to the new room. Otherwise clients cannot trust that to happen and [Spaces](https://spec.matrix.org/v1.2/client-server-api/#spaces) 11 | or [MSC3588](https://github.com/matrix-org/matrix-spec-proposals/pull/3588) Story rooms may incorrectly become 12 | normal rooms breaking user-experience. 13 | 14 | The Spec currently specifies this in [section 11.32.3. server behaviour](https://spec.matrix.org/v1.2/client-server-api/#server-behaviour-16): 15 | 16 | > 2. Creates a replacement room with a `m.room.create` event containing a `predecessor` field and the applicable `room_version`. 17 | 18 | It becomes: 19 | 20 | > 2. Creates a replacement room with a `m.room.create` event containing a `predecessor` field, a 21 | > `type` field set to what it was in the previous room (if it was set), and the applicable `room_version`. 22 | 23 | 24 | ## Potential issues 25 | 26 | Some room types such as Spaces also require copying over state events as a part of the update progress, 27 | in case of Spaces, `m.space.child` events. However as that can be changed later and done by the client, 28 | it's out of scope for this MSC. 29 | 30 | ## Alternatives 31 | 32 | A suggested alternative is having every room type specify their own update process if they use other 33 | room types. However this would complicate the MSC process with even simple client-side proposals 34 | requiring also a server-side implementation. This could also result in room types dependent on a 35 | particular server software or discourage using Matrix for a smaller project where an MSC wasn't 36 | otherwise consider necessary. 37 | 38 | ## Security considerations 39 | 40 | Non-applicable. 41 | 42 | ## Unstable prefix 43 | 44 | Non-applicable. 45 | 46 | ## Dependencies 47 | 48 | Non-applicable. 49 | -------------------------------------------------------------------------------- /proposals/2611-remove-login-auth-type.md: -------------------------------------------------------------------------------- 1 | # MSC2611: Remove `m.login.token` User-Interactive Authentication type from the specification 2 | 3 | The client-server API specification 4 | [defines](https://matrix.org/docs/spec/client_server/r0.6.1#authentication-types) 5 | a number of "authentication types" for use with the User-Interactive 6 | Authentication protocol. 7 | 8 | Of these, `m.login.token` is unused and confusing. This MSC proposes removing it. 9 | 10 | ## Proposal 11 | 12 | The definition of 13 | [token-based](https://matrix.org/docs/spec/client_server/r0.6.1#token-based) 14 | authentication is unclear about how this authentication type should be used. It 15 | suggests "via some external service, such as email or SMS", but in practice 16 | those validation mechanisms have their own token-submission mechanisms (for 17 | example, the 18 | `submit_url` field of the responses from 19 | [`/account/password/email/requestToken`](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-account-password-email-requesttoken) 20 | and 21 | [`/account/password/msisdn/requestToken`](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-account-password-msisdn-requesttoken) 22 | respectively). Additionally, the specification requires that "the server must 23 | encode the user ID in the token", which seems at odds with any token which can 24 | be sent to a user over SMS. 25 | 26 | Additional confusion stems from the presence of an `m.login.token` [login 27 | type](https://matrix.org/docs/spec/client_server/r0.6.1#login), which is used 28 | quite differently: it forms part of the single-sign-on login flow. For clarity: 29 | this proposal does not suggest making any changes to the `m.login.token` login 30 | type. 31 | 32 | In practice, we are not aware of any implementations of the `m.login.token` 33 | authentication type, and the inconsistency adds unnecessary confusion to the 34 | specification. 35 | 36 | ## Potential Issues 37 | 38 | It's possible that somebody has found a use for this mechanism. However, that 39 | would necessarily entail some custom development of clients and servers, so is 40 | not materially affected by the removal from the specification. 41 | -------------------------------------------------------------------------------- /proposals/images/1730-seq-diagram.txt: -------------------------------------------------------------------------------- 1 | # https://sequencediagram.org/ 2 | 3 | participantspacing equal 4 | participant Client 5 | participant matrix.ac.cdl 6 | participant SAML2 SSO system 7 | participant matrix.eng.ac.cdl 8 | 9 | activate Client 10 | 11 | Client->matrix.ac.cdl:""GET /_matrix/client/r0/login"" 12 | activate matrix.ac.cdl 13 | Client<--matrix.ac.cdl:"""type": "m.login.sso""" 14 | deactivate matrix.ac.cdl 15 | # Start SSO flow: displayed in browser for web clients, or via fallback auth in embeddedbrowser for others 16 | Client->matrix.ac.cdl:""GET /_matrix/client/r0/login/sso/redirect\n--?redirectUrl=--"" 17 | activate matrix.ac.cdl 18 | matrix.ac.cdl->matrix.ac.cdl:Generate SAML request 19 | Client<--matrix.ac.cdl:302 to SSO system 20 | deactivate matrix.ac.cdl 21 | Client->SAML2 SSO system:""GET /single-sign-on\n--?SAMLRequest=&RelayState=--"" 22 | activate SAML2 SSO system 23 | Client<-->SAML2 SSO system: auth credentials 24 | SAML2 SSO system-->Client:auto-submitting HTML form including SAML Response 25 | deactivate SAML2 SSO system 26 | Client->matrix.ac.cdl:""POST /SAML2\n--SAMLResponse=\nRelayState= 27 | activate matrix.ac.cdl 28 | matrix.ac.cdl->matrix.ac.cdl:map user to HS 29 | Client<--matrix.ac.cdl:auto-submitting HTML form for target HS 30 | deactivate matrix.ac.cdl 31 | Client->matrix.eng.ac.cdl:""POST /SAML2\n--SAMLResponse=\nRelayState= 32 | activate matrix.eng.ac.cdl 33 | Client<--matrix.eng.ac.cdl:302 to clienturl with\n""--?loginToken= 34 | deactivate matrix.eng.ac.cdl 35 | Client->matrix.ac.cdl:""POST /_matrix/client/r0/login\n--{"type": "m.login.token","token": ""} 36 | activate matrix.ac.cdl 37 | matrix.ac.cdl->matrix.eng.ac.cdl:""POST /_matrix/client/r0/login\n--{"type": "m.login.token", "token": ""} 38 | activate matrix.eng.ac.cdl 39 | matrix.ac.cdl<--matrix.eng.ac.cdl:""--{"user_id": "@user:eng.ac.cdl", "access_token": "abc123",\n "well_known": {"m.homeserver": "..."}} 40 | deactivate matrix.eng.ac.cdl 41 | Client<--matrix.ac.cdl:""--{"user_id": "@user:eng.ac.cdl",\n "access_token": "abc123",\n "well-known": {"m.homeserver": "..."}} 42 | deactivate matrix.ac.cdl 43 | Client<-#0000FF>matrix.eng.ac.cdl: Matrix 44 | -------------------------------------------------------------------------------- /proposals/3283-enable_set_displayname-capabilities.md: -------------------------------------------------------------------------------- 1 | # MSC3283: Expose enable_set_displayname, enable_set_avatar_url and enable_3pid_changes in capabilities response 2 | 3 | Some home servers like [Synapse](https://github.com/matrix-org/synapse/blob/756fd513dfaebddd28bf783eafa95b4505ce8745/docs/sample_config.yaml#L1207) 4 | can be configured to `enable_set_displayname: false`, `enable_set_avatar_url: false` or `enable_3pid_changes: false`. 5 | To enable clients to handle that gracefully in the UI this setting should be exposed. 6 | 7 | ## Proposal 8 | 9 | The `/_matrix/client/r0/capabilities` endpoint should be decorated to provide more information on capabilities. 10 | ```jsonc 11 | { 12 | "capabilities": { 13 | "m.set_displayname": { "enabled": false }, 14 | "m.set_avatar_url": { "enabled": false }, 15 | "m.3pid_changes": { "enabled": false }, 16 | "m.room_versions": {...}, 17 | } 18 | } 19 | ``` 20 | As part of this MSC, a capability for each setting will be added that exposes the server setting: 21 | - `m.set_displayname` 22 | 23 | Whether users are allowed to change their displayname after it has been initially set. 24 | Useful when provisioning users based on the contents of a third-party directory. 25 | 26 | - `m.set_avatar_url` 27 | 28 | Whether users are allowed to change their avatar after it has been initially set. 29 | Useful when provisioning users based on the contents of a third-party directory. 30 | 31 | - `m.3pid_changes` 32 | 33 | Whether users can change the 3PIDs associated with their accounts 34 | (email address and msisdn). 35 | Useful when provisioning users based on the contents of a third-party directory. 36 | 37 | ## Client recommendations 38 | When presenting profile settings, clients should use capabilities in order to display the correct UI. 39 | 40 | Capability should always be present. 41 | Servers should always send these capabilities. If they aren't (because the server does not support 42 | a new enough spec version or for any other reason), clients should behave as if they were present and set to true. 43 | 44 | ## Unstable prefix 45 | 46 | While this MSC is not considered stable, implementations should use `org.matrix.msc3283.` in place of `m.` throughout this proposal. 47 | -------------------------------------------------------------------------------- /proposals/2414-optional-content-reporting-reason.md: -------------------------------------------------------------------------------- 1 | # MSC2414: Make `reason` and `score` optional for reporting content 2 | 3 | ## Proposal 4 | 5 | On the [report content endpoint](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-rooms-roomid-report-eventid) 6 | we remove the `required` flag for both the `reason` and `score` parameters, as 7 | well as the "may be blank" clause in the description of `reason`. 8 | 9 | ## Rationale 10 | 11 | ### `reason` Parameter 12 | 13 | Currently, the spec says that the `reason` parameter on the content reporting 14 | endpoint is required, but also says that the string "may be blank." This 15 | seems to be a contradiction. 16 | 17 | Note that the kicking and banning endpoints already have optional `reason` 18 | parameters. The other membership endpoints mentioned in 19 | [#2367][membership-endpoints] will also add optional `reason` parameters, 20 | so it would be more more consistent with the rest of the spec to make this 21 | optional as well. 22 | 23 | ### `score` Parameter 24 | 25 | The spec also requires the `score` parameter, but its usefulness is limited. 26 | Offensiveness is difficult to measure and is likely not going to be applied 27 | consistently across several rooms. Because of this ambiguity, it seems, many 28 | clients [simply hard-code the integer value][hard-code]. 29 | 30 | To make this useful, for example, room administrators would need a way to map more 31 | specific values to the integer range and perhaps even instruct the client to 32 | display those mappings to the user. That may be possible to do in a closed 33 | client/homeserver implementation, but not generally across the Matrix protocol. 34 | 35 | Making `score` optional would enable this feature to be used in specific contexts 36 | while not forcing clients to support the ambiguity it brings. 37 | 38 | ## Backwards Compatibility 39 | 40 | Since servers currently expect these fields to be sent by all clients, making 41 | them optional is a breaking change. Clients should check the spec versions 42 | the homeserver supports to detect this change. 43 | 44 | [membership-endpoints]: https://github.com/matrix-org/matrix-doc/pull/2367 45 | [hard-code]: https://github.com/matrix-org/matrix-react-sdk/pull/3290/files#diff-551ca16d6a8ffb96888b337b5246402dR66 46 | -------------------------------------------------------------------------------- /proposals/2076-enforce-validity-periods.md: -------------------------------------------------------------------------------- 1 | # MSC2076: Enforce key-validity periods when validating event signatures 2 | 3 | ## Background 4 | 5 | The [Federation API 6 | specification](https://matrix.org/docs/spec/server_server/r0.1.1.html#validating-hashes-and-signatures-on-received-events) 7 | specifies that events should be validated via the signature verification 8 | algorithm, but does not specify how the keys for that check should be obtained 9 | and validated. 10 | 11 | In practice, the implementation has been as follows. The receiving server 12 | first requests a copy of the key via the [`GET /_matrix/key/v2/server/` 13 | API](https://matrix.org/docs/spec/server_server/r0.1.1.html#get-matrix-key-v2-server-keyid) 14 | directly from the server which created the signature, or via the [`POST 15 | /_matrix/key/v2/query` API](https://matrix.org/docs/spec/server_server/r0.1.1.html#post-matrix-key-v2-query) 16 | from a trusted key server. Once such a key is obtained, it is then cached 17 | forever. No check is made on the `valid_until_ts` field, and 18 | `minimum_valid_until_ts` is set to zero for calls to `POST 19 | /_matrix/key/v2/query`. 20 | 21 | This is highly unsatisfactory, as it means that, should a key be compromised, 22 | then an attacker can spoof arbitrary events claiming to be from the compromised 23 | server forever, since there is no revocation mechanism. 24 | 25 | ## Proposal 26 | 27 | This MSC proposes to enforce the `valid_until_ts` property when validating 28 | event signatures. In particular, the server must ensure that it has a copy of 29 | the key with a `valid_until_ts` at least as large as the `origin_server_ts` of 30 | the event being validated. If it does not have such a copy, it must try to 31 | obtain one via the `GET /_matrix/key/v2/server/` or `POST 32 | /_matrix/key/v2/query` APIs. For the latter, it must set 33 | `minimum_valid_until_ts` to prompt the notary server to attempt to refresh the 34 | key if appropriate. 35 | 36 | Since this changes the rules used to validate events, it will be introduced 37 | with a new room version. This will reduce the risk of divergence between 38 | servers in a room due to some servers accepting events which others reject. 39 | 40 | This MSC also proposes that the current situation - where `valid_until_ts` is 41 | ignored - be formalised for the existing room versions v1-v4, rather than be 42 | left as implementation-specific behaviour. 43 | -------------------------------------------------------------------------------- /proposals/3821-update-redaction-rules-again.md: -------------------------------------------------------------------------------- 1 | # MSC3821: Update redaction rules, again 2 | 3 | [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) aimed to fix inconsistencies 4 | with the [redaction algorithm](https://spec.matrix.org/v1.6/rooms/v10/#redactions) where server-side 5 | event auth required properties to exist that were being removed. While MSC2176 fixed a number of cases, 6 | one was unfortunately missed. 7 | 8 | This MSC aims to fix that missing case, originally identified long ago by [synapse#1831](https://github.com/matrix-org/synapse/issues/1831). 9 | 10 | ## Proposal 11 | 12 | *Note*: It is recommended to read [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) 13 | before this proposal as MSC2176 contains a lot of backing context. 14 | 15 | In a future room version, the following changes are made to the [redaction algorithm](https://spec.matrix.org/v1.6/rooms/v10/#redactions). 16 | Note that this requires a new room version because changing the redaction algorithm changes how 17 | [event IDs](https://spec.matrix.org/v1.6/rooms/v10/#event-ids) are calculated, as they are 18 | [reference hashes](https://spec.matrix.org/v1.6/server-server-api/#calculating-the-reference-hash-for-an-event) 19 | which redact the event during calculation. 20 | 21 | * [`m.room.member`](https://spec.matrix.org/v1.6/client-server-api/#mroommember) events preserve a portion 22 | of `third_party_invite` under `content`, if present. Those properties being: 23 | 24 | * `signed`: the block is required for the server to validate the event, however excess adjacent properties 25 | such as `display_name` are not important. 26 | 27 | Clients should note that because `display_name` is *not* preserved during redaction they might need to change 28 | how that event is rendered/presented to users. For example, when rendering such a redacted event the client 29 | might show it as "Bob accepted a third party invite". 30 | 31 | ## Unstable prefix 32 | 33 | Implementations looking to test these changes before adopted into a stable room version should use 34 | `org.matrix.msc3821.opt1` as the room version, using **v9** as a base and treating it as unstable. 35 | 36 | **History**: This MSC was originally written before room version 10 existed. Implementations wishing to use 37 | v10 as a base instead of v9 should use `org.matrix.msc3821.opt1.v10` as the room version instead. 38 | -------------------------------------------------------------------------------- /proposals/4163-make-acls-apply-to-edus.md: -------------------------------------------------------------------------------- 1 | # MSC4163: Make ACLs apply to EDUs 2 | 3 | [Access Control Lists](https://spec.matrix.org/v1.11/client-server-api/#server-access-control-lists-acls-for-rooms) 4 | (also known as ACLs) are used to prevent other servers from participating in a room at a federation level, 5 | covering many federation API endpoints, including 6 | [`/send`](https://spec.matrix.org/v1.11/server-server-api/#put_matrixfederationv1sendtxnid). However, while ACLs 7 | are applied on a per-PDU basis on this endpoint, they are not applied to EDUs at all. Considering that some EDUs 8 | are specific to certain rooms (e.g. read receipts & typing indicators), it makes sense to apply ACLs to them as well. 9 | 10 | 11 | ## Proposal 12 | 13 | All EDUs which are local to a specific room MUST have ACLs applied to them. This means that for the EDUs currently 14 | in the spec, ACLs would only apply to receipts and typing notifications. Examples of how ACLs should be enforced 15 | at the point of receiving a transaction for those two types of EDUs are as follows: 16 | - For 17 | [typing notifications (`m.typing`)](https://spec.matrix.org/v1.11/server-server-api/#typing-notifications), 18 | the `room_id` field inside `content` should be checked, with the typing notification ignored if the `origin` 19 | of the request is a server which is forbidden by the room's ACL. Ignoring the typing notification means that the EDU 20 | MUST be dropped upon receipt. 21 | - For [read receipts (`m.receipt`)](https://spec.matrix.org/v1.11/server-server-api/#receipts), all receipts 22 | inside a `room_id` inside `content` should be ignored if the `origin` of the request is forbidden by the 23 | room's ACL. 24 | 25 | ## Potential issues 26 | 27 | None considered. 28 | 29 | ## Alternatives 30 | 31 | Leave things as-is, which wouldn't be that big of a deal when you consider that this would only apply 32 | to typing notifications and read receipts currently, which don't allow for very significant disruption inside 33 | a room. However, as ACLs are meant to prevent certain servers from participating in a room at all, it makes 34 | sense to apply ACLs to EDUs which are local to certain rooms, as they are a form of participation. 35 | 36 | ## Security considerations 37 | 38 | None considered. 39 | 40 | ## Unstable prefix 41 | 42 | None required, as no new fields or endpoints are added. 43 | 44 | ## Dependencies 45 | 46 | None. 47 | -------------------------------------------------------------------------------- /proposals/4138-update-cors-methods.md: -------------------------------------------------------------------------------- 1 | # MSC4138: Update allowed HTTP methods in CORS responses 2 | 3 | The [specification](https://spec.matrix.org/v1.10/client-server-api/#web-browser-clients) suggests 4 | that servers allow a limited subset of the available [HTTP methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) 5 | available in [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) responses. However, it's 6 | reasonable to expect the specification to use other methods in the future or as part of feature 7 | detection. To permit these use cases early, this MSC proposes adding a few more allowable values to 8 | the `Access-Control-Allow-Methods` header. 9 | 10 | ## Proposal 11 | 12 | The [`Access-Control-Allow-Methods` header's recommended value](https://spec.matrix.org/v1.10/client-server-api/#web-browser-clients) 13 | is updated to note that the HTTP methods described cover existing specified endpoints. Servers which 14 | support additional endpoints or methods should add those methods as well. The specification will be 15 | updated whenever a new method is supported by an endpoint. 16 | 17 | Examples of possible future-use methods include: 18 | 19 | * `PATCH` - A plausibly useful HTTP method for future use. 20 | * `HEAD` - Similar to `PATCH`, `HEAD` is plausibly useful for feature detection and cases like 21 | [MSC4120](https://github.com/matrix-org/matrix-spec-proposals/pull/4120). 22 | 23 | The following methods are *not* included because they don't have foreseeable use in Matrix: 24 | 25 | * `CONNECT` 26 | * `TRACE` 27 | 28 | ## Potential issues 29 | 30 | None anticipated. 31 | 32 | ## Alternatives 33 | 34 | No significant alternatives. 35 | 36 | ## Security considerations 37 | 38 | CORS is meant to help ensure requests made by the client are properly scoped in the client. If the 39 | client wishes to use an HTTP method not allowed by the server, the web browser will mask the 40 | response with an error before the application can inspect it. Therefore, to increase future 41 | compatibility, we append a few useful HTTP methods while still excluding ones which are (currently) 42 | nonsensical. 43 | 44 | ## Unstable prefix 45 | 46 | This proposal cannot have an unstable prefix due to the nature of CORS. Servers are already able to 47 | go off-spec and serve different headers because the spec is merely a recommendation. 48 | 49 | ## Dependencies 50 | 51 | This proposal has no dependencies. 52 | -------------------------------------------------------------------------------- /proposals/2457-password-modification-invalidating-devices.md: -------------------------------------------------------------------------------- 1 | # Invalidating devices during password modification 2 | 3 | There are multiple use cases for why a user might want to modify their password: 4 | 5 | * Adopting a password manager (to use a unique password or more secure password). 6 | * Password rotation. 7 | * Re-secure a compromised account. 8 | * ... probably tons of others ... 9 | 10 | These can be summarized into two groups: 11 | 12 | 1. "My account has been compromised and I need to re-secure it." 13 | 2. "I just want to change my password." 14 | 15 | The [current Matrix specification](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-account-password) 16 | does not provide a way to differentiate between these use cases. It currently 17 | specifies behavior that fits well into the first use-case above: that the 18 | sessions except the current session should be revoked. 19 | 20 | It is reasonable for a client to want to specify this behavior to offer two 21 | different workflows: 22 | 23 | 1. Modify a password and log all other devices out (for use when an account has 24 | been compromised). 25 | 2. Modify a password and do not touch any session data (for use in a 26 | non-malicious situations). 27 | 28 | Alternately a client may default to whichever workflow is best for their users. 29 | 30 | ## Proposal 31 | 32 | An optional field is added to the JSON body of the [password reset endpoint](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-account-password) 33 | called `logout_devices`. This is a boolean flag (defaulting to `true`) that 34 | signals to whether other devices and sessions should be invalidated after 35 | modifying the password. 36 | 37 | ## Potential issues 38 | 39 | The specification states: 40 | 41 | > The homeserver SHOULD NOT revoke the access token provided in the request, 42 | > however all other access tokens for the user should be revoked if the request 43 | > succeeds. 44 | 45 | Defaulting `logout_devices` to `true` should be backwards compatible. 46 | 47 | ## Alternatives 48 | 49 | A new endpoint could be provided in a future version of the specification that 50 | supports an additional field (as described above). 51 | 52 | ## Security considerations 53 | 54 | By defaulting to invalidating devices and sessions the security considerations 55 | of this endpoint should remain intact. A client will need to be modified to 56 | choose to keep other devices active. 57 | -------------------------------------------------------------------------------- /proposals/3966-exact-event-property-contains-push-condition.md: -------------------------------------------------------------------------------- 1 | # MSC3966: `event_property_contains` push rule condition 2 | 3 | [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952): 4 | Intentional mentions requires a way for a push rule condition to search 5 | for a value in a JSON array of values. This proposes implementing it in a 6 | generic fashion for re-use with other push rules. 7 | 8 | ## Proposal 9 | 10 | A new push rule condition `event_property_contains` is added which acts like 11 | [`event_match`](https://spec.matrix.org/v1.5/client-server-api/#conditions-1), 12 | but searches an array for an exact value. The values must match exactly and be a 13 | non-compound JSON type allowed by [canonical JSON](https://spec.matrix.org/v1.5/appendices/#canonical-json): 14 | i.e. strings, `null`, `true`, `false` and integers. 15 | 16 | An example condition would look like: 17 | 18 | ```json 19 | { 20 | "kind": "event_property_contains", 21 | "key": "content.my_array", 22 | "value": "foo" 23 | } 24 | ``` 25 | 26 | This would match an event with content: 27 | 28 | ```json 29 | { 30 | "content": { 31 | "my_array": ["foo", true] 32 | } 33 | } 34 | ``` 35 | 36 | And it would not match if `my_array` was empty or did not exist. 37 | 38 | ## Potential issues 39 | 40 | None foreseen. 41 | 42 | ## Alternatives 43 | 44 | [MSC3887](https://github.com/matrix-org/matrix-spec-proposals/pull/3887) is an 45 | unfinished alternative which suggests allowing [`event_match`](https://spec.matrix.org/v1.5/client-server-api/#conditions-1) 46 | to search in arrays without other changes. 47 | 48 | ## Security considerations 49 | 50 | It is possible for the event content to contain very large arrays (the 51 | [maximum event size](https://spec.matrix.org/v1.5/client-server-api/#size-limits) 52 | is 65,536 bytes, if most of that contains an array of empty strings you get 53 | somewhere around 20,000 entries). Iterating through arrays of this size should 54 | not be a problem for modern computers, especially since the push rule searches 55 | for *exact* matches. 56 | 57 | ## Unstable prefix 58 | 59 | During development `org.matrix.msc3966.exact_event_property_contains` shall be 60 | used in place of `event_property_contains`. 61 | 62 | ## Dependencies 63 | 64 | This MSC has similar semantics to [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) 65 | (and the implementation builds on that), but it does not strictly depend on it. 66 | -------------------------------------------------------------------------------- /proposals/2422-allow-color-attribute-on-font-tag.md: -------------------------------------------------------------------------------- 1 | # MSC2422: Allow `color` as attribute for `` in messages 2 | 3 | Currently the spec recommends that you to use `data-mx-color` instead of the standard 4 | `color` html attribute for the `` tag. This is probably done to make it 5 | consistent with ``, where you may not want to allow a generic style tag for. 6 | 7 | On the other hand the /rainbow command on almost every client just uses the 8 | `color` attribute of the `` tag. While some clients support 9 | `data-mx-color` (i.e. Riot Web), most clients don't. Most clients support 10 | rendering `color` however. 11 | 12 | It would probably be for the best to allow or even prefer `color` on the 13 | `` tag. 14 | 15 | ## Proposal 16 | 17 | Add the `color` attribute to the allowed attributes of `` in section 18 | 13.2.1.7. No changes to the allowable values from the HTML spec are made here. 19 | 20 | ## Potential issues 21 | 22 | - We now have a redundant attribute in the spec. While it matches what the 23 | clients currently do, it may be better to fix each client instead. 24 | - Clients may not sanitize the color attribute and will let other color values 25 | through, increasing compatibility issues again. 26 | - Clients may never support the data-mx-* attributes now. 27 | - Old messages could loose their color 28 | - This proposal doesn't touch span at all, maybe it should? 29 | 30 | ## Alternatives 31 | 32 | - fix the clients 33 | -> This currently seems not feasible. Multiple clients started using color first (i.e. RiotX, Gomuks) and if it isn't spelled out explicitly in the spec, this will probably continue. 34 | - remove the `data-mx-color` and `data-mx-bg-color` attributes entirely, leaving us just with `color` for `` 35 | -> This would break old messages and can be done independently of this proposal at a later date, if it is deemed useful. 36 | - Add a section to tell the clients to prefer `color` over `mx-data-color` 37 | -> I don't really know, why mx-data-* was chosen, but I assume there was a reason, so I don't want to change that. 38 | - Spec an entirely different format for messages (that would probably not make this proposal obsolete) 39 | -> This wouldn't fix the issue, where some client may choose to remove the color tag, since it is discouraged in the spec. Migration would probably also take a while, so this proposal is a quick solution, that doesn't prevent other solutions at a later date. 40 | -------------------------------------------------------------------------------- /proposals/3904-room-version-10-as-a-default.md: -------------------------------------------------------------------------------- 1 | # MSC3904: Room version 10 as a default 2 | 3 | Enough time has passed to allow the public federation to upgrade their servers to support room 4 | version 10, though with some caveats (see "potential issues"). This proposal aims to make v10 the 5 | default room version. 6 | 7 | ## Proposal 8 | 9 | The specification adopts v10 as the suggested default room version, making no changes to the stability 10 | of any room versions. As of writing, v9 is currently the suggested room version. 11 | 12 | Room version 10 is currently published here: https://spec.matrix.org/v1.4/rooms/v10/ 13 | 14 | ## Potential issues 15 | 16 | Servers will be encouraged to update their config/internal defaults to use v10 instead of v9. This 17 | is considered a good problem to have. 18 | 19 | Note that servers are not required to honour the default room version due to it being a suggestion 20 | in the specification, however they might fall behind as other servers set their defaults accordingly. 21 | 22 | Some server implementations, like Synapse, support configurable default room versions: servers which 23 | have set this flag will not necessarily be affected by this change. 24 | 25 | As of writing (2022-10-09) Synapse and Dendrite both have supported Room version 10 since 2022-08-02 26 | when Synapse in 1.64.0 added its support. Dendrite added its support back in 2022-06-01. This leaves 27 | Conduit as the only major implementation to lack v10 support. 28 | 29 | Conduit status for v10 is not implemented as of (2022-10-09) but has been reported that its getting close 30 | by Conduit developer Timo. Ruma has it implemented and the Catalyst Conduit fork has v10 working 31 | for about as long as Synapse has had its implementation based on the memory of the Author of this MSC. 32 | 33 | For completeness, some links: 34 | 35 | **Conduit**: 36 | 37 | * Tracking issue: N/A 38 | * Library support: https://github.com/ruma/ruma/pull/1213 39 | * Release: v0.5.0 40 | * Testing: N/A 41 | * Update Progress Source: https://gitlab.com/famedly/conduit/-/merge_requests/444/diffs?commit_id=1e1a144dfa98429ef9f02d16045796b73013830d 42 | 43 | ## Alternatives 44 | 45 | None relevant. 46 | 47 | ## Security considerations 48 | 49 | None relevant. 50 | 51 | ## Unstable prefix 52 | 53 | None relevant - servers can already choose a different default room version legally. This MSC 54 | just formalizes v10 as the default. 55 | -------------------------------------------------------------------------------- /proposals/4307-auth-events-in-correct-room.md: -------------------------------------------------------------------------------- 1 | # MSC4307: Validate that `auth_events` are in the correct room 2 | 3 | Each event in Matrix specifies a list of [auth events](https://spec.matrix.org/v1.14/server-server-api/#auth-events-selection), which are used during [event authorisation](https://spec.matrix.org/v1.14/server-server-api/#checks-performed-on-receipt-of-a-pdu) to ensure that the event should be permitted. 4 | 5 | Currently, the Matrix specification does not make explicit that these auth events must be in the same room as the event itself. 6 | 7 | This was the cause of a security vulnerability in Synapse 1.7 and earlier. 8 | 9 | ## Proposal 10 | 11 | Within the [auth rules](https://spec.matrix.org/v1.14/rooms/v11/#authorization-rules), for all room versions, add a new rule 2.5 reading: 12 | 13 | > 2.5. If any `auth_event` has a `room_id` which does not match that of the event being authorised, reject. 14 | 15 | In practice, Synapse already 16 | [implements](https://github.com/element-hq/synapse/blob/9d43bec/synapse/event_auth.py#L234) 17 | this check, and we would expect that any other server does likewise. It is also 18 | [enforced](https://github.com/matrix-org/sytest/blob/bb83c6f0cbec5f822dcaecd22533ac3e7ffde0ef/tests/50federation/31room-send.pl#L201) 19 | by the SyTest homeserver test suite. It seems a clear omission in the text of 20 | the auth rules. 21 | 22 | ## Potential issues 23 | 24 | If there exist implementations which do not already enforce this rule, then 25 | introducing it retrospectively could lead to split-brain situations where 26 | different servers accept different events into the DAG. However: 27 | 28 | 1. Since Synapse already implements this rule, the possibility of a split-brain already exists. 29 | 2. The security implications of *not* doing this check are prohibitive (ultimately, an attacker with the ability to send messages to a room can subvert the event auth system to take over the room). 30 | 31 | ## Alternatives 32 | 33 | We could leave the auth rules for existing room versions unchanged (and make 34 | either this or some other change in a future room version). Again though, given 35 | we believe all current implementations must implement this rule in practice, 36 | this seems futile. 37 | 38 | ## Security considerations 39 | 40 | Auth rules are a very delicate area of the Matrix spec. Homeserver maintainers should be particularly careful when implementing them. 41 | 42 | ## Unstable prefix 43 | 44 | N/A 45 | 46 | ## Dependencies 47 | 48 | None. 49 | -------------------------------------------------------------------------------- /proposals/2181-user-deactivated-errcode.md: -------------------------------------------------------------------------------- 1 | # Add an Error Code for Signaling a Deactivated User 2 | 3 | Currently, when a user attempts to log in, they will receive an `M_FORBIDDEN` 4 | error code if their password is incorrect. However, if the user's account is 5 | deactivated, they will also receive an `M_FORBIDDEN`, leaving clients in a 6 | state where they are unable to inform the user that the reason they cannot 7 | log in is that their account has been deactivated. This leads to confusion 8 | and password resetting which ultimately results in frustration. 9 | 10 | ## Proposal 11 | 12 | This proposal asks to create a new error code, `M_USER_DEACTIVATED`, that may 13 | be returned whenever an action is attempted that requires an activited user, 14 | but the authenticating user is deactivated. The HTTP code to return alongside 15 | is `403`. 16 | 17 | An example of this could be returning `M_USER_DEACTIVATED` on `/login`, when 18 | an identifier of a deactivated user is sent to the homeserver. Whether the 19 | password has to be correct depends on whether the Homeserver implementation 20 | removes login information on deactivation. This is an implementation detail. 21 | 22 | It should be noted that this proposal is not requiring implementations to 23 | return `M_USER_DEACTIVATED` on any endpoints when a request from a 24 | deactivated user appears. Instead it is simply defining the new error code, 25 | recommends that it should be used in situations as described above, and that 26 | the client should understand the meaning of it when it is received. 27 | 28 | ## Tradeoffs 29 | 30 | The alternative is to continue returning an `M_FORBIDDEN`, but send back a 31 | different error message. This is undesirable as clients are supposed to treat 32 | the message as an opaque string, and should not be performing any 33 | pattern-matching on it. 34 | 35 | ## Potential issues 36 | 37 | None 38 | 39 | ## Security considerations 40 | 41 | While the existence of a user was already public knowledge (one can check if 42 | the User ID is available through 43 | [/_matrix/client/r0/register/available](https://matrix.org/docs/spec/client_server/r0.5.0#get-matrix-client-r0-register-available), 44 | this proposal would allow any user to be able to detect if a registered 45 | account has been deactivated, depending on the homeserver's implementation. 46 | 47 | ## Conclusion 48 | 49 | Adding `M_USER_DEACTIVATED` would better inform clients about the state of a 50 | user's account, and lead to less confusion when they cannot log in. 51 | -------------------------------------------------------------------------------- /proposals/4041-retry-after-header-rate-limiting.md: -------------------------------------------------------------------------------- 1 | # MSC4041: Use http header Retry-After to enable library-assisted retry handling 2 | 3 | The current Matrix Client-Server API (v1.7) recommends that homeservers should protect themselves from 4 | being overloaded by enforcing rate-limits to selected API calls. 5 | If homeservers limit access to an API they respond with an http error code 429 and a response body 6 | that includes a property `retry_after_ms` to indicate how long a client has to wait before retrying. 7 | 8 | Some http libraries (like [Ky](https://github.com/sindresorhus/ky), [got](https://github.com/sindresorhus/got) 9 | and [urllib3](https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html#urllib3.util.Retry)) ease 10 | the burden of handling retries by honoring the http header `Retry-After`. As explained in 11 | [RFC 9119 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after) this header is optional 12 | and contains either a (relative) value for the delay in seconds or an (absolute) date. 13 | 14 | The current Matrix Client Server API specification does not take this header into account. This wastes the 15 | potential that current http libraries offer in terms of automated retry handling. 16 | 17 | ## Proposal 18 | 19 | In order to allow developers to make use of the automated retry handling capabilities of http libraries 20 | homeservers shall use the http header `Retry-After` in case they respond with an http error 429. 21 | The value of `Retry-After` (in __seconds__) is meant to be a delay after receiving the response and must be 22 | calculated in order to comply with the specification in [RFC 9119 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after). 23 | 24 | With the introduction of the http header `Retry-After` the usage of the existing `retry_after_ms` property in the response body becomes deprecated. 25 | 26 | ## Potential issues 27 | 28 | In order to maintain backward compatibility with existing client libraries homeservers shall use both the `Retry-After` header and the 29 | `retry_after_ms` property in the response body. 30 | 31 | Client libraries shall use the values in this order: 32 | 33 | 1) `Retry-After` http header. 34 | 2) `retry_after_ms` property in the response body. 35 | 36 | ## Alternatives 37 | 38 | N/A 39 | 40 | ## Security considerations 41 | 42 | N/A 43 | 44 | ## Unstable prefix 45 | 46 | Since this MSC is using a standard HTTP header, it will not use a unstable prefix. 47 | 48 | ## Dependencies 49 | 50 | N/A 51 | -------------------------------------------------------------------------------- /proposals/3667-enforce-integer-power-levels.md: -------------------------------------------------------------------------------- 1 | # MSC3667: Enforce integer power levels 2 | 3 | The spec defines power levels in `m.room.power_levels` events as integers, but due to legacy 4 | behaviour in Synapse, string power levels are also accepted and parsed. The string parsing itself 5 | is problematic because it is done using Python's [int()](https://docs.python.org/3/library/functions.html#int) 6 | function, which has all sorts of associated behaviours: 7 | 8 | > If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance 9 | > representing an integer literal in radix base. Optionally, the literal can be preceded by + or - 10 | > (with no space in between) and surrounded by whitespace. A base-n literal consists of the digits 0 11 | > to n-1, with a to z (or A to Z) having values 10 to 35. The default base is 10. The allowed values 12 | > are 0 and 2–36. Base-2, -8, and -16 literals can be optionally prefixed with 0b/0B, 0o/0O, or 0x/0X, 13 | > as with integer literals in code. Base 0 means to interpret exactly as a code literal, so that the 14 | > actual base is 2, 8, 10, or 16, and so that int('010', 0) is not legal, while int('010') is, as 15 | > well as int('010', 8). 16 | 17 | All of this behaviour is exceptionally difficult for non-Python implementations to reproduce 18 | accurately. 19 | 20 | ## Proposal 21 | 22 | In a future room version, we should enforce the letter of the spec and only allow power levels 23 | as integers within the range defined by canonical JSON and reject events which try to define them as any other type. This removes all of the 24 | associated headaches with string parsing. 25 | 26 | ## Potential issues 27 | 28 | We can't avoid the string parsing behaviour altogether because we need to continue to do so for 29 | existing room versions so that we do not break existing rooms. However, there are already documented 30 | cases of this causing problems across implementations. For example, Synapse will accept `" +2 "` as 31 | a power level but Dendrite will outright fail to parse it. 32 | 33 | ## Alternatives 34 | 35 | Event schema enforcement for all event types used in event auth could solve this problem and 36 | more but is a significantly bigger task. 37 | 38 | ## Unstable prefix 39 | 40 | An implementation exists in Dendrite using the `org.matrix.msc3667` room version identifier. The 41 | experimental room version is based on room version 7, with the additional requirement that power 42 | levels must be integers or the power level content will fail to unmarshal altogether. 43 | -------------------------------------------------------------------------------- /proposals/1804-advertising-capable-room-versions.md: -------------------------------------------------------------------------------- 1 | # Proposal for advertising capable room versions to clients 2 | 3 | Currently clients need to guess at which room versions the server supports, if any. This is particularly 4 | difficult to do as it generally requires knowing the state of the ecosystem and what versions are 5 | available and how keen users are to upgrade their servers and clients. The impossible judgement call 6 | for when to encourage people to upgrade shouldn't be impossible, or even a judgement call. 7 | 8 | 9 | ## Proposal 10 | 11 | Building off of [MSC1753](https://github.com/matrix-org/matrix-doc/pull/1753) (capabilities API) and 12 | the [recommendations laid out for room versions](https://github.com/matrix-org/matrix-doc/pull/1773/files#diff-1436075794bb304492ca6953a6692cd0R463), 13 | this proposal suggests a `m.room_versions` capability be introduced like the following: 14 | 15 | ```json 16 | { 17 | "capabilities": { 18 | "m.room_versions": { 19 | "default": "1", 20 | "available": { 21 | "1": "stable", 22 | "2": "stable", 23 | "state-res-v2-test": "unstable", 24 | "event-ids-as-hashes": "unstable", 25 | "3": "future-scifi-label" 26 | } 27 | } 28 | } 29 | } 30 | ``` 31 | 32 | Clients are encouraged to make use of this capability to determine if the server supports a given 33 | version, and at what level of stability. Anything not flagged explicitly as `stable` should be treated 34 | as `unstable` (ie: `future-scifi-label` is the same as `unstable`). 35 | 36 | The default version is the version that the server is using to create new rooms with. Clients can 37 | make the assumption that the default version is a stable version. 38 | 39 | Clients should encourage people with sufficient permissions to perform an upgrade to upgrade their 40 | rooms to the `default` room version when the room is using an `unstable` version. 41 | 42 | 43 | ## Potential issues 44 | 45 | Changes aren't pushed to the client, which means clients may want to poll this endpoint on some 46 | heuristic instead. For example, clients may want to poll the endpoint weekly or when the user relaunches 47 | the client. Clients may also wish to provide users a way to upgrade without considering the capabilities 48 | of the server, expecting that the server may not support the user-provided version - the intention 49 | being such a feature would be used by eager room administrators which do not want to relaunch their 50 | client, for example. 51 | -------------------------------------------------------------------------------- /proposals/4142-fix-reply-intentional-mentions.md: -------------------------------------------------------------------------------- 1 | # MSC4142: Remove unintentional intentional mentions in replies 2 | 3 | Currently, the reply spec has a section called [Mentioning the replied to user](https://spec.matrix.org/v1.10/client-server-api/#mentioning-the-replied-to-user) 4 | which says 5 | 6 | > In order to notify users of the reply, it may be desirable to include the 7 | > sender of the replied to event and any users mentioned in that event. See 8 | > [user and room mentions](https://spec.matrix.org/v1.10/client-server-api/#user-and-room-mentions) 9 | > for additional information. 10 | 11 | The "*any users mentioned in that event*" part is particularly problematic, as 12 | it effectively means all mentions will be propagated forever through a reply 13 | chain, causing lots of unintentional pings. 14 | 15 | The propagation was originally added to preserve the old reply fallback mention 16 | behavior where explicit mentions in the replied-to message were be copied to 17 | the reply fallback and therefore caused pings. However, the current spec copies 18 | far more than just explicit pings from the replied-to message. Additionally, no 19 | other chat application that I know of propagates mentions like that. 20 | 21 | ## Proposal 22 | The proposed fix is to stop propagating mentions entirely. The `m.mentions` 23 | object of replies should only contain explicit mentions in the new message, 24 | plus the sender of the replied-to message. The mentions in the replied-to 25 | message are ignored. 26 | 27 | Clients are still free to add other mentions to the list as they see fit. For 28 | example, a client could offer a button to mention all users in a reply chain. 29 | This proposal simply changes the default behavior recommended in the spec. 30 | 31 | ## Potential issues 32 | Users who have already got used to the new behavior may be surprised when they 33 | don't get mentioned by reply chains. 34 | 35 | ## Alternatives 36 | ### Split `m.mentions` 37 | To preserve the old reply fallback behavior, `m.mentions` could be split into 38 | "explicit" and "implicit", so that replies copy explicit mentions into the 39 | implicit list. Future replies would then only copy new explicit pings and 40 | wouldn't cause an infinite chain. 41 | 42 | Since other chat applications don't copy pings at all, having a weird feature 43 | like that doesn't seem worth the additional complexity. 44 | 45 | ## Security considerations 46 | This proposal doesn't touch anything security-sensitive. 47 | 48 | ## Unstable prefix 49 | Not applicable, this proposal only changes how the existing `m.mentions` object 50 | is filled for replies. 51 | 52 | -------------------------------------------------------------------------------- /proposals/2451-remove-query_auth-federation-endpoint.md: -------------------------------------------------------------------------------- 1 | # MSC2451: Remove the `query_auth` federation endpoint 2 | 3 | This API was added without sufficient thought nor testing. The endpoint isn't 4 | used in any known implementations, and we do not believe it to be necessary 5 | for federation to work. The only known implementation (in Synapse) was not fully 6 | fleshed out and is broken. 7 | 8 | For background, the idea behind this endpoint was that two homeservers would be 9 | able to share state events with the hope of filling in missing state from one 10 | of homeservers allowing state resolution to complete. This was to protect 11 | against a joining server not providing the full (or providing stale) state. 12 | 13 | In addition to the ideas above not coming to fruition, it is unclear whether the 14 | current design of this endpoint would be sufficient. If this state negotiation 15 | feature is needed in the future it should be redesigned from scratch via the MSC 16 | proposal process. 17 | 18 | ## Proposal 19 | 20 | Remove the following endpoint: 21 | 22 | * [POST `/_matrix/federation/v1/query_auth/{roomId}/{eventId}`](https://matrix.org/docs/spec/server_server/r0.1.3#post-matrix-federation-v1-query-auth-roomid-eventid) 23 | 24 | ## Potential issues 25 | 26 | Removing this endpoint impacts backwards compatibility, in practice removing 27 | this endpoint should have minimal impact as it was an unused error path in 28 | Synapse. The federation client code to call this endpoint was removed in Synapse 29 | v1.5.0rc1. 30 | 31 | There is no evidence of other homeserver implementations having implemented this 32 | endpoint. 33 | 34 | ### History 35 | 36 | This endpoint (and the federation client code) to call it was initially 37 | added in Synapse v0.7.0 (see [#43](https://github.com/matrix-org/synapse/pull/43)). 38 | The federation client code was heavily modified for v1.0.0rc1 (see 39 | [#5227](https://github.com/matrix-org/synapse/pull/5227/)), 40 | 41 | The federation client code to call this endpoint was removed in v1.5.0rc1 of 42 | Synapse (see [#6214](https://github.com/matrix-org/synapse/pull/6214). After 43 | that point this endpoint is not called). 44 | 45 | During removal it was noted that the code to call this endpoint was already 46 | unreachable. It seems that this code was never reachable and was meant for an 47 | error situation which was never built out (see `git log -S NOT_ANCESTOR`, the 48 | error condition is never assigned). 49 | 50 | ## Alternatives 51 | 52 | The endpoint could be deprecated and removed in a future version of the specification. 53 | 54 | ## Security considerations 55 | 56 | None. 57 | -------------------------------------------------------------------------------- /proposals/3758-expand-push-rule-conditions.md: -------------------------------------------------------------------------------- 1 | # MSC3758: Add `event_property_is` push rule condition kind 2 | 3 | Currently the only condition used to match event content for push rules is the `event_match` kind. 4 | This compares a glob-style string against a string value within the event dictionary. The event 5 | dictionary is flattened before conditions are checked to enable matching nested values. 6 | 7 | This approach is currently limited to only checking for string values within the event dictionary 8 | (at any level). This MSC proposes a new exact match type for event content that works with all 9 | JSON types. 10 | 11 | 12 | ## Proposal 13 | 14 | ### Exact matching event data 15 | 16 | We propose a new type of condition, `event_property_is`. Similar to the current `event_match` 17 | ([link to spec](https://spec.matrix.org/v1.3/client-server-api/#conditions-1)), this condition 18 | takes two parameters: `value` and `key`. The exact match compares the `value` to the event data 19 | associated with `key` exactly. Both type and content (when a string) should be identical 20 | (include case). This allows for matching all non-compound JSON types allowed by 21 | [canonical JSON](https://spec.matrix.org/v1.5/appendices/#canonical-json): 22 | i.e. strings, `null`, `true`, `false` and integers. This also provides a simpler 23 | exact string matching mechanism (and any associated performance gains on implementation side without 24 | globbing). 25 | 26 | An example condition may look like (encoded as a JSON object): 27 | 28 | ```json 29 | { 30 | "kind": "event_property_is", 31 | "key": "content.is_something", 32 | "value": true 33 | } 34 | ``` 35 | 36 | 37 | ## Alternatives 38 | 39 | [MSC3862](https://github.com/matrix-org/matrix-spec-proposals/pull/3862) proposes an alternative 40 | solution by converting non-string JSON objects to strings in the `event_match` condition type. 41 | 42 | ## Security considerations 43 | 44 | None. 45 | 46 | ## Future extensions 47 | 48 | A future MSC may wish to define the behavior of `event_property_is` when 49 | used with a JSON object or array. 50 | 51 | [MSC3887](https://github.com/matrix-org/matrix-spec-proposals/pull/3887) is a 52 | related MSC which attempts to define behavior for searching for a value inside of 53 | an array. 54 | 55 | ## Unstable prefix 56 | 57 | While still not part of the Matrix spec, the new push rule condition should be 58 | `com.beeper.msc3758.exact_event_match` instead of `event_property_is`, e.g.: 59 | 60 | ```json 61 | { 62 | "kind": "com.beeper.msc3758.exact_event_match", 63 | "key": "..." 64 | } 65 | ``` 66 | 67 | ## Dependencies 68 | 69 | None. 70 | -------------------------------------------------------------------------------- /proposals/1819-remove-presence-lists.md: -------------------------------------------------------------------------------- 1 | # Remove references to presence lists 2 | 3 | [Presence](https://matrix.org/docs/spec/client_server/r0.4.0.html#id107) lists 4 | allow a given user the ability to subscribe to other users and be alerted to 5 | their current presence status. 6 | 7 | While spec'd, no established client has implemented support and the only server 8 | side implementation raises privacy concerns. 9 | 10 | The proposal is to simply remove references to presence lists with a view to 11 | revisiting the same ideas in the future. 12 | 13 | This MSC addresses 14 | [#1810](https://github.com/matrix-org/matrix-doc/issues/1810) 15 | 16 | ## Proposal 17 | 18 | Presence lists seem like a good fit for ['MSC1769: Extensible profiles as 19 | rooms'](https://github.com/matrix-org/matrix-doc/pull/1769) proposal, meaning 20 | that the current design will most likely be superseded. 21 | 22 | Additionally, no major client has implemented the behaviour to date and the 23 | only server implementation of presence lists (Synapse) auto-accepts invites 24 | leading to privacy concerns in the wild. 25 | 26 | With this in mind the most pragmatic solution is to remove presence lists ahead 27 | of the r0 release. 28 | 29 | Specifically:- 30 | 31 | CS API: Remove 32 | * [POST 33 | /_matrix/client/r0/presence/list/{userId}](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-presence-list-userid) 34 | * [GET 35 | /_matrix/client/r0/presence/list/{userId}](https://matrix.org/docs/spec/client_server/r0.4.0.html#get-matrix-client-r0-presence-list-userid) 36 | 37 | SS API: Remove 38 | * [m.presence_invite](https://github.com/matrix-org/matrix-doc/blob/8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3/api/server-server/definitions/event-schemas/m.presence_invite.yaml) 39 | * [m.presence_accept](https://github.com/matrix-org/matrix-doc/blob/8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3/api/server-server/definitions/event-schemas/m.presence_accept.yaml) 40 | * [m.presence_deny](https://github.com/matrix-org/matrix-doc/blob/8b65da1cf6fce5f657a2a46b5c6c8bcc24d32ae3/api/server-server/definitions/event-schemas/m.presence_deny.yaml) 41 | 42 | 43 | ## Tradeoffs 44 | 45 | Ideally this proposal would also come with an alternative design for this 46 | functionality. Out of pragmatism the proposal only covers removal of what is 47 | there today. 48 | 49 | 50 | ## Conclusions 51 | 52 | This is a common sense attempt to remove unused portions of the spec ahead of 53 | an r0 release. It does not suggest that the ability to subscribe to the 54 | presence of others is undesirable and assumes that this behaviour will return 55 | again in some form. 56 | -------------------------------------------------------------------------------- /proposals/3980-dotted-fields-consistency.md: -------------------------------------------------------------------------------- 1 | # MSC3980: Dotted Field Consistency 2 | 3 | [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) disambiguated 4 | how event properties are matched for push rules and based the proposal on how 5 | [filters](https://spec.matrix.org/v1.6/client-server-api/#post_matrixclientv3useruseridfilter) 6 | are currently escaped for consistency. 7 | 8 | Through the MSC process the escaping was expanded from just escaping `.` characters 9 | with a backslash (`\.`) to also escaping backslashes themselves (`\\`). Unfortunately 10 | that MSC did not propose applying this change *back* to filters for consistency. [^1] 11 | 12 | ## Proposal 13 | 14 | Apply consistent escaping as described in [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) 15 | to the `event_fields` property of filters. 16 | This would allow an unambiguous way to describe property names, as currently 17 | the behavior of backslashes is undefined. 18 | 19 | The text given in MSC3873 can apply here (changing `key` to `event_fields`): 20 | 21 | > The dot (`.`) character in the [`event_fields`] parameter is changed to be exclusively 22 | reserved for field separators. Any literal dot in field names are to be 23 | escaped using a backslash (`\.`) and any literal backslashes are also escaped with 24 | a backslash (`\\`). A backslash before any other character has no special meaning 25 | and is left as-is, but it is recommended that implementations do not redundantly 26 | escape characters, as they may be used for escape sequences in the future. 27 | 28 | In short, this would update the 29 | [description of `event_fields`](https://spec.matrix.org/v1.6/client-server-api/#post_matrixclientv3useruseridfilter) 30 | (bolded part is new): 31 | 32 | > List of event fields to include. If this list is absent then all fields are 33 | > included. The entries may include ‘.’ characters to indicate sub-fields. So 34 | > [‘content.body’] will include the ‘body’ field of the ‘content’ object. A 35 | > literal ‘.’ **or '\\'** character in a field name may be escaped using a ‘\’. A server 36 | > may include more fields than were requested. 37 | 38 | 39 | ## Potential issues 40 | 41 | This is slightly backwards incompatible if a property name currently contains a 42 | backslash in it. 43 | 44 | ## Alternatives 45 | 46 | Leave things as they are and be inconsistent between different parts of the spec. 47 | 48 | ## Security considerations 49 | 50 | N/A 51 | 52 | ## Unstable prefix 53 | 54 | N/A 55 | 56 | ## Dependencies 57 | 58 | N/A 59 | 60 | [^1]: This came up while writing the [spec PR for MSC3873](https://github.com/matrix-org/matrix-spec/pull/1464#discussion_r1135712844). 61 | -------------------------------------------------------------------------------- /proposals/2705-thumbnail-requirements.md: -------------------------------------------------------------------------------- 1 | # MSC2705: Animated thumbnails 2 | 3 | Users may already upload animated media to the media repository, such as gifs, webp images, and videos. 4 | When this media is used in an event or avatar, many clients are stuck with a static thumbnail until 5 | the user clicks on it to get the full, unedited, file. Some clients however would prefer to show an 6 | animated thumbnail in certain conditions, like when the user is hovering over the message or avatar. 7 | 8 | This proposal introduces a new query parameter to the [`GET /_matrix/media/v3/thumbnail`](https://spec.matrix.org/v1.9/client-server-api/#get_matrixmediav3thumbnailservernamemediaid) 9 | endpoint, allowing clients to specifically request an animated thumbnail. 10 | 11 | ## Proposal 12 | 13 | A new query parameter, `animated`, is added to the `/thumbnail` endpoint. It has the following behaviour: 14 | 15 | * When `true`: the server SHOULD return an animated thumbnail if possible/supported. 16 | * When `false`: the server MUST NOT return an animated thumbnail. 17 | * When not provided: the server SHOULD NOT return an animated thumbnail. 18 | 19 | The default case is a relaxed version of the `false` behaviour to allow server owners to customize the 20 | default behaviour when their users' clients do not support requesting animated thumbnails. 21 | 22 | Clients SHOULD respect a user's preference to [reduce motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) 23 | and request non-animated thumbnails in these cases. 24 | 25 | The content types which are able to be animated is left as an implementation detail. The following 26 | SHOULD be supported at a minimum, however: 27 | 28 | * `image/gif` 29 | * `image/png` or `image/apng` ("APNG" format) 30 | * `image/webp` 31 | 32 | The returned content type for an animated thumbnail is additionally left as an implementation detail, 33 | though servers SHOULD use `image/webp` whenever possible. 34 | 35 | When media cannot be animated, such as a PDF or JPEG, the server should return a thumbnail as though 36 | `animated` was `false`. 37 | 38 | ## Alternatives 39 | 40 | No significant alternatives. 41 | 42 | ## Security considerations 43 | 44 | Server load could increase when the server tries to thumbnail a large file. Servers are expected to 45 | mitigate this on their own by providing an option to disable the feature or limiting how/when 46 | they will animate the media. 47 | 48 | ## Unstable prefix 49 | 50 | While this proposal is not considered stable, `animated` is specified as `org.matrix.msc2705.animated` 51 | on requests. No unstable endpoints are required due to backwards compatibility being built-in to the 52 | proposal. 53 | -------------------------------------------------------------------------------- /proposals/4239-v11-default-version.md: -------------------------------------------------------------------------------- 1 | # MSC4239: Room version 11 as the default room version 2 | 3 | [Room version 11](https://spec.matrix.org/v1.12/rooms/v11/) was introduced in Matrix 1.8 back in 4 | August 2023. The room version is a light cleanup from [room version 10](https://spec.matrix.org/v1.12/rooms/v10/), 5 | particularly around the redaction algorithm. There are no other major changes. 6 | 7 | Over the last year since release, the expectation was that there might be a room version 12 in quick 8 | succession, however as is tradition for any expectation, things changed. This proposal bumps the 9 | [default suggested room version](https://spec.matrix.org/v1.12/rooms/#complete-list-of-room-versions) 10 | from version 10 to version 11, bringing the redaction algorithm cleanup to the wider ecosystem. 11 | 12 | ## Proposal 13 | 14 | The specification adopts room version 11 as the suggested default room version. No stability status 15 | changes are made to any room version. 16 | 17 | ## Potential issues 18 | 19 | Some servers may not have updated to support version 11 yet, though many servers support version 10. 20 | The delta between the versions is minimal. 21 | 22 | ## Alternatives 23 | 24 | No relevant alternatives. 25 | 26 | ## Security considerations 27 | 28 | No relevant security considerations (they would have been made in [MSC3820](https://github.com/matrix-org/matrix-spec-proposals/pull/3820)). 29 | 30 | ## Unstable prefix 31 | 32 | No relevant prefix - servers can already choose a different default room version. This MSC formalizes 33 | the default. 34 | 35 | ## Dependencies 36 | 37 | No outstanding blockers are listed. 38 | 39 | ## Prior art 40 | 41 | * https://github.com/matrix-org/matrix-spec-proposals/pull/3904 - Room version 10 to default (released in Matrix 1.6, February 2023) 42 | * https://github.com/matrix-org/matrix-spec-proposals/pull/3589 - Room version 9 to default (released in Matrix 1.3, June 2022) 43 | * https://github.com/matrix-org/matrix-spec-proposals/pull/2788 - Room version 6 to default (released in Matrix 1.1(?), November 2021) 44 | * https://github.com/matrix-org/matrix-spec-proposals/pull/2334 - Room version 5 to default (released in r0.6.0, November 2019) 45 | * https://github.com/matrix-org/matrix-spec-proposals/pull/2002 - Room version 4 to default (released ~r0.5.0, "Matrix 1.0", June 2019) 46 | * https://github.com/matrix-org/matrix-spec-proposals/pull/1943 - Room version 3 to default (closed in favour of version 4) 47 | 48 | Note: Room versions 2, 3, 7, and 8 were never adopted as the default room version. Version 1 was the original room version, 49 | released formally in https://github.com/matrix-org/matrix-doc/pull/1773 (~r0.5.0, "Matrix 1.0", June 2019). 50 | -------------------------------------------------------------------------------- /proposals/3288-pass_room_type_in_3pid_invite.md: -------------------------------------------------------------------------------- 1 | # MSC3288: Add room type to `/_matrix/identity/v2/store-invite` API 2 | 3 | Currently when inviting via 3pid, the Identity Server receives some information about the room, 4 | like for example the room name and avatar as well as the inviter name. 5 | This allows the identity server to generate a rich email to the invitee. 6 | 7 | Now that the matrix spec supports spaces, it would be nice to also provide this information to the identity server 8 | so that the email invite could be customized for spaces. The current implementation would say wrongly that 9 | you are invited to a room when the room is actually a space. 10 | 11 | The goal of this proposal is to make 3pid invites space aware. 12 | 13 | 14 | ## Proposal 15 | 16 | Homeservers should also send the `room_type` to the identity server when performing a third party invite (__Invitation storage__). 17 | 18 | 19 | __Proposed change:__ 20 | 21 | Add a new `room_type` field in json body of [`POST /_matrix/identity/v2/store-invite`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-store-invite): 22 | 23 | | Parameter | Type | Description | 24 | |--|--|--| 25 | | room_type | string | The room type for the room to which the user is invited. This should be retrieved from the value of `type` in the `m.room.create` event's `content`. Do not include parameter if `type` is not present in `m.room.create`. 26 | 27 | ```` 28 | POST /_matrix/identity/v2/store-invite HTTP/1.1 29 | Content-Type: application/json 30 | 31 | { 32 | "medium": "email", 33 | "address": "foo@example.com", 34 | "room_id": "!something:example.org", 35 | "sender": "@bob:example.com", 36 | "room_alias": "#somewhere:example.org", 37 | "room_avatar_url": "mxc://example.org/s0meM3dia", 38 | "room_join_rules": "public", 39 | "room_name": "The Bob Project", 40 | "room_type": "m.space", 41 | "sender_display_name": "Bob Smith", 42 | "sender_avatar_url": "mxc://example.org/an0th3rM3dia" 43 | } 44 | ```` 45 | 46 | The identity server could then use room type to customize the email depending on the room type. 47 | 48 | __Email Generation__ 49 | 50 | The link in the generated email should also pass over the `room_type` to clients ( like it is doing for 51 | `inviter_name`, `room_name`, `room_avatar`) 52 | 53 | ## Potential issues 54 | 55 | None. 56 | 57 | 58 | ## Security considerations 59 | 60 | None. 61 | 62 | ## Unstable prefix 63 | 64 | The following mapping will be used for identifiers in this MSC during development: 65 | 66 | 67 | Proposed final identifier | Purpose | Development identifier 68 | ------------------------------- | ------- | ---- 69 | `room_type` | POST body | `org.matrix.msc3288.room_type` 70 | -------------------------------------------------------------------------------- /proposals/2184-allow-html-details.md: -------------------------------------------------------------------------------- 1 | # Allow the HTML `
` tag in messages 2 | 3 | Currently, there's no available method for bot developers - among others - to provide larger informative 4 | messages in a room without disrupting the conversation for all other users. This often causes bots 5 | to appear needlessly "spammy". 6 | 7 | ## Proposal 8 | 9 | This proposal suggests adding the existing HTML tags for `
` and `` to the list of 10 | allowed tags in formatted Matrix messages. Which would allow for larger messages to be shown simply 11 | as smaller - and less intrusive - summaries for the users who are not interested in their full contents. 12 | 13 | ## Tradeoffs 14 | 15 | An alternative method to provide a summary/details split could possibly be done through [MSC1767], 16 | with the details and summaries being specified through repeated bodies with added metadata. This could 17 | then also allow clients better autonomy in deciding what to display - or how to structure the information. 18 | 19 | However, allowing the use of the `
` and `` tags would still offer richer formatting 20 | capabilities even in such messages, especially as more than one detail/summary block could be included 21 | in a single message. 22 | 23 | ## Potential issues 24 | 25 | Allowing more HTML tags in formatted messages could cause more work for client developers, as they would 26 | have to fit a larger and more diverse corpus of input into their designs and user experience. 27 | However, these are both well documented - and implemented - HTML tags, so there is plenty of prior work 28 | available to take example from in how to incorporate them. 29 | 30 | Additionally, as the addition of these tags will make it possible to fit even more information into 31 | a single message without worry of overflowing the room, any client that doesn't render the formatting 32 | of the body might end up with a lessened user experience - from either an under- or overflow of information. 33 | 34 | The onus on ensuring that the unformatted body is a reasonable representation of the message has always 35 | been on the user or bot writing the formatted message though, so providing an improved ability for 36 | formatting should not negatively affect the experience for any clients that simply render unformatted 37 | text. 38 | 39 | ## Security considerations 40 | 41 | Allowing more HTML tags in client rendering could lead to a wider attack surface for DOM-based exploits. 42 | However, these tags are very simple in both function and design, so any possible attack surface they 43 | would offer would be minimal at best. 44 | 45 | [MSC1767]: https://github.com/matrix-org/matrix-doc/blob/matthew/msc1767/proposals/1767-extensible-events.md 46 | -------------------------------------------------------------------------------- /proposals/4026-optional-authed-versions.md: -------------------------------------------------------------------------------- 1 | # MSC4026: Allow /versions to optionally accept authentication 2 | 3 | ## Introduction 4 | 5 | Synapse is implementing the ability to turn some unstable features on per-user. Once this is 6 | implemented, certain experimental features will be available to be enabled per-user via the [Admin API](https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/index.html). 7 | The intention is to allow certain users to test the experimental feature without making it available to 8 | all users before it is stable. 9 | This is in addition to the current ability to toggle on/off those features system-wide in the configuration. 10 | 11 | However, this poses a problem when considering how to advertise that those features are enabled to clients. 12 | Traditionally, to determine what unstable features were available from a server clients checked the [`/_matrix/client/versions`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientversions) 13 | endpoint, which in turn checked the Synapse configuration to determine what experimental features were enabled. With the 14 | changes being implemented this is no longer possible, as some experimental features may be enabled per-user. As the 15 | `/_matrix/client/versions` endpoint does not require authentication there is no way to know which experimental features 16 | are enabled - there is no access token that we can extract user info from to determine which unstable features are 17 | currently enabled (as they may only be enabled for some users) - and thus there is no way to correctly communicate to 18 | clients which experimental features are enabled. 19 | 20 | ## Proposal 21 | 22 | The proposal to remedy this is to make `/_matrix/client/versions` optionally accept authentication, and ask clients 23 | to use the authenticated version when determining which experimental features are enabled. 24 | 25 | ## Potential issues 26 | 27 | This does raise the question of what the non-authenticated version of `/_matrix/client/versions` should return with 28 | regard to unstable features if the proposal is accepted. 29 | 30 | ## Alternatives 31 | 32 | An alternative to the proposal would be to move advertising the unstable features to the [`/_matrix/client/v3/capabilities`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3capabilities) 33 | endpoint, which does require authentication. However, the spec is clear that `/_matrix/client/v3/capabilities` "should 34 | not be used to advertise unstable or experimental features - this is better done by the `/versions` endpoint." Thus, 35 | this seems like a less desirable option than the proposed solution. 36 | 37 | ## Security considerations 38 | 39 | None that I am currently aware of. -------------------------------------------------------------------------------- /proposals/2630-sas-check-public-keys.md: -------------------------------------------------------------------------------- 1 | # MSC2630: Checking public keys in SAS verification 2 | 3 | The current SAS protocol does not ensure that the two users correctly received 4 | each other's public keys. An attacker could send Alice and Bob public keys 5 | that he has created and, if the attacker is lucky, could obtain the same shared 6 | secret with both Alice and Bob, so that when they verify the SAS string, will 7 | believe that the exchange was secure. 8 | 9 | To mitigate against this, Alice and Bob can use the two public keys in the 10 | generation of the SAS string by including it in the info parameter of the HKDF. 11 | Thus if an attacker sends them different public keys, the info parameters will 12 | be different, and so the key generated by the HKDF will be different. 13 | 14 | Thanks to [David Wong](https://twitter.com/cryptodavidw) for identifying the 15 | issue, disclosing responsibly, and for helping to design the fix. 16 | 17 | ## Proposal 18 | 19 | A new `key_agreement_protocol`, `curve25519-hkdf-sha256` is introduced, and 20 | will be mandatory for clients to support when performing SAS verification. It 21 | is the same as `curve25519` except that the info parameter for the HKDF is the 22 | concatenation of: 23 | 24 | * The string `MATRIX_KEY_VERIFICATION_SAS|`. 25 | * The Matrix ID of the user who sent the `m.key.verification.start` message, 26 | followed by `|`. 27 | * The Device ID of the device which sent the `m.key.verification.start` 28 | message, followed by `|`. 29 | * The public key from the `m.key.verification.key` message sent by the device 30 | which sent the `m.key.verification.start` message, followed by `|`. 31 | * The Matrix ID of the user who sent the `m.key.verification.accept` message, 32 | followed by `|`. 33 | * The Device ID of the device which sent the `m.key.verification.accept` 34 | message, followed by `|`. 35 | * The public key from the `m.key.verification.key` message sent by the device 36 | which sent the `m.key.verification.accept` message, followed by `|`. 37 | * The `transaction_id` being used. 38 | 39 | The differences from `curve25519` are the addition of the public keys, and the 40 | addition of `|` as delimiter between the fields. 41 | 42 | The `key_agreement_protocol` `curve25519` is deprecated and may be removed in 43 | the future. It will no longer be mandatory for clients to support, and new 44 | implementations are discouraged from implementing it. 45 | 46 | ## Implementation 47 | 48 | This has been implemented in: 49 | 50 | - Riot Web 1.6.3 (matrix-js-sdk 6.2.0) 51 | - Riot Android 0.9.12 (matrix-android-sdk 0.9.35) 52 | - RiotX 0.21 53 | - Riot iOS 0.11.5 (matrix-ios-sdk 0.16.5) 54 | - matrix-weechat and pantalaimon (matrix-nio 0.12.0) 55 | - famedlysdk 56 | -------------------------------------------------------------------------------- /proposals/2002-rooms-v4.md: -------------------------------------------------------------------------------- 1 | # MSC 2002 - Rooms V4 2 | 3 | This MSC proposes creating a new room version named v4 to allow servers to switch 4 | event ID grammar to that proposed in MSC1884. 5 | 6 | ## Proposal 7 | 8 | The new room version is called "4". The only difference between v4 and v3 is 9 | that v4 rooms use the grammar for defining event IDs as proposed in MSC1884 - 10 | expressing event IDs as url-safe base64 rather than plain base64 for the 11 | convenience of client implementors. 12 | 13 | It is not proposed that servers change the default room version used when 14 | creating new rooms, and it is not proposed that servers recommend upgrading 15 | existing rooms to v4. 16 | 17 | ## Rationale and Context 18 | 19 | We would like to default to creating rooms with a reasonably secure room 20 | algorithm in upcoming Matrix 1.0. We do not want to default to creating v3 21 | rooms due to the inconvenience the v3 event ID grammar might cause, so instead 22 | we are proposing favouring v4. 23 | 24 | Ideally we would also include other room algorithm changes in v4 (e.g. 25 | honouring server signing key validity periods, as per 26 | https://github.com/matrix-org/synapse/issues/4364), but as spec & 27 | implementation work is still ongoing there, we are proposing using v4 as a 28 | room version which can be supported in the wild before Matrix 1.0 and then 29 | used as the initial default for creating rooms. The expectation is for the 30 | versions of the spec which coincide with 1.0 to also support v5 rooms, but in 31 | practice v5 will not be marked as default until it has sufficient adoption on 32 | the public network. 33 | 34 | The expectation is never to recommend upgrading existing 35 | rooms to v4, but instead v5 (once ready), to avoid overburdening room admins 36 | with upgrade notifications. 37 | 38 | To conclude, the proposed plan is: 39 | 1. Define room v4 as MSC1884 40 | 2. Introduce servers with v4 support into the public network as rapidly as possible 41 | 3. Wait for enough servers to speak v4. Meanwhile: 42 | 1. Define an MSC for honouring server signing key validity periods 43 | 2. Implement this MSC 44 | 3. Define room v5 as this MSC 45 | 4. Release Matrix 1.0, defining room v4 as the new default for creating rooms, 46 | but also shipping support for room v5 for the first time. 47 | 5. Wait for enough servers to speak v5 rooms. 48 | 6. Define room v5 as the new default for creating rooms. 49 | 7. Define room versions prior to v5 as unsafe, thus prompting users to upgrade their 50 | rooms to v5. 51 | 52 | The reason we don't wait for v5 to be widespread before releasing 1.0 is to avoid 53 | delaying the 1.0 yet further. It is good enough for 1.0 to support v5 without it 54 | also being the default for creating rooms. 55 | -------------------------------------------------------------------------------- /proposals/2249-report-require-joined.md: -------------------------------------------------------------------------------- 1 | # MSC2249: Require users to have visibility on an event when submitting reports 2 | 3 | The [report API](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-rooms-roomid-report-eventid) 4 | currently does not require users to be joined to the room in order to report that an 5 | event is inappropriate. This allows anyone to report any event in any room without being joined to the room. 6 | There is limited use (and scope for abuse) for users to call report on rooms they are not joined to, 7 | so this proposal requires that reporting users must be joined to a room before they can report an event. 8 | 9 | Furthermore this proposal addresses the case where the user may not have visibility 10 | on an event (e.g. not being able to read history in a room). 11 | 12 | In that case, similar logic applies as described below. 13 | 14 | ## Proposal 15 | 16 | The `/rooms/{roomId}/report/{eventId}` endpoint should check to see if the authenticated user 17 | is joined to the room in the current state of the room. If the user is not joined to the room, 18 | the room does not exist, or the event does not exist the server should respond with: 19 | 20 | ```json 21 | { 22 | "errcode": "M_NOT_FOUND", 23 | "error": "Unable to report event: it does not exist or you aren't able to see it." 24 | } 25 | ``` 26 | 27 | where the contents of `error` can be left to the implementation. It is important to note that this response 28 | MUST be sent regardless if the room/event exists or not as this endpoint could be used as a way to brute 29 | force room/event IDs in order to find a room/event. 30 | 31 | It is not expected for homeservers to attempt to backfill an event they cannot find locally, as the user is unlikely to 32 | have seen an event that the homeserver has not yet stored. 33 | 34 | If the event is redacted, reports MAY still be allowed but are dependant on the implementation. 35 | 36 | ## Tradeoffs 37 | 38 | None 39 | 40 | ## Potential issues 41 | 42 | This will incur a performance penalty on the endpoint as the homeserver now needs to query state in the room, however 43 | this is considered acceptable given the potential to reduce abuse of the endpoint. 44 | 45 | ## Security considerations 46 | 47 | Care should be taken not to give away information inadvertently by responding with different error codes depending 48 | on the existence of the room, as it may give away private rooms on the homeserver. This may be somewhat unavoidable 49 | due to the time delay for checking the existence of a room vs checking the state for a user, so implementations 50 | MAY decide to "fuzz" the response times of the endpoint to avoid time-based attacks. 51 | ## Conclusion 52 | 53 | This proposal should hopefully reduce the abuse potential of the /report endpoint without significantly increasing 54 | the complexity or performance requirements on a homeserver. 55 | -------------------------------------------------------------------------------- /proposals/3316-appservice-timestamp-massaging.md: -------------------------------------------------------------------------------- 1 | # Proposal to add timestamp massaging to the spec 2 | Bridges often want to override message timestamps to preserve the timestamps from 3 | the remote network. The spec used to have a concept of [timestamp massaging], but 4 | it was excluded from the release due to not being properly specified. Synapse 5 | still implements it and it is widely used in bridges. 6 | 7 | [MSC2716] was originally going to add timestamp massaging to the spec, but it 8 | pivoted to focusing solely on batch sending history. This MSC simply copies the 9 | proposed `ts` query param from the [original MSC2716]. 10 | 11 | [timestamp massaging]: https://matrix.org/docs/spec/application_service/r0.1.2#timestamp-massaging 12 | [MSC2716]: https://github.com/matrix-org/matrix-doc/pull/2716 13 | [original MSC2716]: https://github.com/matrix-org/matrix-doc/blob/94514392b118dfae8ee6840b13b83d2f8ce8fcfc/proposals/2716-importing-history-into-existing-rooms.md 14 | 15 | ## Proposal 16 | As per the original version of MSC2716: 17 | 18 | > We let the AS API override ('massage') the `origin_server_ts` timestamp 19 | > applied to sent events. We do this by adding a `ts` querystring parameter on 20 | > the `PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}` 21 | > and `PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}` 22 | > endpoints, specifying the value to apply to `origin_server_ts` on the event 23 | > (UNIX epoch milliseconds). 24 | > 25 | > We consciously don't support the `ts` parameter on the various helper 26 | > syntactic-sugar APIs like /kick and /ban. If a bridge/bot is smart enough to 27 | > be faking history, it is already in the business of dealing with raw events, 28 | > and should not be using the syntactic sugar APIs. 29 | 30 | The spec should also make it clear that the `ts` query param won't affect DAG 31 | ordering, and MSC2716's batch sending should be used when the intention is to 32 | insert history somewhere else than the end of the room. 33 | 34 | ## Potential issues 35 | None. 36 | 37 | ## Alternatives 38 | The new MSC2716 could technically be considered an alternative, but it can only 39 | be used for history, while this proposal also supports overriding timestamps of 40 | new messages. In practice, bridges will likely use both: Batch sending for 41 | filling history and timestamp massaging for new messages. 42 | 43 | ## Security considerations 44 | Timestamps should already be considered untrusted over federation, and 45 | application services are trusted server components, so allowing appservices 46 | to override timestamps does not create any new security considerations. 47 | 48 | ## Unstable prefix 49 | `org.matrix.msc3316.ts` may be used as the query parameter. However, the `ts` 50 | parameter is already used in production for the `/send` endpoint, which means 51 | the unstable prefix should only be used for the `/state` endpoint. 52 | -------------------------------------------------------------------------------- /proposals/2540-stricter-event-validation.md: -------------------------------------------------------------------------------- 1 | # MSC2540: Stricter event validation: JSON compliance 2 | 3 | ## Background 4 | 5 | There has been [prior discussions](https://github.com/matrix-org/matrix-doc/issues/1646) 6 | about validating events more strictly. This MSC proposes fixing a small piece of 7 | this: JSON compliance. 8 | 9 | The [Canonical JSON](https://matrix.org/docs/spec/appendices#canonical-json) 10 | specification requires that numbers that are serialized in JSON are integers in 11 | the inclusive range of `[-(2^53) + 1, (2^53) - 1]`, which matches the requirements of 12 | [section 6 of RFC 7159](https://tools.ietf.org/html/rfc7159). Note that it is 13 | not explicit, but all floats are invalid. 14 | 15 | It is worth mentioning that there are common extensions to JSON which produce 16 | invalid JSON according to the Matrix specification; some programming languages 17 | even support these by default. One common additional feature is handling 18 | "special" float values: `Infinity`, `-Infinity`, and `NaN`. 19 | 20 | 21 | ## Proposal 22 | 23 | In a future room version, homeserver implementations are to strictly enforce 24 | the JSON compliance of the Canonical JSON specification for events. 25 | Non-compliant events should be treated like any other malformed event, 26 | for example by rejecting the request with an HTTP 400 error with `M_BAD_JSON`, 27 | or by discarding the event. 28 | 29 | The rationale for doing this in a future room version is to avoid a split brain 30 | room -- where some federated servers believe an event is valid and others reject 31 | it as invalid. Rooms will be able to opt into this behavior as part of a room 32 | version upgrade. 33 | 34 | Homeserver implementations are not to strictly enforce this JSON compliance in 35 | [room versions 1, 2, 3, 4, and 5](https://matrix.org/docs/spec/#complete-list-of-room-versions). 36 | The rationale is essentially the same as why a future room version is necessary: 37 | this ensures that all federated servers treat the same events as valid. 38 | 39 | 40 | ## Potential issues 41 | 42 | Homeserver implementations might include JSON parsers which are stricter than 43 | others. It may not be worthwhile or reasonable to loosen those restrictions for 44 | stable room versions. 45 | 46 | 47 | ## Alternatives 48 | 49 | It could be argued that this MSC is unnecessary since it does not add any new 50 | requirements for handling of JSON data. Unfortunately starting to enforce these 51 | requirements in current rooms could cause federation to break as homeservers 52 | will disagree on whether events are valid. 53 | 54 | 55 | ## Security considerations 56 | 57 | N/A 58 | 59 | 60 | ## Unstable prefix 61 | 62 | A room version of `org.matrix.strict_canonicaljson` until a future room version 63 | is available. This room version will use 64 | [room version 5](https://matrix.org/docs/spec/rooms/v5) as base and include the 65 | above modifications. 66 | -------------------------------------------------------------------------------- /proposals/4189-guest-access-media-routes.md: -------------------------------------------------------------------------------- 1 | # MSC4189: Allowing guests to access uploaded media 2 | 3 | [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3916-authentication-for-media.md) 4 | introduced new endpoints which require clients to provide a valid access token in order to access 5 | media. The MSC failed to specify [guest access](https://spec.matrix.org/v1.11/client-server-api/#guest-access) 6 | requirements for the new endpoints. 7 | 8 | This MSC specifies the missing guest access requirements on the new endpoints. 9 | 10 | ## Proposal 11 | 12 | The following endpoints explicitly permit guest access, joining the 13 | [list of other endpoints](https://spec.matrix.org/v1.11/client-server-api/#client-behaviour-13) 14 | already in the specification: 15 | 16 | * [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) 17 | * [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) 18 | * [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) 19 | 20 | The rationale for the above endpoints is that being able to see events without the associated media 21 | isn't very useful. 22 | 23 | For clarity, the following endpoints are *not* added to the guest access list, as their prior (now 24 | deprecated) versions are not already included. A future MSC may change this with sufficient rationale. 25 | Note that guests cannot currently *upload* files, but can send messages/events. 26 | 27 | * [`GET /_matrix/client/v1/media/config`](https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv1mediaconfig) 28 | * [`GET /_matrix/client/v1/media/preview_url`](https://spec.matrix.org/v1.11/client-server-api/#get_matrixclientv1mediapreview_url) 29 | 30 | ## Potential issues 31 | 32 | This MSC fixes an issue where guests cannot download images/files. 33 | 34 | ## Alternatives 35 | 36 | None applicable. 37 | 38 | ## Security considerations 39 | 40 | This MSC does not materially increase the threat profile for guests: guests could already download 41 | media using the unauthenticated endpoints. 42 | 43 | ## Unstable prefix 44 | 45 | Prefixed endpoints are excessive for this MSC. Implementations can enable guest access on the existing 46 | endpoints safely, or continue to respond with "guest access forbidden" errors. No `/versions` flag 47 | is specified for feature detection: clients with guest access tokens should expect failure until a 48 | server advertises a specification version containing this MSC. Clients should continue trying to make 49 | requests for the best user experience. 50 | 51 | ## Dependencies 52 | 53 | This MSC has no dependencies. 54 | -------------------------------------------------------------------------------- /proposals/3567-optional-from-on-messages.md: -------------------------------------------------------------------------------- 1 | # MSC3567: Allow requesting events from the start/end of the room history 2 | 3 | It can be useful to request the latest events in a room directly without calling 4 | `/_matrix/client/v3/sync` first to fetch the room state. Some use-cases include: 5 | 6 | * Requesting events using a different filter after receiving a `/sync` response. 7 | * A client which does not need to fully sync an account, but wishes to inspect a 8 | specific room's history (perhaps for exporting or auditing). 9 | 10 | 11 | ## Proposal 12 | 13 | The `from` field on the [`/_matrix/client/v3/rooms/{roomId}/messages`](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages) 14 | becomes optional. If it is not provided, the homeserver shall return a list of 15 | messages from the first or last (per the value of the `dir` parameter) visible 16 | event in the room history for the requesting user. 17 | 18 | Note that Synapse already implements this, but it is not spec-compliant. It is 19 | known to be used by Element Android [^1] and Element Web, and there are other 20 | use-cases involving threads [^2], which shows real-world usage that this would 21 | be valuable. 22 | 23 | Ideally this would not be necessary and the `prev_batch` token received from 24 | calling `/sync` could be provided as the pagination token to `/messages`, but this 25 | will not work if you `/sync` with a filter that excludes a given class of event 26 | (such as threaded replies), and all the events taking place in a room are of that 27 | class. This will result in your `/sync` not returning an update for that room, 28 | which means that your most recent `prev_batch` token precedes all the excluded 29 | events. Trying to back-paginate from `prev_batch` using `/messages` will not 30 | result in seeing the excluded events. 31 | 32 | 33 | ## Potential issues 34 | 35 | None. 36 | 37 | 38 | ## Alternatives 39 | 40 | The alternative is today's status quo: a client must first make a request to 41 | `/_matrix/client/v3/sync` and then follow-up that request with queries to 42 | `/_matrix/client/v3/rooms/{roomId}/messages`. This is clunky if the client is 43 | going to throw away most of the information received from the `/sync` request. 44 | 45 | The behavior also seems undefined if a different `filter` parameter is provided 46 | for the call to `/sync` compared to the one used for `/messages`. 47 | 48 | 49 | ## Security considerations 50 | 51 | None. 52 | 53 | 54 | ## Unstable prefix 55 | 56 | Since this is modifying the endpoint to support not including a field, no unstable 57 | prefix is necessary. 58 | 59 | 60 | ## Dependencies 61 | 62 | N/A 63 | 64 | [^1]: https://github.com/matrix-org/synapse/issues/5538 65 | 66 | [^2]: In order to list all threads in a room without pulling the history locally 67 | it uses `/messages` to push the filtering onto the homeserver. See https://github.com/matrix-org/matrix-js-sdk/pull/2065 68 | -------------------------------------------------------------------------------- /proposals/3783-fixed-base64-sas-verification.md: -------------------------------------------------------------------------------- 1 | # MSC3783: Fixed base64 for SAS verification 2 | 3 | libolm's original implementation for calculating the 4 | [MAC](https://spec.matrix.org/v1.5/client-server-api/#mkeyverificationmac) for 5 | SAS-based device verification [encoded the base64 output 6 | incorrectly](https://gitlab.matrix.org/matrix-org/olm/-/merge_requests/16). 7 | Thus other implementations that use a correct base64 encoding are not 8 | compatible, and must instead [re-implement libolm's incorrect 9 | encoding](https://matrix-org.github.io/vodozemac/vodozemac/sas/struct.EstablishedSas.html#method.calculate_mac_invalid_base64). 10 | libolm now has a function that returns the correct base64 encoding, but it is 11 | currently not used to ensure compatibility with older clients. 12 | 13 | This proposal introduces a new message authentication code identifier for use 14 | with SAS verification that uses the correct base64 encoding. The current 15 | method will be deprecated. 16 | 17 | ## Proposal 18 | 19 | A new message authentication code identifier `hkdf-hmac-sha256.v2` is 20 | introduced. This identifier is used in the `message_authentication_codes` 21 | property of the 22 | [`m.key.verification.start`](https://spec.matrix.org/v1.5/client-server-api/#mkeyverificationstartmsasv1) 23 | event, and the `message_authentication_code` property of the 24 | [`m.key.verification.accept`](https://spec.matrix.org/v1.5/client-server-api/#mkeyverificationaccept) 25 | event. Clients that implement SAS verification are required to implement this 26 | method. The `message_authentication_codes` parameter for the 27 | [`m.key.verification.start`](https://spec.matrix.org/v1.5/client-server-api/#mkeyverificationstartmsasv1) 28 | event will require clients to include `hkdf-hmac-sha256.v2`. Clients are no 29 | longer required to include `hkdf-hmac-sha256`, but should still do so for 30 | compatibility with older clients. 31 | 32 | When the two clients that are verifying each other agree to use 33 | this method, the MAC is calculated in the same way as `hkdf-hmac-sha256`, but 34 | is encoded to base64 correctly. 35 | 36 | The old `hkdf-hmac-sha256` method is redefined to use the base64 encoding 37 | implemented in the original libolm implementation, and is deprecated: if both 38 | clients involved in the verification support `hkdf-hmac-sha256.v2` as the 39 | message authentication code, then `hkdf-hmac-sha256` must not be used, even if 40 | both clients support it. 41 | 42 | `hkdf-hmac-sha256` will be removed by a future MSC. 43 | 44 | ## Potential issues 45 | 46 | None 47 | 48 | ## Alternatives 49 | 50 | None 51 | 52 | ## Security considerations 53 | 54 | This change does not introduce any security issues. 55 | 56 | ## Unstable prefix 57 | 58 | Until this MSC is accepted, the key agreement protocol identifier 59 | `org.matrix.msc3783.hkdf-hmac-sha256` should be used instead of 60 | `hkdf-hmac-sha256.v2`. 61 | 62 | ## Dependencies 63 | 64 | None 65 | -------------------------------------------------------------------------------- /proposals/4210-remove-legacy-mentions.md: -------------------------------------------------------------------------------- 1 | # MSC4210: Remove legacy mentions 2 | Matrix v1.7 introduced [intentional mentions], where events list users they 3 | mention explicitly, instead of the recipients inferring mentions from the raw 4 | message text. For backwards-compatibility reasons, messages without the new 5 | `m.mentions` field still use the old plaintext matching for mentions. 6 | 7 | [intentional mentions]: https://spec.matrix.org/v1.15/client-server-api/#user-and-room-mentions 8 | 9 | Plaintext matching means it's very difficult for automated tools to tell which 10 | users are mentioned in a message. This means that it's easy to spam mentions by 11 | simply not using intentional mentions. 12 | 13 | If intentional mentions are mandatory, automated tools could easily ban users 14 | who send more than X mentions in a single message. There could even be a new 15 | push rule condition to allow checking the number of mentioned users and skip 16 | notifying entirely. 17 | 18 | ## Proposal 19 | Support for legacy mentions is dropped. Specifically, the following deprecated 20 | standard push rules are removed entirely: 21 | 22 | * [`.m.rule.contains_display_name`](https://spec.matrix.org/v1.15/client-server-api/#_m_rule_contains_display_name) 23 | * [`.m.rule.contains_user_name`](https://spec.matrix.org/v1.15/client-server-api/#_m_rule_contains_user_name) 24 | * [`.m.rule.roomnotif`](https://spec.matrix.org/v1.15/client-server-api/#_m_rule_roomnotif) 25 | 26 | Additionally, the `contains_display_name` [push rule condition] is deprecated. 27 | 28 | [push rule condition]: https://spec.matrix.org/v1.15/client-server-api/#conditions-1 29 | 30 | Including an empty `m.mentions` key is still required for clients that are 31 | aware of intentional mentions, as omitting it would cause current clients to 32 | assume messages are not using intentional mentions. 33 | 34 | ## Potential issues 35 | Users using old clients (which don't send intentional mentions) will no longer 36 | be able to mention users on up-to-date clients/servers. 37 | 38 | Users using old clients (which don't support the new push rule conditions) will 39 | also no longer be notified for mentions in case the client depends on the push 40 | rules served by the server. 41 | 42 | ## Alternatives 43 | The removal could be done in a new room version, such as when switching to 44 | extensible events, as suggested by [MSC3952]. However, such a migration will 45 | likely take much longer than clients implementing intentional mentions. 46 | Additionally, the room upgrade UX is still an open issue, which means many 47 | rooms simply don't upgrade. Therefore, making a slightly breaking change to 48 | existing room versions seems like the better option. 49 | 50 | [MSC3952]: https://github.com/matrix-org/matrix-spec-proposals/pull/3952 51 | 52 | ## Security considerations 53 | This proposal doesn't add any features, so there are no new security 54 | considerations. 55 | 56 | ## Unstable prefix 57 | Not applicable, this proposal only removes features. 58 | 59 | ## Dependencies 60 | None. 61 | -------------------------------------------------------------------------------- /proposals/1961-integrations-auth.md: -------------------------------------------------------------------------------- 1 | # MSC1961: Integration manager authentication 2 | 3 | A set of common APIs needs to be defined for clients to be able to interact with an integration 4 | manager. This proposal covers the authentication portion of that API. 5 | 6 | **Note**: this proposal is part of a larger "Integrations API" which has not yet been defined. 7 | See [MSC1956](https://github.com/matrix-org/matrix-doc/pull/1956) for details. 8 | 9 | 10 | ## Proposal 11 | 12 | All specified APIs (except `/register`) will take an `Authorization` header with a `Bearer` token returned 13 | from a call to `/register`. This token is used to authorize the request and to identify who is making the 14 | request. The token may also be specified as the `access_token` query string parameter, similar to the 15 | Client-Server API. 16 | 17 | #### POST `/_matrix/integrations/v1/account/register` 18 | 19 | Exchanges an OpenID object for a token which can be used to authorize future requests to the manager. 20 | 21 | Request body is an OpenID object as returned by `/_matrix/client/r0/user/:userId/openid/request_token`. 22 | 23 | Response is: 24 | ```json 25 | { 26 | "token": "OpaqueString" 27 | } 28 | ``` 29 | 30 | The token should consist of URL-safe base64 characters. Integration managers should be careful to validate 31 | the OpenID object by ensuring the `/_matrix/federation/v1/openid/userinfo` response has a `sub` which belongs 32 | to the `matrix_server_name` provided in the original OpenID object. 33 | 34 | Applications which register for a token are responsible for tracking which integration manager they are for. 35 | This can usually be done by tracking the hostname of the integration manager and matching a token with it. 36 | 37 | #### GET `/_matrix/integrations/v1/account` 38 | 39 | Gets information about the token's owner, such as the user ID for which it belongs. 40 | 41 | Besides a token, no other information is required for the request. 42 | 43 | Response is: 44 | ```json 45 | { 46 | "user_id": "@alice:example.org" 47 | } 48 | ``` 49 | 50 | The `user_id` is the user ID which was represented in the OpenID object provided to `/register`. Integration 51 | managers may be interested in also supplying information about the user's credit balance for paid integrations 52 | here. Preferably, custom information is stored under a namespaced key like so: 53 | ```json 54 | { 55 | "user_id": "@alice:example.org", 56 | "org.example.paid.integrations": { 57 | "credit": 20000 58 | } 59 | } 60 | ``` 61 | 62 | #### POST `/_matrix/integrations/v1/account/logout` 63 | 64 | Logs the token out, rendering it useless for future requests. 65 | 66 | Request body is an empty object. Response body is also an empty object if successful. 67 | 68 | 69 | ## Security considerations 70 | 71 | Clients should be sure to call `/logout` where possible when the user is logging out or no longer needs access 72 | to a given manager. Clients should additionally be cautious about which managers they register for tokens with, 73 | as some integration managers may be untrusted. 74 | -------------------------------------------------------------------------------- /proposals/2874-single-ssss.md: -------------------------------------------------------------------------------- 1 | # MSC2874: Single SSSS 2 | 3 | [Secure Secret Storage and 4 | Sharing](https://github.com/matrix-org/matrix-doc/pull/1946) (SSSS) was 5 | designed to allow the user to create multiple keys that would be able to 6 | decrypt different subsets of the secrets. However, the vast majority of users 7 | do not need this feature. 8 | 9 | This proposal defines how clients should behave if they only wish to support a 10 | single key, by defining which key clients should use if multiple keys are 11 | present. It also makes the `name` field in the `m.secret_storage.key.*` events 12 | optional, as this field was mainly added to allow a user to select between 13 | different keys. 14 | 15 | ## Proposal 16 | 17 | If a client wants to present a simplified interface to users by not supporting 18 | multiple SSSS keys, then the client should use the default key (the key listed 19 | in the `m.secret_storage.default_key` account data event.) If there is no 20 | default key the client may behave as if there is no SSSS key at all. When such 21 | a client creates an SSSS key, it must mark that key as being the default key. 22 | 23 | The `name` field in the `m.secret_storage.key.*` account data events is 24 | optional, rather than required. If a client wishes to display multiple keys to 25 | a user and a given key does not have a `name` field, the client may use a 26 | default name as the key's name, such as "Unnamed key", or "Default key" if the 27 | key is marked as default. 28 | 29 | For example, when a client creates a key with ID `abcdefg`, it will create an 30 | `m.secret_storage.key.abcdefg` account data event to store information about 31 | the key. It will then mark it as the default key by setting the 32 | `m.secret_storage.default_key` account data to `{"key": "abcdefg"}`. When 33 | another client logs in after this, it will see that the default key has been 34 | set, and will know to use that key as the SSSS key. 35 | 36 | ## Potential issues 37 | 38 | If secrets are encrypted using a key that is not marked as default, a client 39 | might not decrypt the secrets, even if it would otherwise be able to. 40 | 41 | ## Alternatives 42 | 43 | Rather than solely relying on the key marked as default, a client could guess 44 | at what key to use. For example, it could look at the secrets that it needs, 45 | see what keys they are encrypted with, and if there is only one common key, 46 | then it could use that. (This is what Element currently does.) Or if there 47 | are multiple keys, it could use some sort of heuristic to pick a key. However, 48 | this approach can be error-prone, and it is better to rely on an explicit 49 | marking. 50 | 51 | ## Security considerations 52 | 53 | None 54 | 55 | ## Unstable prefix 56 | 57 | An unstable prefix is not needed for a behaviour change in choosing the key to 58 | use as there are no event/endpoint changes. 59 | 60 | Some clients already omit the `name` field (notably, matrix-js-sdk 61 | unintentionally does this -- mea culpa), and this does not seem to be causing 62 | issues, so an unstable prefix seems unnecessary for this. 63 | -------------------------------------------------------------------------------- /proposals/1719-olm_unwedging.md: -------------------------------------------------------------------------------- 1 | # Olm unwedging 2 | 3 | Olm sessions sometimes get out of sync, resulting in undecryptable messages. 4 | This can happen for several reasons. For example, if a user restores their 5 | client state from a backup, the client will be using an old ratchet state 6 | ([riot-web#3822](https://github.com/vector-im/riot-web/issues/3822)). Or a 7 | client might expire a one-time key that another client is trying to use 8 | ([riot-web#3309](https://github.com/vector-im/riot-web/issues/3309)). This 9 | proposal documents a method for devices to create a new session to replace the 10 | broken session. 11 | 12 | ## Proposal 13 | 14 | When a device receives an olm-encrypted message that it cannot decrypt, it 15 | should assume that the olm session has become corrupted and create a new olm 16 | session to replace it. It should then send a dummy message, using that 17 | session, to the other party in order to inform them of the new session. To 18 | send a dummy message, clients may send an event with type `m.dummy`, and with 19 | empty contents. 20 | 21 | In order to avoid creating too many extra sessions, a client should rate-limit 22 | the number of new sessions it creates per device that it receives a message 23 | from; the client should not create a new session with another device if it has 24 | already created one for that given device in the past 1 hour. 25 | 26 | Clients may wish to take steps to mitigate the loss of the undecryptable 27 | messages. For example, megolm sessions that were sent using the old session 28 | would have been lost, so the client can send 29 | [`m.room_key_request`](https://matrix.org/docs/spec/client_server/r0.6.1.html#m-room-key-request) 30 | messages to re-request any megolm sessions that it is unable to decrypt. 31 | 32 | The spec currently says, "If a client has multiple sessions established with 33 | another device, it should use the session from which it last received a 34 | message." (the last paragraph of the [`m.olm.v1.curve25519-aes-sha2` 35 | section](https://matrix.org/docs/spec/client_server/r0.4.0.html#m-olm-v1-curve25519-aes-sha2)). 36 | When comparing the time of the last received message for each session, the 37 | client should only consider messages that were successfully decrypted, 38 | and for sessions that have never received a message, it should use the creation 39 | time of the session. The spec will be changed to read: 40 | 41 | > If a client has multiple sessions established with another device, it should 42 | > use the session from which it last received and successfully decrypted a 43 | > message. For these purposes, a session that has not received any messages 44 | > should use its creation time as the time that it last received a message. 45 | 46 | ## Tradeoffs 47 | 48 | ## Potential issues 49 | 50 | ## Security considerations 51 | 52 | An attacker could use this to create a new session on a device that they are 53 | able to read. However, this would require the attacker to have compromised the 54 | device's keys. 55 | 56 | ## Conclusion 57 | 58 | This proposal outlines how wedged olm sessions can be replaced by a new 59 | session. 60 | -------------------------------------------------------------------------------- /proposals/2758-textual-id-grammar.md: -------------------------------------------------------------------------------- 1 | # MSC2758: Common grammar for textual identifiers 2 | 3 | The matrix specification uses textual identifiers for a wide range of 4 | concepts. Examples include "event types" and "room versions". 5 | 6 | In the past, these identifiers have often lacked a formal grammar, leaving 7 | servers and clients to make assumptions about questions such as which 8 | characters are permitted, minimum and maximum lengths, etc. 9 | 10 | This proposal suggests a common grammar which can be used as a basis for 11 | *future* identifier types, to reduce the work involved in future specification 12 | work. 13 | 14 | No attempt is made here to bring existing identifiers into line; however 15 | examples of identifiers which might have benefitted from such a grammar in the 16 | past include: 17 | 18 | * [`capabilities`](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-capabilities) 19 | identifiers. 20 | * authentication types for the [User-Interactive Authentication mechanism](https://matrix.org/docs/spec/client_server/r0.6.0#user-interactive-authentication-api). 21 | * login types for [`/_matrix/client/r0/login`](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-login). 22 | * event types 23 | * [`m.room.message` `msgtypes`](https://matrix.org/docs/spec/client_server/r0.6.0#m-room-message-msgtypes) 24 | * `app_id` for [`POST /_matrix/client/r0/pushers/set`](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-pushers-set). 25 | * `rule_ids`, `actions` and `tweaks` for [push rules](https://matrix.org/docs/spec/client_server/r0.6.0#push-rules). 26 | * [E2E messaging algorithm names](https://matrix.org/docs/spec/client_server/r0.6.0#messaging-algorithm-names). 27 | 28 | ## Proposal 29 | 30 | We define a "common namespaced identifier grammar". This can then be referenced 31 | by other parts of the grammar, in much the same way as [Unpadded 32 | Base64](https://matrix.org/docs/spec/appendices#unpadded-base64) is defined 33 | today. 34 | 35 | The grammar is defined as follows: 36 | 37 | * An identifier may not be less than one character or more than 255 characters 38 | in length. 39 | * Identifiers must start with one of the characters `[a-z]`, and be entirely 40 | composed of the characters `[a-z]`, `[0-9]`, `-`, `_` and `.`. 41 | * Identifiers starting with the characters `m.` are reserved for use by the 42 | formal matrix specification. 43 | * Implementations wishing to implement unspecified identifiers should follow 44 | the Java Package Naming convention of starting with a reversed domain 45 | name (with a dot after the domain name part). For example, for the 46 | organisation `example.com`, a valid identifier would be 47 | `com.example.identifier`. 48 | 49 | This grammar is intended for use entirely by internal identifiers, and *not* 50 | for user-visible strings. 51 | 52 | ### Rationale 53 | 54 | * Avoiding non-ascii characters sidesteps any issues with homoglyphs or 55 | alternative encodings of the same characters. 56 | * Avoiding upper-case character sidesteps any concerns over case-sensitivity. 57 | -------------------------------------------------------------------------------- /proposals/3589-v9-default-version.md: -------------------------------------------------------------------------------- 1 | # MSC3589: Room version 9 as a default 2 | 3 | Enough time has passed to allow the public federation to upgrade their servers to support room 4 | version 9, though with some caveats (see "potential issues"). This proposal aims to make v9 the 5 | default room version. 6 | 7 | ## Proposal 8 | 9 | The specification adopts v9 as the suggested default room version, making no changes to the stability 10 | of any room versions. As of writing, v6 is currently the suggested room version. 11 | 12 | Room version 9 is currently published here: https://spec.matrix.org/v1.2/rooms/v9/ 13 | 14 | ## Potential issues 15 | 16 | Servers will be encouraged to update their config/internal defaults to use v9 instead of v6. This 17 | is considered a good problem to have. 18 | 19 | Note that servers are not required to honour the default room version due to it being a suggestion 20 | in the specification, however they might fall behind as other servers set their defaults accordingly. 21 | 22 | Some server implementations, like Synapse, support configurable default room versions: servers which 23 | have set this flag will not necessarily be affected by this change. 24 | 25 | As of writing (Jan 26, 2022), some prominent server implementations are only just getting support for 26 | the room version. Namely, Dendrite released a version with support about 2 months ago and Conduit is 27 | working on including Ruma's changes which landed also about 2 months ago. 28 | 29 | Though both Dendrite and Conduit (meaning Ruma) have not had the same amount of time as Synapse to 30 | reach maturity on v9-capable versions, both the Dendrite and Conduit communities appear to update to 31 | newer versions much more quickly. This implies, without statistics to back it up, that nearly all 32 | Dendrite servers out there will have upgraded and that a similar percentage of Conduit servers will 33 | upgrade once available. 34 | 35 | No major issues appear to be reported to Synapse or Dendrite with respect to v9, however Conduit 36 | has [reported](https://gitlab.com/famedly/conduit/-/merge_requests/257#note_814327701) that the auth 37 | rules for v9 might not be perfect. All of this indicates to the author that the implementation is at 38 | least sane and accomplishable, even if a bit difficult to incorporate. 39 | 40 | For completeness, some links: 41 | 42 | **Dendrite**: 43 | 44 | * Tracking issue: https://github.com/matrix-org/dendrite/issues/2010 45 | * Library support: https://github.com/matrix-org/gomatrixserverlib/pull/279 46 | * Release: https://github.com/matrix-org/dendrite/commit/b4a007ecceafd2b93fee2e775b0a61283d4a3844 47 | * Testing: https://github.com/matrix-org/complement/pull/220 48 | 49 | **Conduit**: 50 | 51 | * Tracking issue: https://gitlab.com/famedly/conduit/-/issues/161 52 | * Library support: https://github.com/ruma/ruma/pull/771 53 | * Release: N/A 54 | * Testing: N/A 55 | 56 | ## Alternatives 57 | 58 | None relevant. 59 | 60 | ## Security considerations 61 | 62 | None relevant. 63 | 64 | ## Unstable prefix 65 | 66 | None relevant - servers can already choose a different default room version legally. This MSC 67 | just formalizes v9 as the default. 68 | -------------------------------------------------------------------------------- /proposals/3828-content-repository-corp-headers.md: -------------------------------------------------------------------------------- 1 | # MSC3828: Content Repository Cross Origin Resource Policy (CORP) Headers 2 | 3 | In 2018 two side-channel hardware vulnerabilities, 4 | [Meltdown](https://en.wikipedia.org/wiki/Meltdown_(security_vulnerability)) 5 | and [Spectre](https://en.wikipedia.org/wiki/Spectre_(security_vulnerability)) were disclosed. 6 | In web browsers this meant that features such as high resolution timers and SharedArrayBuffer 7 | could be used to expose sensitive data across origins. In response, browser vendors have 8 | required documents that wish to continue using features such as SharedArrayBuffer to be 9 | served with the `Cross-Origin-Embedder-Policy: require-corp` header. This header prevents a 10 | document from loading any cross-origin resources that don't explicitly grant the document 11 | permission via the `Cross-Origin-Resource-Policy` header. 12 | 13 | Currently Matrix homeservers are expected to serve all routes with the 14 | `Access-Control-Allow-Origin: *` header. This allows web clients on one origin to fetch 15 | content from homeservers on other origins. However, when the web client uses SharedArrayBuffer 16 | and the required `Cross-Origin-Embedder-Policy: require-corp` header, all embedded documents 17 | must set the required CORP header. 18 | 19 | ## Proposal 20 | 21 | The content repository should serve assets with the `Cross-Origin-Resource-Policy: cross-origin` 22 | header. This allows web clients to set the `Cross-Origin-Embedder-Policy: require-corp` 23 | header and enable access to APIs like SharedArrayBuffer. 24 | 25 | This header should be set on responses from the following endpoints: 26 | 27 | - `/_matrix/media/v3/download` 28 | - `/_matrix/media/v3/thumbnail` 29 | 30 | ## Potential issues 31 | 32 | Chrome 73-75 have problems downloading files with this header, see [bug 952834](https://crbug.com/952834). 33 | Chrome 80-85 has a [bug](https://crbug.com/1074261) with viewing multi-page PDF documents with CORP 34 | headers set to `same-origin`. This proposal is for setting the header to `cross-origin` which should 35 | not have an issue but I was not able to verify this. However, 36 | [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy_(CORP)#browser_compatibility) 37 | suggests this bug was fixed in Chrome 86 by disabling partial PDF loading. I was able to verify that 38 | multi-page PDFs are viewable in the latest versions of Chrome, Safari, and Firefox with either header 39 | value set. This should only be an issue if you require supporting Chrome 73-75. 40 | 41 | Also see [Security considerations](#Security-considerations) 42 | 43 | ## Alternatives 44 | 45 | Clients using features like SharedArrayBuffer cannot fetch media from the Matrix media 46 | repositories without these headers. 47 | 48 | 49 | ## Security considerations 50 | 51 | I don't believe this poses any additional risks to private data from Matrix homeservers. 52 | We are not exposing iframes with personal data or any data that could not already be 53 | gathered from Matrix's existing APIs. However, I believe this proposal deserves thorough review. 54 | 55 | ## Unstable prefix 56 | 57 | None 58 | 59 | ## Dependencies 60 | 61 | None 62 | -------------------------------------------------------------------------------- /proposals/4156-server-name-to-via.md: -------------------------------------------------------------------------------- 1 | # MSC4156: Migrate `server_name` to `via` 2 | 3 | Room IDs in Matrix are generally not routable on their own. In the [room ID grammar] `!opaque_id:domain`, 4 | the `domain` is the server that created the room. There is, however, no guarantee that this server is 5 | still joined to the room at a later time. Therefore, room IDs don't provide a reliable resident server 6 | to send requests to. Critically, the `domain` is not to be used as a routing server. It is purely a namespace. 7 | 8 | The spec partially addresses this issue by defining a [`via`] query parameter on room URIs that can be 9 | used to list servers that have a high probability of being in the room in the distant future. Additionally, 10 | some APIs such as [`/_matrix/client/v3/join/{roomIdOrAlias}`] can take a `server_name` query parameter 11 | that has the same effect as `via`. 12 | 13 | The terminology difference between `server_name` and `via` can be slightly confusing which is why this 14 | proposal attempts to standardize on `via`. 15 | 16 | 17 | ## Proposal 18 | 19 | The `server_name` query parameter on [`/_matrix/client/v3/join/{roomIdOrAlias}`] and 20 | [`/_matrix/client/v3/knock/{roomIdOrAlias}`] is deprecated and a new parameter `via: [string]` is 21 | introduced. 22 | 23 | Clients SHOULD use `via` when the homeserver they're talking to supports it. To do this, they MAY either 24 | detect server support through the supported spec versions in [`/_matrix/client/versions`] or always include 25 | both parameters (with identical values). 26 | 27 | Homeservers MUST ignore all `server_name` parameters if any `via` parameters are supplied. 28 | 29 | 30 | ## Potential issues 31 | 32 | As with any migration, some effort will be required to update client and server implementations. Additionally, 33 | while the transitions isn't completed, the concurrent existence of both query parameters might lead to further 34 | confusion. 35 | 36 | 37 | ## Alternatives 38 | 39 | None other than accepting status quo. 40 | 41 | 42 | ## Security considerations 43 | 44 | A client that supplies different `via` and `server_name` parameters could be served a different room depending 45 | on which set of parameters the server uses to resolve the room ID. Tricking a client into doing this seems very 46 | difficult though because [Matrix URIs], for instance, only have a single documented `via` parameter. 47 | 48 | 49 | ## Unstable prefix 50 | 51 | Until this proposal is accepted into the spec, implementations SHOULD refer to `via` as `org.matrix.msc4156.via`. 52 | 53 | 54 | ## Dependencies 55 | 56 | None. 57 | 58 | 59 | [Matrix URIs]: https://spec.matrix.org/v1.11/appendices/#matrix-uri-scheme 60 | [room ID grammar]: https://spec.matrix.org/v1.10/appendices/#room-ids 61 | [`via`]: https://spec.matrix.org/v1.10/appendices/#routing 62 | [`/_matrix/client/v3/join/{roomIdOrAlias}`]: https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3joinroomidoralias 63 | [`/_matrix/client/v3/knock/{roomIdOrAlias}`]: https://spec.matrix.org/v1.10/client-server-api/#post_matrixclientv3knockroomidoralias 64 | [`/_matrix/client/versions`]: https://spec.matrix.org/v1.10/client-server-api/#get_matrixclientversions 65 | -------------------------------------------------------------------------------- /proposals/3987-push-actions-clean-up.md: -------------------------------------------------------------------------------- 1 | # MSC3987: Push actions clean-up 2 | 3 | There are [two defined push rule actions](https://spec.matrix.org/v1.6/client-server-api/#actions) 4 | which are of dubious use: 5 | 6 | * `coalesce` is defined, but unused in the spec and not implemented on any homeservers [^1] 7 | or clients [^2] beyond validating it or treating it identically to `notify`. 8 | * `dont_notify` is a no-op, but frequently used as a way to denote do nothing. 9 | It is clearer to provide an empty list of actions to avoid a situation where 10 | additional actions are given with it, e.g. `["notify", "dont_notify"]` is 11 | currently valid, but does not make sense. [^3] 12 | 13 | ## Proposal 14 | 15 | The `coalesce` push rule action is removed from the Matrix specification. 16 | 17 | The `dont_notify` push rule action is deprecated. Homeservers and clients should 18 | ignore it. Any [pre-defined rules](https://spec.matrix.org/v1.6/client-server-api/#actions) 19 | which include the `dont_notify` action are redefined to have an empty list of actions: 20 | 21 | * `.m.rule.master` 22 | * `.m.rule.suppress_notices` 23 | * `.m.rule.member_event` 24 | 25 | It is recommended that homeservers continue accepting the `coalesce` and `dont_notify` 26 | actions, but ignore them during processing. (Treating them as no-ops.) A future 27 | Matrix spec version should remove them completely. 28 | 29 | ## Potential issues 30 | 31 | A client might attempt to create a push rule with a `coalesce` or `dont_notify` 32 | action that homeservers will reject as an unknown action. 33 | 34 | ## Alternatives 35 | 36 | Do nothing and continue propagating confusion. 37 | 38 | ## Security considerations 39 | 40 | None. 41 | 42 | ## Dependencies 43 | 44 | None. 45 | 46 | [^1]: [Dendrite](https://github.com/search?q=repo%3Amatrix-org%2Fdendrite+CoalesceAction+NOT+path%3A%2F_test.go%24%2F&type=code), 47 | [Synapse](https://github.com/search?q=repo%3Amatrix-org%2Fsynapse+coalesce+language%3ARust&type=code&l=Rust), 48 | [Conduit](https://gitlab.com/search?search=coalesce&nav_source=navbar&project_id=22083768&group_id=4616224&search_code=true&repository_ref=next), 49 | [Construct](https://github.com/matrix-construct/construct/blob/4ecf1ef037ecc1a5d1e3a1049d9a63cb0a6f3455/matrix/push.cc#L739-L740).. 50 | 51 | [^2]: [matrix-js-sdk](https://github.com/search?q=repo%3Amatrix-org/matrix-js-sdk%20Coalesce&type=code), 52 | [matrix-ios-sdk](https://github.com/search?q=repo%3Amatrix-org%2Fmatrix-ios-sdk%20coalesce&type=code), 53 | [matrix-rust-sdk](https://github.com/matrix-org/matrix-rust-sdk/commit/59edc22a35c4ef162ea0a8cafccdf25e37ab1070), 54 | [matrix-android-sdk2](https://github.com/search?q=repo%3Amatrix-org/matrix-android-sdk2%20ACTION_COALESCE&type=code), 55 | [Ruma](https://github.com/search?q=repo%3Aruma/ruma%20Coalesce&type=code). 56 | 57 | [^3]: It has been noted on recent MSCs that new rules should not use `dont_notify`, 58 | see [MSC3786](https://github.com/matrix-org/matrix-spec-proposals/pull/3786#discussion_r864607531), 59 | [MSC2153](https://github.com/matrix-org/matrix-spec-proposals/pull/2153#discussion_r450188777) / 60 | [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677#discussion_r879701007). 61 | -------------------------------------------------------------------------------- /proposals/1794-federation-v2-invites.md: -------------------------------------------------------------------------------- 1 | # MSC 1794 - Federation v2 Invite API 2 | 3 | This proposal adds a new `/invite` API to federation that supports different 4 | room versions. 5 | 6 | ## Motivation 7 | 8 | It is planned for future room versions to be able to change the format of events 9 | in various ways. To support this, all servers must know the room version 10 | whenever they need to parse an event. Currently the `/invite` API does not 11 | include the room version, so the target server would be unable to parse the event included in the payload. 12 | 13 | ## Proposal 14 | 15 | Add a new version of the invite API under the prefix `/_matrix/federation/v2`, 16 | which has a payload of: 17 | 18 | ``` 19 | PUT /_matrix/federation/v2/invite// 20 | 21 | { 22 | "room_version": , 23 | "event": { ... }, 24 | "invite_room_state": [ ... ] 25 | } 26 | ``` 27 | 28 | The differences between this and `v1` are: 29 | 30 | 1. The payload in `v1` is the event, while in `v2` the event is instead placed 31 | under an `"event"` key. This is for consistency with other APIs, and to allow 32 | extra data to be added to the request payload separately from the event. 33 | 2. A required field called `"room_version"` is added that specifies the room 34 | version. 35 | 3. The `"invite_room_state"` is moved from the `unsigned` section of the event 36 | to a top level key. The key `invite_room_state` being in the `event.unsigned` 37 | was a hack due to point 1. above. 38 | 39 | 40 | The response is identical to `v1`, except that: 41 | 42 | 1. If the receiving server does not support the given room version the 43 | appropriate incompatible-room-version error is returned, in the same way 44 | as e.g. for `/make_join` APIs. 45 | 2. The response payload is no longer in the format of `[200, { ... }]`, and is 46 | instead simply the `{ ... }` portion. This fixes a historical accident to 47 | bring the invite API into line with the rest of the federation API. 48 | 49 | 50 | If a call to `v2` `/invite` results in an unrecognised request exception **AND** 51 | the room version is `1` or `2` then the sending server should retry the request 52 | with the `v1` API. 53 | 54 | 55 | ## Alternatives 56 | 57 | 58 | ### Reusing V1 API 59 | 60 | One alternative is to add a `room_version` query string parameter to the `v1` 61 | `/invite` API in a similar way as for the `/make_join` APIs. However, older 62 | servers would ignore the query string parameter while processing an incoming 63 | `/invite` request, resulting in the server attempting to parse the event in the 64 | old `v1` format. This would likely result in either a `400` or `500` response, 65 | which the sending server could interpret as the receiving server not supporting 66 | the room version. 67 | 68 | This method, however, is fragile and could easily mask legitimate `400` and 69 | `500` errors that are not due to not supporting the room version. 70 | 71 | 72 | ### Using V1 API for V1 room versions 73 | 74 | Instead of all servers attempting to use the new API and falling back if the API 75 | is not found, servers could instead always use the current API for V1 and V2 76 | rooms. 77 | 78 | However, this would not allow us to deprecate the `v1` API. 79 | -------------------------------------------------------------------------------- /proposals/3860-media-download-redirect.md: -------------------------------------------------------------------------------- 1 | # MSC3860: Media Download Redirects 2 | 3 | Currently the media download endpoints must return either a 200 with content or error responses. This 4 | means the media server instance must stream the data from wherever it is stored, which is likely not 5 | local to itself. Allowing redirects on these endpoints would make it possible for the media repo to 6 | tell clients/servers to pull data direct from the source, e.g. a CDN. 7 | 8 | Additionally redirects could be used to avoid downloading media from untrusted homeservers. Currently 9 | users can make their homeserver download, cache and proxy any matrix mid that I want, including 10 | bad/illegal content. Allowing for a 307 redirect would permit cautious server operators to not 11 | store and provide any media that floats in the matrixverse, but just refer to the "original" media. 12 | 13 | ## Proposal 14 | 15 | This MSC proposes that a 307 or 308 redirect code is allowed and followed according to the `Location` 16 | header. It is possible some clients would already follow these which needs to be confirmed. Specific 17 | endpoints in question ([current spec link for these](https://spec.matrix.org/v1.6/client-server-api/#get_matrixmediav3downloadservernamemediaid)): 18 | 19 | + `/_matrix/media/v3/download/{serverName}/{mediaId}` 20 | + `/_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}` 21 | + `/_matrix/media/v3/thumbnail/{serverName}/{mediaId}` 22 | 23 | To prevent breaking clients that don't properly follow the redirect response this functionality will 24 | be enabled by a query string flag `allow_redirect=true`. So specifically in the above cases if a 25 | client respects redirect responses it can make requests like so to the media endpoints: 26 | 27 | + `/_matrix/media/v3/download/{serverName}/{mediaId}?allow_redirect=true` 28 | + `/_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}?allow_redirect=true` 29 | + `/_matrix/media/v3/thumbnail/{serverName}/{mediaId}?allow_redirect=true` 30 | 31 | In the case where a client wishes not to redirect (either implicitly with no parameter or explicitly 32 | providing `allow_redirect=false`) the server must continue to serve media directly with no redirect. 33 | 34 | ## Potential Issues 35 | 36 | None for clients, as opt-in functionality this change is 100% backwards compatible. 37 | 38 | With redirects it becomes easier to force another homeserver to be your CDN, which isn't great 39 | (clients could already do that, but not without recompiling). 40 | 41 | Redirects also potentially allow changing of media underneath the users as different redirects could 42 | be returned over time. It is worth noting that a badly behaving media server can already just return 43 | different content as well. 44 | 45 | ## Alternatives 46 | 47 | None at this time. 48 | 49 | ## Security Considerations 50 | 51 | A media repo could redirect requests to a bad actor, although this would make the primary media 52 | repo itself a bad actor, thus this does not present any increased security issues. 53 | 54 | ## Unstable Prefix 55 | 56 | Until this functionality has landed in the spec, the `allow_redirect` query 57 | parameter should be prefixed with `com.beeper.msc3860.`: 58 | 59 | ``` 60 | ?com.beeper.msc3860.allow_redirect=true 61 | ``` 62 | -------------------------------------------------------------------------------- /proposals/2367-membership-reasons.md: -------------------------------------------------------------------------------- 1 | # Allowing Reasons in all Membership Events 2 | 3 | Currently users can specify a reason for kicking or banning users in a room 4 | that both the target and other users in a room can see. This is useful to 5 | explain *why* an action without having to send separate messages. 6 | 7 | The proposal extends this to all events, including invites, invite rejections 8 | and leaves for similar reasons. 9 | 10 | ## Proposal 11 | 12 | Allow `reason` field to be specified for all of the following APIs: 13 | 14 | ``` 15 | POST /_matrix/client/r0/rooms/{roomId}/invite 16 | POST /_matrix/client/r0/rooms/{roomId}/leave 17 | POST /_matrix/client/r0/rooms/{roomId}/kick 18 | POST /_matrix/client/r0/rooms/{roomId}/ban 19 | POST /_matrix/client/r0/rooms/{roomId}/unban 20 | POST /_matrix/client/r0/rooms/{roomId}/join 21 | POST /_matrix/client/r0/join/{roomIdOrAlias} 22 | PUT /_matrix/client/r0/rooms/{roomId}/state/m.room.member/{userID} 23 | ``` 24 | 25 | If specified the `reason` field will be added to the generated membership 26 | event's content. 27 | 28 | *Note: `/state/m.room.member` API currently allows this as clients can specify 29 | arbitrary content already* 30 | 31 | Clients may choose to display the reason for membership events in a room, 32 | though may not do so if e.g. they have collapsed a set of membership changes. 33 | 34 | Clients should not display an invite reason by default to the invitee as this 35 | allows a classic abuse and harassment vector. However, clients may wish to show 36 | invite reasons from known¹ senders, or have a button that allows viewing any 37 | invite reason. 38 | 39 | ## Use Cases 40 | 41 | Some basic use cases and examples are given below. 42 | 43 | ### Kick/ban 44 | 45 | Kicking and banning already allow specifying a reason to allow giving a reason 46 | for the moderation action (e.g. "Banned for spamming"). 47 | 48 | ### Leaving a Room 49 | 50 | A user may wish to leave a room e.g. because the room is no longer relevant 51 | to them, allowing them to specify a reason means they can easily step out of 52 | the room quietly without having to send a message to explain their actions. 53 | 54 | ### Invite 55 | 56 | This can be useful to give some context for an invite, e.g. "Alice invites Bob 57 | to get some feedback on the membership reasons MSC". 58 | 59 | ### Rejecting an Invite 60 | 61 | If Alice has invited Bob (and many others) to a room to discuss going to a 62 | concert then Bob may wish to simply reject the invite if he can't make it. 63 | Adding a "will be out of town" reason to the rejection helps Alice to know why 64 | her invite was rejected. 65 | 66 | ### Joining room 67 | 68 | Adding a reason for joining could be used e.g. by automated bots to say why 69 | they're joining. For example a bridge bot may join a room when asked to bridge 70 | the room to an external network, in which case they may have a reason such as 71 | "BridgeBot joined to bridge the room to RemoteNetwork at the request of Alice". 72 | 73 | ## Potential Issues 74 | 75 | The main issue here is ensuring that the invite reason cannot be used as an 76 | abuse vector, however if clients follow the recommendations above this concern 77 | should be mitigated. 78 | 79 | --- 80 | 81 | ¹ This is left up to implementations to decide, if they wish to do so. 82 | -------------------------------------------------------------------------------- /proposals/2263-homeserver-pw-resets.md: -------------------------------------------------------------------------------- 1 | # MSC2263: Give homeservers the ability to handle their own 3PID registrations/password resets 2 | 3 | In order to better protect the privacy of a user, Matrix is wanting to shift to 4 | a model where identity servers have less control over the affairs of the homeserver. 5 | Identity servers are currently used to reset the passwords of users on a given homeserver 6 | as an identity verification technique, however there is no reason why the homeserver 7 | itself can't handle the verification. This proposal allows for a homeserver to verify 8 | the identity of users itself, without the use of an identity server. 9 | 10 | ## Proposal 11 | 12 | The `id_server` parameter is to become optional on the following endpoints: 13 | 14 | * `/_matrix/client/:version/account/3pid/:medium/requestToken` 15 | * `/_matrix/client/:version/register/:medium/requestToken` 16 | * `/_matrix/client/:version/account/password/:medium/requestToken` 17 | 18 | The `id_server` parameter is additionally deprecated with intention of being removed 19 | in a future specification release on the `/register/:medium` and `/account/password/:medium` 20 | endpoints. Once appropriate adoption has been achieved, the specification can safely 21 | remove the parameter as supported. The reason for this deprecation is to completely 22 | remove the identity server's ability to be involved in password resets/registration. 23 | Users wishing to bind their 3rd party identifiers can do so after registration, and 24 | clients can automate this if they so desire. 25 | 26 | Note that `bind_email` and `bind_msisdn` on `/register` have already been removed 27 | by [MSC2140](https://github.com/matrix-org/matrix-doc/pull/2140). 28 | 29 | As per [MSC2140](https://github.com/matrix-org/matrix-doc/pull/2140), an `id_access_token` 30 | is required only if an `id_server` is supplied. 31 | 32 | Although not specified as required in the specification currently, the `id_server` 33 | as part of User-Interactive Authentication is also optional if this proposal is accepted. 34 | When the client requests a token without an `id_server`, it should not specify an 35 | `id_server` in UIA. 36 | 37 | Homeservers can reuse HTTP 400 `M_SERVER_NOT_TRUSTED` as an error code on the `/requestToken` 38 | endpoints listed above if they do not trust the identity server the user is supplying. 39 | 40 | In order to allow client implementations to determine if the homeserver they are developed 41 | against supports `id_server` being optional, an unstable feature flag of `m.require_identity_server` 42 | is to be added to `/versions`. When the flag is `true` or not present, clients must assume 43 | that the homeserver requires an `id_server` (ie: it has not yet considered it optional). 44 | If this proposal is accepted, clients are expected to use the supported specification versions 45 | the homeserver advertises instead of the feature flag's presence. 46 | 47 | ## Tradeoffs 48 | 49 | Homeservers may have to set up MSISDN/email support to their implementations. This is believed 50 | to be of minimal risk compared to allowing the identity server to continue being involved 51 | with password reset/registration. 52 | 53 | ## Security considerations 54 | 55 | The identity server was previously involved with affairs only the homeserver cares about. 56 | This is no longer the case. 57 | -------------------------------------------------------------------------------- /proposals/3666-bundled-aggregations-for-search.md: -------------------------------------------------------------------------------- 1 | # MSC3666: Bundled aggregations for server side search 2 | 3 | [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) defines a way for 4 | homeservers to include events related to a requested event via "bundled aggregations". 5 | These bundled aggregations help a client render a requested event without needing 6 | to fetch additional information from the server. 7 | 8 | As part of MSC2675 the following APIs should include bundled aggregations: 9 | 10 | * `GET /rooms/{roomId}/messages` 11 | * `GET /rooms/{roomId}/context/{eventId}` 12 | * `GET /rooms/{roomId}/event/{eventId}` 13 | * `GET /sync`, only for room sections in the response where limited field is true; 14 | this amounts to all rooms in the response if the since request parameter was 15 | not passed, also known as an initial sync. 16 | * `GET /rooms/{roomId}/relations/{eventId}` 17 | 18 | A noticeable missing API from here is the server side search feature (`POST /search`) 19 | where it is common for a client to not have the full timeline of a room when 20 | receiving results. This would benefit from having the bundled aggregations. 21 | 22 | 23 | ## Proposal 24 | 25 | The server side search API ([`POST /search`](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3search)) 26 | for the `room_events` category will 27 | include bundled aggregations for any matching events returned to the client. 28 | As in [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675), the `unsigned` 29 | field of the results would include `m.relations` where appropriate. This applies to 30 | any events themselves, as well as contextual events returned; these appear as the 31 | following fields: 32 | 33 | * The event itself: `results["search_categories"]["room_events"]["results"]["result"]` 34 | * Each contextual event in: 35 | * `results["search_categories"]["room_events"]["results"]["context"]["events_before"]` 36 | * `results["search_categories"]["room_events"]["results"]["context"]["events_after"]` 37 | 38 | 39 | ## Potential issues 40 | 41 | The `/search` API is already fairly complicated and can be slow for large rooms. 42 | Returning more data from it could cause performance issues. 43 | 44 | 45 | ## Alternatives 46 | 47 | The status quo is that a client can call `/rooms/{roomId}/relations/{eventId}` for 48 | each event in the search results in order to fully render each event. This is 49 | expensive, slow, and bandwidth heavy since clients generally need the aggregated 50 | relations, not each related event. 51 | 52 | Older versions of [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) 53 | included an `/rooms/{roomId}/aggregations/{eventId}` API to fetch the bundled 54 | aggregations for an event directly. This would save on bandwidth and simplify 55 | the work that clients need to achieve, but would still result in needless 56 | roundtrips as it would have to be called per event. 57 | 58 | 59 | ## Security considerations 60 | 61 | None. 62 | 63 | 64 | ## Unstable prefix 65 | 66 | N/A 67 | 68 | 69 | ## Dependencies 70 | 71 | This MSC builds on [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674) 72 | and [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675), which have 73 | been accepted, but are not yet in a released version of the spec at the time of 74 | writing. 75 | -------------------------------------------------------------------------------- /proposals/4132-deprecate-event-on-room-alias-uris.md: -------------------------------------------------------------------------------- 1 | # MSC4132: Deprecate Linking to an Event Against a Room Alias. 2 | 3 | ## Introduction 4 | 5 | The spec supports 2 types of URI, the [Matrix scheme](https://spec.matrix.org/v1.10/appendices/#matrix-uri-scheme) 6 | and [matrix.to](https://spec.matrix.org/v1.10/appendices/#matrixto-navigation) links which allow deep linking to 7 | Matrix users, rooms and events. Event URIs can be constructed against either a room ID or a room alias the latter of 8 | which is fragile issue as a room's alias is mutable and so event links may be broken by changes to the alias. Users 9 | expect deep links to continue working so that older links continue to show the correct content. Therefore it is proposed 10 | to deprecate event links against a room alias. 11 | 12 | 13 | ## Proposal 14 | 15 | As room IDs are immutable, event URIs built against these will continue to work for as long as the room is reachable by 16 | the homeserver. In contrast, event URIs built against a room alias can break under the following circumstances: 17 | - The room is upgraded, resulting in the alias pointing to the new room, which won't contain any events from the 18 | ancestor. 19 | - The alias is removed/changed resulting in a dead link that can't be resolved. 20 | 21 | The proposal would [deprecate](https://spec.matrix.org/v1.10/#deprecation-policy) the 2 following URIs: 22 | - Link to `$event` in `#somewhere:example.org`: `matrix:r/somewhere:example.org/e/event` 23 | - Link to `$event` in `#somewhere:example.org`: `https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org` 24 | 25 | Specifically this means it would be marked in the spec as not to be used in future and clients should: 26 | 1. Stop making new event URIs with room aliases, generating the examples above as the following respectively: 27 | - `matrix:roomid/opaqueid:example.org/e/event?via=example.com` 28 | - `https://matrix.to/#/!opaqueid%3Aexample.org/%24event%3Aexample.org?via=example.com` 29 | 2. Continue to accept them as it will take time for other clients to update and legacy events will continue to exist. 30 | 31 | It is worth nothing that this change would require clients to always add the `via=` fields when building event URIs as 32 | these are expected for URIs that reference a room ID. 33 | 34 | 35 | ## Potential issues 36 | 37 | Whilst most clients do take the sensible route and generate event URIs against a room ID (even when it has an alias), as 38 | it is part of the spec these kinds of links likely exist somewhere in room history and on the World Wide Web. This would 39 | mean that after deprecation clients may still want to handle these URIs when received. 40 | 41 | Additionally, whilst not a new problem some clients don't always update the `via` fields, which poses a problem for 42 | rooms that have lots of single user homeservers: A single user leaving can result in the `via` to become non functional 43 | which over time can result in unreachable room IDs (this is essentially the equivalent of the alias being removed). 44 | 45 | 46 | ## Alternatives 47 | 48 | An alternative would be to leave things as they are, although this wouldn't be the best choice for the user. 49 | 50 | 51 | ## Security considerations 52 | 53 | It is unlikely that accepting this change would introduce any security considerations. 54 | 55 | 56 | ## Dependencies 57 | 58 | N/A 59 | -------------------------------------------------------------------------------- /proposals/4077-process-deprecated-html.md: -------------------------------------------------------------------------------- 1 | # MSC4077: Improved process for handling deprecated HTML features 2 | 3 | The Matrix specification [defines](https://spec.matrix.org/v1.8/client-server-api/#mroommessage-msgtypes) 4 | a subset of HTML which clients *should* use when rendering messages, limiting the possibility for 5 | Cross-Site Scripting (XSS) and similar attacks. Clients are always welcome to use a different subset 6 | in both their send and receive paths, however in practice the recommended set of HTML has become the 7 | baseline standard for support among Matrix client developers. 8 | 9 | Additionally, to fix issues like [tags being deprecated](https://github.com/matrix-org/matrix-spec/issues/1492), 10 | the existing spec process would require an entire MSC to add or remove the tag. This has precedent 11 | through [MSC2422](https://github.com/matrix-org/matrix-spec-proposals/pull/2422) and 12 | [MSC2184](https://github.com/matrix-org/matrix-spec-proposals/pull/2184), where additional HTML 13 | features are analyzed from a security perspective. For example, whether XSS attacks are more probable 14 | or flooding/disruption attempts are made easier. 15 | 16 | This proposal adjusts the MSC process to explicitly allow changes to the supported HTML tags where 17 | the WHATWG has deprecated a feature in favour of another, enabling more rapid iteration and reducing 18 | paperwork for everyone involved. 19 | 20 | ## Proposal 21 | 22 | Where the WHATWG has deprecated a feature of the HTML specification, a Matrix spec PR *may* bypass the 23 | MSC process to use the modern feature instead. In the case of [issue#1492](https://github.com/matrix-org/matrix-spec/issues/1492), 24 | the spec PR is explicitly able to add the `s` tag and remove the `strike` tag. Note that such changes 25 | can also bypass the [deprecation policy](https://spec.matrix.org/v1.8/#deprecation-policy) in this way. 26 | 27 | It is left to the discretion of the spec PR reviewer as to whether an MSC is required. In general, an 28 | MSC should be requested when the replacement HTML feature is not quite the same as the old feature. 29 | The reviewer *may* also decide whether to keep supporting the old, deprecated, feature for some time. 30 | For example, replacing `strike` with `s` may mean that both tags are supported for 1-2 Matrix spec 31 | versions before `strike` can be dropped. 32 | 33 | For clarity, an MSC is always required to add net-new features to the HTML subset, or to remove a 34 | feature entirely. An example of this is [MSC2398](https://github.com/matrix-org/matrix-spec-proposals/pull/2398). 35 | These changes are subject to interoperability and security review, and cannot bypass the MSC process. 36 | 37 | ## Potential issues 38 | 39 | The author notes that this MSC might not need to exist under the banner of pragmatism, however for all 40 | the effort to *not* write an MSC, an MSC has been written for review. 41 | 42 | ## Alternatives 43 | 44 | Critically, without agreement that replacing deprecated HTML features can happen outside the MSC process, 45 | changes to the HTML subset become slow and burdensome for no apparent gain. 46 | 47 | ## Security considerations 48 | 49 | Special care and attention is expected to be taken by spec PR reviewers to ensure that changes are 50 | safe and in line with the semantics of this proposal's guidance. 51 | 52 | ## Unstable prefix 53 | 54 | Not applicable. This is a process MSC. 55 | 56 | ## Dependencies 57 | 58 | None applicable. 59 | -------------------------------------------------------------------------------- /proposals/1929-admin-contact.md: -------------------------------------------------------------------------------- 1 | # MSC1929 Homeserver Admin Contact and Support page 2 | 3 | Currently, contacting a homeserver admin is difficult because you need to have insider knowledge 4 | of who the admin actually is. This proposal aims to fix that by specifying a way to add contact details 5 | of admins, as well as a link to a support page for users who are having issues with the service. 6 | 7 | This proposal aims to fix https://github.com/matrix-org/matrix-doc/issues/484 8 | 9 | ## Proposal 10 | 11 | The proposal suggests adding a new endpoint: `https://{hostname}/.well-known/matrix/support`, 12 | where `hostname` is the server name, without the port number. This is the same as what is used 13 | when performing server discovery. 14 | 15 | The response format should be: 16 | 17 | ```json5 18 | { 19 | "contacts": [ 20 | { 21 | "matrix_id": "@admin:domain.tld", 22 | "email_address": "admin@domain.tld", 23 | "role": "m.role.admin" 24 | }, 25 | { 26 | "email_address": "security@domain.tld", 27 | "role": "m.role.security" 28 | } 29 | ], 30 | "support_page": "https://domain.tld/support.html" 31 | } 32 | ``` 33 | 34 | The `contacts` array is optional, but recommended. 35 | 36 | The `matrix_id` and `email_address` do NOT need to have the same domain as the homeserver. It is expected that 37 | an admin will have a "backup" contact address if the server is down, like an email or alternative mxid on a different homeserver. 38 | 39 | Entries may have a `matrix_id` OR an `email_address`, but at least one MUST be specified. 40 | 41 | `role` is an informal description of what the address(es) are used for. The only two specified in this 42 | proposal are `m.role.admin` and `m.role.security`. 43 | 44 | - `m.role.admin` is a catch-all user for any queries. 45 | - `m.role.security` is intended for sensitive requests 46 | 47 | A value for `role` MUST be specified. Custom values are permitted using the 48 | [common namespaced identifier format](https://spec.matrix.org/v1.8/appendices/#common-namespaced-identifier-grammar). 49 | 50 | `support_page` is an optional property to specify an affiliated page of the homeserver to give users help 51 | specific to the homeserver, like extra login/registration steps. 52 | 53 | At least one valid key should be provided. This means `contacts` should have at least one entry, or the `support_page` should be defined. An empty object is not considered valid, however both `contacts `and `support_page` may be specified together. 54 | 55 | ## Alternative solutions 56 | 57 | Hardcode a given user localpart that should be used as an admin address. 58 | - The account would need to either internally redirect messages intended for @admin:domain.tld to another account(s) 59 | - OR require an admin to regularly sign into this special account to check for messages. Neither of which is useful. 60 | 61 | Specify the same content inside a homeserver endpoint, rather than use `.well-known`. 62 | - This requires the homeserver to be up or responsive, which might be not very useful if trying to report issues with 63 | connectivity. 64 | 65 | Use vCards. 66 | - vCards would add bloat, as the vast majority of a vcards contents is not useful for contacting an admin. 67 | 68 | ## Security considerations 69 | 70 | If the host is compromised, any information could be specified in the well known file which may direct users to send 71 | sensitive information to a malicious user. 72 | -------------------------------------------------------------------------------- /MSC_CHECKLIST.md: -------------------------------------------------------------------------------- 1 | # MSC Checklist 2 | 3 | This document contains a list of final checks to perform on an MSC before it 4 | is accepted. The purpose is to prevent small clarifications needing to be 5 | made to the MSC after it has already been accepted. 6 | 7 | Spec Core Team (SCT) members, please ensure that all of the following checks 8 | pass before accepting a given Matrix Spec Change (MSC). 9 | 10 | MSC authors, feel free to ask in a thread on your PR or in the 11 | [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) room for 12 | clarification of any of these points. 13 | 14 | - [ ] Are [appropriate implementation(s)](https://spec.matrix.org/proposals/#implementing-a-proposal) specified in the MSC’s PR description? 15 | - [ ] Are all MSCs that this MSC depends on already accepted? 16 | - [ ] For each endpoint that is introduced or modified: 17 | - [ ] Have authentication requirements been specified? 18 | - [ ] Have rate-limiting requirements been specified? 19 | - [ ] Have guest access requirements been specified? 20 | - [ ] Are error responses specified? 21 | - [ ] Does each error case have a specified `errcode` (e.g. `M_FORBIDDEN`) and HTTP status code? 22 | - [ ] If a new `errcode` is introduced, is it clear that it is new? 23 | - [ ] Will the MSC require a new room version, and if so, has that been made clear? 24 | - [ ] Is the reason for a new room version clearly stated? For example, modifying the set of redacted fields changes how event IDs are calculated, thus requiring a new room version. 25 | - [ ] Are backwards-compatibility concerns appropriately addressed? 26 | - [ ] Are the [endpoint conventions](https://spec.matrix.org/latest/appendices/#conventions-for-matrix-apis) honoured? 27 | - [ ] Do HTTP endpoints `use_underscores_like_this`? 28 | - [ ] Will the endpoint return unbounded data? If so, has pagination been considered? 29 | - [ ] If the endpoint utilises pagination, is it consistent with [the appendices](https://spec.matrix.org/latest/appendices/#pagination)? 30 | - [ ] An introduction exists and clearly outlines the problem being solved. Ideally, the first paragraph should be understandable by a non-technical audience. 31 | - [ ] All outstanding threads are resolved 32 | - [ ] All feedback is incorporated into the proposal text itself, either as a fix or noted as an alternative 33 | - [ ] While the exact sections do not need to be present, the details implied by the proposal template are covered. Namely: 34 | - [ ] Introduction 35 | - [ ] Proposal text 36 | - [ ] Potential issues 37 | - [ ] Alternatives 38 | - [ ] Dependencies 39 | - [ ] Stable identifiers are used throughout the proposal, except for the unstable prefix section 40 | - [ ] Unstable prefixes [consider](https://github.com/matrix-org/matrix-spec-proposals/blob/main/README.md#unstable-prefixes) the awkward accepted-but-not-merged state 41 | - [ ] Chosen unstable prefixes do not pollute any global namespace (use “org.matrix.mscXXXX”, not “org.matrix”). 42 | - [ ] Changes have applicable [Sign Off](https://github.com/matrix-org/matrix-spec-proposals/blob/main/CONTRIBUTING.md#sign-off) from all authors/editors/contributors 43 | - [ ] There is a dedicated "Security Considerations" section which detail any possible attacks/vulnerabilities this proposal may introduce, even if this is "None.". See [RFC3552](https://datatracker.ietf.org/doc/html/rfc3552) for things to think about, but in particular pay attention to the [OWASP Top Ten](https://owasp.org/www-project-top-ten/). 44 | --------------------------------------------------------------------------------