From 8521c2d6963e878c60a91ffa5ab3d03c245e1cfa Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 13 Nov 2018 11:31:41 -0500 Subject: [PATCH 001/497] initial proposal for key verification methods --- proposals/xxxx-key_verification.md | 126 +++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 proposals/xxxx-key_verification.md diff --git a/proposals/xxxx-key_verification.md b/proposals/xxxx-key_verification.md new file mode 100644 index 00000000..b71fcf34 --- /dev/null +++ b/proposals/xxxx-key_verification.md @@ -0,0 +1,126 @@ +# Key verification mechanisms + +Key verification is an essential part of ensuring that end-to-end encrypted +messages are secure. Matrix may support multiple verification methods that +require sending events; in fact, two such methods have already been proposed. + +This proposal tries to present a common framework for verification methods to +use, and presents a way to request key verification. + +## Proposal + +Each key verification method is identified by a name. Verification method +names defined in the Matrix spec will begin with `m.`, and verification method +names that are not defined in the Matrix spec must be namespaced following the +Java package naming convention. + +If Alice wants to verify keys with Bob, Alice's device may send `to_device` +events to Bob's devices with the `type` set to `m.key.verification.request`, as +described below. The event lists the verification methods that Alice's device +supports. Upon receipt of this message, Bob's client should prompt him to +verify keys with Alice using one of the applicable methods. In order to avoid +displaying stale key verification prompts, if Bob does not interact with the +prompt, it should be automatically hidden 10 minutes after the message is sent +(according to the `timestamp` field), or 2 minutes after the client receives +the message, whichever comes first. The prompt should also be hidden if an +appropriate `m.key.verification.cancel` message is received. If Bob chooses to +reject the key verification request, Bob's client should send a +`m.key.verification.cancel` message to Alice's device. If Bob's client does +not understand any of the methods offered, it should display a message to Bob +saying so. + +To initiate a key verification process, Bob's device sends a `to_device` event +to one of Alice's devices with the `type` set to `m.key.verification.start`. +This may either be done in response to an `m.key.verification.request` message, +or can be done independently. If Alice's device receives an +`m.key.verification.start` message in response to an +`m.key.verification.request` message, it should send an +`m.key.verification.cancel` message to Bob's other devices that it had +originally sent an `m.key.verification.request` to, in order to cancel the key +verification request. + +Verification methods can define other events required to complete the +verification. Event types for verification methods defined in the Matrix spec +should be in the `m.key.verification` namespace. Event types that are not +defined in the Matrix spec must be namespaced following the Java package naming +convention. + +Alice's or Bob's devices can cancel a key verification process or a key +verification request by sending a `to_device` event with `type` set to +`m.key.verification.cancel`. + +### Event Definitions + +#### `m.key.verification.request` + +Requests a key verification. + +Properties: + +- `from_device` (string): the device ID of the device requesting verification. +- `transaction_id` (string): an identifier for the verification request. Must + be unique with respect to the pair of devices. +- `methods` ([string]): the verification methods supported by the sender. +- `timestamp` (integer): the time when the request was made. If the timestamp + is in the future (by more than 5 minutes, to allow for clock skew), or more + than 10 minutes in the past, then the message must be ignored. + +#### `m.key.verification.start` + +Begins a key verification process. + +Properties: + +- `method` (string): the verification method to use. +- `from_device` (string): The device ID of the device starting the verification + process. +- `transaction_id` (string): an identifier for the verification process. If + this message is sent in reponse to an `m.key.verification.request` event, then + it must use the same `transaction_id` as the one given in the + `m.key.verification.request`. + +Key verification methods can define additional properties to be included. + +#### `m.key.verification.cancel` + +Cancels a key verification process or a key verification request. Upon +receiving an `m.key.verification.cancel` message, the receiving device must +cancel the verification or the request. If it is a verification process that +is cancelled, or a verification request initiated by the recipient of the +cancellation message, the device should inform the user of the reason. + +Properties: + +- `transaction_id` (string): the identifier for the request or key verification + to cancel. +- `code` (string): machine-readable reason for cancelling. Possible reasons + are: + - `m.user`: the user cancelled the verification. + - `m.timeout`: the verification process has timed out. Different verification + methods may define their own timeouts. + - `m.unknown_transaction`: the device does not know about the given transaction + ID. + - `m.unknown_method`: the device does not know how to handle the given method. + This can be sent in response to an `m.key.verification.start` message, or + can be sent in response to other verification method-specific messages. + - `m.unexpected_message`: the device received an unexpected message. For + example, a message for a verification method may have been received when it + was not expected. +- `reason` (string): human-readable reason for cancelling. This should only be + used if the recieving client does not understand the code given. + +Verification methods may define their own additional cancellation codes. +Cancellation codes defined in the Matrix spec will begin with `m.`; other +cancellation codes must be namespaced following the Java package naming +convention. + +## Tradeoffs + +## Potential issues + +## Security considerations + +## Conclusion + +This proposal presents common event definitions for use by key verification +methods and defines a way for users to request key verification. From ec2e02e8b5479b4734b0d8a6ed5aa8953f495a67 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 13 Nov 2018 11:45:18 -0500 Subject: [PATCH 002/497] rename to match MSC number --- proposals/{xxxx-key_verification.md => 1717-key_verification.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-key_verification.md => 1717-key_verification.md} (100%) diff --git a/proposals/xxxx-key_verification.md b/proposals/1717-key_verification.md similarity index 100% rename from proposals/xxxx-key_verification.md rename to proposals/1717-key_verification.md From b535226d407b28709c8d126ef6852f3bb9344c10 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 13 Nov 2018 22:00:42 -0500 Subject: [PATCH 003/497] initial work on documenting olm unwedging --- proposals/xxxx-olm_unwedging.md | 45 +++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 proposals/xxxx-olm_unwedging.md diff --git a/proposals/xxxx-olm_unwedging.md b/proposals/xxxx-olm_unwedging.md new file mode 100644 index 00000000..60f45fe1 --- /dev/null +++ b/proposals/xxxx-olm_unwedging.md @@ -0,0 +1,45 @@ +# Olm unwedging + +Olm sessions sometimes get out of sync, resulting in undecryptable messages. +This proposal documents a method for devices to create a new session to replace +the broken session. + +## Proposal + +When a device receives an olm-encrypted message that it cannot decrypt, it +should assume that the olm session has become corrupted and create a new olm +session to replace it. It should then send a dummy message, using that +session, to the other party in order to inform them of the new session. To +send a dummy message, clients may send an event with type `m.dummy`, and with +empty contents. + +If the corrupted session has already been replaced, the receiving device should +do nothing, under the assumption that the message from the corrupted session +was sent before the sender was informed of the replacement session, in order to +avoid creating too many extra sessions. + +The spec currently says, "If a client has multiple sessions established with +another device, it should use the session from which it last received a +message." (the last paragraph of the [`m.olm.v1.curve25519-aes-sha2` +section](https://matrix.org/docs/spec/client_server/r0.4.0.html#m-olm-v1-curve25519-aes-sha2)). +When comparing the time of the last received message for each session, the +client should consider only consider messages that were successfully decrypted, +and for sessions that have never received a message, it should use the creation +time of the session. The spec will be changed to read: + +> If a client has multiple sessions established with another device, it should +> use the session from which it last received and successfully decrypted a +> message. For these purposes, a session that has not received any messages +> should consider its creation time to be the time that it last received a +> message. + +## Tradeoffs + +## Potential issues + +## Security considerations + +## Conclusion + +This proposal outlines how wedged olm sessions can be replaced by a new +session. From d0bfdc13af8b4b8e5bba695c6f6bb3a2f6d7d275 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 13 Nov 2018 22:03:07 -0500 Subject: [PATCH 004/497] rename to match MSC number --- proposals/{xxxx-olm_unwedging.md => 1719-olm_unwedging.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-olm_unwedging.md => 1719-olm_unwedging.md} (100%) diff --git a/proposals/xxxx-olm_unwedging.md b/proposals/1719-olm_unwedging.md similarity index 100% rename from proposals/xxxx-olm_unwedging.md rename to proposals/1719-olm_unwedging.md From 495df02da6efb5d821fad69abb4fb66600db20b4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 14 Nov 2018 10:19:11 -0500 Subject: [PATCH 005/497] we don't actually know which session got stuck, so rate-limit by device --- proposals/1719-olm_unwedging.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index 60f45fe1..13c4ea4b 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -13,10 +13,11 @@ session, to the other party in order to inform them of the new session. To send a dummy message, clients may send an event with type `m.dummy`, and with empty contents. -If the corrupted session has already been replaced, the receiving device should -do nothing, under the assumption that the message from the corrupted session -was sent before the sender was informed of the replacement session, in order to -avoid creating too many extra sessions. +In order to avoid creating too many extra sessions, a client should rate-limit +the number of new sessions it creates per device that it receives a message +from; the client should not create a new session with another device if it has +already created one for that given device in the past 1 hour. (TODO: is 1 hour +the right amount of time?) The spec currently says, "If a client has multiple sessions established with another device, it should use the session from which it last received a From 2b5805255564bb80a63c73dd977b487c67c9007c Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 14 Nov 2018 10:28:26 -0500 Subject: [PATCH 006/497] add note about re-requesting megolm keys --- proposals/1719-olm_unwedging.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index 13c4ea4b..e696c1e2 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -19,6 +19,12 @@ from; the client should not create a new session with another device if it has already created one for that given device in the past 1 hour. (TODO: is 1 hour the right amount of time?) +Clients may wish to ask the sender of the undecryptable messages to re-send the +message. For exampe, if the undecryptable message was a megolm session, then +the client can send an +[`m.room_key_request`](https://matrix.org/docs/spec/client_server/r0.4.0.html#m-room-key-request) +message to request that the sender re-send the key. + The spec currently says, "If a client has multiple sessions established with another device, it should use the session from which it last received a message." (the last paragraph of the [`m.olm.v1.curve25519-aes-sha2` From 4538745809d15dbdc6107466f88193f555f3a948 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 7 Jan 2019 02:43:46 +0000 Subject: [PATCH 007/497] MSC1779: Open Governance for Matrix.org --- proposals/1779-open-governance.md | 386 ++++++++++++++++++++++++++++++ 1 file changed, 386 insertions(+) create mode 100644 proposals/1779-open-governance.md diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md new file mode 100644 index 00000000..a79d175b --- /dev/null +++ b/proposals/1779-open-governance.md @@ -0,0 +1,386 @@ +# Proposal for Open Governance of Matrix.org + +This whole document is a **work in progress** draft of a constitution proposal +for open governance for Matrix.org, and forms the basis of the first full +Articles of Association (AoA) for [The Matrix.org Foundation +C.I.C.](https://beta.companieshouse.gov.uk/company/11648710) - a non-profit legal +entity incorporated to act as the neutral guardian of the Matrix decentralised +communication standard on behalf of the whole Matrix community. + +See https://matrix.org/blog/2018/10/29/introducing-the-matrix-org-foundation-part-1-of-2/ +for more context. + +This obsoletes [MSC1318](https://github.com/matrix-org/matrix-doc/issues/1318) + +## Introduction + +Historically the core team of Matrix has been paid to work on it by the same +employer (currently New Vector; the startup incorporated to hire the core +team in Aug 2017). Whilst convenient in initially getting Matrix built, we +recognise that this could create a potential conflict of interest between the +core team’s responsibilities to neutrally support the wider Matrix.org ecosystem +versus the need for New Vector to be able to support the team, and it has always +been the plan to set up a completely neutral custodian for the standard once it +had reached sufficient maturity. + +This proposal seeks to establish a new open governance process for Matrix.org, +such that once the specification has finally been ‘born’ and reached an initial +‘r0’ release across all APIs, control of Matrix.org can be decoupled from New +Vector and better support contributions from the whole ecosystem. + +The concepts here are somewhat inspired by [Rust’s Governance +Model](https://github.com/rust-lang/rfcs/blob/master/text/1068-rust- +governance.md); a highly regarded solution to a similar problem: an ambitious +open-source project which has been too many years in the making, incubated at +first by a single company (Mozilla Corporation), which also enjoys a very +enthusiastic community! + +## Overview + +Governance of the project is split into two teams: the Spec Core Team and the +Guardians of the Foundation. In brief: + +The Spec Core Team are the technical experts who curate and edit the Matrix +Specification from day to day, and so steer the evolution of the protocol by +having final review over which Matrix Spec Changes (MSCs) are merged into the +core spec. + +The Guardians are the legal directors of the non-profit Foundation, and are +responsible for ensuring that the Foundation (and by extension the Spec Core +Team) keeps on mission and neutrally protects the development of Matrix. +Guardians are typically independent of the commercial Matrix ecosystem and may +even not be members of today’s Matrix community, but are deeply aligned with the +mission of the project, and who are respected and trusted by the wider community +to uphold the guiding principles of the Foundation and keep the other Guardians +honest. + +In other words; the Spec Core Team builds the spec, and the Guardians provide an +independent backstop to ensure the spec evolves in line with the Foundation's +mission. + +## Guiding Principles + +The guiding principles define the core philosophy of the project, and will be a +formal part of the final Articles of Association of the Matrix.org Foundation. + +### Matrix Manifesto + +We believe: + + * People should have full control over their own communication. + + * People should not be locked into centralised communication silos, but free to + pick who they choose to host their communication without limiting who they + can reach. + + * The ability to converse securely and privately is a basic human right. + + * Communication should be available to everyone as an free and open, + unencumbered, standard and global network. + +### Mission + +The Matrix.org Foundation exists to act as a neutral custodian for Matrix and +nurture it as efficiently as possible as a single unfragmented standard, for the +greater benefit of the whole ecosystem; not benefiting or privileging any single +player or subset of players. + +For clarity: the Matrix ecosystem is defined as anyone who uses the Matrix +protocol. This includes (non-exhaustively): + + * End-users of Matrix clients + * Matrix client developers and testers + * Spec developers + * Server admins + * Matrix packagers & maintainers + * Companies building products or services on Matrix + * Bridge developers + * Bot developers + * Widget developers + * Server developers + * Matrix room and community moderators + * End-users who are using Matrix indirectly via bridges + * External systems which are bridged into Matrix + * Anyone using Matrix for data communications + +"Greater benefit" is defined as maximising: + + * the number of end-users reachable on the open Matrix network + * the number of regular users on the Matrix network (e.g. 30-day retained federated users) + * the number of end-users reachable by Matrix (natively or via bridges) + * the number of online servers in the open federation + * the number of developers building on Matrix + * the number of independent implementations which use Matrix + * the quality and utility of the Matrix spec (as defined by ease and ability + with which a developer can implement spec-compliant clients, servers, bots, + bridges, and other integrations without needing to refer to any other + external material) + +N.B. that we consider success to be the growth of the open federated network +rather than closed deployments. For example, if WhatsApp adopted Matrix it +wouldn’t be a complete win unless they openly federated with the rest of the +Matrix network. + +### Values + +As Matrix evolves, it's critical that the Spec Core Team and Guardians are +aligned on the overall philosophy of the project, particularly in more +subjective areas. The values we follow are: + + * Supporting the whole long-term ecosystem rather than individual stakeholder gain + * Openness rather than proprietariness + * Collaboration rather than competition + * Accessibility rather than elitism + * Transparency rather than stealth + * Empathy rather than contrariness + * Pragmatism rather than perfection + * Proof rather than conjecture + +Patent encumbered IP is strictly prohibited from being added to the standard. + +## The Spec Core Team + +The contents and direction of the Matrix Spec is governed by the Spec Core Team; +a set of experts from across the whole Matrix community, representing all +aspects of the Matrix ecosystem. The Spec Core Team acts as a subcommittee of +the Foundation. + +Members of the Spec Core Team pledge to act as a neutral custodian for Matrix on +behalf of the whole ecosystem and uphold the Guiding Principles of the project +as outlined above. In particular, they agree to drive the adoption of Matrix as +a single global federation, an open standard unencumbered from any proprietary +IP or software patents, minimising fragmentation (whilst encouraging +experimentation), evolving rapidly, and prioritising the long-term success and +growth of the overall network over individual commercial concerns. + +Spec Core Team members need to have significant proven domain experience/skill +and have had clear dedication and commitment to the project and community for >6 +months. (In future, once we have subteams a la Rust, folks need to have proven +themselves there first). + +Members need to demonstrate ability to work constructively with the rest of the +team; we want participation in the Spec Core Team to be an efficient, pleasant and +productive place, even in the face of inevitable disagreement. We do not want a +toxic culture of bullying or competitive infighting. Folks need to be able to +compromise; we are not building a culture of folks pushing their personal +agendas at the expense of the overall project. + +We are particularly vigilant against 'trojan horse' additions to the spec - +features which only benefit particular players, or are designed to somehow +cripple or fragment the open protocol and ecosystem in favour of competitive +advantage. Commercial players are of course encouraged to build proprietary +implementations, or use custom event types, or even custom API extensions (e.g. +more efficient network transports) - but implementations must fall back to +interoperating correctly with the rest of the ecosystem. + +### Spec Core Team logistics + +The Spec Core Team itself will be made up of roughly 8 members + 1 project lead. +Roughly half the members are expected to be from the historical core team +(similar to Rust). + +In future we may also have sub-teams (like Rust - e.g. CS/AS/Push API; SS API; +IS API; Crypto), but as a starting point we are beginning with a single core +team in the interests of not over-engineering it and scaling up elastically. + +Spec Core Team members need to be able to commit to at least 1 hour a week of +availability to work on the spec and (where relevant) reference implementations. +Members of the team volunteer their time for free to work on the project. + +Responsibilities include: + + * Reviewing Matrix Spec Change proposals and Spec PRs + + * Contributing to and reviewing reference implementations of Matrix Spec Change + proposals + + * Shepherding Matrix Spec Changes on behalf of authors where needed + + * Triaging Matrix Spec issues + + * Coordinating reference implementations + + * Ensuring the code of conduct for +matrix:matrix.org community rooms is + maintained and applied + +If members are absent for more than 8 weeks without prior agreement, they will +be assumed to have left the project. + +Spec Core Team members can resign whenever they want, but must notify the rest +of the team and the Guardians on doing so. + +New additions to the team require 100% consent from the current team members. +Membership has to be formally proposed by someone already on the Spec Core Team. + +Members can be removed from the team if X% of the team agrees they are no longer +following the goals and guiding principles of the project. + +Guardians act as a backstop, and can appoint or remove Spec Core Team members +(requiring a 75% consensus threshold between the Guardians) if the Spec Core +Team is unable to reach consensus or is failing to align with the Foundation's +mission. + +It's suggested that one of the Spec Core Team members is also be a Guardian, to +facilitate information between the Guardians and the Spec Core Team and +represent the technical angle of the project to the other Guardians. + +The project lead role acts to coordinate the team and to help tie-break in the +event of failing to get acceptance on a Matrix Spec Change. The project lead is +reviewed every 12 months and requires the confidence of 75% of the team to be +renewed. There is no maximum term for the project lead. The lead may be removed +by the core team at any point (with 75% majority), and may resign the role at +any point (notifying the team and the Guardians). The lead automatically resigns +the role if they resign from the Spec Core Team. + +The initial Spec Core Team (and their domain areas) is: + + * Matthew Hodgson (Lead) + * Erik Johnston (Servers) + * Richard van der Hoff (Servers, Cryptography) + * David Baker (Clients, IS API, Push API, Media) + * Hubert Chathi (Cryptography, General) + * Andrew Morgan (Servers, AS API, Spec Process) + * Travis Ralston (Bots and Bridges & AS API, Media, acting with Dimension hat on) + * kitsune (Clients on behalf of Community) + * TBD + +MSCs require >= 75% approval from the Spec Core Team to proceed to Final Comment +Period (see https://matrix.org/docs/spec/proposals for the rest of the MSC +process). + +The above governance process for the Spec Core Team is considered as part of the +spec and is updated using the Matrix Spec Change process. However, changes to +the governance process also require a 75% positive approval from the Guardians +(acting as a formal decision of the Foundation's Directors), in order to ensure +changes are aligned with the Foundation's mission. + +## The Guardians + +*This section will be used as the basis for the legal responsibilities of +Directors in the Articles of Association of the Foundation.* + +The Guardians form the legal Board of Directors of The Matrix.org Foundation CIC +(Community Interest Company). They are responsible for ensuring the Foundation +is following its guiding principles, and provide a safety mechanism if the +structure of the Spec Core Team runs into trouble. + +In practice, this means that: + * Guardians must approve changes to the Spec Core Team + * Guardians must keep each other honest, providing a ‘checks and balances’ + mechanism between each other to ensure that all Guardians and the Spec Core + Team act in the best interests of the protocol and ecosystem. + * Guardians may appoint/dismiss members of the Spec Core Team who are in serious + breach of the guiding principles. + * Guardians must approve changes to the Guiding Principles (above) + * Guardians are responsible for approving use of the Foundation's assets + (e.g. redistributing donations) + * In future, Guardians may also be responsible for ensuring staff are hired by + the Foundation to support administrative functions + * As well as the Spec Core Team committee, they may also oversee committees for + other areas such as marketing Matrix.org, registering custom event types, + or "Made for Matrix" certification. + * It's likely a subset of Guardians will be hands-on for day-to-day + administrative purposes, whilst the others act to keep them in balance. + +Guardians are chosen typically to be independent of the commercial Matrix +ecosystem (and especially independent from New Vector), and may even not be +members of today’s Matrix community. However, they should be deeply aligned with +the mission of the project, and respected and trusted by the wider community to +uphold the guiding principles of the Foundation and keep the other Guardians +honest. + +Guardians are responsible for maintaining and updating the Guiding +Principles and Articles of Association of the Foundation if/when +necessary. Changes to the Guiding Principles require a 75% majority from the +Guardians and are passed as a 'special resolution' of the board. + +New Guardians may be appointed with a 75% majority by the board. + +Guardians may resign at any time, with notification to the board. + +Guardians may be removed due to serious breach of the guiding principles with a +75% majority of the other Guardians, or if absent from 3 consecutive board +meetings, or if they are legally disqualified from acting as a Director. + +We aim to recruit roughly 5 Guardians. The initial Guardians are: + + * Matthew Hodgson (CEO/CTO, New Vector) + * Amandine Le Pape (COO, New Vector) + * TBA (agreed, needs paperwork) + * TBD + * TBD + +The intention is for Matthew & Amandine (the original founders of Matrix) to +form a minority of the Guardians, in order to ensure the neutrality of the +Foundation relative to Matthew & Amandine’s day jobs at New Vector. + +Guardians volunteer their time for free to work on the project. + +## The Core Team + +"The Core Team" is a loose term that describes the set of people with access to +commit code to the public https://github.com/matrix-org repositories, who are +either working on matrix.org's reference implementations or the spec itself. +Commit access is decided by those responsible for the projects in question, much +like any other open source project. Anyone is eligible for commit access if +they have proved themselves a valuable long-term contributor, upholds the +guiding principles and mission of the project and have proved themselves able to +collaborate constructively with the existing core team. + +## Responsibilities for the Foundation + + * Independent legal entity to act as neutral custodian of Matrix + * Gathering donations + * Owns the core Matrix IP in an asset lock, which shall be transferred from New Vector: + * Owns the matrix.org domain and branding + * Owns the copyright of the reference implementations of Matrix (i.e. everything in https://github.com/matrix-org). + By assigning copyright to the Foundation, it’s protected against New Vector ever being tempted to relicense it. + * Owns the IP of the website + * Owns the Matrix.org marketing swag (t-shirts, stickers, exhibition stands etc) + * It's responsible for finding someone to run the Matrix.org homeserver (currently New Vector) + * Publishing the spec + * Responsible for sytest + * Manages IANA-style allocations for Matrix + * mx:// URI scheme? + * TCP port 8448 + * .well-known URIs…? + +In future: + + * contract entities to work on Matrix? (e.g. redistributing donations back to fund development) + * manage a Matrix certification process? + * promote Matrix (e.g. organise meetups & events & fund community activity)? + +## Timings + +The Foundation was incorporated in October 2018 as a UK limited by guarantee +private company, using generic non-profit articles of association combined with +a high-level mission lock aligned with the above: + +> 4. The objects of the Foundation are for the benefit of the community as a whole +> to: + +> 4.1.1 empower users to control their communication data and have freedom over +> their communications infrastructure by creating, maintaining and promoting +> Matrix as an openly standardised secure decentralised communication protocol and +> network, open to all, and available to the public for no charge; + +> 4.1.2 build and develop an appropriate governance model for Matrix through the +> Foundation, in order to drive the adoption of Matrix as a single global +> federation, an open standard unencumbered from any proprietary intellectual +> property and/or software patents, minimising fragmentation (whilst encouraging +> experimentation), maximising speed of development, and prioritising the long- +> term success and growth of the overall network over the commercial concerns of +> an individual person or persons. + +The foundation was then converted into a Community Interest Company, formalising +its non-profit status under the approval of the independent [Community Interest +Companies Regulator](https://www.gov.uk/government/organisations/office-of-the- +regulator- of-community-interest-companies), which took effect Jan 2019. + +We are currently planning to release r0 of the Matrix Spec at the end of Jan 2019, and +finalise the Foundation's articles of association shortly afterwards based on the +contents of this MSC once passed FCP. + +This will coincide with the formal asset transfer of Matrix.org's assets from +New Vector Ltd, and the appointment of the remaining Guardians. From 303e1081f8e0647b2acd67a4050793789cb5e2a7 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 7 Jan 2019 02:44:59 +0000 Subject: [PATCH 008/497] unbreak wordwrap --- proposals/1779-open-governance.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index a79d175b..cf5d0d20 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -375,8 +375,8 @@ a high-level mission lock aligned with the above: The foundation was then converted into a Community Interest Company, formalising its non-profit status under the approval of the independent [Community Interest -Companies Regulator](https://www.gov.uk/government/organisations/office-of-the- -regulator- of-community-interest-companies), which took effect Jan 2019. +Companies Regulator](https://www.gov.uk/government/organisations/office-of-the-regulator-of-community-interest-companies), +which took effect Jan 2019. We are currently planning to release r0 of the Matrix Spec at the end of Jan 2019, and finalise the Foundation's articles of association shortly afterwards based on the From e6fb403dd0919018fced9525412da6f9eaef6701 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 7 Jan 2019 02:47:37 +0000 Subject: [PATCH 009/497] add TODO for clarifying features v. extensions --- proposals/1779-open-governance.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index cf5d0d20..006d65b3 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -121,6 +121,10 @@ rather than closed deployments. For example, if WhatsApp adopted Matrix it wouldn’t be a complete win unless they openly federated with the rest of the Matrix network. +TODO: spell out when features should land in the spec, versus via +integration/widget or other non-core extension. e.g. should video conferencing +be in the spec itself, or done via Jitsi? + ### Values As Matrix evolves, it's critical that the Spec Core Team and Guardians are From c073adac9bbdaac30cc24e941185163da19cda12 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 7 Jan 2019 02:51:04 +0000 Subject: [PATCH 010/497] incorporate review from #1318 --- proposals/1779-open-governance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 006d65b3..4fb564a5 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -344,6 +344,7 @@ collaborate constructively with the existing core team. * It's responsible for finding someone to run the Matrix.org homeserver (currently New Vector) * Publishing the spec * Responsible for sytest + * Publishing the website (including ensuring This Week In Matrix and similar exist to promote independent projects) * Manages IANA-style allocations for Matrix * mx:// URI scheme? * TCP port 8448 @@ -352,7 +353,7 @@ collaborate constructively with the existing core team. In future: * contract entities to work on Matrix? (e.g. redistributing donations back to fund development) - * manage a Matrix certification process? + * manage a "Made for Matrix" certification process? (to confirm that products are actually compatible with Matrix) * promote Matrix (e.g. organise meetups & events & fund community activity)? ## Timings From de6a8b20ff26f317d8a3ca8988f15cd59bd1d802 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 7 Jan 2019 02:53:49 +0000 Subject: [PATCH 011/497] grammar --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 4fb564a5..79213f89 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -10,7 +10,7 @@ communication standard on behalf of the whole Matrix community. See https://matrix.org/blog/2018/10/29/introducing-the-matrix-org-foundation-part-1-of-2/ for more context. -This obsoletes [MSC1318](https://github.com/matrix-org/matrix-doc/issues/1318) +This obsoletes [MSC1318](https://github.com/matrix-org/matrix-doc/issues/1318). ## Introduction From b8249067090fc533676d23fff7a13fd16fc4ee4f Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 7 Jan 2019 03:23:36 +0000 Subject: [PATCH 012/497] typoes --- proposals/1779-open-governance.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 79213f89..34230d70 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -29,8 +29,8 @@ such that once the specification has finally been ‘born’ and reached an init Vector and better support contributions from the whole ecosystem. The concepts here are somewhat inspired by [Rust’s Governance -Model](https://github.com/rust-lang/rfcs/blob/master/text/1068-rust- -governance.md); a highly regarded solution to a similar problem: an ambitious +Model](https://github.com/rust-lang/rfcs/blob/master/text/1068-rust-governance.md); +a highly regarded solution to a similar problem: an ambitious open-source project which has been too many years in the making, incubated at first by a single company (Mozilla Corporation), which also enjoys a very enthusiastic community! @@ -224,8 +224,8 @@ Guardians act as a backstop, and can appoint or remove Spec Core Team members Team is unable to reach consensus or is failing to align with the Foundation's mission. -It's suggested that one of the Spec Core Team members is also be a Guardian, to -facilitate information between the Guardians and the Spec Core Team and +It's suggested that one of the Spec Core Team members should also be a Guardian, +to facilitate information between the Guardians and the Spec Core Team and represent the technical angle of the project to the other Guardians. The project lead role acts to coordinate the team and to help tie-break in the From 4994fa115e41fd4b8777b474465c3e3702589f4a Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:21:19 +0000 Subject: [PATCH 013/497] X=75 --- proposals/1779-open-governance.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 34230d70..4181d7de 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -216,8 +216,8 @@ of the team and the Guardians on doing so. New additions to the team require 100% consent from the current team members. Membership has to be formally proposed by someone already on the Spec Core Team. -Members can be removed from the team if X% of the team agrees they are no longer -following the goals and guiding principles of the project. +Members can be removed from the team if >= 75% of the team agrees they are no +longer following the goals and guiding principles of the project. Guardians act as a backstop, and can appoint or remove Spec Core Team members (requiring a 75% consensus threshold between the Guardians) if the Spec Core From 4fcd38a3a03a48d0610225453ab5adbc51636ab7 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:27:03 +0000 Subject: [PATCH 014/497] clarify guardians' right to override spec core team membership --- proposals/1779-open-governance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 4181d7de..07e275dc 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -274,7 +274,8 @@ In practice, this means that: mechanism between each other to ensure that all Guardians and the Spec Core Team act in the best interests of the protocol and ecosystem. * Guardians may appoint/dismiss members of the Spec Core Team who are in serious - breach of the guiding principles. + breach of the guiding principles. This overrides the unanimous consent + requirement for the Spec Core Team when appointing new members. * Guardians must approve changes to the Guiding Principles (above) * Guardians are responsible for approving use of the Foundation's assets (e.g. redistributing donations) From 7831c04e4caa9459cb527338e9ff6ea75ff8703f Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:29:24 +0000 Subject: [PATCH 015/497] clarify sytest responsibilities --- proposals/1779-open-governance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 07e275dc..6ba52f4d 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -344,7 +344,8 @@ collaborate constructively with the existing core team. * Owns the Matrix.org marketing swag (t-shirts, stickers, exhibition stands etc) * It's responsible for finding someone to run the Matrix.org homeserver (currently New Vector) * Publishing the spec - * Responsible for sytest + * Responsible for tools and documentation that supports the spec + * Responsible for ensuring reference implementations and test suite exists for the spec * Publishing the website (including ensuring This Week In Matrix and similar exist to promote independent projects) * Manages IANA-style allocations for Matrix * mx:// URI scheme? From e730cc02a9d5ec77a70296b30c66a45e8ae41bf6 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:34:20 +0000 Subject: [PATCH 016/497] specify how to select a new spec core team lead --- proposals/1779-open-governance.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 6ba52f4d..67d66b2a 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -234,7 +234,9 @@ reviewed every 12 months and requires the confidence of 75% of the team to be renewed. There is no maximum term for the project lead. The lead may be removed by the core team at any point (with 75% majority), and may resign the role at any point (notifying the team and the Guardians). The lead automatically resigns -the role if they resign from the Spec Core Team. +the role if they resign from the Spec Core Team. Resignation automatically +triggers selection of a new lead, who must be selected from the existing core +spec team. The initial Spec Core Team (and their domain areas) is: @@ -276,6 +278,8 @@ In practice, this means that: * Guardians may appoint/dismiss members of the Spec Core Team who are in serious breach of the guiding principles. This overrides the unanimous consent requirement for the Spec Core Team when appointing new members. + * Guardians may also override deadlocks when appointing a Spec Core Team leader + (with a >= 75% majority) * Guardians must approve changes to the Guiding Principles (above) * Guardians are responsible for approving use of the Foundation's assets (e.g. redistributing donations) From 103d2f4ed223be24f798b7d45a4f5cb87c6e8720 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:36:32 +0000 Subject: [PATCH 017/497] clarify that the project lead doesn't have casting vote --- proposals/1779-open-governance.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 67d66b2a..6280a45b 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -228,15 +228,15 @@ It's suggested that one of the Spec Core Team members should also be a Guardian, to facilitate information between the Guardians and the Spec Core Team and represent the technical angle of the project to the other Guardians. -The project lead role acts to coordinate the team and to help tie-break in the -event of failing to get acceptance on a Matrix Spec Change. The project lead is -reviewed every 12 months and requires the confidence of 75% of the team to be -renewed. There is no maximum term for the project lead. The lead may be removed -by the core team at any point (with 75% majority), and may resign the role at -any point (notifying the team and the Guardians). The lead automatically resigns -the role if they resign from the Spec Core Team. Resignation automatically -triggers selection of a new lead, who must be selected from the existing core -spec team. +The project lead role acts to coordinate the team and to help steer the team to +consensus in the event of failing to get agreement on a Matrix Spec Change. The +project lead is reviewed every 12 months and requires the confidence of 75% of +the team to be renewed. There is no maximum term for the project lead. The lead +may be removed by the core team at any point (with 75% majority), and may resign +the role at any point (notifying the team and the Guardians). The lead +automatically resigns the role if they resign from the Spec Core Team. +Resignation automatically triggers selection of a new lead, who must be selected +from the existing core spec team. The initial Spec Core Team (and their domain areas) is: From 2047ba59daf0632b04ed974dc3598c2224b9335e Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:42:49 +0000 Subject: [PATCH 018/497] spell out domain spread requirement for spec core team --- proposals/1779-open-governance.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 6280a45b..fb15027a 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -238,6 +238,10 @@ automatically resigns the role if they resign from the Spec Core Team. Resignation automatically triggers selection of a new lead, who must be selected from the existing core spec team. +It is vital that the core spec team has strong domain expertise covering all +different domains of the spec (e.g. we don't want to end up with a core spec +team where nobody has strong experience in cryptography) + The initial Spec Core Team (and their domain areas) is: * Matthew Hodgson (Lead) From c05000b38dd7529fe79f582091de6bea1590509d Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:43:44 +0000 Subject: [PATCH 019/497] broaden reasons for dysfunctional core spec teams --- proposals/1779-open-governance.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index fb15027a..2c67a5ca 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -221,8 +221,7 @@ longer following the goals and guiding principles of the project. Guardians act as a backstop, and can appoint or remove Spec Core Team members (requiring a 75% consensus threshold between the Guardians) if the Spec Core -Team is unable to reach consensus or is failing to align with the Foundation's -mission. +Team is unable to function or is failing to align with the Foundation's mission. It's suggested that one of the Spec Core Team members should also be a Guardian, to facilitate information between the Guardians and the Spec Core Team and From 0e246b147717b1b7f7d40968211a39b365d6effa Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Jan 2019 14:44:18 +0000 Subject: [PATCH 020/497] Update proposals/1779-open-governance.md Co-Authored-By: ara4n --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 2c67a5ca..1a836322 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -243,7 +243,7 @@ team where nobody has strong experience in cryptography) The initial Spec Core Team (and their domain areas) is: - * Matthew Hodgson (Lead) + * Matthew Hodgson (Lead, Guardian) * Erik Johnston (Servers) * Richard van der Hoff (Servers, Cryptography) * David Baker (Clients, IS API, Push API, Media) From 5235293623bfbe62301d8514c6055d321f0aad06 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:50:18 +0000 Subject: [PATCH 021/497] spell out the Core Team a bit more --- proposals/1779-open-governance.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 2c67a5ca..6f8af97d 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -328,16 +328,27 @@ Foundation relative to Matthew & Amandine’s day jobs at New Vector. Guardians volunteer their time for free to work on the project. -## The Core Team +## The Code Core Team (aka The Core Team) -"The Core Team" is a loose term that describes the set of people with access to -commit code to the public https://github.com/matrix-org repositories, who are -either working on matrix.org's reference implementations or the spec itself. -Commit access is decided by those responsible for the projects in question, much -like any other open source project. Anyone is eligible for commit access if -they have proved themselves a valuable long-term contributor, upholds the -guiding principles and mission of the project and have proved themselves able to -collaborate constructively with the existing core team. +The "Core Team" (or the "Code Core Team", to disambiguate from the Spec Core +Team) is a loose term that describes the set of people with access to commit +code to the public https://github.com/matrix-org repositories, who are either +working on matrix.org's reference implementations or the spec itself. Commit +access is decided by those responsible for the projects in question, much like +any other open source project. Anyone is eligible for commit access if they +have proved themselves a valuable long-term contributor, upholds the guiding +principles and mission of the project and have proved themselves able to +collaborate constructively with the existing core team. Active participation in +the core team is also signified by membership of the +matrix:matrix.org Matrix +community. + +TODO: spell out some responsibilities. Erik suggests something like: + * Helping to ensure the quality of the projects' repositories + * That all projects follow the Matrix spec + * Engaging with the people in a way that fosters a healthy and happy community + * Following the Guiding Principles and promoting them within the community + +Code Core Team members volunteer their time for free to work on the project. ## Responsibilities for the Foundation From 3a5d56467bcaacf3f1672f3ed522c61da8c097a0 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 8 Jan 2019 14:51:45 +0000 Subject: [PATCH 022/497] reword lead renewals --- proposals/1779-open-governance.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index f7712197..1e78d8e0 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -228,14 +228,14 @@ to facilitate information between the Guardians and the Spec Core Team and represent the technical angle of the project to the other Guardians. The project lead role acts to coordinate the team and to help steer the team to -consensus in the event of failing to get agreement on a Matrix Spec Change. The -project lead is reviewed every 12 months and requires the confidence of 75% of -the team to be renewed. There is no maximum term for the project lead. The lead -may be removed by the core team at any point (with 75% majority), and may resign -the role at any point (notifying the team and the Guardians). The lead -automatically resigns the role if they resign from the Spec Core Team. -Resignation automatically triggers selection of a new lead, who must be selected -from the existing core spec team. +consensus in the event of failing to get agreement on a Matrix Spec Change. +Every 12 months, a vote of confidence is held in the project lead, requiring the +confidence of 75% of the team for the lead to be renewed. There is no maximum +term for the project lead. The lead may be removed by the core team at any +point (with 75% majority), and may resign the role at any point (notifying the +team and the Guardians). The lead automatically resigns the role if they resign +from the Spec Core Team. Resignation automatically triggers selection of a new +lead, who must be selected from the existing core spec team. It is vital that the core spec team has strong domain expertise covering all different domains of the spec (e.g. we don't want to end up with a core spec From c02ecb58aec48778d9ca4531bb84f5e875d71210 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Jan 2019 16:11:00 -0500 Subject: [PATCH 023/497] mark which fields are required --- proposals/1717-key_verification.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index b71fcf34..fa1d7373 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -57,13 +57,15 @@ Requests a key verification. Properties: -- `from_device` (string): the device ID of the device requesting verification. -- `transaction_id` (string): an identifier for the verification request. Must - be unique with respect to the pair of devices. -- `methods` ([string]): the verification methods supported by the sender. -- `timestamp` (integer): the time when the request was made. If the timestamp - is in the future (by more than 5 minutes, to allow for clock skew), or more - than 10 minutes in the past, then the message must be ignored. +- `from_device` (string): Required. The device ID of the device requesting + verification. +- `transaction_id` (string): Required. An identifier for the verification + request. Must be unique with respect to the pair of devices. +- `methods` ([string]): Required. The verification methods supported by the + sender. +- `timestamp` (integer): Required. The time when the request was made. If the + timestamp is in the future (by more than 5 minutes, to allow for clock skew), + or more than 10 minutes in the past, then the message must be ignored. #### `m.key.verification.start` @@ -71,13 +73,13 @@ Begins a key verification process. Properties: -- `method` (string): the verification method to use. -- `from_device` (string): The device ID of the device starting the verification - process. -- `transaction_id` (string): an identifier for the verification process. If - this message is sent in reponse to an `m.key.verification.request` event, then - it must use the same `transaction_id` as the one given in the - `m.key.verification.request`. +- `method` (string): Required. The verification method to use. +- `from_device` (string): Required. The device ID of the device starting the + verification process. +- `transaction_id` (string): Required. An identifier for the verification + process. If this message is sent in reponse to an + `m.key.verification.request` event, then it must use the same + `transaction_id` as the one given in the `m.key.verification.request`. Key verification methods can define additional properties to be included. From ff0b9eac76cfa65222dd82d45ff3358570ab1fd1 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Jan 2019 16:11:15 -0500 Subject: [PATCH 024/497] add ability to start verifications that happen in two stages --- proposals/1717-key_verification.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index fa1d7373..8acc4654 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -80,6 +80,10 @@ Properties: process. If this message is sent in reponse to an `m.key.verification.request` event, then it must use the same `transaction_id` as the one given in the `m.key.verification.request`. +- `next_method` (string): Optional. If the selected verification method only + verifies one user's key, then this property can be used to indicate the + method to use to verify the other user's key, which will be started + immediately after after the current key verification is complete. Key verification methods can define additional properties to be included. From 09a547d67e0a4b835405af0be9ce739f9dfe400a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Jan 2019 17:45:13 -0500 Subject: [PATCH 025/497] add some cancellation codes, and mention existing verification MSCs --- proposals/1717-key_verification.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 8acc4654..b536be0e 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -2,7 +2,8 @@ Key verification is an essential part of ensuring that end-to-end encrypted messages are secure. Matrix may support multiple verification methods that -require sending events; in fact, two such methods have already been proposed. +require sending events; in fact, two such methods (such as MSC1267 and MSC1543) +have already been proposed. This proposal tries to present a common framework for verification methods to use, and presents a way to request key verification. @@ -112,6 +113,12 @@ Properties: - `m.unexpected_message`: the device received an unexpected message. For example, a message for a verification method may have been received when it was not expected. + - `m.key_mismatch`: the key was not verified. + - `m.user_mismatch`: the expected user did not match the user verified. + - `m.invalid_message`: an invalid message was received. + - `m.accepted`: when an `m.key.verification.request` is accepted by one + device, an `m.key.verification.cancel` message with `code` set to + `m.accepted` is sent to the other devices - `reason` (string): human-readable reason for cancelling. This should only be used if the recieving client does not understand the code given. From 03802701715d4ac1e404e14d619c1c80be4fca2e Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Wed, 9 Jan 2019 23:29:59 +0000 Subject: [PATCH 026/497] spell out that hypothetical employees could come in any size --- proposals/1779-open-governance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 1e78d8e0..8834da30 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -287,7 +287,8 @@ In practice, this means that: * Guardians are responsible for approving use of the Foundation's assets (e.g. redistributing donations) * In future, Guardians may also be responsible for ensuring staff are hired by - the Foundation to support administrative functions + the Foundation to support administrative functions and other roles required + to facilitate the Foundation's mission. * As well as the Spec Core Team committee, they may also oversee committees for other areas such as marketing Matrix.org, registering custom event types, or "Made for Matrix" certification. From c053996a7749b810affe871f36541de481b152c7 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:12:56 +0000 Subject: [PATCH 027/497] add new technical guidelines to proposals.rst this was originally a todo for MSC1779, but belongs better in proposals.rst --- specification/proposals_intro.rst | 69 +++++++++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 4 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 73ace98e..049ad0c8 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -44,15 +44,18 @@ moderators and admins, companies/projects building products or services on Matrix, spec contributors, translators, and those who created it in the first place. -"Greater benefit" could include maximising: +"Greater benefit" includes maximising: * the number of end-users reachable on the open Matrix network -* the number of regular users on the Matrix network (e.g. 30-day retained - federated users) +* the number of regular users on the Matrix network (e.g. 30-day retained federated users) +* the number of end-users reachable by Matrix (natively or via bridges) * the number of online servers in the open federation * the number of developers building on Matrix * the number of independent implementations which use Matrix -* the quality and utility of the Matrix spec +* the quality and utility of the Matrix spec (as defined by ease and ability + with which a developer can implement spec-compliant clients, servers, bots, + bridges, and other integrations without needing to refer to any other + external material) In addition, proposal authors are expected to uphold the following values in their proposed changes to the Matrix protocol: @@ -66,6 +69,64 @@ their proposed changes to the Matrix protocol: * Pragmatism rather than perfection * Proof rather than conjecture +Technical notes +--------------- + +Proposals **must** develop Matrix as a layered protocol: with new features +building on layers of shared abstractions rather than introducing tight vertical +coupling within the stack. This ensures that new features can evolve rapidly by +building on existing layers and swapping out old features without impacting the +rest of the stack or requiring substantial upgrades to the whole ecosystem. +This is critical for Matrix to rapidly evolve and compete effectively with +centralised systems, despite being a federated protocol. + +For instance, new features should be implemented using the highest layer +abstractions possible (e.g. new event types, which layer on top of the existing +room semantics, and so don't even require any API changes). Failing that, the +next recourse would be backwards-compatible changes to the next layer down (e.g. +room APIs); failing that, considering changes to the format of events or the +DAG; etc. It would be a very unusual feature which doesn't build on the +existing infrastructure provided by the spec and instead created new primitives +or low level APIs. + +Backwards compatibility is very important for Matrix, but not at the expense of +hindering the protocol's evolution. Backwards incompatible changes to endpoints +are allowed when no other alternative exists, and must be versioned under a new +major release of the API. Backwards incompatible changes to the room algorithm +are also allowed when no other alternative exists, and must be versioned under a +new version of the room algorithm. + +There is sometimes a dilemma over where to include higher level features: for +instance, should video conferencing be formalised in the spec, or should it be +implemented via widgets (if one assumes that widgets have landed in the spec and +[MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236) is merged)? +Should reputation systems be specified? Should search engine behaviour be +specified? + +There is no universal answer to this, but the following guidelines should be +applied: + * If the feature would benefit the whole Matrix ecosystem and is aligned with + the guiding principles above, then it should be supported by the spec. + For instance, video conferencing is clearly a feature which would benefit + the whole ecosystem, and so the spec should find a way to make it happen. + * If the spec already makes the feature possible without changing any of the + spec *or implementations*, then it may not need to be added to the spec. + For instance, video conferencing done by widgets requires no compulsory + changes to clients nor servers to work, and so could be omitted. + * However, if the best user experience for a feature does require custom + implementation behaviour - e.g. embedding Jitsi into your client rather than + using a widget, then the behaviour should be defined in the spec to allow + implementations to do so. + * However, the spec must never add dependencies on unspecified/nonstandardised + 3rd party behaviour. For instance, defining how to embed Jitsi is unlikely to + ever make it into the spec, given Jitsi does not implement a standardised + interface (although a URL-based calling standard may emerge in future, which + could be used as an extension to the current widget-based approach). + * Therefore, our two options in the specific case of video conferencing are + either to spec SFU conferencing semantics on WebRTC (or refer to an existing spec + for doing so), or to keep it as a widget-based approach (optionally with widget + extensions specific for more deeply integrating video conferencing use cases). + Process ------- From edaf3596f470323a66c74383afb70332d26c28d9 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:14:36 +0000 Subject: [PATCH 028/497] fix 'which features should go in the spec?' TODO and reword intro --- proposals/1779-open-governance.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 8834da30..9db96756 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -1,11 +1,11 @@ # Proposal for Open Governance of Matrix.org -This whole document is a **work in progress** draft of a constitution proposal -for open governance for Matrix.org, and forms the basis of the first full -Articles of Association (AoA) for [The Matrix.org Foundation -C.I.C.](https://beta.companieshouse.gov.uk/company/11648710) - a non-profit legal -entity incorporated to act as the neutral guardian of the Matrix decentralised -communication standard on behalf of the whole Matrix community. +This whole document is the proposed constitution proposal for Matrix.org, and +will form the basis of the first full Articles of Association (AoA) for [The +Matrix.org Foundation +C.I.C.](https://beta.companieshouse.gov.uk/company/11648710) - a non-profit +legal entity incorporated to act as the neutral guardian of the Matrix +decentralised communication standard on behalf of the whole Matrix community. See https://matrix.org/blog/2018/10/29/introducing-the-matrix-org-foundation-part-1-of-2/ for more context. @@ -121,10 +121,6 @@ rather than closed deployments. For example, if WhatsApp adopted Matrix it wouldn’t be a complete win unless they openly federated with the rest of the Matrix network. -TODO: spell out when features should land in the spec, versus via -integration/widget or other non-core extension. e.g. should video conferencing -be in the spec itself, or done via Jitsi? - ### Values As Matrix evolves, it's critical that the Spec Core Team and Guardians are From 21a781b1d2d5c035763da2d734613d323888eb3d Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:16:24 +0000 Subject: [PATCH 029/497] fix proprietary wording --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 9db96756..f829f1d8 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -168,7 +168,7 @@ agendas at the expense of the overall project. We are particularly vigilant against 'trojan horse' additions to the spec - features which only benefit particular players, or are designed to somehow cripple or fragment the open protocol and ecosystem in favour of competitive -advantage. Commercial players are of course encouraged to build proprietary +advantage. Commercial players are of course free to build proprietary implementations, or use custom event types, or even custom API extensions (e.g. more efficient network transports) - but implementations must fall back to interoperating correctly with the rest of the ecosystem. From 265a3dc49b3a00f7ce80e00e8b34bc13a5612adc Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:20:09 +0000 Subject: [PATCH 030/497] clarify removing members --- proposals/1779-open-governance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index f829f1d8..9013f6b6 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -213,7 +213,8 @@ New additions to the team require 100% consent from the current team members. Membership has to be formally proposed by someone already on the Spec Core Team. Members can be removed from the team if >= 75% of the team agrees they are no -longer following the goals and guiding principles of the project. +longer following the goals and guiding principles of the project. (The 75% is +measured of the whole team, including the member in question) Guardians act as a backstop, and can appoint or remove Spec Core Team members (requiring a 75% consensus threshold between the Guardians) if the Spec Core From e584ae31f4e1e5bf806250a06e28b1bb3d9abcee Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:21:02 +0000 Subject: [PATCH 031/497] fix missing words --- proposals/1779-open-governance.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 9013f6b6..808e8368 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -221,8 +221,8 @@ Guardians act as a backstop, and can appoint or remove Spec Core Team members Team is unable to function or is failing to align with the Foundation's mission. It's suggested that one of the Spec Core Team members should also be a Guardian, -to facilitate information between the Guardians and the Spec Core Team and -represent the technical angle of the project to the other Guardians. +to facilitate information exchange between the Guardians and the Spec Core Team, +and to represent the technical angle of the project to the other Guardians. The project lead role acts to coordinate the team and to help steer the team to consensus in the event of failing to get agreement on a Matrix Spec Change. From ed820ca27bdc00845f085c48fbf73c06f42c5202 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Sat, 12 Jan 2019 23:21:52 +0000 Subject: [PATCH 032/497] s/core spec team/Spec Core Team/ Co-Authored-By: ara4n --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 808e8368..2d0e21ed 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -232,7 +232,7 @@ term for the project lead. The lead may be removed by the core team at any point (with 75% majority), and may resign the role at any point (notifying the team and the Guardians). The lead automatically resigns the role if they resign from the Spec Core Team. Resignation automatically triggers selection of a new -lead, who must be selected from the existing core spec team. +lead, who must be selected from the existing Spec Core Team. It is vital that the core spec team has strong domain expertise covering all different domains of the spec (e.g. we don't want to end up with a core spec From b758ceea5b3976f0ae64da5ad7cf8855f0ee5ab7 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:23:46 +0000 Subject: [PATCH 033/497] add erik's quorum --- proposals/1779-open-governance.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 2d0e21ed..58142027 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -177,7 +177,8 @@ interoperating correctly with the rest of the ecosystem. The Spec Core Team itself will be made up of roughly 8 members + 1 project lead. Roughly half the members are expected to be from the historical core team -(similar to Rust). +(similar to Rust). The team must have 5 members to be quorate, with the aim of +generally having between 7 and 9 members. In future we may also have sub-teams (like Rust - e.g. CS/AS/Push API; SS API; IS API; Crypto), but as a starting point we are beginning with a single core From 107d96c50e4882924d4823fef92967e09e9bc223 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:24:55 +0000 Subject: [PATCH 034/497] spell out consensus ftw --- proposals/1779-open-governance.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 58142027..76c6ffa9 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -255,6 +255,9 @@ MSCs require >= 75% approval from the Spec Core Team to proceed to Final Comment Period (see https://matrix.org/docs/spec/proposals for the rest of the MSC process). +Even though a threshold of only 75% is required for approval, the Spec Core Team +is expected to seek consensus on MSCs. + The above governance process for the Spec Core Team is considered as part of the spec and is updated using the Matrix Spec Change process. However, changes to the governance process also require a 75% positive approval from the Guardians From cccd62f03530fcaa78fa38b8fa4992518058100a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Sat, 12 Jan 2019 23:25:37 +0000 Subject: [PATCH 035/497] grammar Co-Authored-By: ara4n --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 76c6ffa9..4de598a9 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -338,7 +338,7 @@ code to the public https://github.com/matrix-org repositories, who are either working on matrix.org's reference implementations or the spec itself. Commit access is decided by those responsible for the projects in question, much like any other open source project. Anyone is eligible for commit access if they -have proved themselves a valuable long-term contributor, upholds the guiding +have proved themselves a valuable long-term contributor, uphold the guiding principles and mission of the project and have proved themselves able to collaborate constructively with the existing core team. Active participation in the core team is also signified by membership of the +matrix:matrix.org Matrix From d00a5eba93926b768555d53a7b081c3a4ccfc9b0 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:26:58 +0000 Subject: [PATCH 036/497] consistent tenses --- proposals/1779-open-governance.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 4de598a9..16047a2d 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -354,19 +354,19 @@ Code Core Team members volunteer their time for free to work on the project. ## Responsibilities for the Foundation - * Independent legal entity to act as neutral custodian of Matrix - * Gathering donations + * Independent legal entity which acts as neutral custodian of Matrix + * Gathers donations * Owns the core Matrix IP in an asset lock, which shall be transferred from New Vector: * Owns the matrix.org domain and branding * Owns the copyright of the reference implementations of Matrix (i.e. everything in https://github.com/matrix-org). By assigning copyright to the Foundation, it’s protected against New Vector ever being tempted to relicense it. * Owns the IP of the website * Owns the Matrix.org marketing swag (t-shirts, stickers, exhibition stands etc) - * It's responsible for finding someone to run the Matrix.org homeserver (currently New Vector) - * Publishing the spec + * Responsible for finding someone to run the Matrix.org homeserver (currently New Vector) + * Publishes the spec * Responsible for tools and documentation that supports the spec * Responsible for ensuring reference implementations and test suite exists for the spec - * Publishing the website (including ensuring This Week In Matrix and similar exist to promote independent projects) + * Publishes the website (including ensuring This Week In Matrix and similar exist to promote independent projects) * Manages IANA-style allocations for Matrix * mx:// URI scheme? * TCP port 8448 @@ -374,9 +374,9 @@ Code Core Team members volunteer their time for free to work on the project. In future: - * contract entities to work on Matrix? (e.g. redistributing donations back to fund development) - * manage a "Made for Matrix" certification process? (to confirm that products are actually compatible with Matrix) - * promote Matrix (e.g. organise meetups & events & fund community activity)? + * contracts entities to work on Matrix? (e.g. redistributing donations back to fund development) + * manages a "Made for Matrix" certification process? (to confirm that products are actually compatible with Matrix) + * promotes Matrix (e.g. organise meetups & events & fund community activity)? ## Timings From ddc3921318262ad7134b37253030ac5a182833ca Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:31:01 +0000 Subject: [PATCH 037/497] un-todo code core team responsibilities --- proposals/1779-open-governance.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 16047a2d..f30d50d0 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -344,10 +344,14 @@ collaborate constructively with the existing core team. Active participation in the core team is also signified by membership of the +matrix:matrix.org Matrix community. -TODO: spell out some responsibilities. Erik suggests something like: - * Helping to ensure the quality of the projects' repositories - * That all projects follow the Matrix spec - * Engaging with the people in a way that fosters a healthy and happy community +Responsibilities include: + * Helping ensure the quality of the projects' code repositories + * Ensuring all commits are reviewed + * Ensuring that all projects follow the Matrix spec + * Helping architect the implementations + * Contributing code to the implementations + * Fostering contributions and engaging with contributors constructively in a + way that fosters a healthy and happy community * Following the Guiding Principles and promoting them within the community Code Core Team members volunteer their time for free to work on the project. From 156488384c75aa23290da0cd845902fffb043d1d Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:49:27 +0000 Subject: [PATCH 038/497] add more examples for spec inclusion; add interoperability as a core value --- proposals/1779-open-governance.md | 1 + specification/proposals_intro.rst | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index f30d50d0..f5a89f5e 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -129,6 +129,7 @@ subjective areas. The values we follow are: * Supporting the whole long-term ecosystem rather than individual stakeholder gain * Openness rather than proprietariness + * Interoperability rather than fragmentation * Collaboration rather than competition * Accessibility rather than elitism * Transparency rather than stealth diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 049ad0c8..b7663e66 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -62,6 +62,7 @@ their proposed changes to the Matrix protocol: * Supporting the whole long-term ecosystem rather than individual stakeholder gain * Openness rather than proprietariness +* Interoperability rather than fragmentation * Collaboration rather than competition * Accessibility rather than elitism * Transparency rather than stealth @@ -110,7 +111,7 @@ applied: For instance, video conferencing is clearly a feature which would benefit the whole ecosystem, and so the spec should find a way to make it happen. * If the spec already makes the feature possible without changing any of the - spec *or implementations*, then it may not need to be added to the spec. + implementations and spec, then it may not need to be added to the spec. For instance, video conferencing done by widgets requires no compulsory changes to clients nor servers to work, and so could be omitted. * However, if the best user experience for a feature does require custom @@ -127,6 +128,19 @@ applied: for doing so), or to keep it as a widget-based approach (optionally with widget extensions specific for more deeply integrating video conferencing use cases). +As an alternative example: it's very unlikely that "how to visualise Magnetic +Resonsance Imaging data over Matrix" would ever be added to the Matrix spec +(other than perhaps a custom event type in a wider standardised Matrix event +registry) given that the spec's existing primitives of file transfer and +extensible events (MSC1767) give excellent tools for transferring and +visualising arbitrary rich data. + +Conversely, features such as reactions, threaded messages, editable messages, +spam/abuse/content filtering, are all features which would clearly benefit the +whole Matrix ecosystem and require both client & server implementation +changes across the board to be implemented in an interoperable way, and so +necessitate a spec change. + Process ------- From f3085812e9c160f63e0cb542378eb827112a54c2 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 12 Jan 2019 23:51:49 +0000 Subject: [PATCH 039/497] more examples; remove widget MSC ref --- specification/proposals_intro.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index b7663e66..c8a2fd32 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -99,10 +99,8 @@ new version of the room algorithm. There is sometimes a dilemma over where to include higher level features: for instance, should video conferencing be formalised in the spec, or should it be -implemented via widgets (if one assumes that widgets have landed in the spec and -[MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236) is merged)? -Should reputation systems be specified? Should search engine behaviour be -specified? +implemented via widgets? Should reputation systems be specified? Should search +engine behaviour be specified? There is no universal answer to this, but the following guidelines should be applied: @@ -135,11 +133,17 @@ registry) given that the spec's existing primitives of file transfer and extensible events (MSC1767) give excellent tools for transferring and visualising arbitrary rich data. +Supporting public search engines are likely to not require custom spec features +(other than possibly better bulk access APIs), given they can be implemented as +clients using the existing CS API. An exception could be API features required +by decentralised search infrastructure (avoiding centralisation of power by +a centralised search engine). + Conversely, features such as reactions, threaded messages, editable messages, -spam/abuse/content filtering, are all features which would clearly benefit the -whole Matrix ecosystem and require both client & server implementation -changes across the board to be implemented in an interoperable way, and so -necessitate a spec change. +spam/abuse/content filtering (and reputation systems), are all features which +would clearly benefit the whole Matrix ecosystem and require both client & +server implementation changes across the board to be implemented in an +interoperable way, and so necessitate a spec change. Process ------- From 09813fc3a080600c13ccaaa74deb61c9df07c1ee Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 Jan 2019 12:41:19 +0000 Subject: [PATCH 040/497] improve wording around compensation for team members. tweak Greater Benefit (particularly adding SnR and filtering goals --- proposals/1779-open-governance.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index f5a89f5e..63684e40 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -105,12 +105,14 @@ protocol. This includes (non-exhaustively): "Greater benefit" is defined as maximising: - * the number of end-users reachable on the open Matrix network + * the number of Matrix-native end-users reachable on the open Matrix network * the number of regular users on the Matrix network (e.g. 30-day retained federated users) - * the number of end-users reachable by Matrix (natively or via bridges) * the number of online servers in the open federation * the number of developers building on Matrix * the number of independent implementations which use Matrix + * the number of bridged end-users reachable on the open Matrix network + * the signal-to-noise ratio of the content on the open Matrix network (i.e. minimising spam) + * the ability for users to discover content on their terms (empowering them to select what to see and what not to see) * the quality and utility of the Matrix spec (as defined by ease and ability with which a developer can implement spec-compliant clients, servers, bots, bridges, and other integrations without needing to refer to any other @@ -130,6 +132,7 @@ subjective areas. The values we follow are: * Supporting the whole long-term ecosystem rather than individual stakeholder gain * Openness rather than proprietariness * Interoperability rather than fragmentation + * Cross-platform rather than platform-specific * Collaboration rather than competition * Accessibility rather than elitism * Transparency rather than stealth @@ -187,7 +190,7 @@ team in the interests of not over-engineering it and scaling up elastically. Spec Core Team members need to be able to commit to at least 1 hour a week of availability to work on the spec and (where relevant) reference implementations. -Members of the team volunteer their time for free to work on the project. +Members must arrange their own funding for their time. Responsibilities include: @@ -329,7 +332,7 @@ The intention is for Matthew & Amandine (the original founders of Matrix) to form a minority of the Guardians, in order to ensure the neutrality of the Foundation relative to Matthew & Amandine’s day jobs at New Vector. -Guardians volunteer their time for free to work on the project. +Guardians must arrange their own funding for their time. ## The Code Core Team (aka The Core Team) @@ -355,7 +358,7 @@ Responsibilities include: way that fosters a healthy and happy community * Following the Guiding Principles and promoting them within the community -Code Core Team members volunteer their time for free to work on the project. +Code Core Team members must arrange their own funding for their time. ## Responsibilities for the Foundation From 2f20679db514ec6b58970bcf91e18a3f3c46270a Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Mon, 14 Jan 2019 12:48:12 +0000 Subject: [PATCH 041/497] deanonymise kitsune Co-Authored-By: ara4n --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 63684e40..a98f36a0 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -252,7 +252,7 @@ The initial Spec Core Team (and their domain areas) is: * Hubert Chathi (Cryptography, General) * Andrew Morgan (Servers, AS API, Spec Process) * Travis Ralston (Bots and Bridges & AS API, Media, acting with Dimension hat on) - * kitsune (Clients on behalf of Community) + * Alexey Rusakov (Clients on behalf of Community) * TBD MSCs require >= 75% approval from the Spec Core Team to proceed to Final Comment From a38e1e6adff27c649b6ac964f7787535b1aa988e Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 Jan 2019 12:54:21 +0000 Subject: [PATCH 042/497] incorporate kitsune & dbkr review --- proposals/1779-open-governance.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index a98f36a0..0b8c0aeb 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -75,7 +75,7 @@ We believe: * The ability to converse securely and privately is a basic human right. - * Communication should be available to everyone as an free and open, + * Communication should be available to everyone as a free and open, unencumbered, standard and global network. ### Mission @@ -130,7 +130,7 @@ aligned on the overall philosophy of the project, particularly in more subjective areas. The values we follow are: * Supporting the whole long-term ecosystem rather than individual stakeholder gain - * Openness rather than proprietariness + * Openness rather than proprietary lock-in * Interoperability rather than fragmentation * Cross-platform rather than platform-specific * Collaboration rather than competition @@ -142,6 +142,10 @@ subjective areas. The values we follow are: Patent encumbered IP is strictly prohibited from being added to the standard. +Making the specification rely on non-standard/unspecified behaviour of other +systems or actors (such as SaaS services, even open-sourced, not governed by a +standard protocol) shall not be accepted, either. + ## The Spec Core Team The contents and direction of the Matrix Spec is governed by the Spec Core Team; @@ -208,8 +212,8 @@ Responsibilities include: * Ensuring the code of conduct for +matrix:matrix.org community rooms is maintained and applied -If members are absent for more than 8 weeks without prior agreement, they will -be assumed to have left the project. +If members are absent (uncontactable) for more than 8 weeks without prior +agreement, they will be assumed to have left the project. Spec Core Team members can resign whenever they want, but must notify the rest of the team and the Guardians on doing so. @@ -375,16 +379,20 @@ Code Core Team members must arrange their own funding for their time. * Responsible for tools and documentation that supports the spec * Responsible for ensuring reference implementations and test suite exists for the spec * Publishes the website (including ensuring This Week In Matrix and similar exist to promote independent projects) - * Manages IANA-style allocations for Matrix - * mx:// URI scheme? + * Manages IANA-style allocations for Matrix, including: + * mx:// URI scheme * TCP port 8448 - * .well-known URIs…? + * .well-known URIs +* Ensures that Matrix promotion is happening (e.g. ensuring that meetups & + events & community activity is supported) In future: - * contracts entities to work on Matrix? (e.g. redistributing donations back to fund development) + * contracts entities to work on Matrix if such contracts help the Foundation to + fulfil its mission and obey the Guiding Principles (e.g. redistributing + donations back to fund development of reference implementations or compliance + kits) * manages a "Made for Matrix" certification process? (to confirm that products are actually compatible with Matrix) - * promotes Matrix (e.g. organise meetups & events & fund community activity)? ## Timings From 70be8393a391baecc23a322800f6843d63d8187a Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 Jan 2019 13:01:50 +0000 Subject: [PATCH 043/497] clarify the technical note and guiding principles --- specification/proposals_intro.rst | 73 ++++++++++++++++++------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index c8a2fd32..393a43a2 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -33,25 +33,28 @@ Guiding Principles Proposals **must** act to the greater benefit of the entire Matrix ecosystem, rather than benefiting or privileging any single player or subset of players - -and must not contain any patent encumbered intellectual property. Members of the Core Team pledge to act as +and must not contain any patent encumbered intellectual property. +Members of the Spec Core Team pledge to act as a neutral custodian for Matrix on behalf of the whole ecosystem. For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That -includes client users, server admins, client developers, bot developers, -bridge and application service developers, users and admins who are indirectly using Matrix via -3rd party networks which happen to be bridged, server developers, room -moderators and admins, companies/projects building products or services on -Matrix, spec contributors, translators, and those who created it in -the first place. +includes client users, server admins, client developers, bot developers, bridge +and application service developers, users and admins who are indirectly using +Matrix via 3rd party networks which happen to be bridged, server developers, +room moderators and admins, companies/projects building products or services on +Matrix, spec contributors, translators, and those who created it in the first +place. -"Greater benefit" includes maximising: +"Greater benefit" is defined as maximising: -* the number of end-users reachable on the open Matrix network +* the number of Matrix-native end-users reachable on the open Matrix network * the number of regular users on the Matrix network (e.g. 30-day retained federated users) -* the number of end-users reachable by Matrix (natively or via bridges) * the number of online servers in the open federation * the number of developers building on Matrix * the number of independent implementations which use Matrix +* the number of bridged end-users reachable on the open Matrix network +* the signal-to-noise ratio of the content on the open Matrix network (i.e. minimising spam) +* the ability for users to discover content on their terms (empowering them to select what to see and what not to see) * the quality and utility of the Matrix spec (as defined by ease and ability with which a developer can implement spec-compliant clients, servers, bots, bridges, and other integrations without needing to refer to any other @@ -61,8 +64,9 @@ In addition, proposal authors are expected to uphold the following values in their proposed changes to the Matrix protocol: * Supporting the whole long-term ecosystem rather than individual stakeholder gain -* Openness rather than proprietariness +* Openness rather than proprietary lock-in * Interoperability rather than fragmentation +* Cross-platform rather than platform-specific * Collaboration rather than competition * Accessibility rather than elitism * Transparency rather than stealth @@ -70,6 +74,9 @@ their proposed changes to the Matrix protocol: * Pragmatism rather than perfection * Proof rather than conjecture +Please see [MSC1779](https://github.com/matrix-org/matrix-doc/pull/1779) +for full details of the project's Guiding Principles. + Technical notes --------------- @@ -104,33 +111,37 @@ engine behaviour be specified? There is no universal answer to this, but the following guidelines should be applied: - * If the feature would benefit the whole Matrix ecosystem and is aligned with +1. If the feature would benefit the whole Matrix ecosystem and is aligned with the guiding principles above, then it should be supported by the spec. - For instance, video conferencing is clearly a feature which would benefit - the whole ecosystem, and so the spec should find a way to make it happen. - * If the spec already makes the feature possible without changing any of the +2. If the spec already makes the feature possible without changing any of the implementations and spec, then it may not need to be added to the spec. - For instance, video conferencing done by widgets requires no compulsory - changes to clients nor servers to work, and so could be omitted. - * However, if the best user experience for a feature does require custom - implementation behaviour - e.g. embedding Jitsi into your client rather than - using a widget, then the behaviour should be defined in the spec to allow - implementations to do so. - * However, the spec must never add dependencies on unspecified/nonstandardised - 3rd party behaviour. For instance, defining how to embed Jitsi is unlikely to - ever make it into the spec, given Jitsi does not implement a standardised - interface (although a URL-based calling standard may emerge in future, which - could be used as an extension to the current widget-based approach). - * Therefore, our two options in the specific case of video conferencing are - either to spec SFU conferencing semantics on WebRTC (or refer to an existing spec - for doing so), or to keep it as a widget-based approach (optionally with widget - extensions specific for more deeply integrating video conferencing use cases). +3. However, if the best user experience for a feature does require custom + implementation behaviour then the behaviour should be defined in the spec + such that all implementations may implement it. +4. However, the spec must never add dependencies on unspecified/nonstandardised + 3rd party behaviour. + +As a worked example: +1. Video conferencing is clearly a feature which would benefit + the whole ecosystem, and so the spec should find a way to make it happen. +2. Video conferencing can be achieved by widgets without requiring any + compulsory changes to changes to clients nor servers to work, and so could be + omitted from the spec. +3. A better experience could be achieved by embedding Jitsi natively into clients + rather than using a widget... +4. ...except that would add a dependency on unspecified/nonstandardised 3rd party + behaviour, so must not be added to the spec. + +Therefore, our two options in the specific case of video conferencing are +either to spec SFU conferencing semantics for WebRTC (or refer to an existing spec +for doing so), or to keep it as a widget-based approach (optionally with widget +extensions specific for more deeply integrating video conferencing use cases). As an alternative example: it's very unlikely that "how to visualise Magnetic Resonsance Imaging data over Matrix" would ever be added to the Matrix spec (other than perhaps a custom event type in a wider standardised Matrix event registry) given that the spec's existing primitives of file transfer and -extensible events (MSC1767) give excellent tools for transferring and +extensible events (MSC1767) give excellent tools for transfering and visualising arbitrary rich data. Supporting public search engines are likely to not require custom spec features From 811e65a4d1cf92b1314889330a01f86a16d23148 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 14 Jan 2019 13:14:43 +0000 Subject: [PATCH 044/497] kitsune review on when to add things to the spec --- specification/proposals_intro.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 393a43a2..1e93a22a 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -150,11 +150,10 @@ clients using the existing CS API. An exception could be API features required by decentralised search infrastructure (avoiding centralisation of power by a centralised search engine). -Conversely, features such as reactions, threaded messages, editable messages, +Features such as reactions, threaded messages, editable messages, spam/abuse/content filtering (and reputation systems), are all features which -would clearly benefit the whole Matrix ecosystem and require both client & -server implementation changes across the board to be implemented in an -interoperable way, and so necessitate a spec change. +would clearly benefit the whole Matrix ecosystem, and cannot be implemented in an +interoperable way using the current spec; so they necessitate a spec change. Process ------- From 9e435d6dabdeb2e482d15e1ceb9bcda0bbe9b432 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 14 Jan 2019 23:33:03 +0000 Subject: [PATCH 045/497] scifi IANA Co-Authored-By: ara4n --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 0b8c0aeb..f6d5b959 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -379,7 +379,7 @@ Code Core Team members must arrange their own funding for their time. * Responsible for tools and documentation that supports the spec * Responsible for ensuring reference implementations and test suite exists for the spec * Publishes the website (including ensuring This Week In Matrix and similar exist to promote independent projects) - * Manages IANA-style allocations for Matrix, including: + * Manages any future IANA-style allocations for Matrix, such as: * mx:// URI scheme * TCP port 8448 * .well-known URIs From 6ff0155a324510b863f3c66843817f4d45e5b9e7 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 Jan 2019 00:16:33 +0000 Subject: [PATCH 046/497] s/responsibilities/functions --- proposals/1779-open-governance.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index f6d5b959..28c18791 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -364,7 +364,7 @@ Responsibilities include: Code Core Team members must arrange their own funding for their time. -## Responsibilities for the Foundation +## Functions of the Foundation * Independent legal entity which acts as neutral custodian of Matrix * Gathers donations @@ -392,7 +392,8 @@ In future: fulfil its mission and obey the Guiding Principles (e.g. redistributing donations back to fund development of reference implementations or compliance kits) - * manages a "Made for Matrix" certification process? (to confirm that products are actually compatible with Matrix) + * manages a "Made for Matrix" certification process? (to confirm that products + are actually compatible with Matrix) ## Timings From 822d84e50c46f335efbd04af8f565fbf98af7b96 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 Jan 2019 00:29:07 +0000 Subject: [PATCH 047/497] append fullstops to lists to make vdh happy --- proposals/1779-open-governance.md | 128 +++++++++++++++--------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 28c18791..58e43b80 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -88,35 +88,35 @@ player or subset of players. For clarity: the Matrix ecosystem is defined as anyone who uses the Matrix protocol. This includes (non-exhaustively): - * End-users of Matrix clients - * Matrix client developers and testers - * Spec developers - * Server admins - * Matrix packagers & maintainers - * Companies building products or services on Matrix - * Bridge developers - * Bot developers - * Widget developers - * Server developers - * Matrix room and community moderators - * End-users who are using Matrix indirectly via bridges - * External systems which are bridged into Matrix - * Anyone using Matrix for data communications + * End-users of Matrix clients. + * Matrix client developers and testers. + * Spec developers. + * Server admins. + * Matrix packagers & maintainers. + * Companies building products or services on Matrix. + * Bridge developers. + * Bot developers. + * Widget developers. + * Server developers. + * Matrix room and community moderators. + * End-users who are using Matrix indirectly via bridges. + * External systems which are bridged into Matrix. + * Anyone using Matrix for data communications. "Greater benefit" is defined as maximising: - * the number of Matrix-native end-users reachable on the open Matrix network - * the number of regular users on the Matrix network (e.g. 30-day retained federated users) - * the number of online servers in the open federation - * the number of developers building on Matrix - * the number of independent implementations which use Matrix - * the number of bridged end-users reachable on the open Matrix network - * the signal-to-noise ratio of the content on the open Matrix network (i.e. minimising spam) - * the ability for users to discover content on their terms (empowering them to select what to see and what not to see) + * the number of Matrix-native end-users reachable on the open Matrix network. + * the number of regular users on the Matrix network (e.g. 30-day retained federated users). + * the number of online servers in the open federation. + * the number of developers building on Matrix. + * the number of independent implementations which use Matrix. + * the number of bridged end-users reachable on the open Matrix network. + * the signal-to-noise ratio of the content on the open Matrix network (i.e. minimising spam). + * the ability for users to discover content on their terms (empowering them to select what to see and what not to see). * the quality and utility of the Matrix spec (as defined by ease and ability with which a developer can implement spec-compliant clients, servers, bots, bridges, and other integrations without needing to refer to any other - external material) + external material). N.B. that we consider success to be the growth of the open federated network rather than closed deployments. For example, if WhatsApp adopted Matrix it @@ -129,16 +129,16 @@ As Matrix evolves, it's critical that the Spec Core Team and Guardians are aligned on the overall philosophy of the project, particularly in more subjective areas. The values we follow are: - * Supporting the whole long-term ecosystem rather than individual stakeholder gain - * Openness rather than proprietary lock-in - * Interoperability rather than fragmentation - * Cross-platform rather than platform-specific - * Collaboration rather than competition - * Accessibility rather than elitism - * Transparency rather than stealth - * Empathy rather than contrariness - * Pragmatism rather than perfection - * Proof rather than conjecture + * Supporting the whole long-term ecosystem rather than individual stakeholder gain. + * Openness rather than proprietary lock-in. + * Interoperability rather than fragmentation. + * Cross-platform rather than platform-specific. + * Collaboration rather than competition. + * Accessibility rather than elitism. + * Transparency rather than stealth. + * Empathy rather than contrariness. + * Pragmatism rather than perfection. + * Proof rather than conjecture. Patent encumbered IP is strictly prohibited from being added to the standard. @@ -198,19 +198,19 @@ Members must arrange their own funding for their time. Responsibilities include: - * Reviewing Matrix Spec Change proposals and Spec PRs + * Reviewing Matrix Spec Change proposals and Spec PRs. * Contributing to and reviewing reference implementations of Matrix Spec Change - proposals + proposals. - * Shepherding Matrix Spec Changes on behalf of authors where needed + * Shepherding Matrix Spec Changes on behalf of authors where needed. - * Triaging Matrix Spec issues + * Triaging Matrix Spec issues. - * Coordinating reference implementations + * Coordinating reference implementations. * Ensuring the code of conduct for +matrix:matrix.org community rooms is - maintained and applied + maintained and applied. If members are absent (uncontactable) for more than 8 weeks without prior agreement, they will be assumed to have left the project. @@ -283,18 +283,18 @@ is following its guiding principles, and provide a safety mechanism if the structure of the Spec Core Team runs into trouble. In practice, this means that: - * Guardians must approve changes to the Spec Core Team - * Guardians must keep each other honest, providing a ‘checks and balances’ + * Guardians must approve changes to the Spec Core Team. + * Guardians must keep each other honest, providing a ‘checks and balances’. mechanism between each other to ensure that all Guardians and the Spec Core Team act in the best interests of the protocol and ecosystem. * Guardians may appoint/dismiss members of the Spec Core Team who are in serious breach of the guiding principles. This overrides the unanimous consent requirement for the Spec Core Team when appointing new members. * Guardians may also override deadlocks when appointing a Spec Core Team leader - (with a >= 75% majority) + (with a >= 75% majority). * Guardians must approve changes to the Guiding Principles (above) * Guardians are responsible for approving use of the Foundation's assets - (e.g. redistributing donations) + (e.g. redistributing donations). * In future, Guardians may also be responsible for ensuring staff are hired by the Foundation to support administrative functions and other roles required to facilitate the Foundation's mission. @@ -354,46 +354,46 @@ community. Responsibilities include: * Helping ensure the quality of the projects' code repositories - * Ensuring all commits are reviewed - * Ensuring that all projects follow the Matrix spec - * Helping architect the implementations - * Contributing code to the implementations + * Ensuring all commits are reviewed. + * Ensuring that all projects follow the Matrix spec. + * Helping architect the implementations. + * Contributing code to the implementations. * Fostering contributions and engaging with contributors constructively in a - way that fosters a healthy and happy community - * Following the Guiding Principles and promoting them within the community + way that fosters a healthy and happy community. + * Following the Guiding Principles and promoting them within the community. Code Core Team members must arrange their own funding for their time. ## Functions of the Foundation - * Independent legal entity which acts as neutral custodian of Matrix - * Gathers donations + * Independent legal entity which acts as neutral custodian of Matrix. + * Gathers donations. * Owns the core Matrix IP in an asset lock, which shall be transferred from New Vector: - * Owns the matrix.org domain and branding + * Owns the matrix.org domain and branding. * Owns the copyright of the reference implementations of Matrix (i.e. everything in https://github.com/matrix-org). By assigning copyright to the Foundation, it’s protected against New Vector ever being tempted to relicense it. - * Owns the IP of the website - * Owns the Matrix.org marketing swag (t-shirts, stickers, exhibition stands etc) - * Responsible for finding someone to run the Matrix.org homeserver (currently New Vector) - * Publishes the spec - * Responsible for tools and documentation that supports the spec - * Responsible for ensuring reference implementations and test suite exists for the spec - * Publishes the website (including ensuring This Week In Matrix and similar exist to promote independent projects) + * Owns the IP of the website. + * Owns the Matrix.org marketing swag (t-shirts, stickers, exhibition stands etc). + * Responsible for finding someone to run the Matrix.org homeserver (currently New Vector). + * Publishes the spec. + * Responsible for tools and documentation that supports the spec. + * Responsible for ensuring reference implementations and test suite exists for the spec. + * Publishes the website (including ensuring This Week In Matrix and similar exist to promote independent projects). * Manages any future IANA-style allocations for Matrix, such as: - * mx:// URI scheme - * TCP port 8448 + * mx:// URI scheme. + * TCP port 8448. * .well-known URIs * Ensures that Matrix promotion is happening (e.g. ensuring that meetups & - events & community activity is supported) + events & community activity is supported). In future: * contracts entities to work on Matrix if such contracts help the Foundation to fulfil its mission and obey the Guiding Principles (e.g. redistributing donations back to fund development of reference implementations or compliance - kits) + kits). * manages a "Made for Matrix" certification process? (to confirm that products - are actually compatible with Matrix) + are actually compatible with Matrix). ## Timings From cc6b6ea021645f93b339bc17df1cfaf92f079fd2 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 Jan 2019 00:31:08 +0000 Subject: [PATCH 048/497] clarify wording for trojan horsen --- proposals/1779-open-governance.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 58e43b80..38469a06 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -173,13 +173,13 @@ toxic culture of bullying or competitive infighting. Folks need to be able to compromise; we are not building a culture of folks pushing their personal agendas at the expense of the overall project. -We are particularly vigilant against 'trojan horse' additions to the spec - -features which only benefit particular players, or are designed to somehow -cripple or fragment the open protocol and ecosystem in favour of competitive -advantage. Commercial players are of course free to build proprietary -implementations, or use custom event types, or even custom API extensions (e.g. -more efficient network transports) - but implementations must fall back to -interoperating correctly with the rest of the ecosystem. +The team should be particularly vigilant against 'trojan horse' additions to the +spec - features which only benefit particular players, or are designed to +somehow cripple or fragment the open protocol and ecosystem in favour of +competitive advantage. Commercial players are of course free to build +proprietary implementations, or use custom event types, or even custom API +extensions (e.g. more efficient network transports) - but implementations must +fall back to interoperating correctly with the rest of the ecosystem. ### Spec Core Team logistics From 8f4e1d9686993097df415ee71bf4dd16d4257b34 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 Jan 2019 00:32:14 +0000 Subject: [PATCH 049/497] clarify guardian selection wording --- proposals/1779-open-governance.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 38469a06..7fbb786f 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -50,9 +50,9 @@ responsible for ensuring that the Foundation (and by extension the Spec Core Team) keeps on mission and neutrally protects the development of Matrix. Guardians are typically independent of the commercial Matrix ecosystem and may even not be members of today’s Matrix community, but are deeply aligned with the -mission of the project, and who are respected and trusted by the wider community -to uphold the guiding principles of the Foundation and keep the other Guardians -honest. +mission of the project. Guardians are selected to be respected and trusted by +the wider community to uphold the guiding principles of the Foundation and keep +the other Guardians honest. In other words; the Spec Core Team builds the spec, and the Guardians provide an independent backstop to ensure the spec evolves in line with the Foundation's From 80b9c83ccea64d31732a35642653eeb326cf2f20 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 15 Jan 2019 10:00:17 +0000 Subject: [PATCH 050/497] clarify dual-hatted guardians & spec core teamistas --- proposals/1779-open-governance.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 7fbb786f..9f6a49d3 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -270,7 +270,9 @@ The above governance process for the Spec Core Team is considered as part of the spec and is updated using the Matrix Spec Change process. However, changes to the governance process also require a 75% positive approval from the Guardians (acting as a formal decision of the Foundation's Directors), in order to ensure -changes are aligned with the Foundation's mission. +changes are aligned with the Foundation's mission. For avoidance of doubt, Spec +Core Team votes and Guardians' votes are distinct and a person having both hats +has to vote independently on both forums with the respective hat on. ## The Guardians From 3b86fa0e3c5ef217e112cd1bcf3dc4c082638520 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Thu, 17 Jan 2019 23:56:49 +0000 Subject: [PATCH 051/497] incorporating delph & vdh reviews --- proposals/1779-open-governance.md | 100 ++++++++++++++++++------------ specification/proposals_intro.rst | 22 +++---- 2 files changed, 72 insertions(+), 50 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 9f6a49d3..dde9aeac 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -69,9 +69,9 @@ We believe: * People should have full control over their own communication. - * People should not be locked into centralised communication silos, but free to - pick who they choose to host their communication without limiting who they - can reach. + * People should not be locked into centralised communication silos, but instead + be free to pick who they choose to host their communication without limiting + who they can reach. * The ability to converse securely and privately is a basic human right. @@ -80,9 +80,9 @@ We believe: ### Mission -The Matrix.org Foundation exists to act as a neutral custodian for Matrix and +The Matrix.org Foundation exists to act as a neutral custodian for Matrix and to nurture it as efficiently as possible as a single unfragmented standard, for the -greater benefit of the whole ecosystem; not benefiting or privileging any single +greater benefit of the whole ecosystem, not benefiting or privileging any single player or subset of players. For clarity: the Matrix ecosystem is defined as anyone who uses the Matrix @@ -185,8 +185,8 @@ fall back to interoperating correctly with the rest of the ecosystem. The Spec Core Team itself will be made up of roughly 8 members + 1 project lead. Roughly half the members are expected to be from the historical core team -(similar to Rust). The team must have 5 members to be quorate, with the aim of -generally having between 7 and 9 members. +(similar to Rust). The team must have 5 members to be able to function, with +the aim of generally having between 7 and 9 members. In future we may also have sub-teams (like Rust - e.g. CS/AS/Push API; SS API; IS API; Crypto), but as a starting point we are beginning with a single core @@ -221,13 +221,14 @@ of the team and the Guardians on doing so. New additions to the team require 100% consent from the current team members. Membership has to be formally proposed by someone already on the Spec Core Team. -Members can be removed from the team if >= 75% of the team agrees they are no -longer following the goals and guiding principles of the project. (The 75% is -measured of the whole team, including the member in question) +Members can be removed from the team if 75% of the current members approves and +agrees they are no longer following the goals and guiding principles of the +project. (The 75% is measured of the whole team, including the member in +question). -Guardians act as a backstop, and can appoint or remove Spec Core Team members -(requiring a 75% consensus threshold between the Guardians) if the Spec Core -Team is unable to function or is failing to align with the Foundation's mission. +Guardians act as a safety net, and can appoint or remove Spec Core Team members +(requiring approval by 75% of the current Guardians) if the Spec Core Team is +unable to function or is failing to align with the Foundation's mission. It's suggested that one of the Spec Core Team members should also be a Guardian, to facilitate information exchange between the Guardians and the Spec Core Team, @@ -236,12 +237,14 @@ and to represent the technical angle of the project to the other Guardians. The project lead role acts to coordinate the team and to help steer the team to consensus in the event of failing to get agreement on a Matrix Spec Change. Every 12 months, a vote of confidence is held in the project lead, requiring the -confidence of 75% of the team for the lead to be renewed. There is no maximum -term for the project lead. The lead may be removed by the core team at any -point (with 75% majority), and may resign the role at any point (notifying the -team and the Guardians). The lead automatically resigns the role if they resign -from the Spec Core Team. Resignation automatically triggers selection of a new -lead, who must be selected from the existing Spec Core Team. +approval of 75% of the current Spec Core Team members for the lead to be +renewed. There is no maximum term for the project lead. The lead may be +removed by the core team at any point (requiring 75% approval of current +members), and may resign the role at any point (notifying the team and the +Guardians). The lead automatically resigns the role if they resign from the +Spec Core Team. Resignation automatically triggers selection of a new lead, who +must be selected from the existing Spec Core Team with 75% approval from current +members within 14 days. It is vital that the core spec team has strong domain expertise covering all different domains of the spec (e.g. we don't want to end up with a core spec @@ -259,21 +262,24 @@ The initial Spec Core Team (and their domain areas) is: * Alexey Rusakov (Clients on behalf of Community) * TBD -MSCs require >= 75% approval from the Spec Core Team to proceed to Final Comment -Period (see https://matrix.org/docs/spec/proposals for the rest of the MSC -process). +MSCs require approval by 75% of the current members of the Spec Core Team to +proceed to Final Comment Period (see https://matrix.org/docs/spec/proposals for +the rest of the MSC process). Even though a threshold of only 75% is required for approval, the Spec Core Team is expected to seek consensus on MSCs. The above governance process for the Spec Core Team is considered as part of the spec and is updated using the Matrix Spec Change process. However, changes to -the governance process also require a 75% positive approval from the Guardians +the governance process also require approval by 75% of the current Guardians (acting as a formal decision of the Foundation's Directors), in order to ensure changes are aligned with the Foundation's mission. For avoidance of doubt, Spec Core Team votes and Guardians' votes are distinct and a person having both hats has to vote independently on both forums with the respective hat on. +Spec Core Team decisions (e.g. appointing/removing members and lead) +should be published openly and transparently for the public. + ## The Guardians *This section will be used as the basis for the legal responsibilities of @@ -285,16 +291,23 @@ is following its guiding principles, and provide a safety mechanism if the structure of the Spec Core Team runs into trouble. In practice, this means that: - * Guardians must approve changes to the Spec Core Team. + + * Guardians are responsible for ensuring the Spec Core Team continues to + function, and have the power to appoint/dismiss members of the spec core team + (with the agreement of 75% of the Guardians) to address issues with the Spec + Core Team. * Guardians must keep each other honest, providing a ‘checks and balances’. mechanism between each other to ensure that all Guardians and the Spec Core Team act in the best interests of the protocol and ecosystem. - * Guardians may appoint/dismiss members of the Spec Core Team who are in serious - breach of the guiding principles. This overrides the unanimous consent - requirement for the Spec Core Team when appointing new members. + * Guardians may dismiss members of the Spec Core Team who are in serious + breach of the guiding principles. + * Guardians may appoint members of the Spec Core Team to break deadlocks in the + unanimous consent requirement for the Spec Core Team when appointing new + members. * Guardians may also override deadlocks when appointing a Spec Core Team leader - (with a >= 75% majority). - * Guardians must approve changes to the Guiding Principles (above) + (with approval of 75% of the current Guardians). + * Guardians must approve changes to the above Guiding Principles (with approval + of 75% of the current Guardians) * Guardians are responsible for approving use of the Foundation's assets (e.g. redistributing donations). * In future, Guardians may also be responsible for ensuring staff are hired by @@ -303,8 +316,14 @@ In practice, this means that: * As well as the Spec Core Team committee, they may also oversee committees for other areas such as marketing Matrix.org, registering custom event types, or "Made for Matrix" certification. - * It's likely a subset of Guardians will be hands-on for day-to-day - administrative purposes, whilst the others act to keep them in balance. + * Guardians are responsible for choosing if, when and how staff are located by + the Foundation to fill administrative and other functions required to + facilitate the Foundations' mission. + * Guardians are responsible for choosing if and when additional committees are + formed, and to oversee those committees. + * Guardians are not required to be involved on a day-to-day basis, however + those not taking a hands on approach are required to monitor to ensure a + suitable balance is kept by those that do. Guardians are chosen typically to be independent of the commercial Matrix ecosystem (and especially independent from New Vector), and may even not be @@ -313,18 +332,18 @@ the mission of the project, and respected and trusted by the wider community to uphold the guiding principles of the Foundation and keep the other Guardians honest. -Guardians are responsible for maintaining and updating the Guiding -Principles and Articles of Association of the Foundation if/when -necessary. Changes to the Guiding Principles require a 75% majority from the -Guardians and are passed as a 'special resolution' of the board. +Guardians are responsible for maintaining and updating the Guiding Principles +and Articles of Association of the Foundation if/when necessary. Changes to the +Guiding Principles require approval from 75% of the current Guardians and are +passed as a 'special resolution' of the board. -New Guardians may be appointed with a 75% majority by the board. +New Guardians may be appointed with approval from 75% of the current Guardians. Guardians may resign at any time, with notification to the board. -Guardians may be removed due to serious breach of the guiding principles with a -75% majority of the other Guardians, or if absent from 3 consecutive board -meetings, or if they are legally disqualified from acting as a Director. +Guardians may be removed due to serious breach of the guiding principles with +approval by 75% of the other current Guardians, or if absent from 3 consecutive +board meetings, or if they are legally disqualified from acting as a Director. We aim to recruit roughly 5 Guardians. The initial Guardians are: @@ -340,6 +359,9 @@ Foundation relative to Matthew & Amandine’s day jobs at New Vector. Guardians must arrange their own funding for their time. +Guardian decisions (e.g. appointing/removing guardians; changes to the spec core +team; etc) should be published openly and transparently for the public. + ## The Code Core Team (aka The Core Team) The "Core Team" (or the "Code Core Team", to disambiguate from the Spec Core diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 1e93a22a..87828916 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -19,10 +19,10 @@ proposal being accepted, then actually having your ideas implemented as committed changes to the `Specification repository `_. -Meet the `members of the Core Team +Meet the `members of the Spec Core Team `_, a group of individuals tasked with ensuring the spec process is as smooth and painless as -possible. Members of the Core Team will do their best to participate in +possible. Members of the Spec Core Team will do their best to participate in discussion, summarise when things become long-winded, and generally try to act towards the benefit of everyone. As a majority, team members have the ability to change the state of a proposal, and individually have the final say in @@ -74,7 +74,7 @@ their proposed changes to the Matrix protocol: * Pragmatism rather than perfection * Proof rather than conjecture -Please see [MSC1779](https://github.com/matrix-org/matrix-doc/pull/1779) +Please see [MSC1779](https://github.com/matrix-org/matrix-doc/blob/matthew/msc1779/proposals/1779-open-governance.md) for full details of the project's Guiding Principles. Technical notes @@ -213,25 +213,25 @@ follows: viewpoints and get consensus, but this can sometimes be time-consuming (or the author may be biased), in which case an impartial 'shepherd' can be assigned to help guide the proposal through this process instead. A shepherd is - typically a neutral party from the Core Team or an experienced member of + typically a neutral party from the Spec Core Team or an experienced member of the community. There is no formal process for assignment. Simply ask for a shepherd to help get your proposal through and one will be assigned based on availability. Having a shepherd is not a requirement for proposal acceptance. -- Members of the Core Team and community will review and discuss the PR in the +- Members of the Spec Core Team and community will review and discuss the PR in the comments and in relevant rooms on Matrix. Discussion outside of GitHub should be summarised in a comment on the PR. -- When a member of the Core Team believes that no new discussion points are +- When a member of the Spec Core Team believes that no new discussion points are being made, they will propose a motion for a final comment period (FCP), along with a *disposition* of either merge, close or postpone. This FCP is provided to allow a short period of time for any invested party to provide a final objection before a major decision is made. If sufficient reasoning is given, an FCP can be cancelled. It is often preceded by a comment summarising the current state of the discussion, along with reasoning for its occurrence. -- A concern can be raised by a Core Team member at any time, which will block - an FCP from beginning. An FCP will only begin when a **majority** of core - team members agree on its outcome, and all existing concerns have been +- A concern can be raised by a Spec Core Team member at any time, which will block + an FCP from beginning. An FCP will only begin when 75% of the members of the + Spec Core Team team agree on its outcome, and all existing concerns have been resolved. - The FCP will then begin and last for 5 days, giving anyone else some time to speak up before it concludes. On its conclusion, the disposition of the FCP @@ -321,7 +321,7 @@ Lifetime States Name GitHub Label Description =============================== ============================= ==================================== Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback -Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Core Team and community +Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Spec Core Team and community Proposed Final Comment Period proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period Final Comment Period final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement Final Commment Period Complete finished-final-comment-period The final comment period has been completed. Waiting for a demonstration implementation @@ -342,7 +342,7 @@ pull request trackers of the `matrix-doc `_ repo. We use labels and some metadata in MSC PR descriptions to generate this page. -Labels are assigned by the Core Team whilst triaging the proposals based on those +Labels are assigned by the Spec Core Team whilst triaging the proposals based on those which exist in the `matrix-doc `_ repo already. From 20b9a33b1240a45cae4419ba19ff5670195cfb99 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Fri, 18 Jan 2019 22:39:26 +0000 Subject: [PATCH 052/497] clarify 100% threshold for new spec core team additions --- proposals/1779-open-governance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index dde9aeac..779e94ab 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -218,7 +218,7 @@ agreement, they will be assumed to have left the project. Spec Core Team members can resign whenever they want, but must notify the rest of the team and the Guardians on doing so. -New additions to the team require 100% consent from the current team members. +New additions to the team must be approved by all current members of the team. Membership has to be formally proposed by someone already on the Spec Core Team. Members can be removed from the team if 75% of the current members approves and From 41c14c9e7df76efbbcc70eab2b93669a64909a40 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 18 Jan 2019 22:56:19 +0000 Subject: [PATCH 053/497] uhoreg tweaks Co-Authored-By: ara4n --- proposals/1779-open-governance.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 779e94ab..0a1cfca4 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -377,7 +377,7 @@ the core team is also signified by membership of the +matrix:matrix.org Matrix community. Responsibilities include: - * Helping ensure the quality of the projects' code repositories + * Helping ensure the quality of the projects' code repositories. * Ensuring all commits are reviewed. * Ensuring that all projects follow the Matrix spec. * Helping architect the implementations. @@ -400,7 +400,7 @@ Code Core Team members must arrange their own funding for their time. * Owns the Matrix.org marketing swag (t-shirts, stickers, exhibition stands etc). * Responsible for finding someone to run the Matrix.org homeserver (currently New Vector). * Publishes the spec. - * Responsible for tools and documentation that supports the spec. + * Responsible for tools and documentation that support the spec. * Responsible for ensuring reference implementations and test suite exists for the spec. * Publishes the website (including ensuring This Week In Matrix and similar exist to promote independent projects). * Manages any future IANA-style allocations for Matrix, such as: @@ -412,11 +412,11 @@ Code Core Team members must arrange their own funding for their time. In future: - * contracts entities to work on Matrix if such contracts help the Foundation to + * Contracts entities to work on Matrix if such contracts help the Foundation to fulfil its mission and obey the Guiding Principles (e.g. redistributing donations back to fund development of reference implementations or compliance kits). - * manages a "Made for Matrix" certification process? (to confirm that products + * Manages a "Made for Matrix" certification process? (to confirm that products are actually compatible with Matrix). ## Timings From a358e2d4d8e8d1128dc308306eaec91b188ed547 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 28 Jan 2019 14:57:59 +0000 Subject: [PATCH 054/497] rst --- specification/proposals_intro.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 9274b2a9..44fcf4b1 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -111,6 +111,7 @@ engine behaviour be specified? There is no universal answer to this, but the following guidelines should be applied: + 1. If the feature would benefit the whole Matrix ecosystem and is aligned with the guiding principles above, then it should be supported by the spec. 2. If the spec already makes the feature possible without changing any of the @@ -122,6 +123,7 @@ applied: 3rd party behaviour. As a worked example: + 1. Video conferencing is clearly a feature which would benefit the whole ecosystem, and so the spec should find a way to make it happen. 2. Video conferencing can be achieved by widgets without requiring any From f9a00fc943d9ae49ae32845a7a971578ff84c4a0 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 Mar 2019 23:25:11 -0400 Subject: [PATCH 055/497] clarify that not understanding a verification method should not auto-cancel --- proposals/1717-key_verification.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index b536be0e..10ccf785 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -28,7 +28,10 @@ appropriate `m.key.verification.cancel` message is received. If Bob chooses to reject the key verification request, Bob's client should send a `m.key.verification.cancel` message to Alice's device. If Bob's client does not understand any of the methods offered, it should display a message to Bob -saying so. +saying so. However, it should not send a `m.key.verification.cancel` message +to Alice's device unless Bob chooses to reject the verification request, as Bob +may have another device that is capable of verifying using one of the given +methods. To initiate a key verification process, Bob's device sends a `to_device` event to one of Alice's devices with the `type` set to `m.key.verification.start`. From 4842a718d8ab3c4000e86270d3ef3aea6cf42154 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 Mar 2019 23:39:00 -0400 Subject: [PATCH 056/497] fill in some of the other sections --- proposals/1717-key_verification.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 10ccf785..9296cf40 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -132,10 +132,18 @@ convention. ## Tradeoffs -## Potential issues +Rather than broadcasting verification requests to Bob's devices, Alice could +simply send an `m.key.verification.start` request to a single device. However, +this would require Alice to choose the right device to send to, which may be +hard for Alice to do if, for example, Bob has many devices, or if his devices +have similar names. ## Security considerations +An attacker could try to spam a user with verification requests. Clients +should take care that such requests do not interfere with a user's use of the +client. + ## Conclusion This proposal presents common event definitions for use by key verification From 1749a91344786815ecbae43a53e19fb53157c307 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 Mar 2019 23:41:43 -0400 Subject: [PATCH 057/497] make MSC mentions into links --- proposals/1717-key_verification.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 9296cf40..02018ef9 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -2,8 +2,10 @@ Key verification is an essential part of ensuring that end-to-end encrypted messages are secure. Matrix may support multiple verification methods that -require sending events; in fact, two such methods (such as MSC1267 and MSC1543) -have already been proposed. +require sending events; in fact, two such methods (such as [MSC +1267](https://github.com/matrix-org/matrix-doc/issues/1267) and [MSC +1543](https://github.com/matrix-org/matrix-doc/issues/1543)) have already been +proposed. This proposal tries to present a common framework for verification methods to use, and presents a way to request key verification. From 696e568fb2101480826d873fac83897ae904472a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 26 Mar 2019 15:10:14 -0400 Subject: [PATCH 058/497] add some clarifications --- proposals/1717-key_verification.md | 46 +++++++++++++++++++----------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 02018ef9..6c9e2341 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -19,26 +19,40 @@ Java package naming convention. If Alice wants to verify keys with Bob, Alice's device may send `to_device` events to Bob's devices with the `type` set to `m.key.verification.request`, as -described below. The event lists the verification methods that Alice's device -supports. Upon receipt of this message, Bob's client should prompt him to -verify keys with Alice using one of the applicable methods. In order to avoid -displaying stale key verification prompts, if Bob does not interact with the -prompt, it should be automatically hidden 10 minutes after the message is sent -(according to the `timestamp` field), or 2 minutes after the client receives -the message, whichever comes first. The prompt should also be hidden if an -appropriate `m.key.verification.cancel` message is received. If Bob chooses to -reject the key verification request, Bob's client should send a -`m.key.verification.cancel` message to Alice's device. If Bob's client does -not understand any of the methods offered, it should display a message to Bob -saying so. However, it should not send a `m.key.verification.cancel` message -to Alice's device unless Bob chooses to reject the verification request, as Bob -may have another device that is capable of verifying using one of the given -methods. +described below. The `m.key.verification.request` messages should all have the +same `transaction_id`, and are considered to be a single request. Thus, for +example, if Bob rejects the request on one device, then the entire request +should be considered as rejected across all of his devices. Similarly, if Bob +accepts the request on one device, that device is now in charge of completing +the key verification, and Bob's other devices no longer need to be involved. + +The `m.key.verification.request` event lists the verification methods that +Alice's device supports, and upon receipt of this message, Bob's client should +prompt him to verify keys with Alice using one of the applicable methods. In +order to avoid displaying stale key verification prompts, if Bob does not +interact with the prompt, it should be automatically hidden 10 minutes after +the message is sent (according to the `timestamp` field), or 2 minutes after +the client receives the message, whichever comes first. The prompt should also +be hidden if an appropriate `m.key.verification.cancel` message is received. + +If Bob chooses to reject the key verification request, Bob's client should send +a `m.key.verification.cancel` message to Alice's device. This indicates to +Alice that Bob does not wish to verify keys with her. In this case, Alice's +device should send an `m.key.verification.cancel` message to all of Bob's +devices to notify them that the request has been rejected. + +If one of Bob's clients does not understand any of the methods offered, it +should display a message to Bob saying so. However, it should not send a +`m.key.verification.cancel` message to Alice's device unless Bob chooses to +reject the verification request, as Bob may have another device that is capable +of verifying using one of the given methods. To initiate a key verification process, Bob's device sends a `to_device` event to one of Alice's devices with the `type` set to `m.key.verification.start`. This may either be done in response to an `m.key.verification.request` message, -or can be done independently. If Alice's device receives an +or can be done independently. If it is done in response to an +`m.key.verification.request` messsage, it should use the same `transaction_id` +as the `m.key.verification.request` message. If Alice's device receives an `m.key.verification.start` message in response to an `m.key.verification.request` message, it should send an `m.key.verification.cancel` message to Bob's other devices that it had From 29a9982447a946e7338749031a68e1fa7937df0f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 7 Apr 2019 21:04:52 -0600 Subject: [PATCH 059/497] Proposal for integration manager discovery --- proposals/0000-integrations-discovery.md | 133 +++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 proposals/0000-integrations-discovery.md diff --git a/proposals/0000-integrations-discovery.md b/proposals/0000-integrations-discovery.md new file mode 100644 index 00000000..c09551a8 --- /dev/null +++ b/proposals/0000-integrations-discovery.md @@ -0,0 +1,133 @@ +# MSC0000: Integration manager discovery + +*Note*: This is a required component of [MSC1956 - Integrations API](https://github.com/matrix-org/matrix-doc/pull/1956) + +Users should have the freedom to choose which integration manager they want to use in their client, while +also accepting suggestions from their homeserver and client. Clients need to know where to find the different +integration managers and how to contact them. + + +## Proposal + +A single logged in user may be influenced by zero or more integration managers at any given time. Managers +are sourced from the client's own configuration, homeserver discovery information, and the user's personal +account data in the form of widgets. Clients should support users using more than one integration manager +at a given time, although the rules for how this can be handled are defined later in this proposal. + +#### Client-configured integration managers + +This is left as an implementation detail. In the case of Riot, this is likely to be part of the existing +`config.json` options, although liekly modified to support multiple managers instead of one. + +#### Homeserver-configured integration managers + +The integration managers suggested by a homeserver are done through the existing +[.well-known](https://matrix.org/docs/spec/client_server/r0.4.0.html#get-well-known-matrix-client) discovery +mechanism. The added optional fields, which should not affect a client's ability to log a user in, are: +```json +{ + "m.integrations": { + "managers": [ + { + "api_url": "https://integrations.example.org", + "ui_url": "https://integrations.example.org/ui" + }, + { + "api_url": "https://bots.example.org" + } + ] + } +} +``` + +As shown, the homeserver is able to suggest multiple integration managers through this method. Each manager +must have an `api_url` which must be an `http` or `https` URL. The `ui_url` is optional and if not provided +is the same as the `api_url`. Like the `api_url`, the `ui_url` must be `http` or `https` if supplied. + +The `ui_url` is ultimately treated the same as a widget, except that the custom `data` is not present and +must not be templated here. Variables like `$matrix_display_name` are able to function, however. Integration +managers should never use the `$matrix_user_id` as authoritative and instead seek other ways to determine the +user ID. This is covered by other proposals. + +The `api_url` is the URL clients will use when *not* embedding the integration manager, and instead showing +its own purpose-built interface. + +#### User-configured integration managers + +Users can specify integration managers in the form of account widgets. The `type` is to be `m.integration_manager` +and the content would look something similar to: +```json +{ + "url": "https://integrations.example.org/ui?displayName=$matrix_display_name", + "data": { + "api_url": "https://integrations.example.org" + } +} +``` + +The `api_url` in the `data` object is required and has the same meaning as the homeserver-defined `api_url`. +The `url` of the widget is analogous to the `ui_url` from the homeserver configuration above, however normal +widget rules apply here. + +The user is able to have multiple integration managers through use of multiple widgets. + +#### Display order of integration managers + +Clients which have support for integration managers should display at least 1 manager, but may decide +to display multiple via something like tabs. Clients must prefer to display the user's configured +integration managers over any defaults, and if only displaying one manager must pick the first +manager after sorting the `state_key`s in lexicographical order. Clients may additionally display +default managers if they so wish, and should preserve the order defined in the various defaults. +If the user has no configured integration managers, the client must prefer to display one or more +of the managers suggested by the homeserver over the managers recommended by the client. + +The client may optionally support a way to entirely disable integration manager support, even if the +user and homeserver have managers defined. + +The rationale for having the client prefer to use the user's integration managers first is so that +the user can tailor their experience within Matrix if desired. Similarly, a homeserver may wish to +subject all of their users to the same common integration manager as would be common in some organizations. +The client's own preference is a last ditch effort to have an integration manager available to the +user so they don't get left out. + +#### Displaying integration managers + +Clients simply open the `ui_url` (or equivalent) in an `iframe` or similar. In the current ecosystem, +integration managers would receive a `scalar_token` to idenitify the user - this is no longer the case +and instead integration managers must seek other avenues for determining the user ID. Other proposals +cover how to do this in the context of the integrations API. + +Integration managers shown in this way must be treated like widgets, regardless of source. In practice +this means exposing the Widget API to the manager and applying necessary scoping to keep the manager +as an account widget rather than a room widget. + + +## Tradeoffs + +We could limit the user (and by extension, the homeserver and client) to exactly 1 integration manager +and not worry about tabs or other concepts, however this restricts a user's access to integrations. +In a scenario where the user wants to use widgets from Service A and bots from Service B, they'd +end up switching accounts or clients to gain access to either service, or potentially just give up +and walk away from the problem. Instead of having the user switch between clients, we might as well +support this use case, even if it is moderately rare. + +We could also define the integration managers in a custom account data event rather than defining them +as a widget. Doing so just adds clutter to the account data and risks duplicating code in clients as +using widgets gets us URL templating for free (see the section later on in this proposal about account +widgets for more information). + + +## Future extensions + +Some things which may be desirable in the future are: +* Avatars for the different managers +* Human-readable names for the different managers +* Supporting `ui_url`s targeting specific clients for a more consistent design + + +## Security considerations + +When displaying integration managers, clients should not trust that the input is sanitary. Integration +managers may only be at HTTP(S) endpoints and may still have malicious intent. Ensure any sandboxing +on the manager is appropriate such that it can communicate with the client, but cannot perform unauthorized +actions. From cc10444d4b3dceac24ae15648e2ab0f078fa99a2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 7 Apr 2019 21:06:42 -0600 Subject: [PATCH 060/497] Assign MSC number --- proposals/0000-integrations-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/0000-integrations-discovery.md b/proposals/0000-integrations-discovery.md index c09551a8..7672e024 100644 --- a/proposals/0000-integrations-discovery.md +++ b/proposals/0000-integrations-discovery.md @@ -1,4 +1,4 @@ -# MSC0000: Integration manager discovery +# MSC1957: Integration manager discovery *Note*: This is a required component of [MSC1956 - Integrations API](https://github.com/matrix-org/matrix-doc/pull/1956) From dffe19bb76226f956d35d79e6e67c256e4b9a896 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 7 Apr 2019 21:07:46 -0600 Subject: [PATCH 061/497] Rename file to match MSC number --- ...0-integrations-discovery.md => 1957-integrations-discovery.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{0000-integrations-discovery.md => 1957-integrations-discovery.md} (100%) diff --git a/proposals/0000-integrations-discovery.md b/proposals/1957-integrations-discovery.md similarity index 100% rename from proposals/0000-integrations-discovery.md rename to proposals/1957-integrations-discovery.md From 2dcda7d564d9e45538b95a08f5183c1628aff05a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 7 Apr 2019 21:17:14 -0600 Subject: [PATCH 062/497] Add a mention that clients should re-query .well-known --- proposals/1957-integrations-discovery.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index 7672e024..2eca300b 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -52,6 +52,11 @@ user ID. This is covered by other proposals. The `api_url` is the URL clients will use when *not* embedding the integration manager, and instead showing its own purpose-built interface. +Clients should query the `.well-known` information for the homeserver periodically to update the integration +manager settings for that homeserver. The client is not expected to validate or use any other information +contained in the response. Current recommendations are to query the configuration when the client starts up +and every 8 hours after that. + #### User-configured integration managers Users can specify integration managers in the form of account widgets. The `type` is to be `m.integration_manager` From 13d63685d379b68b4bb356822a64d78526ca65b1 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Mon, 8 Apr 2019 07:05:38 -0600 Subject: [PATCH 063/497] Spelling Co-Authored-By: turt2live --- proposals/1957-integrations-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index 2eca300b..fd6bc8f9 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -17,7 +17,7 @@ at a given time, although the rules for how this can be handled are defined late #### Client-configured integration managers This is left as an implementation detail. In the case of Riot, this is likely to be part of the existing -`config.json` options, although liekly modified to support multiple managers instead of one. +`config.json` options, although likely modified to support multiple managers instead of one. #### Homeserver-configured integration managers From d6d0f9780dc3948f25bac7880adea6602650ec4e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Apr 2019 21:36:16 -0600 Subject: [PATCH 064/497] Proposal for basic integration manager authentication APIs --- proposals/0000-integrations-auth.md | 69 +++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 proposals/0000-integrations-auth.md diff --git a/proposals/0000-integrations-auth.md b/proposals/0000-integrations-auth.md new file mode 100644 index 00000000..1a491790 --- /dev/null +++ b/proposals/0000-integrations-auth.md @@ -0,0 +1,69 @@ +# MSC0000: Integration manager authentication + +A set of common APIs needs to be defined for clients to be able to interact with an integration +manager. This proposal covers the authentication portion of that API. + + +## Proposal + +All specified APIs (except `/register`) will take an `Authorization` header with a `Bearer` token returned +from a call to `/register`. This token is used to authorize the request and to identify who is making the +request. + +#### POST /_matrix/integrations/v1/account/register + +Exchanges an OpenID object for a token which can be used to authorize future requests to the manager. + +Request body is an OpenID object as returned by `/_matrix/client/r0/user/:userId/openid/request_token`. + +Response is: +```json +{ + "token": "OpaqueString" +} +``` + +The token should consist of URL-safe base64 characters. Integration managers should be careful to validate +the OpenID object by ensuring the `/_matrix/federation/v1/openid/userinfo` response has a `sub` which belongs +to the `matrix_server_name` provided in the original OpenID object. + +Applications which register for a token are responsible for tracking which integration manager they are for. +This can usually be done by tracking the hostname of the integration manager and matching a token with it. + +#### GET /_matrix/integrations/v1/account + +Gets information about the token's owner, such as the user ID for which it belongs. + +Besides a token, no other information is required for the request. + +Response is: +```json +{ + "user_id": "@alice:example.org" +} +``` + +The `user_id` is the user ID which was represented in the OpenID object provided to `/register`. Integration +managers may be interested in also supplying information about the user's credit balance for paid integrations +here. Preferably, custom information is stored under a namespaced key like so: +```json +{ + "user_id": "@alice:example.org", + "org.example.paid.integrations": { + "credit": 20000 + } +} +``` + +#### POST /_matrix/integrations/v1/account/logout + +Logs the token out, rendering it useless for future requests. + +Request body is an empty object. Response body is also an empty object if successful. + + +## Security considerations + +Clients should be sure to call `/logout` where possible when the user is logging out or no longer needs access +to a given manager. Clients should additionally be cautious about which managers they register for tokens with, +as some integration managers may be untrusted. From 0bab70c14e84ff71146cc9a8dce7071e1021d75f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Apr 2019 21:37:35 -0600 Subject: [PATCH 065/497] Assign MSC number --- .../{0000-integrations-auth.md => 1961-integrations-auth.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{0000-integrations-auth.md => 1961-integrations-auth.md} (98%) diff --git a/proposals/0000-integrations-auth.md b/proposals/1961-integrations-auth.md similarity index 98% rename from proposals/0000-integrations-auth.md rename to proposals/1961-integrations-auth.md index 1a491790..863ea325 100644 --- a/proposals/0000-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -1,4 +1,4 @@ -# MSC0000: Integration manager authentication +# MSC1961: Integration manager authentication A set of common APIs needs to be defined for clients to be able to interact with an integration manager. This proposal covers the authentication portion of that API. From 14715468bb6aa157601fa271bd3a57507f90b8dd Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 26 Apr 2019 14:41:19 +0100 Subject: [PATCH 066/497] Make thumbnail dimensions mandatory Fixes #1883 --- api/client-server/content-repo.yaml | 2 ++ changelogs/client_server/newsfragments/1975.clarification | 1 + 2 files changed, 3 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1975.clarification diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 5f4e9111..07df18fe 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -202,6 +202,7 @@ paths: type: integer x-example: 64 name: width + required: true description: |- The *desired* width of the thumbnail. The actual thumbnail may not match the size specified. @@ -209,6 +210,7 @@ paths: type: integer x-example: 64 name: height + required: true description: |- The *desired* height of the thumbnail. The actual thumbnail may not match the size specified. diff --git a/changelogs/client_server/newsfragments/1975.clarification b/changelogs/client_server/newsfragments/1975.clarification new file mode 100644 index 00000000..03a9b754 --- /dev/null +++ b/changelogs/client_server/newsfragments/1975.clarification @@ -0,0 +1 @@ +Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``. It is somewhat meaningless to request a thumbnail without specifying a desired size, and Synapse has never permitted such requests. \ No newline at end of file From 4e9dc2098ff65acda435797b8d824653289f0e8b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 30 Apr 2019 17:43:21 +0100 Subject: [PATCH 067/497] Fix comments which refer to jenkins. (#1981) * Fix comments which refer to jenkins. * Spelling Co-Authored-By: turt2live --- scripts/test-and-build.sh | 2 +- specification/proposals.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/test-and-build.sh b/scripts/test-and-build.sh index 710b03dd..f45e2da6 100755 --- a/scripts/test-and-build.sh +++ b/scripts/test-and-build.sh @@ -30,5 +30,5 @@ go get gopkg.in/fsnotify/fsnotify.v1 # build the spec for matrix.org. # (we don't actually use it on travis, but it's still useful to check we -# can build it. On Jenkins, this is then used to deploy to matrix.org). +# can build it. On Buildkite, this is then used to deploy to matrix.org). ./scripts/generate-matrix-org-assets diff --git a/specification/proposals.rst b/specification/proposals.rst index 371850ab..94878f80 100644 --- a/specification/proposals.rst +++ b/specification/proposals.rst @@ -1,6 +1,6 @@ Tables of Tracked Proposals --------------------------- -This file is autogenerated by a jenkins build process +This file is generated by an automated process on our build server. -View the current live version `at https://matrix.org/docs/spec/proposals `_ +View the current live version `at https://matrix.org/docs/spec/proposals `_. From 7c7bc677fb485d3df0e2dcb52554eb1bf2bd7f28 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 7 May 2019 00:11:14 +0100 Subject: [PATCH 068/497] Trigger matrix.org rebuild --- .buildkite/pipeline.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.buildkite/pipeline.yaml b/.buildkite/pipeline.yaml index e98d7026..6e595120 100644 --- a/.buildkite/pipeline.yaml +++ b/.buildkite/pipeline.yaml @@ -9,3 +9,8 @@ steps: plugins: - docker#v3.0.1: image: "python:3.6" + + - label: "rebuild matrix.org" + trigger: "matrix-dot-org" + async: true + branches: "master" From da82a423084d4bd5a209e73548001fb89024aa35 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 15:40:39 -0700 Subject: [PATCH 069/497] fix grammatical error --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 59d241b6..8d8a2d06 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -182,7 +182,7 @@ process: field as the ``from`` parameter. If the client is tracking the device list of any of the users listed in the response, it marks them as outdated. It combines this list with those already flagged as outdated, and initiates a - |/keys/query|_ requests for all of them. + |/keys/query|_ request for all of them. .. Warning:: From c233535de00e8c66d80fa807535b68f3e9ec291b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 15:51:32 -0700 Subject: [PATCH 070/497] fix typo --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 59d241b6..9ad80a12 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -460,7 +460,7 @@ Keys can be manually exported from one device to an encrypted file, copied to another device, and imported. The file is encrypted using a user-supplied passphrase, and is created as follows: -1. Encode the sessions a JSON object, formatted as described in `Key export +1. Encode the sessions as a JSON object, formatted as described in `Key export format`_. 2. Generate a 512-bit key from the user-entered passphrase by computing `PBKDF2`_\(HMAC-SHA-512, passphrase, S, N, 512), where S is a 128-bit From 40482f76163951aaf95a2ccef848fc43789ec3f9 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 15:55:07 -0700 Subject: [PATCH 071/497] Add missing period --- specification/appendices/signing_json.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendices/signing_json.rst b/specification/appendices/signing_json.rst index 795d6669..8036950e 100644 --- a/specification/appendices/signing_json.rst +++ b/specification/appendices/signing_json.rst @@ -59,7 +59,7 @@ Grammar +++++++ Adapted from the grammar in http://tools.ietf.org/html/rfc7159 removing -insignificant whitespace, fractions, exponents and redundant character escapes +insignificant whitespace, fractions, exponents and redundant character escapes. .. code:: From 3c62b90dfbf58a4ff99c4e7fc403d8737816dc2b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 16:59:10 -0700 Subject: [PATCH 072/497] Add missing punctuation --- api/client-server/keys.yaml | 2 +- api/server-server/user_keys.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 55f8a5a5..718703fd 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -253,7 +253,7 @@ paths: responses: 200: description: - The claimed keys + The claimed keys. schema: type: object properties: diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index 63c74d20..3c59cf81 100644 --- a/api/server-server/user_keys.yaml +++ b/api/server-server/user_keys.yaml @@ -63,7 +63,7 @@ paths: - one_time_keys responses: 200: - description: The claimed keys + description: The claimed keys. schema: type: object properties: From 57cf1aaa96f9767444f42a32f0f7c7d21b92062e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 19:37:25 -0700 Subject: [PATCH 073/497] Add missing period --- specification/modules/send_to_device.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/send_to_device.rst b/specification/modules/send_to_device.rst index 86288546..cca0338a 100644 --- a/specification/modules/send_to_device.rst +++ b/specification/modules/send_to_device.rst @@ -108,7 +108,7 @@ to_device ToDevice Optional. Information on the send-to-device messages ========= ========= ============================================= Parameter Type Description ========= ========= ============================================= -events [Event] List of send-to-device messages +events [Event] List of send-to-device messages. ========= ========= ============================================= ``Event`` From 20d2fdc288e3e79909db449f99895f1a2ad77764 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 19:51:11 -0700 Subject: [PATCH 074/497] Add changelog --- changelogs/client_server/newsfragments/1988.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1988.clarification diff --git a/changelogs/client_server/newsfragments/1988.clarification b/changelogs/client_server/newsfragments/1988.clarification new file mode 100644 index 00000000..b0f05203 --- /dev/null +++ b/changelogs/client_server/newsfragments/1988.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. From abd770419b6169510293e963c373625bfefd0646 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 19:52:38 -0700 Subject: [PATCH 075/497] Add changelog --- changelogs/client_server/newsfragments/1989.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1989.clarification diff --git a/changelogs/client_server/newsfragments/1989.clarification b/changelogs/client_server/newsfragments/1989.clarification new file mode 100644 index 00000000..b0f05203 --- /dev/null +++ b/changelogs/client_server/newsfragments/1989.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. From 713e4401b47ff71da6aad21ce2bd781281f48007 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 7 May 2019 19:54:38 -0700 Subject: [PATCH 076/497] Add changelogs --- changelogs/client_server/newsfragments/1991.clarification | 1 + changelogs/server_server/newsfragments/1991.clarification | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1991.clarification create mode 100644 changelogs/server_server/newsfragments/1991.clarification diff --git a/changelogs/client_server/newsfragments/1991.clarification b/changelogs/client_server/newsfragments/1991.clarification new file mode 100644 index 00000000..b0f05203 --- /dev/null +++ b/changelogs/client_server/newsfragments/1991.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. diff --git a/changelogs/server_server/newsfragments/1991.clarification b/changelogs/server_server/newsfragments/1991.clarification new file mode 100644 index 00000000..b0f05203 --- /dev/null +++ b/changelogs/server_server/newsfragments/1991.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. From 00b7b70c062e78c8bdbce060a56d099540654f9e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 7 May 2019 23:09:39 -0600 Subject: [PATCH 077/497] Create 1992.clarification --- changelogs/client_server/newsfragments/1992.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1992.clarification diff --git a/changelogs/client_server/newsfragments/1992.clarification b/changelogs/client_server/newsfragments/1992.clarification new file mode 100644 index 00000000..b0f05203 --- /dev/null +++ b/changelogs/client_server/newsfragments/1992.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. From 383e02835e5c9e60d0f574e69cf7cd6fa2cae262 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 May 2019 18:07:58 +0100 Subject: [PATCH 078/497] Words on using m.login.dummy for disambiguation Add some text on how m.login.dummy can be used to distinguish a flow that would otherwise be a subset of other flows. --- specification/client_server_api.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index f9f815f7..b2ff3dbd 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -789,7 +789,14 @@ Dummy Auth :Description: Dummy authentication always succeeds and requires no extra parameters. Its purpose is to allow servers to not require any form of User-Interactive - Authentication to perform a request. + Authentication to perform a request. It can also be used to differentiate + flows where otherwise one flow would be a subset of another flow. eg. if + a server offers flows ``m.login.recaptcha`` and ``m.login.recaptcha, + m.login.email.identity`` and the client completes the recaptcha stage first, + the auth would succeed with the former flow, even if the client was intending + to then complete the email auth stage. A server can instead send flows + ``m.login.recaptcha, m.login.dummy`` and ``m.login.recaptcha, + m.login.email.identity`` to fix the ambiguity. To use this authentication type, clients should submit an auth dict with just the type and session, if provided: From c38581fb868c0d198297d82932d2b8117264bad3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 May 2019 19:20:01 +0100 Subject: [PATCH 079/497] Too many spaces Co-Authored-By: Travis Ralston --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index b2ff3dbd..6f65ebb1 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -790,7 +790,7 @@ Dummy Auth Dummy authentication always succeeds and requires no extra parameters. Its purpose is to allow servers to not require any form of User-Interactive Authentication to perform a request. It can also be used to differentiate - flows where otherwise one flow would be a subset of another flow. eg. if + flows where otherwise one flow would be a subset of another flow. eg. if a server offers flows ``m.login.recaptcha`` and ``m.login.recaptcha, m.login.email.identity`` and the client completes the recaptcha stage first, the auth would succeed with the former flow, even if the client was intending From 37871106c6fc6013c17b5711fb93853fff140267 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 21 May 2019 16:21:47 +0100 Subject: [PATCH 080/497] MSC2002: Proposal for adopting MSC1884 as v4 rooms (#2002) --- proposals/2002-rooms-v4.md | 54 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 proposals/2002-rooms-v4.md diff --git a/proposals/2002-rooms-v4.md b/proposals/2002-rooms-v4.md new file mode 100644 index 00000000..defacee1 --- /dev/null +++ b/proposals/2002-rooms-v4.md @@ -0,0 +1,54 @@ +# MSC 2002 - Rooms V4 + +This MSC proposes creating a new room version named v4 to allow servers to switch +event ID grammar to that proposed in MSC1884. + +## Proposal + +The new room version is called "4". The only difference between v4 and v3 is +that v4 rooms use the grammar for defining event IDs as proposed in MSC1884 - +expressing event IDs as url-safe base64 rather than plain base64 for the +convenience of client implementors. + +It is not proposed that servers change the default room version used when +creating new rooms, and it is not proposed that servers recommend upgrading +existing rooms to v4. + +## Rationale and Context + +We would like to default to creating rooms with a reasonably secure room +algorithm in upcoming Matrix 1.0. We do not want to default to creating v3 +rooms due to the inconvenience the v3 event ID grammar might cause, so instead +we are proposing favouring v4. + +Ideally we would also include other room algorithm changes in v4 (e.g. +honouring server signing key validity periods, as per +https://github.com/matrix-org/synapse/issues/4364), but as spec & +implementation work is still ongoing there, we are proposing using v4 as a +room version which can be supported in the wild before Matrix 1.0 and then +used as the initial default for creating rooms. The expectation is for the +versions of the spec which coincide with 1.0 to also support v5 rooms, but in +practice v5 will not be marked as default until it has sufficient adoption on +the public network. + +The expectation is never to recommend upgrading existing +rooms to v4, but instead v5 (once ready), to avoid overburdening room admins +with upgrade notifications. + +To conclude, the proposed plan is: + 1. Define room v4 as MSC1884 + 2. Introduce servers with v4 support into the public network as rapidly as possible + 3. Wait for enough servers to speak v4. Meanwhile: + 1. Define an MSC for honouring server signing key validity periods + 2. Implement this MSC + 3. Define room v5 as this MSC + 4. Release Matrix 1.0, defining room v4 as the new default for creating rooms, + but also shipping support for room v5 for the first time. + 5. Wait for enough servers to speak v5 rooms. + 6. Define room v5 as the new default for creating rooms. + 7. Define room versions prior to v5 as unsafe, thus prompting users to upgrade their + rooms to v5. + +The reason we don't wait for v5 to be widespread before releasing 1.0 is to avoid +delaying the 1.0 yet further. It is good enough for 1.0 to support v5 without it +also being the default for creating rooms. From 70d3fd809ea0c57fb16281e7330e49f5b657f44b Mon Sep 17 00:00:00 2001 From: Sorunome Date: Wed, 22 May 2019 14:46:31 +0200 Subject: [PATCH 081/497] add spoiler msc --- proposals/2010-spoilers.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 proposals/2010-spoilers.md diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md new file mode 100644 index 00000000..bec895b7 --- /dev/null +++ b/proposals/2010-spoilers.md @@ -0,0 +1,25 @@ +# MSC 2010: Proposal to add client-side spoilers +Sometimes you are talking about e.g. a new movie and want to discuss the plot without spoiling others. Or you are talking in e.g. some mental health community where, due to triggers, some content shouldn't be immediately visible to everybody. For this the content is hidden and then revealed once interacted somehow (e.g. a click / hover). + +## Proposal +This proposal adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. + +For example: +`Hello there, the movie was awesome` for a spoiler without reason and `Hey the movie was awesome` for a spoiler with the reason "movie". + +The plain-text fallback could be rendered as `(Spoiler: )` and `(Spoiler for : )` respectively. + +For example: +`Hi there` would have as fallback `Hi (Spoiler: there)` +`Hi there` would have as fallback `Hi (Spoiler for greeting: there)` + +## Tradeoffs +Instead of making this an attribute, an entirely new tag could be introduced (e.g. ``), however that wouldn't be HTML-compliant. + +Instead of limiting the proposed `data-mx-spoiler` attribute only to the ``-tag it could be added to all tags, however it might make implementations for clients more complicated. + +## Potential issues +Depending on context it might make sense to put other events, such as `m.image`, into spoilers, too. This MSC doesn't address that at all. Using `` seems rather sub-optimal for that. + +## Security considerations +The spoiler reason needs to be properly escaped when rendered. From d750115fdc30ce29ed7281c24bbfff65fff0af95 Mon Sep 17 00:00:00 2001 From: Sorunome Date: Wed, 22 May 2019 15:20:30 +0200 Subject: [PATCH 082/497] fix up some things --- proposals/2010-spoilers.md | 39 ++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index bec895b7..d47b058f 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -1,25 +1,48 @@ # MSC 2010: Proposal to add client-side spoilers -Sometimes you are talking about e.g. a new movie and want to discuss the plot without spoiling others. Or you are talking in e.g. some mental health community where, due to triggers, some content shouldn't be immediately visible to everybody. For this the content is hidden and then revealed once interacted somehow (e.g. a click / hover). +Sometimes, while you want to put text into a spoiler to not have people accidentally read things that they don't want to see. +For example, when discussing a new movie or a TV series, not everyone might have watched it yet. In such cases it would make sense to add a spoiler so that only those who have seen the movie or don't mind spoilers read the content. +Another example would be e.g. in mental health communities where certain people have certain triggers. People could put talking about abuse or thelike into a spoiler, to not accidentally trigger anyone just reading along the conversation. +Furthermore this is helpful for bridging to other networks that already have a spoiler feature. + +To render the spoiler the content is hidden and then revealed once interacted somehow (e.g. a click / hover). ## Proposal -This proposal adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. - -For example: -`Hello there, the movie was awesome` for a spoiler without reason and `Hey the movie was awesome` for a spoiler with the reason "movie". +This proposal is about adding a new attribute to the `formatted_body` of messages with type `m.room.message` and msgtype `m.text`. +It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. The plain-text fallback could be rendered as `(Spoiler: )` and `(Spoiler for : )` respectively. -For example: -`Hi there` would have as fallback `Hi (Spoiler: there)` -`Hi there` would have as fallback `Hi (Spoiler for greeting: there)` +### Example +Without reason: +``` +{ + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "body": "Hello there, the movie was (Spoiler: awesome)", + "formatted_body": "Hello there, the movie was awesome" +} +``` +With reason: +``` +{ + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "body": "Hey (Spoiler for movie: the movie was awesome)", + "formatted_body": "Hey the movie was awesome" +} +``` ## Tradeoffs Instead of making this an attribute, an entirely new tag could be introduced (e.g. ``), however that wouldn't be HTML-compliant. Instead of limiting the proposed `data-mx-spoiler` attribute only to the ``-tag it could be added to all tags, however it might make implementations for clients more complicated. +Clients would have to come up with a way how to input spoilers. This could be done, for example, by adding a custom markdown tag (like discord does), so that you do `Text ||spoiler||`, however that doesn't take a spoiler reason into account. + ## Potential issues Depending on context it might make sense to put other events, such as `m.image`, into spoilers, too. This MSC doesn't address that at all. Using `` seems rather sub-optimal for that. +This MSC doesn't take HTML block elements into account. + ## Security considerations The spoiler reason needs to be properly escaped when rendered. From ebb1351a9f27bb335cebf6e2cd92deedcd0dabaf Mon Sep 17 00:00:00 2001 From: Sorunome Date: Wed, 22 May 2019 15:22:22 +0200 Subject: [PATCH 083/497] linebreak consistency --- proposals/2010-spoilers.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index d47b058f..739bfe2e 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -1,5 +1,6 @@ # MSC 2010: Proposal to add client-side spoilers -Sometimes, while you want to put text into a spoiler to not have people accidentally read things that they don't want to see. +Sometimes, while you want to put text into a spoiler to not have people accidentally read things that they don't want to see. + For example, when discussing a new movie or a TV series, not everyone might have watched it yet. In such cases it would make sense to add a spoiler so that only those who have seen the movie or don't mind spoilers read the content. Another example would be e.g. in mental health communities where certain people have certain triggers. People could put talking about abuse or thelike into a spoiler, to not accidentally trigger anyone just reading along the conversation. Furthermore this is helpful for bridging to other networks that already have a spoiler feature. @@ -7,7 +8,8 @@ Furthermore this is helpful for bridging to other networks that already have a s To render the spoiler the content is hidden and then revealed once interacted somehow (e.g. a click / hover). ## Proposal -This proposal is about adding a new attribute to the `formatted_body` of messages with type `m.room.message` and msgtype `m.text`. +This proposal is about adding a new attribute to the `formatted_body` of messages with type `m.room.message` and msgtype `m.text`. + It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. The plain-text fallback could be rendered as `(Spoiler: )` and `(Spoiler for : )` respectively. From 6f3bcb56d34364de1cc6d1c7dc1ad8ca281ef806 Mon Sep 17 00:00:00 2001 From: Sorunome Date: Wed, 22 May 2019 15:35:32 +0200 Subject: [PATCH 084/497] add rendering idea --- proposals/2010-spoilers.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index 739bfe2e..d4128de4 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -10,7 +10,9 @@ To render the spoiler the content is hidden and then revealed once interacted so ## Proposal This proposal is about adding a new attribute to the `formatted_body` of messages with type `m.room.message` and msgtype `m.text`. -It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. +It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. It could be rendered, for example, similar to this: + +![Spoiler rendering idea](https://user-images.githubusercontent.com/2433620/58178745-082c1480-7ca7-11e9-901b-13b147cfd157.png) The plain-text fallback could be rendered as `(Spoiler: )` and `(Spoiler for : )` respectively. From 273af2a2e0eb3351ad58bf39c1e2472a3c96881d Mon Sep 17 00:00:00 2001 From: Sorunome Date: Wed, 22 May 2019 17:30:18 +0200 Subject: [PATCH 085/497] wrap long lines --- proposals/2010-spoilers.md | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index d4128de4..366f4a3e 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -1,20 +1,29 @@ # MSC 2010: Proposal to add client-side spoilers Sometimes, while you want to put text into a spoiler to not have people accidentally read things that they don't want to see. -For example, when discussing a new movie or a TV series, not everyone might have watched it yet. In such cases it would make sense to add a spoiler so that only those who have seen the movie or don't mind spoilers read the content. -Another example would be e.g. in mental health communities where certain people have certain triggers. People could put talking about abuse or thelike into a spoiler, to not accidentally trigger anyone just reading along the conversation. +For example, when discussing a new movie or a TV series, not everyone might have watched it yet. +In such cases it would make sense to add a spoiler so that only those who have seen the movie or +don't mind spoilers read the content. +Another example would be e.g. in mental health communities where certain people have certain +triggers. People could put talking about abuse or thelike into a spoiler, to not accidentally +trigger anyone just reading along the conversation. Furthermore this is helpful for bridging to other networks that already have a spoiler feature. -To render the spoiler the content is hidden and then revealed once interacted somehow (e.g. a click / hover). +To render the spoiler the content is hidden and then revealed once interacted somehow +(e.g. a click / hover). ## Proposal -This proposal is about adding a new attribute to the `formatted_body` of messages with type `m.room.message` and msgtype `m.text`. +This proposal is about adding a new attribute to the `formatted_body` of messages with type +`m.room.message` and msgtype `m.text`. -It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. It could be rendered, for example, similar to this: +It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribute is present the +contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for +the spoiler by setting the attribute string. It could be rendered, for example, similar to this: ![Spoiler rendering idea](https://user-images.githubusercontent.com/2433620/58178745-082c1480-7ca7-11e9-901b-13b147cfd157.png) -The plain-text fallback could be rendered as `(Spoiler: )` and `(Spoiler for : )` respectively. +The plain-text fallback could be rendered as `(Spoiler: )` and +`(Spoiler for : )` respectively. ### Example Without reason: @@ -37,14 +46,20 @@ With reason: ``` ## Tradeoffs -Instead of making this an attribute, an entirely new tag could be introduced (e.g. ``), however that wouldn't be HTML-compliant. +Instead of making this an attribute, an entirely new tag could be introduced (e.g. ``), +however that wouldn't be HTML-compliant. -Instead of limiting the proposed `data-mx-spoiler` attribute only to the ``-tag it could be added to all tags, however it might make implementations for clients more complicated. +Instead of limiting the proposed `data-mx-spoiler` attribute only to the ``-tag it could be +added to all tags, however it might make implementations for clients more complicated. -Clients would have to come up with a way how to input spoilers. This could be done, for example, by adding a custom markdown tag (like discord does), so that you do `Text ||spoiler||`, however that doesn't take a spoiler reason into account. +Clients would have to come up with a way how to input spoilers. This could be done, for example, +by adding a custom markdown tag (like discord does), so that you do `Text ||spoiler||`, however +that doesn't take a spoiler reason into account. ## Potential issues -Depending on context it might make sense to put other events, such as `m.image`, into spoilers, too. This MSC doesn't address that at all. Using `` seems rather sub-optimal for that. +Depending on context it might make sense to put other events, such as `m.image`, into spoilers, +too. This MSC doesn't address that at all. Using +`` seems rather sub-optimal for that. This MSC doesn't take HTML block elements into account. From 77050062601cad901623660de151081608fb5ca3 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 22 May 2019 12:43:43 -0400 Subject: [PATCH 086/497] 1 hour seems to be fine --- proposals/1719-olm_unwedging.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index e696c1e2..50b6f0e6 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -16,8 +16,7 @@ empty contents. In order to avoid creating too many extra sessions, a client should rate-limit the number of new sessions it creates per device that it receives a message from; the client should not create a new session with another device if it has -already created one for that given device in the past 1 hour. (TODO: is 1 hour -the right amount of time?) +already created one for that given device in the past 1 hour. Clients may wish to ask the sender of the undecryptable messages to re-send the message. For exampe, if the undecryptable message was a megolm session, then From d39baba21b64c0dfe3b57e2bbbe8b9609fb69f2d Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 22 May 2019 12:44:04 -0400 Subject: [PATCH 087/497] add a security note --- proposals/1719-olm_unwedging.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index 50b6f0e6..3e0ce35d 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -45,6 +45,10 @@ time of the session. The spec will be changed to read: ## Security considerations +An attacker could use this to create a new session on a device that they are +able to read. However, this would require the attacker to have compromised the +device's keys. + ## Conclusion This proposal outlines how wedged olm sessions can be replaced by a new From dd74baa5d0fb6c2f15878a929c1a70e2edf69e62 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 22 May 2019 12:54:01 -0400 Subject: [PATCH 088/497] clarify wording --- proposals/1719-olm_unwedging.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index 3e0ce35d..67bd6010 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -36,8 +36,7 @@ time of the session. The spec will be changed to read: > If a client has multiple sessions established with another device, it should > use the session from which it last received and successfully decrypted a > message. For these purposes, a session that has not received any messages -> should consider its creation time to be the time that it last received a -> message. +> should use its creation time as the time that it last received a message. ## Tradeoffs From ac08c8461240e2fc9f88bc59c34263d8add4115f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 23 May 2019 14:39:46 -0400 Subject: [PATCH 089/497] remove duplicate consideration Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/1719-olm_unwedging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index 67bd6010..c181e3f7 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -29,7 +29,7 @@ another device, it should use the session from which it last received a message." (the last paragraph of the [`m.olm.v1.curve25519-aes-sha2` section](https://matrix.org/docs/spec/client_server/r0.4.0.html#m-olm-v1-curve25519-aes-sha2)). When comparing the time of the last received message for each session, the -client should consider only consider messages that were successfully decrypted, +client should only consider messages that were successfully decrypted, and for sessions that have never received a message, it should use the creation time of the session. The spec will be changed to read: From 9c2a789d34da6a465ace23875d9d9e89ff7ced48 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 23 May 2019 22:13:57 -0600 Subject: [PATCH 090/497] Add missing changelogs and make existing ones match conventions The conventions are not set in stone, however the changelog should not be a mixed bag of voices. --- changelogs/application_service/newsfragments/1650.clarification | 1 + changelogs/client_server/newsfragments/1650.clarification | 1 + changelogs/client_server/newsfragments/1656.clarification | 1 + changelogs/client_server/newsfragments/1701.feature | 2 +- changelogs/client_server/newsfragments/1744.clarification | 2 +- changelogs/client_server/newsfragments/1889.clarification | 2 +- changelogs/client_server/newsfragments/1891.clarification | 1 + changelogs/client_server/newsfragments/1969.clarification | 1 + changelogs/client_server/newsfragments/1975.clarification | 2 +- changelogs/client_server/newsfragments/1999.clarification | 1 + changelogs/identity_service/newsfragments/1967.clarification | 1 + changelogs/server_server/newsfragments/1650.clarification | 1 + 12 files changed, 12 insertions(+), 4 deletions(-) create mode 100644 changelogs/application_service/newsfragments/1650.clarification create mode 100644 changelogs/client_server/newsfragments/1650.clarification create mode 100644 changelogs/client_server/newsfragments/1656.clarification create mode 100644 changelogs/client_server/newsfragments/1891.clarification create mode 100644 changelogs/client_server/newsfragments/1969.clarification create mode 100644 changelogs/client_server/newsfragments/1999.clarification create mode 100644 changelogs/identity_service/newsfragments/1967.clarification create mode 100644 changelogs/server_server/newsfragments/1650.clarification diff --git a/changelogs/application_service/newsfragments/1650.clarification b/changelogs/application_service/newsfragments/1650.clarification new file mode 100644 index 00000000..617b7ab6 --- /dev/null +++ b/changelogs/application_service/newsfragments/1650.clarification @@ -0,0 +1 @@ +Change examples to use example.org instead of a real domain. diff --git a/changelogs/client_server/newsfragments/1650.clarification b/changelogs/client_server/newsfragments/1650.clarification new file mode 100644 index 00000000..617b7ab6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1650.clarification @@ -0,0 +1 @@ +Change examples to use example.org instead of a real domain. diff --git a/changelogs/client_server/newsfragments/1656.clarification b/changelogs/client_server/newsfragments/1656.clarification new file mode 100644 index 00000000..0c8f4ad0 --- /dev/null +++ b/changelogs/client_server/newsfragments/1656.clarification @@ -0,0 +1 @@ +Clarify that ``state_default`` in ``m.room.power_levels`` always defaults to 50. diff --git a/changelogs/client_server/newsfragments/1701.feature b/changelogs/client_server/newsfragments/1701.feature index 39c22dd7..cf6084ae 100644 --- a/changelogs/client_server/newsfragments/1701.feature +++ b/changelogs/client_server/newsfragments/1701.feature @@ -1 +1 @@ -Documented megolm session export format. \ No newline at end of file +Add megolm session export format. diff --git a/changelogs/client_server/newsfragments/1744.clarification b/changelogs/client_server/newsfragments/1744.clarification index dc103920..dfe838f1 100644 --- a/changelogs/client_server/newsfragments/1744.clarification +++ b/changelogs/client_server/newsfragments/1744.clarification @@ -1 +1 @@ -Add missing status_msg to m.presence schema. +Add missing ``status_msg`` to ``m.presence`` schema. diff --git a/changelogs/client_server/newsfragments/1889.clarification b/changelogs/client_server/newsfragments/1889.clarification index 5026dab3..2737a7ee 100644 --- a/changelogs/client_server/newsfragments/1889.clarification +++ b/changelogs/client_server/newsfragments/1889.clarification @@ -1 +1 @@ -Add the missing `m.push_rules` event schema. +Add the missing ``m.push_rules`` event schema. diff --git a/changelogs/client_server/newsfragments/1891.clarification b/changelogs/client_server/newsfragments/1891.clarification new file mode 100644 index 00000000..ef4edfb4 --- /dev/null +++ b/changelogs/client_server/newsfragments/1891.clarification @@ -0,0 +1 @@ +Clarify how modern day local echo is meant to be solved by clients. diff --git a/changelogs/client_server/newsfragments/1969.clarification b/changelogs/client_server/newsfragments/1969.clarification new file mode 100644 index 00000000..b0f05203 --- /dev/null +++ b/changelogs/client_server/newsfragments/1969.clarification @@ -0,0 +1 @@ +Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1975.clarification b/changelogs/client_server/newsfragments/1975.clarification index 03a9b754..ac118bfd 100644 --- a/changelogs/client_server/newsfragments/1975.clarification +++ b/changelogs/client_server/newsfragments/1975.clarification @@ -1 +1 @@ -Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``. It is somewhat meaningless to request a thumbnail without specifying a desired size, and Synapse has never permitted such requests. \ No newline at end of file +Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``. diff --git a/changelogs/client_server/newsfragments/1999.clarification b/changelogs/client_server/newsfragments/1999.clarification new file mode 100644 index 00000000..748c55f2 --- /dev/null +++ b/changelogs/client_server/newsfragments/1999.clarification @@ -0,0 +1 @@ +Clarify how ``m.login.dummy`` can be used to disambiguate login flows. diff --git a/changelogs/identity_service/newsfragments/1967.clarification b/changelogs/identity_service/newsfragments/1967.clarification new file mode 100644 index 00000000..b080caeb --- /dev/null +++ b/changelogs/identity_service/newsfragments/1967.clarification @@ -0,0 +1 @@ +Fix route for ``/3pid/bind``. diff --git a/changelogs/server_server/newsfragments/1650.clarification b/changelogs/server_server/newsfragments/1650.clarification new file mode 100644 index 00000000..617b7ab6 --- /dev/null +++ b/changelogs/server_server/newsfragments/1650.clarification @@ -0,0 +1 @@ +Change examples to use example.org instead of a real domain. From 3c38956510511d97dc770c0ec0be4d681b382af0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 May 2019 11:57:22 -0600 Subject: [PATCH 091/497] Remove prev_content from the redaction essential keys list As per [MSC1954](https://github.com/matrix-org/matrix-doc/pull/1954) No known changes since the proposal was accepted. --- changelogs/client_server/newsfragments/2016.clarification | 1 + specification/client_server_api.rst | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2016.clarification diff --git a/changelogs/client_server/newsfragments/2016.clarification b/changelogs/client_server/newsfragments/2016.clarification new file mode 100644 index 00000000..77ea0d4c --- /dev/null +++ b/changelogs/client_server/newsfragments/2016.clarification @@ -0,0 +1 @@ +Remove ``prev_content`` from the redaction algorithm's essential keys list. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6f65ebb1..604c2b1c 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1500,7 +1500,6 @@ the following list: - ``room_id`` - ``sender`` - ``state_key`` -- ``prev_content`` - ``content`` - ``hashes`` - ``signatures`` From 3b0e194ff7a5a4b6e20bbf1572337738904feda5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 May 2019 15:50:05 -0600 Subject: [PATCH 092/497] Add version 4 rooms to the spec As per [MSC1884](https://github.com/matrix-org/matrix-doc/pull/1884) and [MSC2002](https://github.com/matrix-org/matrix-doc/pull/2002). No known changes since the proposals were accepted. Due to being in the area: This fixes https://github.com/matrix-org/matrix-doc/issues/1863 --- api/server-server/definitions/pdu_v3.yaml | 4 ++ api/server-server/definitions/pdu_v4.yaml | 47 ++++++++++++++ api/server-server/examples/pdu_v3.json | 3 +- api/server-server/examples/pdu_v4.json | 12 ++++ specification/index.rst | 1 + specification/rooms/v4.rst | 76 +++++++++++++++++++++++ specification/targets.yaml | 4 ++ 7 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 api/server-server/definitions/pdu_v4.yaml create mode 100644 api/server-server/examples/pdu_v4.json create mode 100644 specification/rooms/v4.rst diff --git a/api/server-server/definitions/pdu_v3.yaml b/api/server-server/definitions/pdu_v3.yaml index 8d41fbda..38105098 100644 --- a/api/server-server/definitions/pdu_v3.yaml +++ b/api/server-server/definitions/pdu_v3.yaml @@ -20,6 +20,10 @@ allOf: - $ref: "unsigned_pdu_base.yaml" - type: object properties: + redacts: + type: string + description: For redaction events, the ID of the event being redacted. + example: "$def/456+oldevent" auth_events: type: array items: diff --git a/api/server-server/definitions/pdu_v4.yaml b/api/server-server/definitions/pdu_v4.yaml new file mode 100644 index 00000000..55b1c26f --- /dev/null +++ b/api/server-server/definitions/pdu_v4.yaml @@ -0,0 +1,47 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Persistent Data Unit +description: A persistent data unit (event) for room version 3 and beyond. +example: + $ref: "../examples/pdu_v4.json" +allOf: + - $ref: "pdu_v3.yaml" + - type: object + properties: + redacts: + type: string + description: For redaction events, the ID of the event being redacted. + example: "$def_456-oldevent" + auth_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the authorization events that would + allow this event to be in the room. + example: ["$URLsafe-base64EncodedHash", "$Another_Event"] + prev_events: + type: array + items: + type: string + description: Event ID. + description: |- + Event IDs for the most recent events in the room + that the homeserver was aware of when it made this event. + example: ["$URLsafe-base64EncodedHash", "$Another_Event"] + required: + - auth_events + - prev_events diff --git a/api/server-server/examples/pdu_v3.json b/api/server-server/examples/pdu_v3.json index 6a454b4e..acffdf26 100644 --- a/api/server-server/examples/pdu_v3.json +++ b/api/server-server/examples/pdu_v3.json @@ -15,5 +15,6 @@ "prev_events": [ "$base64encodedeventid", "$adifferenteventid" - ] + ], + "redacts": "$some/old+event" } diff --git a/api/server-server/examples/pdu_v4.json b/api/server-server/examples/pdu_v4.json new file mode 100644 index 00000000..3c2f0e22 --- /dev/null +++ b/api/server-server/examples/pdu_v4.json @@ -0,0 +1,12 @@ +{ + "$ref": "pdu_v3.json", + "auth_events": [ + "$urlsafe_base64_encoded_eventid", + "$a-different-event-id" + ], + "prev_events": [ + "$urlsafe_base64_encoded_eventid", + "$a-different-event-id" + ], + "redacts": "$some-old_event" +} diff --git a/specification/index.rst b/specification/index.rst index 19c5ad22..33dff5a3 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -493,6 +493,7 @@ The available room versions are: * `Version 1 `_ - **Stable**. The current version of most rooms. * `Version 2 `_ - **Stable**. Implements State Resolution Version 2. * `Version 3 `_ - **Stable**. Introduces events whose IDs are the event's hash. +* `Version 4 `_ - **Stable**. Builds on v3 by using URL-safe base64 for event IDs. Specification Versions ---------------------- diff --git a/specification/rooms/v4.rst b/specification/rooms/v4.rst new file mode 100644 index 00000000..8d2cc59b --- /dev/null +++ b/specification/rooms/v4.rst @@ -0,0 +1,76 @@ +.. Copyright 2019 The Matrix.org Foundation C.I.C. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Room Version 4 +============== + +This room version builds on `version 3 `_ using a different encoding for +event IDs. + +.. contents:: Table of Contents +.. sectnum:: + + +Client considerations +--------------------- + +This room version changes the format form event IDs sent to clients. Clients should +already be treating event IDs as opaque identifiers, and should not be concerned with +the format of them. Clients should still encode the event ID when including it in a +request path. + +Clients should expect to see event IDs changed from the format of ``$randomstring:example.org`` +to something like ``$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`` (note the lack of domain). + + +Server implementation components +-------------------------------- + +.. WARNING:: + The information contained in this section is strictly for server implementors. + Applications which use the Client-Server API are generally unaffected by the + intricacies contained here. The section above regarding client considerations + is the resource that Client-Server API use cases should reference. + + +Room version 4 uses the same algorithms defined in `room version 3 `_, however +using URL-safe base64 to generate the event ID. + +Event IDs +~~~~~~~~~ + +.. admonition:: Rationale + + Room version 3 generated event IDs that were difficult for client implementations + which were not encoding the event ID to function in those rooms. It additionally + raised concern due to the ``/`` character being interpretted differently by some + reverse proxy software, and generally made administration harder. + +The event ID is the `reference hash`_ of the event encoded using a variation of +`Unpadded Base64`_ which replaces the 62nd and 63rd characters with ``-`` and ``_`` +instead of using ``+`` and ``/``. This matches `RFC4648's definition of URL-safe base64 +`_. Event IDs are still prefixed +with ``$`` and may result in looking like ``$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg``. + +Just like in room version 3, event IDs should not be sent over federation to servers +when the room uses this room version. On the receiving end of an event, the server +should compute the relevant event ID for itself. Room version 3 also changes the format +of ``auth_events`` and ``prev_events`` in a PDU. + +{{definition_ss_pdu_v4}} + +.. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`Canonical JSON`: ../appendices.html#canonical-json +.. _`Signing Events`: ../server_server/r0.1.1.html#signing-events +.. _`reference hash`: ../server_server/r0.1.1.html#reference-hashes diff --git a/specification/targets.yaml b/specification/targets.yaml index 830449ae..be4a063a 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -38,6 +38,10 @@ targets: files: - rooms/v3.rst version_label: v3 + rooms@v4: # this is translated to be rooms/v4.html + files: + - rooms/v4.rst + version_label: v4 appendices: files: - appendices.rst From ceaccffdf7244e79aa91e3916811f93881be9bca Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 24 May 2019 17:14:23 -0600 Subject: [PATCH 093/497] Add a .m.rule.tombstone default push rule for room upgrades As per [MSC1930](https://github.com/matrix-org/matrix-doc/pull/1930) There are no known changes to this proposal since it was accepted. --- .../client_server/newsfragments/2020.feature | 1 + specification/modules/push.rst | 35 +++++++++++++++++-- 2 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2020.feature diff --git a/changelogs/client_server/newsfragments/2020.feature b/changelogs/client_server/newsfragments/2020.feature new file mode 100644 index 00000000..0d7c7eb8 --- /dev/null +++ b/changelogs/client_server/newsfragments/2020.feature @@ -0,0 +1 @@ +Add a ``.m.rule.tombstone`` default push rule for room ugprade notifications. diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 9830729a..1bac0c2e 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -177,7 +177,7 @@ notification is delivered for a matching event. The following actions are define This prevents each matching event from generating a notification ``coalesce`` This enables notifications for matching events but activates homeserver - specific behaviour to intelligently coalesce multiple events into a single + specific behaviour to intelligently coalesce multiple events into a single notification. Not all homeservers may support this. Those that do not support it should treat it as the ``notify`` action. ``set_tweak`` @@ -369,6 +369,37 @@ Definition: } +``.m.rule.tombstone`` +````````````````````` +Matches any event whose type is ``m.room.tombstone``. This is intended +to notify users of a room when it is upgraded, similar to what an +``@room`` notification would accomplish. + +Definition: + +.. code:: json + + { + "rule_id": ".m.rule.tombstone", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.tombstone" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": true + } + ] + } + + ``.m.rule.roomnotif`` ````````````````````` Matches any message whose content is unencrypted and contains the @@ -599,7 +630,7 @@ Definition: Conditions ++++++++++ -Override, Underride and Default Rules MAY have a list of 'conditions'. +Override, Underride and Default Rules MAY have a list of 'conditions'. All conditions must hold true for an event in order to apply the ``action`` for the event. A rule with no conditions always matches. Room, Sender, User and Content rules do not have conditions in the same way, but instead have From 2b96d73305328188f584070f550ce1591d08bbff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 15:39:35 -0600 Subject: [PATCH 094/497] Fix third party signed definitions for join APIs Fixes https://github.com/matrix-org/matrix-doc/issues/1978 --- .../definitions/third_party_signed.yaml | 41 +++++++++++ api/client-server/joining.yaml | 69 +------------------ specification/modules/third_party_invites.rst | 3 +- 3 files changed, 45 insertions(+), 68 deletions(-) create mode 100644 api/client-server/definitions/third_party_signed.yaml diff --git a/api/client-server/definitions/third_party_signed.yaml b/api/client-server/definitions/third_party_signed.yaml new file mode 100644 index 00000000..c9c761a1 --- /dev/null +++ b/api/client-server/definitions/third_party_signed.yaml @@ -0,0 +1,41 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +title: Third Party Signed +description: |- + A signature of an ``m.third_party_invite`` token to prove that this user + owns a third party identity which has been invited to the room. +properties: + sender: + type: string + description: The Matrix ID of the user who issued the invite. + example: "@alice:example.org" + mxid: + type: string + description: The Matrix ID of the invitee. + example: "@bob:example.org" + token: + type: string + description: The state key of the m.third_party_invite event. + example: "random8nonce" + signatures: + type: object + description: A signatures object containing a signature of the entire signed object. + title: Signatures + example: { + "example.org": { + "ed25519:0": "some9signature" + } + } +required: ["sender", "mxid", "token", "signatures"] diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index 1dcf769f..af38d6f9 100644 --- a/api/client-server/joining.yaml +++ b/api/client-server/joining.yaml @@ -58,38 +58,9 @@ paths: name: third_party_signed schema: type: object - example: { - "third_party_signed": { - "sender": "@cat:the.hat", - "mxid": "@green:eggs.ham", - "token": "random8nonce", - "signatures": { - "horton.hears": { - "ed25519:0": "some9signature" - } - } - } - } properties: third_party_signed: - type: object - title: ThirdPartySigned - description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room. - properties: - sender: - type: string - description: The Matrix ID of the user who issued the invite. - mxid: - type: string - description: The Matrix ID of the invitee. - token: - type: string - description: The state key of the m.third_party_invite event. - signatures: - type: object - description: A signatures object containing a signature of the entire signed object. - title: Signatures - required: ["sender", "mxid", "token", "signatures"] + $ref: "definitions/third_party_signed.yaml" responses: 200: description: |- @@ -163,45 +134,9 @@ paths: name: third_party_signed schema: type: object - example: { - "third_party_signed": { - "signed": { - "sender": "@cat:the.hat", - "mxid": "@green:eggs.ham", - "token": "random8nonce", - "signatures": { - "horton.hears": { - "ed25519:0": "some9signature" - } - } - } - } - } properties: third_party_signed: - type: object - title: ThirdPartySigned - description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room. - properties: - signed: - type: object - title: Signed - properties: - sender: - type: string - description: The Matrix ID of the user who issued the invite. - mxid: - type: string - description: The Matrix ID of the invitee. - token: - type: string - description: The state key of the m.third_party_invite event. - signatures: - type: object - description: A signatures object containing a signature of the entire signed object. - title: Signatures - required: ["sender", "mxid", "token", "signatures"] - required: ["signed"] + $ref: "definitions/third_party_signed.yaml" responses: 200: description: |- diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 3e11d929..b8ab9657 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -38,7 +38,8 @@ When the invitee's homeserver receives the notification of the binding, it should insert an ``m.room.member`` event into the room's graph for that user, with ``content.membership`` = ``invite``, as well as a ``content.third_party_invite`` property which contains proof that the invitee -does indeed own that third party identifier. +does indeed own that third party identifier. See the `m.room.member <#m-room-member>`_ +schema for more information. Events From 17a9524cad8774c9cfe12157742d0f196391de44 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 15:40:29 -0600 Subject: [PATCH 095/497] changelog --- changelogs/client_server/newsfragments/2025.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2025.clarification diff --git a/changelogs/client_server/newsfragments/2025.clarification b/changelogs/client_server/newsfragments/2025.clarification new file mode 100644 index 00000000..9e99b23d --- /dev/null +++ b/changelogs/client_server/newsfragments/2025.clarification @@ -0,0 +1 @@ +Fix the ``third_party_signed`` definitions for the join APIs. From 5eea4a477f98d79371791ab153bdaae91883f4b8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 20:42:21 -0600 Subject: [PATCH 096/497] Add server notices support As per [MSC1452](https://github.com/matrix-org/matrix-doc/issues/1452) Fixes https://github.com/matrix-org/matrix-doc/issues/1254 Although MSC1452 focuses on just the warnings part of the server notices, the base for notices has not been established in the spec. This commit adds the needed support to be able to handle notices. No intentional divergences from the proposal are included in this changeset. There are a few additions which are used in practice although not defined in the proposal, such as who is responsible for aesthetics, sending notices, and other misc rules. --- .../client_server/newsfragments/2026.feature | 1 + .../examples/m.room.message#m.server_notice | 11 +++ .../schema/m.room.message#m.server_notice | 39 ++++++++++ .../templating/matrix_templates/sections.py | 15 +++- .../matrix_templates/templates/events.tmpl | 7 ++ scripts/templating/matrix_templates/units.py | 2 + specification/client_server_api.rst | 5 +- specification/modules/server_notices.rst | 78 +++++++++++++++++++ specification/targets.yaml | 1 + 9 files changed, 154 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2026.feature create mode 100644 event-schemas/examples/m.room.message#m.server_notice create mode 100644 event-schemas/schema/m.room.message#m.server_notice create mode 100644 specification/modules/server_notices.rst diff --git a/changelogs/client_server/newsfragments/2026.feature b/changelogs/client_server/newsfragments/2026.feature new file mode 100644 index 00000000..f82b9aea --- /dev/null +++ b/changelogs/client_server/newsfragments/2026.feature @@ -0,0 +1 @@ +Add support for sending server notices to clients. diff --git a/event-schemas/examples/m.room.message#m.server_notice b/event-schemas/examples/m.room.message#m.server_notice new file mode 100644 index 00000000..0eb44ea7 --- /dev/null +++ b/event-schemas/examples/m.room.message#m.server_notice @@ -0,0 +1,11 @@ +{ + "$ref": "core/room_event.json", + "type": "m.room.message", + "content": { + "body": "Human-readable message to explain the notice", + "msgtype": "m.server_notice", + "server_notice_type": "m.server_notice.usage_limit_reached", + "admin_contact": "mailto:server.admin@example.org", + "limit_type": "monthly_active_user" + } +} diff --git a/event-schemas/schema/m.room.message#m.server_notice b/event-schemas/schema/m.room.message#m.server_notice new file mode 100644 index 00000000..f1848821 --- /dev/null +++ b/event-schemas/schema/m.room.message#m.server_notice @@ -0,0 +1,39 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: Represents a server notice for a user. +properties: + content: + properties: + body: + description: A human-readable description of the notice. + type: string + msgtype: + enum: + - m.server_notice + type: string + server_notice_type: + description: |- + The type of notice being represented. + type: string + admin_contact: + description: |- + A URI giving a contact method for the server administrator. Required if the + notice type is ``m.server_notice.usage_limit_reached``. + type: string + limit_type: + description: |- + The kind of usage limit the server has exceeded. Required if the notice type is + ``m.server_notice.usage_limit_reached``. + type: string + required: + - msgtype + - body + - server_notice_type + type: object + type: + enum: + - m.room.message + type: string +title: ServerNoticeMessage +type: object diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 5961aa24..92afa5ff 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -110,12 +110,13 @@ class MatrixSections(Sections): # Special function: Returning a dict will specify multiple sections where # the key is the section name and the value is the value of the section def render_group_events(self): - # map all event schemata to the form $EVENTTYPE_event with s/./_/g - # e.g. m_room_topic_event + # map all event schemata to the form $EVENTTYPE_event with s/.#/_/g + # e.g. m_room_topic_event or m_room_message_m_text_event schemas = self.units.get("event_schemas") renders = {} for event_type in schemas: - renders[event_type.replace(".", "_") + "_event"] = self._render_events( + underscored_event_type = event_type.replace(".", "_").replace("#", "_") + renders[underscored_event_type + "_event"] = self._render_events( lambda x: x == event_type, sorted ) return renders @@ -141,9 +142,15 @@ class MatrixSections(Sections): "m.room.message#m.notice", "m.room.message#m.image", "m.room.message#m.file" ] + excluded_types = [ + # We exclude server notices from here because we handle them in a + # dedicated module. We do not want to confuse developers this early + # in the spec. + "m.room.message#m.server_notice", + ] other_msgtypes = [ k for k in schemas.keys() if k.startswith("m.room.message#") and - k not in msgtype_order + k not in msgtype_order and k not in excluded_types ] for event_name in (msgtype_order + other_msgtypes): if not event_name.startswith("m.room.message#m."): diff --git a/scripts/templating/matrix_templates/templates/events.tmpl b/scripts/templating/matrix_templates/templates/events.tmpl index 0955cf4c..f55be73f 100644 --- a/scripts/templating/matrix_templates/templates/events.tmpl +++ b/scripts/templating/matrix_templates/templates/events.tmpl @@ -1,7 +1,14 @@ {% import 'tables.tmpl' as tables -%} +{% if (event.type_with_msgtype) %} +``{{event.type_with_msgtype}}`` +{{(4 + event.type_with_msgtype | length) * title_kind}} +{% endif -%} + +{% if (not event.type_with_msgtype) %} ``{{event.type}}`` {{(4 + event.type | length) * title_kind}} +{% endif -%} {% if (event.typeof | length) %} *{{event.typeof}}* diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index c1755119..466110f8 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -846,6 +846,7 @@ class MatrixUnits(Units): "title": None, "desc": None, "msgtype": None, + "type_with_msgtype": None, # for the template's sake "content_fields": [ # ] @@ -884,6 +885,7 @@ class MatrixUnits(Units): ) if msgtype: schema["msgtype"] = msgtype[0] # enum prop + schema["type_with_msgtype"] = schema["type"] + " (" + msgtype[0] + ")" # link to msgtypes for m.room.message if schema["type"] == "m.room.message" and not msgtype: diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 604c2b1c..a8bbfca0 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -219,9 +219,12 @@ Other error codes the client might encounter are: to modify state (eg: sending messages, account data, etc) and not routes which only read state (eg: ``/sync``, get account data, etc). +:``M_CANNOT_LEAVE_SERVER_NOTICE_ROOM``: + The user is unable to reject an invite to join the server notices room. See the + `Server Notices <#server-notices>`_ module for more information. + .. TODO: More error codes (covered by other issues) .. * M_CONSENT_NOT_GIVEN - GDPR: https://github.com/matrix-org/matrix-doc/issues/1512 -.. * M_CANNOT_LEAVE_SERVER_NOTICE_ROOM - GDPR: https://github.com/matrix-org/matrix-doc/issues/1254 .. _sect:txn_ids: diff --git a/specification/modules/server_notices.rst b/specification/modules/server_notices.rst new file mode 100644 index 00000000..63b7bfc5 --- /dev/null +++ b/specification/modules/server_notices.rst @@ -0,0 +1,78 @@ +.. Copyright 2019 The Matrix.org Foundation C.I.C. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Server Notices +============== + +.. _module:server-notices: + +Homeserver hosts often want to send messages to users in an official capacity, +or have resource limits which affect a user's ability to use the homeserver. +For example, the homeserver may be limited to a certain number of active users +per month and has exceeded that limit. To communicate this failure to users, +the homeserver would use the Server Notices room. + +The aesthetics of the room (name, topic, avatar, etc) are left as an implementation +detail. It is recommended that the homeserver decorate the room such that it looks +like an official room to users. + +Events +------ +Notices are sent to the client as normal ``m.room.message`` events with a +``msgtype`` of ``m.server_notice`` in the server notices room. Events with +a ``m.server_notice`` ``msgtype`` outside of the server notice room must +be ignored by clients. + +The specified values for ``server_notice_type`` are: + +:``m.server_notice.usage_limit_reached``: + The server has exceeded some limit which requires the server administrator + to intervene. The ``limit_type`` describes the kind of limit reached. + The specified values for ``limit_type`` are: + + :``monthly_active_user``: + The server's number of active users in the last 30 days has exceeded the + maximum. New connections are being refused by the server. What defines + "active" is left as an implementation detail, however servers are encouraged + to treat syncing users as "active". + + +{{m_room_message_m_server_notice_event}} + +Client behaviour +---------------- +Clients can identify the server notices room by the ``m.server_notice`` tag +on the room. Active notices are represented by the `pinned events <#m-room-pinned-events>`_ +in the server notices room. Server notice events pinned in that room should +be shown to the user through special UI and not through the normal pinned +events interface in the client. For example, clients may show warning banners +or bring up dialogs to get the user's attention. Events which are not server +notice events and are pinned in the server notices room should be shown just +like any other pinned event in a room. + +The client must not expect to be able to reject an invite to join the server +notices room. Attempting to reject the invite must result in a +``M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`` error. Servers should not prevent the user +leaving the room after joining the server notices room, however the same error +code must be used if the server will prevent leaving the room. + +Server behaviour +---------------- +Servers should manage exactly 1 server notices room per user. Servers must +identify this room to clients with the ``m.server_notice`` tag. Servers should +invite the target user rather than automatically join them to the server notice +room. + +How servers send notices to clients, and which user they use to send the events, +is left as an implementation detail for the server. diff --git a/specification/targets.yaml b/specification/targets.yaml index 830449ae..aa53e9c3 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -83,6 +83,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/server_acls.rst - modules/mentions.rst - modules/room_upgrades.rst + - modules/server_notices.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"] From 1d33adf62d8d56d1bfb88a0ff13da7e00fb0cc60 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 21:20:04 -0600 Subject: [PATCH 097/497] Add rationale for UIA on change password, and how access tokens behave Fixes https://github.com/matrix-org/matrix-doc/issues/680 --- api/client-server/registration.yaml | 8 ++++++-- changelogs/client_server/newsfragments/2027.clarification | 1 + 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2027.clarification diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index e2d35d2c..3195ab41 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -326,13 +326,17 @@ paths: description: |- Changes the password for an account on this homeserver. - This API endpoint uses the `User-Interactive Authentication API`_. + This API endpoint uses the `User-Interactive Authentication API`_ to + ensure the user changing the password is actually the owner of the + account. An access token should be submitted to this endpoint if the client has an active session. The homeserver may change the flows available depending on whether a - valid access token is provided. + valid access token is provided. The homeserver SHOULD NOT revoke the + access token provided in the request, however all other access tokens + for the user should be revoked if the request succeeds. security: - accessToken: [] operationId: changePassword diff --git a/changelogs/client_server/newsfragments/2027.clarification b/changelogs/client_server/newsfragments/2027.clarification new file mode 100644 index 00000000..db74ea56 --- /dev/null +++ b/changelogs/client_server/newsfragments/2027.clarification @@ -0,0 +1 @@ +Clarify why User Interactive Auth is used on password changes and how access tokens are handled. From 221d9f24fd5699c78072feeab335c9a389a4de41 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 21:30:55 -0600 Subject: [PATCH 098/497] Clarify that logging out deletes devices too Fixes https://github.com/matrix-org/matrix-doc/issues/1651 --- api/client-server/logout.yaml | 5 +++-- changelogs/client_server/newsfragments/2028.clarification | 1 + 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2028.clarification diff --git a/api/client-server/logout.yaml b/api/client-server/logout.yaml index 2dfd6d97..8451f739 100644 --- a/api/client-server/logout.yaml +++ b/api/client-server/logout.yaml @@ -32,7 +32,7 @@ paths: summary: Invalidates a user access token description: |- Invalidates an existing access token, so that it can no longer be used for - authorization. + authorization. The device associated with the access token is also deleted. operationId: logout security: - accessToken: [] @@ -49,7 +49,8 @@ paths: summary: Invalidates all access tokens for a user description: |- Invalidates all access tokens for a user, so that they can no longer be used for - authorization. This includes the access token that made this request. + authorization. This includes the access token that made this request. All devices + for the user are also deleted. This endpoint does not require UI authorization because UI authorization is designed to protect against attacks where the someone gets hold of a single access diff --git a/changelogs/client_server/newsfragments/2028.clarification b/changelogs/client_server/newsfragments/2028.clarification new file mode 100644 index 00000000..75e21e74 --- /dev/null +++ b/changelogs/client_server/newsfragments/2028.clarification @@ -0,0 +1 @@ +Clarify that devices are deleted upon logout. From d52fcdacfa7a98e6ab56916dd7d331e53d94ab77 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 21:36:31 -0600 Subject: [PATCH 099/497] Add M_NOT_FOUND definition for deleting non-existent aliases Fixes https://github.com/matrix-org/matrix-doc/issues/1675 --- api/client-server/directory.yaml | 9 +++++++++ .../client_server/newsfragments/2029.clarification | 1 + 2 files changed, 10 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2029.clarification diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml index 78ddfa29..2c7c8386 100644 --- a/api/client-server/directory.yaml +++ b/api/client-server/directory.yaml @@ -148,5 +148,14 @@ paths: } schema: type: object + 404: + description: There is no mapped room ID for this room alias. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Room alias #monkeys:example.org not found." + } + schema: + "$ref": "definitions/errors/error.yaml" tags: - Room directory diff --git a/changelogs/client_server/newsfragments/2029.clarification b/changelogs/client_server/newsfragments/2029.clarification new file mode 100644 index 00000000..95b65481 --- /dev/null +++ b/changelogs/client_server/newsfragments/2029.clarification @@ -0,0 +1 @@ +Add ``M_NOT_FOUND`` error definition for deleting room aliases. From a30dbc590da00727e71920af0df7f5e140783aba Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 21:39:09 -0600 Subject: [PATCH 100/497] Clarify that e2e keys are also obliterated --- api/client-server/logout.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/api/client-server/logout.yaml b/api/client-server/logout.yaml index 8451f739..75a3ec87 100644 --- a/api/client-server/logout.yaml +++ b/api/client-server/logout.yaml @@ -33,6 +33,7 @@ paths: description: |- Invalidates an existing access token, so that it can no longer be used for authorization. The device associated with the access token is also deleted. + `Device keys <#device-keys>`_ for the device are deleted alongside the device. operationId: logout security: - accessToken: [] @@ -50,7 +51,8 @@ paths: description: |- Invalidates all access tokens for a user, so that they can no longer be used for authorization. This includes the access token that made this request. All devices - for the user are also deleted. + for the user are also deleted. `Device keys <#device-keys>`_ for the device are + deleted alongside the device. This endpoint does not require UI authorization because UI authorization is designed to protect against attacks where the someone gets hold of a single access From 1bda3fe2b20427be2e129ac2a91d7dc9bbd72215 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 21:49:46 -0600 Subject: [PATCH 101/497] Spec MSISDN UIA support Fixes https://github.com/matrix-org/matrix-doc/issues/1702 1702 describes the lack of `bind_msisdn` parameter, however the whole login type was missing from UIA. --- api/client-server/registration.yaml | 6 ++++ .../client_server/newsfragments/2030.feature | 1 + specification/client_server_api.rst | 29 +++++++++++++++++++ 3 files changed, 36 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2030.feature diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index e2d35d2c..741008bb 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -94,6 +94,12 @@ paths: If true, the server binds the email used for authentication to the Matrix ID with the identity server. example: false + bind_msisdn: + type: boolean + description: |- + If true, the server binds the phone number used for authentication + to the Matrix ID with the identity server. + example: false username: type: string description: |- diff --git a/changelogs/client_server/newsfragments/2030.feature b/changelogs/client_server/newsfragments/2030.feature new file mode 100644 index 00000000..b5975a73 --- /dev/null +++ b/changelogs/client_server/newsfragments/2030.feature @@ -0,0 +1 @@ +Add MSISDN (phone number) support to User-Interactive Authentication. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 604c2b1c..a40d463c 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -618,6 +618,7 @@ This specification defines the following auth types: - ``m.login.recaptcha`` - ``m.login.oauth2`` - ``m.login.email.identity`` + - ``m.login.msisdn`` - ``m.login.token`` - ``m.login.dummy`` @@ -782,6 +783,34 @@ To use this authentication type, clients should submit an auth dict as follows: "session": "" } +Phone number/MSISDN-based (identity server) +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< +:Type: + ``m.login.msisdn`` +:Description: + Authentication is supported by authorising a phone number with an identity + server. + +Prior to submitting this, the client should authenticate with an identity +server. After authenticating, the session information should be submitted to +the homeserver. + +To use this authentication type, clients should submit an auth dict as follows: + +.. code:: json + + { + "type": "m.login.msisdn", + "threepidCreds": [ + { + "sid": "", + "client_secret": "", + "id_server": "" + } + ], + "session": "" + } + Dummy Auth <<<<<<<<<< :Type: From 00f97636a22b28de26ffaafd674e1014374210e0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 22:08:04 -0600 Subject: [PATCH 102/497] Add missing reason property to m.call.hangup Fixes https://github.com/matrix-org/matrix-doc/issues/1689 --- .../client_server/newsfragments/2031.clarification | 1 + event-schemas/schema/m.call.hangup | 10 +++++++++- 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2031.clarification diff --git a/changelogs/client_server/newsfragments/2031.clarification b/changelogs/client_server/newsfragments/2031.clarification new file mode 100644 index 00000000..9bed3bcc --- /dev/null +++ b/changelogs/client_server/newsfragments/2031.clarification @@ -0,0 +1 @@ +Add missing ``reason`` to ``m.call.hangup``. diff --git a/event-schemas/schema/m.call.hangup b/event-schemas/schema/m.call.hangup index 9d45d179..0328e03a 100644 --- a/event-schemas/schema/m.call.hangup +++ b/event-schemas/schema/m.call.hangup @@ -1,6 +1,6 @@ { "type": "object", - "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.", + "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call. The ``reason`` for the hangup is expected to be provided when there was an error in the call negotiation, such as ``ice_failed`` for when ICE negotiation fails or ``invite_timeout`` for when the other party did not answer in time.", "allOf": [{ "$ref": "core-event-schema/room_event.yaml" }], @@ -15,6 +15,14 @@ "version": { "type": "integer", "description": "The version of the VoIP specification this message adheres to. This specification is version 0." + }, + "reason": { + "type": "string", + "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call.", + "enum": [ + "ice_failed", + "invite_timeout" + ] } }, "required": ["call_id", "version"] From 23ab1c527a4864f632ce07d80d80fa23eae81ed6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 May 2019 22:16:12 -0600 Subject: [PATCH 103/497] Clarify how redactions affect room state Fixes https://github.com/matrix-org/matrix-doc/issues/1726 --- .../client_server/newsfragments/2032.clarification | 1 + specification/client_server_api.rst | 9 +++++++++ 2 files changed, 10 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2032.clarification diff --git a/changelogs/client_server/newsfragments/2032.clarification b/changelogs/client_server/newsfragments/2032.clarification new file mode 100644 index 00000000..e497b8be --- /dev/null +++ b/changelogs/client_server/newsfragments/2032.clarification @@ -0,0 +1 @@ +Clarify how redactions affect room state. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 604c2b1c..a254a85d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1531,6 +1531,15 @@ property of the redacted event, under the ``redacted_because`` key. When a client receives a redaction event it should change the redacted event in the same way a server does. +.. NOTE:: + + Redacted events can still affect the state of the room. For example, a + redacted ``join`` event will still result in the user being considered + joined. Similarly, a redacted topic does not necessarily cause the topic + to revert to what is was prior to the event - it causes the topic to be + removed from the room. + + Events ++++++ From e7ed8a23ce1e2e4c11484e1ffcda728730c56b22 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 14:42:00 -0600 Subject: [PATCH 104/497] Move lazy loading filter options to event filter The options also work on /messages --- .../definitions/room_event_filter.yaml | 25 ++++++++++++++++ .../definitions/sync_filter.yaml | 29 +------------------ 2 files changed, 26 insertions(+), 28 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index aa217d2b..fd399913 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -16,6 +16,31 @@ allOf: - type: object title: RoomEventFilter properties: + lazy_load_members: + type: boolean + description: |- + If ``true``, the only ``m.room.member`` events returned in + the ``state`` section of the ``/sync`` response are those + which are definitely necessary for a client to display + the ``sender`` of the timeline events in that response. + If ``false``, ``m.room.member`` events are not filtered. + By default, servers should suppress duplicate redundant + lazy-loaded ``m.room.member`` events from being sent to a given + client across multiple calls to ``/sync``, given that most clients + cache membership events (see ``include_redundant_members`` + to change this behaviour). + include_redundant_members: + type: boolean + description: |- + If ``true``, the ``state`` section of the ``/sync`` response will + always contain the ``m.room.member`` events required to display + the ``sender`` of the timeline events in that response, assuming + ``lazy_load_members`` is enabled. This means that redundant + duplicate member events may be returned across multiple calls to + ``/sync``. This is useful for naive clients who never track + membership data. If ``false``, duplicate ``m.room.member`` events + may be suppressed by the server across multiple calls to ``/sync``. + If ``lazy_load_members`` is ``false`` this field is ignored. not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` diff --git a/api/client-server/definitions/sync_filter.yaml b/api/client-server/definitions/sync_filter.yaml index 65b18ba6..45a269c7 100644 --- a/api/client-server/definitions/sync_filter.yaml +++ b/api/client-server/definitions/sync_filter.yaml @@ -47,7 +47,7 @@ properties: not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` - filter. This filter is applied before the filters in ``ephemeral``, + filter. This filter is applied before the filters in ``ephemeral``, ``state``, ``timeline`` or ``account_data`` items: type: string @@ -73,33 +73,6 @@ properties: allOf: - $ref: room_event_filter.yaml description: The state events to include for rooms. - properties: - lazy_load_members: - type: boolean - description: |- - If ``true``, the only ``m.room.member`` events returned in - the ``state`` section of the ``/sync`` response are those - which are definitely necessary for a client to display - the ``sender`` of the timeline events in that response. - If ``false``, ``m.room.member`` events are not filtered. - By default, servers should suppress duplicate redundant - lazy-loaded ``m.room.member`` events from being sent to a given - client across multiple calls to ``/sync``, given that most clients - cache membership events (see ``include_redundant_members`` - to change this behaviour). - include_redundant_members: - type: boolean - description: |- - If ``true``, the ``state`` section of the ``/sync`` response will - always contain the ``m.room.member`` events required to display - the ``sender`` of the timeline events in that response, assuming - ``lazy_load_members`` is enabled. This means that redundant - duplicate member events may be returned across multiple calls to - ``/sync``. This is useful for naive clients who never track - membership data. If ``false``, duplicate ``m.room.member`` events - may be suppressed by the server across multiple calls to ``/sync``. - If ``lazy_load_members`` is ``false`` this field is ignored. - timeline: allOf: - $ref: room_event_filter.yaml From d56df3238c58abde17ca28165baa9b904cb743c0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 14:35:37 -0600 Subject: [PATCH 105/497] Generalize wording to fit /messages and /sync --- .../definitions/room_event_filter.yaml | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index fd399913..5258ea30 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -19,28 +19,32 @@ allOf: lazy_load_members: type: boolean description: |- - If ``true``, the only ``m.room.member`` events returned in - the ``state`` section of the ``/sync`` response are those - which are definitely necessary for a client to display - the ``sender`` of the timeline events in that response. + If ``true``, the only ``m.room.member`` events returned + are those which are definitely necessary for a client to + display the ``sender`` of the timeline events in the response. If ``false``, ``m.room.member`` events are not filtered. By default, servers should suppress duplicate redundant lazy-loaded ``m.room.member`` events from being sent to a given - client across multiple calls to ``/sync``, given that most clients + client across multiple calls, given that most clients cache membership events (see ``include_redundant_members`` to change this behaviour). + + Only applicable when filtering state events, such as the + ``state`` section of a ``/sync`` or ``/messages``. include_redundant_members: type: boolean description: |- - If ``true``, the ``state`` section of the ``/sync`` response will - always contain the ``m.room.member`` events required to display - the ``sender`` of the timeline events in that response, assuming - ``lazy_load_members`` is enabled. This means that redundant - duplicate member events may be returned across multiple calls to - ``/sync``. This is useful for naive clients who never track + If ``true``, response will always contain the ``m.room.member`` + events required to display the ``sender`` of the timeline events + in that response, assuming ``lazy_load_members`` is enabled. This + means that redundant duplicate member events may be returned across + multiple calls to. This is useful for naive clients who never track membership data. If ``false``, duplicate ``m.room.member`` events - may be suppressed by the server across multiple calls to ``/sync``. - If ``lazy_load_members`` is ``false`` this field is ignored. + may be suppressed by the server across multiple calls. If + ``lazy_load_members`` is ``false`` this field is ignored. + + Only applicable when filtering state events, such as the + ``state`` section of a ``/sync`` or ``/messages``. not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` From 34d6c1f4ad60d7d753ac703613034a8756662ae8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 14:46:59 -0600 Subject: [PATCH 106/497] Clarify wording further for how to handle redundant members Note: This makes assumptions on what the TODO comment in Synapse means: https://github.com/matrix-org/synapse/blob/e26e6b3230f0b55376f0f3bf823dd789ac7064d0/synapse/handlers/pagination.py#L262 Due to lack of implementation, it is assumed that using the same filter across multiple calls to /sync OR /messages will result in the redundant members being excluded in the next request. For example, calling /sync, then /messages which returns some members, then /sync again will exclude the members due to them being in /messages. --- .../definitions/room_event_filter.yaml | 25 ++++++++++--------- api/client-server/message_pagination.yaml | 17 +++++++++++++ 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 5258ea30..35b3edf9 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -24,27 +24,28 @@ allOf: display the ``sender`` of the timeline events in the response. If ``false``, ``m.room.member`` events are not filtered. By default, servers should suppress duplicate redundant - lazy-loaded ``m.room.member`` events from being sent to a given - client across multiple calls, given that most clients - cache membership events (see ``include_redundant_members`` - to change this behaviour). + lazy-loaded ``m.room.member`` events from being sent to a + given client in a previous request using the same filter, + given that most clients cache membership events (see + ``include_redundant_members`` to change this behaviour). Only applicable when filtering state events, such as the - ``state`` section of a ``/sync`` or ``/messages``. + ``state`` section of a ``/sync`` or ``/messages`` response. include_redundant_members: type: boolean description: |- If ``true``, response will always contain the ``m.room.member`` events required to display the ``sender`` of the timeline events - in that response, assuming ``lazy_load_members`` is enabled. This - means that redundant duplicate member events may be returned across - multiple calls to. This is useful for naive clients who never track - membership data. If ``false``, duplicate ``m.room.member`` events - may be suppressed by the server across multiple calls. If - ``lazy_load_members`` is ``false`` this field is ignored. + in that response, assuming ``lazy_load_members`` is enabled. + This means that redundant duplicate member events will be returned + across multiple calls using the same filter. This is useful for + naive clients who never track membership data. If ``false`` or + not provided, duplicate ``m.room.member`` events should be + suppressed by the server across multiple calls. If ``lazy_load_members`` + is ``false`` this field is ignored. Only applicable when filtering state events, such as the - ``state`` section of a ``/sync`` or ``/messages``. + ``state`` section of a ``/sync`` or ``/messages`` response. not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 941e61fb..ff6d970d 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -108,6 +108,23 @@ paths: type: object title: RoomEvent "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml" + state: + type: array + description: |- + A list of state events relevant to showing the ``chunk``. For example, if + lazy-loading members is enabled in the filter then this will contain any + applicable membership events. Servers should be careful to not exclude + membership events which are older than ones already sent to the client. + Likewise, clients should be cautious and avoid using older membership + events as the current membership event when paginating backwards. + + Unless ``include_redundant_members`` is ``true``, the server should remove + redundant members which would have already been sent to clients in prior calls + to ``/messages`` or ``/sync`` with the same filter. + items: + type: object + title: RoomStateEvent + $ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml" examples: application/json: { "start": "t47429-4392820_219380_26003_2265", From b67161cf97badda0c37ccaa482634e5c5fa4093b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 14:59:59 -0600 Subject: [PATCH 107/497] List the endpoints which are lazy-loading aware --- api/client-server/definitions/room_event_filter.yaml | 9 +++++++-- api/client-server/event_context.yaml | 3 +++ api/client-server/message_pagination.yaml | 5 ++++- api/client-server/sync.yaml | 3 +++ 4 files changed, 17 insertions(+), 3 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 35b3edf9..4790643e 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -30,7 +30,12 @@ allOf: ``include_redundant_members`` to change this behaviour). Only applicable when filtering state events, such as the - ``state`` section of a ``/sync`` or ``/messages`` response. + ``state`` section of a lazy-loading aware endpoint. + + The endpoints which support lazy-loading are: + `/sync <#get-matrix-client-%CLIENT_RELEASE_LABEL%-sync>`_, + `/messages <#get-matrix-client-%CLIENT_RELEASE_LABEL%-rooms-roomid-messages>`_, + and `/context <#get-matrix-client-%CLIENT_RELEASE_LABEL%-rooms-roomid-context-eventid>`_. include_redundant_members: type: boolean description: |- @@ -45,7 +50,7 @@ allOf: is ``false`` this field is ignored. Only applicable when filtering state events, such as the - ``state`` section of a ``/sync`` or ``/messages`` response. + ``state`` section of a lazy-loading aware endpoint. not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 91da3cf4..c0f391e5 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -34,6 +34,9 @@ paths: This API returns a number of events that happened just before and after the specified event. This allows clients to get the context surrounding an event. + + *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ + for more information. operationId: getEventContext security: - accessToken: [] diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index ff6d970d..716afb65 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -33,6 +33,9 @@ paths: description: |- This API returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room. + + *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ + for more information. operationId: getRoomEvents security: - accessToken: [] @@ -120,7 +123,7 @@ paths: Unless ``include_redundant_members`` is ``true``, the server should remove redundant members which would have already been sent to clients in prior calls - to ``/messages`` or ``/sync`` with the same filter. + to lazy-loading aware endpoints with the same filter. items: type: object title: RoomStateEvent diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index f204152a..87e7bf74 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -34,6 +34,9 @@ paths: Clients use this API when they first log in to get an initial snapshot of the state on the server, and then continue to call this API to get incremental deltas to the state, and to receive new messages. + + *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ + for more information. operationId: sync security: - accessToken: [] From ba520df004eafdf3fc58d051a567708d7419fe14 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 17:38:04 -0600 Subject: [PATCH 108/497] Move lazy loading to a section in Filtering --- .../definitions/room_event_filter.yaml | 36 ++++--------------- api/client-server/sync.yaml | 3 +- specification/client_server_api.rst | 33 +++++++++++++++++ 3 files changed, 42 insertions(+), 30 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 4790643e..0659be8e 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -19,38 +19,16 @@ allOf: lazy_load_members: type: boolean description: |- - If ``true``, the only ``m.room.member`` events returned - are those which are definitely necessary for a client to - display the ``sender`` of the timeline events in the response. - If ``false``, ``m.room.member`` events are not filtered. - By default, servers should suppress duplicate redundant - lazy-loaded ``m.room.member`` events from being sent to a - given client in a previous request using the same filter, - given that most clients cache membership events (see - ``include_redundant_members`` to change this behaviour). - - Only applicable when filtering state events, such as the - ``state`` section of a lazy-loading aware endpoint. - - The endpoints which support lazy-loading are: - `/sync <#get-matrix-client-%CLIENT_RELEASE_LABEL%-sync>`_, - `/messages <#get-matrix-client-%CLIENT_RELEASE_LABEL%-rooms-roomid-messages>`_, - and `/context <#get-matrix-client-%CLIENT_RELEASE_LABEL%-rooms-roomid-context-eventid>`_. + If ``true``, enables lazy-loading of membership events. See + `Lazy-loading room members <#lazy-loading-room-members>`_ + for more information. Defaults to ``false``. include_redundant_members: type: boolean description: |- - If ``true``, response will always contain the ``m.room.member`` - events required to display the ``sender`` of the timeline events - in that response, assuming ``lazy_load_members`` is enabled. - This means that redundant duplicate member events will be returned - across multiple calls using the same filter. This is useful for - naive clients who never track membership data. If ``false`` or - not provided, duplicate ``m.room.member`` events should be - suppressed by the server across multiple calls. If ``lazy_load_members`` - is ``false`` this field is ignored. - - Only applicable when filtering state events, such as the - ``state`` section of a lazy-loading aware endpoint. + If ``true``, enables redudant membership events. Does not + apply unless ``lazy_load_members`` is ``true``. See + `Lazy-loading room members <#lazy-loading-room-members>`_ + for more information. Defaults to ``false``. not_rooms: description: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 87e7bf74..bd659369 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -36,7 +36,8 @@ paths: incremental deltas to the state, and to receive new messages. *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ - for more information. + for more information. Lazy-loading members is only supported on a ``StateFilter`` + for this endpoint. operationId: sync security: - accessToken: [] diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 604c2b1c..a4b8dd5c 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1268,6 +1268,39 @@ Filters can be created on the server and can be passed as as a parameter to APIs which return events. These filters alter the data returned from those APIs. Not all APIs accept filters. +Lazy-loading room members +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Membership events often take significant resources for clients to track. In an +effort to reduce the number of resources used, clients can enable "lazy-loading" +for room members. By doing this, servers will only ever send membership events +which are relevant to the client. + +In terms of filters, this means enabling ``lazy_load_members`` on a ``StateFilter`` +or ``RoomEventFilter``. When enabled, lazy-loading aware endpoints (see below) +will only include membership events for the ``sender`` of events being included +in the response. For example, if a client makes a ``/sync`` request with lazy-loading +enabled, the server will only return membership events for the ``sender`` of events +in the timeline, not all members of a room. + +Repeated calls to lazy-loading aware endpoints will result in redundant membership +events being excluded by default. Clients often track which membership events they +already have, therefore making the extra information not as useful to the client. +Clients can always request redundant members by setting ``include_redundant_members`` +to true in the filter. + +Servers should be cautious about which events they consider redundant. Membership +events can change over time, and should be included as relevant to maintain the +historical record. Likewise, clients should be cautious about treating an older event +as the current membership event for a user. + +.. Note:: + Repeated calls using the same filter to *any* lazy-loading aware endpoint may + result in redundant members being excluded from future calls. For example, a + request to ``/sync`` followed by a request to ``/messages`` may result in a + future call to ``/sync`` excluding members included by the ``/messages`` call. + + {{filter_cs_http_api}} Events From 7b266b33da0cdabcfa6e2d2fdf4d3fc36f83ed0f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 19:26:26 -0600 Subject: [PATCH 109/497] Add membership params Fixes https://github.com/matrix-org/matrix-doc/issues/1945 --- api/client-server/rooms.yaml | 38 ++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index cc1f2bf7..acddf891 100644 --- a/api/client-server/rooms.yaml +++ b/api/client-server/rooms.yaml @@ -288,6 +288,44 @@ paths: description: The room to get the member events for. required: true x-example: "!636q39766251:example.com" + - in: query + name: at + type: string + description: |- + The point in time (pagination token) to return members for in the room. + This token can be obtained from a ``prev_batch`` token returned for + each room by the sync API. Defaults to the current state of the room, + as determined by the server. + x-example: "YWxsCgpOb25lLDM1ODcwOA" + # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON + # filter might be a better alternative. + # See https://github.com/matrix-org/matrix-doc/issues/1337 + - in: query + name: membership + type: string + enum: + - join + - invite + - leave + - ban + description: |- + The kind of membership to filter for. Defaults to no filtering if + unspecified. When specified alongside ``not_membership``, the two + parameters create an 'or' condition: either the membership *is* + the same as ``membership`` **or** *is not* the same as ``not_membership``. + x-example: "join" + - in: query + name: not_membership + type: string + enum: + - join + - invite + - leave + - ban + description: |- + The kind of membership to exclude from the results. Defaults to no + filtering if unspecified. + x-example: leave security: - accessToken: [] responses: From b3d86f99b9d21ad98e26b37cf6afcc73d7064964 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 20:20:00 -0600 Subject: [PATCH 110/497] Add room summary spec --- api/client-server/sync.yaml | 52 +++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index bd659369..2c504295 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -129,6 +129,50 @@ paths: title: Joined Room type: object properties: + summary: + title: RoomSummary + type: object + description: |- + Information about the room which clients may need to + correctly render it to users. + properties: + "m.heroes": + type: array + description: |- + The users which can be used to generate a room name + if the room does not have one. Required if the room + does not have a ``m.room.name`` or ``m.room.canonical_alias`` + state event with non-empty content. + + This should be the first 5 members of the room, ordered + by stream ordering, which are joined or invited. The + list must never include the client's own user ID. When + no joined or invited members are available, this should + consist of the banned and left users. More than 5 members + may be provided, however less than 5 should only be provided + when there are less than 5 members to represent. + + When lazy-loading room members is enabled, the membership + events for the heroes MUST be included in the ``state``, + unless they are redundant. When the list of users changes, + the server notifies the client by sending a fresh list of + heroes. If there are no changes since the last sync, this + field may be omitted. + items: + type: string + "m.joined_member_count": + type: integer + description: |- + The number of users with ``membership`` of ``join``, + including the client's own user ID. If this field has + not changed since the last sync, it may be omitted. + Required otherwise. + "m.invited_member_count": + type: integer + description: |- + The number of users with ``membership`` of ``invite``. + If this field has not changed since the last sync, it + may be omitted. Required otherwise. state: title: State type: object @@ -334,6 +378,14 @@ paths: "rooms": { "join": { "!726s6s6q:example.com": { + "summary": { + "m.heroes": [ + "@alice:example.com", + "@bob:example.com" + ], + "m.joined_member_count": 2, + "m.invited_member_count": 0 + }, "state": { "events": [ { From 8330810e957bf33991274b9fad6cd258deaf670d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 20:47:03 -0600 Subject: [PATCH 111/497] Specify the new room naming scheme --- specification/modules/instant_messaging.rst | 88 +++++++-------------- 1 file changed, 30 insertions(+), 58 deletions(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 86daa700..dd3e9c6c 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -278,70 +278,42 @@ choose a name: #. If the room has an `m.room.canonical_alias`_ state event with a non-empty ``alias`` field, use the alias given by that field as the name. -#. If neither of the above conditions are met, a name should be composed based +#. If neither of the above conditions are met, the client can optionally guess + an alias from the ``m.room.alias`` events in the room. This is a temporary + measure while clients do not promote canonical aliases as prominently. This + step may be removed in a future version of the specification. + +#. If none of the above conditions are met, a name should be composed based on the members of the room. Clients should consider `m.room.member`_ events - for users other than the logged-in user, with ``membership: join`` or - ``membership: invite``. + for users other than the logged-in user, as defined below. - .. _active_members: + i. If the ``m.heroes`` for the room are greater or equal to + ``m.joined_member_count + m.invited_member_count - 1``, then use the + membership events for the heroes to calculate display names for the + users (`disambiguating them if required`_) and concatenating them. For + example, the client may choose to show "Alice, Bob, and Charlie + (@charlie:example.org)" as the room name. The client may optionally + limit the number - i. If there is only one such event, the display name for the room should be - the `disambiguated display name`_ of the corresponding user. + #. If there are fewer heroes than ``m.joined_member_count + m.invited_member_count + - 1``, and ``m.joined_member_count + m.invited_member_count`` is greater + than 1, the client should use the heroes to calculate display names for + the users (`disambiguating them if required`_) and concatenating them + alongside a count of the remaining users. For example, "Alice, Bob, and + 1234 others". - #. If there are two such events, they should be lexicographically sorted by - their ``state_key`` (i.e. the corresponding user IDs), and the display - name for the room should be the `disambiguated display name`_ of both - users: " and ", or a localised variant thereof. + #. If ``m.joined_member_count + m.invited_member_count`` is less than or + equal to 1 (indicating the member is alone), the client should use the + rules above to indicate that the room was empty. For example, "Empty + Room (was Alice)", "Empty Room (was Alice and 1234 others)", or + "Empty Room" if there are no heroes. - #. If there are three or more such events, the display name for the room - should be based on the disambiguated display name of the user - corresponding to the first such event, under a lexicographical sorting - according to their ``state_key``. The display name should be in the - format " and others" (or a localised variant thereof), where N - is the number of `m.room.member`_ events with ``membership: join`` or - ``membership: invite``, excluding the logged-in user and "user1". - - For example, if Alice joins a room, where Bob (whose user id is - ``@superuser:example.com``), Carol (user id ``@carol:example.com``) and - Dan (user id ``@dan:matrix.org``) are in conversation, Alice's - client should show the room name as "Carol and 2 others". - - .. TODO-spec - Sorting by user_id certainly isn't ideal, as IDs at the start of the - alphabet will end up dominating room names: they will all be called - "Arathorn and 15 others". Furthermore - user_ids are not necessarily - ASCII, which means we need to either specify a collation order, or specify - how to choose one. - - Ideally we might sort by the time when the user was first invited to, or - first joined the room. But we don't have this information. - - See https://matrix.org/jira/browse/SPEC-267 for further discussion. - -#. If the room has no valid ``m.room.name`` or ``m.room.canonical_alias`` - event, and no active members other than the current user, clients should - consider ``m.room.member`` events with ``membership: leave``. If such events - exist, a display name such as "Empty room (was and others)" (or - a localised variant thereof) should be used, following similar rules as for - active members (see `above `_). - -#. A complete absence of room name, canonical alias, and room members is likely - to indicate a problem with creating the room or synchronising the state - table; however clients should still handle this situation. A display name - such as "Empty room" (or a localised variant thereof) should be used in this - situation. - -.. _`disambiguated display name`: `Calculating the display name for a user`_ - -Clients SHOULD NOT use `m.room.aliases`_ events as a source for room names, as -it is difficult for clients to agree on the best alias to use, and aliases can -change unexpectedly. - -.. TODO-spec - How can we make this less painful for clients to implement, without forcing - an English-language implementation on them all? See - https://matrix.org/jira/browse/SPEC-425. +Clients SHOULD internationalise the room name to the user's language when using +the ``m.heroes`` to calculate the name. Clients SHOULD use minimum 5 heroes to +calculate room names where possible, but may use more or less to fit better with +their user experience. +.. _`disambiguating them if required`: `Calculating the display name for a user`_ Forming relationships between events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From b1dccda49ddae41ec67e193b7da1f0bd1f345360 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 20:47:53 -0600 Subject: [PATCH 112/497] changelog --- changelogs/client_server/newsfragments/2035.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2035.feature diff --git a/changelogs/client_server/newsfragments/2035.feature b/changelogs/client_server/newsfragments/2035.feature new file mode 100644 index 00000000..47029c28 --- /dev/null +++ b/changelogs/client_server/newsfragments/2035.feature @@ -0,0 +1 @@ +Add the option to lazy-load room members for increased client performance. From d14dc1d8e15a12b91cb20592d6e46c6b20ea678a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 21:15:24 -0600 Subject: [PATCH 113/497] Clarify that redacted state events affect the room with default values --- specification/client_server_api.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index a254a85d..22cc9425 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1533,11 +1533,12 @@ same way a server does. .. NOTE:: - Redacted events can still affect the state of the room. For example, a - redacted ``join`` event will still result in the user being considered - joined. Similarly, a redacted topic does not necessarily cause the topic - to revert to what is was prior to the event - it causes the topic to be - removed from the room. + Redacted events can still affect the state of the room. When redacted, + state events behave as though their properties were simply not specified + unless their properties are protected by the redaction algorithm. For example, + a redacted ``join`` event will still result in the user being considered joined. + Similarly, a redacted topic does not necessarily cause the topic to revert to + what is was prior to the event - it causes the topic to be removed from the room. Events From 229893589a30f21560cf55fac00d0112fa041413 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 21:18:04 -0600 Subject: [PATCH 114/497] Move wording for reason definitions --- event-schemas/schema/m.call.hangup | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/event-schemas/schema/m.call.hangup b/event-schemas/schema/m.call.hangup index 0328e03a..c0478f5a 100644 --- a/event-schemas/schema/m.call.hangup +++ b/event-schemas/schema/m.call.hangup @@ -1,6 +1,6 @@ { "type": "object", - "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call. The ``reason`` for the hangup is expected to be provided when there was an error in the call negotiation, such as ``ice_failed`` for when ICE negotiation fails or ``invite_timeout`` for when the other party did not answer in time.", + "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.", "allOf": [{ "$ref": "core-event-schema/room_event.yaml" }], @@ -18,7 +18,7 @@ }, "reason": { "type": "string", - "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call.", + "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be ``ice_failed`` for when ICE negotiation fails or ``invite_timeout`` for when the other party did not answer in time.", "enum": [ "ice_failed", "invite_timeout" From ade346f8cc173a532a0e991b61ed153a3ea93e9c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 21:19:58 -0600 Subject: [PATCH 115/497] Add m.server_notice to reserved tags --- specification/modules/tags.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index a4b0becf..9d0cd554 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -34,9 +34,9 @@ The JSON object associated with each tag gives information about the tag, e.g ho to order the rooms with a given tag. Ordering information is given under the ``order`` key as a number between 0 and -1. The numbers are compared such that 0 is displayed first. Therefore a room -with an ``order`` of ``0.2`` would be displayed before a room with an ``order`` -of ``0.7``. If a room has a tag without an ``order`` key then it should appear +1. The numbers are compared such that 0 is displayed first. Therefore a room +with an ``order`` of ``0.2`` would be displayed before a room with an ``order`` +of ``0.7``. If a room has a tag without an ``order`` key then it should appear after the rooms with that tag that have an ``order`` key. The name of a tag MUST NOT exceed 255 bytes. @@ -60,6 +60,7 @@ The following tags are defined in the ``m.*`` namespace: * ``m.favourite``: The user's favourite rooms. These should be shown with higher precedence than other rooms. * ``m.lowpriority``: These should be shown with lower precedence than others. +* ``m.server_notice``: Used to identify `Server Notice Rooms <#module-server-notices>`_. {{m_tag_event}} From 9acd960cf6afc8ddb011f7db5ca00fbf57cba5a5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 21:22:07 -0600 Subject: [PATCH 116/497] Update specification/client_server_api.rst Co-Authored-By: Kitsune Ral --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 22cc9425..c18f4d03 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1535,7 +1535,7 @@ same way a server does. Redacted events can still affect the state of the room. When redacted, state events behave as though their properties were simply not specified - unless their properties are protected by the redaction algorithm. For example, + except those protected by the redaction algorithm. For example, a redacted ``join`` event will still result in the user being considered joined. Similarly, a redacted topic does not necessarily cause the topic to revert to what is was prior to the event - it causes the topic to be removed from the room. From 699cafe6701d2206160170c6eaafeb789405507a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 21:27:54 -0600 Subject: [PATCH 117/497] v4 is v4, not v3 --- api/server-server/definitions/pdu_v4.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/server-server/definitions/pdu_v4.yaml b/api/server-server/definitions/pdu_v4.yaml index 55b1c26f..a045e657 100644 --- a/api/server-server/definitions/pdu_v4.yaml +++ b/api/server-server/definitions/pdu_v4.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object title: Persistent Data Unit -description: A persistent data unit (event) for room version 3 and beyond. +description: A persistent data unit (event) for room version 4 and beyond. example: $ref: "../examples/pdu_v4.json" allOf: From 10648aa9e8ce9556d3b881539acca7c9a7962156 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 22:30:37 -0600 Subject: [PATCH 118/497] Clarify that FAIL_ERROR is not limited to just homeservers. Fixes https://github.com/matrix-org/matrix-doc/issues/1735 --- changelogs/client_server/newsfragments/2036.clarification | 1 + specification/client_server_api.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2036.clarification diff --git a/changelogs/client_server/newsfragments/2036.clarification b/changelogs/client_server/newsfragments/2036.clarification new file mode 100644 index 00000000..96058b7b --- /dev/null +++ b/changelogs/client_server/newsfragments/2036.clarification @@ -0,0 +1 @@ +Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index a8bbfca0..4158bad8 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -289,7 +289,7 @@ In this section, the following terms are used with specific meanings: ``FAIL_ERROR`` Inform the user that auto-discovery did not return any usable URLs. Do not continue further with the current login process. At this point, valid data - was obtained, but no homeserver is available to serve the client. No further + was obtained, but no server is available to serve the client. No further guess should be attempted and the user should make a conscientious decision what to do next. From d0fd20fdb4b412c9bb596cfc2b06915d46c631a3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 22:40:07 -0600 Subject: [PATCH 119/497] Clarify how homeservers are meant to auth themselves to appservices Fixes https://github.com/matrix-org/matrix-doc/issues/1765 Note that the swagger definitions already say that authorization is required. It just wasn't mentioned in the spec. --- .../application_service/newsfragments/2037.clarification | 1 + specification/application_service_api.rst | 8 ++++++++ 2 files changed, 9 insertions(+) create mode 100644 changelogs/application_service/newsfragments/2037.clarification diff --git a/changelogs/application_service/newsfragments/2037.clarification b/changelogs/application_service/newsfragments/2037.clarification new file mode 100644 index 00000000..f425b1c1 --- /dev/null +++ b/changelogs/application_service/newsfragments/2037.clarification @@ -0,0 +1 @@ +Add missing definition for how appservices verify requests came from a homeserver. diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 865544dd..81077bcf 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -187,6 +187,14 @@ An example registration file for an IRC-bridging application service is below: Homeserver -> Application Service API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Authorization ++++++++++++++ + +Homeservers MUST include a query parameter named ``access_token`` containing the +``hs_token`` from the application service's registration when making requests to +the application service. Application services MUST verify the provided ``access_token`` +matches their known ``hs_token``, failing the request with a ``M_FORBIDDEN`` error. + Legacy routes +++++++++++++ From d8eb2949066c9c53f7501da9fb86f76fa762e960 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 22:44:24 -0600 Subject: [PATCH 120/497] Fix s2s changelog entries --- changelogs/server_server/newsfragments/1904.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/server_server/newsfragments/1904.clarification b/changelogs/server_server/newsfragments/1904.clarification index 94174ebd..531fdb94 100644 --- a/changelogs/server_server/newsfragments/1904.clarification +++ b/changelogs/server_server/newsfragments/1904.clarification @@ -1 +1 @@ -Fix the `access_token` parameter in the open_id endpoint. +Fix the ``access_token`` parameter in the open_id endpoint. From 88d47fd57e423c3e2e958fc547f7ef4812eb3ca2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 22:51:52 -0600 Subject: [PATCH 121/497] Rename changelog entry to point to PR We use the PR for every other entry, so here is no exception. --- .../newsfragments/{1904.clarification => 1906.clarification} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/server_server/newsfragments/{1904.clarification => 1906.clarification} (100%) diff --git a/changelogs/server_server/newsfragments/1904.clarification b/changelogs/server_server/newsfragments/1906.clarification similarity index 100% rename from changelogs/server_server/newsfragments/1904.clarification rename to changelogs/server_server/newsfragments/1906.clarification From 62890d21b25016dc008a5cc2e2f993ee3a0873ab Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 23:08:02 -0600 Subject: [PATCH 122/497] Fix example Content-Type for /media/upload request Fixes https://github.com/matrix-org/matrix-doc/issues/1770 --- api/client-server/content-repo.yaml | 11 ++++++----- .../client_server/newsfragments/2041.clarification | 1 + scripts/templating/matrix_templates/units.py | 9 +++++++-- 3 files changed, 14 insertions(+), 7 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2041.clarification diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 07df18fe..4460bb69 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -41,7 +41,7 @@ paths: name: Content-Type type: string description: The content type of the file being uploaded - x-example: "Content-Type: audio/mpeg" + x-example: "Content-Type: application/pdf" - in: query type: string x-example: "War and Peace.pdf" @@ -51,6 +51,7 @@ paths: name: "" description: The content to be uploaded. required: true + x-example: "" # so the spec shows "" without quotes. schema: type: string example: "" @@ -103,7 +104,7 @@ paths: default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed - remote. This is to prevent routing loops where the server contacts itself. Defaults to + remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. responses: 200: @@ -158,7 +159,7 @@ paths: default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed - remote. This is to prevent routing loops where the server contacts itself. Defaults to + remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. responses: 200: @@ -228,7 +229,7 @@ paths: default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed - remote. This is to prevent routing loops where the server contacts itself. Defaults to + remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. responses: 200: @@ -330,7 +331,7 @@ paths: m.upload.size: type: integer format: int64 - description: |- + description: |- The maximum size an upload can be in bytes. Clients SHOULD use this as a guide when uploading content. If not listed or null, the size limit should be treated as unknown. diff --git a/changelogs/client_server/newsfragments/2041.clarification b/changelogs/client_server/newsfragments/2041.clarification new file mode 100644 index 00000000..39bbddb5 --- /dev/null +++ b/changelogs/client_server/newsfragments/2041.clarification @@ -0,0 +1 @@ +Fix example ``Content-Type`` for ``/media/upload`` request. diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 466110f8..d4745e4d 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -521,6 +521,7 @@ class MatrixUnits(Units): path_template = path example_query_params = [] example_body = "" + example_mime = "application/json" for param in endpoint_swagger.get("parameters", []): # even body params should have names, otherwise the active docs don't work. param_name = param["name"] @@ -533,6 +534,10 @@ class MatrixUnits(Units): example_body = get_example_for_param(param) continue + if param_loc == "header": + if param["name"] == "Content-Type" and param["x-example"]: + example_mime = param["x-example"] + # description desc = param.get("description", "") if param.get("required"): @@ -610,8 +615,8 @@ class MatrixUnits(Units): example_query_params) if example_body: endpoint["example"][ - "req"] = "%s %s%s HTTP/1.1\nContent-Type: application/json\n\n%s" % ( - method.upper(), path_template, query_string, example_body + "req"] = "%s %s%s HTTP/1.1\nContent-Type: %s\n\n%s" % ( + method.upper(), path_template, query_string, example_mime, example_body ) else: endpoint["example"]["req"] = "%s %s%s HTTP/1.1\n\n" % ( From 572a6056ad64c5f3f654f91a27cf8a42c19d6ee5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 23:15:02 -0600 Subject: [PATCH 123/497] Clarify that login flows must be completed in order Fixes https://github.com/matrix-org/matrix-doc/issues/1134 Evidence of this being the case is shown here: https://github.com/matrix-org/synapse/pull/5174 --- changelogs/client_server/newsfragments/2042.clarification | 1 + specification/client_server_api.rst | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2042.clarification diff --git a/changelogs/client_server/newsfragments/2042.clarification b/changelogs/client_server/newsfragments/2042.clarification new file mode 100644 index 00000000..4e17b99f --- /dev/null +++ b/changelogs/client_server/newsfragments/2042.clarification @@ -0,0 +1 @@ +Clarify that login flows are meant to be completed in order. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index a8bbfca0..4b7065b3 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -406,8 +406,9 @@ an additional stage. This exchange continues until the final success. For each endpoint, a server offers one or more 'flows' that the client can use to authenticate itself. Each flow comprises a series of stages, as described -above. The client is free to choose which flow it follows. When all stages in a -flow are complete, authentication is complete and the API call succeeds. +above. The client is free to choose which flow it follows, however the flow's +stages must be completed in order. When all stages in a flow are complete, +authentication is complete and the API call succeeds. User-interactive API in the REST API <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< From 4e58414b26d9d2bc145393091b7e141574c36450 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 23:20:09 -0600 Subject: [PATCH 124/497] Clarify that clients should not ack their own messages Fixes https://github.com/matrix-org/matrix-doc/issues/567 --- changelogs/client_server/newsfragments/2043.clarification | 1 + specification/modules/receipts.rst | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2043.clarification diff --git a/changelogs/client_server/newsfragments/2043.clarification b/changelogs/client_server/newsfragments/2043.clarification new file mode 100644 index 00000000..9bb975fa --- /dev/null +++ b/changelogs/client_server/newsfragments/2043.clarification @@ -0,0 +1 @@ +Clarify that clients should not send read receipts for their own messages. diff --git a/specification/modules/receipts.rst b/specification/modules/receipts.rst index faba7b62..ee2b697a 100644 --- a/specification/modules/receipts.rst +++ b/specification/modules/receipts.rst @@ -60,7 +60,8 @@ Clients should send read receipts when there is some certainty that the event in question has been **displayed** to the user. Simply receiving an event does not provide enough certainty that the user has seen the event. The user SHOULD need to *take some action* such as viewing the room that the event was sent to or -dismissing a notification in order for the event to count as "read". +dismissing a notification in order for the event to count as "read". Clients +SHOULD NOT send read receipts for events sent by their own user. A client can update the markers for its user by interacting with the following HTTP APIs. @@ -94,4 +95,3 @@ Security considerations As receipts are sent outside the context of the event graph, there are no integrity checks performed on the contents of ``m.receipt`` events. - From bf86b4b83ca9ee97ef8bc7edcc17a663996bcffd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 May 2019 23:42:08 -0600 Subject: [PATCH 125/497] Fix incorrect PR reference on changelog --- .../client_server/newsfragments/{1903.feature => 1908.feature} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/client_server/newsfragments/{1903.feature => 1908.feature} (100%) diff --git a/changelogs/client_server/newsfragments/1903.feature b/changelogs/client_server/newsfragments/1908.feature similarity index 100% rename from changelogs/client_server/newsfragments/1903.feature rename to changelogs/client_server/newsfragments/1908.feature From 0580f5120693e2535920f5e57e4218e9467b7d18 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 12:49:50 -0600 Subject: [PATCH 126/497] Clarify that failing to follow the flows == 401 --- specification/client_server_api.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 4b7065b3..3ea1411e 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -407,8 +407,9 @@ an additional stage. This exchange continues until the final success. For each endpoint, a server offers one or more 'flows' that the client can use to authenticate itself. Each flow comprises a series of stages, as described above. The client is free to choose which flow it follows, however the flow's -stages must be completed in order. When all stages in a flow are complete, -authentication is complete and the API call succeeds. +stages must be completed in order. Failing to follow the flows in order must +result in an HTTP 401 response, as defined below. When all stages in a flow +are complete, authentication is complete and the API call succeeds. User-interactive API in the REST API <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< From 8151aa331f6b553ffa755f38aaffb5f5b466b07a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 12:51:36 -0600 Subject: [PATCH 127/497] Update specification/client_server_api.rst Co-Authored-By: Hubert Chathi --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index c18f4d03..a8246578 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1534,7 +1534,7 @@ same way a server does. .. NOTE:: Redacted events can still affect the state of the room. When redacted, - state events behave as though their properties were simply not specified + state events behave as though their properties were simply not specified, except those protected by the redaction algorithm. For example, a redacted ``join`` event will still result in the user being considered joined. Similarly, a redacted topic does not necessarily cause the topic to revert to From e2da3728a0631f95bae08f7ceb4a18b695841d3b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 12:53:48 -0600 Subject: [PATCH 128/497] Only error if the token doesn't match --- specification/application_service_api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 81077bcf..3220df2d 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -193,7 +193,8 @@ Authorization Homeservers MUST include a query parameter named ``access_token`` containing the ``hs_token`` from the application service's registration when making requests to the application service. Application services MUST verify the provided ``access_token`` -matches their known ``hs_token``, failing the request with a ``M_FORBIDDEN`` error. +matches their known ``hs_token``, failing the request with a ``M_FORBIDDEN`` error +if it does not match. Legacy routes +++++++++++++ From 3ade2a9ae78406c2804d57f4dbda09e0655bcb41 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 13:56:25 -0600 Subject: [PATCH 129/497] List the endpoints which support LL --- specification/client_server_api.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index a4b8dd5c..740023fb 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1300,6 +1300,11 @@ as the current membership event for a user. request to ``/sync`` followed by a request to ``/messages`` may result in a future call to ``/sync`` excluding members included by the ``/messages`` call. +The current endpoints which support lazy-loading room members are: + +* |/sync|_ +* |/rooms//messages|_ +* |/rooms/{roomId}/context/{eventId}|_ {{filter_cs_http_api}} From 551806a8ad797895a53f4555a252f1d59048ae43 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 13:54:22 -0600 Subject: [PATCH 130/497] Add a reference to the filtering module to /sync --- api/client-server/sync.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 2c504295..a9f1f714 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -53,6 +53,8 @@ paths: requests. Creating a filter using the filter API is recommended for clients that reuse the same filter multiple times, for example in long poll requests. + + See `Filtering <#filtering>`_ for more information. x-example: "66696p746572" - in: query name: since From c5fdd5cb0bef008945cde2e915245ade190541c5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 13:55:37 -0600 Subject: [PATCH 131/497] Change note style --- api/client-server/event_context.yaml | 2 +- api/client-server/message_pagination.yaml | 2 +- api/client-server/sync.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index c0f391e5..327c8f43 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -35,7 +35,7 @@ paths: after the specified event. This allows clients to get the context surrounding an event. - *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ + *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_ for more information. operationId: getEventContext security: diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 716afb65..8469eec4 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -34,7 +34,7 @@ paths: This API returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room. - *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ + *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_ for more information. operationId: getRoomEvents security: diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index a9f1f714..4fe22d50 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -35,7 +35,7 @@ paths: of the state on the server, and then continue to call this API to get incremental deltas to the state, and to receive new messages. - *Note*: this endpoint supports lazy-loading. See `Filtering <#filtering>`_ + *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_ for more information. Lazy-loading members is only supported on a ``StateFilter`` for this endpoint. operationId: sync From 0463084924543ee5b024adb62ac32ee5339855c5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 May 2019 14:19:56 -0600 Subject: [PATCH 132/497] Spec 3PID unbind API As per [MSC1915](https://github.com/matrix-org/matrix-doc/pull/1915) Implementation proof: * https://github.com/matrix-org/synapse/pull/4982 * https://github.com/matrix-org/sydent/pull/160 The only alteration made which differs from the proposal is clarity on how to handle homeservers not knowing the `id_server`. All other differences are unintentional. --- api/client-server/administrative_contact.yaml | 27 +++++- api/client-server/registration.yaml | 30 ++++++- api/identity/associations.yaml | 83 +++++++++++++++++++ .../client_server/newsfragments/2046.feature | 1 + .../identity_service/newsfragments/2046.new | 1 + .../1915-unbind-identity-server-param.md | 4 +- 6 files changed, 142 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2046.feature create mode 100644 changelogs/identity_service/newsfragments/2046.new diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 33ea9786..5cf01805 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -163,6 +163,14 @@ paths: schema: type: object properties: + id_server: + type: string + description: |- + The identity server to unbind from. If not provided, the homeserver + MUST use the ``id_server`` the identifier was added through. If the + homeserver does not know the original ``id_server``, it MUST return + a ``id_server_unbind_result`` of ``no-support``. + example: "example.org" medium: type: string description: The medium of the third party identifier being removed. @@ -180,7 +188,24 @@ paths: user. schema: type: object - properties: {} + properties: + id_server_unbind_result: + type: string + enum: + # XXX: I don't know why, but the order matters here so that "no-support" + # doesn't become "no- support" by the renderer. + - "no-support" + - "success" + description: |- + An indicator as to whether or not the homeserver was able to unbind + the 3PID from the identity server. ``success`` indicates that the + indentity server has unbound the identifier whereas ``no-support`` + indicates that the identity server refuses to support the request + or the homeserver was not able to determine an identity server to + unbind from. + example: "success" + required: + - id_server_unbind_result tags: - User data "/account/3pid/email/requestToken": diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 3195ab41..f003cf1f 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -524,13 +524,39 @@ paths: description: |- Additional authentication information for the user-interactive authentication API. "$ref": "definitions/auth_data.yaml" + id_server: + type: string + description: |- + The identity server to unbind all of the user's 3PIDs from. + If not provided, the homeserver MUST use the ``id_server`` + that was originally use to bind each identifier. If the + homeserver does not know which ``id_server`` that was, + it must return an ``id_server_unbind_result`` of + ``no-support``. + example: "example.org" responses: 200: description: The account has been deactivated. - examples: - application/json: {} schema: type: object + properties: + id_server_unbind_result: + type: string + enum: + - "success" + - "no-support" + description: |- + An indicator as to whether or not the homeserver was able to unbind + the user's 3PIDs from the identity server(s). ``success`` indicates + that all identifiers have been unbound from the identity server while + ``no-support`` indicates that one or more identifiers failed to unbind + due to the identity server refusing the request or the homeserver + being unable to determine an identity server to unbind from. This + must be ``success`` if the homeserver has no identifiers to unbind + for the user. + example: "success" + required: + - id_server_unbind_result 401: description: |- The homeserver requires additional authentication information. diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index 152a0a9b..f44fe3cc 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -201,3 +201,86 @@ paths: } schema: $ref: "../client-server/definitions/errors/error.yaml" + "/3pid/unbind": + post: + summary: Remove an association between a session and a Matrix user ID. + description: |- + Remove an association between a session and a Matrix user ID. + + Future calls to ``/lookup`` for any of the session's 3pids will not + return the removed association. + + The identity server should authenticate the request in one of two + ways: + + 1. The request is signed by the homeserver which controls the ``user_id``. + 2. The request includes the ``sid`` and ``client_secret`` parameters, + as per ``/3pid/bind``, which proves ownership of the 3PID. + + If this endpoint returns a JSON Matrix error, that error should be passed + through to the client requesting an unbind through a homeserver, if the + homeserver is acting on behalf of a client. + operationId: unbind + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:example.org", + "threepid": { + "medium": "email", + "address": "monkeys_have_ears@example.org" + } + } + properties: + sid: + type: string + description: The Session ID generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret passed to the ``requestToken`` call. + mxid: + type: string + description: The Matrix user ID to remove from the 3pids. + threepid: + type: object + title: 3PID + description: |- + The 3PID to remove. Must match the 3PID used to generate the session + if using ``sid`` and ``client_secret`` to authenticate this request. + properties: + medium: + type: string + description: |- + A medium from the `3PID Types`_ Appendix, matching the medium + of the identifier to unbind. + address: + type: string + description: The 3PID address to remove. + required: ['medium', 'address'] + required: ["threepid", "mxid"] + responses: + 200: + description: The association was successfully removed. + examples: + application/json: {} + schema: + type: object + 400: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 404: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 501: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. diff --git a/changelogs/client_server/newsfragments/2046.feature b/changelogs/client_server/newsfragments/2046.feature new file mode 100644 index 00000000..e54df535 --- /dev/null +++ b/changelogs/client_server/newsfragments/2046.feature @@ -0,0 +1 @@ +Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server. diff --git a/changelogs/identity_service/newsfragments/2046.new b/changelogs/identity_service/newsfragments/2046.new new file mode 100644 index 00000000..7146799b --- /dev/null +++ b/changelogs/identity_service/newsfragments/2046.new @@ -0,0 +1 @@ +Add ``/3pid/unbind`` for removing 3PIDs. diff --git a/proposals/1915-unbind-identity-server-param.md b/proposals/1915-unbind-identity-server-param.md index 6817ece3..5b7a1a50 100644 --- a/proposals/1915-unbind-identity-server-param.md +++ b/proposals/1915-unbind-identity-server-param.md @@ -27,7 +27,9 @@ known by the homeserver). The 200 response is a JSON object with an `id_server_unbind_result` field whose value is either `success` or `no-support`, where the latter indicates that the identity server (IS) does not support unbinding 3PIDs directly. If the identity -server returns an error then that should be returned to the client. +server returns an error then that should be returned to the client. If the homeserver +is unable to determine an `id_server` to use, it should return `no-support` for +the `id_server_unbind_result`. Example: From 84f0d9d7e4467460a9caf9128cd739ddd2fb03b6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 28 May 2019 20:07:45 -0400 Subject: [PATCH 133/497] add clarification --- proposals/1717-key_verification.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 6c9e2341..429e3a97 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -139,7 +139,8 @@ Properties: device, an `m.key.verification.cancel` message with `code` set to `m.accepted` is sent to the other devices - `reason` (string): human-readable reason for cancelling. This should only be - used if the recieving client does not understand the code given. + used if the recieving client does not understand the code given in the `code` + property. Verification methods may define their own additional cancellation codes. Cancellation codes defined in the Matrix spec will begin with `m.`; other From 6706d772c91be7c4ab5c8089f4579695e461ffd4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 00:46:00 -0600 Subject: [PATCH 134/497] Fix test vectors with invalid JSON and signature Fixes https://github.com/matrix-org/matrix-doc/issues/2023 The content hashes appear correct, however applying the algorithm defined in the spec never resulted in the signatures previously demonstrated. --- specification/appendices/test_vectors.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/appendices/test_vectors.rst b/specification/appendices/test_vectors.rst index e2b8fb58..7759fa88 100644 --- a/specification/appendices/test_vectors.rst +++ b/specification/appendices/test_vectors.rst @@ -114,7 +114,7 @@ The event signing algorithm should emit the following signed event: "origin_server_ts": 1000000, "signatures": { "domain": { - "ed25519:1": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA" + "ed25519:1": "JV2dlZUASAefSdywnyCxzykHlyr7xkKGK7IRir1cF8eYsnONrCSb+GRn7aXXstr1UHKvzYjRXPx0001+boD1Ag" } }, "type": "X", @@ -129,7 +129,7 @@ Given the following event containing redactable content: { "content": { - "body": "Here is the message content", + "body": "Here is the message content" }, "event_id": "$0:domain", "origin": "domain", @@ -149,7 +149,7 @@ The event signing algorithm should emit the following signed event: { "content": { - "body": "Here is the message content", + "body": "Here is the message content" }, "event_id": "$0:domain", "hashes": { @@ -162,7 +162,7 @@ The event signing algorithm should emit the following signed event: "sender": "@u:domain", "signatures": { "domain": { - "ed25519:1": "Wm+VzmOUOz08Ds+0NTWb1d4CZrVsJSikkeRxh6aCcUwu6pNC78FunoD7KNWzqFn241eYHYMGCA5McEiVPdhzBA" + "ed25519:1": "4zc79tH2cU6Y+eg4YbbF7KiDOrnwEDjlhTqIKiH4k7L9zD9XCiomD7x9odL9eEwnyy1144QyMBe8O3HK++GHBg" } }, "unsigned": { From ffb70a2fabd46f5197cf123d6ed8bcd5d613566d Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 29 May 2019 15:01:35 -0400 Subject: [PATCH 135/497] fix typo Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/1719-olm_unwedging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index c181e3f7..5de6463f 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -19,7 +19,7 @@ from; the client should not create a new session with another device if it has already created one for that given device in the past 1 hour. Clients may wish to ask the sender of the undecryptable messages to re-send the -message. For exampe, if the undecryptable message was a megolm session, then +message. For example, if the undecryptable message was a megolm session, then the client can send an [`m.room_key_request`](https://matrix.org/docs/spec/client_server/r0.4.0.html#m-room-key-request) message to request that the sender re-send the key. From 6929579360113e4e653e884f7e4cb5bfa68fbbd7 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 29 May 2019 15:18:54 -0400 Subject: [PATCH 136/497] add some clarifications --- proposals/1719-olm_unwedging.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/proposals/1719-olm_unwedging.md b/proposals/1719-olm_unwedging.md index 5de6463f..dffdc8b1 100644 --- a/proposals/1719-olm_unwedging.md +++ b/proposals/1719-olm_unwedging.md @@ -1,8 +1,13 @@ # Olm unwedging Olm sessions sometimes get out of sync, resulting in undecryptable messages. -This proposal documents a method for devices to create a new session to replace -the broken session. +This can happen for several reasons. For example, if a user restores their +client state from a backup, the client will be using an old ratchet state +([riot-web#3822](https://github.com/vector-im/riot-web/issues/3822)). Or a +client might expire a one-time key that another client is trying to use +([riot-web#3309](https://github.com/vector-im/riot-web/issues/3309)). This +proposal documents a method for devices to create a new session to replace the +broken session. ## Proposal @@ -18,11 +23,11 @@ the number of new sessions it creates per device that it receives a message from; the client should not create a new session with another device if it has already created one for that given device in the past 1 hour. -Clients may wish to ask the sender of the undecryptable messages to re-send the -message. For example, if the undecryptable message was a megolm session, then -the client can send an -[`m.room_key_request`](https://matrix.org/docs/spec/client_server/r0.4.0.html#m-room-key-request) -message to request that the sender re-send the key. +Clients may wish to take steps to mitigate the loss of the undecryptable +messages. For example, megolm sessions that were sent using the old session +would have been lost, so the client can send +[`m.room_key_request`](https://matrix.org/docs/spec/client_server/latest.html#m-room-key-request) +messages to re-request any megolm sessions that it is unable to decrypt. The spec currently says, "If a client has multiple sessions established with another device, it should use the session from which it last received a From 15b8011f63a687bc8961c881c1dcb73fd4318c6b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 13:37:58 -0600 Subject: [PATCH 137/497] Add missing aesthetic parameters to /store-invite Fixes https://github.com/matrix-org/matrix-doc/issues/2048 --- api/identity/store_invite.yaml | 47 ++++++++++++++++--- .../newsfragments/2049.clarification | 1 + 2 files changed, 42 insertions(+), 6 deletions(-) create mode 100644 changelogs/identity_service/newsfragments/2049.clarification diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 69103294..bca78d7e 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -50,31 +50,66 @@ paths: requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. Currently, invites may only be issued for 3pids of the ``email`` medium. + + Optional fields in the request should be populated to the best of the + server's ability. Identity servers may use these variables when notifying + the ``address`` of the pending invite for display purposes. operationId: storeInvite parameters: - in: body name: body schema: type: object - example: { - "medium": "email", - "address": "foo@bar.baz", - "room_id": "!something:example.tld", - "sender": "@bob:example.com" - } properties: medium: type: string description: The literal string ``email``. + example: "email" address: type: string description: The email address of the invited user. + example: "foo@example.com" room_id: type: string description: The Matrix room ID to which the user is invited + example: "!something:example.org" sender: type: string description: The Matrix user ID of the inviting user + example: "@bob:example.com" + room_alias: + type: string + description: |- + The Matrix room alias for the room to which the user is + invited. This should be retrieved from the ``m.room.canonical_alias`` + state event. + example: "#somewhere:exmaple.org" + room_avatar_url: + type: string + description: |- + The Content URI for the room to which the user is invited. This should + be retrieved from the ``m.room.avatar`` state event. + example: "mxc://example.org/s0meM3dia" + room_join_rules: + type: string + description: |- + The ``join_rule`` for the room to which the user is invited. This should + be retrieved from the ``m.room.join_rules`` state event. + example: "public" + room_name: + type: string + description: |- + The name of the room to which the user is invited. This should be retrieved + from the ``m.room.name`` state event. + example: "Bob's Emporium of Messages" + sender_display_name: + type: string + description: The display name of the user ID initiating the invite. + example: "Bob Smith" + sender_avatar_url: + type: string + description: The Content URI for the avatar of the user ID initiating the invite. + example: "mxc://example.org/an0th3rM3dia" required: ["medium", "address", "room_id", "sender"] responses: 200: diff --git a/changelogs/identity_service/newsfragments/2049.clarification b/changelogs/identity_service/newsfragments/2049.clarification new file mode 100644 index 00000000..403ac8d0 --- /dev/null +++ b/changelogs/identity_service/newsfragments/2049.clarification @@ -0,0 +1 @@ +Add missing aesthetic parameters to ``/store-invite``. From 78d93432f4cf3fde1cb11af37b95fe16b46bbe0c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 14:00:34 -0600 Subject: [PATCH 138/497] Synchronize proposals_intro.rst and CONTRIBUTING.rst --- CONTRIBUTING.rst | 28 +++++++++++++++------------- specification/proposals_intro.rst | 26 +++++++++++++++++--------- 2 files changed, 32 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7a6c6be2..0b814fb9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a server before they can be documented in the specification. This process can take some time to complete. -For this reason, we have not found the github pull-request model effective for -discussing changes to the specification. Instead, we have adopted the workflow -as described at https://matrix.org/docs/spec/proposals - *please read this for -details on how to contribute spec changes*. +Changes to the protocol (new endpoints, ideas, etc) need to go through the +`proposals process `_. Other changes, +such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal. +If you're not sure, visit us at `#matrix-spec:matrix.org`_ +and ask. Other changes @@ -51,8 +52,7 @@ following: `_ label. (If there is any doubt about whether it is the spec or the implementations - that need fixing, please discuss it with us first in `#matrix-dev:matrix.org - `_.) + that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.) * Clarifications to the specification which do not change the behaviour of Matrix servers or clients in a way which might introduce compatibility @@ -60,14 +60,16 @@ following: `clarification `_ label. - For example, recommendations for UI behaviour do not require a proposal - document. On the other hand, changes to event contents would be best - discussed in a proposal document even though no changes would be necessary to - server implementations. + For example, areas where the specification is unclear do not require a proposal + to fix. On the other hand, introducing new behaviour is best represented by a + proposal. -For such changes, please do just open a `pull request`_. +For such changes, please do just open a `pull request`_. If you're not sure if +your change is covered by the above, please visit `#matrix-spec:matrix.org` and +ask. -.. _pull request: https://help.github.com/articles/about-pull-requests +.. _`pull request`: https://help.github.com/articles/about-pull-requests +.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org Adding to the changelog @@ -96,7 +98,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following: * ``breaking`` - Used when the change is not backwards compatible. -* ``deprecation`` - Used when deprecating something +* ``deprecation`` - Used when deprecating something. All news fragments must have a brief summary explaining the change in the contents of the file. The summary must end in a full stop to be in line with diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index d95128b7..d492700e 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -13,12 +13,18 @@ Proposals for Spec Changes to Matrix If you are interested in submitting a change to the Matrix Specification, please take note of the following guidelines. -All changes to Specification content require a formal proposal process. This -involves writing a proposal, having it reviewed by everyone, having the -proposal being accepted, then actually having your ideas implemented as -committed changes to the `Specification repository +Most changes to the Specification require a formal proposal. Bug fixes, typos, +and clarifications to existing behaviour do not need proposals - see the +`contributing guide `_ +for more information on what does and does not need a proposal. + +The proposal process involves some technical writing, having it reviewed by +everyone, having the proposal being accepted, then actually having your ideas +implemented as committed changes to the `Specification repository `_. +.. TODO: Replace GH team link with https://matrix.org/foundation or something + Meet the `members of the Core Team `_, a group of individuals tasked with ensuring the spec process is as smooth and painless as @@ -33,14 +39,15 @@ Guiding Principles Proposals **must** act to the greater benefit of the entire Matrix ecosystem, rather than benefiting or privileging any single player or subset of players - -and must not contain any patent encumbered intellectual property. Members of the Core Team pledge to act as -a neutral custodian for Matrix on behalf of the whole ecosystem. +and must not contain any patent encumbered intellectual property. Members of +the Core Team pledge to act as a neutral custodian for Matrix on behalf of the +whole ecosystem. For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That includes client users, server admins, client developers, bot developers, -bridge and application service developers, users and admins who are indirectly using Matrix via -3rd party networks which happen to be bridged, server developers, room -moderators and admins, companies/projects building products or services on +bridge and application service developers, users and admins who are indirectly +using Matrix via 3rd party networks which happen to be bridged, server developers, +room moderators and admins, companies/projects building products or services on Matrix, spec contributors, translators, and those who created it in the first place. @@ -242,6 +249,7 @@ Spec PR Merged merged A proposal with Postponed proposal-postponed A proposal that is temporarily blocked or a feature that may not be useful currently but perhaps sometime in the future Closed proposal-closed A proposal which has been reviewed and deemed unsuitable for acceptance +Obsolete obsolete A proposal which has been made obsolete by another proposal or decision elsewhere. =============================== ============================= ==================================== From c25afa663ef619a82b4d7f93f96118974a59d4a0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 14:56:42 -0600 Subject: [PATCH 139/497] Use consistent event examples throughout the Client-Server API Fixes https://github.com/matrix-org/matrix-doc/issues/1968 --- api/client-server/event_context.yaml | 88 ++++-------- api/client-server/message_pagination.yaml | 39 +---- api/client-server/notifications.yaml | 11 +- api/client-server/old_sync.yaml | 136 ++---------------- api/client-server/peeking_events.yaml | 12 +- api/client-server/room_initial_sync.yaml | 89 +----------- api/client-server/rooms.yaml | 136 +++--------------- api/client-server/search.yaml | 13 +- api/client-server/sync.yaml | 44 ++---- .../newsfragments/2050.clarification | 1 + 10 files changed, 94 insertions(+), 475 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2050.clarification diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 91da3cf4..549902a0 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -101,65 +101,35 @@ paths: - "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml" examples: application/json: { - "end": "t29-57_2_0_2", - "events_after": [ - { - "age": 91911336, - "content": { - "body": "7", - "msgtype": "m.text" - }, - "event_id": "$14460306086CiUaL:localhost:8480", - "origin_server_ts": 1446030608551, - "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480", - "type": "m.room.message", - "sender": "@test:localhost:8480" - } - ], - "events_before": [ - { - "age": 91911903, - "content": { - "body": "5", - "msgtype": "m.text" - }, - "event_id": "$14460306074UYTlh:localhost:8480", - "origin_server_ts": 1446030607984, - "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480", - "type": "m.room.message", - "sender": "@test:localhost:8480" - } - ], - "start": "t27-54_2_0_2", - "state": [ - { - "age": 3123715284, - "content": { - "creator": "@test:localhost:8480" - }, - "event_id": "$14429988040dgQAE:localhost:8480", - "origin_server_ts": 1442998804603, - "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480", - "state_key": "", - "type": "m.room.create", - "sender": "@test:localhost:8480" - }, - { - "age": 2067105053, - "content": { - "avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto", - "displayname": "Bob2", - "membership": "join" - }, - "event_id": "$14440554144URDbf:localhost:8480", - "origin_server_ts": 1444055414834, - "replaces_state": "$14440552472PgiGk:localhost:8480", - "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480", - "state_key": "@test:localhost:8480", - "type": "m.room.member", - "sender": "@test:localhost:8480" - } - ] + "end": "t29-57_2_0_2", + "events_after": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" } + ], + "event": { + "event_id": "$f3h4d129462ha:example.com", + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.message#m.image" + }, + "events_before": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.message#m.file" + } + ], + "start": "t27-54_2_0_2", + "state": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.create" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.member" + } + ] + } tags: - Room participation diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 941e61fb..f29f1f23 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -114,43 +114,16 @@ paths: "end": "t47409-4357353_219380_26003_2265", "chunk": [ { - "origin_server_ts": 1444812213737, - "sender": "@alice:example.com", - "event_id": "$1444812213350496Caaaa:example.com", - "content": { - "body": "hello world", - "msgtype":"m.text" - }, - "room_id":"!Xq3620DUiqCaoxq:example.com", - "type":"m.room.message", - "age": 1042 + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" }, { - "origin_server_ts": 1444812194656 , - "sender": "@bob:example.com", - "event_id": "$1444812213350496Cbbbb:example.com", - "content": { - "body": "the world is big", - "msgtype":"m.text" - }, - "room_id":"!Xq3620DUiqCaoxq:example.com", - "type":"m.room.message", - "age": 20123 + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.name" }, { - "origin_server_ts": 1444812163990, - "sender": "@bob:example.com", - "event_id": "$1444812213350496Ccccc:example.com", - "content": { - "name": "New room name" - }, - "prev_content": { - "name": "Old room name" - }, - "state_key": "", - "room_id":"!Xq3620DUiqCaoxq:example.com", - "type":"m.room.name", - "age": 50789 + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.message#m.video" } ] } diff --git a/api/client-server/notifications.yaml b/api/client-server/notifications.yaml index b450885b..6d9366be 100644 --- a/api/client-server/notifications.yaml +++ b/api/client-server/notifications.yaml @@ -75,16 +75,7 @@ paths: "room_id": "!abcdefg:example.com", "ts": 1475508881945, "event": { - "sender": "@alice:example.com", - "type": "m.room.message", - "age": 124524, - "txn_id": "1234", - "content": { - "body": "I am a fish", - "msgtype": "m.text" - }, - "origin_server_ts": 1417731086797, - "event_id": "$74686972643033:example.com" + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" } } ] diff --git a/api/client-server/old_sync.yaml b/api/client-server/old_sync.yaml index c502c239..c9b7586b 100644 --- a/api/client-server/old_sync.yaml +++ b/api/client-server/old_sync.yaml @@ -64,18 +64,7 @@ paths: "start": "s3456_9_0", "end": "s3457_9_0", "chunk": [ - { - "age": 32, - "content": { - "body": "incoming message", - "msgtype": "m.text" - }, - "event_id": "$14328055551tzaee:localhost", - "origin_server_ts": 1432804485886, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "type": "m.room.message", - "sender": "@bob:localhost" - } + {"$ref": "definitions/event-schemas/examples/m.room.message#m.text"} ] } schema: @@ -142,16 +131,7 @@ paths: application/json: { "end": "s3456_9_0", "presence": [ - { - "content": { - "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto", - "displayname": "Bob", - "last_active_ago": 31053, - "presence": "online", - "user_id": "@bob:localhost" - }, - "type": "m.presence" - } + {"$ref": "definitions/event-schemas/examples/m.presence"} ], "account_data": [ { @@ -167,28 +147,12 @@ paths: "messages": { "chunk": [ { - "age": 343513403, - "content": { - "body": "foo", - "msgtype": "m.text" - }, - "event_id": "$14328044851tzTJS:localhost", - "origin_server_ts": 1432804485886, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "type": "m.room.message", - "sender": "@alice:localhost" + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" }, { - "age": 343511809, - "content": { - "body": "bar", - "msgtype": "m.text" - }, - "event_id": "$14328044872spjFg:localhost", - "origin_server_ts": 1432804487480, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "type": "m.room.message", - "sender": "@bob:localhost" + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "definitions/event-schemas/examples/m.room.message#m.video" } ], "end": "s3456_9_0", @@ -197,81 +161,20 @@ paths: "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state": [ { - "age": 7148266897, - "content": { - "join_rule": "public" - }, - "event_id": "$14259997323TLwtb:localhost", - "origin_server_ts": 1425999732392, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "state_key": "", - "type": "m.room.join_rules", - "sender": "@alice:localhost" + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "definitions/event-schemas/examples/m.room.join_rules" }, { - "age": 6547561012, - "content": { - "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto", - "membership": "join" - }, - "event_id": "$1426600438280zExKY:localhost", - "membership": "join", - "origin_server_ts": 1426600438277, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "state_key": "@alice:localhost", - "type": "m.room.member", - "sender": "@alice:localhost" + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "definitions/event-schemas/examples/m.room.member" }, { - "age": 7148267200, - "content": { - "creator": "@alice:localhost" - }, - "event_id": "$14259997320KhbwJ:localhost", - "origin_server_ts": 1425999732089, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "state_key": "", - "type": "m.room.create", - "sender": "@alice:localhost" + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "definitions/event-schemas/examples/m.room.create" }, { - "age": 1622568720, - "content": { - "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto", - "displayname": "Bob", - "membership": "join" - }, - "event_id": "$1431525430134MxlLX:localhost", - "origin_server_ts": 1431525430569, - "replaces_state": "$142652023736BSXcM:localhost", - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "state_key": "@bob:localhost", - "type": "m.room.member", - "sender": "@bob:localhost" - }, - { - "age": 7148267004, - "content": { - "ban": 50, - "events": { - "m.room.name": 100, - "m.room.power_levels": 100 - }, - "events_default": 0, - "kick": 50, - "redact": 50, - "state_default": 50, - "users": { - "@alice:localhost": 100 - }, - "users_default": 0 - }, - "event_id": "$14259997322mqfaq:localhost", - "origin_server_ts": 1425999732285, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "state_key": "", - "type": "m.room.power_levels", - "sender": "@alice:localhost" + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "definitions/event-schemas/examples/m.room.power_levels" } ], "visibility": "private", @@ -423,16 +326,7 @@ paths: 200: description: The full event. examples: - application/json: { - "content": { - "body": "Hello world!", - "msgtype": "m.text" - }, - "room_id": "!wfgy43Sg4a:matrix.org", - "sender": "@bob:matrix.org", - "event_id": "$asfDuShaf7Gafaw:matrix.org", - "type": "m.room.message" - } + application/json: {"$ref": "definitions/event-schemas/examples/m.room.message#m.text"} schema: allOf: - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml" diff --git a/api/client-server/peeking_events.yaml b/api/client-server/peeking_events.yaml index 2f66bae7..e3dc5777 100644 --- a/api/client-server/peeking_events.yaml +++ b/api/client-server/peeking_events.yaml @@ -75,16 +75,8 @@ paths: "end": "s3457_9_0", "chunk": [ { - "age": 32, - "content": { - "body": "incoming message", - "msgtype": "m.text" - }, - "event_id": "$14328055551tzaee:localhost", - "origin_server_ts": 1432804485886, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "type": "m.room.message", - "sender": "@bob:localhost" + "room_id": "!somewhere:over.the.rainbow", + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" } ] } diff --git a/api/client-server/room_initial_sync.yaml b/api/client-server/room_initial_sync.yaml index c27f0f24..2a354fc0 100644 --- a/api/client-server/room_initial_sync.yaml +++ b/api/client-server/room_initial_sync.yaml @@ -43,28 +43,12 @@ paths: "messages": { "chunk": [ { - "age": 343513403, - "content": { - "body": "foo", - "msgtype": "m.text" - }, - "event_id": "$14328044851tzTJS:example.com", - "origin_server_ts": 1432804485886, "room_id": "!636q39766251:example.com", - "type": "m.room.message", - "sender": "@alice:example.com" + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" }, { - "age": 343511809, - "content": { - "body": "bar", - "msgtype": "m.text" - }, - "event_id": "$14328044872spjFg:example.com", - "origin_server_ts": 1432804487480, "room_id": "!636q39766251:example.com", - "type": "m.room.message", - "sender": "@bob:example.com" + "$ref": "definitions/event-schemas/examples/m.room.message#m.file" } ], "end": "s3456_9_0", @@ -73,81 +57,20 @@ paths: "room_id": "!636q39766251:example.com", "state": [ { - "age": 7148266897, - "content": { - "join_rule": "public" - }, - "event_id": "$14259997323TLwtb:example.com", - "origin_server_ts": 1425999732392, "room_id": "!636q39766251:example.com", - "state_key": "", - "type": "m.room.join_rules", - "sender": "@alice:example.com" + "$ref": "definitions/event-schemas/examples/m.room.join_rules" }, { - "age": 6547561012, - "content": { - "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", - "membership": "join" - }, - "event_id": "$1426600438280zExKY:example.com", - "membership": "join", - "origin_server_ts": 1426600438277, "room_id": "!636q39766251:example.com", - "state_key": "@alice:example.com", - "type": "m.room.member", - "sender": "@alice:example.com" + "$ref": "definitions/event-schemas/examples/m.room.member" }, { - "age": 7148267200, - "content": { - "creator": "@alice:example.com" - }, - "event_id": "$14259997320KhbwJ:example.com", - "origin_server_ts": 1425999732089, "room_id": "!636q39766251:example.com", - "state_key": "", - "type": "m.room.create", - "sender": "@alice:example.com" + "$ref": "definitions/event-schemas/examples/m.room.create" }, { - "age": 1622568720, - "content": { - "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto", - "displayname": "Bob", - "membership": "join" - }, - "event_id": "$1431525430134MxlLX:example.com", - "origin_server_ts": 1431525430569, - "replaces_state": "$142652023736BSXcM:example.com", "room_id": "!636q39766251:example.com", - "state_key": "@bob:example.com", - "type": "m.room.member", - "sender": "@bob:example.com" - }, - { - "age": 7148267004, - "content": { - "ban": 50, - "events": { - "m.room.name": 100, - "m.room.power_levels": 100 - }, - "events_default": 0, - "kick": 50, - "redact": 50, - "state_default": 50, - "users": { - "@alice:example.com": 100 - }, - "users_default": 0 - }, - "event_id": "$14259997322mqfaq:example.com", - "origin_server_ts": 1425999732285, - "room_id": "!636q39766251:example.com", - "state_key": "", - "type": "m.room.power_levels", - "sender": "@alice:example.com" + "$ref": "definitions/event-schemas/examples/m.room.power_levels" } ], "visibility": "private", diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index cc1f2bf7..55456436 100644 --- a/api/client-server/rooms.yaml +++ b/api/client-server/rooms.yaml @@ -42,7 +42,7 @@ paths: name: roomId description: The ID of the room the event is in. required: true - x-example: "!asfDuShaf7Gafaw:matrix.org" + x-example: "!636q39766251:matrix.org" - in: path type: string name: eventId @@ -54,15 +54,9 @@ paths: description: The full event. examples: application/json: { - "content": { - "body": "Hello world!", - "msgtype": "m.text" - }, - "room_id": "!wfgy43Sg4a:matrix.org", - "sender": "@bob:matrix.org", - "event_id": "$asfDuShaf7Gafaw:matrix.org", - "type": "m.room.message" - } + "room_id": "!636q39766251:matrix.org", + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + } schema: allOf: - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml" @@ -178,84 +172,23 @@ paths: description: The current state of the room examples: application/json: [ - { - "age": 7148266897, - "content": { - "join_rule": "public" - }, - "event_id": "$14259997323TLwtb:example.com", - "origin_server_ts": 1425999732392, - "room_id": "!636q39766251:example.com", - "state_key": "", - "type": "m.room.join_rules", - "sender": "@alice:example.com" - }, - { - "age": 6547561012, - "content": { - "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", - "membership": "join" - }, - "event_id": "$1426600438280zExKY:example.com", - "membership": "join", - "origin_server_ts": 1426600438277, - "room_id": "!636q39766251:example.com", - "state_key": "@alice:example.com", - "type": "m.room.member", - "sender": "@alice:example.com" - }, - { - "age": 7148267200, - "content": { - "creator": "@alice:example.com" - }, - "event_id": "$14259997320KhbwJ:example.com", - "origin_server_ts": 1425999732089, - "room_id": "!636q39766251:example.com", - "state_key": "", - "type": "m.room.create", - "sender": "@alice:example.com" - }, - { - "age": 1622568720, - "content": { - "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto", - "displayname": "Bob", - "membership": "join" - }, - "event_id": "$1431525430134MxlLX:example.com", - "origin_server_ts": 1431525430569, - "replaces_state": "$142652023736BSXcM:example.com", - "room_id": "!636q39766251:example.com", - "state_key": "@bob:example.com", - "type": "m.room.member", - "sender": "@bob:example.com" - }, - { - "age": 7148267004, - "content": { - "ban": 50, - "events": { - "m.room.name": 100, - "m.room.power_levels": 100 - }, - "events_default": 0, - "kick": 50, - "redact": 50, - "state_default": 50, - "users": { - "@alice:example.com": 100 - }, - "users_default": 0 - }, - "event_id": "$14259997322mqfaq:example.com", - "origin_server_ts": 1425999732285, - "room_id": "!636q39766251:example.com", - "state_key": "", - "type": "m.room.power_levels", - "sender": "@alice:example.com" - } - ] + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.join_rules" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.member" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.create" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "definitions/event-schemas/examples/m.room.power_levels" + } + ] schema: type: array title: RoomState @@ -300,33 +233,8 @@ paths: application/json: { "chunk": [ { - "age": 6547561012, - "content": { - "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto", - "membership": "join" - }, - "event_id": "$1426600438280zExKY:example.com", - "membership": "join", - "origin_server_ts": 1426600438277, "room_id": "!636q39766251:example.com", - "state_key": "@alice:example.com", - "type": "m.room.member", - "sender": "@alice:example.com" - }, - { - "age": 1622568720, - "content": { - "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto", - "displayname": "Bob", - "membership": "join" - }, - "event_id": "$1431525430134MxlLX:example.com", - "origin_server_ts": 1431525430569, - "replaces_state": "$142652023736BSXcM:example.com", - "room_id": "!636q39766251:example.com", - "state_key": "@bob:example.com", - "type": "m.room.member", - "sender": "@bob:example.com" + "$ref": "definitions/event-schemas/examples/m.room.member" } ] } diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 4a5f4515..9d5d2074 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -280,7 +280,7 @@ paths: Any groups that were requested. The outer ``string`` key is the group key requested (eg: ``room_id`` - or ``sender``). The inner ``string`` key is the grouped value (eg: + or ``sender``). The inner ``string`` key is the grouped value (eg: a room's ID or a user's ID). additionalProperties: type: object @@ -347,16 +347,9 @@ paths: { "rank": 0.00424866, "result": { - "age": 526228296, - "content": { - "body": "Test content martians and men", - "msgtype": "m.text" - }, - "event_id": "$144429830826TWwbB:localhost", - "origin_server_ts": 1444298308034, "room_id": "!qPewotXpIctQySfjSy:localhost", - "type": "m.room.message", - "sender": "@test:localhost" + "event_id": "$144429830826TWwbB:localhost", + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" } } ] diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index f204152a..ad5a6075 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -310,11 +310,7 @@ paths: "next_batch": "s72595_4483_1934", "presence": { "events": [ - { - "sender": "@alice:example.com", - "type": "m.presence", - "content": {"presence": "online"} - } + {"$ref": "definitions/event-schemas/examples/m.presence"} ] }, "account_data": { @@ -333,36 +329,20 @@ paths: "state": { "events": [ { - "sender": "@alice:example.com", - "type": "m.room.member", - "state_key": "@alice:example.com", - "content": {"membership": "join"}, - "origin_server_ts": 1417731086795, - "event_id": "$66697273743031:example.com" + "room_id": "!726s6s6q:example.com", + "$ref": "definitions/event-schemas/examples/m.room.member" } ] }, "timeline": { "events": [ { - "sender": "@bob:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "join"}, - "prev_content": {"membership": "invite"}, - "origin_server_ts": 1417731086795, - "event_id": "$7365636s6r6432:example.com" + "room_id": "!726s6s6q:example.com", + "$ref": "definitions/event-schemas/examples/m.room.member" }, { - "sender": "@alice:example.com", - "type": "m.room.message", - "txn_id": "1234", - "content": { - "body": "I am a fish", - "msgtype": "m.text" - }, - "origin_server_ts": 1417731086797, - "event_id": "$74686972643033:example.com" + "room_id": "!726s6s6q:example.com", + "$ref": "definitions/event-schemas/examples/m.room.message#m.text" } ], "limited": true, @@ -370,18 +350,12 @@ paths: }, "ephemeral": { "events": [ - { - "type": "m.typing", - "content": {"user_ids": ["@alice:example.com"]} - } + {"$ref": "definitions/event-schemas/examples/m.typing"} ] }, "account_data": { "events": [ - { - "type": "m.tag", - "content": {"tags": {"work": {"order": 1}}} - }, + {"$ref": "definitions/event-schemas/examples/m.tag"}, { "type": "org.example.custom.room.config", "content": { diff --git a/changelogs/client_server/newsfragments/2050.clarification b/changelogs/client_server/newsfragments/2050.clarification new file mode 100644 index 00000000..384daa11 --- /dev/null +++ b/changelogs/client_server/newsfragments/2050.clarification @@ -0,0 +1 @@ +Use consistent examples of events throughout the specification. From d6d74c4cbef04e194826cf3565b21bf5959a7d31 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 15:23:45 -0600 Subject: [PATCH 140/497] Switch to using $ instead of # for sub-types # is reserved by the swagger validator as a way to include partial content from a JSON object (eg: "#/path" would include {"test": true} from the object {"path":{"test":true}}). Instead of trying to convince the validator that it is wrong, we'll just use a different character. Note that our rendering tools do not care about #-style references to objects. It's still somewhat worth changing the character though. --- api/application-service/transactions.yaml | 2 +- api/client-server/event_context.yaml | 6 +++--- api/client-server/message_pagination.yaml | 4 ++-- api/client-server/notifications.yaml | 2 +- api/client-server/old_sync.yaml | 8 ++++---- api/client-server/peeking_events.yaml | 2 +- api/client-server/room_initial_sync.yaml | 4 ++-- api/client-server/rooms.yaml | 2 +- api/client-server/search.yaml | 2 +- api/client-server/sync.yaml | 2 +- event-schemas/check_examples.py | 4 ++-- ....encrypted#megolm => m.room.encrypted$megolm} | 0 ...m.room.encrypted#olm => m.room.encrypted$olm} | 0 ...oom_state => m.room.member$invite_room_state} | 0 ...y_invite => m.room.member$third_party_invite} | 0 ...om.message#m.audio => m.room.message$m.audio} | 2 +- ...om.message#m.emote => m.room.message$m.emote} | 0 ...room.message#m.file => m.room.message$m.file} | 0 ...om.message#m.image => m.room.message$m.image} | 0 ...sage#m.location => m.room.message$m.location} | 0 ....message#m.notice => m.room.message$m.notice} | 0 ...ver_notice => m.room.message$m.server_notice} | 0 ...room.message#m.text => m.room.message$m.text} | 0 ...om.message#m.video => m.room.message$m.video} | 0 ...request => m.room_key_request$cancel_request} | 0 ...equest#request => m.room_key_request$request} | 0 ...om.message#m.audio => m.room.message$m.audio} | 0 ...om.message#m.emote => m.room.message$m.emote} | 0 ...room.message#m.file => m.room.message$m.file} | 0 ...om.message#m.image => m.room.message$m.image} | 0 ...sage#m.location => m.room.message$m.location} | 0 ....message#m.notice => m.room.message$m.notice} | 0 ...ver_notice => m.room.message$m.server_notice} | 0 ...room.message#m.text => m.room.message$m.text} | 0 ...om.message#m.video => m.room.message$m.video} | 0 scripts/templating/matrix_templates/sections.py | 16 ++++++++-------- scripts/templating/matrix_templates/units.py | 2 +- 37 files changed, 29 insertions(+), 29 deletions(-) rename event-schemas/examples/{m.room.encrypted#megolm => m.room.encrypted$megolm} (100%) rename event-schemas/examples/{m.room.encrypted#olm => m.room.encrypted$olm} (100%) rename event-schemas/examples/{m.room.member#invite_room_state => m.room.member$invite_room_state} (100%) rename event-schemas/examples/{m.room.member#third_party_invite => m.room.member$third_party_invite} (100%) rename event-schemas/examples/{m.room.message#m.audio => m.room.message$m.audio} (99%) rename event-schemas/examples/{m.room.message#m.emote => m.room.message$m.emote} (100%) rename event-schemas/examples/{m.room.message#m.file => m.room.message$m.file} (100%) rename event-schemas/examples/{m.room.message#m.image => m.room.message$m.image} (100%) rename event-schemas/examples/{m.room.message#m.location => m.room.message$m.location} (100%) rename event-schemas/examples/{m.room.message#m.notice => m.room.message$m.notice} (100%) rename event-schemas/examples/{m.room.message#m.server_notice => m.room.message$m.server_notice} (100%) rename event-schemas/examples/{m.room.message#m.text => m.room.message$m.text} (100%) rename event-schemas/examples/{m.room.message#m.video => m.room.message$m.video} (100%) rename event-schemas/examples/{m.room_key_request#cancel_request => m.room_key_request$cancel_request} (100%) rename event-schemas/examples/{m.room_key_request#request => m.room_key_request$request} (100%) rename event-schemas/schema/{m.room.message#m.audio => m.room.message$m.audio} (100%) rename event-schemas/schema/{m.room.message#m.emote => m.room.message$m.emote} (100%) rename event-schemas/schema/{m.room.message#m.file => m.room.message$m.file} (100%) rename event-schemas/schema/{m.room.message#m.image => m.room.message$m.image} (100%) rename event-schemas/schema/{m.room.message#m.location => m.room.message$m.location} (100%) rename event-schemas/schema/{m.room.message#m.notice => m.room.message$m.notice} (100%) rename event-schemas/schema/{m.room.message#m.server_notice => m.room.message$m.server_notice} (100%) rename event-schemas/schema/{m.room.message#m.text => m.room.message$m.text} (100%) rename event-schemas/schema/{m.room.message#m.video => m.room.message$m.video} (100%) diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml index 98181196..09f15276 100644 --- a/api/application-service/transactions.yaml +++ b/api/application-service/transactions.yaml @@ -56,7 +56,7 @@ paths: example: { "events": [ {"$ref": "../../event-schemas/examples/m.room.member"}, - {"$ref": "../../event-schemas/examples/m.room.message#m.text"} + {"$ref": "../../event-schemas/examples/m.room.message$m.text"} ] } description: Transaction information diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 549902a0..e2018028 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -105,18 +105,18 @@ paths: "events_after": [ { "room_id": "!636q39766251:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" } ], "event": { "event_id": "$f3h4d129462ha:example.com", "room_id": "!636q39766251:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.image" + "$ref": "definitions/event-schemas/examples/m.room.message$m.image" }, "events_before": [ { "room_id": "!636q39766251:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.file" + "$ref": "definitions/event-schemas/examples/m.room.message$m.file" } ], "start": "t27-54_2_0_2", diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index f29f1f23..c9f9d0ae 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -115,7 +115,7 @@ paths: "chunk": [ { "room_id": "!636q39766251:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" }, { "room_id": "!636q39766251:example.com", @@ -123,7 +123,7 @@ paths: }, { "room_id": "!636q39766251:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.video" + "$ref": "definitions/event-schemas/examples/m.room.message$m.video" } ] } diff --git a/api/client-server/notifications.yaml b/api/client-server/notifications.yaml index 6d9366be..87341d41 100644 --- a/api/client-server/notifications.yaml +++ b/api/client-server/notifications.yaml @@ -75,7 +75,7 @@ paths: "room_id": "!abcdefg:example.com", "ts": 1475508881945, "event": { - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" } } ] diff --git a/api/client-server/old_sync.yaml b/api/client-server/old_sync.yaml index c9b7586b..a79c3b32 100644 --- a/api/client-server/old_sync.yaml +++ b/api/client-server/old_sync.yaml @@ -64,7 +64,7 @@ paths: "start": "s3456_9_0", "end": "s3457_9_0", "chunk": [ - {"$ref": "definitions/event-schemas/examples/m.room.message#m.text"} + {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"} ] } schema: @@ -148,11 +148,11 @@ paths: "chunk": [ { "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" }, { "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "definitions/event-schemas/examples/m.room.message#m.video" + "$ref": "definitions/event-schemas/examples/m.room.message$m.video" } ], "end": "s3456_9_0", @@ -326,7 +326,7 @@ paths: 200: description: The full event. examples: - application/json: {"$ref": "definitions/event-schemas/examples/m.room.message#m.text"} + application/json: {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"} schema: allOf: - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml" diff --git a/api/client-server/peeking_events.yaml b/api/client-server/peeking_events.yaml index e3dc5777..feac36f4 100644 --- a/api/client-server/peeking_events.yaml +++ b/api/client-server/peeking_events.yaml @@ -76,7 +76,7 @@ paths: "chunk": [ { "room_id": "!somewhere:over.the.rainbow", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" } ] } diff --git a/api/client-server/room_initial_sync.yaml b/api/client-server/room_initial_sync.yaml index 2a354fc0..72e56ba9 100644 --- a/api/client-server/room_initial_sync.yaml +++ b/api/client-server/room_initial_sync.yaml @@ -44,11 +44,11 @@ paths: "chunk": [ { "room_id": "!636q39766251:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" }, { "room_id": "!636q39766251:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.file" + "$ref": "definitions/event-schemas/examples/m.room.message$m.file" } ], "end": "s3456_9_0", diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index 55456436..377783c6 100644 --- a/api/client-server/rooms.yaml +++ b/api/client-server/rooms.yaml @@ -55,7 +55,7 @@ paths: examples: application/json: { "room_id": "!636q39766251:matrix.org", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" } schema: allOf: diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 9d5d2074..4fe72d5b 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -349,7 +349,7 @@ paths: "result": { "room_id": "!qPewotXpIctQySfjSy:localhost", "event_id": "$144429830826TWwbB:localhost", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" } } ] diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index ad5a6075..02fddb84 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -342,7 +342,7 @@ paths: }, { "room_id": "!726s6s6q:example.com", - "$ref": "definitions/event-schemas/examples/m.room.message#m.text" + "$ref": "definitions/event-schemas/examples/m.room.message$m.text" } ], "limited": true, diff --git a/event-schemas/check_examples.py b/event-schemas/check_examples.py index 3e536ec3..2baa3ef0 100755 --- a/event-schemas/check_examples.py +++ b/event-schemas/check_examples.py @@ -112,8 +112,8 @@ def check_example_dir(exampledir, schemadir): continue examplepath = os.path.join(root, filename) schemapath = examplepath.replace(exampledir, schemadir) - if schemapath.find("#") >= 0: - schemapath = schemapath[:schemapath.find("#")] + if schemapath.find("$") >= 0: + schemapath = schemapath[:schemapath.find("$")] try: check_example_file(examplepath, schemapath) except Exception as e: diff --git a/event-schemas/examples/m.room.encrypted#megolm b/event-schemas/examples/m.room.encrypted$megolm similarity index 100% rename from event-schemas/examples/m.room.encrypted#megolm rename to event-schemas/examples/m.room.encrypted$megolm diff --git a/event-schemas/examples/m.room.encrypted#olm b/event-schemas/examples/m.room.encrypted$olm similarity index 100% rename from event-schemas/examples/m.room.encrypted#olm rename to event-schemas/examples/m.room.encrypted$olm diff --git a/event-schemas/examples/m.room.member#invite_room_state b/event-schemas/examples/m.room.member$invite_room_state similarity index 100% rename from event-schemas/examples/m.room.member#invite_room_state rename to event-schemas/examples/m.room.member$invite_room_state diff --git a/event-schemas/examples/m.room.member#third_party_invite b/event-schemas/examples/m.room.member$third_party_invite similarity index 100% rename from event-schemas/examples/m.room.member#third_party_invite rename to event-schemas/examples/m.room.member$third_party_invite diff --git a/event-schemas/examples/m.room.message#m.audio b/event-schemas/examples/m.room.message$m.audio similarity index 99% rename from event-schemas/examples/m.room.message#m.audio rename to event-schemas/examples/m.room.message$m.audio index 2f743d49..58e874e0 100644 --- a/event-schemas/examples/m.room.message#m.audio +++ b/event-schemas/examples/m.room.message$m.audio @@ -11,4 +11,4 @@ }, "msgtype": "m.audio" } -} +} diff --git a/event-schemas/examples/m.room.message#m.emote b/event-schemas/examples/m.room.message$m.emote similarity index 100% rename from event-schemas/examples/m.room.message#m.emote rename to event-schemas/examples/m.room.message$m.emote diff --git a/event-schemas/examples/m.room.message#m.file b/event-schemas/examples/m.room.message$m.file similarity index 100% rename from event-schemas/examples/m.room.message#m.file rename to event-schemas/examples/m.room.message$m.file diff --git a/event-schemas/examples/m.room.message#m.image b/event-schemas/examples/m.room.message$m.image similarity index 100% rename from event-schemas/examples/m.room.message#m.image rename to event-schemas/examples/m.room.message$m.image diff --git a/event-schemas/examples/m.room.message#m.location b/event-schemas/examples/m.room.message$m.location similarity index 100% rename from event-schemas/examples/m.room.message#m.location rename to event-schemas/examples/m.room.message$m.location diff --git a/event-schemas/examples/m.room.message#m.notice b/event-schemas/examples/m.room.message$m.notice similarity index 100% rename from event-schemas/examples/m.room.message#m.notice rename to event-schemas/examples/m.room.message$m.notice diff --git a/event-schemas/examples/m.room.message#m.server_notice b/event-schemas/examples/m.room.message$m.server_notice similarity index 100% rename from event-schemas/examples/m.room.message#m.server_notice rename to event-schemas/examples/m.room.message$m.server_notice diff --git a/event-schemas/examples/m.room.message#m.text b/event-schemas/examples/m.room.message$m.text similarity index 100% rename from event-schemas/examples/m.room.message#m.text rename to event-schemas/examples/m.room.message$m.text diff --git a/event-schemas/examples/m.room.message#m.video b/event-schemas/examples/m.room.message$m.video similarity index 100% rename from event-schemas/examples/m.room.message#m.video rename to event-schemas/examples/m.room.message$m.video diff --git a/event-schemas/examples/m.room_key_request#cancel_request b/event-schemas/examples/m.room_key_request$cancel_request similarity index 100% rename from event-schemas/examples/m.room_key_request#cancel_request rename to event-schemas/examples/m.room_key_request$cancel_request diff --git a/event-schemas/examples/m.room_key_request#request b/event-schemas/examples/m.room_key_request$request similarity index 100% rename from event-schemas/examples/m.room_key_request#request rename to event-schemas/examples/m.room_key_request$request diff --git a/event-schemas/schema/m.room.message#m.audio b/event-schemas/schema/m.room.message$m.audio similarity index 100% rename from event-schemas/schema/m.room.message#m.audio rename to event-schemas/schema/m.room.message$m.audio diff --git a/event-schemas/schema/m.room.message#m.emote b/event-schemas/schema/m.room.message$m.emote similarity index 100% rename from event-schemas/schema/m.room.message#m.emote rename to event-schemas/schema/m.room.message$m.emote diff --git a/event-schemas/schema/m.room.message#m.file b/event-schemas/schema/m.room.message$m.file similarity index 100% rename from event-schemas/schema/m.room.message#m.file rename to event-schemas/schema/m.room.message$m.file diff --git a/event-schemas/schema/m.room.message#m.image b/event-schemas/schema/m.room.message$m.image similarity index 100% rename from event-schemas/schema/m.room.message#m.image rename to event-schemas/schema/m.room.message$m.image diff --git a/event-schemas/schema/m.room.message#m.location b/event-schemas/schema/m.room.message$m.location similarity index 100% rename from event-schemas/schema/m.room.message#m.location rename to event-schemas/schema/m.room.message$m.location diff --git a/event-schemas/schema/m.room.message#m.notice b/event-schemas/schema/m.room.message$m.notice similarity index 100% rename from event-schemas/schema/m.room.message#m.notice rename to event-schemas/schema/m.room.message$m.notice diff --git a/event-schemas/schema/m.room.message#m.server_notice b/event-schemas/schema/m.room.message$m.server_notice similarity index 100% rename from event-schemas/schema/m.room.message#m.server_notice rename to event-schemas/schema/m.room.message$m.server_notice diff --git a/event-schemas/schema/m.room.message#m.text b/event-schemas/schema/m.room.message$m.text similarity index 100% rename from event-schemas/schema/m.room.message#m.text rename to event-schemas/schema/m.room.message$m.text diff --git a/event-schemas/schema/m.room.message#m.video b/event-schemas/schema/m.room.message$m.video similarity index 100% rename from event-schemas/schema/m.room.message#m.video rename to event-schemas/schema/m.room.message$m.video diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 92afa5ff..c88959ed 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -115,7 +115,7 @@ class MatrixSections(Sections): schemas = self.units.get("event_schemas") renders = {} for event_type in schemas: - underscored_event_type = event_type.replace(".", "_").replace("#", "_") + underscored_event_type = event_type.replace(".", "_").replace("$", "_") renders[underscored_event_type + "_event"] = self._render_events( lambda x: x == event_type, sorted ) @@ -125,7 +125,7 @@ class MatrixSections(Sections): def filterFn(eventType): return ( eventType.startswith("m.room") and - not eventType.startswith("m.room.message#m.") + not eventType.startswith("m.room.message$m.") ) return self._render_events(filterFn, sorted) @@ -138,22 +138,22 @@ class MatrixSections(Sections): ]["subtitle"] sections = [] msgtype_order = [ - "m.room.message#m.text", "m.room.message#m.emote", - "m.room.message#m.notice", "m.room.message#m.image", - "m.room.message#m.file" + "m.room.message$m.text", "m.room.message$m.emote", + "m.room.message$m.notice", "m.room.message$m.image", + "m.room.message$m.file" ] excluded_types = [ # We exclude server notices from here because we handle them in a # dedicated module. We do not want to confuse developers this early # in the spec. - "m.room.message#m.server_notice", + "m.room.message$m.server_notice", ] other_msgtypes = [ - k for k in schemas.keys() if k.startswith("m.room.message#") and + k for k in schemas.keys() if k.startswith("m.room.message$") and k not in msgtype_order and k not in excluded_types ] for event_name in (msgtype_order + other_msgtypes): - if not event_name.startswith("m.room.message#m."): + if not event_name.startswith("m.room.message$m."): continue sections.append(template.render( example=examples[event_name][0], diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index d4745e4d..ddb65efe 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -795,7 +795,7 @@ class MatrixUnits(Units): if not filename.startswith("m."): continue - event_name = filename.split("#")[0] + event_name = filename.split("$")[0] filepath = os.path.join(path, filename) logger.info("Reading event example: %s" % filepath) try: From f9472bae411e8db020247eb7394d7bd42fe50d5a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 16:27:16 -0600 Subject: [PATCH 141/497] Change reference for definition of push rule condition kinds Fixes https://github.com/matrix-org/matrix-doc/issues/1970 --- api/client-server/definitions/push_condition.yaml | 12 ++++++++---- .../client_server/newsfragments/2052.clarification | 1 + 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2052.clarification diff --git a/api/client-server/definitions/push_condition.yaml b/api/client-server/definitions/push_condition.yaml index 796a51f4..8752274e 100644 --- a/api/client-server/definitions/push_condition.yaml +++ b/api/client-server/definitions/push_condition.yaml @@ -16,16 +16,20 @@ title: PushCondition type: object properties: kind: - enum: - - event_match - - contains_display_name - - room_member_count type: string + description: |- + The kind of condition to apply. See `conditions <#conditions>`_ for + more information on the allowed kinds and how they work. key: type: string description: |- Required for ``event_match`` conditions. The dot-separated field of the event to match. + + Required for ``sender_notification_permission`` conditions. The field in + the power level event the user needs a minimum power level for. Fields + must be specified under the ``notifications`` property in the power level + event's ``content``. x-example: content.body pattern: type: string diff --git a/changelogs/client_server/newsfragments/2052.clarification b/changelogs/client_server/newsfragments/2052.clarification new file mode 100644 index 00000000..95bdc928 --- /dev/null +++ b/changelogs/client_server/newsfragments/2052.clarification @@ -0,0 +1 @@ +Clarify which push rule condition kinds exist. From 792bb8faa49c4551067fd824e805ba4f5c195509 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 16:28:36 -0600 Subject: [PATCH 142/497] Renumber changelog to match PR --- .../newsfragments/{2050.clarification => 2051.clarification} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/client_server/newsfragments/{2050.clarification => 2051.clarification} (100%) diff --git a/changelogs/client_server/newsfragments/2050.clarification b/changelogs/client_server/newsfragments/2051.clarification similarity index 100% rename from changelogs/client_server/newsfragments/2050.clarification rename to changelogs/client_server/newsfragments/2051.clarification From 464845feb0695c99f1b81e665e980e0289ec119c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 16:36:43 -0600 Subject: [PATCH 143/497] Make url required for m.file-like messages Fixes https://github.com/matrix-org/matrix-doc/issues/2008 This also removes `filename` from `m.file` because it has never been used in practice. --- changelogs/client_server/newsfragments/2053.clarification | 1 + event-schemas/schema/m.room.message#m.audio | 1 + event-schemas/schema/m.room.message#m.file | 2 +- event-schemas/schema/m.room.message#m.image | 1 + event-schemas/schema/m.room.message#m.video | 1 + 5 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2053.clarification diff --git a/changelogs/client_server/newsfragments/2053.clarification b/changelogs/client_server/newsfragments/2053.clarification new file mode 100644 index 00000000..2a72a88e --- /dev/null +++ b/changelogs/client_server/newsfragments/2053.clarification @@ -0,0 +1 @@ +Clarify the required fields on ``m.file`` (and similar) messages. diff --git a/event-schemas/schema/m.room.message#m.audio b/event-schemas/schema/m.room.message#m.audio index c258b85f..99e28110 100644 --- a/event-schemas/schema/m.room.message#m.audio +++ b/event-schemas/schema/m.room.message#m.audio @@ -38,6 +38,7 @@ properties: required: - msgtype - body + - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.file b/event-schemas/schema/m.room.message#m.file index 2fb4fe50..2389d8a9 100644 --- a/event-schemas/schema/m.room.message#m.file +++ b/event-schemas/schema/m.room.message#m.file @@ -53,7 +53,7 @@ properties: required: - msgtype - body - - filename + - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.image b/event-schemas/schema/m.room.message#m.image index 349f78f4..1e6ebeaa 100644 --- a/event-schemas/schema/m.room.message#m.image +++ b/event-schemas/schema/m.room.message#m.image @@ -28,6 +28,7 @@ properties: required: - msgtype - body + - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message#m.video b/event-schemas/schema/m.room.message#m.video index 8a66fdeb..2da7e0bc 100644 --- a/event-schemas/schema/m.room.message#m.video +++ b/event-schemas/schema/m.room.message#m.video @@ -59,6 +59,7 @@ properties: required: - msgtype - body + - url type: object type: enum: From 0f623113f10cfc50d99305a8d61ce02371636f5c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 18:35:18 -0600 Subject: [PATCH 144/497] Clarify that UIA stages cannot be attempted twice Fixes https://github.com/matrix-org/matrix-doc/issues/1987 Note: Synapse currently does not care, however the spirit of the text in the spec implies that completed == done forever, so we're just reinforcing it here. --- .../client_server/newsfragments/2054.clarification | 1 + specification/client_server_api.rst | 11 ++++++----- 2 files changed, 7 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2054.clarification diff --git a/changelogs/client_server/newsfragments/2054.clarification b/changelogs/client_server/newsfragments/2054.clarification new file mode 100644 index 00000000..e43aea2d --- /dev/null +++ b/changelogs/client_server/newsfragments/2054.clarification @@ -0,0 +1 @@ +Clarify that User-Interactive Authentication stages cannot be attempted more than once. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 6c2e364a..318ac08d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -453,11 +453,10 @@ params presented, that type may be present as a key in this dictionary. For example, the public part of an OAuth client ID could be given here. session - This is a session identifier that the client must pass back to the home - server, if one is provided, in subsequent attempts to authenticate in the same - API call. + This is a session identifier that the client must pass back to the homeserver, + if one is provided, in subsequent attempts to authenticate in the same API call. -The client then chooses a flow and attempts to complete one of the stages. It +The client then chooses a flow and attempts to complete the first stage. It does this by resubmitting the same request with the addition of an ``auth`` key in the object that it submits. This dictionary contains a ``type`` key whose value is the name of the authentication type that the client is attempting to complete. @@ -558,7 +557,9 @@ message in the standard format. For example: } If the client has completed all stages of a flow, the homeserver performs the -API call and returns the result as normal. +API call and returns the result as normal. Completed stages cannot be re-tried; +The client must abandon the current session and start over. Homeservers should +treat retries as authentication errors. Some authentication types may be completed by means other than through the Matrix client, for example, an email confirmation may be completed when the user From 2ed37f5bf464d03a322184221a89f6ebe4c61630 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 21:00:37 -0600 Subject: [PATCH 145/497] Clarify guest accounts and `auth` usage on /register Fixes https://github.com/matrix-org/matrix-doc/issues/1980 Fixes https://github.com/matrix-org/matrix-doc/issues/1984 --- api/client-server/registration.yaml | 34 ++++++++++++++----- .../newsfragments/2055.clarification | 1 + 2 files changed, 26 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2055.clarification diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 3195ab41..10b661a3 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -29,7 +29,8 @@ paths: post: summary: Register for an account on this homeserver. description: |- - This API endpoint uses the `User-Interactive Authentication API`_. + This API endpoint uses the `User-Interactive Authentication API`_, except in + the cases where a guest account is being registered. Register for an account on this homeserver. @@ -59,6 +60,11 @@ paths: supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See `Relationship between access tokens and devices`_. + + When registering a guest account, all parameters in the request body + with the exception of ``initial_device_display_name`` are ignored by + the server. The server will pick a ``device_id`` for the account + regardless of input. operationId: register parameters: - in: query @@ -72,7 +78,7 @@ paths: enum: - guest - user - description: The kind of account to register. Defaults to `user`. + description: The kind of account to register. Defaults to ``user``. - in: body name: body schema: @@ -80,13 +86,11 @@ paths: properties: auth: description: |- - Additional authentication information for the - user-interactive authentication API. Note that this - information is *not* used to define how the registered user - should be authenticated, but is instead used to - authenticate the ``register`` call itself. It should be - left empty, or omitted, unless an earlier call returned an - response with status code 401. + Additional authentication information for the + user-interactive authentication API. Note that this + information is *not* used to define how the registered user + should be authenticated, but is instead used to + authenticate the ``register`` call itself. "$ref": "definitions/auth_data.yaml" bind_email: type: boolean @@ -194,6 +198,18 @@ paths: The homeserver requires additional authentication information. schema: "$ref": "definitions/auth_response.yaml" + 403: + description: |- + The homeserver does not permit registering the account. This response + can be used to identify that a particular ``kind`` of account is not + allowed, or that registration is generally not supported by the homeserver. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Registration is disabled" + } + schema: + "$ref": "definitions/errors/error.yaml" 429: description: This request was rate-limited. schema: diff --git a/changelogs/client_server/newsfragments/2055.clarification b/changelogs/client_server/newsfragments/2055.clarification new file mode 100644 index 00000000..3a57ef7e --- /dev/null +++ b/changelogs/client_server/newsfragments/2055.clarification @@ -0,0 +1 @@ +Clarify which parameters apply in what scenarios on ``/register``. From f3c0c5232fb812d90ceeda1348c1fc2d17558e28 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 May 2019 21:44:50 -0600 Subject: [PATCH 146/497] Add a table to show how changes in membership should be interpreted Fixes https://github.com/matrix-org/matrix-doc/issues/876 --- .../newsfragments/2056.clarification | 1 + event-schemas/schema/m.room.member | 23 +++++++++++++++++++ scripts/css/tables.css | 4 ++++ 3 files changed, 28 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2056.clarification create mode 100644 scripts/css/tables.css diff --git a/changelogs/client_server/newsfragments/2056.clarification b/changelogs/client_server/newsfragments/2056.clarification new file mode 100644 index 00000000..12521867 --- /dev/null +++ b/changelogs/client_server/newsfragments/2056.clarification @@ -0,0 +1 @@ +Clarify how to interpret changes of ``membership`` over time. diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index de14644d..20d3cbcc 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -21,6 +21,29 @@ description: |- This event may also include an ``invite_room_state`` key inside the event's ``unsigned`` data. If present, this contains an array of ``StrippedState`` Events. These events provide information on a subset of state events such as the room name. + + The user for which a membership applies is represented by the ``state_key``. Under some conditions, + the ``sender`` and ``state_key`` may not match - this may be interpreted as the ``sender`` affecting + the membership state of the ``state_key`` user. + + The ``membership`` for a given user can change over time. The table below represents the various changes + over time and how clients and servers must interpret those changes. Previous membership can be retrieved + from the ``prev_content`` object on an event. If not present, the user's previous membership must be assumed + as ``leave``. + + .. TODO: Improve how this table is written? We use a csv-table to get around vertical header restrictions. + + .. csv-table:: + :header-rows: 1 + :stub-columns: 1 + + "","to ``invite``","to ``join``","to ``leave``","to ``ban``","to ``knock``" + "from ``invite``","No change.","User joined the room.","If the ``state_key`` is the same as the ``sender``, the user rejected the invite. Otherwise, the ``state_key`` user had their invite revoked.","User was banned.","Not implemented." + "from ``join``","Must never happen.","``displayname`` or ``avatar_url`` changed.","If the ``state_key`` is the same as the ``sender``, the user left. Otherwise, the ``state_key`` user was kicked.","User was kicked and banned.","Not implemented." + "from ``leave``","New invitation sent.","User joined.","Must never happen.","User was banned.","Not implemented." + "from ``ban``","Must never happen.","Must never happen.","User was unbanned.","No change.","Not implemented." + "from ``knock``","Not implemented.","Not implemented.","Not implemented.","Not implemented.","Not implemented." + properties: content: properties: diff --git a/scripts/css/tables.css b/scripts/css/tables.css new file mode 100644 index 00000000..03ee1d85 --- /dev/null +++ b/scripts/css/tables.css @@ -0,0 +1,4 @@ +/* Column with header cells */ +table.docutils tbody th.stub { + background: #eeeeee; +} From 6ae7e49522e34b32fa317756b906a784317ac829 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 30 May 2019 12:30:43 +0100 Subject: [PATCH 147/497] Clarify what the client should receiving on email resending It was a little unclear what the client should do when asked to send a validation email and provides a `send_attempt` value that is not greater than previous attempts. As this is intended to be for when a client mistakenly sends the request twice, it makes logical sense that the implication was to simply resend a success value so the client doesn't error even when an email may have been sent on the first attempt. This behaviour was also mimicked in Synapse/Sydent. --- api/identity/definitions/request_email_validation.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index 1194a18e..d6606f03 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -39,7 +39,8 @@ properties: avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new - email (e.g. a reminder) to be sent. + email (e.g. a reminder) to be sent. If they do not, the server + should return a success but not resend the email. example: 1 next_link: type: string From c0c462999374a51b8430b88f7abe58a5a2b4386b Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 30 May 2019 12:31:26 +0100 Subject: [PATCH 148/497] Slight word change --- api/identity/definitions/request_email_validation.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index d6606f03..5d1aac8a 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -40,7 +40,7 @@ properties: retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server - should return a success but not resend the email. + should response with success but not resend the email. example: 1 next_link: type: string From dda8976d2544a22cb280fce243d23107e2bd4c88 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 30 May 2019 12:33:29 +0100 Subject: [PATCH 149/497] Add changelog --- changelogs/client_server/newsfragments/2057.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2057.clarification diff --git a/changelogs/client_server/newsfragments/2057.clarification b/changelogs/client_server/newsfragments/2057.clarification new file mode 100644 index 00000000..de72c201 --- /dev/null +++ b/changelogs/client_server/newsfragments/2057.clarification @@ -0,0 +1 @@ +Clarify what the client should receive upon sending an identical email validation request multiple times. From 54f74cd877eb166ca53d52bd1a16f51a6df68461 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 May 2019 16:46:55 -0600 Subject: [PATCH 150/497] Add Olm unwedging As per [MSC1719](https://github.com/matrix-org/matrix-doc/pull/1719) No known alterations have been made to the proposal. Implementation proof: https://github.com/matrix-org/matrix-js-sdk/pull/780 --- .../client_server/newsfragments/2059.feature | 1 + event-schemas/examples/m.dummy | 4 ++ event-schemas/schema/m.dummy | 23 +++++++++++ .../modules/end_to_end_encryption.rst | 41 ++++++++++++++++--- 4 files changed, 64 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2059.feature create mode 100644 event-schemas/examples/m.dummy create mode 100644 event-schemas/schema/m.dummy diff --git a/changelogs/client_server/newsfragments/2059.feature b/changelogs/client_server/newsfragments/2059.feature new file mode 100644 index 00000000..fde106ce --- /dev/null +++ b/changelogs/client_server/newsfragments/2059.feature @@ -0,0 +1 @@ +Add support for Olm sessions becoming un-stuck. diff --git a/event-schemas/examples/m.dummy b/event-schemas/examples/m.dummy new file mode 100644 index 00000000..0cd39166 --- /dev/null +++ b/event-schemas/examples/m.dummy @@ -0,0 +1,4 @@ +{ + "content": {}, + "type": "m.dummy" +} diff --git a/event-schemas/schema/m.dummy b/event-schemas/schema/m.dummy new file mode 100644 index 00000000..5bebe430 --- /dev/null +++ b/event-schemas/schema/m.dummy @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to indicate new Olm sessions for end-to-end encryption. + Typically it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ + event. + + The event does not have any content associated with it. The sending client is expected + to send a key share request shortly after this message, causing the receiving client to + process this ``m.dummy`` event as the most recent event and using the keyshare request + to set up the session. The keyshare request and ``m.dummy`` combination should result + in the original sending client receiving keys over the newly establish session. +properties: + content: + properties: {} + type: object + type: + enum: + - m.dummy + type: string +type: object diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 38a0a06b..a77dbad9 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2019 The Matrix.org Foundation C.I.C. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -18,7 +19,7 @@ End-to-End Encryption .. _module:e2e: Matrix optionally supports end-to-end encryption, allowing rooms to be created -whose conversation contents is not decryptable or interceptable on any of the +whose conversation contents are not decryptable or interceptable on any of the participating homeservers. Key Distribution @@ -549,6 +550,31 @@ Example: ] } + +Recovering from undecryptable messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Occasionally messages may be undecryptable by clients due to a variety of reasons. +When this happens to an Olm-encrypted message, the client should assume that the Olm +session has become corrupted and create a new one to replace it. + +.. Note:: + Megolm-encrypted messages generally do not have the same problem. Usually the key + for an undecryptable Megolm-encrypted message will come later, allowing the client + to decrypt it successfully. Olm does not have a way to recover from the failure, + making this session replacement process required. + +To establish a new session, the client sends a `m.dummy <#m-dummy>`_ to-device event +to the other party to notify them of the new session details. + +Clients should rate-limit the number of sessions it creates per device that it receives +a message from. Clients should not create a new session with another device if it has +already created on for that given device in the past 1 hour. + +Clients should attempt to mitigate loss of the undecryptable messages. For example, +Megolm sessions that were sent using the old session would have been lost. The client +can attempt to retrieve the lost sessions through ``m.room_key_request`` messages. + Messaging Algorithms -------------------- @@ -658,10 +684,13 @@ part of the ed25519 key it claims to have in the Olm payload. This is crucial when the ed25519 key corresponds to a verified device. If a client has multiple sessions established with another device, it should -use the session from which it last received a message. A client may expire old -sessions by defining a maximum number of olm sessions that it will maintain for -each device, and expiring sessions on a Least Recently Used basis. The maximum -number of olm sessions maintained per device should be at least 4. +use the session from which it last received and successfully decrypted a +message. For these purposes, a session that has not received any messages +should use its creation time as the time that it last received a message. +A client may expire old sessions by defining a maximum number of olm sessions +that it will maintain for each device, and expiring sessions on a Least Recently +Used basis. The maximum number of olm sessions maintained per device should +be at least 4. ``m.megolm.v1.aes-sha2`` ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -740,6 +769,8 @@ Events {{m_forwarded_room_key_event}} +{{m_dummy_event}} + Key management API ~~~~~~~~~~~~~~~~~~ From d48265f49be7ba8b4fd4471396dd4deb0796ec25 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 May 2019 16:51:24 -0600 Subject: [PATCH 151/497] typo --- event-schemas/schema/m.dummy | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/m.dummy b/event-schemas/schema/m.dummy index 5bebe430..8e4b6f94 100644 --- a/event-schemas/schema/m.dummy +++ b/event-schemas/schema/m.dummy @@ -11,7 +11,7 @@ description: |- to send a key share request shortly after this message, causing the receiving client to process this ``m.dummy`` event as the most recent event and using the keyshare request to set up the session. The keyshare request and ``m.dummy`` combination should result - in the original sending client receiving keys over the newly establish session. + in the original sending client receiving keys over the newly established session. properties: content: properties: {} From 41e07ff7d64ba3bb667532bb0f69c250ba93d149 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 May 2019 16:54:19 -0600 Subject: [PATCH 152/497] Fix incorrect state of leave->leave As mentioned in PR review, it is possible for moderators in a room to race at kicking someone, resulting in multiple leave events. --- event-schemas/schema/m.room.member | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index 20d3cbcc..8984ac5c 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -40,7 +40,7 @@ description: |- "","to ``invite``","to ``join``","to ``leave``","to ``ban``","to ``knock``" "from ``invite``","No change.","User joined the room.","If the ``state_key`` is the same as the ``sender``, the user rejected the invite. Otherwise, the ``state_key`` user had their invite revoked.","User was banned.","Not implemented." "from ``join``","Must never happen.","``displayname`` or ``avatar_url`` changed.","If the ``state_key`` is the same as the ``sender``, the user left. Otherwise, the ``state_key`` user was kicked.","User was kicked and banned.","Not implemented." - "from ``leave``","New invitation sent.","User joined.","Must never happen.","User was banned.","Not implemented." + "from ``leave``","New invitation sent.","User joined.","No change.","User was banned.","Not implemented." "from ``ban``","Must never happen.","Must never happen.","User was unbanned.","No change.","Not implemented." "from ``knock``","Not implemented.","Not implemented.","Not implemented.","Not implemented.","Not implemented." From 754b19bb929601fa5253470eea5dbfc45361d81b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 May 2019 10:21:16 -0600 Subject: [PATCH 153/497] typo Co-Authored-By: Hubert Chathi --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index a77dbad9..628c1a60 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -569,7 +569,7 @@ to the other party to notify them of the new session details. Clients should rate-limit the number of sessions it creates per device that it receives a message from. Clients should not create a new session with another device if it has -already created on for that given device in the past 1 hour. +already created one for that given device in the past 1 hour. Clients should attempt to mitigate loss of the undecryptable messages. For example, Megolm sessions that were sent using the old session would have been lost. The client From 57e3b152b042183f1bbb424fdaec7518c820dc66 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 May 2019 11:37:09 -0600 Subject: [PATCH 154/497] Move section to under Olm stuff --- .../modules/end_to_end_encryption.rst | 50 +++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 628c1a60..e6048c28 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -550,31 +550,6 @@ Example: ] } - -Recovering from undecryptable messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Occasionally messages may be undecryptable by clients due to a variety of reasons. -When this happens to an Olm-encrypted message, the client should assume that the Olm -session has become corrupted and create a new one to replace it. - -.. Note:: - Megolm-encrypted messages generally do not have the same problem. Usually the key - for an undecryptable Megolm-encrypted message will come later, allowing the client - to decrypt it successfully. Olm does not have a way to recover from the failure, - making this session replacement process required. - -To establish a new session, the client sends a `m.dummy <#m-dummy>`_ to-device event -to the other party to notify them of the new session details. - -Clients should rate-limit the number of sessions it creates per device that it receives -a message from. Clients should not create a new session with another device if it has -already created one for that given device in the past 1 hour. - -Clients should attempt to mitigate loss of the undecryptable messages. For example, -Megolm sessions that were sent using the old session would have been lost. The client -can attempt to retrieve the lost sessions through ``m.room_key_request`` messages. - Messaging Algorithms -------------------- @@ -692,6 +667,31 @@ that it will maintain for each device, and expiring sessions on a Least Recently Used basis. The maximum number of olm sessions maintained per device should be at least 4. +Recovering from undecryptable messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Occasionally messages may be undecryptable by clients due to a variety of reasons. +When this happens to an Olm-encrypted message, the client should assume that the Olm +session has become corrupted and create a new one to replace it. + +.. Note:: + Megolm-encrypted messages generally do not have the same problem. Usually the key + for an undecryptable Megolm-encrypted message will come later, allowing the client + to decrypt it successfully. Olm does not have a way to recover from the failure, + making this session replacement process required. + +To establish a new session, the client sends a `m.dummy <#m-dummy>`_ to-device event +to the other party to notify them of the new session details. + +Clients should rate-limit the number of sessions it creates per device that it receives +a message from. Clients should not create a new session with another device if it has +already created one for that given device in the past 1 hour. + +Clients should attempt to mitigate loss of the undecryptable messages. For example, +Megolm sessions that were sent using the old session would have been lost. The client +can attempt to retrieve the lost sessions through ``m.room_key_request`` messages. + + ``m.megolm.v1.aes-sha2`` ~~~~~~~~~~~~~~~~~~~~~~~~ From 7a07a6b358cb15cc6ef81fba07037b440ade2879 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 2 Jun 2019 17:41:39 -0600 Subject: [PATCH 155/497] Clarify exactly what StrippedState is Fixes https://github.com/matrix-org/matrix-doc/issues/2066 The expectation everywhere is that the `sender` is required. `/initialSync` references StrippedState through a `m.room.member` event reference, and does not need editing. --- api/client-server/sync.yaml | 25 +---------- api/server-server/invites-v1.yaml | 20 +-------- api/server-server/invites-v2.yaml | 20 +-------- .../newsfragments/2067.clarification | 1 + .../newsfragments/2067.clarification | 1 + .../examples/m.room.member$invite_room_state | 19 ++------ event-schemas/examples/stripped_state.json | 18 ++++++++ event-schemas/schema/m.room.member | 19 +------- event-schemas/schema/stripped_state.yaml | 44 +++++++++++++++++++ 9 files changed, 71 insertions(+), 96 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2067.clarification create mode 100644 changelogs/server_server/newsfragments/2067.clarification create mode 100644 event-schemas/examples/stripped_state.json create mode 100644 event-schemas/schema/stripped_state.yaml diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 02fddb84..3db1fa54 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -212,30 +212,7 @@ paths: events: description: The StrippedState events that form the invite state. items: - description: |- - A stripped down state event, with only the ``type``, ``state_key``, - ``sender``, and ``content`` keys. - properties: - content: - description: The ``content`` for the event. - title: EventContent - type: object - state_key: - description: The ``state_key`` for the event. - type: string - type: - description: The ``type`` for the event. - type: string - sender: - description: The ``sender`` for the event. - type: string - required: - - type - - state_key - - content - - sender - title: StrippedState - type: object + $ref: "definitions/event-schemas/schema/stripped_state.yaml" type: array leave: title: Left rooms diff --git a/api/server-server/invites-v1.yaml b/api/server-server/invites-v1.yaml index 2ad0f220..867d7b05 100644 --- a/api/server-server/invites-v1.yaml +++ b/api/server-server/invites-v1.yaml @@ -82,25 +82,7 @@ paths: identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. items: - type: object - title: Invite Room State Event - properties: - type: - type: string - description: The type of event. - example: "m.room.join_rules" - state_key: - type: string - description: The state key for the event. May be an empty string. - example: "" - content: - type: object - description: The content for the event. - sender: - type: string - description: The sender of the event. - example: "@someone:matrix.org" - required: ['type', 'state_key', 'content', 'sender'] + $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml" example: [ { "type": "m.room.join_rules", diff --git a/api/server-server/invites-v2.yaml b/api/server-server/invites-v2.yaml index c459a848..6d5b102e 100644 --- a/api/server-server/invites-v2.yaml +++ b/api/server-server/invites-v2.yaml @@ -83,25 +83,7 @@ paths: identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. items: - type: object - title: Invite Room State Event - properties: - type: - type: string - description: The type of event. - example: "m.room.join_rules" - state_key: - type: string - description: The state key for the event. May be an empty string. - example: "" - content: - type: object - description: The content for the event. - sender: - type: string - description: The sender of the event. - example: "@someone:matrix.org" - required: ['type', 'state_key', 'content', 'sender'] + $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml" example: [ { "type": "m.room.join_rules", diff --git a/changelogs/client_server/newsfragments/2067.clarification b/changelogs/client_server/newsfragments/2067.clarification new file mode 100644 index 00000000..cc706274 --- /dev/null +++ b/changelogs/client_server/newsfragments/2067.clarification @@ -0,0 +1 @@ +Clarify exactly what invite_room_state consists of. diff --git a/changelogs/server_server/newsfragments/2067.clarification b/changelogs/server_server/newsfragments/2067.clarification new file mode 100644 index 00000000..cc706274 --- /dev/null +++ b/changelogs/server_server/newsfragments/2067.clarification @@ -0,0 +1 @@ +Clarify exactly what invite_room_state consists of. diff --git a/event-schemas/examples/m.room.member$invite_room_state b/event-schemas/examples/m.room.member$invite_room_state index f8f05484..b60abf95 100644 --- a/event-schemas/examples/m.room.member$invite_room_state +++ b/event-schemas/examples/m.room.member$invite_room_state @@ -7,21 +7,8 @@ }, "unsigned": { "age": 1234, - "invite_room_state": [ - { - "type": "m.room.name", - "state_key": "", - "content": { - "name": "Forest of Magic" - } - }, - { - "type": "m.room.join_rules", - "state_key": "", - "content": { - "join_rule": "invite" - } - } - ] + "invite_room_state": { + "$ref": "stripped_state.json" + } } } diff --git a/event-schemas/examples/stripped_state.json b/event-schemas/examples/stripped_state.json new file mode 100644 index 00000000..9d8c1b2b --- /dev/null +++ b/event-schemas/examples/stripped_state.json @@ -0,0 +1,18 @@ +[ + { + "type": "m.room.name", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "name": "Example Room" + } + }, + { + "type": "m.room.join_rules", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "join_rule": "invite" + } + } +] diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index de14644d..f846196b 100644 --- a/event-schemas/schema/m.room.member +++ b/event-schemas/schema/m.room.member @@ -81,24 +81,7 @@ properties: invite_room_state: description: 'A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.' items: - description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.' - properties: - content: - description: The ``content`` for the event. - title: EventContent - type: object - state_key: - description: The ``state_key`` for the event. - type: string - type: - description: The ``type`` for the event. - type: string - required: - - type - - state_key - - content - title: StrippedState - type: object + $ref: "stripped_state.yaml" type: array required: - membership diff --git a/event-schemas/schema/stripped_state.yaml b/event-schemas/schema/stripped_state.yaml new file mode 100644 index 00000000..ec591bf1 --- /dev/null +++ b/event-schemas/schema/stripped_state.yaml @@ -0,0 +1,44 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Note: this, and the example, are in the `event-schemas` directory because +# the CS API uses a symlink. In order for the `m.room.member` event to +# reference this, we'd need to use relative pathing. The symlink makes this +# difficult because the schema would be at two different locations, with +# different relative pathing. + +title: StrippedState +type: object +description: |- + A stripped down state event, with only the ``type``, ``state_key``, + ``sender``, and ``content`` keys. +properties: + content: + description: The ``content`` for the event. + title: EventContent + type: object + state_key: + description: The ``state_key`` for the event. + type: string + type: + description: The ``type`` for the event. + type: string + sender: + description: The ``sender`` for the event. + type: string +required: + - type + - state_key + - content + - sender From b9c4a2561ff8692b8e960e9eb977efb27b86e57b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 2 Jun 2019 17:50:27 -0600 Subject: [PATCH 156/497] Fix examples of StrippedState in s2s spec --- api/server-server/invites-v1.yaml | 53 +++---------------------------- api/server-server/invites-v2.yaml | 53 ++++--------------------------- 2 files changed, 11 insertions(+), 95 deletions(-) diff --git a/api/server-server/invites-v1.yaml b/api/server-server/invites-v1.yaml index 867d7b05..2f08dd12 100644 --- a/api/server-server/invites-v1.yaml +++ b/api/server-server/invites-v1.yaml @@ -83,16 +83,8 @@ paths: canonical alias, avatar, and name of the room. items: $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml" - example: [ - { - "type": "m.room.join_rules", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "join_rule": "public" - } - } - ] + example: + $ref: "../client-server/definitions/event-schemas/examples/stripped_state.json" example: { "$ref": "examples/minimal_pdu.json", "type": "m.room.member", @@ -100,26 +92,6 @@ paths: "origin": "example.org", "origin_server_ts": 1549041175876, "sender": "@someone:example.org", - "unsigned": { - "invite_room_state": [ - { - "type": "m.room.join_rules", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "join_rule": "public" - } - }, - { - "type": "m.room.name", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "name": "Cool New Room" - } - } - ] - }, "content": { "membership": "invite" }, @@ -162,24 +134,9 @@ paths: "origin_server_ts": 1549041175876, "sender": "@someone:example.org", "unsigned": { - "invite_room_state": [ - { - "type": "m.room.join_rules", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "join_rule": "public" - } - }, - { - "type": "m.room.name", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "name": "Cool New Room" - } - } - ] + "invite_room_state": { + "$ref": "../../client-server/definitions/event-schemas/examples/stripped_state.json" + } }, "content": { "membership": "invite" diff --git a/api/server-server/invites-v2.yaml b/api/server-server/invites-v2.yaml index 6d5b102e..57ca99ff 100644 --- a/api/server-server/invites-v2.yaml +++ b/api/server-server/invites-v2.yaml @@ -84,16 +84,8 @@ paths: canonical alias, avatar, and name of the room. items: $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml" - example: [ - { - "type": "m.room.join_rules", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "join_rule": "public" - } - } - ] + example: + $ref: "../client-server/definitions/event-schemas/examples/stripped_state.json" required: ['room_version', 'event'] example: { "room_version": "2", @@ -112,25 +104,7 @@ paths: "ed25519:key_version": "SomeSignatureHere" }, } - }, - "invite_room_state": [ - { - "type": "m.room.join_rules", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "join_rule": "public" - } - }, - { - "type": "m.room.name", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "name": "Cool New Room" - } - } - ] + } } responses: 200: @@ -156,24 +130,9 @@ paths: "origin_server_ts": 1549041175876, "sender": "@someone:example.org", "unsigned": { - "invite_room_state": [ - { - "type": "m.room.join_rules", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "join_rule": "public" - } - }, - { - "type": "m.room.name", - "sender": "@someone:matrix.org", - "state_key": "", - "content": { - "name": "Cool New Room" - } - } - ] + "invite_room_state": { + "$ref": "../../client-server/definitions/event-schemas/examples/stripped_state.json" + } }, "content": { "membership": "invite" From 237d585e07b376d69e0f7e887b7135bc8250aba6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 2 Jun 2019 17:59:19 -0600 Subject: [PATCH 157/497] Shorten references to StrippedState in s2s spec --- api/server-server/invites-v1.yaml | 6 +++--- api/server-server/invites-v2.yaml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/server-server/invites-v1.yaml b/api/server-server/invites-v1.yaml index 2f08dd12..83aafb3a 100644 --- a/api/server-server/invites-v1.yaml +++ b/api/server-server/invites-v1.yaml @@ -82,9 +82,9 @@ paths: identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. items: - $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml" + $ref: "../../event-schemas/schema/stripped_state.yaml" example: - $ref: "../client-server/definitions/event-schemas/examples/stripped_state.json" + $ref: "../../event-schemas/examples/stripped_state.json" example: { "$ref": "examples/minimal_pdu.json", "type": "m.room.member", @@ -135,7 +135,7 @@ paths: "sender": "@someone:example.org", "unsigned": { "invite_room_state": { - "$ref": "../../client-server/definitions/event-schemas/examples/stripped_state.json" + "$ref": "../../../event-schemas/examples/stripped_state.json" } }, "content": { diff --git a/api/server-server/invites-v2.yaml b/api/server-server/invites-v2.yaml index 57ca99ff..d2cc63a2 100644 --- a/api/server-server/invites-v2.yaml +++ b/api/server-server/invites-v2.yaml @@ -83,9 +83,9 @@ paths: identify the room. The recommended events to include are the join rules, canonical alias, avatar, and name of the room. items: - $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml" + $ref: "../../event-schemas/schema/stripped_state.yaml" example: - $ref: "../client-server/definitions/event-schemas/examples/stripped_state.json" + $ref: "../../event-schemas/examples/stripped_state.json" required: ['room_version', 'event'] example: { "room_version": "2", @@ -131,7 +131,7 @@ paths: "sender": "@someone:example.org", "unsigned": { "invite_room_state": { - "$ref": "../../client-server/definitions/event-schemas/examples/stripped_state.json" + "$ref": "../../../event-schemas/examples/stripped_state.json" } }, "content": { From 0b45f3795bb6c561266f9388f850bae460c204fd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 2 Jun 2019 18:02:22 -0600 Subject: [PATCH 158/497] Rename example to invite_room_state This is a better representation of what it actually is --- api/server-server/invites-v1.yaml | 4 ++-- api/server-server/invites-v2.yaml | 4 ++-- .../examples/{stripped_state.json => invite_room_state.json} | 0 event-schemas/examples/m.room.member$invite_room_state | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) rename event-schemas/examples/{stripped_state.json => invite_room_state.json} (100%) diff --git a/api/server-server/invites-v1.yaml b/api/server-server/invites-v1.yaml index 83aafb3a..8e1c861d 100644 --- a/api/server-server/invites-v1.yaml +++ b/api/server-server/invites-v1.yaml @@ -84,7 +84,7 @@ paths: items: $ref: "../../event-schemas/schema/stripped_state.yaml" example: - $ref: "../../event-schemas/examples/stripped_state.json" + $ref: "../../event-schemas/examples/invite_room_state.json" example: { "$ref": "examples/minimal_pdu.json", "type": "m.room.member", @@ -135,7 +135,7 @@ paths: "sender": "@someone:example.org", "unsigned": { "invite_room_state": { - "$ref": "../../../event-schemas/examples/stripped_state.json" + "$ref": "../../../event-schemas/examples/invite_room_state.json" } }, "content": { diff --git a/api/server-server/invites-v2.yaml b/api/server-server/invites-v2.yaml index d2cc63a2..cae14bb4 100644 --- a/api/server-server/invites-v2.yaml +++ b/api/server-server/invites-v2.yaml @@ -85,7 +85,7 @@ paths: items: $ref: "../../event-schemas/schema/stripped_state.yaml" example: - $ref: "../../event-schemas/examples/stripped_state.json" + $ref: "../../event-schemas/examples/invite_room_state.json" required: ['room_version', 'event'] example: { "room_version": "2", @@ -131,7 +131,7 @@ paths: "sender": "@someone:example.org", "unsigned": { "invite_room_state": { - "$ref": "../../../event-schemas/examples/stripped_state.json" + "$ref": "../../../event-schemas/examples/invite_room_state.json" } }, "content": { diff --git a/event-schemas/examples/stripped_state.json b/event-schemas/examples/invite_room_state.json similarity index 100% rename from event-schemas/examples/stripped_state.json rename to event-schemas/examples/invite_room_state.json diff --git a/event-schemas/examples/m.room.member$invite_room_state b/event-schemas/examples/m.room.member$invite_room_state index b60abf95..2c93eb9b 100644 --- a/event-schemas/examples/m.room.member$invite_room_state +++ b/event-schemas/examples/m.room.member$invite_room_state @@ -8,7 +8,7 @@ "unsigned": { "age": 1234, "invite_room_state": { - "$ref": "stripped_state.json" + "$ref": "invite_room_state.json" } } } From 86019c9adeb05a3998a03b7e12089b151293015a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 2 Jun 2019 18:02:36 -0600 Subject: [PATCH 159/497] Skip over partial event definitions in examples --- event-schemas/check_examples.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/event-schemas/check_examples.py b/event-schemas/check_examples.py index 2baa3ef0..31daa478 100755 --- a/event-schemas/check_examples.py +++ b/event-schemas/check_examples.py @@ -106,6 +106,9 @@ def check_example_dir(exampledir, schemadir): if filename.startswith("."): # Skip over any vim .swp files. continue + if filename.endswith(".json"): + # Skip over any explicit examples (partial event definitions) + continue cwd = os.path.basename(os.path.dirname(os.path.join(root, filename))) if cwd == "core": # Skip checking the underlying definitions From 1f86e8e31b11db7514db2d139cb3836f5af0078e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 2 Jun 2019 21:23:59 -0600 Subject: [PATCH 160/497] Refactor documentation for content/media repository Fixes https://github.com/matrix-org/matrix-doc/issues/2060 Fixes https://github.com/matrix-org/matrix-doc/issues/772 Fixes https://github.com/matrix-org/matrix-doc/issues/888 --- api/client-server/content-repo.yaml | 156 ++++++++++-------- api/client-server/room_state.yaml | 2 +- .../newsfragments/2068.clarification | 1 + event-schemas/examples/m.room.member | 2 +- .../examples/m.room.member$invite_room_state | 2 +- .../examples/m.room.member$third_party_invite | 2 +- .../msgtype_infos/image_info.yaml | 2 +- event-schemas/schema/m.room.message$m.audio | 2 +- event-schemas/schema/m.room.message$m.file | 2 +- event-schemas/schema/m.room.message$m.image | 2 +- event-schemas/schema/m.room.message$m.video | 4 +- specification/modules/content_repo.rst | 87 +++++++--- 12 files changed, 163 insertions(+), 101 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2068.clarification diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 4460bb69..576d29ef 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -1,4 +1,5 @@ # Copyright 2016 OpenMarket Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -58,66 +59,41 @@ paths: format: byte responses: 200: - description: The MXC URI for the uploaded content. + description: The `MXC URI`_ for the uploaded content. schema: type: object required: ["content_uri"] properties: content_uri: type: string - description: "The MXC URI to the uploaded content." + description: "The `MXC URI`_ to the uploaded content." examples: application/json: { - "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" - } - 429: - description: This request was rate-limited. + "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" + } + 403: + description: |- + The user does not have permission to upload the content. Some reasons for this error include: + + - The server does not permit the file type. + - The user has reached a quota for uploaded content. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } schema: - "$ref": "definitions/errors/rate_limited.yaml" - tags: - - Media - "/download/{serverName}/{mediaId}": - get: - summary: "Download content from the content repository." - operationId: getContent - produces: ["*/*"] - parameters: - - in: path - type: string - name: serverName - x-example: matrix.org - required: true - description: | - The server name from the ``mxc://`` URI (the authoritory component) - - in: path - type: string - name: mediaId - x-example: ascERGshawAWawugaAcauga - required: true - description: | - The media ID from the ``mxc://`` URI (the path component) - - in: query - type: boolean - name: allow_remote - x-example: false - required: false - default: true - description: | - Indicates to the server that it should not attempt to fetch the media if it is deemed - remote. This is to prevent routing loops where the server contacts itself. Defaults to - true if not provided. - responses: - 200: - description: "The content that was previously uploaded." - headers: - Content-Type: - description: "The content type of the file that was previously uploaded." - type: "string" - Content-Disposition: - description: "The name of the file that was previously uploaded, if set." - type: "string" + "$ref": "definitions/errors/error.yaml" + 413: + description: |- + The uploaded content is too large for the server. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Cannot upload files larger than 100mb" + } schema: - type: file + "$ref": "definitions/errors/error.yaml" 429: description: This request was rate-limited. schema: @@ -126,8 +102,8 @@ paths: - Media "/download/{serverName}/{mediaId}/{fileName}": get: - summary: "Download content from the content repository as a given filename." - operationId: getContentOverrideName + summary: "Download content from the content repository." + operationId: getContent produces: ["*/*"] parameters: - in: path @@ -148,9 +124,7 @@ paths: type: string name: fileName x-example: filename.jpg - required: true - description: | - The filename to give in the Content-Disposition + description: An optional filename to give in the ``Content-Disposition`` header. - in: query type: boolean name: allow_remote @@ -169,10 +143,24 @@ paths: description: "The content type of the file that was previously uploaded." type: "string" Content-Disposition: - description: "The name of file given in the request" + description: |- + The ``fileName`` requested or the name of the file that was previously + uploaded, if set. type: "string" schema: type: file + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + 502: + description: |- + The content is too large for the server to serve. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + schema: + "$ref": "definitions/errors/error.yaml" 429: description: This request was rate-limited. schema: @@ -181,7 +169,9 @@ paths: - Media "/thumbnail/{serverName}/{mediaId}": get: - summary: "Download a thumbnail of the content from the content repository." + summary: |- + Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_ + section for more information. operationId: getContentThumbnail produces: ["image/jpeg", "image/png"] parameters: @@ -189,7 +179,7 @@ paths: type: string name: serverName required: true - x-example: matrix.org + x-example: example.org description: | The server name from the ``mxc://`` URI (the authoritory component) - in: path @@ -205,22 +195,24 @@ paths: name: width required: true description: |- - The *desired* width of the thumbnail. The actual thumbnail may not - match the size specified. + The *desired* width of the thumbnail. The actual thumbnail may be + larger than the size specified. - in: query type: integer x-example: 64 name: height required: true description: |- - The *desired* height of the thumbnail. The actual thumbnail may not - match the size specified. + The *desired* height of the thumbnail. The actual thumbnail may be + larger than the size specified. - in: query type: string enum: ["crop", "scale"] name: method x-example: "scale" - description: The desired resizing method. + description: |- + The desired resizing method. See the `thumbnailing <#thumbnails>`_ + section for more information. - in: query type: boolean name: allow_remote @@ -241,6 +233,40 @@ paths: enum: ["image/jpeg", "image/png"] schema: type: file + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the thumbnail." + 400: + description: |- + The request does not make sense to the server, or the server cannot thumbnail + the content. For example, the client requested non-integer dimensions or asked + for negatively-sized images. + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + schema: + "$ref": "definitions/errors/error.yaml" + 413: + description: |- + The local content is too large for the server to thumbnail. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + schema: + "$ref": "definitions/errors/error.yaml" + 502: + description: |- + The remote content is too large for the server to thumbnail. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + schema: + "$ref": "definitions/errors/error.yaml" 429: description: This request was rate-limited. schema: @@ -259,7 +285,7 @@ paths: type: string x-example: "https://matrix.org" name: url - description: "The URL to get a preview of" + description: "The URL to get a preview of." required: true - in: query type: integer @@ -287,7 +313,7 @@ paths: "og:image": type: string description: |- - An MXC URI to the image. Omitted if there is no image. + An `MXC URI`_ to the image. Omitted if there is no image. examples: application/json: { "og:title": "Matrix Blog Post", diff --git a/api/client-server/room_state.yaml b/api/client-server/room_state.yaml index bda66eb8..4b159a3c 100644 --- a/api/client-server/room_state.yaml +++ b/api/client-server/room_state.yaml @@ -70,7 +70,7 @@ paths: type: object example: { "membership": "join", - "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto", + "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" } responses: diff --git a/changelogs/client_server/newsfragments/2068.clarification b/changelogs/client_server/newsfragments/2068.clarification new file mode 100644 index 00000000..77ad7125 --- /dev/null +++ b/changelogs/client_server/newsfragments/2068.clarification @@ -0,0 +1 @@ +Clarify how the content repository works, and what it is used for. diff --git a/event-schemas/examples/m.room.member b/event-schemas/examples/m.room.member index b0aa59dd..18bc457b 100644 --- a/event-schemas/examples/m.room.member +++ b/event-schemas/examples/m.room.member @@ -4,7 +4,7 @@ "type": "m.room.member", "content": { "membership": "join", - "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto", + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" } } diff --git a/event-schemas/examples/m.room.member$invite_room_state b/event-schemas/examples/m.room.member$invite_room_state index f8f05484..9045dffd 100644 --- a/event-schemas/examples/m.room.member$invite_room_state +++ b/event-schemas/examples/m.room.member$invite_room_state @@ -2,7 +2,7 @@ "$ref": "m.room.member", "content": { "membership": "invite", - "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto", + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }, "unsigned": { diff --git a/event-schemas/examples/m.room.member$third_party_invite b/event-schemas/examples/m.room.member$third_party_invite index c688a283..a40d44f9 100644 --- a/event-schemas/examples/m.room.member$third_party_invite +++ b/event-schemas/examples/m.room.member$third_party_invite @@ -2,7 +2,7 @@ "$ref": "m.room.member", "content": { "membership": "invite", - "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF#auto", + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "third_party_invite": { "display_name": "alice", diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index 8ff27b1e..b6a45007 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -19,7 +19,7 @@ properties: type: integer thumbnail_url: description: |- - The URL to a thumbnail of the image. Only present if the + The `MXC URI`_ to a thumbnail of the image. Only present if the thumbnail is unencrypted. type: string thumbnail_file: diff --git a/event-schemas/schema/m.room.message$m.audio b/event-schemas/schema/m.room.message$m.audio index 99e28110..40075541 100644 --- a/event-schemas/schema/m.room.message$m.audio +++ b/event-schemas/schema/m.room.message$m.audio @@ -27,7 +27,7 @@ properties: - m.audio type: string url: - description: Required if the file is not encrypted. The URL to the audio clip. + description: Required if the file is not encrypted. The `MXC URI`_ to the audio clip. type: string file: description: |- diff --git a/event-schemas/schema/m.room.message$m.file b/event-schemas/schema/m.room.message$m.file index 2389d8a9..225ca61d 100644 --- a/event-schemas/schema/m.room.message$m.file +++ b/event-schemas/schema/m.room.message$m.file @@ -42,7 +42,7 @@ properties: - m.file type: string url: - description: Required if the file is unencrypted. The URL to the file. + description: Required if the file is unencrypted. The `MXC URI`_ to the file. type: string file: description: |- diff --git a/event-schemas/schema/m.room.message$m.image b/event-schemas/schema/m.room.message$m.image index 1e6ebeaa..8bf9c5fa 100644 --- a/event-schemas/schema/m.room.message$m.image +++ b/event-schemas/schema/m.room.message$m.image @@ -17,7 +17,7 @@ properties: - m.image type: string url: - description: Required if the file is unencrypted. The URL to the image. + description: Required if the file is unencrypted. The `MXC URI`_ to the image. type: string file: description: |- diff --git a/event-schemas/schema/m.room.message$m.video b/event-schemas/schema/m.room.message$m.video index 2da7e0bc..01286ce2 100644 --- a/event-schemas/schema/m.room.message$m.video +++ b/event-schemas/schema/m.room.message$m.video @@ -28,7 +28,7 @@ properties: type: integer thumbnail_url: description: |- - The URL to an image thumbnail of the video clip. Only present if the + The `MXC URI`_ to an image thumbnail of the video clip. Only present if the thumbnail is unencrypted. type: string thumbnail_file: @@ -48,7 +48,7 @@ properties: - m.video type: string url: - description: Required if the file is unencrypted. The URL to the video clip. + description: Required if the file is unencrypted. The `MXC URI`_ to the video clip. type: string file: description: |- diff --git a/specification/modules/content_repo.rst b/specification/modules/content_repo.rst index e7bdb044..823efb3c 100644 --- a/specification/modules/content_repo.rst +++ b/specification/modules/content_repo.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2019 The Matrix.org Foundation C.I.C. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -17,26 +18,37 @@ Content repository .. _module:content: -This module allows users to upload content to their homeserver which is -retrievable from other homeservers. Its' purpose is to allow users to share -attachments in a room. Content locations are represented as Matrix Content (MXC) -URIs. They look like:: +The content repository (or "media repository") allows users to upload +files to their homeserver for later user. For example, files which the +user wants to send to a room would be uploaded here, as would an avatar +the user wants to use. + +Uploads are POSTed to a resource on the user's local homeserver which +returns a MXC URI which can later be used to GET the download. Content +is downloaded from the recipient's local homeserver, which must first +transfer the content from the origin homeserver using the same API +(unless the origin and destination homeservers are the same). + +When serving content, the server SHOULD provide a ``Content-Security-Policy`` +header. The recommended policy is ``sandbox; default-src 'none'; script-src +'none'; plugin-types application/pdf; style-src 'unsafe-inline'; object-src +'self';``. + +Content in the repository should be treated as bytes as it may be encrypted. + +Matrix Content (MXC) URIs +------------------------- + +.. _`MXC URI`: + +Content locations are represented as Matrix Content (MXC) URIs. They look +like:: mxc:/// : The name of the homeserver where this content originated, e.g. matrix.org : An opaque ID which identifies the content. -Uploads are POSTed to a resource on the user's local homeserver which returns a -token which is used to GET the download. Content is downloaded from the -recipient's local homeserver, which must first transfer the content from the -origin homeserver using the same API (unless the origin and destination -homeservers are the same). - -When serving content, the server SHOULD provide a ``Content-Security-Policy`` -header. The recommended policy is ``sandbox; default-src 'none'; script-src -'none'; plugin-types application/pdf; style-src 'unsafe-inline'; object-src -'self';``. Client behaviour ---------------- @@ -47,6 +59,11 @@ Clients can upload and download content using the following HTTP APIs. Thumbnails ~~~~~~~~~~ +The homeserver SHOULD be able to supply thumbnails for uploaded images and +videos. The exact file types which can be thumbnailed are not currently +specified - see `Issue #1938 `_ +for more information. + The thumbnail methods are "crop" and "scale". "scale" tries to return an image where either the width or the height is smaller than the requested size. The client should then scale and letterbox the image if it needs to @@ -55,18 +72,32 @@ width and height are close to the requested size and the aspect matches the requested size. The client should scale the image if it needs to fit within a given rectangle. +The dimensions given to the thumbnail API are the minimum size the client +would prefer. Servers must never return thumbnails smaller than the client's +requested dimensions, unless the content being thumbnailed is smaller than +the dimensions. When the content is smaller than the requested dimensions, +servers should return the original content rather than thumbnail it. + +Servers SHOULD pre-calculate or have a list of set dimensions for which they +will thumbnail content at. For example, the server may choose that it will +only create thumbnails sized 96x96 or 512x512. When the client requests a +thumbnail, the server will pick the size which is larger than the requested +dimensions. Servers SHOULD pre-calculate the following thumbnails for uploaded +content, and limit thumbnails to the same sizes: + +* 32x32, crop +* 96x96, crop +* 320x240, scale +* 640x480, scale +* 800x600, scale + In summary: * "scale" maintains the original aspect ratio of the image * "crop" provides an image in the aspect ratio of the sizes given in the request + * The server will return an image larger than or equal to the dimensions requested + where possible. -Server behaviour ----------------- - -Homeservers may generate thumbnails for content uploaded to remote -homeservers themselves or may rely on the remote homeserver to thumbnail -the content. Homeservers may return thumbnails of a different size to that -requested. However homeservers should provide exact matches where reasonable. -Homeservers must never upscale images. +Servers MUST NOT upscale thumbnails under any circumstance. Security considerations ----------------------- @@ -88,16 +119,20 @@ UTF-8 encoded traversals, etc). Homeservers have additional content-specific concerns: - Clients may try to upload very large files. Homeservers should not store files - that are too large and should not serve them to clients. + that are too large and should not serve them to clients, returning a HTTP 413 + error with the ``M_TOO_LARGE`` code. - Clients may try to upload very large images. Homeservers should not attempt to - generate thumbnails for images that are too large. + generate thumbnails for images that are too large, returning a HTTP 413 error + with the ``M_TOO_LARGE`` code. - Remote homeservers may host very large files or images. Homeservers should not - proxy or thumbnail large files or images from remote homeservers. + proxy or thumbnail large files or images from remote homeservers, returning a + HTTP 502 error with the ``M_TOO_LARGE`` code. - Clients may try to upload a large number of files. Homeservers should limit the - number and total size of media that can be uploaded by clients. + number and total size of media that can be uploaded by clients, returning a + HTTP 403 error with the ``M_FORBIDDEN`` code. - Clients may try to access a large number of remote files through a homeserver. Homeservers should restrict the number and size of remote files that it caches. From dc6d89caca5ea165bfe472d82f696529e80feaab Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 2 Jun 2019 21:31:06 -0600 Subject: [PATCH 161/497] Split download endpoints back apart Apparently you can't have an optional path parameter. --- api/client-server/content-repo.yaml | 68 ++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 2 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 576d29ef..a9a0c2f6 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -100,11 +100,74 @@ paths: "$ref": "definitions/errors/rate_limited.yaml" tags: - Media - "/download/{serverName}/{mediaId}/{fileName}": + "/download/{serverName}/{mediaId}": get: summary: "Download content from the content repository." operationId: getContent produces: ["*/*"] + parameters: + - in: path + type: string + name: serverName + x-example: matrix.org + required: true + description: | + The server name from the ``mxc://`` URI (the authoritory component) + - in: path + type: string + name: mediaId + x-example: ascERGshawAWawugaAcauga + required: true + description: | + The media ID from the ``mxc://`` URI (the path component) + - in: query + type: boolean + name: allow_remote + x-example: false + required: false + default: true + description: | + Indicates to the server that it should not attempt to fetch the media if it is deemed + remote. This is to prevent routing loops where the server contacts itself. Defaults to + true if not provided. + responses: + 200: + description: "The content that was previously uploaded." + headers: + Content-Type: + description: "The content type of the file that was previously uploaded." + type: "string" + Content-Disposition: + description: |- + The name of the file that was previously uploaded, if set. + type: "string" + schema: + type: file + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + 502: + description: |- + The content is too large for the server to serve. + examples: + application/json: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Media + "/download/{serverName}/{mediaId}/{fileName}": + get: + summary: |- + Download content from the content repository. This is the same as + the download endpoint above, except permitting a desired file name. + operationId: getContentOverrideName + produces: ["*/*"] parameters: - in: path type: string @@ -124,7 +187,8 @@ paths: type: string name: fileName x-example: filename.jpg - description: An optional filename to give in the ``Content-Disposition`` header. + required: true + description: A filename to give in the ``Content-Disposition`` header. - in: query type: boolean name: allow_remote From 53aa8fe8ecc7e4d2028894a57395fe3e9340fc2c Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Mon, 3 Jun 2019 09:47:09 +0200 Subject: [PATCH 162/497] clarify the order events in chunk for /messages --- api/client-server/message_pagination.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index c9f9d0ae..7457530b 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -103,7 +103,7 @@ paths: chunk: type: array description: |- - A list of room events. + A list of room events. The order depends on the ``dir`` parameter. For ``dir=b`` events will be in reverse-chronological order, for ``dir=f`` in chronological order, so that events start at the ``from`` point. items: type: object title: RoomEvent From 0b42a17352356eb879ee21f264dddfdcc78ef647 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Mon, 3 Jun 2019 09:48:38 +0100 Subject: [PATCH 163/497] Update api/identity/definitions/request_email_validation.yaml Co-Authored-By: Travis Ralston --- api/identity/definitions/request_email_validation.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index 5d1aac8a..5f15bd41 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -40,7 +40,7 @@ properties: retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server - should response with success but not resend the email. + should respond with success but not resend the email. example: 1 next_link: type: string From 49b9bfc9f6ed5041807d8d893a29f9753381ad06 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 3 Jun 2019 09:48:53 +0100 Subject: [PATCH 164/497] Move changelog to the right place --- .../newsfragments/2057.clarification | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/{client_server => identity_service}/newsfragments/2057.clarification (100%) diff --git a/changelogs/client_server/newsfragments/2057.clarification b/changelogs/identity_service/newsfragments/2057.clarification similarity index 100% rename from changelogs/client_server/newsfragments/2057.clarification rename to changelogs/identity_service/newsfragments/2057.clarification From 39144942da1b235627b652909c0f21c8f57c33ea Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 3 Jun 2019 20:39:41 -0600 Subject: [PATCH 165/497] Fix title ordering --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index e6048c28..1fd28e93 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -668,7 +668,7 @@ Used basis. The maximum number of olm sessions maintained per device should be at least 4. Recovering from undecryptable messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< Occasionally messages may be undecryptable by clients due to a variety of reasons. When this happens to an Olm-encrypted message, the client should assume that the Olm From 8b28972a2d38935f3c5c7953ba40dbc5c36ddbcb Mon Sep 17 00:00:00 2001 From: Bruno Windels Date: Tue, 4 Jun 2019 09:28:01 +0200 Subject: [PATCH 166/497] PR feedback --- api/client-server/message_pagination.yaml | 5 ++++- changelogs/client_server/newsfragments/2069.clarification | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2069.clarification diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 7457530b..9a24537c 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -103,7 +103,10 @@ paths: chunk: type: array description: |- - A list of room events. The order depends on the ``dir`` parameter. For ``dir=b`` events will be in reverse-chronological order, for ``dir=f`` in chronological order, so that events start at the ``from`` point. + A list of room events. The order depends on the ``dir`` parameter. + For ``dir=b`` events will be in reverse-chronological order, + for ``dir=f`` in chronological order, so that events start + at the ``from`` point. items: type: object title: RoomEvent diff --git a/changelogs/client_server/newsfragments/2069.clarification b/changelogs/client_server/newsfragments/2069.clarification new file mode 100644 index 00000000..353b545d --- /dev/null +++ b/changelogs/client_server/newsfragments/2069.clarification @@ -0,0 +1 @@ +Clarify the order events in chunk are returned in for /messages From 042455d954699b486b5c732d848697d11fd6a5e4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 4 Jun 2019 10:58:39 -0600 Subject: [PATCH 167/497] Update changelog to appease style guidelines --- changelogs/client_server/newsfragments/2069.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2069.clarification b/changelogs/client_server/newsfragments/2069.clarification index 353b545d..127573a6 100644 --- a/changelogs/client_server/newsfragments/2069.clarification +++ b/changelogs/client_server/newsfragments/2069.clarification @@ -1 +1 @@ -Clarify the order events in chunk are returned in for /messages +Clarify the order events in chunk are returned in for ``/messages``. From a3364ff35712be278fc4f5914a89dbb27f41d08a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 4 Jun 2019 12:41:30 -0600 Subject: [PATCH 168/497] Spec SAS verification and the common key verification framework Reference implementations: * https://gitlab.matrix.org/matrix-org/olm/commit/94f664e7256215f33639dbbad6aaf87ada082a9f * https://github.com/matrix-org/matrix-react-sdk/pull/2461 * https://github.com/matrix-org/matrix-js-sdk/pull/818 * https://github.com/matrix-org/matrix-react-sdk/pull/2596 * https://github.com/matrix-org/matrix-js-sdk/pull/837 Proposals: * [MSC1717](https://github.com/matrix-org/matrix-doc/pull/1717) * [MSC1267](https://github.com/matrix-org/matrix-doc/issues/1267) No alterations to either proposal have been made intentionally here. --- .../client_server/newsfragments/2072.feature | 1 + data-definitions/sas-emoji.json | 66 ++++ .../examples/m.key.verification.accept | 12 + .../examples/m.key.verification.cancel | 8 + event-schemas/examples/m.key.verification.key | 7 + event-schemas/examples/m.key.verification.mac | 10 + .../examples/m.key.verification.request | 11 + .../examples/m.key.verification.start | 8 + .../m.key.verification.start$m.sas.v1 | 12 + .../schema/m.key.verification.accept | 64 ++++ .../schema/m.key.verification.cancel | 70 ++++ event-schemas/schema/m.key.verification.key | 28 ++ event-schemas/schema/m.key.verification.mac | 38 ++ .../schema/m.key.verification.request | 43 +++ event-schemas/schema/m.key.verification.start | 39 +++ .../schema/m.key.verification.start$m.sas.v1 | 69 ++++ scripts/continuserv/main.go | 2 +- .../templating/matrix_templates/sections.py | 17 + scripts/templating/matrix_templates/units.py | 20 ++ .../modules/end_to_end_encryption.rst | 325 +++++++++++++++++- 20 files changed, 847 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2072.feature create mode 100644 data-definitions/sas-emoji.json create mode 100644 event-schemas/examples/m.key.verification.accept create mode 100644 event-schemas/examples/m.key.verification.cancel create mode 100644 event-schemas/examples/m.key.verification.key create mode 100644 event-schemas/examples/m.key.verification.mac create mode 100644 event-schemas/examples/m.key.verification.request create mode 100644 event-schemas/examples/m.key.verification.start create mode 100644 event-schemas/examples/m.key.verification.start$m.sas.v1 create mode 100644 event-schemas/schema/m.key.verification.accept create mode 100644 event-schemas/schema/m.key.verification.cancel create mode 100644 event-schemas/schema/m.key.verification.key create mode 100644 event-schemas/schema/m.key.verification.mac create mode 100644 event-schemas/schema/m.key.verification.request create mode 100644 event-schemas/schema/m.key.verification.start create mode 100644 event-schemas/schema/m.key.verification.start$m.sas.v1 diff --git a/changelogs/client_server/newsfragments/2072.feature b/changelogs/client_server/newsfragments/2072.feature new file mode 100644 index 00000000..c7d8bd76 --- /dev/null +++ b/changelogs/client_server/newsfragments/2072.feature @@ -0,0 +1 @@ +Add interactive device verification, including a common framework for device verification. diff --git a/data-definitions/sas-emoji.json b/data-definitions/sas-emoji.json new file mode 100644 index 00000000..060fbd49 --- /dev/null +++ b/data-definitions/sas-emoji.json @@ -0,0 +1,66 @@ +[ + {"number": 0, "emoji": "🐶", "description": "Dog", "unicode": "U+1F436"}, + {"number": 1, "emoji": "🐱", "description": "Cat", "unicode": "U+1F431"}, + {"number": 2, "emoji": "🦁", "description": "Lion", "unicode": "U+1F981"}, + {"number": 3, "emoji": "🐎", "description": "Horse", "unicode": "U+1F40E"}, + {"number": 4, "emoji": "🦄", "description": "Unicorn", "unicode": "U+1F984"}, + {"number": 5, "emoji": "🐷", "description": "Pig", "unicode": "U+1F437"}, + {"number": 6, "emoji": "🐘", "description": "Elephant", "unicode": "U+1F418"}, + {"number": 7, "emoji": "🐰", "description": "Rabbit", "unicode": "U+1F430"}, + {"number": 8, "emoji": "🐼", "description": "Panda", "unicode": "U+1F43C"}, + {"number": 9, "emoji": "🐓", "description": "Rooster", "unicode": "U+1F413"}, + {"number": 10, "emoji": "🐧", "description": "Penguin", "unicode": "U+1F427"}, + {"number": 11, "emoji": "🐢", "description": "Turtle", "unicode": "U+1F422"}, + {"number": 12, "emoji": "🐟", "description": "Fish", "unicode": "U+1F41F"}, + {"number": 13, "emoji": "🐙", "description": "Octopus", "unicode": "U+1F419"}, + {"number": 14, "emoji": "🦋", "description": "Butterfly", "unicode": "U+1F98B"}, + {"number": 15, "emoji": "🌷", "description": "Flower", "unicode": "U+1F337"}, + {"number": 16, "emoji": "🌳", "description": "Tree", "unicode": "U+1F333"}, + {"number": 17, "emoji": "🌵", "description": "Cactus", "unicode": "U+1F335"}, + {"number": 18, "emoji": "🍄", "description": "Mushroom", "unicode": "U+1F344"}, + {"number": 19, "emoji": "🌏", "description": "Globe", "unicode": "U+1F30F"}, + {"number": 20, "emoji": "🌙", "description": "Moon", "unicode": "U+1F319"}, + {"number": 21, "emoji": "☁️", "description": "Cloud", "unicode": "U+2601U+FE0F"}, + {"number": 22, "emoji": "🔥", "description": "Fire", "unicode": "U+1F525"}, + {"number": 23, "emoji": "🍌", "description": "Banana", "unicode": "U+1F34C"}, + {"number": 24, "emoji": "🍎", "description": "Apple", "unicode": "U+1F34E"}, + {"number": 25, "emoji": "🍓", "description": "Strawberry", "unicode": "U+1F353"}, + {"number": 26, "emoji": "🌽", "description": "Corn", "unicode": "U+1F33D"}, + {"number": 27, "emoji": "🍕", "description": "Pizza", "unicode": "U+1F355"}, + {"number": 28, "emoji": "🎂", "description": "Cake", "unicode": "U+1F382"}, + {"number": 29, "emoji": "❤️", "description": "Heart", "unicode": "U+2764U+FE0F"}, + {"number": 30, "emoji": "😀", "description": "Smiley", "unicode": "U+1F600"}, + {"number": 31, "emoji": "🤖", "description": "Robot", "unicode": "U+1F916"}, + {"number": 32, "emoji": "🎩", "description": "Hat", "unicode": "U+1F3A9"}, + {"number": 33, "emoji": "👓", "description": "Glasses", "unicode": "U+1F453"}, + {"number": 34, "emoji": "🔧", "description": "Spanner", "unicode": "U+1F527"}, + {"number": 35, "emoji": "🎅", "description": "Santa", "unicode": "U+1F385"}, + {"number": 36, "emoji": "👍", "description": "Thumbs Up", "unicode": "U+1F44D"}, + {"number": 37, "emoji": "☂️", "description": "Umbrella", "unicode": "U+2602U+FE0F"}, + {"number": 38, "emoji": "⌛", "description": "Hourglass", "unicode": "U+231B"}, + {"number": 39, "emoji": "⏰", "description": "Clock", "unicode": "U+23F0"}, + {"number": 40, "emoji": "🎁", "description": "Gift", "unicode": "U+1F381"}, + {"number": 41, "emoji": "💡", "description": "Light Bulb", "unicode": "U+1F4A1"}, + {"number": 42, "emoji": "📕", "description": "Book", "unicode": "U+1F4D5"}, + {"number": 43, "emoji": "✏️", "description": "Pencil", "unicode": "U+270FU+FE0F"}, + {"number": 44, "emoji": "📎", "description": "Paperclip", "unicode": "U+1F4CE"}, + {"number": 45, "emoji": "✂️", "description": "Scissors", "unicode": "U+2702U+FE0F"}, + {"number": 46, "emoji": "🔒", "description": "Lock", "unicode": "U+1F512"}, + {"number": 47, "emoji": "🔑", "description": "Key", "unicode": "U+1F511"}, + {"number": 48, "emoji": "🔨", "description": "Hammer", "unicode": "U+1F528"}, + {"number": 49, "emoji": "☎️", "description": "Telephone", "unicode": "U+260EU+FE0F"}, + {"number": 50, "emoji": "🏁", "description": "Flag", "unicode": "U+1F3C1"}, + {"number": 51, "emoji": "🚂", "description": "Train", "unicode": "U+1F682"}, + {"number": 52, "emoji": "🚲", "description": "Bicycle", "unicode": "U+1F6B2"}, + {"number": 53, "emoji": "✈️", "description": "Aeroplane", "unicode": "U+2708U+FE0F"}, + {"number": 54, "emoji": "🚀", "description": "Rocket", "unicode": "U+1F680"}, + {"number": 55, "emoji": "🏆", "description": "Trophy", "unicode": "U+1F3C6"}, + {"number": 56, "emoji": "⚽", "description": "Ball", "unicode": "U+26BD"}, + {"number": 57, "emoji": "🎸", "description": "Guitar", "unicode": "U+1F3B8"}, + {"number": 58, "emoji": "🎺", "description": "Trumpet", "unicode": "U+1F3BA"}, + {"number": 59, "emoji": "🔔", "description": "Bell", "unicode": "U+1F514"}, + {"number": 60, "emoji": "⚓", "description": "Anchor", "unicode": "U+2693"}, + {"number": 61, "emoji": "🎧", "description": "Headphones", "unicode": "U+1F3A7"}, + {"number": 62, "emoji": "📁", "description": "Folder", "unicode": "U+1F4C1"}, + {"number": 63, "emoji": "📌", "description": "Pin", "unicode": "U+1F4CC"} +] diff --git a/event-schemas/examples/m.key.verification.accept b/event-schemas/examples/m.key.verification.accept new file mode 100644 index 00000000..98e89c06 --- /dev/null +++ b/event-schemas/examples/m.key.verification.accept @@ -0,0 +1,12 @@ +{ + "type": "m.key.verification.accept", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "method": "m.sas.v1", + "key_agreement_protocol": "curve25519", + "hash": "sha256", + "message_authentication_code": "hkdf-hmac-sha256", + "short_authentication_string": ["decimal", "emoji"], + "commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } +} diff --git a/event-schemas/examples/m.key.verification.cancel b/event-schemas/examples/m.key.verification.cancel new file mode 100644 index 00000000..9d78f67c --- /dev/null +++ b/event-schemas/examples/m.key.verification.cancel @@ -0,0 +1,8 @@ +{ + "type": "m.key.verification.cancel", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "code": "m.user", + "reason": "User rejected the key verification request" + } +} diff --git a/event-schemas/examples/m.key.verification.key b/event-schemas/examples/m.key.verification.key new file mode 100644 index 00000000..608a2ebd --- /dev/null +++ b/event-schemas/examples/m.key.verification.key @@ -0,0 +1,7 @@ +{ + "type": "m.key.verification.key", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } +} diff --git a/event-schemas/examples/m.key.verification.mac b/event-schemas/examples/m.key.verification.mac new file mode 100644 index 00000000..c77c3a8d --- /dev/null +++ b/event-schemas/examples/m.key.verification.mac @@ -0,0 +1,10 @@ +{ + "type": "m.key.verification.mac", + "content": { + "transaction_id": "S0meUniqueAndOpaqueString", + "keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA", + "mac": { + "ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } +} diff --git a/event-schemas/examples/m.key.verification.request b/event-schemas/examples/m.key.verification.request new file mode 100644 index 00000000..258471d2 --- /dev/null +++ b/event-schemas/examples/m.key.verification.request @@ -0,0 +1,11 @@ +{ + "type": "m.key.verification.request", + "content": { + "from_device": "AliceDevice2", + "transaction_id": "S0meUniqueAndOpaqueString", + "methods": [ + "m.sas.v1" + ], + "timestamp": 1559598944869 + } +} diff --git a/event-schemas/examples/m.key.verification.start b/event-schemas/examples/m.key.verification.start new file mode 100644 index 00000000..52f16150 --- /dev/null +++ b/event-schemas/examples/m.key.verification.start @@ -0,0 +1,8 @@ +{ + "type": "m.key.verification.start", + "content": { + "from_device": "BobDevice1", + "transaction_id": "S0meUniqueAndOpaqueString", + "method": "m.sas.v1" + } +} diff --git a/event-schemas/examples/m.key.verification.start$m.sas.v1 b/event-schemas/examples/m.key.verification.start$m.sas.v1 new file mode 100644 index 00000000..dae1d405 --- /dev/null +++ b/event-schemas/examples/m.key.verification.start$m.sas.v1 @@ -0,0 +1,12 @@ +{ + "type": "m.key.verification.start", + "content": { + "from_device": "BobDevice1", + "transaction_id": "S0meUniqueAndOpaqueString", + "method": "m.sas.v1", + "key_agreement_protocols": ["curve25519"], + "hashes": ["sha256"], + "message_authentication_codes": ["hkdf-hmac-sha256"], + "short_authentication_string": ["decimal", "emoji"] + } +} diff --git a/event-schemas/schema/m.key.verification.accept b/event-schemas/schema/m.key.verification.accept new file mode 100644 index 00000000..e52df39e --- /dev/null +++ b/event-schemas/schema/m.key.verification.accept @@ -0,0 +1,64 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Accepts a previously sent ``m.key.verification.start`` messge. Typically sent as a + `to-device`_ event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be the same as + the one used for the ``m.key.verification.start`` message. + method: + type: string + enum: ["m.sas.v1"] + description: |- + The verification method to use. Must be ``m.sas.v1``. + key_agreement_protocol: + type: string + description: |- + The key agreement protocol the device is choosing to use, out of the + options in the ``m.key.verification.start`` message. + hash: + type: string + description: |- + The hash method the device is choosing to use, out of the options in + the ``m.key.verification.start`` message. + message_authentication_code: + type: string + description: |- + The message authentication code the device is choosing to use, out of + the options in the ``m.key.verification.start`` message. + short_authentication_string: + type: array + description: |- + The SAS methods both devices involved in the verification process + understand. Must be a subset of the options in the ``m.key.verification.start`` + message. + items: + type: string + enum: ["decimal", "emoji"] + commitment: + type: string + description: |- + The hash (encoded as unpadded base64) of the concatenation of the device's + ephemeral public key (encoded as unpadded base64) and the canonical JSON + representation of the ``m.key.verification.start`` message. + required: + - transaction_id + - method + - key_agreement_protocol + - hash + - message_authentication_code + - short_authentication_string + - commitment + type: object + type: + enum: + - m.key.verification.accept + type: string +type: object diff --git a/event-schemas/schema/m.key.verification.cancel b/event-schemas/schema/m.key.verification.cancel new file mode 100644 index 00000000..36ffc9ea --- /dev/null +++ b/event-schemas/schema/m.key.verification.cancel @@ -0,0 +1,70 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Cancels a key verification process/request. Typically sent as a `to-device`_ event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + The opaque identifier for the verification process/request. + reason: + type: string + description: |- + A human readable description of the ``code``. The client should only rely on this + string if it does not understand the ``code``. + code: + type: string + # Note: this is not an enum because we go into detail about the different + # error codes. If we made this an enum, we'd be repeating information. + # Also, we can't put a real bulleted list in here because the HTML2RST parser + # cuts the text at weird points, breaking the list completely. + description: |- + The error code for why the process/request was cancelled by the user. Error + codes should use the Java package naming convention if not in the following + list: + + ``m.user``: The user cancelled the verification. + + ``m.timeout``: The verification process timed out. Verification processes + can define their own timeout parameters. + + ``m.unknown_transaction``: The device does not know about the given transaction + ID. + + ``m.unknown_method``: The device does not know how to handle the requested + method. This should be sent for ``m.key.verification.start`` messages and + messages defined by individual verification processes. + + ``m.unexpected_message``: The device received an unexpected message. Typically + raised when one of the parties is handling the verification out of order. + + ``m.key_mismatch``: The key was not verified. + + ``m.user_mismatch``: The expected user did not match the user verified. + + ``m.invalid_message``: The message received was invalid. + + ``m.accepted``: A ``m.key.verification.request`` was accepted by a different + device. The device receiving this error can ignore the verification request. + + Clients should be careful to avoid error loops. For example, if a device sends + an incorrect message and the client returns ``m.invalid_message`` to which it + gets an unexpected response with ``m.unexpected_message``, the client should not + respond again with ``m.unexpected_message`` to avoid the other device potentially + sending another error response. + + .. The above blank line is important for RST. + required: + - transaction_id + - code + - reason + type: object + type: + enum: + - m.key.verification.cancel + type: string +type: object diff --git a/event-schemas/schema/m.key.verification.key b/event-schemas/schema/m.key.verification.key new file mode 100644 index 00000000..6dc4954b --- /dev/null +++ b/event-schemas/schema/m.key.verification.key @@ -0,0 +1,28 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Sends the ephemeral public key for a device to the partner device. Typically sent as a + `to-device`_ event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be the same as + the one used for the ``m.key.verification.start`` message. + key: + type: string + description: |- + The device's ephemeral public key, encoded as unpadded base64. + required: + - transaction_id + - key + type: object + type: + enum: + - m.key.verification.key + type: string +type: object diff --git a/event-schemas/schema/m.key.verification.mac b/event-schemas/schema/m.key.verification.mac new file mode 100644 index 00000000..769ebe15 --- /dev/null +++ b/event-schemas/schema/m.key.verification.mac @@ -0,0 +1,38 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Sends the MAC of a device's key to the partner device. Typically sent as a + `to-device`_ event. +properties: + content: + properties: + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be the same as + the one used for the ``m.key.verification.start`` message. + mac: + type: object + description: |- + A map of the key ID to the MAC of the key, using the algorithm in the + verification process. The MAC is encoded as unpadded base64. + additionalProperties: + type: string + description: The key's MAC, encoded as unpadded base64. + keys: + type: string + description: |- + The MAC of the comma-separated, sorted, list of key IDs given in the ``mac`` + property, encoded as unpadded base64. + required: + - transaction_id + - mac + - keys + type: object + type: + enum: + - m.key.verification.mac + type: string +type: object diff --git a/event-schemas/schema/m.key.verification.request b/event-schemas/schema/m.key.verification.request new file mode 100644 index 00000000..c9efa14e --- /dev/null +++ b/event-schemas/schema/m.key.verification.request @@ -0,0 +1,43 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Requests a key verification with another user's devices. Typically sent as a + `to-device`_ event. +properties: + content: + properties: + from_device: + type: string + description: |- + The device ID which is initiating the request. + transaction_id: + type: string + description: |- + An opaque identifier for the verification request. Must be unique + with respect to the devices involved. + methods: + type: array + description: |- + The verification methods supported by the sender. + items: + type: string + timestamp: + type: integer + format: int64 + description: |- + The POSIX timestamp in milliseconds for when the request was made. If + the request is in the future by more than 5 minutes or more than 10 + minutes in the past, the message should be ignored by the receiver. + required: + - from_device + - transaction_id + - methods + - timestamp + type: object + type: + enum: + - m.key.verification.request + type: string +type: object diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start new file mode 100644 index 00000000..ad59d6c7 --- /dev/null +++ b/event-schemas/schema/m.key.verification.start @@ -0,0 +1,39 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Begins a key verification process. Typically sent as a `to-device`_ event. +properties: + content: + properties: + from_device: + type: string + description: |- + The device ID which is initiating the process. + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be unique + with respect to the devices involved. Must be the same as the + ``transaction_id`` given in the ``m.key.verification.request`` + if this process is originating from a request. + method: + type: string + description: |- + The verification method to use. + next_method: + type: string + description: |- + Optional method to use to verify the other user's key with. Applicable + when the ``method`` chosen only verifies one user's key. + required: + - from_device + - transaction_id + - method + type: object + type: + enum: + - m.key.verification.start + type: string +type: object diff --git a/event-schemas/schema/m.key.verification.start$m.sas.v1 b/event-schemas/schema/m.key.verification.start$m.sas.v1 new file mode 100644 index 00000000..867ca820 --- /dev/null +++ b/event-schemas/schema/m.key.verification.start$m.sas.v1 @@ -0,0 +1,69 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + Begins a SAS key verification process. Typically sent as a `to-device`_ event. +properties: + content: + properties: + from_device: + type: string + description: |- + The device ID which is initiating the process. + transaction_id: + type: string + description: |- + An opaque identifier for the verification process. Must be unique + with respect to the devices involved. Must be the same as the + ``transaction_id`` given in the ``m.key.verification.request`` + if this process is originating from a request. + method: + type: string + enum: ["m.sas.v1"] + description: |- + The verification method to use. Must be ``m.sas.v1``. + key_agreement_protocols: + type: array + description: |- + The key agreement protocols the sending device understands. Must + include at least ``curve25519``. + items: + type: string + hashes: + type: array + description: |- + The hash methods the sending device understands. Must include at least + ``sha256``. + items: + type: string + message_authentication_codes: + type: array + description: |- + The message authentication codes that the sending device understands. + Must include at least ``hkdf-hmac-sha256``. + items: + type: string + short_authentication_string: + type: array + description: |- + The SAS methods the sending device (and the sending device's user) + understands. Must include at least ``decimal``. Optionally can include + ``emoji``. + items: + type: string + enum: ["decimal", "emoji"] + required: + - from_device + - transaction_id + - method + - key_agreement_protocols + - hashes + - message_authentication_codes + - short_authentication_string + type: object + type: + enum: + - m.key.verification.start + type: string +type: object diff --git a/scripts/continuserv/main.go b/scripts/continuserv/main.go index 2ef6fed9..1bd07e6e 100644 --- a/scripts/continuserv/main.go +++ b/scripts/continuserv/main.go @@ -52,7 +52,7 @@ func main() { walker := makeWalker(dir, w) paths := []string{"api", "changelogs", "event-schemas", "scripts", - "specification"} + "specification", "schemas", "data-definitions"} for _, p := range paths { filepath.Walk(path.Join(dir, p), walker) diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index c88959ed..7000916b 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -18,6 +18,7 @@ import inspect import json import os import logging +import re logger = logging.getLogger(__name__) @@ -225,3 +226,19 @@ class MatrixSections(Sections): examples=swagger_def['examples'], title_kind=subtitle_title_char) return rendered + + def render_sas_emoji_table(self): + emoji = self.units.get("sas_emoji") + rendered = ".. csv-table::\n" + rendered += " :header: \"Number\", \"Emoji\", \"Unicode\", \"Description\"\n" + rendered += " :widths: 10, 10, 15, 20\n" + rendered += "\n" + for row in emoji: + rendered += " %d, \"%s\", \"``%s``\", \"%s\"\n" % ( + row['number'], + row['emoji'], + row['unicode'], + row['description'], + ) + rendered += "\n" + return rendered diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index ddb65efe..fe3ba5d2 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -59,6 +59,8 @@ TARGETS = os.path.join(matrix_doc_dir, "specification/targets.yaml") ROOM_EVENT = "core-event-schema/room_event.yaml" STATE_EVENT = "core-event-schema/state_event.yaml" +SAS_EMOJI_JSON = os.path.join(matrix_doc_dir, "data-definitions/sas-emoji.json") + logger = logging.getLogger(__name__) # a yaml Loader which loads mappings into OrderedDicts instead of regular @@ -1088,3 +1090,21 @@ class MatrixUnits(Units): "string": git_version, "revision": git_commit } + + def load_sas_emoji(self): + with open(SAS_EMOJI_JSON, 'r', encoding='utf-8') as sas_json: + emoji = json.load(sas_json) + + # Verify the emoji matches the unicode + for c in emoji: + e = c['emoji'] + logger.info("Checking emoji %s (%s)", e, c['description']) + u = re.sub(r'U\+([0-9a-fA-F]+)', lambda m: chr(int(m.group(1), 16)), c['unicode']) + if e != u: + raise Exception("Emoji %s should be %s not %s" % ( + c['description'], + repr(e), + c['unicode'], + )) + + return emoji diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 1fd28e93..4bd12b71 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -396,8 +396,8 @@ recommended that clients provide mechanisms by which the user can see: Ed25519 signing key for each device, again encoded using unpadded Base64. Alice can then meet Bob in person, or contact him via some other trusted -medium, and ask him to read out the Ed25519 key shown on his device. She -compares this with the value shown for his device on her client. +medium, and use `SAS Verification`_ or ask him to read out the Ed25519 key +shown on his device, comparing it to the one shown on Alice's device. Device verification may reach one of several conclusions. For example: @@ -423,6 +423,327 @@ Device verification may reach one of several conclusions. For example: decrypted by such a device. For the Olm protocol, this is documented at https://matrix.org/git/olm/about/docs/signing.rst. + +Key verification framework +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Verifying keys manually by reading out the Ed25519 key is not very user friendly, +and can lead to errors. In order to help mitigate errors, and to make the process +eaiser for users, some verification methods are supported by the specification. +The methods all use a common framework for negotiating the key verification. + +To use this framework, Alice's client would send ``m.key.verification.request`` +events to Bob's devices. All of the ``to_device`` messages sent to Bob MUST have +the same ``transaction_id`` to indicate they are part of the same request. This +allows Bob to reject the request on one device, and have it apply to all of his +devices. Similarly, it allows Bob to process the verification on one device without +having to involve all of his devices. + +When Bob's device receives a ``m.key.verification.request``, it should prompt Bob +to verify keys with Alice using one of the supported methods in the request. If +Bob's device does not understand any of the methods, it should not cancel the request +as one of his other devices may support the request. Instead, Bob's device should +tell Bob that an unsupported method was used for starting key verification. The +prompt for Bob to accept/reject Alice's request (or the unsupported method prompt) +should be automatically dismissed 10 minutes after the ``timestamp`` field or 2 +minutes after Bob's client receives the message, whichever comes first, if Bob +does not interact with the prompt. The prompt should additionally be hidden if +an appropriate ``m.key.verification.cancel`` message is received. + +If Bob rejects the request, Bob's client must send a ``m.key.verification.cancel`` +message to Alice's device. Upon receipt, Alice's device should tell her that Bob +does not want to verify her device and send ``m.key.verification.cancel`` messages +to all of Bob's devices to notify them that the request was rejected. + +If Bob accepts the request, Bob's device starts the key verification process by +sending a ``m.key.verification.start`` message to Alice's device. Upon receipt +of this message, Alice's device should send a ``m.key.verification.cancel`` message +to all of Bob's other devices to indicate the process has been started. The start +message must use the same ``transaction_id`` from the original key verification +request if it is in response to the request. The start message can be sent indepdently +of any request. + +Individual verification methods may add additional steps, events, and properties to +the verification messages. Event types for methods defined in this specification must +be under the ``m.key.verification`` namespace and any other event types must be namespaced +according to the Java package naming convention. + +Any of Alice's or Bob's devices can cancel the key verification request or process +at any time with a ``m.key.verification.cancel`` message to all applicable devices. + +This framework yields the following handshake, assuming both Alice and Bob each have +2 devices, Bob's first device accepts the key verification request, and Alice's second +device initiates the request. Note how Alice's first device is not involved in the +request or verification process. + +:: + + +---------------+ +---------------+ +-------------+ +-------------+ + | AliceDevice1 | | AliceDevice2 | | BobDevice1 | | BobDevice2 | + +---------------+ +---------------+ +-------------+ +-------------+ + | | | | + | | m.key.verification.request | | + | |---------------------------------->| | + | | | | + | | m.key.verification.request | | + | |-------------------------------------------------->| + | | | | + | | m.key.verification.start | | + | |<----------------------------------| | + | | | | + | | m.key.verification.cancel | | + | |-------------------------------------------------->| + | | | | + + +After the handshake, the verification process begins. + +{{m_key_verification_request_event}} + +{{m_key_verification_start_event}} + +{{m_key_verification_cancel_event}} + + +.. _`SAS Verification`: + +Short Authentication String (SAS) verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SAS verification is a user-friendly key verification process built off the common +framework outlined above. SAS verification is intended to be a highly interactive +process for users, and as such exposes verfiication methods which are easier for +users to use. + +The verification process is heavily inspired by Phil Zimmerman's ZRTP key agreement +handshake. A key part of key agreement in ZRTP is the hash commitment: the party that +begins the Diffie-Hellman key sharing sends a hash of their part of the Diffie-Hellman +exchange, and does not send their part of the Diffie-Hellman exchange until they have +received the other party's part. Thus an attacker essentially only has one attempt to +attack the Diffie-Hellman exchange, and hence we can verify fewer bits while still +achieving a high degree of security: if we verify n bits, then an attacker has a 1 in +2\ :sup:`n` chance of success. For example, if we verify 40 bits, then an attacker has +a 1 in 1,099,511,627,776 chance (or less than 1 in 1012 chance) of success. A failed +attack would result in a mismatched Short Authentication String, alerting users to the +attack. + +The verification process takes place over `to-device`_ messages in two phases: + +1. Key agreement phase (based on `ZRTP key agreement `_). +#. Key verification phase (based on HMAC). + +The process between Alice and Bob verifying each other would be: + +.. |AlicePublicKey| replace:: :math:`K_{A}^{public}` +.. |AlicePrivateKey| replace:: :math:`K_{A}^{private}` +.. |AliceCurve25519| replace:: :math:`K_{A}^{private}K_{A}^{public}` +.. |BobPublicKey| replace:: :math:`K_{B}^{public}` +.. |BobPrivateKey| replace:: :math:`K_{B}^{private}` +.. |BobCurve25519| replace:: :math:`K_{B}^{private}K_{B}^{public}` +.. |AliceBobCurve25519| replace:: :math:`K_{A}^{private}K_{B}^{public}` +.. |BobAliceCurve25519| replace:: :math:`K_{B}^{private}K_{A}^{public}` +.. |AliceBobECDH| replace:: :math:`ECDH(K_{A}^{private},K_{B}^{public})` + +1. Alice and Bob establish a secure connection, likely meeting in-person. "Secure" + here means that either party cannot be impersonated, not explicit secrecy. +#. Alice and Bob communicate which devices they'd like to verify with each other. +#. Alice selects Bob's device from the device list and begins verification. +#. Alice's client ensures it has a copy of Bob's device key. +#. Alice's device sends Bob's device a ``m.key.verification.start`` message. +#. Bob's device receives the message and selects a key agreement protocol, hash + algorithm, message authentication code, and SAS method supported by Alice's + device. +#. Bob's device ensures it has a copy of Alice's device key. +#. Bob's device creates an ephemeral Curve25519 key pair (|BobCurve25519|), and + calculates the hash (using the chosen algorithm) of the public key |BobPublicKey|. +#. Bob's device replies to Alice's device with a ``m.key.verification.accept`` message. +#. Alice's device receives Bob's message and stores the commitment hash for later use. +#. Alice's device creates an ephemeral Curve25519 key pair (|AliceCurve25519|) and + replies to Bob's device with a ``m.key.verification.key``, sending only the public + key |AlicePublicKey|. +#. Bob's device receives Alice's message and replies with its own ``m.key.verification.key`` + message containing its public key |BobPublicKey|. +#. Alice's device receives Bob's message and verifies the commitment hash from earlier + matches the hash of the key Bob's device just sent and the content of Alice's + ``m.key.verification.start`` message. +#. Both Alice and Bob's devices perform an Elliptic-curve Diffie-Hellman (|AliceBobECDH|), + using the result as the shared secret. +#. Both Alice and Bob's devices display a SAS to their users, which is derived + from the shared key using one of the methods in this section. If multiple SAS + methods are available, clients should allow the users to select a method. +#. Alice and Bob compare the strings shown by their devices, and tell their devices if + they match or not. +#. Assuming they match, Alice and Bob's devices calculate the HMAC of their own device + and a comma-separated sorted list of of the key IDs that they wish the other user + to verify. HMAC is defined in RFC 2104, and SHA-256 as the hash function. The key for + the HMAC is different for each item and is calculated by generating 32 bytes (256 bits) + using `the key verification HKDF <#SAS-HKDF>`_. +#. Alice's device sends Bob's device a ``m.key.verification.mac`` message containing the + MAC of Alice's device keys and the MAC of her key IDs to be verified. Bob's device does + the same for Bob's device keys and key IDs concurrently with Alice. +#. When the other device receives the ``m.key.verification.mac`` message, the device + calculates the HMAC of its copies of the other device's keys given in the message, + as well as the HMAC of the comma-seperated, sorted, list of key IDs in the message. + The device compares these with the HMAC values given in the message, and if everything + matches then the device keys are verified. + +The wire protocol looks like the following between Alice and Bob's devices:: + + +-------------+ +-----------+ + | AliceDevice | | BobDevice | + +-------------+ +-----------+ + | | + | m.key.verification.start | + |-------------------------------->| + | | + | m.key.verification.accept | + |<--------------------------------| + | | + | m.key.verification.key | + |-------------------------------->| + | | + | m.key.verification.key | + |<--------------------------------| + | | + | m.key.verification.mac | + |-------------------------------->| + | | + | m.key.verification.mac | + |<--------------------------------| + | | + +Error and exception handling +<<<<<<<<<<<<<<<<<<<<<<<<<<<< + +At any point the interactive verfication can go wrong. The following describes what +to do when an error happens: + +* Alice or Bob can cancel the verification at any time. A ``m.key.verification.cancel`` + message must be sent to signify the cancelation. +* The verification can time out. Clients should time out a verification that does not + complete within 5 minutes. Additionally, clients should expire a ``transaction_id`` + which goes unused for 5 minutes after having last sent/received it. The client should + inform the user that the verification timed out, and send an appropriate ``m.key.verification.cancel`` + message to the other device. +* When the same device attempts to intiate multiple verification attempts, cancel all + attempts with that device. +* When a device receives an unknown ``transaction_id``, it should send an appropriate + ``m.key.verfication.cancel`` message to the other device indicating as such. This + does not apply for inbound ``m.key.verification.start`` or ``m.key.verification.cancel`` + messages. +* If the two devices do not share a common key share, hash, HMAC, or SAS method then + the device should notify the other device with an appropriate ``m.key.verification.cancel`` + message. +* If the user claims the Short Authentication Strings do not match, the device should + send an appropriate ``m.key.verification.cancel`` message to the other device. +* If the device receives a message out of sequence or that it was not expecting, it should + notify the other device with an appropriate ``m.key.verification.cancel`` message. + + +Verification messages specific to SAS +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< + +Building off the common framework, the following events are involved in SAS verification. + +The ``m.key.verification.cancel`` event is unchanged, however the following error codes +are used in addition to those already specified: + +* ``m.unknown_method``: The devices are unable to agree on the key agreement, hash, MAC, + or SAS method. +* ``m.mismatched_commitment``: The hash commitment did not match. +* ``m.mismatched_sas``: The SAS did not match. + + +{{m_key_verification_start_m_sas_v1_event}} + +{{m_key_verification_accept_event}} + +{{m_key_verification_key_event}} + +{{m_key_verification_mac_event}} + + +.. _`SAS-HKDF`: + +HKDF calculation +<<<<<<<<<<<<<<<< + +In all of the SAS methods, HKDF is as defined in RFC 5869 and uses the previously +agreed upon hash function for the hash function. The shared secret is supplied +as the input keying material. No salt is used, and the input parameter is the +concatenation of: + + * The string ``MATRIX_KEY_VERIFICATION_SAS``. + * The Matrix ID of the user who sent the ``m.key.verification.start`` message. + * The Device ID of the device which sent the ``m.key.verification.start`` message. + * The Matrix ID of the user who sent the ``m.key.verification.accept`` message. + * The Device ID of the device which sent the ``m.key.verification.accept`` message. + * The ``transaction_id`` being used. + +HKDF is used over the plain shared secret as it results in a harder attack +as well as more uniform data to work with. + +For verification of each party's device keys, HKDF is as defined in RFC 5869 and +uses SHA-256 as the hash function. The shared secret is supplied as the input keying +material. No salt is used, and in the input parameter is the concatenation of: + + * The string ``MATRIX_KEY_VERIFICATION_MAC``. + * The Matrix ID of the user whose key is being MAC-ed. + * The Device ID of the device sending the MAC. + * The Matrix ID of the other user. + * The Device ID of the device receiving the MAC. + * The ``transaction_id`` being used. + * The Key ID of the key being MAC-ed, or the string ``KEY_IDS`` if the item + being MAC-ed is the list of key IDs. + +SAS method: ``decimal`` +<<<<<<<<<<<<<<<<<<<<<<< + +Generate 5 bytes using `HKDF <#SAS-HKDF>`_ then take sequences of 13 bits to +convert to decimal numbers (resulting in 3 numbers between 0 and 8191 inclusive +each). Add 1000 to each calculated number. + +The bitwise operations to get the numbers given the 5 bytes +:math:`B_{0}, B_{1}, B_{2}, B_{3}, B_{4}` would be: + +* First: :math:`(B_{0} \ll 5 | B_{1} \gg 3) + 1000` +* Second: :math:`(B_{1} \& 0x7 | B_{2} \ll 2 | B_{3} \gg 6) + 1000` +* Third: :math:`((B_{3} \& 0x3F) \ll 7 | B_{4} \gg 1) + 1000` + +The digits are displayed to the user either with an appropriate separator, +such as dashes, or with the numbers on individual lines. + +SAS method: ``emoji`` +<<<<<<<<<<<<<<<<<<<<< + +Generate 6 bytes using `HKDF <#SAS-HKDF>`_ then split the first 42 bits into +7 groups of 6 bits, similar to how one would base64 encode something. Convert +each group of 6 bits to a number and use the following table to get the corresponding +emoji: + +{{sas_emoji_table}} + +.. Note:: + This table is available as JSON at + https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json + +.. admonition:: Rationale + + The emoji above were chosen to: + + * Be recognisable without colour. + * Be recognisable at a small size. + * Be recognisable by most cultures. + * Be distinguishable from each other. + * Easily described by a few words. + * Avoid symbols with negative connotations. + * Be likely similar across multiple platforms. + +Clients SHOULD show the emoji with the descriptions from the table, or appropriate +translation of those descriptions. Client authors SHOULD collaborate to create a +common set of translations for all languages. + + .. section name changed, so make sure that old links keep working .. _key-sharing: From 37b1e171fc182d3a055190b02f3cfe7c7ea9cd99 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 4 Jun 2019 23:51:10 +0100 Subject: [PATCH 169/497] MSC2076: Enforce key-validity periods when validating event signatures --- proposals/2076-enforce-validity-periods.md | 42 ++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 proposals/2076-enforce-validity-periods.md diff --git a/proposals/2076-enforce-validity-periods.md b/proposals/2076-enforce-validity-periods.md new file mode 100644 index 00000000..b09aa2f4 --- /dev/null +++ b/proposals/2076-enforce-validity-periods.md @@ -0,0 +1,42 @@ +# MSC2076: Enforce key-validity periods when validating event signatures + +## Background + +The [Federation API +specification](https://matrix.org/docs/spec/server_server/r0.1.1.html#validating-hashes-and-signatures-on-received-events) +specifies that events should be validated via the signature verification +algorithm, but does not specify how the keys for that check should be obtained +and validated. + +In practice, the implementation has been as follows. The receiving server +first requests a copy of the key via the [`GET /_matrix/key/v2/server/` +API](https://matrix.org/docs/spec/server_server/r0.1.1.html#get-matrix-key-v2-server-keyid) +directly from the server which created the signature, or via the [`POST +/_matrix/key/v2/query` API](https://matrix.org/docs/spec/server_server/r0.1.1.html#post-matrix-key-v2-query) +from a trusted key server. Once such a key is obtained, it is then cached +forever. No check is made on the `valid_until_ts` field, and +`minimum_valid_until_ts` is set to zero for calls to `POST +/_matrix/key/v2/query`. + +This is highly unsatisfactory, as it means that, should a key be compromised, +then an attacker can spoof arbitrary events claiming to be from the compromised +server forever, since there is no revocation mechanism. + +## Proposal + +This MSC proposes to enforce the `valid_until_ts` property when validating +event signatures. In particular, the server must ensure that it has a copy of +the key with a `valid_until_ts` at least as large as the `origin_server_ts` of +the event being validated. If it does not have such a copy, it must try to +obtain one via the `GET /_matrix/key/v2/server/` or `POST +/_matrix/key/v2/query` APIs. For the latter, it must set +`minimum_valid_until_ts` to prompt the notary server to attempt to refresh the +key if appropriate. + +Since this changes the rules used to validate events, it will be introduced +with a new room version. This will reduce the risk of divergence between +servers in a room due to some servers accepting events which others reject. + +This MSC also proposes that the current situation - where `valid_until_ts` is +ignored - be formalised for the existing room versions v1-v4, rather than be +left as implementation-specific behaviour. From d2ccd6b268e28437a0a2d70c2fb2d1135fc76757 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 4 Jun 2019 23:53:42 +0100 Subject: [PATCH 170/497] MSC2077: room v5 --- proposals/2077-rooms-v5.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 proposals/2077-rooms-v5.md diff --git a/proposals/2077-rooms-v5.md b/proposals/2077-rooms-v5.md new file mode 100644 index 00000000..034c118a --- /dev/null +++ b/proposals/2077-rooms-v5.md @@ -0,0 +1,20 @@ +# MSC2077 - Rooms V6 + +This MSC proposes creating a new room version named v5, which will enforce the +signing key `valid_until_ts` timestamps proposed in +[MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). + +## Proposal + +The new room version is called "5". The only difference between v5 and v4 is +that v5 rooms enforce the `valid_until_ts` timestamp on signing keys as +proposed in [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). + +It is not yet proposed that servers change the default room version used when +creating new rooms, and it is not yet proposed that servers recommend upgrading +existing rooms to v5. + +## Notes + +See also [MSC2002](./2002-rooms-v4.md), which proposed room v4 but also +mentioned that a v5 was anticipated and gave some context for this change. From 3347a480eb0db602d964073129b7e567de84e7e8 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 5 Jun 2019 00:07:05 +0100 Subject: [PATCH 171/497] fix typo --- proposals/2077-rooms-v5.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2077-rooms-v5.md b/proposals/2077-rooms-v5.md index 034c118a..0a7eff2b 100644 --- a/proposals/2077-rooms-v5.md +++ b/proposals/2077-rooms-v5.md @@ -1,4 +1,4 @@ -# MSC2077 - Rooms V6 +# MSC2077 - Rooms V5 This MSC proposes creating a new room version named v5, which will enforce the signing key `valid_until_ts` timestamps proposed in From 40b10f254b5c82e11b56f96260e7e9b4f184d52d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 5 Jun 2019 07:18:25 +0100 Subject: [PATCH 172/497] clarifications --- proposals/2077-rooms-v5.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/proposals/2077-rooms-v5.md b/proposals/2077-rooms-v5.md index 0a7eff2b..9f8c1654 100644 --- a/proposals/2077-rooms-v5.md +++ b/proposals/2077-rooms-v5.md @@ -1,18 +1,17 @@ -# MSC2077 - Rooms V5 +# MSC2077 - Room version 5 -This MSC proposes creating a new room version named v5, which will enforce the -signing key `valid_until_ts` timestamps proposed in +This MSC proposes creating room version 5, which will enforce the signing key +`valid_until_ts` timestamps proposed in [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). ## Proposal -The new room version is called "5". The only difference between v5 and v4 is +The new room version is called `5`. The only difference between v5 and v4 is that v5 rooms enforce the `valid_until_ts` timestamp on signing keys as proposed in [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). -It is not yet proposed that servers change the default room version used when -creating new rooms, and it is not yet proposed that servers recommend upgrading -existing rooms to v5. +It is not yet proposed to change the default room version to v5. Version 5 will +be considered a "stable" version. ## Notes From cf932ad4f817b05ffbaf2464ad3eb1bc6e781d14 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 11:20:28 +0100 Subject: [PATCH 173/497] msc2078 - proposal for homeservers sending passwords reset requests --- proposals/2078-homeserver-password-resets.md | 21 ++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 proposals/2078-homeserver-password-resets.md diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md new file mode 100644 index 00000000..f5523cd2 --- /dev/null +++ b/proposals/2078-homeserver-password-resets.md @@ -0,0 +1,21 @@ +# MSC2078 - Sending Password Reset Emails via the Homeserver + +This MSC proposes removing the current requirement of the identity server to send password reset tokens, and allows homeservers to implement the functionality instead. The intention is to put less trust in the identity server which is currently one of the most centralised components of Matrix. As it stands, an attacker in control of a identity server can reset a user's password if that user has registered a third-party identifier (3PID) with that identity server, due to itself also handling the job of confirming the user's control of that identity. + +The MSC aims to simply clarify that homeservers can take on the responisibility of sending password reset tokens themselves. + +## Proposal + +Currently when a client requests a password reset, they make a call to either [/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) or [/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). This request is supplied all the necessary details as well as a `id_server` field containing the address of a trusted identity server which the user has used in the past to bind their 3PID. Understand that it is recommended for the homeserver to only grant the request if the given identity server is in a trusted list. + +The `id_server` field is currently required as the homeserver must know where to proxy the request to. This MSC proposes not to change the requirements of this field, but instead to clarify that the homeserver is allowed to not proxy the request, but carry it out itself. This would mean the homeserver can both send password reset tokens (via email or sms), as well as accept requests to [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) to verify that token. + +Thus, this proposal really only requests that it be clear that a homeserver does not need to proxy requests to `/requestToken`, and instead can ignore the `id_server` field and carry out the request itself. + +## Tradeoffs + +If homeservers choose to not proxy the request, they will need to implement the ability to send emails and/or sms messages. This is left as a detail for the homeserver implementation. + +## Future Considerations + +At some point we should look into removing the `id_server` field altogether and removing any email/sms message sending from the identity server. This would drastically reduce the amount of trust needed in the identity server and its required ability. This is, however, a good first step. From 4e692735f55f18c86033edb00d61f5d1ce17bc38 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 11:25:26 +0100 Subject: [PATCH 174/497] Update some wording --- proposals/2078-homeserver-password-resets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index f5523cd2..f1c5928a 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -8,9 +8,9 @@ The MSC aims to simply clarify that homeservers can take on the responisibility Currently when a client requests a password reset, they make a call to either [/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) or [/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). This request is supplied all the necessary details as well as a `id_server` field containing the address of a trusted identity server which the user has used in the past to bind their 3PID. Understand that it is recommended for the homeserver to only grant the request if the given identity server is in a trusted list. -The `id_server` field is currently required as the homeserver must know where to proxy the request to. This MSC proposes not to change the requirements of this field, but instead to clarify that the homeserver is allowed to not proxy the request, but carry it out itself. This would mean the homeserver can both send password reset tokens (via email or sms), as well as accept requests to [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) to verify that token. +The `id_server` field is currently required as the homeserver must know where to proxy the request to. This MSC proposes not to change the requirements of this field. Instead, it asks to clarify that the homeserver is allowed to not proxy the request, but carry it out itself. This would mean the homeserver can both send password reset tokens (via email or sms), as well as accept requests to [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) to verify that token. -Thus, this proposal really only requests that it be clear that a homeserver does not need to proxy requests to `/requestToken`, and instead can ignore the `id_server` field and carry out the request itself. +Thus, this proposal really only requests that it be clear that a homeserver does not need to proxy requests to `/requestToken`, and instead can ignore the `id_server` field and perform emailing/sms message sending by itself. ## Tradeoffs From c9711acbc5fe231e67c2dbfe15a8c795219a25d5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 12:52:01 +0100 Subject: [PATCH 175/497] Remove attacker bit --- proposals/2078-homeserver-password-resets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index f1c5928a..8ef560e9 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -1,6 +1,6 @@ # MSC2078 - Sending Password Reset Emails via the Homeserver -This MSC proposes removing the current requirement of the identity server to send password reset tokens, and allows homeservers to implement the functionality instead. The intention is to put less trust in the identity server which is currently one of the most centralised components of Matrix. As it stands, an attacker in control of a identity server can reset a user's password if that user has registered a third-party identifier (3PID) with that identity server, due to itself also handling the job of confirming the user's control of that identity. +This MSC proposes removing the current requirement of the identity server to send password reset tokens, and allows homeservers to implement the functionality instead. The intention is to put less trust in the identity server which is currently one of the most centralised components of Matrix. The MSC aims to simply clarify that homeservers can take on the responisibility of sending password reset tokens themselves. From 1956f1a916d5fbb512c834740e9e5cb0a027e6e9 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 12:59:58 +0100 Subject: [PATCH 176/497] Revert "Remove attacker bit" This reverts commit c9711acbc5fe231e67c2dbfe15a8c795219a25d5. --- proposals/2078-homeserver-password-resets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 8ef560e9..f1c5928a 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -1,6 +1,6 @@ # MSC2078 - Sending Password Reset Emails via the Homeserver -This MSC proposes removing the current requirement of the identity server to send password reset tokens, and allows homeservers to implement the functionality instead. The intention is to put less trust in the identity server which is currently one of the most centralised components of Matrix. +This MSC proposes removing the current requirement of the identity server to send password reset tokens, and allows homeservers to implement the functionality instead. The intention is to put less trust in the identity server which is currently one of the most centralised components of Matrix. As it stands, an attacker in control of a identity server can reset a user's password if that user has registered a third-party identifier (3PID) with that identity server, due to itself also handling the job of confirming the user's control of that identity. The MSC aims to simply clarify that homeservers can take on the responisibility of sending password reset tokens themselves. From 085c5667a478fe0f0f64973b3627863d8e656057 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 13:42:23 +0100 Subject: [PATCH 177/497] wrap lines --- proposals/2078-homeserver-password-resets.md | 44 ++++++++++++++++---- 1 file changed, 37 insertions(+), 7 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index f1c5928a..e64c8651 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -1,21 +1,51 @@ # MSC2078 - Sending Password Reset Emails via the Homeserver -This MSC proposes removing the current requirement of the identity server to send password reset tokens, and allows homeservers to implement the functionality instead. The intention is to put less trust in the identity server which is currently one of the most centralised components of Matrix. As it stands, an attacker in control of a identity server can reset a user's password if that user has registered a third-party identifier (3PID) with that identity server, due to itself also handling the job of confirming the user's control of that identity. +This MSC proposes removing the current requirement of the identity server to +send password reset tokens, and allows homeservers to implement the +functionality instead. The intention is to put less trust in the identity +server which is currently one of the most centralised components of Matrix. As +it stands, an attacker in control of a identity server can reset a user's +password if that user has registered a third-party identifier (3PID) with that +identity server, due to itself also handling the job of confirming the user's +control of that identity. -The MSC aims to simply clarify that homeservers can take on the responisibility of sending password reset tokens themselves. +The MSC aims to simply clarify that homeservers can take on the responisibility +of sending password reset tokens themselves. ## Proposal -Currently when a client requests a password reset, they make a call to either [/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) or [/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). This request is supplied all the necessary details as well as a `id_server` field containing the address of a trusted identity server which the user has used in the past to bind their 3PID. Understand that it is recommended for the homeserver to only grant the request if the given identity server is in a trusted list. +Currently when a client requests a password reset, they make a call to either +[/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) +or +[/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). +This request is supplied all the necessary details as well as a `id_server` +field containing the address of a trusted identity server which the user has +used in the past to bind their 3PID. Understand that it is recommended for the +homeserver to only grant the request if the given identity server is in a +trusted list. -The `id_server` field is currently required as the homeserver must know where to proxy the request to. This MSC proposes not to change the requirements of this field. Instead, it asks to clarify that the homeserver is allowed to not proxy the request, but carry it out itself. This would mean the homeserver can both send password reset tokens (via email or sms), as well as accept requests to [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) to verify that token. +The `id_server` field is currently required as the homeserver must know where +to proxy the request to. This MSC proposes not to change the requirements of +this field. Instead, it asks to clarify that the homeserver is allowed to not +proxy the request, but carry it out itself. This would mean the homeserver can +both send password reset tokens (via email or sms), as well as accept requests +to +[/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) +to verify that token. -Thus, this proposal really only requests that it be clear that a homeserver does not need to proxy requests to `/requestToken`, and instead can ignore the `id_server` field and perform emailing/sms message sending by itself. +Thus, this proposal really only requests that it be clear that a homeserver +does not need to proxy requests to `/requestToken`, and instead can ignore the +`id_server` field and perform emailing/sms message sending by itself. ## Tradeoffs -If homeservers choose to not proxy the request, they will need to implement the ability to send emails and/or sms messages. This is left as a detail for the homeserver implementation. +If homeservers choose to not proxy the request, they will need to implement the +ability to send emails and/or sms messages. This is left as a detail for the +homeserver implementation. ## Future Considerations -At some point we should look into removing the `id_server` field altogether and removing any email/sms message sending from the identity server. This would drastically reduce the amount of trust needed in the identity server and its required ability. This is, however, a good first step. +At some point we should look into removing the `id_server` field altogether and +removing any email/sms message sending from the identity server. This would +drastically reduce the amount of trust needed in the identity server and its +required ability. This is, however, a good first step. From 8cba7adcdf47ed69ece187f472d3237e532dae32 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 13:52:02 +0100 Subject: [PATCH 178/497] Clarify conditions for attack --- proposals/2078-homeserver-password-resets.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index e64c8651..0d2207b0 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -5,8 +5,9 @@ send password reset tokens, and allows homeservers to implement the functionality instead. The intention is to put less trust in the identity server which is currently one of the most centralised components of Matrix. As it stands, an attacker in control of a identity server can reset a user's -password if that user has registered a third-party identifier (3PID) with that -identity server, due to itself also handling the job of confirming the user's +password if the identity server is considered trusted by that homeserver, and +the user has registered at least one third-party identifier (3PID). This is due +to the identity server currently handling the job of confirming the user's control of that identity. The MSC aims to simply clarify that homeservers can take on the responisibility From 7e18c5d5a8a6cd392561eb260a4ab66eaa759fad Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 14:38:16 +0100 Subject: [PATCH 179/497] Add new submit_url response field --- proposals/2078-homeserver-password-resets.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 0d2207b0..b780d188 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -21,9 +21,7 @@ or [/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). This request is supplied all the necessary details as well as a `id_server` field containing the address of a trusted identity server which the user has -used in the past to bind their 3PID. Understand that it is recommended for the -homeserver to only grant the request if the given identity server is in a -trusted list. +used in the past to bind their 3PID. The `id_server` field is currently required as the homeserver must know where to proxy the request to. This MSC proposes not to change the requirements of @@ -34,9 +32,11 @@ to [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) to verify that token. -Thus, this proposal really only requests that it be clear that a homeserver -does not need to proxy requests to `/requestToken`, and instead can ignore the -`id_server` field and perform emailing/sms message sending by itself. +An additional complication is that in the case of sms, a full link to reset passwords is not sent, but a short code. The client then asks the user to enter this code, however the client may now not know where to send the code. Should it send it to the identity server or the homeserver? Which sent out the code? + +In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the homeserver has not sent out the entire link (for instance in the case of a short code through sms). If this field is omitted, the client knows that the link has been sent in its entirety and the verification will be handled out of band. + +If the client receives a response to `/requestToken` with `submit_url`, it should accept the token from user input, then make a request (either POST or GET, depending on whether it desires a machine- or human-readable response) to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. This data should be submitted as query parameters for `GET` request, and a JSON body for a `POST`. ## Tradeoffs From 8259ae292a010b6453f6a7b4f40609370b80dc1d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 14:39:36 +0100 Subject: [PATCH 180/497] Capitalise SMS --- proposals/2078-homeserver-password-resets.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index b780d188..1a224fe8 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -27,26 +27,26 @@ The `id_server` field is currently required as the homeserver must know where to proxy the request to. This MSC proposes not to change the requirements of this field. Instead, it asks to clarify that the homeserver is allowed to not proxy the request, but carry it out itself. This would mean the homeserver can -both send password reset tokens (via email or sms), as well as accept requests +both send password reset tokens (via email or SMS), as well as accept requests to [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) to verify that token. -An additional complication is that in the case of sms, a full link to reset passwords is not sent, but a short code. The client then asks the user to enter this code, however the client may now not know where to send the code. Should it send it to the identity server or the homeserver? Which sent out the code? +An additional complication is that in the case of SMS, a full link to reset passwords is not sent, but a short code. The client then asks the user to enter this code, however the client may now not know where to send the code. Should it send it to the identity server or the homeserver? Which sent out the code? -In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the homeserver has not sent out the entire link (for instance in the case of a short code through sms). If this field is omitted, the client knows that the link has been sent in its entirety and the verification will be handled out of band. +In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the homeserver has not sent out the entire link (for instance in the case of a short code through SMS). If this field is omitted, the client knows that the link has been sent in its entirety and the verification will be handled out of band. If the client receives a response to `/requestToken` with `submit_url`, it should accept the token from user input, then make a request (either POST or GET, depending on whether it desires a machine- or human-readable response) to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. This data should be submitted as query parameters for `GET` request, and a JSON body for a `POST`. ## Tradeoffs If homeservers choose to not proxy the request, they will need to implement the -ability to send emails and/or sms messages. This is left as a detail for the +ability to send emails and/or SMS messages. This is left as a detail for the homeserver implementation. ## Future Considerations At some point we should look into removing the `id_server` field altogether and -removing any email/sms message sending from the identity server. This would +removing any email/SMS message sending from the identity server. This would drastically reduce the amount of trust needed in the identity server and its required ability. This is, however, a good first step. From 4174b612794b77a35eee0c9ea4cac8bdee40a62a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 14:50:40 +0100 Subject: [PATCH 181/497] submit_url only if the user has to enter the code somewhere --- proposals/2078-homeserver-password-resets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 1a224fe8..47e12224 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -34,7 +34,7 @@ to verify that token. An additional complication is that in the case of SMS, a full link to reset passwords is not sent, but a short code. The client then asks the user to enter this code, however the client may now not know where to send the code. Should it send it to the identity server or the homeserver? Which sent out the code? -In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the homeserver has not sent out the entire link (for instance in the case of a short code through SMS). If this field is omitted, the client knows that the link has been sent in its entirety and the verification will be handled out of band. +In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the verification message contains a code the user is expected to enter into the client (for instance in the case of a short code through SMS). If this field is omitted, the client knows that the link has been sent in its entirety and the verification will be handled out of band. If the client receives a response to `/requestToken` with `submit_url`, it should accept the token from user input, then make a request (either POST or GET, depending on whether it desires a machine- or human-readable response) to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. This data should be submitted as query parameters for `GET` request, and a JSON body for a `POST`. From 6e0af5e64cda74dad65c602e2425a148c35ddda9 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 15:07:06 +0100 Subject: [PATCH 182/497] If no submit_url, just send it to the IS as before --- proposals/2078-homeserver-password-resets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 47e12224..1bb5dbc4 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -34,7 +34,7 @@ to verify that token. An additional complication is that in the case of SMS, a full link to reset passwords is not sent, but a short code. The client then asks the user to enter this code, however the client may now not know where to send the code. Should it send it to the identity server or the homeserver? Which sent out the code? -In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the verification message contains a code the user is expected to enter into the client (for instance in the case of a short code through SMS). If this field is omitted, the client knows that the link has been sent in its entirety and the verification will be handled out of band. +In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the verification message contains a code the user is expected to enter into the client (for instance in the case of a short code through SMS). If this field is omitted, the client should continue the same behaviour from before, which is to send the token to the identity server directly. This is intended for backwards compatibility with older servers. If the client receives a response to `/requestToken` with `submit_url`, it should accept the token from user input, then make a request (either POST or GET, depending on whether it desires a machine- or human-readable response) to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. This data should be submitted as query parameters for `GET` request, and a JSON body for a `POST`. From 6bb48723e8fe7aa88bf1f5f7f42b1f047b057aa0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 15:43:57 +0100 Subject: [PATCH 183/497] The HS can send any URL --- proposals/2078-homeserver-password-resets.md | 28 ++++++++++++++------ 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 1bb5dbc4..6f7386d4 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -19,24 +19,36 @@ Currently when a client requests a password reset, they make a call to either [/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) or [/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). -This request is supplied all the necessary details as well as a `id_server` -field containing the address of a trusted identity server which the user has -used in the past to bind their 3PID. +This request is supplied all the necessary details as well as an `id_server` +field containing the address of a identity server trusted by the homeserver. The `id_server` field is currently required as the homeserver must know where to proxy the request to. This MSC proposes not to change the requirements of this field. Instead, it asks to clarify that the homeserver is allowed to not proxy the request, but carry it out itself. This would mean the homeserver can both send password reset tokens (via email or SMS), as well as accept requests -to -[/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) +an endpoint (with the same parameters as +[/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken)) to verify that token. -An additional complication is that in the case of SMS, a full link to reset passwords is not sent, but a short code. The client then asks the user to enter this code, however the client may now not know where to send the code. Should it send it to the identity server or the homeserver? Which sent out the code? +An additional complication is that in the case of SMS, a full link to reset +passwords is not sent, but a short code. The client then asks the user to enter +this code, however the client may now not know where to send the code. Should +it send it to the identity server or the homeserver? Which sent out the code? -In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the verification message contains a code the user is expected to enter into the client (for instance in the case of a short code through SMS). If this field is omitted, the client should continue the same behaviour from before, which is to send the token to the identity server directly. This is intended for backwards compatibility with older servers. +In order to combat this problem, the field `submit_url` should be added in the +response from both the email and msisdn variants of the `/requestToken` +Client-Server API, if and only if the verification message contains a code the +user is expected to enter into the client (for instance in the case of a short +code through SMS). If this field is omitted, the client should continue the +same behaviour from before, which is to send the token to the identity server +directly. This is intended for backwards compatibility with older servers. -If the client receives a response to `/requestToken` with `submit_url`, it should accept the token from user input, then make a request (either POST or GET, depending on whether it desires a machine- or human-readable response) to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. This data should be submitted as query parameters for `GET` request, and a JSON body for a `POST`. +If the client receives a response to `/requestToken` with `submit_url`, it +should accept the token from user input, then make a POST request to the +content of `submit_url` with the `sid`, `client_secret` and user-entered token. +This data should be submitted as query parameters for `GET` request, and a JSON +body for a `POST`. ## Tradeoffs From 395acf8e0650a147dbcc7340e48d2d4f21ea20c5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 5 Jun 2019 15:58:14 +0100 Subject: [PATCH 184/497] Update proposals/2078-homeserver-password-resets.md Co-Authored-By: Hubert Chathi --- proposals/2078-homeserver-password-resets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 6f7386d4..e92d679e 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -15,7 +15,7 @@ of sending password reset tokens themselves. ## Proposal -Currently when a client requests a password reset, they make a call to either +Currently when a client requests a password reset, it makes a call to either [/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) or [/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). From e49518099de29e8d092b2fbb675fc941fb1124fc Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 17:37:09 +0100 Subject: [PATCH 185/497] Be explicit with request/responses --- proposals/2078-homeserver-password-resets.md | 53 +++++++++++++++++++- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 6f7386d4..0052c48e 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -47,8 +47,57 @@ directly. This is intended for backwards compatibility with older servers. If the client receives a response to `/requestToken` with `submit_url`, it should accept the token from user input, then make a POST request to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. -This data should be submitted as query parameters for `GET` request, and a JSON -body for a `POST`. +`submit_url` can lead to anywhere the homeserver deems necessary for +verification. This data should be submitted as a JSON body. + +An example exchange from the client's perspective is shown below: + +``` +POST https://homeserver.tld/_matrix/client/r0/account/password/email/requestToken + +{ + "client_secret": "monkeys_are_AWESOME", + "email": "alice@homeserver.tld", + "send_attempt": 1, + "id_server": "id.example.com" +} +``` + +If the server responds with a `submit_url` field, it means the client should +collect a token from the user and then submit it to the provided URL. + +``` +{ + "sid": "123abc", + "submit_url": "https://homeserver.tld/path/to/submitToken" +} +``` + +Since a `submit_url` was provided, the client will now collect a token from the +user, say "123456", and then submit that as a POST request to the +`"submit_url"`. + +``` +POST https://homeserver.tld/path/to/submitToken + +{ + "sid": "123abc", + "client_secret": "monkeys_are_AWESOME", + "token": "123456" +} +``` + +The client will then receive an appropriate response: + +``` +{ + "success": true +} +``` + +If the client did not receive a `submit_url` field, they should instead assume +that verification will be completed out of band (e.g. the user clicks a link in +their email and makes the submitToken request with their web browser). ## Tradeoffs From de725c26ccebe93faf556305f4803215f0aab50d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 10:37:22 -0600 Subject: [PATCH 186/497] Add more clarity to the media repo --- specification/modules/content_repo.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/specification/modules/content_repo.rst b/specification/modules/content_repo.rst index 823efb3c..1e3d1866 100644 --- a/specification/modules/content_repo.rst +++ b/specification/modules/content_repo.rst @@ -34,8 +34,6 @@ header. The recommended policy is ``sandbox; default-src 'none'; script-src 'none'; plugin-types application/pdf; style-src 'unsafe-inline'; object-src 'self';``. -Content in the repository should be treated as bytes as it may be encrypted. - Matrix Content (MXC) URIs ------------------------- @@ -78,12 +76,7 @@ requested dimensions, unless the content being thumbnailed is smaller than the dimensions. When the content is smaller than the requested dimensions, servers should return the original content rather than thumbnail it. -Servers SHOULD pre-calculate or have a list of set dimensions for which they -will thumbnail content at. For example, the server may choose that it will -only create thumbnails sized 96x96 or 512x512. When the client requests a -thumbnail, the server will pick the size which is larger than the requested -dimensions. Servers SHOULD pre-calculate the following thumbnails for uploaded -content, and limit thumbnails to the same sizes: +Servers SHOULD produce thumbnails with the following dimensions and methods: * 32x32, crop * 96x96, crop @@ -97,7 +90,9 @@ In summary: * The server will return an image larger than or equal to the dimensions requested where possible. -Servers MUST NOT upscale thumbnails under any circumstance. +Servers MUST NOT upscale thumbnails under any circumstance. Servers MUST NOT +return a smaller thumbnail than requested, unless the original content makes +that impossible. Security considerations ----------------------- From fc4965f2748a97312cfe9930aa456ba0caea7302 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 10:40:51 -0600 Subject: [PATCH 187/497] Stronger spec words --- api/client-server/registration.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 10b661a3..093bac6b 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -62,8 +62,8 @@ paths: `Relationship between access tokens and devices`_. When registering a guest account, all parameters in the request body - with the exception of ``initial_device_display_name`` are ignored by - the server. The server will pick a ``device_id`` for the account + with the exception of ``initial_device_display_name`` MUST BE ignored + by the server. The server MUST pick a ``device_id`` for the account regardless of input. operationId: register parameters: From d3f21e03605ad1dafb548b0386716103905d6282 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 17:54:18 +0100 Subject: [PATCH 188/497] Address review comments --- proposals/2078-homeserver-password-resets.md | 33 ++++++++++++++------ 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 0052c48e..64916931 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -31,6 +31,17 @@ an endpoint (with the same parameters as [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken)) to verify that token. +Consideration was taken not to make `id_server` and optional field. Let's +assume for a moment that it was optional. Now, a client could send a request to +`/requestToken` omitting the `id_server` field. The homeserver however has +opted to continue proxying `/requestToken` to the identity server, even though +it knows this is potentially insecure. The homeserver now has no idea which +identity server to proxy the request to, and must return a failure to the +client. The client could then make another request with an `id_server`, but +we've now made two requests that ended up in the same outcome, instead of one, +in hopes of saving a very small amount of bandwidth by omitting the field +originally. + An additional complication is that in the case of SMS, a full link to reset passwords is not sent, but a short code. The client then asks the user to enter this code, however the client may now not know where to send the code. Should @@ -40,15 +51,19 @@ In order to combat this problem, the field `submit_url` should be added in the response from both the email and msisdn variants of the `/requestToken` Client-Server API, if and only if the verification message contains a code the user is expected to enter into the client (for instance in the case of a short -code through SMS). If this field is omitted, the client should continue the -same behaviour from before, which is to send the token to the identity server -directly. This is intended for backwards compatibility with older servers. +code through SMS). It SHOULD be in the form of +`/_matrix/identity/api/v1/validate/{3pid_type}/submitToken`, similar to the +[same endpoint that exists in the Identity-Server +API](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken). +If this field is omitted, the client MUST continue the same behaviour from +before, which is to send the token to the identity server directly. This is +intended for backwards compatibility with older servers. -If the client receives a response to `/requestToken` with `submit_url`, it -should accept the token from user input, then make a POST request to the -content of `submit_url` with the `sid`, `client_secret` and user-entered token. +If the client receives a response to `/requestToken` with `submit_url`, it MUST +accept the token from user input, then make a POST request to the content of +`submit_url` with the `sid`, `client_secret` and user-entered token. `submit_url` can lead to anywhere the homeserver deems necessary for -verification. This data should be submitted as a JSON body. +verification. This data MUST be submitted as a JSON body. An example exchange from the client's perspective is shown below: @@ -69,7 +84,7 @@ collect a token from the user and then submit it to the provided URL. ``` { "sid": "123abc", - "submit_url": "https://homeserver.tld/path/to/submitToken" + "submit_url": "https://homeserver.tld/_matrix/identity/api/v1/validate/msisdn/submitToken" } ``` @@ -78,7 +93,7 @@ user, say "123456", and then submit that as a POST request to the `"submit_url"`. ``` -POST https://homeserver.tld/path/to/submitToken +POST https://homeserver.tld/_matrix/identity/api/v1/validate/msisdn/submitToken { "sid": "123abc", From 3e23dde341b114117a448261d02d45ed495b3e34 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 5 Jun 2019 21:49:02 +0100 Subject: [PATCH 189/497] Be clear that any 3PID token request can now be done by the hs --- proposals/2078-homeserver-password-resets.md | 26 ++++++++++++-------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index e9e53151..f8dfc53e 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -1,16 +1,22 @@ -# MSC2078 - Sending Password Reset Emails via the Homeserver +# MSC2078 - Sending Third-Party Request Tokens via the Homeserver This MSC proposes removing the current requirement of the identity server to -send password reset tokens, and allows homeservers to implement the -functionality instead. The intention is to put less trust in the identity -server which is currently one of the most centralised components of Matrix. As -it stands, an attacker in control of a identity server can reset a user's -password if the identity server is considered trusted by that homeserver, and -the user has registered at least one third-party identifier (3PID). This is due -to the identity server currently handling the job of confirming the user's -control of that identity. +send third-party request tokens, and allows homeservers to implement the +functionality instead. These request tokens are used to verify the identity of +the request auther as an owner of the third-party identity (3PID). This can be +used for binding a 3PID to an account, or for resetting passwords via email or +SMS. The latter is what this proposal mainly focuses on, but be aware that it +allows for any task that requires requesting a token through a 3PID to be +taken on by the homeserver instead of the identity server. -The MSC aims to simply clarify that homeservers can take on the responisibility +The intention is to put less trust in the identity server, which is currently +one of the most centralised components of Matrix. As it stands, an attacker in +control of a identity server can reset a user's password if the identity server +is considered trusted by that homeserver, and the user has registered at least +one 3PID. This is due to the identity server currently handling the job of +confirming the user's control of that identity. + +The MSC aims to simply clarify that homeservers can take on the responsibility of sending password reset tokens themselves. ## Proposal From a6314df44ceb63bd65a9508464e454a3a224d9ff Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 17:03:19 -0600 Subject: [PATCH 190/497] Spec v5 rooms: Key validity Proposals: * [MSC2076](https://github.com/matrix-org/matrix-doc/pull/2076) * [MSC2077](https://github.com/matrix-org/matrix-doc/pull/2077) Implementation references: * https://github.com/matrix-org/synapse/commit/00bf99fa628e173ff14c99e5ffd02e8317ee1656 * https://github.com/matrix-org/synapse/pull/5354 * https://github.com/matrix-org/synapse/pull/5321 No known differences from the proposals are included here - alterations are accidental. --- api/server-server/definitions/keys.yaml | 10 +++- .../newsfragments/2080.clarification | 1 + specification/index.rst | 1 + specification/rooms/v5.rst | 54 +++++++++++++++++++ specification/targets.yaml | 4 ++ 5 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 changelogs/server_server/newsfragments/2080.clarification create mode 100644 specification/rooms/v5.rst diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml index 06619641..c48c320a 100644 --- a/api/server-server/definitions/keys.yaml +++ b/api/server-server/definitions/keys.yaml @@ -94,6 +94,12 @@ properties: type: integer format: int64 description: |- - POSIX timestamp when the list of valid keys should be refreshed. Keys used beyond this - timestamp are no longer valid. + POSIX timestamp when the list of valid keys should be refreshed. This field MUST + be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST + be considered invalid, depending on the `room version specification`_. + + Servers SHOULD use the lesser of this field and 7 days into the future when + determining if a key is valid. This is to avoid a situation where an attacker + publishes a key which is valid for a significant amount of time without a way + for the homeserver owner to revoke it. example: 1052262000000 diff --git a/changelogs/server_server/newsfragments/2080.clarification b/changelogs/server_server/newsfragments/2080.clarification new file mode 100644 index 00000000..c568fa13 --- /dev/null +++ b/changelogs/server_server/newsfragments/2080.clarification @@ -0,0 +1 @@ +Clarify how ``valid_until_ts`` behaves with respect to room version. diff --git a/specification/index.rst b/specification/index.rst index 33dff5a3..2e1ffd27 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -494,6 +494,7 @@ The available room versions are: * `Version 2 `_ - **Stable**. Implements State Resolution Version 2. * `Version 3 `_ - **Stable**. Introduces events whose IDs are the event's hash. * `Version 4 `_ - **Stable**. Builds on v3 by using URL-safe base64 for event IDs. +* `Version 5 `_ - **Stable**. Introduces enforcement of signing key validity periods. Specification Versions ---------------------- diff --git a/specification/rooms/v5.rst b/specification/rooms/v5.rst new file mode 100644 index 00000000..9b9fad7e --- /dev/null +++ b/specification/rooms/v5.rst @@ -0,0 +1,54 @@ +.. Copyright 2019 The Matrix.org Foundation C.I.C. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Room Version 5 +============== + +This room version builds on `version 4 `_, enforcing signing key validity +periods for events. + +.. contents:: Table of Contents +.. sectnum:: + + +Client considerations +--------------------- + +There are no specific requirements for clients in this room version. Clients should +be aware of event ID changes in `room version 4 `_, however. + + +Server implementation components +-------------------------------- + +.. WARNING:: + The information contained in this section is strictly for server implementors. + Applications which use the Client-Server API are generally unaffected by the + intricacies contained here. The section above regarding client considerations + is the resource that Client-Server API use cases should reference. + + +Room version 5 uses the same algorithms defined in `room version 4 `_, ensuring +that signing key validity is respected. + +Signing key validity period +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When validating event signatures, servers MUST enforce the ``valid_until_ts`` property +from a key request is at least as large as the ``origin_server_ts`` for the event being +validated. Servers missing a copy of the signing key MUST try to obtain one via the +`GET /_matrix/key/v2/server <../server_server/r0.1.1.html#get-matrix-key-v2-server-keyid>`_ +or `POST /_matrix/key/v2/query <../server_server/r0.1.1.html#post-matrix-key-v2-query>`_ +APIs. When using the ``/query`` endpoint, servers MUST set the ``minimum_valid_until_ts`` +property to prompt the notary server to attempt to refresh the key if appropriate. diff --git a/specification/targets.yaml b/specification/targets.yaml index abcdc240..11d69fc0 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -42,6 +42,10 @@ targets: files: - rooms/v4.rst version_label: v4 + rooms@v5: # this is translated to be rooms/v5.html + files: + - rooms/v5.rst + version_label: v5 appendices: files: - appendices.rst From 7ce1ff21351d61cf9cac88637ac9ac389ee12255 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 20:30:21 -0600 Subject: [PATCH 191/497] Clarify which servers are supposed to sign events Fixes https://github.com/matrix-org/matrix-doc/issues/2074 --- .../server_server/newsfragments/2081.clarification | 1 + specification/server_server_api.rst | 14 +++++++++++--- 2 files changed, 12 insertions(+), 3 deletions(-) create mode 100644 changelogs/server_server/newsfragments/2081.clarification diff --git a/changelogs/server_server/newsfragments/2081.clarification b/changelogs/server_server/newsfragments/2081.clarification new file mode 100644 index 00000000..fd291273 --- /dev/null +++ b/changelogs/server_server/newsfragments/2081.clarification @@ -0,0 +1 @@ +Clarify which servers are supposed to sign events. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index b765e36a..812f0ffc 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -421,9 +421,8 @@ must ensure that the event: Further details of these checks, and how to handle failures, are described below. -.. TODO: - Flesh this out a bit more, and probably change the doc to group the various - checks in one place, rather than have them spread out. +The `Signing Events <#signing-events>`_ section has more information on which hashes +and signatures are expected on events, and how to calculate them. Definitions @@ -1099,6 +1098,15 @@ originating server, following the algorithm described in `Checking for a signatu Note that this step should succeed whether we have been sent the full event or a redacted copy. +The signatures expected on an event are: + +* The sender's server, unless the invite was created as a result of 3rd party invite. + The sender must already match the 3rd party invite, and the server which actually + sends the event may be a different server. +* For room versions 1 and 2, the server which created the ``event_id``. Other room + versions do not track the ``event_id`` over federation and therefore do not need + a signature from those servers. + If the signature is found to be valid, the expected content hash is calculated as described below. The content hash in the ``hashes`` property of the received event is base64-decoded, and the two are compared for equality. From 80aa5a24dc55433bd95f37cd03dd20fab55c280b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 20:33:09 -0600 Subject: [PATCH 192/497] Make v4 the "default" room version As per [MSC2002](https://github.com/matrix-org/matrix-doc/pull/2002). This was missed in https://github.com/matrix-org/matrix-doc/pull/2019 Fixes https://github.com/matrix-org/matrix-doc/issues/2071 --- specification/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/index.rst b/specification/index.rst index 33dff5a3..a6f6f62b 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -485,7 +485,7 @@ some other reason. Versions can switch between stable and unstable periodically for a variety of reasons, including discovered security vulnerabilities and age. Clients should not ask room administrators to upgrade their rooms if the room is -running a stable version. Servers SHOULD use room version 1 as the default room +running a stable version. Servers SHOULD use room version 4 as the default room version when creating new rooms. The available room versions are: From a19eb59f13058afcb6f7b2bb9947a173fb004f5a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 21:10:38 -0600 Subject: [PATCH 193/497] Clarify the key object definition for the key management API Fixes https://github.com/matrix-org/matrix-doc/issues/1907 One too far --- api/client-server/keys.yaml | 99 +++++++++++++------ api/server-server/user_keys.yaml | 37 ++++--- .../newsfragments/2083.clarification | 1 + .../newsfragments/2083.clarification | 1 + 4 files changed, 96 insertions(+), 42 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2083.clarification create mode 100644 changelogs/server_server/newsfragments/2083.clarification diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 718703fd..30056259 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -59,22 +59,41 @@ paths: by the key algorithm. May be absent if no new one-time keys are required. - additionalProperties: - type: - - string - - object - example: - "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8" - signed_curve25519:AAAAHg: - key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs" - signatures: - "@alice:example.com": - ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" - signed_curve25519:AAAAHQ: - key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw" - signatures: - "@alice:example.com": - ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" + additionalProperties: + type: + - string + - type: object + title: KeyObject + properties: + key: + type: string + description: The key, encoded using unpadded base64. + signatures: + type: object + description: |- + Signature for the device. Mapped from user ID to signature object. + additionalProperties: + type: string + required: ['key', 'signatures'] + example: { + "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", + "signed_curve25519:AAAAHg": { + "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + } + } + }, + "signed_curve25519:AAAAHQ": { + "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" + } + } + } + } responses: 200: description: @@ -205,12 +224,12 @@ paths: "@alice:example.com": { "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" } - }, + }, "unsigned": { "device_display_name": "Alice's mobile phone" } } - + tags: - End-to-end encryption "/keys/claim": @@ -246,8 +265,9 @@ paths: type: string description: algorithm example: "signed_curve25519" - example: + example: { "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } + } required: - one_time_keys responses: @@ -263,7 +283,7 @@ paths: If any remote homeservers could not be reached, they are recorded here. The names of the properties are the names of the unreachable servers. - + If the homeserver could be reached, but the user or device was unknown, no failure is recorded. Instead, the corresponding user or device is missing from the ``one_time_keys`` result. @@ -281,14 +301,37 @@ paths: type: - string - object - example: - "@alice:example.com": - JLAFKJWSCS: - signed_curve25519:AAAAHg: - key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs" - signatures: - "@alice:example.com": - ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + # XXX: We can't define an actual object here, so we have to hope + # that people will look at the swagger source or can figure it out + # from the other endpoints/example. + # - type: object + # title: KeyObject + # properties: + # key: + # type: string + # description: The key, encoded using unpadded base64. + # signatures: + # type: object + # description: |- + # Signature for the device. Mapped from user ID to signature object. + # additionalProperties: + # type: string + # required: ['key', 'signatures'] + example: { + "@alice:example.com": { + "JLAFKJWSCS": { + "signed_curve25519:AAAAHg": { + "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + } + } + } + } + } + } + required: ['one_time_keys'] tags: - End-to-end encryption "/keys/changes": diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index 3c59cf81..613948c3 100644 --- a/api/server-server/user_keys.yaml +++ b/api/server-server/user_keys.yaml @@ -77,25 +77,34 @@ paths: additionalProperties: type: - string - - object - required: ['one_time_keys'] - examples: - application/json: { - "one_time_keys": { - "@alice:example.com": { - "JLAFKJWSCS": { - "signed_curve25518:AAAAHg": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + - type: object + title: KeyObject + properties: + key: + type: string + description: The key, encoded using unpadded base64. + signatures: + type: object + description: |- + Signature for the device. Mapped from user ID to signature object. + additionalProperties: + type: string + required: ['key', 'signatures'] + example: { + "@alice:example.com": { + "JLAFKJWSCS": { + "signed_curve25519:AAAAHg": { + "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + } } } } } } - } - } + required: ['one_time_keys'] "/user/keys/query": post: summary: Download device identity keys. diff --git a/changelogs/client_server/newsfragments/2083.clarification b/changelogs/client_server/newsfragments/2083.clarification new file mode 100644 index 00000000..8083d85d --- /dev/null +++ b/changelogs/client_server/newsfragments/2083.clarification @@ -0,0 +1 @@ +Clarify the key object definition for the key management API. diff --git a/changelogs/server_server/newsfragments/2083.clarification b/changelogs/server_server/newsfragments/2083.clarification new file mode 100644 index 00000000..8083d85d --- /dev/null +++ b/changelogs/server_server/newsfragments/2083.clarification @@ -0,0 +1 @@ +Clarify the key object definition for the key management API. From e115e3439dd84d195496f740d6951531524450ec Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 22:13:25 -0600 Subject: [PATCH 194/497] Touchups on the s2s swagger definitions Duplicate properties, wrong types, etc. --- api/server-server/leaving.yaml | 1 - api/server-server/query.yaml | 6 +++--- api/server-server/user_devices.yaml | 3 +-- api/server-server/version.yaml | 1 + api/server-server/wellknown.yaml | 1 + 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index c088cb5d..e0882fe8 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -57,7 +57,6 @@ paths: `room version specification`_ for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** - schema: schema: type: object properties: diff --git a/api/server-server/query.yaml b/api/server-server/query.yaml index dc14724c..29826b32 100644 --- a/api/server-server/query.yaml +++ b/api/server-server/query.yaml @@ -81,7 +81,7 @@ paths: servers: type: array description: |- - An array of server names that are likely to hold the given room. This + An array of server names that are likely to hold the given room. This list may or may not include the server answering the query. items: type: string @@ -128,7 +128,7 @@ paths: x-example: "@someone:example.org" - in: query name: field - type: enum + type: string enum: ['displayname', 'avatar_url'] description: |- The field to query. If specified, the server will only return the given field @@ -139,7 +139,7 @@ paths: description: |- The profile for the user. If a ``field`` is specified in the request, only the matching field should be included in the response. If no ``field`` was specified, - the response should include the fields of the user's profile that can be made + the response should include the fields of the user's profile that can be made public, such as the display name and avatar. If the user does not have a particular field set on their profile, the server diff --git a/api/server-server/user_devices.yaml b/api/server-server/user_devices.yaml index 4805deb4..362f9baa 100644 --- a/api/server-server/user_devices.yaml +++ b/api/server-server/user_devices.yaml @@ -42,7 +42,6 @@ paths: description: |- The user ID to retrieve devices for. Must be a user local to the receiving homeserver. - required: true x-example: "@alice:example.org" responses: 200: @@ -82,4 +81,4 @@ paths: description: Optional display name for the device. example: "Alice's Mobile Phone" required: ['device_id', 'keys'] - required: ['user_id', 'stream_id', 'devices'] \ No newline at end of file + required: ['user_id', 'stream_id', 'devices'] diff --git a/api/server-server/version.yaml b/api/server-server/version.yaml index 19975529..929f7b91 100644 --- a/api/server-server/version.yaml +++ b/api/server-server/version.yaml @@ -27,6 +27,7 @@ paths: get: summary: Get the implementation name and version of this homeserver. description: Get the implementation name and version of this homeserver. + operationId: getVersion responses: 200: description: diff --git a/api/server-server/wellknown.yaml b/api/server-server/wellknown.yaml index 75676646..bc390bd5 100644 --- a/api/server-server/wellknown.yaml +++ b/api/server-server/wellknown.yaml @@ -29,6 +29,7 @@ paths: Gets information about the delegated server for server-server communication between Matrix homeservers. Servers should follow 30x redirects, carefully avoiding redirect loops, and use normal X.509 certificate validation. + operationId: getWellKnown responses: 200: description: From 500f3d3bf121f30171422566a46dbbeab3d88608 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 22:28:57 -0600 Subject: [PATCH 195/497] Clarify that the default s2s transport is JSON over HTTP Fixes https://github.com/matrix-org/matrix-doc/issues/1713 --- .../identity_service/newsfragments/2086.clarification | 1 + specification/client_server_api.rst | 3 ++- specification/server_server_api.rst | 11 +++++++++++ 3 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 changelogs/identity_service/newsfragments/2086.clarification diff --git a/changelogs/identity_service/newsfragments/2086.clarification b/changelogs/identity_service/newsfragments/2086.clarification new file mode 100644 index 00000000..7016308b --- /dev/null +++ b/changelogs/identity_service/newsfragments/2086.clarification @@ -0,0 +1 @@ +Clarify that the default transport is JSON over HTTP. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index d9342a5b..d5b6491f 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -57,6 +57,8 @@ The following other versions are also available, in reverse chronological order: API Standards ------------- +.. TODO: Move a lot of this to a common area for all specs. + .. TODO Need to specify any HMAC or access_token lifetime/ratcheting tricks We need to specify capability negotiation for extensible transports @@ -82,7 +84,6 @@ names in JSON objects passed over the API also follow this convention. ``/createRoom``. A future version of this specification will address the inconsistency. - Any errors which occur at the Matrix API level MUST return a "standard error response". This is a JSON object which looks like: diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index b765e36a..28876e44 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -83,6 +83,17 @@ The following other versions are also available, in reverse chronological order: - `r0.1.1 `_ - `r0.1.0 `_ + +API standards +------------- + +The mandatory baseline for client-server communication in Matrix is exchanging +JSON objects over HTTP APIs. More efficient optional transports will in future +be supported as optional extensions - e.g. a packed binary encoding over +stream-cipher encrypted TCP socket for low-bandwidth/low-roundtrip mobile usage. +For the default HTTP transport, all API calls use a Content-Type of +``application/json``. In addition, all strings MUST be encoded as UTF-8. + Server discovery ---------------- From 8fd5b15594ebe41f15334078507edc956c3bc8fb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 22:55:11 -0600 Subject: [PATCH 196/497] Reorganize event structure in c2s spec and clarify event capabilities Fixes https://github.com/matrix-org/matrix-doc/issues/1166 Fixes https://github.com/matrix-org/matrix-doc/issues/1527 Fixes https://github.com/matrix-org/matrix-doc/issues/1827 Note: In order to fix the "state events have the following fields: [no words]" bug (1827) we need to resolve references on common event types. When doing this we ultimately end up with more fields than may be required to explain the section, however this commit alters the section descriptions to just say "these fields" instead of "these additional fields". This is also preferable over trying to get the inheritance reversed in the common event types, as the `/sync` endpoint has a high amount of reliance on partial events definitions. --- .../newsfragments/2087.clarification | 1 + .../schema/core-event-schema/room_event.yaml | 3 +- .../schema/core-event-schema/state_event.yaml | 3 +- scripts/templating/matrix_templates/units.py | 1 + specification/client_server_api.rst | 57 +++++++++++++++ specification/events.rst | 73 ------------------- specification/index.rst | 5 ++ specification/targets.yaml | 1 - 8 files changed, 66 insertions(+), 78 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2087.clarification delete mode 100644 specification/events.rst diff --git a/changelogs/client_server/newsfragments/2087.clarification b/changelogs/client_server/newsfragments/2087.clarification new file mode 100644 index 00000000..1974127d --- /dev/null +++ b/changelogs/client_server/newsfragments/2087.clarification @@ -0,0 +1 @@ +Reorganize information about events into a common section. diff --git a/event-schemas/schema/core-event-schema/room_event.yaml b/event-schemas/schema/core-event-schema/room_event.yaml index 007372a5..231d5c65 100644 --- a/event-schemas/schema/core-event-schema/room_event.yaml +++ b/event-schemas/schema/core-event-schema/room_event.yaml @@ -1,7 +1,6 @@ allOf: - $ref: sync_room_event.yaml -description: In addition to the Event fields, Room Events have the following additional - fields. +description: Room Events have the following fields. properties: room_id: description: |- diff --git a/event-schemas/schema/core-event-schema/state_event.yaml b/event-schemas/schema/core-event-schema/state_event.yaml index 37d4426f..816f925f 100644 --- a/event-schemas/schema/core-event-schema/state_event.yaml +++ b/event-schemas/schema/core-event-schema/state_event.yaml @@ -1,7 +1,6 @@ allOf: - $ref: room_event.yaml - $ref: sync_state_event.yaml -description: In addition to the Room Event fields, State Events have the following - additional fields. +description: State Events have the following fields. title: State Event type: object diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index ddb65efe..d44fb9c8 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -748,6 +748,7 @@ class MatrixUnits(Units): with open(filepath, encoding="utf-8") as f: event_schema = yaml.load(f, OrderedLoader) + event_schema = resolve_references(filepath, event_schema) schema_info = process_data_type( event_schema, diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index d9342a5b..80e4a2f4 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1326,6 +1326,63 @@ the event ``type`` key SHOULD follow the Java package naming convention, e.g. ``com.example.myapp.event``. This ensures event types are suitably namespaced for each application and reduces the risk of clashes. +.. Note:: + Events are not limited to the types defined in this specification. New or custom + event types can be created on a whim using the Java package naming convention. + For example, a ``com.example.game.score`` event can be sent by clients and other + clients would receive it through Matrix. + +Note that the structure of these events may be different than those in the +server-server API. + +{{common_event_fields}} + +{{common_room_event_fields}} + +{{common_state_event_fields}} + + +Size limits +~~~~~~~~~~~ + +The complete event MUST NOT be larger than 65535 bytes, when formatted as a +`PDU for the Server-Server protocol <../server_server/%SERVER_RELEASE_LABEL%#pdus>`_, +including any signatures, and encoded as `Canonical JSON`_. + +There are additional restrictions on sizes per key: + +- ``sender`` MUST NOT exceed 255 bytes (including domain). +- ``room_id`` MUST NOT exceed 255 bytes. +- ``state_key`` MUST NOT exceed 255 bytes. +- ``type`` MUST NOT exceed 255 bytes. +- ``event_id`` MUST NOT exceed 255 bytes. + +Some event types have additional size restrictions which are specified in +the description of the event. Additional keys have no limit other than that +implied by the total 65 KB limit on events. + +Room Events +~~~~~~~~~~~ +.. NOTE:: + This section is a work in progress. + +This specification outlines several standard event types, all of which are +prefixed with ``m.`` + +{{m_room_aliases_event}} + +{{m_room_canonical_alias_event}} + +{{m_room_create_event}} + +{{m_room_join_rules_event}} + +{{m_room_member_event}} + +{{m_room_power_levels_event}} + +{{m_room_redaction_event}} + Syncing ~~~~~~~ diff --git a/specification/events.rst b/specification/events.rst deleted file mode 100644 index c5e4a288..00000000 --- a/specification/events.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. Copyright 2016 OpenMarket Ltd -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. - -Event Structure -=============== - -All communication in Matrix is expressed in the form of data objects called -Events. These are the fundamental building blocks common to the client-server, -server-server and application-service APIs, and are described below. - -Note that the structure of these events may be different than those in the -server-server API. - -{{common_event_fields}} - -{{common_room_event_fields}} - -{{common_state_event_fields}} - - -Size limits ------------ - -The complete event MUST NOT be larger than 65535 bytes, when formatted as a -`PDU for the Server-Server protocol <../server_server/%SERVER_RELEASE_LABEL%#pdus>`_, -including any signatures, and encoded as `Canonical JSON`_. - -There are additional restrictions on sizes per key: - -- ``sender`` MUST NOT exceed 255 bytes (including domain). -- ``room_id`` MUST NOT exceed 255 bytes. -- ``state_key`` MUST NOT exceed 255 bytes. -- ``type`` MUST NOT exceed 255 bytes. -- ``event_id`` MUST NOT exceed 255 bytes. - -Some event types have additional size restrictions which are specified in -the description of the event. Additional keys have no limit other than that -implied by the total 65 KB limit on events. - -Room Events ------------ -.. NOTE:: - This section is a work in progress. - -This specification outlines several standard event types, all of which are -prefixed with ``m.`` - -{{m_room_aliases_event}} - -{{m_room_canonical_alias_event}} - -{{m_room_create_event}} - -{{m_room_join_rules_event}} - -{{m_room_member_event}} - -{{m_room_power_levels_event}} - -{{m_room_redaction_event}} - -.. _`Canonical JSON`: ../appendices.html#canonical-json diff --git a/specification/index.rst b/specification/index.rst index 33dff5a3..7aa6a672 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -348,6 +348,11 @@ pushed over federation to the participating servers in a room, currently using full mesh topology. Servers may also request backfill of events over federation from the other servers participating in a room. +.. Note:: + Events are not limited to the types defined in this specification. New or custom + event types can be created on a whim using the Java package naming convention. + For example, a ``com.example.game.score`` event can be sent by clients and other + clients would receive it through Matrix. Room Aliases ++++++++++++ diff --git a/specification/targets.yaml b/specification/targets.yaml index abcdc240..ed3dcee3 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -5,7 +5,6 @@ targets: client_server: files: - client_server_api.rst - - { 1: events.rst } - { 1: modules.rst } - { 2: feature_profiles.rst } - { 2: "group:modules" } # reference a group of files From c8a3850598cfa11fbfd1f30005ded4a854eec270 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 23:06:00 -0600 Subject: [PATCH 197/497] Merge GET/PUT /state/:event_type endpoints Clarifying that the state key is optional, and how that works. Fixes https://github.com/matrix-org/matrix-doc/issues/1182 --- api/client-server/room_state.yaml | 72 ++----------------- api/client-server/rooms.yaml | 49 ++----------- .../newsfragments/2088.clarification | 1 + 3 files changed, 13 insertions(+), 109 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2088.clarification diff --git a/api/client-server/room_state.yaml b/api/client-server/room_state.yaml index bda66eb8..37da0335 100644 --- a/api/client-server/room_state.yaml +++ b/api/client-server/room_state.yaml @@ -31,6 +31,9 @@ paths: put: summary: Send a state event to the given room. description: | + .. For backwards compatibility with older links... + .. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`: + State events can be sent using this endpoint. These events will be overwritten if ````, ```` and ```` all match. @@ -61,7 +64,9 @@ paths: - in: path type: string name: stateKey - description: The state_key for the state to send. Defaults to the empty string. + description: |- + The state_key for the state to send. Defaults to the empty string. When + an empty string, the trailing slash on this endpoint is optional. required: true x-example: "@alice:example.com" - in: body @@ -99,68 +104,3 @@ paths: } tags: - Room participation - "/rooms/{roomId}/state/{eventType}": - put: - summary: Send a state event to the given room. - description: | - State events can be sent using this endpoint. This endpoint is - equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}` - with an empty `stateKey`. Previous state events with matching - `` and ``, and empty ``, will be overwritten. - - Requests to this endpoint **cannot use transaction IDs** - like other ``PUT`` paths because they cannot be differentiated from the - ``state_key``. Furthermore, ``POST`` is unsupported on state paths. - - The body of the request should be the content object of the event; the - fields in this object will vary depending on the type of event. See - `Room Events`_ for the ``m.`` event specification. - operationId: setRoomState - security: - - accessToken: [] - parameters: - - in: path - type: string - name: roomId - description: The room to set the state in - required: true - x-example: "!636q39766251:example.com" - - in: path - type: string - name: eventType - description: The type of event to send. - required: true - x-example: "m.room.name" - - in: body - name: body - schema: - type: object - example: { - "name": "New name for the room" - } - responses: - 200: - description: "An ID for the sent event." - examples: - application/json: { - "event_id": "$YUwRidLecu:example.com" - } - schema: - type: object - properties: - event_id: - type: string - description: |- - A unique identifier for the event. - 403: - description: |- - The sender doesn't have permission to send the event into the room. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have permission to send the event." - } - tags: - - Room participation diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index 377783c6..f29a1860 100644 --- a/api/client-server/rooms.yaml +++ b/api/client-server/rooms.yaml @@ -68,6 +68,9 @@ paths: get: summary: Get the state identified by the type and key. description: |- + .. For backwards compatibility with older links... + .. _`get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`: + Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is @@ -91,7 +94,9 @@ paths: - in: path type: string name: stateKey - description: The key of the state to look up. + description: |- + The key of the state to look up. Defaults to an empty string. When + an empty string, the trailing slash on this endpoint is optional. required: true x-example: "" responses: @@ -110,48 +115,6 @@ paths: member of the room. tags: - Room participation - "/rooms/{roomId}/state/{eventType}": - get: - summary: Get the state identified by the type, with the empty state key. - description: |- - Looks up the contents of a state event in a room. If the user is - joined to the room then the state is taken from the current - state of the room. If the user has left the room then the state is - taken from the state of the room when they left. - - This looks up the state event with the empty state key. - operationId: getRoomStateByType - security: - - accessToken: [] - parameters: - - in: path - type: string - name: roomId - description: The room to look up the state in. - required: true - x-example: "!636q39766251:example.com" - - in: path - type: string - name: eventType - description: The type of state to look up. - required: true - x-example: "m.room.name" - responses: - 200: - description: The content of the state event. - examples: - application/json: { - "name": "Example room name"} - schema: - type: object - 404: - description: The room has no state with the given type or key. - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. - tags: - - Room participation "/rooms/{roomId}/state": get: summary: Get all state events in the current state of a room. diff --git a/changelogs/client_server/newsfragments/2088.clarification b/changelogs/client_server/newsfragments/2088.clarification new file mode 100644 index 00000000..ae22d66a --- /dev/null +++ b/changelogs/client_server/newsfragments/2088.clarification @@ -0,0 +1 @@ +De-duplicate ``/state/`` endpoints, clarifying that the ```` is optional. From bbc740197390091f9d9a83fb0a12c79b1a2e620f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 23:14:33 -0600 Subject: [PATCH 198/497] Clarify when and where CORS headers should be returned Fixes https://github.com/matrix-org/matrix-doc/issues/1736 Fixes https://github.com/matrix-org/matrix-doc/issues/2013 --- .../newsfragments/2089.clarification | 1 + specification/client_server_api.rst | 18 +++++++++++++++--- 2 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2089.clarification diff --git a/changelogs/client_server/newsfragments/2089.clarification b/changelogs/client_server/newsfragments/2089.clarification new file mode 100644 index 00000000..17405adc --- /dev/null +++ b/changelogs/client_server/newsfragments/2089.clarification @@ -0,0 +1 @@ +Clarify when and where CORS headers should be returned. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index d9342a5b..e38c8ac0 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -242,6 +242,9 @@ recommended. {{versions_cs_http_api}} + +.. _`CORS`: + Web Browser Clients ------------------- @@ -250,9 +253,14 @@ web browser or similar environment. In these cases, the homeserver should respon to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all requests. -When a client approaches the server with a pre-flight (``OPTIONS``) request, the -server should respond with the CORS headers for that route. The recommended CORS -headers to be returned by servers on all requests are: +Servers MUST expect that clients will approach them with ``OPTIONS`` requests, +allowing clients to discover the CORS headers. All endpoints in this specification s +upport the ``OPTIONS`` method, however the server MUST NOT perform any logic defined +for the endpoints when approached with an ``OPTIONS`` request. + +When a client approaches the server with a request, the server should respond with +the CORS headers for that route. The recommended CORS headers to be returned by +servers on all requests are: .. code:: @@ -296,6 +304,10 @@ In this section, the following terms are used with specific meanings: Well-known URI ~~~~~~~~~~~~~~ +.. Note:: + Servers hosting the ``.well-known`` JSON file SHOULD offer CORS headers, as + per the `CORS`_ section in this specification. + The ``.well-known`` method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows: From 79bbb47d9f200c3d99d3c6d8e2f7456cd66ac94f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 23:18:04 -0600 Subject: [PATCH 199/497] Clarify when authorization and rate-limiting are not applicable Fixes https://github.com/matrix-org/matrix-doc/issues/1971 --- .../newsfragments/2090.clarification | 1 + .../matrix_templates/templates/http-api.tmpl | 18 +++++++++--------- 2 files changed, 10 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2090.clarification diff --git a/changelogs/client_server/newsfragments/2090.clarification b/changelogs/client_server/newsfragments/2090.clarification new file mode 100644 index 00000000..23ab50f7 --- /dev/null +++ b/changelogs/client_server/newsfragments/2090.clarification @@ -0,0 +1 @@ +Clarify when authorization and rate-limiting are not applicable. diff --git a/scripts/templating/matrix_templates/templates/http-api.tmpl b/scripts/templating/matrix_templates/templates/http-api.tmpl index 0b9207d9..74836045 100644 --- a/scripts/templating/matrix_templates/templates/http-api.tmpl +++ b/scripts/templating/matrix_templates/templates/http-api.tmpl @@ -10,13 +10,13 @@ {{endpoint.desc}} -{{":Rate-limited: Yes." if endpoint.rate_limited else "" }} -{{":Requires auth: Yes." if endpoint.requires_auth else "" }} +{{":Rate-limited: Yes." if endpoint.rate_limited else ":Rate-limited: No." }} +{{":Requires auth: Yes." if endpoint.requires_auth else ":Requires auth: No." }} .. class:: httpheaders - + Request format: - + {% if (endpoint.req_param_by_loc | length) %} {{ tables.split_paramtable(endpoint.req_param_by_loc) }} {% if (endpoint.req_body_tables) %} @@ -33,7 +33,7 @@ {% if endpoint.res_headers is not none -%} .. class:: httpheaders - + Response headers: {{ tables.paramtable(endpoint.res_headers.rows) }} @@ -42,7 +42,7 @@ {% if endpoint.res_tables|length > 0 -%} .. class:: httpheaders - + Response format: {% for table in endpoint.res_tables -%} @@ -54,7 +54,7 @@ {% endif -%} .. class:: httpheaders - + Example request: .. code:: http @@ -64,7 +64,7 @@ {% if endpoint.responses|length > 0 -%} .. class:: httpheaders - + Response{{"s" if endpoint.responses|length > 1 else "" }}: {% endif -%} @@ -78,7 +78,7 @@ {% if res["example"] -%} .. class:: httpheaders - + Example .. code:: json From 976f32fcab51fde2de0301a7844c9470a9fd7ab4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jun 2019 23:23:23 -0600 Subject: [PATCH 200/497] Clarify that /register must produce valid Matrix User IDs Fixes https://github.com/matrix-org/matrix-doc/issues/1793 --- api/client-server/registration.yaml | 5 ++++- changelogs/client_server/newsfragments/2091.clarification | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2091.clarification diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 3195ab41..6fa99550 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -59,6 +59,9 @@ paths: supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See `Relationship between access tokens and devices`_. + + Any user ID returned by this API must conform to the grammar given in the + `Matrix specification <../appendices.html#user-identifiers>`_. operationId: register parameters: - in: query @@ -142,7 +145,7 @@ paths: The fully-qualified Matrix user ID (MXID) that has been registered. Any user ID returned by this API must conform to the grammar given in the - `Matrix specification `_. + `Matrix specification <../appendices.html#user-identifiers>`_. access_token: type: string description: |- diff --git a/changelogs/client_server/newsfragments/2091.clarification b/changelogs/client_server/newsfragments/2091.clarification new file mode 100644 index 00000000..2c4a276e --- /dev/null +++ b/changelogs/client_server/newsfragments/2091.clarification @@ -0,0 +1 @@ +Clarify that ``/register`` must produce valid Matrix User IDs. From e644227f4b607b3438cb37b21616a68e7f007645 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 14:13:20 -0600 Subject: [PATCH 201/497] Clarify that the server shouldn't process retries for UIA --- specification/client_server_api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 318ac08d..4593311d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -557,9 +557,10 @@ message in the standard format. For example: } If the client has completed all stages of a flow, the homeserver performs the -API call and returns the result as normal. Completed stages cannot be re-tried; -The client must abandon the current session and start over. Homeservers should -treat retries as authentication errors. +API call and returns the result as normal. Completed stages cannot be retried +by clients, therefore servers must return either a 401 response with the completed +stages, or the result of the API call if all stages were completed when a client +retries a stage. Some authentication types may be completed by means other than through the Matrix client, for example, an email confirmation may be completed when the user From afead2eb1bb578d6ca01af3ed3a8f729b852e795 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 14:18:41 -0600 Subject: [PATCH 202/497] Clarify LL in /sync a bit more --- api/client-server/sync.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 4fe22d50..a0d2fd60 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -37,7 +37,13 @@ paths: *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_ for more information. Lazy-loading members is only supported on a ``StateFilter`` - for this endpoint. + for this endpoint. When lazy-loading is enabled, servers MUST include the + syncing user's own membership event when they join a room, or when the + full state of rooms is requested. The user's own membership event is eligible + for being considered redudant by the server. When a sync is ``limited``, + the server MUST return membership events for the timeline, even if the + applicable events are not in the response, regardless as to whether or not + they are redundant. operationId: sync security: - accessToken: [] From 9bf0103ef359202026ffce958c243b898a828f9e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 14:36:30 -0600 Subject: [PATCH 203/497] Clarify how many PDUs are in a given transaction object Fixes https://github.com/matrix-org/matrix-doc/issues/2093 --- api/server-server/backfill.yaml | 2 +- .../definitions/single_pdu_transaction.yaml | 32 ++++++++++++++++++ .../unlimited_pdu_transaction.yaml | 33 +++++++++++++++++++ api/server-server/events.yaml | 2 +- .../newsfragments/2095.clarification | 1 + 5 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 api/server-server/definitions/single_pdu_transaction.yaml create mode 100644 api/server-server/definitions/unlimited_pdu_transaction.yaml create mode 100644 changelogs/server_server/newsfragments/2095.clarification diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml index 0da0e234..2ed6298c 100644 --- a/api/server-server/backfill.yaml +++ b/api/server-server/backfill.yaml @@ -64,7 +64,7 @@ paths: A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit. schema: - $ref: "definitions/transaction.yaml" + $ref: "definitions/unlimited_pdu_transaction.yaml" "/get_missing_events/{roomId}": post: summary: Retrieves events that the sender is missing diff --git a/api/server-server/definitions/single_pdu_transaction.yaml b/api/server-server/definitions/single_pdu_transaction.yaml new file mode 100644 index 00000000..ff682a44 --- /dev/null +++ b/api/server-server/definitions/single_pdu_transaction.yaml @@ -0,0 +1,32 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: + - $ref: "transaction.yaml" +properties: + pdus: + type: array + description: |- + A single PDU. Note that events have a different format depending on the room + version - check the `room version specification`_ for precise event formats. + items: + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending + on the room version - check the `room version specification`_ for precise event formats. + properties: [] + example: + $ref: "../examples/minimal_pdu.json" +required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/api/server-server/definitions/unlimited_pdu_transaction.yaml b/api/server-server/definitions/unlimited_pdu_transaction.yaml new file mode 100644 index 00000000..0fc31ee4 --- /dev/null +++ b/api/server-server/definitions/unlimited_pdu_transaction.yaml @@ -0,0 +1,33 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: + - $ref: "transaction.yaml" +properties: + pdus: + type: array + description: |- + List of persistent updates to rooms. Note that events have a different format + depending on the room version - check the `room version specification`_ for + precise event formats. + items: + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending + on the room version - check the `room version specification`_ for precise event formats. + properties: [] + example: + $ref: "../examples/minimal_pdu.json" +required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index 1f1a802d..1f8ee537 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -156,4 +156,4 @@ paths: 200: description: A transaction containing a single PDU which is the event requested. schema: - $ref: "definitions/transaction.yaml" + $ref: "definitions/single_pdu_transaction.yaml" diff --git a/changelogs/server_server/newsfragments/2095.clarification b/changelogs/server_server/newsfragments/2095.clarification new file mode 100644 index 00000000..66257e17 --- /dev/null +++ b/changelogs/server_server/newsfragments/2095.clarification @@ -0,0 +1 @@ +Clarify how many PDUs are contained in transaction objects for various endpoints. From f0eb495ceebfced779d54b5fcfab2aabdea35ad2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 15:41:28 -0600 Subject: [PATCH 204/497] Clarify how notification counts are calculated in /sync Fixes https://github.com/matrix-org/matrix-doc/issues/2015 --- api/client-server/sync.yaml | 6 ++++-- changelogs/client_server/newsfragments/2097.clarification | 1 + specification/modules/receipts.rst | 4 +++- 3 files changed, 8 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2097.clarification diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 02fddb84..4514d417 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -167,11 +167,13 @@ paths: this room. allOf: - $ref: "definitions/event_batch.yaml" - "unread_notifications": + unread_notifications: title: Unread Notification Counts type: object description: |- - Counts of unread notifications for this room + Counts of unread notifications for this room. See the + `Receipts module <#module-receipts>`_ for more information + on how these are calculated. properties: highlight_count: title: Highlighted notification count diff --git a/changelogs/client_server/newsfragments/2097.clarification b/changelogs/client_server/newsfragments/2097.clarification new file mode 100644 index 00000000..68d89bcc --- /dev/null +++ b/changelogs/client_server/newsfragments/2097.clarification @@ -0,0 +1 @@ +Clarify how ``unread_notifications`` is calculated. diff --git a/specification/modules/receipts.rst b/specification/modules/receipts.rst index ee2b697a..1745706e 100644 --- a/specification/modules/receipts.rst +++ b/specification/modules/receipts.rst @@ -26,7 +26,9 @@ to a homeserver. To prevent this from becoming a problem, receipts are implement using "up to" markers. This marker indicates that the acknowledgement applies to all events "up to and including" the event specified. For example, marking an event as "read" would indicate that the user had read all events *up to* the -referenced event. +referenced event. Servers MUST decremement the number of pending notifications +for a user if the events are up to or including the read receipt. This is typically +done by adjusting the ``unread_notifications`` value in a ``/sync`` response. Events ------ From b9c9396c111c08a893dda37225b1073d1d2ce4cd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 15:59:54 -0600 Subject: [PATCH 205/497] Specify some of the common concepts for Matrix in the index See https://github.com/matrix-org/matrix-doc/pull/2061 Fixes https://github.com/matrix-org/matrix-doc/issues/1468 Fixes https://github.com/matrix-org/matrix-doc/issues/1528 The section is not referenced by the specifications yet - they do a fairly good job of explaining it over and over. In future, it would be good to point all the references to the index. --- api/server-server/keys_query.yaml | 8 +++-- api/server-server/keys_server.yaml | 2 ++ .../newsfragments/2097.clarification | 1 + specification/index.rst | 36 +++++++++++++++++++ 4 files changed, 44 insertions(+), 3 deletions(-) create mode 100644 changelogs/server_server/newsfragments/2097.clarification diff --git a/api/server-server/keys_query.yaml b/api/server-server/keys_query.yaml index e616915b..4989f7fa 100644 --- a/api/server-server/keys_query.yaml +++ b/api/server-server/keys_query.yaml @@ -44,8 +44,10 @@ paths: type: string description: |- **Deprecated**. Servers should not use this parameter and instead - opt to return all keys, not just the requested one. The key ID to + opt to return all keys, not just the requested one. The key ID to look up. + + When excluded, the trailing slash on this endpoint is optional. required: false x-example: "ed25519:abc123" - in: query @@ -53,7 +55,7 @@ paths: type: integer format: int64 description: |- - A millisecond POSIX timestamp in milliseconds indicating when the returned + A millisecond POSIX timestamp in milliseconds indicating when the returned certificates will need to be valid until to be useful to the requesting server. If not supplied, the current time as determined by the notary server is used. @@ -114,7 +116,7 @@ paths: format: int64 description: |- A millisecond POSIX timestamp in milliseconds indicating when - the returned certificates will need to be valid until to be + the returned certificates will need to be valid until to be useful to the requesting server. If not supplied, the current time as determined by the notary diff --git a/api/server-server/keys_server.yaml b/api/server-server/keys_server.yaml index 69985ab7..465bb294 100644 --- a/api/server-server/keys_server.yaml +++ b/api/server-server/keys_server.yaml @@ -51,6 +51,8 @@ paths: **Deprecated**. Servers should not use this parameter and instead opt to return all keys, not just the requested one. The key ID to look up. + + When excluded, the trailing slash on this endpoint is optional. required: false x-example: "ed25519:abc123" deprecated: true diff --git a/changelogs/server_server/newsfragments/2097.clarification b/changelogs/server_server/newsfragments/2097.clarification new file mode 100644 index 00000000..10dcecb6 --- /dev/null +++ b/changelogs/server_server/newsfragments/2097.clarification @@ -0,0 +1 @@ +Clarify that the trailing slash is optional on ``/keys/*`` endpoints when no key ID is requested. diff --git a/specification/index.rst b/specification/index.rst index 33dff5a3..375e19c0 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -425,6 +425,42 @@ dedicated API. The API is symmetrical to managing Profile data. Would it really be overengineered to use the same API for both profile & private user data, but with different ACLs? + +Common concepts +--------------- + +Various things are common throughout all of the Matrix APIs. They are +documented here. + +Trailing slashes on API endpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unless the endpoint is explicltly specified to have a trailing slash, the +slash is optional. For example, an endpoint specified as ``/_matrix/example/`` +would require a trailing slash, however an endpoint specified as ``/_matrix/example`` +has an optional slash (can be excluded when making requests). + +Namespacing +~~~~~~~~~~~ + +Namespacing helps prevent conflicts between multiple applications and the specification +itself. Where namespacing is used, ``m.`` prefixes are used by the specification to +indicate that the field is controlled by the specification. Custom or non-specified +namespaces used in the wild SHOULD use the Java package naming convention to prevent +conflicts. + +As an example, event types are namespaced under ``m.`` in the specification however +any client can send a custom event type, such as ``com.example.game.score`` without +needing to put the event into the ``m.`` namespace. + +Timestamps +~~~~~~~~~~ + +Unless otherwise stated, timestamps are measured as milliseconds since the Unix epoch. +Throughout the specification this may be referred to as POSIX, Unix, or just "time in +milliseconds". + + .. _`room versions`: Room Versions From cd6b012523c5ea11974617036ec1ee189babdb99 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:07:49 -0600 Subject: [PATCH 206/497] Clarify what a "module" is and update feature profiles for clients Fixes https://github.com/matrix-org/matrix-doc/issues/2009 --- .../newsfragments/2098.clarification | 1 + specification/feature_profiles.rst | 36 ++++++++++++++++++- specification/modules.rst | 8 +++++ specification/modules/_template.rst | 2 +- 4 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2098.clarification diff --git a/changelogs/client_server/newsfragments/2098.clarification b/changelogs/client_server/newsfragments/2098.clarification new file mode 100644 index 00000000..1c8ba3ea --- /dev/null +++ b/changelogs/client_server/newsfragments/2098.clarification @@ -0,0 +1 @@ +Clarify what a "module" is and update feature profiles for clients. diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst index c6b8ef4c..bb638380 100644 --- a/specification/feature_profiles.rst +++ b/specification/feature_profiles.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2019 The Matrix.org Foundation C.I.C. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -32,33 +33,67 @@ Summary Module / Profile Web Mobile Desktop CLI Embedded ===================================== ========== ========== ========== ========== ========== `Instant Messaging`_ Required Required Required Required Optional + `Direct Messaging`_ Required Required Required Required Optional + `Mentions`_ Required Required Required Optional Optional `Presence`_ Required Required Required Required Optional `Push Notifications`_ Optional Required Optional Optional Optional `Receipts`_ Required Required Required Required Optional + `Fully read markers`_ Optional Optional Optional Optional Optional `Typing Notifications`_ Required Required Required Required Optional `VoIP`_ Required Required Required Optional Optional + `Ignoring Users`_ Required Required Required Optional Optional + `Reporting Content`_ Optional Optional Optional Optional Optional `Content Repository`_ Required Required Required Optional Optional `Managing History Visibility`_ Required Required Required Required Optional `Server Side Search`_ Optional Optional Optional Optional Optional + `Room Upgrades`_ Required Required Required Required Optional `Server Administration`_ Optional Optional Optional Optional Optional `Event Context`_ Optional Optional Optional Optional Optional `Third Party Networks`_ Optional Optional Optional Optional Optional + `Send-to-Device Messaging`_ Optional Optional Optional Optional Optional + `Device Management`_ Optional Optional Optional Optional Optional + `End-to-End Encryption`_ Optional Optional Optional Optional Optional + `Guest Accounts`_ Optional Optional Optional Optional Optional + `Room Previews`_ Optional Optional Optional Optional Optional + `Client Config`_ Optional Optional Optional Optional Optional + `SSO Login`_ Optional Optional Optional Optional Optional + `OpenID`_ Optional Optional Optional Optional Optional + `Stickers`_ Optional Optional Optional Optional Optional + `Server ACLs`_ Optional Optional Optional Optional Optional + `Server Notices`_ Optional Optional Optional Optional Optional ===================================== ========== ========== ========== ========== ========== *Please see each module for more details on what clients need to implement.* .. _Instant Messaging: `module:im`_ +.. _Direct Messaging: `module:dm`_ +.. _Mentions: `module:mentions`_ .. _Presence: `module:presence`_ .. _Push Notifications: `module:push`_ .. _Receipts: `module:receipts`_ +.. _Fully read markers: `module:read-markers`_ .. _Typing Notifications: `module:typing`_ .. _VoIP: `module:voip`_ +.. _Ignoring Users: `module:ignore_users`_ +.. _Reporting Content: `module:report_content`_ .. _Content Repository: `module:content`_ .. _Managing History Visibility: `module:history-visibility`_ .. _Server Side Search: `module:search`_ +.. _Room Upgrades: `module:room-upgrades`_ .. _Server Administration: `module:admin`_ .. _Event Context: `module:event-context`_ .. _Third Party Networks: `module:third-party-networks`_ +.. _Send-to-Device Messaging: `module:to_device`_ +.. _Device Management: `module:device-management`_ +.. _End-to-End Encryption: `module:e2e`_ +.. _Guest Accounts: `module:guest-access`_ +.. _Room Previews: `module:room-previews`_ +.. _Client Config: `module:account_data`_ +.. _SSO Login: `module:sso_login`_ +.. _OpenID: `module:openid`_ +.. _Stickers: `module:stickers`_ +.. _Server ACLs: `module:server-acls`_ +.. Server Notices already has a link elsewhere. Clients ------- @@ -110,4 +145,3 @@ This is a client which is typically running on an embedded device such as a kettle, fridge or car. These clients tend to perform a few operations and run in a resource constrained environment. Like embedded applications, they are not intended to be fully-fledged communication systems. - diff --git a/specification/modules.rst b/specification/modules.rst index 36f79cfd..f2269a5a 100644 --- a/specification/modules.rst +++ b/specification/modules.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2019 The Matrix.org Foundation C.I.C. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -15,3 +16,10 @@ Modules ======= +Modules are parts of the Client-Server API which are not universal to all +endpoints and are accessible to all clients. Modules are strictly defined +within this specification and should not be mistaken for XEP or equivalent +extensions from other protocols - in order for an implementation to be +compliant with the Client-Server specification it MUST support all modules +and supporting specification. The exception being clients, which are governed +by `Feature Profiles <#feature-profiles>`_. diff --git a/specification/modules/_template.rst b/specification/modules/_template.rst index aa4f93db..d1fef7f5 100644 --- a/specification/modules/_template.rst +++ b/specification/modules/_template.rst @@ -15,6 +15,7 @@ Module Heading ============== +.. NOTE: Prefer to identify-modules-with-dashes despite historical examples. .. _module:short-name: A short summary of the module. What features does this module provide? An anchor @@ -67,4 +68,3 @@ This includes privacy leaks: for example leaking presence info. How do misbehaving clients or servers impact this module? This section should always be included, if only to say "we've thought about it but there isn't anything to do here". - From 87d8d970745e107f4494256dcbe475fa2c73eda3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:19:08 -0600 Subject: [PATCH 207/497] Remove incomplete and weird sentence --- specification/modules.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/modules.rst b/specification/modules.rst index f2269a5a..6a2564ce 100644 --- a/specification/modules.rst +++ b/specification/modules.rst @@ -17,9 +17,8 @@ Modules ======= Modules are parts of the Client-Server API which are not universal to all -endpoints and are accessible to all clients. Modules are strictly defined -within this specification and should not be mistaken for XEP or equivalent -extensions from other protocols - in order for an implementation to be -compliant with the Client-Server specification it MUST support all modules -and supporting specification. The exception being clients, which are governed -by `Feature Profiles <#feature-profiles>`_. +endpoints. Modules are strictly defined within this specification and +should not be mistaken for XEP or equivalent extensions from other protocols +- in order for an implementation to be compliant with the Client-Server +specification it MUST support all modules and supporting specification. +The exception being clients, which are governed by `Feature Profiles <#feature-profiles>`_. From 49dbb3ee4fa25ff5a2c5b43115471bb32410982b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:26:27 -0600 Subject: [PATCH 208/497] Declare Matrix 1.0 in the index Fixes https://github.com/matrix-org/matrix-doc/issues/2044 --- specification/index.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/specification/index.rst b/specification/index.rst index 33dff5a3..67d17a11 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -52,14 +52,11 @@ is useful for browsing the Client-Server API. Introduction to the Matrix APIs ------------------------------- -.. WARNING:: - The Matrix specification is still evolving: the APIs are not yet frozen - and this document is in places a work in progress or stale. We have made every - effort to clearly flag areas which are still being finalised. - We're publishing it at this point because it's complete enough to be more than - useful and provide a canonical reference to how Matrix is evolving. Our end - goal is to mirror WHATWG's `Living Standard - `_. +.. Note:: + The Matrix specification is currently at version 1.0 - a milestone indicating that + anything built on top of Matrix can safely rely on the APIs in the specification + not changing drastically. The specification continues to evolve, however, mirroring + something similar to WHATWG's `Living Standard `_. Matrix is a set of open APIs for open-federated Instant Messaging (IM), Voice over IP (VoIP) and Internet of Things (IoT) communication, designed to create From 06ee60f0046b80d7d85f80e1b23d2c2e1147d0cd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:32:59 -0600 Subject: [PATCH 209/497] Clarify what compliant implementations are --- specification/modules.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/specification/modules.rst b/specification/modules.rst index 6a2564ce..1bc88445 100644 --- a/specification/modules.rst +++ b/specification/modules.rst @@ -18,7 +18,10 @@ Modules Modules are parts of the Client-Server API which are not universal to all endpoints. Modules are strictly defined within this specification and -should not be mistaken for XEP or equivalent extensions from other protocols -- in order for an implementation to be compliant with the Client-Server -specification it MUST support all modules and supporting specification. -The exception being clients, which are governed by `Feature Profiles <#feature-profiles>`_. +should not be mistaken for experimental extensions or optional features. +A compliant server implementation MUST support all modules and supporting +specification (unless the implementation only targets clients of certain +profiles, in which case only the required modules for those feature profiles +MUST be implemented). A compliant client implementation MUST support all +the required modules and supporting specification for the `Feature Profile <#feature-profiles>`_ +it targets. From 4f665f06e6cbdca0310c2cc5b533b1cdd1cf50d0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 17:42:37 -0600 Subject: [PATCH 210/497] Clarify what Matrix 1.0 is further And add a table for minimum versions. --- specification/index.rst | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/specification/index.rst b/specification/index.rst index 67d17a11..37c6d682 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -50,13 +50,34 @@ one of the above APIs. The `Matrix Client-Server API Swagger Viewer `_ is useful for browsing the Client-Server API. + +Matrix versions +~~~~~~~~~~~~~~~ + +.. Note:: + As of June 10th 2019, the Matrix specification is considered out of beta - + indicating that all currently released APIs are considered stable and secure + to the best of our knowledge, and the spec should contain the complete + information necessary to develop production-grade implementations of Matrix + without the need for external reference. + +Matrix 1.0 (released June 10th, 2019) consists of the following minimum API +versions: + +======================= ======= +API/Specification Version +======================= ======= +Client-Server API r0.5.0 +Server-Server API r0.1.2 +Application Service API r0.1.1 +Identity Service API r0.1.1 +Push Gateway API r0.1.0 +Room Version v5 +======================= ======= + + Introduction to the Matrix APIs ------------------------------- -.. Note:: - The Matrix specification is currently at version 1.0 - a milestone indicating that - anything built on top of Matrix can safely rely on the APIs in the specification - not changing drastically. The specification continues to evolve, however, mirroring - something similar to WHATWG's `Living Standard `_. Matrix is a set of open APIs for open-federated Instant Messaging (IM), Voice over IP (VoIP) and Internet of Things (IoT) communication, designed to create From ae9abe798ef07de9c48f739b50b01e955725c63b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 23:41:51 -0600 Subject: [PATCH 211/497] Revert signature change for redactable event test The previous signature was calculated on the unredacted event, which means the signature produced was wrong. --- specification/appendices/test_vectors.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendices/test_vectors.rst b/specification/appendices/test_vectors.rst index 7759fa88..790ed878 100644 --- a/specification/appendices/test_vectors.rst +++ b/specification/appendices/test_vectors.rst @@ -162,7 +162,7 @@ The event signing algorithm should emit the following signed event: "sender": "@u:domain", "signatures": { "domain": { - "ed25519:1": "4zc79tH2cU6Y+eg4YbbF7KiDOrnwEDjlhTqIKiH4k7L9zD9XCiomD7x9odL9eEwnyy1144QyMBe8O3HK++GHBg" + "ed25519:1": "Wm+VzmOUOz08Ds+0NTWb1d4CZrVsJSikkeRxh6aCcUwu6pNC78FunoD7KNWzqFn241eYHYMGCA5McEiVPdhzBA" } }, "unsigned": { From 7f01346bbad3f0cc31bf2d2fcfde4dd7daa0b2f6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 6 Jun 2019 23:50:26 -0600 Subject: [PATCH 212/497] Provide a more complete example of a "minimally-sized event" Using all the required fields of a v1 event. --- specification/appendices/test_vectors.rst | 25 +++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/specification/appendices/test_vectors.rst b/specification/appendices/test_vectors.rst index 790ed878..1de458cc 100644 --- a/specification/appendices/test_vectors.rst +++ b/specification/appendices/test_vectors.rst @@ -91,11 +91,22 @@ Given the following minimally-sized event: .. code:: json { + "room_id": "!x:domain", + "sender": "@a:domain", "event_id": "$0:domain", "origin": "domain", "origin_server_ts": 1000000, "signatures": {}, + "hashes": {}, "type": "X", + "content": {}, + "prev_events": [ + ["$1:domain", "ExampleHash"] + ], + "auth_events": [ + ["$2", "ExampleHash2"] + ], + "depth": 3, "unsigned": { "age_ts": 1000000 } @@ -106,15 +117,25 @@ The event signing algorithm should emit the following signed event: .. code:: json { + "auth_events": [ + ["$2", "6tJjLpXtggfke8UxFhAKg82QVkJzvKOVOOSjUDK4ZSI"] + ], + "content": {}, + "depth": 3, "event_id": "$0:domain", "hashes": { - "sha256": "6tJjLpXtggfke8UxFhAKg82QVkJzvKOVOOSjUDK4ZSI" + "sha256": "6AaJICN1NJURTtaomDYfJlCPMIU+0gtkwg7qzd8FiJM" }, "origin": "domain", "origin_server_ts": 1000000, + "prev_events": [ + ["$1:domain", "onLKD1bGljeBWQhWZ1kaP9SorVmRQNdN5aM2JYU2n/g"] + ], + "room_id": "!x:domain", + "sender": "@a:domain", "signatures": { "domain": { - "ed25519:1": "JV2dlZUASAefSdywnyCxzykHlyr7xkKGK7IRir1cF8eYsnONrCSb+GRn7aXXstr1UHKvzYjRXPx0001+boD1Ag" + "ed25519:1": "51U0wpKYsaNLTQRbha2v5EGO2cVA6pCtnAKEXguu3j3efCLlmq/53vEfWhsk3tY6gnLsV0YM4Lx2NGZkzmV2Ag" } }, "type": "X", From d7858354f26aa3bb8a6cc58e0b1db1d280eee21e Mon Sep 17 00:00:00 2001 From: Jamie McClymont Date: Fri, 7 Jun 2019 20:54:47 +1200 Subject: [PATCH 213/497] Fix 404s in links from room v1 spec --- specification/rooms/v1.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index 1c7a56c4..e8cbf663 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -293,5 +293,5 @@ Events in version 1 rooms have the following structure: {{definition_ss_pdu}} -.. _`auth events selection`: ../../server_server/r0.1.1.html#auth-events-selection -.. _`Signing Events`: ../../server_server/r0.1.1.html#signing-events +.. _`auth events selection`: ../server_server/r0.1.1.html#auth-events-selection +.. _`Signing Events`: ../server_server/r0.1.1.html#signing-events From 7f65704ebc23c8ebcd8f38b7e5c11172a28e2254 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 12:45:11 +0100 Subject: [PATCH 214/497] Update wording and answer review comments --- proposals/2078-homeserver-password-resets.md | 132 +++++++++++-------- 1 file changed, 75 insertions(+), 57 deletions(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index f8dfc53e..5064be20 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -3,70 +3,76 @@ This MSC proposes removing the current requirement of the identity server to send third-party request tokens, and allows homeservers to implement the functionality instead. These request tokens are used to verify the identity of -the request auther as an owner of the third-party identity (3PID). This can be -used for binding a 3PID to an account, or for resetting passwords via email or -SMS. The latter is what this proposal mainly focuses on, but be aware that it -allows for any task that requires requesting a token through a 3PID to be -taken on by the homeserver instead of the identity server. +the request author as an owner of the third-party ID (3PID). This can be used +for binding a 3PID to an account, or for resetting passwords via email or SMS. +The latter is what this proposal mainly focuses on, but be aware that it allows +for any task that requires requesting a token for a 3PID to be taken on by the +homeserver instead of the identity server. The intention is to put less trust in the identity server, which is currently one of the most centralised components of Matrix. As it stands, an attacker in control of a identity server can reset a user's password if the identity server is considered trusted by that homeserver, and the user has registered at least -one 3PID. This is due to the identity server currently handling the job of -confirming the user's control of that identity. +one 3PID. This is due to the identity server handling the job of confirming the +user's control of that identity. -The MSC aims to simply clarify that homeservers can take on the responsibility -of sending password reset tokens themselves. +The MSC seeks to clarify that homeservers can take on the responsibility of +sending password reset tokens themselves, and a new response field that will +aid homeservers in doing so. + +# Background + +Currently when a client requests a 3PID token, it makes a call to one of the +`/requestToken` endpoints on the homeserver. For instance, during password +resets, a token is requested from either +[/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) +or +[/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken), +depending on the medium of the 3PID. These requests are supplied all the +necessary details as well as an `id_server` field containing the domain address +of a identity server trusted by the homeserver. + +In order to facilitate these requests, the homeserver will simply proxy them to +the identity server. The IS will send out a token via email or sms, the user +will click a link or enter the token into their client, and either the client +or the user's browser will make a request **directly to the identity server** +with the token for verification. The IS then informs the homeserver that +verification was successful. At this point you can likely see that there is +potential for abuse here, so instead Homeservers should be given the option to +stop proxying the request to the identity server, and instead just send and +validate the token themselves. ## Proposal -Currently when a client requests a password reset, it makes a call to either -[/_matrix/client/r0/account/password/email/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-email-requesttoken) -or -[/_matrix/client/r0/account/password/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.4.0.html#post-matrix-client-r0-account-password-msisdn-requesttoken). -This request is supplied all the necessary details as well as an `id_server` -field containing the address of a identity server trusted by the homeserver. - -The `id_server` field is currently required as the homeserver must know where -to proxy the request to. This MSC proposes not to change the requirements of -this field. Instead, it asks to clarify that the homeserver is allowed to not -proxy the request, but carry it out itself. This would mean the homeserver can -both send password reset tokens (via email or SMS), as well as accept requests -an endpoint (with the same parameters as +The homeserver should be allowed to either proxy `/requestToken` requests or +handle them itself. Specifically, this means that the homeserver can both send +password reset tokens (via email or SMS), as well as accept requests on an +arbitrary endpoint (with the same parameters as [/_matrix/identity/api/v1/validate/email/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken)) to verify that token. -Consideration was taken not to make `id_server` and optional field. Let's -assume for a moment that it was optional. Now, a client could send a request to -`/requestToken` omitting the `id_server` field. The homeserver however has -opted to continue proxying `/requestToken` to the identity server, even though -it knows this is potentially insecure. The homeserver now has no idea which -identity server to proxy the request to, and must return a failure to the -client. The client could then make another request with an `id_server`, but -we've now made two requests that ended up in the same outcome, instead of one, -in hopes of saving a very small amount of bandwidth by omitting the field -originally. +One additional complication that in the case of SMS, just a code is sent to a +person's phone. This is then given to the client, but the client may not know +where to send the code now, as it doesn't know whether the homeserver or +identity server generated it. -An additional complication is that in the case of SMS, a full link to reset -passwords is not sent, but a short code. The client then asks the user to enter -this code, however the client may now not know where to send the code. Should -it send it to the identity server or the homeserver? Which sent out the code? - -In order to combat this problem, the field `submit_url` should be added in the -response from both the email and msisdn variants of the `/requestToken` -Client-Server API, if and only if the verification message contains a code the -user is expected to enter into the client (for instance in the case of a short -code through SMS). It SHOULD be in the form of -`/_matrix/identity/api/v1/validate/{3pid_type}/submitToken`, similar to the -[same endpoint that exists in the Identity-Server -API](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken). -If this field is omitted, the client MUST continue the same behaviour from -before, which is to send the token to the identity server directly. This is -intended for backwards compatibility with older servers. +In order to combat this problem, the field `submit_url` MUST be added in the +response from all of the variants of `/requestToken` in the Client-Server API, +if and only if the verification message contains a code the user is expected to +enter into the client (for instance in the case of a short code through SMS). +This URL is simply where the client should submit this token. The endpoint +should accept the same parameters as +[/_matrix/identity/api/v1/validate/{3pid_type}/submitToken](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-validate-email-submittoken) +in the Identity Service API. The only recommendation to homeserver developers +for this endpoint's path is to not be exactly the same as that of the identity +server, in order to prevent clashes between setups running both an identity +server and homeserver on the same domain. If `submit_url` is omitted, the +client MUST continue the same behaviour from before, which is to send the token +to the identity server directly. This is intended for backwards compatibility +with older servers. If the client receives a response to `/requestToken` with `submit_url`, it MUST -accept the token from user input, then make a POST request to the content of +accept a token from user input, then make a POST request to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. `submit_url` can lead to anywhere the homeserver deems necessary for verification. This data MUST be submitted as a JSON body. @@ -90,7 +96,7 @@ collect a token from the user and then submit it to the provided URL. ``` { "sid": "123abc", - "submit_url": "https://homeserver.tld/_matrix/identity/api/v1/validate/msisdn/submitToken" + "submit_url": "https://homeserver.tld/_homeserver/password_reset/msisdn/submitToken" } ``` @@ -99,7 +105,7 @@ user, say "123456", and then submit that as a POST request to the `"submit_url"`. ``` -POST https://homeserver.tld/_matrix/identity/api/v1/validate/msisdn/submitToken +POST https://homeserver.tld/_homeserver/password_reset/msisdn/submitToken { "sid": "123abc", @@ -120,15 +126,27 @@ If the client did not receive a `submit_url` field, they should instead assume that verification will be completed out of band (e.g. the user clicks a link in their email and makes the submitToken request with their web browser). +## Dismissed Alternatives + +Consideration was taken not to make `id_server` an optional field. Let's +assume for a moment that it was optional. Now, a client could send a request to +`/requestToken` omitting the `id_server` field. The homeserver however has +opted to continue proxying `/requestToken` to the identity server, even though +it knows this is potentially insecure. The homeserver now has no idea which +identity server to proxy the request to, and must return a failure to the +client. The client could then make another request with an `id_server`, but +we've now made two requests that ended up in the same outcome, instead of one, +in hopes of saving a very small amount of bandwidth by omitting the field +originally. + +At some point we should look into removing the `id_server` field altogether and +removing any email/SMS message sending from the identity server. This would +drastically reduce the amount of trust needed in the identity server and its +required ability. This is, however, a good first step. + ## Tradeoffs If homeservers choose to not proxy the request, they will need to implement the ability to send emails and/or SMS messages. This is left as a detail for the homeserver implementation. -## Future Considerations - -At some point we should look into removing the `id_server` field altogether and -removing any email/SMS message sending from the identity server. This would -drastically reduce the amount of trust needed in the identity server and its -required ability. This is, however, a good first step. From 45e271c0f7d1a79b37dce2fe9c73d0b8bb742874 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 13:29:22 +0100 Subject: [PATCH 215/497] be super explicit --- proposals/2078-homeserver-password-resets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2078-homeserver-password-resets.md b/proposals/2078-homeserver-password-resets.md index 5064be20..8dd7d9c9 100644 --- a/proposals/2078-homeserver-password-resets.md +++ b/proposals/2078-homeserver-password-resets.md @@ -75,7 +75,9 @@ If the client receives a response to `/requestToken` with `submit_url`, it MUST accept a token from user input, then make a POST request to the content of `submit_url` with the `sid`, `client_secret` and user-entered token. `submit_url` can lead to anywhere the homeserver deems necessary for -verification. This data MUST be submitted as a JSON body. +verification. To be clear the content of `id_server` does not matter here, the +client should just submit a POST request to the value of `submit_url`. Additionally +data MUST be submitted as a JSON body. An example exchange from the client's perspective is shown below: From 00fee7463623b38516687d1d4ea5463a5e5e3ec8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 07:40:52 -0600 Subject: [PATCH 216/497] Update example --- specification/appendices/test_vectors.rst | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/specification/appendices/test_vectors.rst b/specification/appendices/test_vectors.rst index 1de458cc..05b115db 100644 --- a/specification/appendices/test_vectors.rst +++ b/specification/appendices/test_vectors.rst @@ -93,19 +93,14 @@ Given the following minimally-sized event: { "room_id": "!x:domain", "sender": "@a:domain", - "event_id": "$0:domain", "origin": "domain", "origin_server_ts": 1000000, "signatures": {}, "hashes": {}, "type": "X", "content": {}, - "prev_events": [ - ["$1:domain", "ExampleHash"] - ], - "auth_events": [ - ["$2", "ExampleHash2"] - ], + "prev_events": [], + "auth_events": [], "depth": 3, "unsigned": { "age_ts": 1000000 @@ -117,25 +112,20 @@ The event signing algorithm should emit the following signed event: .. code:: json { - "auth_events": [ - ["$2", "6tJjLpXtggfke8UxFhAKg82QVkJzvKOVOOSjUDK4ZSI"] - ], + "auth_events": [], "content": {}, "depth": 3, - "event_id": "$0:domain", "hashes": { - "sha256": "6AaJICN1NJURTtaomDYfJlCPMIU+0gtkwg7qzd8FiJM" + "sha256": "5jM4wQpv6lnBo7CLIghJuHdW+s2CMBJPUOGOC89ncos" }, "origin": "domain", "origin_server_ts": 1000000, - "prev_events": [ - ["$1:domain", "onLKD1bGljeBWQhWZ1kaP9SorVmRQNdN5aM2JYU2n/g"] - ], + "prev_events": [], "room_id": "!x:domain", "sender": "@a:domain", "signatures": { "domain": { - "ed25519:1": "51U0wpKYsaNLTQRbha2v5EGO2cVA6pCtnAKEXguu3j3efCLlmq/53vEfWhsk3tY6gnLsV0YM4Lx2NGZkzmV2Ag" + "ed25519:1": "KxwGjPSDEtvnFgU00fwFz+l6d2pJM6XBIaMEn81SXPTRl16AqLAYqfIReFGZlHi5KLjAWbOoMszkwsQma+lYAg" } }, "type": "X", From d49c7fb3b02db22a4275bfb0f147b0b4a0477b6d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 08:01:17 -0600 Subject: [PATCH 217/497] Apply suggestions from code review Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- event-schemas/schema/m.key.verification.accept | 2 +- specification/modules/end_to_end_encryption.rst | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/event-schemas/schema/m.key.verification.accept b/event-schemas/schema/m.key.verification.accept index e52df39e..41c59968 100644 --- a/event-schemas/schema/m.key.verification.accept +++ b/event-schemas/schema/m.key.verification.accept @@ -17,7 +17,7 @@ properties: type: string enum: ["m.sas.v1"] description: |- - The verification method to use. Must be ``m.sas.v1``. + The verification method to use. key_agreement_protocol: type: string description: |- diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 4bd12b71..fb3d2ba5 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -536,15 +536,15 @@ The process between Alice and Bob verifying each other would be: .. |AlicePublicKey| replace:: :math:`K_{A}^{public}` .. |AlicePrivateKey| replace:: :math:`K_{A}^{private}` -.. |AliceCurve25519| replace:: :math:`K_{A}^{private}K_{A}^{public}` +.. |AliceCurve25519| replace:: :math:`K_{A}^{private},K_{A}^{public}` .. |BobPublicKey| replace:: :math:`K_{B}^{public}` .. |BobPrivateKey| replace:: :math:`K_{B}^{private}` -.. |BobCurve25519| replace:: :math:`K_{B}^{private}K_{B}^{public}` +.. |BobCurve25519| replace:: :math:`K_{B}^{private},K_{B}^{public}` .. |AliceBobCurve25519| replace:: :math:`K_{A}^{private}K_{B}^{public}` .. |BobAliceCurve25519| replace:: :math:`K_{B}^{private}K_{A}^{public}` .. |AliceBobECDH| replace:: :math:`ECDH(K_{A}^{private},K_{B}^{public})` -1. Alice and Bob establish a secure connection, likely meeting in-person. "Secure" +1. Alice and Bob establish a secure out-of-band connection, such as meeting in-person or a video call. "Secure" here means that either party cannot be impersonated, not explicit secrecy. #. Alice and Bob communicate which devices they'd like to verify with each other. #. Alice selects Bob's device from the device list and begins verification. @@ -573,9 +573,9 @@ The process between Alice and Bob verifying each other would be: methods are available, clients should allow the users to select a method. #. Alice and Bob compare the strings shown by their devices, and tell their devices if they match or not. -#. Assuming they match, Alice and Bob's devices calculate the HMAC of their own device +#. Assuming they match, Alice and Bob's devices calculate the HMAC of their own device keys and a comma-separated sorted list of of the key IDs that they wish the other user - to verify. HMAC is defined in RFC 2104, and SHA-256 as the hash function. The key for + to verify, using SHA-256 as the hash function. HMAC is defined in [RFC 2104](https://tools.ietf.org/html/rfc2104). The key for the HMAC is different for each item and is calculated by generating 32 bytes (256 bits) using `the key verification HKDF <#SAS-HKDF>`_. #. Alice's device sends Bob's device a ``m.key.verification.mac`` message containing the @@ -619,7 +619,7 @@ At any point the interactive verfication can go wrong. The following describes w to do when an error happens: * Alice or Bob can cancel the verification at any time. A ``m.key.verification.cancel`` - message must be sent to signify the cancelation. + message must be sent to signify the cancellation. * The verification can time out. Clients should time out a verification that does not complete within 5 minutes. Additionally, clients should expire a ``transaction_id`` which goes unused for 5 minutes after having last sent/received it. The client should @@ -668,8 +668,8 @@ are used in addition to those already specified: HKDF calculation <<<<<<<<<<<<<<<< -In all of the SAS methods, HKDF is as defined in RFC 5869 and uses the previously -agreed upon hash function for the hash function. The shared secret is supplied +In all of the SAS methods, HKDF is as defined in [RFC 5869](https://tools.ietf.org/html/rfc5869) and uses the previously +agreed-upon hash function for the hash function. The shared secret is supplied as the input keying material. No salt is used, and the input parameter is the concatenation of: From 3877896a4cb232ce760f1556d7a1fc6de001b95f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 08:10:52 -0600 Subject: [PATCH 218/497] Clarify how we now expect verification to be done --- .../modules/end_to_end_encryption.rst | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index fb3d2ba5..fb320dc4 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -384,20 +384,10 @@ man-in-the-middle. This verification process requires an out-of-band channel: there is no way to do it within Matrix without trusting the administrators of the homeservers. -In Matrix, the basic process for device verification is for Alice to verify -that the public Ed25519 signing key she received via ``/keys/query`` for Bob's -device corresponds to the private key in use by Bob's device. For now, it is -recommended that clients provide mechanisms by which the user can see: - -1. The public part of their device's Ed25519 signing key, encoded using - `unpadded Base64`_. - -2. The list of devices in use for each user in a room, along with the public - Ed25519 signing key for each device, again encoded using unpadded Base64. - -Alice can then meet Bob in person, or contact him via some other trusted -medium, and use `SAS Verification`_ or ask him to read out the Ed25519 key -shown on his device, comparing it to the one shown on Alice's device. +In Matrix, verification works by Alice meeting Bob in person, or contact him +via some other trusted medium, and use `SAS Verification`_ to interactively +verify Bob's devices. Alice and Bob may also read aloud their unpadded base64 +encoded Ed25519 public key, as returned by ``/keys/query``. Device verification may reach one of several conclusions. For example: From 5ec1a50b94cca9a92951b7f3139c4ff76ed6c2b2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 08:12:09 -0600 Subject: [PATCH 219/497] Linefeeds and other clarifications --- .../modules/end_to_end_encryption.rst | 39 ++++++++++--------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index fb320dc4..0de1328b 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -530,12 +530,12 @@ The process between Alice and Bob verifying each other would be: .. |BobPublicKey| replace:: :math:`K_{B}^{public}` .. |BobPrivateKey| replace:: :math:`K_{B}^{private}` .. |BobCurve25519| replace:: :math:`K_{B}^{private},K_{B}^{public}` -.. |AliceBobCurve25519| replace:: :math:`K_{A}^{private}K_{B}^{public}` .. |BobAliceCurve25519| replace:: :math:`K_{B}^{private}K_{A}^{public}` .. |AliceBobECDH| replace:: :math:`ECDH(K_{A}^{private},K_{B}^{public})` -1. Alice and Bob establish a secure out-of-band connection, such as meeting in-person or a video call. "Secure" - here means that either party cannot be impersonated, not explicit secrecy. +1. Alice and Bob establish a secure out-of-band connection, such as meeting + in-person or a video call. "Secure" here means that either party cannot be + impersonated, not explicit secrecy. #. Alice and Bob communicate which devices they'd like to verify with each other. #. Alice selects Bob's device from the device list and begins verification. #. Alice's client ensures it has a copy of Bob's device key. @@ -565,9 +565,9 @@ The process between Alice and Bob verifying each other would be: they match or not. #. Assuming they match, Alice and Bob's devices calculate the HMAC of their own device keys and a comma-separated sorted list of of the key IDs that they wish the other user - to verify, using SHA-256 as the hash function. HMAC is defined in [RFC 2104](https://tools.ietf.org/html/rfc2104). The key for - the HMAC is different for each item and is calculated by generating 32 bytes (256 bits) - using `the key verification HKDF <#SAS-HKDF>`_. + to verify, using SHA-256 as the hash function. HMAC is defined in [RFC 2104](https://tools.ietf.org/html/rfc2104). + The key for the HMAC is different for each item and is calculated by generating + 32 bytes (256 bits) using `the key verification HKDF <#SAS-HKDF>`_. #. Alice's device sends Bob's device a ``m.key.verification.mac`` message containing the MAC of Alice's device keys and the MAC of her key IDs to be verified. Bob's device does the same for Bob's device keys and key IDs concurrently with Alice. @@ -611,12 +611,12 @@ to do when an error happens: * Alice or Bob can cancel the verification at any time. A ``m.key.verification.cancel`` message must be sent to signify the cancellation. * The verification can time out. Clients should time out a verification that does not - complete within 5 minutes. Additionally, clients should expire a ``transaction_id`` - which goes unused for 5 minutes after having last sent/received it. The client should - inform the user that the verification timed out, and send an appropriate ``m.key.verification.cancel`` - message to the other device. -* When the same device attempts to intiate multiple verification attempts, cancel all - attempts with that device. + complete within 10 minutes. Additionally, clients should expire a ``transaction_id`` + which goes unused for 10 minutes after having last sent/received it. The client should + inform the user that the verification timed out, and send an appropriate + ``m.key.verification.cancel`` message to the other device. +* When the same device attempts to intiate multiple verification attempts, the receipient + should cancel all attempts with that device. * When a device receives an unknown ``transaction_id``, it should send an appropriate ``m.key.verfication.cancel`` message to the other device indicating as such. This does not apply for inbound ``m.key.verification.start`` or ``m.key.verification.cancel`` @@ -658,10 +658,10 @@ are used in addition to those already specified: HKDF calculation <<<<<<<<<<<<<<<< -In all of the SAS methods, HKDF is as defined in [RFC 5869](https://tools.ietf.org/html/rfc5869) and uses the previously -agreed-upon hash function for the hash function. The shared secret is supplied -as the input keying material. No salt is used, and the input parameter is the -concatenation of: +In all of the SAS methods, HKDF is as defined in [RFC 5869](https://tools.ietf.org/html/rfc5869) +and uses the previously agreed-upon hash function for the hash function. The shared +secret is supplied as the input keying material. No salt is used, and the input +parameter is the concatenation of: * The string ``MATRIX_KEY_VERIFICATION_SAS``. * The Matrix ID of the user who sent the ``m.key.verification.start`` message. @@ -670,8 +670,9 @@ concatenation of: * The Device ID of the device which sent the ``m.key.verification.accept`` message. * The ``transaction_id`` being used. -HKDF is used over the plain shared secret as it results in a harder attack -as well as more uniform data to work with. +.. admonition:: Rationale + HKDF is used over the plain shared secret as it results in a harder attack + as well as more uniform data to work with. For verification of each party's device keys, HKDF is as defined in RFC 5869 and uses SHA-256 as the hash function. The shared secret is supplied as the input keying @@ -697,7 +698,7 @@ The bitwise operations to get the numbers given the 5 bytes :math:`B_{0}, B_{1}, B_{2}, B_{3}, B_{4}` would be: * First: :math:`(B_{0} \ll 5 | B_{1} \gg 3) + 1000` -* Second: :math:`(B_{1} \& 0x7 | B_{2} \ll 2 | B_{3} \gg 6) + 1000` +* Second: :math:`((B_{1} \& 0x7) \ll 10 | B_{2} \ll 2 | B_{3} \gg 6) + 1000` * Third: :math:`((B_{3} \& 0x3F) \ll 7 | B_{4} \gg 1) + 1000` The digits are displayed to the user either with an appropriate separator, From 77c4c4b07cb1cfe30d7a3477944eb2229e62ab2f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 08:27:18 -0600 Subject: [PATCH 220/497] Add general clarity --- api/client-server/definitions/room_event_filter.yaml | 2 +- api/client-server/sync.yaml | 9 +++++---- specification/client_server_api.rst | 3 +++ specification/modules/instant_messaging.rst | 2 +- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 0659be8e..7045396d 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -25,7 +25,7 @@ allOf: include_redundant_members: type: boolean description: |- - If ``true``, enables redudant membership events. Does not + If ``true``, enables redundant membership events. Does not apply unless ``lazy_load_members`` is ``true``. See `Lazy-loading room members <#lazy-loading-room-members>`_ for more information. Defaults to ``false``. diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index a0d2fd60..ed9d7420 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -40,10 +40,11 @@ paths: for this endpoint. When lazy-loading is enabled, servers MUST include the syncing user's own membership event when they join a room, or when the full state of rooms is requested. The user's own membership event is eligible - for being considered redudant by the server. When a sync is ``limited``, - the server MUST return membership events for the timeline, even if the - applicable events are not in the response, regardless as to whether or not - they are redundant. + for being considered redundant by the server. When a sync is ``limited``, + the server MUST return membership events for events in the gap (from ``since``), + even if the applicable events are not in the response, regardless as to whether + or not they are redundant. ``include_redundant_members`` is ignored for limited + syncs. operationId: sync security: - accessToken: [] diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 740023fb..5290ec20 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1306,6 +1306,9 @@ The current endpoints which support lazy-loading room members are: * |/rooms//messages|_ * |/rooms/{roomId}/context/{eventId}|_ +API endpoints +~~~~~~~~~~~~~ + {{filter_cs_http_api}} Events diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index dd3e9c6c..c514f481 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -293,7 +293,7 @@ choose a name: users (`disambiguating them if required`_) and concatenating them. For example, the client may choose to show "Alice, Bob, and Charlie (@charlie:example.org)" as the room name. The client may optionally - limit the number + limit the number of users it uses to generate a room name. #. If there are fewer heroes than ``m.joined_member_count + m.invited_member_count - 1``, and ``m.joined_member_count + m.invited_member_count`` is greater From a0e82018161f82a723e2d57eb3e14eec42d66610 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 08:27:53 -0600 Subject: [PATCH 221/497] Apply suggestions from code review Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- api/client-server/event_context.yaml | 2 +- api/client-server/message_pagination.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 327c8f43..0e7fa531 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -35,7 +35,7 @@ paths: after the specified event. This allows clients to get the context surrounding an event. - *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_ + *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_ for more information. operationId: getEventContext security: diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 8469eec4..c5d7b8fc 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -34,7 +34,7 @@ paths: This API returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room. - *Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_ + *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_ for more information. operationId: getRoomEvents security: From 360ac0b90088a0b9fcb6876fb9bac847fb3f0038 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 08:54:21 -0600 Subject: [PATCH 222/497] Update specification/server_server_api.rst Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- specification/server_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 812f0ffc..7acc71e4 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1100,7 +1100,7 @@ a redacted copy. The signatures expected on an event are: -* The sender's server, unless the invite was created as a result of 3rd party invite. +* The ``sender``'s server, unless the invite was created as a result of 3rd party invite. The sender must already match the 3rd party invite, and the server which actually sends the event may be a different server. * For room versions 1 and 2, the server which created the ``event_id``. Other room From 31481840525620c8ac657d31956cfa9428f8f2b0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 10:58:43 +0100 Subject: [PATCH 223/497] HS' can send 3PID token. Add a new submit_url field --- api/client-server/administrative_contact.yaml | 116 +++++++++++-- api/client-server/registration.yaml | 162 ++++++++++++++---- 2 files changed, 228 insertions(+), 50 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 33ea9786..d62a4fab 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -132,11 +132,30 @@ paths: } responses: 200: - description: The addition was successful. + description: |- + The addition was successful. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. examples: - application/json: {} + application/json: { + "submit_url": "https://example.org/path/to/submitToken" + } schema: type: object + properties: + submit_url: + type: string + description: |- + An optional URL to submit information to to verify a + third-party identifier. + example: "https://example.org/path/to/submitToken" 403: description: The credentials could not be verified with the identity server. examples: @@ -187,12 +206,14 @@ paths: post: summary: Begins the validation process for an email address for association with the user's account. description: |- - Proxies the Identity Service API ``validate/email/requestToken``, but - first checks that the given email address is **not** already associated - with an account on this homeserver. This API should be used to request - validation tokens when adding an email address to an account. This API's - parameters and response are identical to that of the |/register/email/requestToken|_ - endpoint. + The homeserver should check that the given email address is **not** + already associated with an account on this homeserver. This API should + be used to request validation tokens when adding an email address to an + account. This API's parameters and response are identical to that of + the |/register/email/requestToken|_ endpoint. The homeserver has the + choice of validating the email address itself, or proxying the request + to the ``validate/email/requestToken`` Identity Server API on the + server sent in ``id_server``. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -212,9 +233,38 @@ paths: required: ['id_server'] responses: 200: - description: An email was sent to the given address. + description: |- + An email was sent to the given address. + Note that this may be an email containing the validation token or + it may be informing the user of an error. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: |- The homeserver does not allow the third party identifier as a @@ -241,12 +291,14 @@ paths: post: summary: Begins the validation process for a phone number for association with the user's account. description: |- - Proxies the Identity Service API ``validate/msisdn/requestToken``, but - first checks that the given phone number is **not** already associated - with an account on this homeserver. This API should be used to request - validation tokens when adding a phone number to an account. This API's - parameters and response are identical to that of the |/register/msisdn/requestToken|_ - endpoint. + The homeserver should check that the given phone number is **not** + already associated with an account on this homeserver. This API should + be used to request validation tokens when adding a phone number to an + account. This API's parameters and response are identical to that of + the |/register/msisdn/requestToken|_ endpoint. The homeserver has the + choice of validating the phone number itself, or proxying the request + to the ``validate/msisdn/requestToken`` Identity Server API on the + server sent in ``id_server``. operationId: requestTokenTo3PIDMSISDN parameters: - in: body @@ -266,9 +318,37 @@ paths: required: ['id_server'] responses: 200: - description: An SMS message was sent to the given phone number. + description: |- + An SMS message was sent to the given phone number. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/msisdn/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" + 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 3195ab41..00d2e90f 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -204,10 +204,11 @@ paths: post: summary: Begins the validation process for an email to be used during registration. description: |- - Proxies the Identity Service API ``validate/email/requestToken``, but - first checks that the given email address is not already associated - with an account on this homeserver. See the Identity Service API for - further information. + The homeserver should check that the given email address is **not** + already associated with an account on this homeserver. The homeserver + has the choice of validating the email address itself, or proxying the + request to the ``validate/email/requestToken`` Identity Server API on + the server sent in ``id_server``. operationId: requestTokenToRegisterEmail parameters: - in: body @@ -231,8 +232,34 @@ paths: An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: The homeserver does not permit the address to be bound. schema: @@ -264,10 +291,11 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account description: |- - Proxies the Identity Service API ``validate/msisdn/requestToken``, but - first checks that the given phone number is not already associated - with an account on this homeserver. See the Identity Service API for - further information. + The homeserver should check that the given phone number is **not** + already associated with an account on this homeserver. The homeserver + has the choice of validating the phone number itself, or proxying the + request to the ``validate/msisdn/requestToken`` Identity Server API on + the server sent in ``id_server``. operationId: requestTokenToRegisterMSISDN parameters: - in: body @@ -291,8 +319,34 @@ paths: An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/msisdn/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: The homeserver does not permit the address to be bound. schema: @@ -377,16 +431,21 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- - Proxies the Identity Service API ``validate/email/requestToken``, but - first checks that the given email address **is** associated with an account - on this homeserver. This API should be used to request - validation tokens when authenticating for the - `account/password` endpoint. This API's parameters and response are - identical to that of the HS API |/register/email/requestToken|_ except that - `M_THREEPID_NOT_FOUND` may be returned if no account matching the - given email address could be found. The server may instead send an - email to the given address prompting the user to create an account. - `M_THREEPID_IN_USE` may not be returned. + The homeserver should check that the given email address **is + associated** with an account on this homeserver. This API should be + used to request validation tokens when authenticating for the + ``account/password`` endpoint. + + This API's parameters and response are identical to that of the HS API + |/register/email/requestToken|_ except that ``M_THREEPID_NOT_FOUND`` + may be returned if no account matching the given email address could be + found. The server may instead send an email to the given address + prompting the user to create an account. ``M_THREEPID_IN_USE`` may not + be returned. + + The homeserver has the choice of validating the email address itself, + or proxying the request to the ``validate/email/requestToken`` Identity + server api on the server sent in ``id_server``. .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` @@ -412,7 +471,24 @@ paths: 200: description: An email was sent to the given address. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit a validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: |- The homeserver does not allow the third party identifier as a @@ -439,16 +515,21 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. description: |- - Proxies the Identity Service API ``validate/msisdn/requestToken``, but - first checks that the given phone number **is** associated with an account - on this homeserver. This API should be used to request - validation tokens when authenticating for the - `account/password` endpoint. This API's parameters and response are - identical to that of the HS API |/register/msisdn/requestToken|_ except that - `M_THREEPID_NOT_FOUND` may be returned if no account matching the - given phone number could be found. The server may instead send an - SMS message to the given address prompting the user to create an account. - `M_THREEPID_IN_USE` may not be returned. + The homeserver should check that the given phone number **is + associated** with an account on this homeserver. This API should be + used to request validation tokens when authenticating for the + ``account/password`` endpoint. + + This API's parameters and response are identical to that of the HS API + |/register/msisdn/requestToken|_ except that ``M_THREEPID_NOT_FOUND`` may + be returned if no account matching the given phone number could be + found. The server may instead send the SMS to the given phone number + prompting the user to create an account. ``M_THREEPID_IN_USE`` may not + be returned. + + The homeserver has the choice of validating the phone number itself, or + proxying the request to the ``validate/msisdn/requestToken`` Identity + server api on the server sent in ``id_server``. .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` @@ -474,7 +555,24 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit a validation token to, with identical parameters + to the Identity Service API's + ``/validate/msisdn/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: |- The homeserver does not allow the third party identifier as a From e4339fd68755344527cce85895ac131ee8618e6e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 09:01:14 -0600 Subject: [PATCH 224/497] More clarity --- specification/client_server_api.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 5290ec20..c62740d4 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1276,12 +1276,12 @@ effort to reduce the number of resources used, clients can enable "lazy-loading" for room members. By doing this, servers will only ever send membership events which are relevant to the client. -In terms of filters, this means enabling ``lazy_load_members`` on a ``StateFilter`` -or ``RoomEventFilter``. When enabled, lazy-loading aware endpoints (see below) -will only include membership events for the ``sender`` of events being included -in the response. For example, if a client makes a ``/sync`` request with lazy-loading -enabled, the server will only return membership events for the ``sender`` of events -in the timeline, not all members of a room. +In terms of filters, this means enabling ``lazy_load_members`` on a ``RoomEventFilter`` +(or a ``StateFilter`` in the case of ``/sync`` only). When enabled, lazy-loading +aware endpoints (see below) will only include membership events for the ``sender`` +of events being included in the response. For example, if a client makes a ``/sync`` +request with lazy-loading enabled, the server will only return membership events +for the ``sender`` of events in the timeline, not all members of a room. Repeated calls to lazy-loading aware endpoints will result in redundant membership events being excluded by default. Clients often track which membership events they From 46747e897ecc0b7c4c06e6488a02b5c208c87d3d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 10:32:06 -0600 Subject: [PATCH 225/497] ing --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 0de1328b..62881967 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -384,7 +384,7 @@ man-in-the-middle. This verification process requires an out-of-band channel: there is no way to do it within Matrix without trusting the administrators of the homeservers. -In Matrix, verification works by Alice meeting Bob in person, or contact him +In Matrix, verification works by Alice meeting Bob in person, or contacting him via some other trusted medium, and use `SAS Verification`_ to interactively verify Bob's devices. Alice and Bob may also read aloud their unpadded base64 encoded Ed25519 public key, as returned by ``/keys/query``. From a38af2009f72fc91f3aa4a90a323a050ba8dde06 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 7 Jun 2019 10:37:57 -0600 Subject: [PATCH 226/497] Apply suggestions from code review Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- api/client-server/message_pagination.yaml | 6 +++--- api/client-server/sync.yaml | 4 ++-- specification/client_server_api.rst | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index c5d7b8fc..3e01437a 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -115,14 +115,14 @@ paths: type: array description: |- A list of state events relevant to showing the ``chunk``. For example, if - lazy-loading members is enabled in the filter then this will contain any - applicable membership events. Servers should be careful to not exclude + ``lazy_load_members`` is enabled in the filter then this will contain any + the membership events for the the senders of events in the ``chunk``. Servers should be careful to not exclude membership events which are older than ones already sent to the client. Likewise, clients should be cautious and avoid using older membership events as the current membership event when paginating backwards. Unless ``include_redundant_members`` is ``true``, the server should remove - redundant members which would have already been sent to clients in prior calls + membership events which would have already been sent to clients in prior calls to lazy-loading aware endpoints with the same filter. items: type: object diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index ed9d7420..45829f68 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -41,8 +41,8 @@ paths: syncing user's own membership event when they join a room, or when the full state of rooms is requested. The user's own membership event is eligible for being considered redundant by the server. When a sync is ``limited``, - the server MUST return membership events for events in the gap (from ``since``), - even if the applicable events are not in the response, regardless as to whether + the server MUST return membership events for events in the gap (between ``since`` and the start of the returned timeline), + regardless as to whether or not they are redundant. ``include_redundant_members`` is ignored for limited syncs. operationId: sync diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index c62740d4..42f34849 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1286,7 +1286,7 @@ for the ``sender`` of events in the timeline, not all members of a room. Repeated calls to lazy-loading aware endpoints will result in redundant membership events being excluded by default. Clients often track which membership events they already have, therefore making the extra information not as useful to the client. -Clients can always request redundant members by setting ``include_redundant_members`` +Clients can always request redundant membership events by setting ``include_redundant_members`` to true in the filter. Servers should be cautious about which events they consider redundant. Membership @@ -1296,9 +1296,9 @@ as the current membership event for a user. .. Note:: Repeated calls using the same filter to *any* lazy-loading aware endpoint may - result in redundant members being excluded from future calls. For example, a + result in redundant membership events being excluded from future calls. For example, a request to ``/sync`` followed by a request to ``/messages`` may result in a - future call to ``/sync`` excluding members included by the ``/messages`` call. + future call to ``/sync`` excluding membership events returned by the ``/messages`` call. The current endpoints which support lazy-loading room members are: From 8a6ef187db803e8150670b6b3b16a496eccfd9db Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 17:52:17 +0100 Subject: [PATCH 227/497] more object! --- api/client-server/administrative_contact.yaml | 2 ++ api/client-server/registration.yaml | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 71ea3e6a..c2985f66 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -272,6 +272,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -355,6 +356,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index c8afed83..769614c1 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -248,6 +248,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -335,6 +336,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -477,6 +479,7 @@ paths: 200: description: An email was sent to the given address. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -561,6 +564,7 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object From a8edb066aa52bdadff63c2fa9d9b5ad50a8f5b99 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 18:00:12 +0100 Subject: [PATCH 228/497] Clear up some wording --- api/client-server/registration.yaml | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 769614c1..d97766e2 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -213,8 +213,10 @@ paths: The homeserver should check that the given email address is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the email address itself, or proxying the - request to the ``validate/email/requestToken`` Identity Server API on - the server sent in ``id_server``. + request to the ``validate/email/requestToken`` Identity Server API. The + request should be proxied to the domain that is sent by the client in + the ``id_server``. It is imperative that the homeserver keep a list of + trusted Identity Servers and only proxies to those it trusts. operationId: requestTokenToRegisterEmail parameters: - in: body @@ -301,8 +303,10 @@ paths: The homeserver should check that the given phone number is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the phone number itself, or proxying the - request to the ``validate/msisdn/requestToken`` Identity Server API on - the server sent in ``id_server``. + request to the ``validate/msisdn/requestToken`` Identity Server API. The + request should be proxied to the domain that is sent by the client in + the ``id_server``. It is imperative that the homeserver keep a list of + trusted Identity Servers and only proxies to those it trusts. operationId: requestTokenToRegisterMSISDN parameters: - in: body @@ -453,7 +457,11 @@ paths: The homeserver has the choice of validating the email address itself, or proxying the request to the ``validate/email/requestToken`` Identity - server api on the server sent in ``id_server``. + Server API. The request should be proxied to the domain that is sent by + the client in the ``id_server``. It is imperative that the homeserver + keep a list of trusted Identity Servers and only proxies to those it + trusts. + .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` @@ -536,9 +544,12 @@ paths: prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - The homeserver has the choice of validating the phone number itself, or - proxying the request to the ``validate/msisdn/requestToken`` Identity - server api on the server sent in ``id_server``. + The homeserver has the choice of validating the phone number itself, + or proxying the request to the ``validate/msisdn/requestToken`` Identity + Server API. The request should be proxied to the domain that is sent by + the client in the ``id_server``. It is imperative that the homeserver + keep a list of trusted Identity Servers and only proxies to those it + trusts. .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` From be568ba9ab8c8f4342220331eb66fe70ae09e5c7 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Fri, 7 Jun 2019 19:10:26 +0100 Subject: [PATCH 229/497] link to the legalified version of MSC1779 --- proposals/1779-open-governance.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/1779-open-governance.md b/proposals/1779-open-governance.md index 0a1cfca4..bfe86eb8 100644 --- a/proposals/1779-open-governance.md +++ b/proposals/1779-open-governance.md @@ -12,6 +12,9 @@ for more context. This obsoletes [MSC1318](https://github.com/matrix-org/matrix-doc/issues/1318). +**This MSC is now formalised in the official Rules of the Matrix.org Foundation, +maintained at https://docs.google.com/document/d/1MhqsuIUxPc7Vf_y8D250mKZlLeQS6E39DPY6Azpc2NY** + ## Introduction Historically the core team of Matrix has been paid to work on it by the same From 1776ba28d3d98d3a63c7b7becc032621aab9632b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sat, 8 Jun 2019 18:52:38 +0100 Subject: [PATCH 230/497] Address review comments --- api/client-server/administrative_contact.yaml | 70 +++++--------- api/client-server/registration.yaml | 94 ++++++++----------- 2 files changed, 63 insertions(+), 101 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index c2985f66..bc6f98c7 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -134,15 +134,6 @@ paths: 200: description: |- The addition was successful. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/email/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. examples: application/json: { "submit_url": "https://example.org/path/to/submitToken" @@ -153,8 +144,15 @@ paths: submit_url: type: string description: |- - An optional URL to submit information to to verify a - third-party identifier. + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. example: "https://example.org/path/to/submitToken" 403: description: The credentials could not be verified with the identity server. @@ -231,14 +229,14 @@ paths: post: summary: Begins the validation process for an email address for association with the user's account. description: |- - The homeserver should check that the given email address is **not** + The homeserver must check that the given email address is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint. The homeserver has the choice of validating the email address itself, or proxying the request - to the ``validate/email/requestToken`` Identity Server API on the - server sent in ``id_server``. + to the ``validate/email/requestToken`` Identity Service API as + identified by ``id_server``. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -262,15 +260,6 @@ paths: An email was sent to the given address. Note that this may be an email containing the validation token or it may be informing the user of an error. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/email/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. schema: type: object allOf: @@ -280,11 +269,11 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be + must send this token to the user, which should then be prompted to provide it to the client. If this field is not present, the client can assume that @@ -317,14 +306,14 @@ paths: post: summary: Begins the validation process for a phone number for association with the user's account. description: |- - The homeserver should check that the given phone number is **not** + The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint. The homeserver has the choice of validating the phone number itself, or proxying the request - to the ``validate/msisdn/requestToken`` Identity Server API on the - server sent in ``id_server``. + to the ``validate/msisdn/requestToken`` Identity Service API as + identified by ``id_server``. operationId: requestTokenTo3PIDMSISDN parameters: - in: body @@ -345,16 +334,7 @@ paths: responses: 200: description: |- - An SMS message was sent to the given phone number. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/msisdn/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. + A SMS message was sent to the given phone number. schema: type: object allOf: @@ -364,12 +344,12 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index d97766e2..c8615d29 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -210,10 +210,10 @@ paths: post: summary: Begins the validation process for an email to be used during registration. description: |- - The homeserver should check that the given email address is **not** + The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the email address itself, or proxying the - request to the ``validate/email/requestToken`` Identity Server API. The + request to the ``validate/email/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -240,15 +240,6 @@ paths: An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/email/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. schema: type: object allOf: @@ -258,12 +249,12 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's @@ -300,10 +291,10 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account description: |- - The homeserver should check that the given phone number is **not** + The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the phone number itself, or proxying the - request to the ``validate/msisdn/requestToken`` Identity Server API. The + request to the ``validate/msisdn/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -327,18 +318,9 @@ paths: responses: 200: description: |- - An SMS message has been sent to the specified phone number. - Note that this may be an SMS message containing the validation token or it may be informing - the user of an error. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/msisdn/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. + A SMS message has been sent to the specified phone number. Note + that this may be an SMS message containing the validation token or + it may be informing the user of an error. schema: type: object allOf: @@ -348,12 +330,12 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's @@ -443,17 +425,17 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- - The homeserver should check that the given email address **is + The homeserver must check that the given email address **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the ``account/password`` endpoint. - This API's parameters and response are identical to that of the HS API - |/register/email/requestToken|_ except that ``M_THREEPID_NOT_FOUND`` - may be returned if no account matching the given email address could be - found. The server may instead send an email to the given address - prompting the user to create an account. ``M_THREEPID_IN_USE`` may not - be returned. + This API's parameters and response are identical to that of the + |/register/email/requestToken|_ endpoint, except that + ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the + given email address could be found. The server may instead send an + email to the given address prompting the user to create an account. + ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the email address itself, or proxying the request to the ``validate/email/requestToken`` Identity @@ -496,11 +478,11 @@ paths: type: string description: |- An optional field containing a URL where the client must - submit a validation token to, with identical parameters + submit the validation token to, with identical parameters to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's @@ -532,17 +514,17 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. description: |- - The homeserver should check that the given phone number **is + The homeserver must check that the given phone number **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the ``account/password`` endpoint. - This API's parameters and response are identical to that of the HS API - |/register/msisdn/requestToken|_ except that ``M_THREEPID_NOT_FOUND`` may - be returned if no account matching the given phone number could be - found. The server may instead send the SMS to the given phone number - prompting the user to create an account. ``M_THREEPID_IN_USE`` may not - be returned. + This API's parameters and response are identical to that of the + |/register/msisdn/requestToken|_ endpoint, except that + ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the + given phone number could be found. The server may instead send the SMS + to the given phone number prompting the user to create an account. + ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the phone number itself, or proxying the request to the ``validate/msisdn/requestToken`` Identity @@ -573,7 +555,7 @@ paths: required: ['id_server'] responses: 200: - description: An SMS message was sent to the given phone number. + description: A SMS message was sent to the given phone number. schema: type: object allOf: @@ -584,11 +566,11 @@ paths: type: string description: |- An optional field containing a URL where the client must - submit a validation token to, with identical parameters + submit the validation token to, with identical parameters to the Identity Service API's ``/validate/msisdn/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's From 0ded48427652857f92e323d5d85580adf0b6c7bd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 16:10:44 +0100 Subject: [PATCH 231/497] Address review comments --- api/client-server/administrative_contact.yaml | 4 ++-- api/client-server/registration.yaml | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index bc6f98c7..99451294 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -235,7 +235,7 @@ paths: account. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint. The homeserver has the choice of validating the email address itself, or proxying the request - to the ``validate/email/requestToken`` Identity Service API as + to the ``/validate/email/requestToken`` Identity Service API as identified by ``id_server``. operationId: requestTokenTo3PIDEmail parameters: @@ -312,7 +312,7 @@ paths: account. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint. The homeserver has the choice of validating the phone number itself, or proxying the request - to the ``validate/msisdn/requestToken`` Identity Service API as + to the ``/validate/msisdn/requestToken`` Identity Service API as identified by ``id_server``. operationId: requestTokenTo3PIDMSISDN parameters: diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index c8615d29..21626815 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -213,7 +213,7 @@ paths: The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the email address itself, or proxying the - request to the ``validate/email/requestToken`` Identity Service API. The + request to the ``/validate/email/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -294,7 +294,7 @@ paths: The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the phone number itself, or proxying the - request to the ``validate/msisdn/requestToken`` Identity Service API. The + request to the ``/validate/msisdn/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -428,7 +428,7 @@ paths: The homeserver must check that the given email address **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the - ``account/password`` endpoint. + ``/account/password`` endpoint. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint, except that @@ -438,7 +438,7 @@ paths: ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the email address itself, - or proxying the request to the ``validate/email/requestToken`` Identity + or proxying the request to the ``/validate/email/requestToken`` Identity Server API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it @@ -517,7 +517,7 @@ paths: The homeserver must check that the given phone number **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the - ``account/password`` endpoint. + ``/account/password`` endpoint. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint, except that @@ -527,7 +527,7 @@ paths: ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the phone number itself, - or proxying the request to the ``validate/msisdn/requestToken`` Identity + or proxying the request to the ``/validate/msisdn/requestToken`` Identity Server API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it From fba61941af471e885fb2310ddb443660e92f0929 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 20:02:57 +0100 Subject: [PATCH 232/497] Move submit_url responses to ref --- api/client-server/administrative_contact.yaml | 41 +--------- api/client-server/registration.yaml | 80 +------------------ api/identity/definitions/sid.yaml | 14 ++++ 3 files changed, 20 insertions(+), 115 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 99451294..d26e5a96 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -261,25 +261,7 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user, which should then be - prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -336,26 +318,7 @@ paths: description: |- A SMS message was sent to the given phone number. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" - + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 21626815..a2a0d47f 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -241,25 +241,7 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -322,25 +304,7 @@ paths: that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -469,25 +433,7 @@ paths: 200: description: An email was sent to the given address. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -557,25 +503,7 @@ paths: 200: description: A SMS message was sent to the given phone number. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/msisdn/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml index c1f1ae64..c09ed395 100644 --- a/api/identity/definitions/sid.yaml +++ b/api/identity/definitions/sid.yaml @@ -21,4 +21,18 @@ properties: ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they must not be empty. example: "123abc" + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" required: ['sid'] From 525bedf8e14327556153d19933efcd488fa61017 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 20:10:44 +0100 Subject: [PATCH 233/497] Fix refs --- api/client-server/administrative_contact.yaml | 6 ++++-- api/client-server/registration.yaml | 12 ++++++++---- api/identity/definitions/sid.yaml | 14 -------------- 3 files changed, 12 insertions(+), 20 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index d26e5a96..c19872e8 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -261,7 +261,8 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -318,7 +319,8 @@ paths: description: |- A SMS message was sent to the given phone number. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index a2a0d47f..4ea8b252 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -241,7 +241,8 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -304,7 +305,8 @@ paths: that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -433,7 +435,8 @@ paths: 200: description: An email was sent to the given address. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -503,7 +506,8 @@ paths: 200: description: A SMS message was sent to the given phone number. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml index c09ed395..c1f1ae64 100644 --- a/api/identity/definitions/sid.yaml +++ b/api/identity/definitions/sid.yaml @@ -21,18 +21,4 @@ properties: ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they must not be empty. example: "123abc" - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" required: ['sid'] From 2551ff6ce0b4100a3436344c2043241998635fa0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 20:12:23 +0100 Subject: [PATCH 234/497] Actually check in code --- api/client-server/definitions/sid.yaml | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 api/client-server/definitions/sid.yaml diff --git a/api/client-server/definitions/sid.yaml b/api/client-server/definitions/sid.yaml new file mode 100644 index 00000000..50b45ca9 --- /dev/null +++ b/api/client-server/definitions/sid.yaml @@ -0,0 +1,38 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +properties: + sid: + type: string + description: |- + The session ID. Session IDs are opaque strings generated by the identity + server. They must consist entirely of the characters + ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they + must not be empty. + example: "123abc" + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" +required: ['sid'] From 046a83448862d000048b644386cfacd5df6190e3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 22:04:58 +0100 Subject: [PATCH 235/497] Slight code cleanup --- api/client-server/administrative_contact.yaml | 14 +++++--------- api/client-server/registration.yaml | 12 ++++-------- 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index c19872e8..f0a86762 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -132,8 +132,7 @@ paths: } responses: 200: - description: |- - The addition was successful. + description: The addition was successful. examples: application/json: { "submit_url": "https://example.org/path/to/submitToken" @@ -257,11 +256,10 @@ paths: responses: 200: description: |- - An email was sent to the given address. - Note that this may be an email containing the validation token or - it may be informing the user of an error. + An email was sent to the given address. Note that this may be an + email containing the validation token or it may be informing the + user of an error. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- @@ -316,10 +314,8 @@ paths: required: ['id_server'] responses: 200: - description: |- - A SMS message was sent to the given phone number. + description: A SMS message was sent to the given phone number. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 4ea8b252..c892b08d 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -237,11 +237,10 @@ paths: responses: 200: description: |- - An email has been sent to the specified address. - Note that this may be an email containing the validation token or it may be informing - the user of an error. + An email has been sent to the specified address. Note that this + may be an email containing the validation token or it may be + informing the user of an error. schema: - type: object $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. @@ -301,11 +300,10 @@ paths: responses: 200: description: |- - A SMS message has been sent to the specified phone number. Note + A SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - type: object $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. @@ -435,7 +433,6 @@ paths: 200: description: An email was sent to the given address. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- @@ -506,7 +503,6 @@ paths: 200: description: A SMS message was sent to the given phone number. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- From fe23de7d7f43f6d7ed30f0a9a320b940071e89f9 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 05:20:15 +0100 Subject: [PATCH 236/497] A SMS -> An SMS --- api/client-server/administrative_contact.yaml | 2 +- api/client-server/registration.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index f0a86762..4c1ea2e7 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -314,7 +314,7 @@ paths: required: ['id_server'] responses: 200: - description: A SMS message was sent to the given phone number. + description: An SMS message was sent to the given phone number. schema: $ref: "definitions/sid.yaml" 403: diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index c892b08d..00334434 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -300,7 +300,7 @@ paths: responses: 200: description: |- - A SMS message has been sent to the specified phone number. Note + An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: @@ -501,7 +501,7 @@ paths: required: ['id_server'] responses: 200: - description: A SMS message was sent to the given phone number. + description: An SMS message was sent to the given phone number. schema: $ref: "definitions/sid.yaml" 403: From 29340c6eb815dc2fedeec9f18468c58e385cda78 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 9 Jun 2019 22:50:23 -0600 Subject: [PATCH 237/497] Clarify that the common identifier format can be broken We already reference in the Event IDs section that the format depends on the room version, so we just need to link there. Fixes https://github.com/matrix-org/matrix-doc/issues/2103 --- specification/appendices/identifier_grammar.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index ea805955..b5b0537a 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -88,8 +88,8 @@ Common Identifier Format ~~~~~~~~~~~~~~~~~~~~~~~~ The Matrix protocol uses a common format to assign unique identifiers to a -number of entities, including users, events and rooms. Each identifier takes -the form:: +number of entities, including users, events and rooms. Each identifier typically +takes the form:: &localpart:domain @@ -106,7 +106,9 @@ The sigil characters are as follows: * ``#``: Room alias The precise grammar defining the allowable format of an identifier depends on -the type of identifier. +the type of identifier. For example, event IDs can be represented without a +``domain`` component under some conditions - see the `Event IDs <#room-ids-and-event-ids>`_ +section below for more information. User Identifiers ++++++++++++++++ From ab0c1bc054247f732e66dd2b424d8c3a12a5e492 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 08:41:35 +0100 Subject: [PATCH 238/497] Add changelog, update imperative check, rename sid.yaml --- api/client-server/administrative_contact.yaml | 14 +++++---- .../{sid.yaml => request_token_response.yaml} | 0 api/client-server/registration.yaml | 30 +++++++++---------- .../client_server/newsfragments/2101.breaking | 1 + 4 files changed, 25 insertions(+), 20 deletions(-) rename api/client-server/definitions/{sid.yaml => request_token_response.yaml} (100%) create mode 100644 changelogs/client_server/newsfragments/2101.breaking diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 4c1ea2e7..4438b643 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -135,7 +135,7 @@ paths: description: The addition was successful. examples: application/json: { - "submit_url": "https://example.org/path/to/submitToken" + "submit_url": "https://example.org/path/to/submitToken" } schema: type: object @@ -235,7 +235,9 @@ paths: the |/register/email/requestToken|_ endpoint. The homeserver has the choice of validating the email address itself, or proxying the request to the ``/validate/email/requestToken`` Identity Service API as - identified by ``id_server``. + identified by ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -260,7 +262,7 @@ paths: email containing the validation token or it may be informing the user of an error. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -294,7 +296,9 @@ paths: the |/register/msisdn/requestToken|_ endpoint. The homeserver has the choice of validating the phone number itself, or proxying the request to the ``/validate/msisdn/requestToken`` Identity Service API as - identified by ``id_server``. + identified by ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. operationId: requestTokenTo3PIDMSISDN parameters: - in: body @@ -316,7 +320,7 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/definitions/sid.yaml b/api/client-server/definitions/request_token_response.yaml similarity index 100% rename from api/client-server/definitions/sid.yaml rename to api/client-server/definitions/request_token_response.yaml diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 00334434..5ec657e0 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -241,7 +241,7 @@ paths: may be an email containing the validation token or it may be informing the user of an error. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -304,7 +304,7 @@ paths: that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -402,11 +402,11 @@ paths: ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the email address itself, - or proxying the request to the ``/validate/email/requestToken`` Identity - Server API. The request should be proxied to the domain that is sent by - the client in the ``id_server``. It is imperative that the homeserver - keep a list of trusted Identity Servers and only proxies to those it - trusts. + or proxying the request to the ``/validate/email/requestToken`` + Identity Service API. The request should be proxied to the domain that + is sent by the client in the ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` @@ -433,7 +433,7 @@ paths: 200: description: An email was sent to the given address. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -472,12 +472,12 @@ paths: to the given phone number prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - The homeserver has the choice of validating the phone number itself, - or proxying the request to the ``/validate/msisdn/requestToken`` Identity - Server API. The request should be proxied to the domain that is sent by - the client in the ``id_server``. It is imperative that the homeserver - keep a list of trusted Identity Servers and only proxies to those it - trusts. + The homeserver has the choice of validating the phone number itself, or + proxying the request to the ``/validate/msisdn/requestToken`` Identity + Service API. The request should be proxied to the domain that is sent + by the client in the ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` @@ -503,7 +503,7 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/changelogs/client_server/newsfragments/2101.breaking b/changelogs/client_server/newsfragments/2101.breaking new file mode 100644 index 00000000..84c645ab --- /dev/null +++ b/changelogs/client_server/newsfragments/2101.breaking @@ -0,0 +1 @@ +Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. From 0f82056ca2a46bd35483ee83c18c75035d85056f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 08:43:34 +0100 Subject: [PATCH 239/497] Highlight breaking change --- changelogs/client_server/newsfragments/2101.breaking | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2101.breaking b/changelogs/client_server/newsfragments/2101.breaking index 84c645ab..bcbdcd55 100644 --- a/changelogs/client_server/newsfragments/2101.breaking +++ b/changelogs/client_server/newsfragments/2101.breaking @@ -1 +1 @@ -Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. +Breaking change: Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. Clients should request a token from the user to submit 3PID validation when they received this field. Older clients will not know about this field and thus may display a deceptive message thinking that validation will be handled out of bounds. From d1fde0837af4ecfde83532f0c027bde4f4c5ea10 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 09:06:13 +0100 Subject: [PATCH 240/497] Consolidate id_server into ref. id_server/next_link are ignored --- api/client-server/administrative_contact.yaml | 24 ++----------------- .../definitions/request_email_validation.yaml | 14 ++++++++--- .../request_msisdn_validation.yaml | 14 ++++++++--- 3 files changed, 24 insertions(+), 28 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 4438b643..6ee4a152 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -244,17 +244,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_email_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_email_validation.yaml" responses: 200: description: |- @@ -305,17 +295,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_msisdn_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_msisdn_validation.yaml" responses: 200: description: An SMS message was sent to the given phone number. diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index 5f15bd41..b99fe121 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -45,7 +45,15 @@ properties: next_link: type: string description: |- - Optional. When the validation is completed, the identity - server will redirect the user to this URL. + Optional. When the validation is completed, the identity server will + redirect the user to this URL. This option is ignored when submitting + 3PID validation information through a POST request. example: "https://example.org/congratulations.html" -required: ["client_secret", "email", "send_attempt"] + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + example: "id.example.com" +required: ["client_secret", "email", "send_attempt", "id_server"] diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index 1a8c0cf8..08dd0482 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -51,7 +51,15 @@ properties: next_link: type: string description: |- - Optional. When the validation is completed, the identity - server will redirect the user to this URL. + Optional. When the validation is completed, the identity server will + redirect the user to this URL. This option is ignored when submitting + 3PID validation information through a POST request. example: "https://example.org/congratulations.html" -required: ["client_secret", "country", "phone_number", "send_attempt"] + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + example: "id.example.com" +required: ["client_secret", "country", "phone_number", "send_attempt", "id_server"] From 7116f9334e8925e2c710c529dd1d0ab8c44209de Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 09:09:26 +0100 Subject: [PATCH 241/497] More consolidation --- api/client-server/registration.yaml | 48 +++-------------------------- 1 file changed, 4 insertions(+), 44 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 5ec657e0..edc52c6a 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -223,17 +223,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_email_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_email_validation.yaml" responses: 200: description: |- @@ -286,17 +276,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_msisdn_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_msisdn_validation.yaml" responses: 200: description: |- @@ -418,17 +398,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_email_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_email_validation.yaml" responses: 200: description: An email was sent to the given address. @@ -488,17 +458,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_msisdn_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_msisdn_validation.yaml" responses: 200: description: An SMS message was sent to the given phone number. From 2068cba598b3e3630950f95d0d730a1a2e081a56 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 09:14:25 +0100 Subject: [PATCH 242/497] Clients should submit a POST request --- api/client-server/administrative_contact.yaml | 8 ++++---- .../definitions/request_token_response.yaml | 16 +++++++--------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 6ee4a152..a3a391bc 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -145,10 +145,10 @@ paths: description: |- An optional field containing a URL where the client must submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. + to the Identity Service API's ``POST + /validate/email/submitToken`` endpoint. The homeserver must + send this token to the user (if applicable), which should + then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement. diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 50b45ca9..48f818e5 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -24,15 +24,13 @@ properties: submit_url: type: string description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. + An optional field containing a URL where the client must submit the + validation token to, with identical parameters to the Identity Service + API's ``POST /validate/email/submitToken`` endpoint. The homeserver must + send this token to the user (if applicable), which should then be + prompted to provide it to the client. - If this field is not present, the client can assume that - verification will happen without the client's - involvement. + If this field is not present, the client can assume that verification + will happen without the client's involvement. example: "https://example.org/path/to/submitToken" required: ['sid'] From 0506d09cf7735ac01ffe30e1783cd0429a761c28 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 10 Jun 2019 19:38:44 +0100 Subject: [PATCH 243/497] incorporate LL review from matthew --- .../definitions/room_event_filter.yaml | 3 +- api/client-server/message_pagination.yaml | 14 ++--- api/client-server/sync.yaml | 19 +++--- specification/client_server_api.rst | 61 ++++++++++++------- specification/modules/instant_messaging.rst | 2 +- 5 files changed, 60 insertions(+), 39 deletions(-) diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml index 7045396d..880cb173 100644 --- a/api/client-server/definitions/room_event_filter.yaml +++ b/api/client-server/definitions/room_event_filter.yaml @@ -25,7 +25,8 @@ allOf: include_redundant_members: type: boolean description: |- - If ``true``, enables redundant membership events. Does not + If ``true``, sends all membership events for all events, even if they have already + been sent to the client. Does not apply unless ``lazy_load_members`` is ``true``. See `Lazy-loading room members <#lazy-loading-room-members>`_ for more information. Defaults to ``false``. diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 3e01437a..35555375 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -115,15 +115,13 @@ paths: type: array description: |- A list of state events relevant to showing the ``chunk``. For example, if - ``lazy_load_members`` is enabled in the filter then this will contain any - the membership events for the the senders of events in the ``chunk``. Servers should be careful to not exclude - membership events which are older than ones already sent to the client. - Likewise, clients should be cautious and avoid using older membership - events as the current membership event when paginating backwards. + ``lazy_load_members`` is enabled in the filter then this may contain + the membership events for the senders of events in the ``chunk``. - Unless ``include_redundant_members`` is ``true``, the server should remove - membership events which would have already been sent to clients in prior calls - to lazy-loading aware endpoints with the same filter. + Unless ``include_redundant_members`` is ``true``, the server + may remove membership events which would have already been + sent to the client in prior calls to this endpoint, assuming + the membership of those members has not changed. items: type: object title: RoomStateEvent diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 45829f68..00ed562d 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -39,12 +39,15 @@ paths: for more information. Lazy-loading members is only supported on a ``StateFilter`` for this endpoint. When lazy-loading is enabled, servers MUST include the syncing user's own membership event when they join a room, or when the - full state of rooms is requested. The user's own membership event is eligible + full state of rooms is requested, to aid discovering the user's avatar & + displayname. + + Like other members, the user's own membership event is eligible for being considered redundant by the server. When a sync is ``limited``, - the server MUST return membership events for events in the gap (between ``since`` and the start of the returned timeline), - regardless as to whether - or not they are redundant. ``include_redundant_members`` is ignored for limited - syncs. + the server MUST return membership events for events in the gap + (between ``since`` and the start of the returned timeline), regardless + as to whether or not they are redundant. This ensures that joins/leaves + and profile changes which occur during the gap are not lost. operationId: sync security: - accessToken: [] @@ -149,9 +152,9 @@ paths: type: array description: |- The users which can be used to generate a room name - if the room does not have one. Required if the room - does not have a ``m.room.name`` or ``m.room.canonical_alias`` - state event with non-empty content. + if the room does not have one. Required if the room's + ``m.room.name`` or ``m.room.canonical_alias`` state events + are unset or empty. This should be the first 5 members of the room, ordered by stream ordering, which are joined or invited. The diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 42f34849..a292eaeb 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1273,32 +1273,51 @@ Lazy-loading room members Membership events often take significant resources for clients to track. In an effort to reduce the number of resources used, clients can enable "lazy-loading" -for room members. By doing this, servers will only ever send membership events +for room members. By doing this, servers will attempt to only send membership events which are relevant to the client. -In terms of filters, this means enabling ``lazy_load_members`` on a ``RoomEventFilter`` -(or a ``StateFilter`` in the case of ``/sync`` only). When enabled, lazy-loading -aware endpoints (see below) will only include membership events for the ``sender`` -of events being included in the response. For example, if a client makes a ``/sync`` -request with lazy-loading enabled, the server will only return membership events -for the ``sender`` of events in the timeline, not all members of a room. +It is important to understand that lazy-loading is not intended to be a +perfect optimisation, and that it may not be practical for the server to +calculate precisely which membership events are relevant to the client. As a +result, it is valid for the server to send redundant membership events to the +client to ease implementation, although such redundancy should be minimised +where possible to conserve bandwidth. -Repeated calls to lazy-loading aware endpoints will result in redundant membership -events being excluded by default. Clients often track which membership events they -already have, therefore making the extra information not as useful to the client. -Clients can always request redundant membership events by setting ``include_redundant_members`` -to true in the filter. +In terms of filters, lazy-loading is enabled by enabling ``lazy_load_members`` +on a ``RoomEventFilter`` (or a ``StateFilter`` in the case of ``/sync`` only). +When enabled, lazy-loading aware endpoints (see below) will only include +membership events for the ``sender`` of events being included in the response. +For example, if a client makes a ``/sync`` request with lazy-loading enabled, +the server will only return membership events for the ``sender`` of events in +the timeline, not all members of a room. -Servers should be cautious about which events they consider redundant. Membership -events can change over time, and should be included as relevant to maintain the -historical record. Likewise, clients should be cautious about treating an older event -as the current membership event for a user. +When processing a sequence of events (e.g. by looping on ``/sync`` or +paginating ``/messages``), it is common for blocks of events in the sequence +to share a similar set of senders. Rather than responses in the sequence +sending duplicate membership events for these senders to the client, the +server MAY assume that clients will remember membership events they have +already been sent, and choose to skip sending membership events for members +whose membership has not changed. These are called 'redundant membership +events'. Clients may request that redundant membership events are always +included in responses by setting ``include_redundant_members`` to true in the +filter. -.. Note:: - Repeated calls using the same filter to *any* lazy-loading aware endpoint may - result in redundant membership events being excluded from future calls. For example, a - request to ``/sync`` followed by a request to ``/messages`` may result in a - future call to ``/sync`` excluding membership events returned by the ``/messages`` call. +The expected pattern for using lazy-loading is currently: + +* Client performs an initial /sync with lazy-loading enabled, and receives + only the membership events which relate to the senders of the events it + receives. +* Clients which support display-name tab-completion or other operations which + require rapid access to all members in a room should call /members for the + currently selected room, with an ``?at`` parameter set to the /sync + response's from token. The member list for the room is then maintained by + the state in subsequent incremental /sync responses. +* Clients which do not support tab-completion may instead pull in profiles for + arbitrary users (e.g. read receipts, typing notifications) on demand by + querying the room state or ``/profile``. + +.. TODO-spec + This implies that GET /state should also take an ``?at`` param The current endpoints which support lazy-loading room members are: diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index c514f481..679eabdc 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -287,7 +287,7 @@ choose a name: on the members of the room. Clients should consider `m.room.member`_ events for users other than the logged-in user, as defined below. - i. If the ``m.heroes`` for the room are greater or equal to + i. If the number of ``m.heroes`` for the room are greater or equal to ``m.joined_member_count + m.invited_member_count - 1``, then use the membership events for the heroes to calculate display names for the users (`disambiguating them if required`_) and concatenating them. For From cf19f525767a9db9a982a966e47f11a983f4eab3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2019 13:21:24 -0600 Subject: [PATCH 244/497] Enforce 7 day validity requirement everywhere also misc formatting fixes --- api/server-server/definitions/keys.yaml | 2 +- specification/rooms/v5.rst | 9 +++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml index c48c320a..8bc6c563 100644 --- a/api/server-server/definitions/keys.yaml +++ b/api/server-server/definitions/keys.yaml @@ -98,7 +98,7 @@ properties: be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST be considered invalid, depending on the `room version specification`_. - Servers SHOULD use the lesser of this field and 7 days into the future when + Servers MUST use the lesser of this field and 7 days into the future when determining if a key is valid. This is to avoid a situation where an attacker publishes a key which is valid for a significant amount of time without a way for the homeserver owner to revoke it. diff --git a/specification/rooms/v5.rst b/specification/rooms/v5.rst index 9b9fad7e..97ebf2fe 100644 --- a/specification/rooms/v5.rst +++ b/specification/rooms/v5.rst @@ -15,8 +15,8 @@ Room Version 5 ============== -This room version builds on `version 4 `_, enforcing signing key validity -periods for events. +This room version builds on `version 4 `_ while enforcing signing +key validity periods for events. .. contents:: Table of Contents .. sectnum:: @@ -52,3 +52,8 @@ validated. Servers missing a copy of the signing key MUST try to obtain one via or `POST /_matrix/key/v2/query <../server_server/r0.1.1.html#post-matrix-key-v2-query>`_ APIs. When using the ``/query`` endpoint, servers MUST set the ``minimum_valid_until_ts`` property to prompt the notary server to attempt to refresh the key if appropriate. + +Servers MUST use the lesser of ``valid_until_ts`` and 7 days into the future when +determining if a key is valid. This is to avoid a situation where an attacker +publishes a key which is valid for a significant amount of time without a way for +the homeserver owner to revoke it. From 1886a2346a27579cd378b4f112181d880626b460 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2019 13:38:43 -0600 Subject: [PATCH 245/497] Move explanation of notifications to notifications module --- api/client-server/sync.yaml | 4 ++-- specification/modules/push.rst | 11 +++++++++++ specification/modules/receipts.rst | 5 ++--- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 4514d417..89292673 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -172,8 +172,8 @@ paths: type: object description: |- Counts of unread notifications for this room. See the - `Receipts module <#module-receipts>`_ for more information - on how these are calculated. + `Receiving notifications section <#receiving-notifications>`_ + for more information on how these are calculated. properties: highlight_count: title: Highlighted notification count diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 1bac0c2e..33ca7fd7 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -1,4 +1,5 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2019 The Matrix.org Foundation C.I.C. .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -116,6 +117,16 @@ have received. {{notifications_cs_http_api}} +Receiving notifications +~~~~~~~~~~~~~~~~~~~~~~~ + +Servers MUST include the number of unread notifications in a client's ``/sync`` +stream, and MUST update it as it changes. Notifications are determined by the +push rules which apply to an event. + +When the user updates their read receipt (either by using the API or by sending an +event), notifications prior to and including that event MUST be marked as read. + Push Rules ~~~~~~~~~~ A push rule is a single rule that states under what *conditions* an event should diff --git a/specification/modules/receipts.rst b/specification/modules/receipts.rst index 1745706e..4630091f 100644 --- a/specification/modules/receipts.rst +++ b/specification/modules/receipts.rst @@ -26,9 +26,8 @@ to a homeserver. To prevent this from becoming a problem, receipts are implement using "up to" markers. This marker indicates that the acknowledgement applies to all events "up to and including" the event specified. For example, marking an event as "read" would indicate that the user had read all events *up to* the -referenced event. Servers MUST decremement the number of pending notifications -for a user if the events are up to or including the read receipt. This is typically -done by adjusting the ``unread_notifications`` value in a ``/sync`` response. +referenced event. See the `Receiving notifications <#receiving-notifications>`_ +section for more information on how read receipts affect notification counts. Events ------ From 49831fb74fbde025c6d1c95a57ae5d15d0919fd5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2019 13:48:55 -0600 Subject: [PATCH 246/497] Clarifications about namespaces --- specification/index.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/index.rst b/specification/index.rst index 375e19c0..547375e3 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -446,12 +446,13 @@ Namespacing Namespacing helps prevent conflicts between multiple applications and the specification itself. Where namespacing is used, ``m.`` prefixes are used by the specification to indicate that the field is controlled by the specification. Custom or non-specified -namespaces used in the wild SHOULD use the Java package naming convention to prevent +namespaces used in the wild MUST use the Java package naming convention to prevent conflicts. -As an example, event types are namespaced under ``m.`` in the specification however -any client can send a custom event type, such as ``com.example.game.score`` without -needing to put the event into the ``m.`` namespace. +As an example, event types defined in the specification are namespaced under the +special ``m.`` prefix, however any client can send a custom event type, such as +``com.example.game.score`` (assuming the client has rights to the ``com.example`` +namespace) without needing to put the event into the ``m.`` namespace. Timestamps ~~~~~~~~~~ From 19c827e581476a18875ea471263453d11a6d5cc3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2019 13:49:05 -0600 Subject: [PATCH 247/497] Remove trailing slashes section --- specification/index.rst | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/specification/index.rst b/specification/index.rst index 547375e3..5acec2ea 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -432,13 +432,7 @@ Common concepts Various things are common throughout all of the Matrix APIs. They are documented here. -Trailing slashes on API endpoints -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unless the endpoint is explicltly specified to have a trailing slash, the -slash is optional. For example, an endpoint specified as ``/_matrix/example/`` -would require a trailing slash, however an endpoint specified as ``/_matrix/example`` -has an optional slash (can be excluded when making requests). +.. TODO: Some words about trailing slashes. See https://github.com/matrix-org/matrix-doc/issues/2107 Namespacing ~~~~~~~~~~~ From 51698a5dd55232d39746269bfd164647ec56548f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2019 14:04:14 -0600 Subject: [PATCH 248/497] Clarify that people must own the namespace to use it --- specification/client_server_api.rst | 3 ++- specification/index.rst | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 80e4a2f4..b67beca1 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1330,7 +1330,8 @@ namespaced for each application and reduces the risk of clashes. Events are not limited to the types defined in this specification. New or custom event types can be created on a whim using the Java package naming convention. For example, a ``com.example.game.score`` event can be sent by clients and other - clients would receive it through Matrix. + clients would receive it through Matrix, assuming the client has access to the + ``com.example`` namespace. Note that the structure of these events may be different than those in the server-server API. diff --git a/specification/index.rst b/specification/index.rst index 7aa6a672..bf12a271 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -352,7 +352,8 @@ from the other servers participating in a room. Events are not limited to the types defined in this specification. New or custom event types can be created on a whim using the Java package naming convention. For example, a ``com.example.game.score`` event can be sent by clients and other - clients would receive it through Matrix. + clients would receive it through Matrix, assuming the client has access to the + ``com.example`` namespace. Room Aliases ++++++++++++ From 37e2d81d580083f8d7ed2f1a99e368231aab299c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2019 14:04:27 -0600 Subject: [PATCH 249/497] Hardcode the state event fields table into the spec See comment for why. --- specification/client_server_api.rst | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index b67beca1..ad58fd1a 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1340,7 +1340,28 @@ server-server API. {{common_room_event_fields}} -{{common_state_event_fields}} +.. This is normally where we'd put the common_state_event_fields variable for the +.. magic table of what makes up a state event, however the table is verbose in our +.. custom rendering of swagger. To combat this, we just hardcode this particular +.. table. + +State Event Fields +++++++++++++++++++ + +In addition to the fields of a Room Event, State Events have the following fields. + ++-----------+--------+-------------------------------------------------------------+ +| Key | Type | Description | ++===========+========+=============================================================+ +| state_key | string | **Required.** A unique key which defines the overwriting | +| | | semantics for this piece of room state. This value is often | +| | | a zero-length string. The presence of this key makes this | +| | | event a State Event. State keys starting with an ``@`` are | +| | | reserved for referencing user IDs, such as room members. | +| | | With the exception of a few events, state events set with | +| | | a given user's ID as the state key MUST only be set by that | +| | | user. | ++-----------+--------+-------------------------------------------------------------+ Size limits From ad2eefdde9b065800b5bc33e7697e14c8de82d90 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2019 14:23:04 -0600 Subject: [PATCH 250/497] Shuffle and clarify identifier grammar Specifically, make it clearer that event IDs are the weird exception in this section. --- .../appendices/identifier_grammar.rst | 22 ++++++++++++------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index b5b0537a..c2c734ab 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -88,14 +88,13 @@ Common Identifier Format ~~~~~~~~~~~~~~~~~~~~~~~~ The Matrix protocol uses a common format to assign unique identifiers to a -number of entities, including users, events and rooms. Each identifier typically -takes the form:: +number of entities, including users, events and rooms. Each identifier takes +the form:: - &localpart:domain + &string -where ``&`` represents a 'sigil' character; ``domain`` is the `server name`_ of -the homeserver which allocated the identifier, and ``localpart`` is an -identifier allocated by that homeserver. +where ``&`` represents a 'sigil' character; ``string`` is the string which makes +up the identifier. The sigil characters are as follows: @@ -105,9 +104,16 @@ The sigil characters are as follows: * ``+``: Group ID * ``#``: Room alias +User IDs, group IDs, room IDs, room aliases, and sometimes event IDs take the form:: + + &localpart:domain + +where ``domain`` is the `server name`_ of the homeserver which allocated the +identifier, and ``localpart`` is an identifier allocated by that homeserver. + The precise grammar defining the allowable format of an identifier depends on -the type of identifier. For example, event IDs can be represented without a -``domain`` component under some conditions - see the `Event IDs <#room-ids-and-event-ids>`_ +the type of identifier. For example, event IDs can sometimes be represented with +a ``domain`` component under some conditions - see the `Event IDs <#room-ids-and-event-ids>`_ section below for more information. User Identifiers From 572d29348c293012a03326c9ee0bfac74b76bf98 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 11 Jun 2019 00:18:37 +0100 Subject: [PATCH 251/497] Update changelogs/client_server/newsfragments/2101.breaking Co-Authored-By: Travis Ralston --- changelogs/client_server/newsfragments/2101.breaking | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2101.breaking b/changelogs/client_server/newsfragments/2101.breaking index bcbdcd55..68971171 100644 --- a/changelogs/client_server/newsfragments/2101.breaking +++ b/changelogs/client_server/newsfragments/2101.breaking @@ -1 +1 @@ -Breaking change: Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. Clients should request a token from the user to submit 3PID validation when they received this field. Older clients will not know about this field and thus may display a deceptive message thinking that validation will be handled out of bounds. +Add a new ``submit_url`` field to the responses of ``/requestToken`` which older clients will not be able to handle correctly. From 1a22508e150071a275c08e3a13ace15211924f74 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 19:18:58 -0400 Subject: [PATCH 252/497] identity server -> the server --- api/client-server/definitions/request_token_response.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 48f818e5..8776d143 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -16,10 +16,9 @@ properties: sid: type: string description: |- - The session ID. Session IDs are opaque strings generated by the identity - server. They must consist entirely of the characters - ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they - must not be empty. + The session ID. Session IDs are opaque strings generated by a server. + They must consist entirely of the characters ``[0-9a-zA-Z.=_-]``. Their + length must not exceed 255 characters and they must not be empty. example: "123abc" submit_url: type: string From 5f24f63338f94a08c51754877a708fb596154e09 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 19:21:14 -0400 Subject: [PATCH 253/497] Better wording --- api/client-server/definitions/request_token_response.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 8776d143..98fefe07 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -16,9 +16,9 @@ properties: sid: type: string description: |- - The session ID. Session IDs are opaque strings generated by a server. - They must consist entirely of the characters ``[0-9a-zA-Z.=_-]``. Their - length must not exceed 255 characters and they must not be empty. + The session ID. Session IDs are opaque strings that must consist entirely + of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 + characters and they must not be empty. example: "123abc" submit_url: type: string From 04930c6ddfb0a5fadbde2a8255a2a8d59c430c98 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 08:29:50 -0600 Subject: [PATCH 254/497] Don't enforce MXC URIs, but also don't confuse people --- .../core-event-schema/msgtype_infos/image_info.yaml | 4 ++-- event-schemas/schema/m.room.message$m.audio | 4 +++- event-schemas/schema/m.room.message$m.file | 4 +++- event-schemas/schema/m.room.message$m.image | 4 +++- event-schemas/schema/m.room.message$m.video | 8 +++++--- 5 files changed, 16 insertions(+), 8 deletions(-) diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index b6a45007..ff40efcb 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -19,8 +19,8 @@ properties: type: integer thumbnail_url: description: |- - The `MXC URI`_ to a thumbnail of the image. Only present if the - thumbnail is unencrypted. + The URL (typically `MXC URI`_) to a thumbnail of the image. + Only present if the thumbnail is unencrypted. type: string thumbnail_file: description: |- diff --git a/event-schemas/schema/m.room.message$m.audio b/event-schemas/schema/m.room.message$m.audio index 40075541..88b459ec 100644 --- a/event-schemas/schema/m.room.message$m.audio +++ b/event-schemas/schema/m.room.message$m.audio @@ -27,7 +27,9 @@ properties: - m.audio type: string url: - description: Required if the file is not encrypted. The `MXC URI`_ to the audio clip. + description: |- + Required if the file is not encrypted. The URL (typically `MXC URI`_) + to the audio clip. type: string file: description: |- diff --git a/event-schemas/schema/m.room.message$m.file b/event-schemas/schema/m.room.message$m.file index 225ca61d..9f4fdf07 100644 --- a/event-schemas/schema/m.room.message$m.file +++ b/event-schemas/schema/m.room.message$m.file @@ -42,7 +42,9 @@ properties: - m.file type: string url: - description: Required if the file is unencrypted. The `MXC URI`_ to the file. + description: |- + Required if the file is unencrypted. The URL (typically `MXC URI`_) + to the file. type: string file: description: |- diff --git a/event-schemas/schema/m.room.message$m.image b/event-schemas/schema/m.room.message$m.image index 8bf9c5fa..a466562a 100644 --- a/event-schemas/schema/m.room.message$m.image +++ b/event-schemas/schema/m.room.message$m.image @@ -17,7 +17,9 @@ properties: - m.image type: string url: - description: Required if the file is unencrypted. The `MXC URI`_ to the image. + description: |- + Required if the file is unencrypted. The URL (typically `MXC URI`_) + to the image. type: string file: description: |- diff --git a/event-schemas/schema/m.room.message$m.video b/event-schemas/schema/m.room.message$m.video index 01286ce2..b23c2392 100644 --- a/event-schemas/schema/m.room.message$m.video +++ b/event-schemas/schema/m.room.message$m.video @@ -28,8 +28,8 @@ properties: type: integer thumbnail_url: description: |- - The `MXC URI`_ to an image thumbnail of the video clip. Only present if the - thumbnail is unencrypted. + The URL (typically `MXC URI`_) to an image thumbnail of + the video clip. Only present if the thumbnail is unencrypted. type: string thumbnail_file: description: |- @@ -48,7 +48,9 @@ properties: - m.video type: string url: - description: Required if the file is unencrypted. The `MXC URI`_ to the video clip. + description: |- + Required if the file is unencrypted. The URL (typically `MXC URI`_) + to the video clip. type: string file: description: |- From ca8b539b2fe51e01c6042519aa04aa78b7e55d72 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 08:47:25 -0600 Subject: [PATCH 255/497] humans prefer to be treated as people --- api/client-server/administrative_contact.yaml | 2 +- api/client-server/definitions/request_token_response.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index a3a391bc..af7cdcd6 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -147,7 +147,7 @@ paths: submit the validation token to, with identical parameters to the Identity Service API's ``POST /validate/email/submitToken`` endpoint. The homeserver must - send this token to the user (if applicable), which should + send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 98fefe07..bca57227 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -26,7 +26,7 @@ properties: An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's ``POST /validate/email/submitToken`` endpoint. The homeserver must - send this token to the user (if applicable), which should then be + send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification From b32f0e768f3a478e01913c997f97b5522b2baad5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 08:47:40 -0600 Subject: [PATCH 256/497] clarify that UIA can now be done by the HS --- specification/client_server_api.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 2e979cf7..fd63339e 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -762,17 +762,17 @@ the auth code. Homeservers can choose any path for the ``redirect URI``. Once the OAuth flow has completed, the client retries the request with the session only, as above. -Email-based (identity server) -<<<<<<<<<<<<<<<<<<<<<<<<<<<<< +Email-based (identity / homeserver) +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< :Type: ``m.login.email.identity`` :Description: Authentication is supported by authorising an email address with an identity - server. + server, or homeserver if supported. Prior to submitting this, the client should authenticate with an identity -server. After authenticating, the session information should be submitted to -the homeserver. +server (or homeserver). After authenticating, the session information should +be submitted to the homeserver. To use this authentication type, clients should submit an auth dict as follows: @@ -790,17 +790,17 @@ To use this authentication type, clients should submit an auth dict as follows: "session": "" } -Phone number/MSISDN-based (identity server) -<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< +Phone number/MSISDN-based (identity / homeserver) +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< :Type: ``m.login.msisdn`` :Description: Authentication is supported by authorising a phone number with an identity - server. + server, or homeserver if supported. Prior to submitting this, the client should authenticate with an identity -server. After authenticating, the session information should be submitted to -the homeserver. +server (or homeserver). After authenticating, the session information should +be submitted to the homeserver. To use this authentication type, clients should submit an auth dict as follows: From f7aa2adfb4bd01ffb10cc76d45ef18c44469ffe5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 09:16:44 -0600 Subject: [PATCH 257/497] Fix indentation --- api/client-server/keys.yaml | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 30056259..0cf074b0 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -59,22 +59,22 @@ paths: by the key algorithm. May be absent if no new one-time keys are required. - additionalProperties: - type: - - string - - type: object - title: KeyObject - properties: - key: + additionalProperties: + type: + - string + - type: object + title: KeyObject + properties: + key: + type: string + description: The key, encoded using unpadded base64. + signatures: + type: object + description: |- + Signature for the device. Mapped from user ID to signature object. + additionalProperties: type: string - description: The key, encoded using unpadded base64. - signatures: - type: object - description: |- - Signature for the device. Mapped from user ID to signature object. - additionalProperties: - type: string - required: ['key', 'signatures'] + required: ['key', 'signatures'] example: { "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", "signed_curve25519:AAAAHg": { From 85f34f942f4c1980658d147d5002f44fb76885fd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 09:18:29 -0600 Subject: [PATCH 258/497] Fix invalid doc error Another annoying case of Swagger fighting us --- api/client-server/keys.yaml | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 0cf074b0..0ea52e4a 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -62,19 +62,23 @@ paths: additionalProperties: type: - string - - type: object - title: KeyObject - properties: - key: - type: string - description: The key, encoded using unpadded base64. - signatures: - type: object - description: |- - Signature for the device. Mapped from user ID to signature object. - additionalProperties: - type: string - required: ['key', 'signatures'] + - object + # XXX: We can't define an actual object here, so we have to hope + # that people will look at the swagger source or can figure it out + # from the other endpoints/example. + # - type: object + # title: KeyObject + # properties: + # key: + # type: string + # description: The key, encoded using unpadded base64. + # signatures: + # type: object + # description: |- + # Signature for the device. Mapped from user ID to signature object. + # additionalProperties: + # type: string + # required: ['key', 'signatures'] example: { "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", "signed_curve25519:AAAAHg": { From 56745c76aa24c3d358574540b0f011aff6f0b15f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 09:22:02 -0600 Subject: [PATCH 259/497] Clarify that submit_url being not present only matters for r0.5 --- api/client-server/administrative_contact.yaml | 4 +++- api/client-server/definitions/request_token_response.yaml | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index af7cdcd6..c196c109 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -151,7 +151,9 @@ paths: then be prompted to provide it to the client. If this field is not present, the client can assume that - verification will happen without the client's involvement. + verification will happen without the client's involvement + provided the homeserver advertises this specification version + in the ``/versions`` response (ie: r0.5.0). example: "https://example.org/path/to/submitToken" 403: description: The credentials could not be verified with the identity server. diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index bca57227..e47db8a0 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -30,6 +30,8 @@ properties: prompted to provide it to the client. If this field is not present, the client can assume that verification - will happen without the client's involvement. + will happen without the client's involvement provided the homeserver + advertises this specification version in the ``/versions`` response + (ie: r0.5.0). example: "https://example.org/path/to/submitToken" required: ['sid'] From 8b7887dfc21615386c0b80e14550d0faf2e5505b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 09:47:02 -0600 Subject: [PATCH 260/497] Link to key algorithms section --- api/client-server/keys.yaml | 5 ++++- api/server-server/user_keys.yaml | 3 +++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 0ea52e4a..cce0edca 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -56,7 +56,7 @@ paths: One-time public keys for "pre-key" messages. The names of the properties should be in the format ``:``. The format of the key is determined - by the key algorithm. + by the `key algorithm <#key-algorithms>`_. May be absent if no new one-time keys are required. additionalProperties: @@ -299,6 +299,9 @@ paths: description: |- One-time keys for the queried devices. A map from user ID, to a map from devices to a map from ``:`` to the key object. + + See the `key algorithms <#key-algorithms>`_ section for information + on the Key Object format. additionalProperties: type: object additionalProperties: diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index 613948c3..ea59de2d 100644 --- a/api/server-server/user_keys.yaml +++ b/api/server-server/user_keys.yaml @@ -72,6 +72,9 @@ paths: description: |- One-time keys for the queried devices. A map from user ID, to a map from devices to a map from ``:`` to the key object. + + See the Client-Server Key Algorithms section for more information on + the Key Object format. additionalProperties: type: object additionalProperties: From c9345ba6a32618ded7fbfd992469164f4f239496 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 09:53:36 -0600 Subject: [PATCH 261/497] Never forget the past --- specification/client_server_api.rst | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index ad58fd1a..948ddc22 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1350,18 +1350,21 @@ State Event Fields In addition to the fields of a Room Event, State Events have the following fields. -+-----------+--------+-------------------------------------------------------------+ -| Key | Type | Description | -+===========+========+=============================================================+ -| state_key | string | **Required.** A unique key which defines the overwriting | -| | | semantics for this piece of room state. This value is often | -| | | a zero-length string. The presence of this key makes this | -| | | event a State Event. State keys starting with an ``@`` are | -| | | reserved for referencing user IDs, such as room members. | -| | | With the exception of a few events, state events set with | -| | | a given user's ID as the state key MUST only be set by that | -| | | user. | -+-----------+--------+-------------------------------------------------------------+ ++--------------+--------------+-------------------------------------------------------------+ +| Key | Type | Description | ++==============+==============+=============================================================+ +| state_key | string | **Required.** A unique key which defines the overwriting | +| | | semantics for this piece of room state. This value is often | +| | | a zero-length string. The presence of this key makes this | +| | | event a State Event. State keys starting with an ``@`` are | +| | | reserved for referencing user IDs, such as room members. | +| | | With the exception of a few events, state events set with | +| | | a given user's ID as the state key MUST only be set by that | +| | | user. | ++--------------+--------------+-------------------------------------------------------------+ +| prev_content | EventContent | Optional. The previous ``content`` for this event. If there | +| | | is no previous content, this key will be missing. | ++--------------+--------------+-------------------------------------------------------------+ Size limits From 4f915f27604c8ce9d3e347d991060a7561dbc4f9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 10:15:51 -0600 Subject: [PATCH 262/497] Appservice r0.1.1 --- changelogs/application_service.rst | 10 ++++++++++ .../newsfragments/1650.clarification | 1 - .../newsfragments/2037.clarification | 1 - specification/application_service_api.rst | 1 + 4 files changed, 11 insertions(+), 2 deletions(-) delete mode 100644 changelogs/application_service/newsfragments/1650.clarification delete mode 100644 changelogs/application_service/newsfragments/2037.clarification diff --git a/changelogs/application_service.rst b/changelogs/application_service.rst index 9d098837..bbc461b2 100644 --- a/changelogs/application_service.rst +++ b/changelogs/application_service.rst @@ -1,3 +1,13 @@ +r0.1.1 +====== + +Spec Clarifications +------------------- + +- Change examples to use example.org instead of a real domain. (`#1650 `_) +- Add missing definition for how appservices verify requests came from a homeserver. (`#2037 `_) + + r0.1.0 ====== diff --git a/changelogs/application_service/newsfragments/1650.clarification b/changelogs/application_service/newsfragments/1650.clarification deleted file mode 100644 index 617b7ab6..00000000 --- a/changelogs/application_service/newsfragments/1650.clarification +++ /dev/null @@ -1 +0,0 @@ -Change examples to use example.org instead of a real domain. diff --git a/changelogs/application_service/newsfragments/2037.clarification b/changelogs/application_service/newsfragments/2037.clarification deleted file mode 100644 index f425b1c1..00000000 --- a/changelogs/application_service/newsfragments/2037.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing definition for how appservices verify requests came from a homeserver. diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 3220df2d..ee7e9de7 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -52,6 +52,7 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: - `HEAD `_: Includes all changes since the latest versioned release. +- `r0.1.1 `_ - `r0.1.0 `_ From 34ad81e81b60775db732edacbd5af59d95579d24 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 10:30:56 -0600 Subject: [PATCH 263/497] Identity r0.2.0 --- changelogs/identity_service.rst | 19 +++++++++++++++++++ .../newsfragments/1853.clarification | 1 - .../newsfragments/1967.clarification | 1 - .../identity_service/newsfragments/2046.new | 1 - .../newsfragments/2049.clarification | 1 - .../newsfragments/2057.clarification | 1 - .../newsfragments/2086.clarification | 1 - specification/identity_service_api.rst | 1 + specification/modules/third_party_invites.rst | 2 +- 9 files changed, 21 insertions(+), 7 deletions(-) delete mode 100644 changelogs/identity_service/newsfragments/1853.clarification delete mode 100644 changelogs/identity_service/newsfragments/1967.clarification delete mode 100644 changelogs/identity_service/newsfragments/2046.new delete mode 100644 changelogs/identity_service/newsfragments/2049.clarification delete mode 100644 changelogs/identity_service/newsfragments/2057.clarification delete mode 100644 changelogs/identity_service/newsfragments/2086.clarification diff --git a/changelogs/identity_service.rst b/changelogs/identity_service.rst index 0405d515..d60812b8 100644 --- a/changelogs/identity_service.rst +++ b/changelogs/identity_service.rst @@ -1,3 +1,22 @@ +r0.2.0 +====== + +New Endpoints +------------- + +- Add ``/3pid/unbind`` for removing 3PIDs. (`#2046 `_) + + +Spec Clarifications +------------------- + +- Fix various spelling mistakes throughout the specification. (`#1853 `_) +- Fix route for ``/3pid/bind``. (`#1967 `_) +- Add missing aesthetic parameters to ``/store-invite``. (`#2049 `_) +- Clarify what the client should receive upon sending an identical email validation request multiple times. (`#2057 `_) +- Clarify that the default transport is JSON over HTTP. (`#2086 `_) + + r0.1.0 ====== diff --git a/changelogs/identity_service/newsfragments/1853.clarification b/changelogs/identity_service/newsfragments/1853.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/identity_service/newsfragments/1853.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/identity_service/newsfragments/1967.clarification b/changelogs/identity_service/newsfragments/1967.clarification deleted file mode 100644 index b080caeb..00000000 --- a/changelogs/identity_service/newsfragments/1967.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix route for ``/3pid/bind``. diff --git a/changelogs/identity_service/newsfragments/2046.new b/changelogs/identity_service/newsfragments/2046.new deleted file mode 100644 index 7146799b..00000000 --- a/changelogs/identity_service/newsfragments/2046.new +++ /dev/null @@ -1 +0,0 @@ -Add ``/3pid/unbind`` for removing 3PIDs. diff --git a/changelogs/identity_service/newsfragments/2049.clarification b/changelogs/identity_service/newsfragments/2049.clarification deleted file mode 100644 index 403ac8d0..00000000 --- a/changelogs/identity_service/newsfragments/2049.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing aesthetic parameters to ``/store-invite``. diff --git a/changelogs/identity_service/newsfragments/2057.clarification b/changelogs/identity_service/newsfragments/2057.clarification deleted file mode 100644 index de72c201..00000000 --- a/changelogs/identity_service/newsfragments/2057.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify what the client should receive upon sending an identical email validation request multiple times. diff --git a/changelogs/identity_service/newsfragments/2086.clarification b/changelogs/identity_service/newsfragments/2086.clarification deleted file mode 100644 index 7016308b..00000000 --- a/changelogs/identity_service/newsfragments/2086.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the default transport is JSON over HTTP. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 88c7a8ab..952a239d 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -51,6 +51,7 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: - `HEAD `_: Includes all changes since the latest versioned release. +- `r0.2.0 `_ - `r0.1.0 `_ General principles diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index b8ab9657..282b06f4 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -255,4 +255,4 @@ these is left to the implementer's discretion. -.. _`identity server /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid +.. _`identity server /isvalid`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#get-matrix-identity-api-v1-pubkey-isvalid From 8e6ccf0a0e79eca83e4e968f7b7c9b837df3d4a7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 10:38:12 -0600 Subject: [PATCH 264/497] Federation r0.1.2 --- changelogs/server_server.rst | 17 +++++++++++++++++ .../newsfragments/1650.clarification | 1 - .../newsfragments/1906.clarification | 1 - .../newsfragments/1991.clarification | 1 - .../newsfragments/2067.clarification | 1 - .../newsfragments/2080.clarification | 1 - .../newsfragments/2081.clarification | 1 - .../newsfragments/2083.clarification | 1 - .../newsfragments/2095.clarification | 1 - .../newsfragments/2097.clarification | 1 - specification/identity_service_api.rst | 2 +- specification/modules/send_to_device.rst | 2 +- specification/rooms/v1.rst | 4 ++-- specification/rooms/v2.rst | 2 +- specification/rooms/v3.rst | 4 ++-- specification/rooms/v4.rst | 4 ++-- specification/rooms/v5.rst | 4 ++-- specification/server_server_api.rst | 1 + 18 files changed, 29 insertions(+), 20 deletions(-) delete mode 100644 changelogs/server_server/newsfragments/1650.clarification delete mode 100644 changelogs/server_server/newsfragments/1906.clarification delete mode 100644 changelogs/server_server/newsfragments/1991.clarification delete mode 100644 changelogs/server_server/newsfragments/2067.clarification delete mode 100644 changelogs/server_server/newsfragments/2080.clarification delete mode 100644 changelogs/server_server/newsfragments/2081.clarification delete mode 100644 changelogs/server_server/newsfragments/2083.clarification delete mode 100644 changelogs/server_server/newsfragments/2095.clarification delete mode 100644 changelogs/server_server/newsfragments/2097.clarification diff --git a/changelogs/server_server.rst b/changelogs/server_server.rst index a21da177..11f99a5f 100644 --- a/changelogs/server_server.rst +++ b/changelogs/server_server.rst @@ -1,3 +1,20 @@ +r0.1.2 +====== + +Spec Clarifications +------------------- + +- Change examples to use example.org instead of a real domain. (`#1650 `_) +- Fix the ``access_token`` parameter in the open_id endpoint. (`#1906 `_) +- Fix various spelling mistakes throughout the specification. (`#1991 `_) +- Clarify exactly what invite_room_state consists of. (`#2067 `_) +- Clarify how ``valid_until_ts`` behaves with respect to room version. (`#2080 `_) +- Clarify which servers are supposed to sign events. (`#2081 `_) +- Clarify the key object definition for the key management API. (`#2083 `_) +- Clarify how many PDUs are contained in transaction objects for various endpoints. (`#2095 `_) +- Clarify that the trailing slash is optional on ``/keys/*`` endpoints when no key ID is requested. (`#2097 `_) + + r0.1.1 ====== diff --git a/changelogs/server_server/newsfragments/1650.clarification b/changelogs/server_server/newsfragments/1650.clarification deleted file mode 100644 index 617b7ab6..00000000 --- a/changelogs/server_server/newsfragments/1650.clarification +++ /dev/null @@ -1 +0,0 @@ -Change examples to use example.org instead of a real domain. diff --git a/changelogs/server_server/newsfragments/1906.clarification b/changelogs/server_server/newsfragments/1906.clarification deleted file mode 100644 index 531fdb94..00000000 --- a/changelogs/server_server/newsfragments/1906.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the ``access_token`` parameter in the open_id endpoint. diff --git a/changelogs/server_server/newsfragments/1991.clarification b/changelogs/server_server/newsfragments/1991.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/server_server/newsfragments/1991.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/server_server/newsfragments/2067.clarification b/changelogs/server_server/newsfragments/2067.clarification deleted file mode 100644 index cc706274..00000000 --- a/changelogs/server_server/newsfragments/2067.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify exactly what invite_room_state consists of. diff --git a/changelogs/server_server/newsfragments/2080.clarification b/changelogs/server_server/newsfragments/2080.clarification deleted file mode 100644 index c568fa13..00000000 --- a/changelogs/server_server/newsfragments/2080.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how ``valid_until_ts`` behaves with respect to room version. diff --git a/changelogs/server_server/newsfragments/2081.clarification b/changelogs/server_server/newsfragments/2081.clarification deleted file mode 100644 index fd291273..00000000 --- a/changelogs/server_server/newsfragments/2081.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify which servers are supposed to sign events. diff --git a/changelogs/server_server/newsfragments/2083.clarification b/changelogs/server_server/newsfragments/2083.clarification deleted file mode 100644 index 8083d85d..00000000 --- a/changelogs/server_server/newsfragments/2083.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the key object definition for the key management API. diff --git a/changelogs/server_server/newsfragments/2095.clarification b/changelogs/server_server/newsfragments/2095.clarification deleted file mode 100644 index 66257e17..00000000 --- a/changelogs/server_server/newsfragments/2095.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how many PDUs are contained in transaction objects for various endpoints. diff --git a/changelogs/server_server/newsfragments/2097.clarification b/changelogs/server_server/newsfragments/2097.clarification deleted file mode 100644 index 10dcecb6..00000000 --- a/changelogs/server_server/newsfragments/2097.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the trailing slash is optional on ``/keys/*`` endpoints when no key ID is requested. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 88c7a8ab..b0b186a4 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -279,4 +279,4 @@ this isn't possible. .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types .. _`Signing JSON`: ../appendices.html#signing-json -.. _`/3pid/onbind`: ../server_server/r0.1.1.html#put-matrix-federation-v1-3pid-onbind +.. _`/3pid/onbind`: ../server_server/%SERVER_RELEASE_LABEL%.html#put-matrix-federation-v1-3pid-onbind diff --git a/specification/modules/send_to_device.rst b/specification/modules/send_to_device.rst index cca0338a..7ab622bc 100644 --- a/specification/modules/send_to_device.rst +++ b/specification/modules/send_to_device.rst @@ -63,7 +63,7 @@ If the client sends messages to users on remote domains, those messages should be sent on to the remote servers via `federation`_. -.. _`federation`: ../server_server/latest.html#send-to-device-messaging +.. _`federation`: ../server_server/%SERVER_RELEASE_LABEL%.html#send-to-device-messaging .. TODO-spec: diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index e8cbf663..b5ef217a 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -293,5 +293,5 @@ Events in version 1 rooms have the following structure: {{definition_ss_pdu}} -.. _`auth events selection`: ../server_server/r0.1.1.html#auth-events-selection -.. _`Signing Events`: ../server_server/r0.1.1.html#signing-events +.. _`auth events selection`: ../server_server/%SERVER_RELEASE_LABEL%.html#auth-events-selection +.. _`Signing Events`: ../server_server/%SERVER_RELEASE_LABEL%.html#signing-events diff --git a/specification/rooms/v2.rst b/specification/rooms/v2.rst index 247f6909..4e8365bf 100644 --- a/specification/rooms/v2.rst +++ b/specification/rooms/v2.rst @@ -161,7 +161,7 @@ The *resolution* of a set of states is obtained as follows: resolved state. -.. _`authorization rules`: ../server_server/r0.1.1.html#authorization-rules +.. _`authorization rules`: ../server_server/%SERVER_RELEASE_LABEL%.html#authorization-rules Rejected events +++++++++++++++ diff --git a/specification/rooms/v3.rst b/specification/rooms/v3.rst index 733c6984..8ef52acc 100644 --- a/specification/rooms/v3.rst +++ b/specification/rooms/v3.rst @@ -120,5 +120,5 @@ The remaining rules are the same as `room version 1 `_ -or `POST /_matrix/key/v2/query <../server_server/r0.1.1.html#post-matrix-key-v2-query>`_ +`GET /_matrix/key/v2/server <../server_server/%SERVER_RELEASE_LABEL%.html#get-matrix-key-v2-server-keyid>`_ +or `POST /_matrix/key/v2/query <../server_server/%SERVER_RELEASE_LABEL%.html#post-matrix-key-v2-query>`_ APIs. When using the ``/query`` endpoint, servers MUST set the ``minimum_valid_until_ts`` property to prompt the notary server to attempt to refresh the key if appropriate. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index d608965b..03c624ab 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -80,6 +80,7 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: - `HEAD `_: Includes all changes since the latest versioned release. +- `r0.1.2 `_ - `r0.1.1 `_ - `r0.1.0 `_ From 1ca60bf5d7658316aa0e917770f06ee4771af364 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 10:40:48 -0600 Subject: [PATCH 265/497] Client-Server r0.5.0 --- changelogs/client_server.rst | 82 +++++++++++++++++++ .../newsfragments/1650.clarification | 1 - .../newsfragments/1656.clarification | 1 - .../client_server/newsfragments/1701.feature | 1 - .../newsfragments/1744.clarification | 1 - .../client_server/newsfragments/1786.feature | 1 - .../client_server/newsfragments/1789.feature | 1 - .../client_server/newsfragments/1790.feature | 1 - .../client_server/newsfragments/1791.feature | 1 - .../newsfragments/1817.deprecation | 1 - .../client_server/newsfragments/1829.feature | 1 - .../newsfragments/1838.clarification | 1 - .../newsfragments/1853.clarification | 1 - .../newsfragments/1860.clarification | 1 - .../client_server/newsfragments/1873.new | 1 - .../client_server/newsfragments/1874.feature | 1 - .../client_server/newsfragments/1875.feature | 1 - .../client_server/newsfragments/1879.feature | 1 - .../newsfragments/1889.clarification | 1 - .../newsfragments/1891.clarification | 1 - .../client_server/newsfragments/1908.feature | 1 - .../newsfragments/1933.clarification | 1 - .../newsfragments/1969.clarification | 1 - .../newsfragments/1975.clarification | 1 - .../newsfragments/1988.clarification | 1 - .../newsfragments/1989.clarification | 1 - .../newsfragments/1991.clarification | 1 - .../newsfragments/1992.clarification | 1 - .../newsfragments/1999.clarification | 1 - .../newsfragments/2016.clarification | 1 - .../client_server/newsfragments/2020.feature | 1 - .../newsfragments/2025.clarification | 1 - .../client_server/newsfragments/2026.feature | 1 - .../newsfragments/2027.clarification | 1 - .../newsfragments/2028.clarification | 1 - .../newsfragments/2029.clarification | 1 - .../client_server/newsfragments/2030.feature | 1 - .../newsfragments/2031.clarification | 1 - .../newsfragments/2032.clarification | 1 - .../client_server/newsfragments/2035.feature | 1 - .../newsfragments/2036.clarification | 1 - .../newsfragments/2041.clarification | 1 - .../newsfragments/2042.clarification | 1 - .../newsfragments/2043.clarification | 1 - .../client_server/newsfragments/2046.feature | 1 - .../newsfragments/2051.clarification | 1 - .../newsfragments/2052.clarification | 1 - .../newsfragments/2053.clarification | 1 - .../newsfragments/2054.clarification | 1 - .../newsfragments/2055.clarification | 1 - .../newsfragments/2056.clarification | 1 - .../client_server/newsfragments/2059.feature | 1 - .../newsfragments/2067.clarification | 1 - .../newsfragments/2068.clarification | 1 - .../newsfragments/2069.clarification | 1 - .../client_server/newsfragments/2072.feature | 1 - .../newsfragments/2083.clarification | 1 - .../newsfragments/2087.clarification | 1 - .../newsfragments/2088.clarification | 1 - .../newsfragments/2089.clarification | 1 - .../newsfragments/2090.clarification | 1 - .../newsfragments/2091.clarification | 1 - .../newsfragments/2097.clarification | 1 - .../newsfragments/2098.clarification | 1 - .../client_server/newsfragments/2101.breaking | 1 - specification/client_server_api.rst | 1 + 66 files changed, 83 insertions(+), 64 deletions(-) delete mode 100644 changelogs/client_server/newsfragments/1650.clarification delete mode 100644 changelogs/client_server/newsfragments/1656.clarification delete mode 100644 changelogs/client_server/newsfragments/1701.feature delete mode 100644 changelogs/client_server/newsfragments/1744.clarification delete mode 100644 changelogs/client_server/newsfragments/1786.feature delete mode 100644 changelogs/client_server/newsfragments/1789.feature delete mode 100644 changelogs/client_server/newsfragments/1790.feature delete mode 100644 changelogs/client_server/newsfragments/1791.feature delete mode 100644 changelogs/client_server/newsfragments/1817.deprecation delete mode 100644 changelogs/client_server/newsfragments/1829.feature delete mode 100644 changelogs/client_server/newsfragments/1838.clarification delete mode 100644 changelogs/client_server/newsfragments/1853.clarification delete mode 100644 changelogs/client_server/newsfragments/1860.clarification delete mode 100644 changelogs/client_server/newsfragments/1873.new delete mode 100644 changelogs/client_server/newsfragments/1874.feature delete mode 100644 changelogs/client_server/newsfragments/1875.feature delete mode 100644 changelogs/client_server/newsfragments/1879.feature delete mode 100644 changelogs/client_server/newsfragments/1889.clarification delete mode 100644 changelogs/client_server/newsfragments/1891.clarification delete mode 100644 changelogs/client_server/newsfragments/1908.feature delete mode 100644 changelogs/client_server/newsfragments/1933.clarification delete mode 100644 changelogs/client_server/newsfragments/1969.clarification delete mode 100644 changelogs/client_server/newsfragments/1975.clarification delete mode 100644 changelogs/client_server/newsfragments/1988.clarification delete mode 100644 changelogs/client_server/newsfragments/1989.clarification delete mode 100644 changelogs/client_server/newsfragments/1991.clarification delete mode 100644 changelogs/client_server/newsfragments/1992.clarification delete mode 100644 changelogs/client_server/newsfragments/1999.clarification delete mode 100644 changelogs/client_server/newsfragments/2016.clarification delete mode 100644 changelogs/client_server/newsfragments/2020.feature delete mode 100644 changelogs/client_server/newsfragments/2025.clarification delete mode 100644 changelogs/client_server/newsfragments/2026.feature delete mode 100644 changelogs/client_server/newsfragments/2027.clarification delete mode 100644 changelogs/client_server/newsfragments/2028.clarification delete mode 100644 changelogs/client_server/newsfragments/2029.clarification delete mode 100644 changelogs/client_server/newsfragments/2030.feature delete mode 100644 changelogs/client_server/newsfragments/2031.clarification delete mode 100644 changelogs/client_server/newsfragments/2032.clarification delete mode 100644 changelogs/client_server/newsfragments/2035.feature delete mode 100644 changelogs/client_server/newsfragments/2036.clarification delete mode 100644 changelogs/client_server/newsfragments/2041.clarification delete mode 100644 changelogs/client_server/newsfragments/2042.clarification delete mode 100644 changelogs/client_server/newsfragments/2043.clarification delete mode 100644 changelogs/client_server/newsfragments/2046.feature delete mode 100644 changelogs/client_server/newsfragments/2051.clarification delete mode 100644 changelogs/client_server/newsfragments/2052.clarification delete mode 100644 changelogs/client_server/newsfragments/2053.clarification delete mode 100644 changelogs/client_server/newsfragments/2054.clarification delete mode 100644 changelogs/client_server/newsfragments/2055.clarification delete mode 100644 changelogs/client_server/newsfragments/2056.clarification delete mode 100644 changelogs/client_server/newsfragments/2059.feature delete mode 100644 changelogs/client_server/newsfragments/2067.clarification delete mode 100644 changelogs/client_server/newsfragments/2068.clarification delete mode 100644 changelogs/client_server/newsfragments/2069.clarification delete mode 100644 changelogs/client_server/newsfragments/2072.feature delete mode 100644 changelogs/client_server/newsfragments/2083.clarification delete mode 100644 changelogs/client_server/newsfragments/2087.clarification delete mode 100644 changelogs/client_server/newsfragments/2088.clarification delete mode 100644 changelogs/client_server/newsfragments/2089.clarification delete mode 100644 changelogs/client_server/newsfragments/2090.clarification delete mode 100644 changelogs/client_server/newsfragments/2091.clarification delete mode 100644 changelogs/client_server/newsfragments/2097.clarification delete mode 100644 changelogs/client_server/newsfragments/2098.clarification delete mode 100644 changelogs/client_server/newsfragments/2101.breaking diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index eb92c29d..c56a1073 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -1,3 +1,85 @@ +r0.5.0 +====== + +Breaking Changes +---------------- + +- Add a new ``submit_url`` field to the responses of ``/requestToken`` which older clients will not be able to handle correctly. (`#2101 `_) + + +Deprecations +------------ + +- Remove references to presence lists. (`#1817 `_) + + +New Endpoints +------------- + +- ``GET /account_data`` routes. (`#1873 `_) + + +Backwards Compatible Changes +---------------------------- + +- Add megolm session export format. (`#1701 `_) +- Add support for advertising experimental features to clients. (`#1786 `_) +- Add a generic SSO login API. (`#1789 `_) +- Add a mechanism for servers to redirect clients to an alternative homeserver after logging in. (`#1790 `_) +- Add room version upgrades. (`#1791 `_, `#1875 `_) +- Support optional features by having clients query for capabilities. (`#1829 `_, `#1879 `_) +- Add ``M_RESOURCE_LIMIT_EXCEEDED`` as an error code for when homeservers exceed limits imposed on them. (`#1874 `_) +- Emit ``M_UNSUPPORTED_ROOM_VERSION`` error codes where applicable on ``/createRoom`` and ``/invite`` APIs. (`#1908 `_) +- Add a ``.m.rule.tombstone`` default push rule for room ugprade notifications. (`#2020 `_) +- Add support for sending server notices to clients. (`#2026 `_) +- Add MSISDN (phone number) support to User-Interactive Authentication. (`#2030 `_) +- Add the option to lazy-load room members for increased client performance. (`#2035 `_) +- Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server. (`#2046 `_) +- Add support for Olm sessions becoming un-stuck. (`#2059 `_) +- Add interactive device verification, including a common framework for device verification. (`#2072 `_) + + +Spec Clarifications +------------------- + +- Change examples to use example.org instead of a real domain. (`#1650 `_) +- Clarify that ``state_default`` in ``m.room.power_levels`` always defaults to 50. (`#1656 `_) +- Add missing ``status_msg`` to ``m.presence`` schema. (`#1744 `_) +- Fix various spelling mistakes throughout the specification. (`#1838 `_, `#1853 `_, `#1860 `_, `#1933 `_, `#1969 `_, `#1988 `_, `#1989 `_, `#1991 `_, `#1992 `_) +- Add the missing ``m.push_rules`` event schema. (`#1889 `_) +- Clarify how modern day local echo is meant to be solved by clients. (`#1891 `_) +- Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``. (`#1975 `_) +- Clarify how ``m.login.dummy`` can be used to disambiguate login flows. (`#1999 `_) +- Remove ``prev_content`` from the redaction algorithm's essential keys list. (`#2016 `_) +- Fix the ``third_party_signed`` definitions for the join APIs. (`#2025 `_) +- Clarify why User Interactive Auth is used on password changes and how access tokens are handled. (`#2027 `_) +- Clarify that devices are deleted upon logout. (`#2028 `_) +- Add ``M_NOT_FOUND`` error definition for deleting room aliases. (`#2029 `_) +- Add missing ``reason`` to ``m.call.hangup``. (`#2031 `_) +- Clarify how redactions affect room state. (`#2032 `_) +- Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers. (`#2036 `_) +- Fix example ``Content-Type`` for ``/media/upload`` request. (`#2041 `_) +- Clarify that login flows are meant to be completed in order. (`#2042 `_) +- Clarify that clients should not send read receipts for their own messages. (`#2043 `_) +- Use consistent examples of events throughout the specification. (`#2051 `_) +- Clarify which push rule condition kinds exist. (`#2052 `_) +- Clarify the required fields on ``m.file`` (and similar) messages. (`#2053 `_) +- Clarify that User-Interactive Authentication stages cannot be attempted more than once. (`#2054 `_) +- Clarify which parameters apply in what scenarios on ``/register``. (`#2055 `_) +- Clarify how to interpret changes of ``membership`` over time. (`#2056 `_) +- Clarify exactly what invite_room_state consists of. (`#2067 `_) +- Clarify how the content repository works, and what it is used for. (`#2068 `_) +- Clarify the order events in chunk are returned in for ``/messages``. (`#2069 `_) +- Clarify the key object definition for the key management API. (`#2083 `_) +- Reorganize information about events into a common section. (`#2087 `_) +- De-duplicate ``/state/`` endpoints, clarifying that the ```` is optional. (`#2088 `_) +- Clarify when and where CORS headers should be returned. (`#2089 `_) +- Clarify when authorization and rate-limiting are not applicable. (`#2090 `_) +- Clarify that ``/register`` must produce valid Matrix User IDs. (`#2091 `_) +- Clarify how ``unread_notifications`` is calculated. (`#2097 `_) +- Clarify what a "module" is and update feature profiles for clients. (`#2098 `_) + + r0.4.0 ====== diff --git a/changelogs/client_server/newsfragments/1650.clarification b/changelogs/client_server/newsfragments/1650.clarification deleted file mode 100644 index 617b7ab6..00000000 --- a/changelogs/client_server/newsfragments/1650.clarification +++ /dev/null @@ -1 +0,0 @@ -Change examples to use example.org instead of a real domain. diff --git a/changelogs/client_server/newsfragments/1656.clarification b/changelogs/client_server/newsfragments/1656.clarification deleted file mode 100644 index 0c8f4ad0..00000000 --- a/changelogs/client_server/newsfragments/1656.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that ``state_default`` in ``m.room.power_levels`` always defaults to 50. diff --git a/changelogs/client_server/newsfragments/1701.feature b/changelogs/client_server/newsfragments/1701.feature deleted file mode 100644 index cf6084ae..00000000 --- a/changelogs/client_server/newsfragments/1701.feature +++ /dev/null @@ -1 +0,0 @@ -Add megolm session export format. diff --git a/changelogs/client_server/newsfragments/1744.clarification b/changelogs/client_server/newsfragments/1744.clarification deleted file mode 100644 index dfe838f1..00000000 --- a/changelogs/client_server/newsfragments/1744.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing ``status_msg`` to ``m.presence`` schema. diff --git a/changelogs/client_server/newsfragments/1786.feature b/changelogs/client_server/newsfragments/1786.feature deleted file mode 100644 index 6f21778c..00000000 --- a/changelogs/client_server/newsfragments/1786.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for advertising experimental features to clients. diff --git a/changelogs/client_server/newsfragments/1789.feature b/changelogs/client_server/newsfragments/1789.feature deleted file mode 100644 index 97c1e5ca..00000000 --- a/changelogs/client_server/newsfragments/1789.feature +++ /dev/null @@ -1 +0,0 @@ -Add a generic SSO login API. diff --git a/changelogs/client_server/newsfragments/1790.feature b/changelogs/client_server/newsfragments/1790.feature deleted file mode 100644 index 26dccd05..00000000 --- a/changelogs/client_server/newsfragments/1790.feature +++ /dev/null @@ -1 +0,0 @@ -Add a mechanism for servers to redirect clients to an alternative homeserver after logging in. diff --git a/changelogs/client_server/newsfragments/1791.feature b/changelogs/client_server/newsfragments/1791.feature deleted file mode 100644 index 0a854c8f..00000000 --- a/changelogs/client_server/newsfragments/1791.feature +++ /dev/null @@ -1 +0,0 @@ -Add room version upgrades. diff --git a/changelogs/client_server/newsfragments/1817.deprecation b/changelogs/client_server/newsfragments/1817.deprecation deleted file mode 100644 index 2c52d198..00000000 --- a/changelogs/client_server/newsfragments/1817.deprecation +++ /dev/null @@ -1 +0,0 @@ -Remove references to presence lists. diff --git a/changelogs/client_server/newsfragments/1829.feature b/changelogs/client_server/newsfragments/1829.feature deleted file mode 100644 index 107291f3..00000000 --- a/changelogs/client_server/newsfragments/1829.feature +++ /dev/null @@ -1 +0,0 @@ -Support optional features by having clients query for capabilities. diff --git a/changelogs/client_server/newsfragments/1838.clarification b/changelogs/client_server/newsfragments/1838.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1838.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1853.clarification b/changelogs/client_server/newsfragments/1853.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1853.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1860.clarification b/changelogs/client_server/newsfragments/1860.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1860.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1873.new b/changelogs/client_server/newsfragments/1873.new deleted file mode 100644 index 724a4308..00000000 --- a/changelogs/client_server/newsfragments/1873.new +++ /dev/null @@ -1 +0,0 @@ -``GET /account_data`` routes. diff --git a/changelogs/client_server/newsfragments/1874.feature b/changelogs/client_server/newsfragments/1874.feature deleted file mode 100644 index bdab5464..00000000 --- a/changelogs/client_server/newsfragments/1874.feature +++ /dev/null @@ -1 +0,0 @@ -Add ``M_RESOURCE_LIMIT_EXCEEDED`` as an error code for when homeservers exceed limits imposed on them. diff --git a/changelogs/client_server/newsfragments/1875.feature b/changelogs/client_server/newsfragments/1875.feature deleted file mode 100644 index 0a854c8f..00000000 --- a/changelogs/client_server/newsfragments/1875.feature +++ /dev/null @@ -1 +0,0 @@ -Add room version upgrades. diff --git a/changelogs/client_server/newsfragments/1879.feature b/changelogs/client_server/newsfragments/1879.feature deleted file mode 100644 index 107291f3..00000000 --- a/changelogs/client_server/newsfragments/1879.feature +++ /dev/null @@ -1 +0,0 @@ -Support optional features by having clients query for capabilities. diff --git a/changelogs/client_server/newsfragments/1889.clarification b/changelogs/client_server/newsfragments/1889.clarification deleted file mode 100644 index 2737a7ee..00000000 --- a/changelogs/client_server/newsfragments/1889.clarification +++ /dev/null @@ -1 +0,0 @@ -Add the missing ``m.push_rules`` event schema. diff --git a/changelogs/client_server/newsfragments/1891.clarification b/changelogs/client_server/newsfragments/1891.clarification deleted file mode 100644 index ef4edfb4..00000000 --- a/changelogs/client_server/newsfragments/1891.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how modern day local echo is meant to be solved by clients. diff --git a/changelogs/client_server/newsfragments/1908.feature b/changelogs/client_server/newsfragments/1908.feature deleted file mode 100644 index 1c64d826..00000000 --- a/changelogs/client_server/newsfragments/1908.feature +++ /dev/null @@ -1 +0,0 @@ -Emit ``M_UNSUPPORTED_ROOM_VERSION`` error codes where applicable on ``/createRoom`` and ``/invite`` APIs. diff --git a/changelogs/client_server/newsfragments/1933.clarification b/changelogs/client_server/newsfragments/1933.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1933.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1969.clarification b/changelogs/client_server/newsfragments/1969.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1969.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1975.clarification b/changelogs/client_server/newsfragments/1975.clarification deleted file mode 100644 index ac118bfd..00000000 --- a/changelogs/client_server/newsfragments/1975.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``. diff --git a/changelogs/client_server/newsfragments/1988.clarification b/changelogs/client_server/newsfragments/1988.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1988.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1989.clarification b/changelogs/client_server/newsfragments/1989.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1989.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1991.clarification b/changelogs/client_server/newsfragments/1991.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1991.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1992.clarification b/changelogs/client_server/newsfragments/1992.clarification deleted file mode 100644 index b0f05203..00000000 --- a/changelogs/client_server/newsfragments/1992.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various spelling mistakes throughout the specification. diff --git a/changelogs/client_server/newsfragments/1999.clarification b/changelogs/client_server/newsfragments/1999.clarification deleted file mode 100644 index 748c55f2..00000000 --- a/changelogs/client_server/newsfragments/1999.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how ``m.login.dummy`` can be used to disambiguate login flows. diff --git a/changelogs/client_server/newsfragments/2016.clarification b/changelogs/client_server/newsfragments/2016.clarification deleted file mode 100644 index 77ea0d4c..00000000 --- a/changelogs/client_server/newsfragments/2016.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove ``prev_content`` from the redaction algorithm's essential keys list. diff --git a/changelogs/client_server/newsfragments/2020.feature b/changelogs/client_server/newsfragments/2020.feature deleted file mode 100644 index 0d7c7eb8..00000000 --- a/changelogs/client_server/newsfragments/2020.feature +++ /dev/null @@ -1 +0,0 @@ -Add a ``.m.rule.tombstone`` default push rule for room ugprade notifications. diff --git a/changelogs/client_server/newsfragments/2025.clarification b/changelogs/client_server/newsfragments/2025.clarification deleted file mode 100644 index 9e99b23d..00000000 --- a/changelogs/client_server/newsfragments/2025.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the ``third_party_signed`` definitions for the join APIs. diff --git a/changelogs/client_server/newsfragments/2026.feature b/changelogs/client_server/newsfragments/2026.feature deleted file mode 100644 index f82b9aea..00000000 --- a/changelogs/client_server/newsfragments/2026.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for sending server notices to clients. diff --git a/changelogs/client_server/newsfragments/2027.clarification b/changelogs/client_server/newsfragments/2027.clarification deleted file mode 100644 index db74ea56..00000000 --- a/changelogs/client_server/newsfragments/2027.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify why User Interactive Auth is used on password changes and how access tokens are handled. diff --git a/changelogs/client_server/newsfragments/2028.clarification b/changelogs/client_server/newsfragments/2028.clarification deleted file mode 100644 index 75e21e74..00000000 --- a/changelogs/client_server/newsfragments/2028.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that devices are deleted upon logout. diff --git a/changelogs/client_server/newsfragments/2029.clarification b/changelogs/client_server/newsfragments/2029.clarification deleted file mode 100644 index 95b65481..00000000 --- a/changelogs/client_server/newsfragments/2029.clarification +++ /dev/null @@ -1 +0,0 @@ -Add ``M_NOT_FOUND`` error definition for deleting room aliases. diff --git a/changelogs/client_server/newsfragments/2030.feature b/changelogs/client_server/newsfragments/2030.feature deleted file mode 100644 index b5975a73..00000000 --- a/changelogs/client_server/newsfragments/2030.feature +++ /dev/null @@ -1 +0,0 @@ -Add MSISDN (phone number) support to User-Interactive Authentication. diff --git a/changelogs/client_server/newsfragments/2031.clarification b/changelogs/client_server/newsfragments/2031.clarification deleted file mode 100644 index 9bed3bcc..00000000 --- a/changelogs/client_server/newsfragments/2031.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing ``reason`` to ``m.call.hangup``. diff --git a/changelogs/client_server/newsfragments/2032.clarification b/changelogs/client_server/newsfragments/2032.clarification deleted file mode 100644 index e497b8be..00000000 --- a/changelogs/client_server/newsfragments/2032.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how redactions affect room state. diff --git a/changelogs/client_server/newsfragments/2035.feature b/changelogs/client_server/newsfragments/2035.feature deleted file mode 100644 index 47029c28..00000000 --- a/changelogs/client_server/newsfragments/2035.feature +++ /dev/null @@ -1 +0,0 @@ -Add the option to lazy-load room members for increased client performance. diff --git a/changelogs/client_server/newsfragments/2036.clarification b/changelogs/client_server/newsfragments/2036.clarification deleted file mode 100644 index 96058b7b..00000000 --- a/changelogs/client_server/newsfragments/2036.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers. diff --git a/changelogs/client_server/newsfragments/2041.clarification b/changelogs/client_server/newsfragments/2041.clarification deleted file mode 100644 index 39bbddb5..00000000 --- a/changelogs/client_server/newsfragments/2041.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix example ``Content-Type`` for ``/media/upload`` request. diff --git a/changelogs/client_server/newsfragments/2042.clarification b/changelogs/client_server/newsfragments/2042.clarification deleted file mode 100644 index 4e17b99f..00000000 --- a/changelogs/client_server/newsfragments/2042.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that login flows are meant to be completed in order. diff --git a/changelogs/client_server/newsfragments/2043.clarification b/changelogs/client_server/newsfragments/2043.clarification deleted file mode 100644 index 9bb975fa..00000000 --- a/changelogs/client_server/newsfragments/2043.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that clients should not send read receipts for their own messages. diff --git a/changelogs/client_server/newsfragments/2046.feature b/changelogs/client_server/newsfragments/2046.feature deleted file mode 100644 index e54df535..00000000 --- a/changelogs/client_server/newsfragments/2046.feature +++ /dev/null @@ -1 +0,0 @@ -Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server. diff --git a/changelogs/client_server/newsfragments/2051.clarification b/changelogs/client_server/newsfragments/2051.clarification deleted file mode 100644 index 384daa11..00000000 --- a/changelogs/client_server/newsfragments/2051.clarification +++ /dev/null @@ -1 +0,0 @@ -Use consistent examples of events throughout the specification. diff --git a/changelogs/client_server/newsfragments/2052.clarification b/changelogs/client_server/newsfragments/2052.clarification deleted file mode 100644 index 95bdc928..00000000 --- a/changelogs/client_server/newsfragments/2052.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify which push rule condition kinds exist. diff --git a/changelogs/client_server/newsfragments/2053.clarification b/changelogs/client_server/newsfragments/2053.clarification deleted file mode 100644 index 2a72a88e..00000000 --- a/changelogs/client_server/newsfragments/2053.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the required fields on ``m.file`` (and similar) messages. diff --git a/changelogs/client_server/newsfragments/2054.clarification b/changelogs/client_server/newsfragments/2054.clarification deleted file mode 100644 index e43aea2d..00000000 --- a/changelogs/client_server/newsfragments/2054.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that User-Interactive Authentication stages cannot be attempted more than once. diff --git a/changelogs/client_server/newsfragments/2055.clarification b/changelogs/client_server/newsfragments/2055.clarification deleted file mode 100644 index 3a57ef7e..00000000 --- a/changelogs/client_server/newsfragments/2055.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify which parameters apply in what scenarios on ``/register``. diff --git a/changelogs/client_server/newsfragments/2056.clarification b/changelogs/client_server/newsfragments/2056.clarification deleted file mode 100644 index 12521867..00000000 --- a/changelogs/client_server/newsfragments/2056.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how to interpret changes of ``membership`` over time. diff --git a/changelogs/client_server/newsfragments/2059.feature b/changelogs/client_server/newsfragments/2059.feature deleted file mode 100644 index fde106ce..00000000 --- a/changelogs/client_server/newsfragments/2059.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for Olm sessions becoming un-stuck. diff --git a/changelogs/client_server/newsfragments/2067.clarification b/changelogs/client_server/newsfragments/2067.clarification deleted file mode 100644 index cc706274..00000000 --- a/changelogs/client_server/newsfragments/2067.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify exactly what invite_room_state consists of. diff --git a/changelogs/client_server/newsfragments/2068.clarification b/changelogs/client_server/newsfragments/2068.clarification deleted file mode 100644 index 77ad7125..00000000 --- a/changelogs/client_server/newsfragments/2068.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how the content repository works, and what it is used for. diff --git a/changelogs/client_server/newsfragments/2069.clarification b/changelogs/client_server/newsfragments/2069.clarification deleted file mode 100644 index 127573a6..00000000 --- a/changelogs/client_server/newsfragments/2069.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the order events in chunk are returned in for ``/messages``. diff --git a/changelogs/client_server/newsfragments/2072.feature b/changelogs/client_server/newsfragments/2072.feature deleted file mode 100644 index c7d8bd76..00000000 --- a/changelogs/client_server/newsfragments/2072.feature +++ /dev/null @@ -1 +0,0 @@ -Add interactive device verification, including a common framework for device verification. diff --git a/changelogs/client_server/newsfragments/2083.clarification b/changelogs/client_server/newsfragments/2083.clarification deleted file mode 100644 index 8083d85d..00000000 --- a/changelogs/client_server/newsfragments/2083.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the key object definition for the key management API. diff --git a/changelogs/client_server/newsfragments/2087.clarification b/changelogs/client_server/newsfragments/2087.clarification deleted file mode 100644 index 1974127d..00000000 --- a/changelogs/client_server/newsfragments/2087.clarification +++ /dev/null @@ -1 +0,0 @@ -Reorganize information about events into a common section. diff --git a/changelogs/client_server/newsfragments/2088.clarification b/changelogs/client_server/newsfragments/2088.clarification deleted file mode 100644 index ae22d66a..00000000 --- a/changelogs/client_server/newsfragments/2088.clarification +++ /dev/null @@ -1 +0,0 @@ -De-duplicate ``/state/`` endpoints, clarifying that the ```` is optional. diff --git a/changelogs/client_server/newsfragments/2089.clarification b/changelogs/client_server/newsfragments/2089.clarification deleted file mode 100644 index 17405adc..00000000 --- a/changelogs/client_server/newsfragments/2089.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify when and where CORS headers should be returned. diff --git a/changelogs/client_server/newsfragments/2090.clarification b/changelogs/client_server/newsfragments/2090.clarification deleted file mode 100644 index 23ab50f7..00000000 --- a/changelogs/client_server/newsfragments/2090.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify when authorization and rate-limiting are not applicable. diff --git a/changelogs/client_server/newsfragments/2091.clarification b/changelogs/client_server/newsfragments/2091.clarification deleted file mode 100644 index 2c4a276e..00000000 --- a/changelogs/client_server/newsfragments/2091.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that ``/register`` must produce valid Matrix User IDs. diff --git a/changelogs/client_server/newsfragments/2097.clarification b/changelogs/client_server/newsfragments/2097.clarification deleted file mode 100644 index 68d89bcc..00000000 --- a/changelogs/client_server/newsfragments/2097.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how ``unread_notifications`` is calculated. diff --git a/changelogs/client_server/newsfragments/2098.clarification b/changelogs/client_server/newsfragments/2098.clarification deleted file mode 100644 index 1c8ba3ea..00000000 --- a/changelogs/client_server/newsfragments/2098.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify what a "module" is and update feature profiles for clients. diff --git a/changelogs/client_server/newsfragments/2101.breaking b/changelogs/client_server/newsfragments/2101.breaking deleted file mode 100644 index 68971171..00000000 --- a/changelogs/client_server/newsfragments/2101.breaking +++ /dev/null @@ -1 +0,0 @@ -Add a new ``submit_url`` field to the responses of ``/requestToken`` which older clients will not be able to handle correctly. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index bc2d66d7..dd6e3246 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -45,6 +45,7 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: - `HEAD `_: Includes all changes since the latest versioned release. +- `r0.5.0 `_ - `r0.4.0 `_ - `r0.3.0 `_ - `r0.2.0 `_ From 8f1f8b4fe5bf5b21ca943678c54d30b1ffbf3025 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 11:28:35 -0600 Subject: [PATCH 266/497] Fix references to filtering We can't have two different backlinks for the same text, so use LL as the label --- api/client-server/event_context.yaml | 4 ++-- api/client-server/message_pagination.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/client-server/event_context.yaml b/api/client-server/event_context.yaml index 802f5f27..3bea351c 100644 --- a/api/client-server/event_context.yaml +++ b/api/client-server/event_context.yaml @@ -35,8 +35,8 @@ paths: after the specified event. This allows clients to get the context surrounding an event. - *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_ - for more information. + *Note*: This endpoint supports lazy-loading of room member events. See + `Lazy-loading room members <#lazy-loading-room-members>`_ for more information. operationId: getEventContext security: - accessToken: [] diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index dc33b717..22828219 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -34,8 +34,8 @@ paths: This API returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room. - *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_ - for more information. + *Note*: This endpoint supports lazy-loading of room member events. See + `Lazy-loading room members <#lazy-loading-room-members>`_ for more information. operationId: getRoomEvents security: - accessToken: [] From ba5479e46f1cd0aecdec54d200233a8d4f771882 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 11:30:04 -0600 Subject: [PATCH 267/497] Reference Canonical JSON --- specification/client_server_api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index dd6e3246..9b16abc3 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1491,6 +1491,8 @@ Some event types have additional size restrictions which are specified in the description of the event. Additional keys have no limit other than that implied by the total 65 KB limit on events. +.. _`Canonical JSON`: ../appendices.html#canonical-json + Room Events ~~~~~~~~~~~ .. NOTE:: From 19a3d574b7e9b961b9df5ceeaa5e13e7f34a077a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 11:31:24 -0600 Subject: [PATCH 268/497] Fix HKDF rationale --- specification/modules/end_to_end_encryption.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 62881967..36336c74 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -671,6 +671,7 @@ parameter is the concatenation of: * The ``transaction_id`` being used. .. admonition:: Rationale + HKDF is used over the plain shared secret as it results in a harder attack as well as more uniform data to work with. From 26349417ba01d5a28fc35faa9f66038a294c316a Mon Sep 17 00:00:00 2001 From: Sorunome Date: Tue, 11 Jun 2019 21:13:16 +0200 Subject: [PATCH 269/497] update spoiler render idea --- proposals/2010-spoilers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index 366f4a3e..40feed29 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -20,7 +20,7 @@ It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribut contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. It could be rendered, for example, similar to this: -![Spoiler rendering idea](https://user-images.githubusercontent.com/2433620/58178745-082c1480-7ca7-11e9-901b-13b147cfd157.png) +![Spoiler rendering idea](https://user-images.githubusercontent.com/2433620/59299700-95063480-8c8d-11e9-9348-3e2c8bc94bdc.gif) The plain-text fallback could be rendered as `(Spoiler: )` and `(Spoiler for : )` respectively. From e60d2defbd608476a4ae15816bf51e813c0e6713 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 12 Jun 2019 13:47:09 -0600 Subject: [PATCH 270/497] Fix changelog generation Only include the target version, not all versions. Additionally, make sure the appservice spec isn't hardcoded as "unstable". --- scripts/templating/matrix_templates/units.py | 4 ++++ specification/application_service_api.rst | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index eeda9e63..157fa5a1 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -962,6 +962,9 @@ class MatrixUnits(Units): if re.match("^[=]{3,}$", line.strip()): # the last line was a header - use that as our new title_part title_part = prev_line.strip() + # take off the last line from the changelog_body_lines because it's the title + if len(changelog_body_lines) > 0: + changelog_body_lines = changelog_body_lines[:len(changelog_body_lines) - 1] continue if re.match("^[-]{3,}$", line.strip()): # the last line is a subheading - drop this line because it's the underline @@ -975,6 +978,7 @@ class MatrixUnits(Units): # that it renders correctly in the section. We also add newlines so that there's # intentionally blank lines that make rst2html happy. changelog_body_lines.append(" " + line + '\n') + prev_line = line if len(changelog_body_lines) > 0: changelogs[api_name] = "".join(changelog_body_lines) diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index ee7e9de7..11a07839 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -36,7 +36,7 @@ Changelog --------- -.. topic:: Version: unstable +.. topic:: Version: %APPSERVICE_RELEASE_LABEL% {{application_service_changelog}} This version of the specification is generated from From 18eca900220031bc92de970ce68662d5c3e9a89a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 12 Jun 2019 13:48:50 -0600 Subject: [PATCH 271/497] Exclude DEL from historical user IDs The range is inclusive, so don't include 7F --- specification/appendices/identifier_grammar.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index c2c734ab..4cce1f90 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -190,7 +190,7 @@ history includes events with a ``sender`` which does not conform. In order to handle these rooms successfully, clients and servers MUST accept user IDs with localparts from the expanded character set:: - extended_user_id_char = %x21-39 / %x3B-7F ; all ascii printing chars except : + extended_user_id_char = %x21-39 / %x3B-7E ; all ascii printing chars except : Mapping from other character sets <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< From b8f1f3792744878b26f17b413c3c7936428a7f05 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 12 Jun 2019 15:29:25 -0600 Subject: [PATCH 272/497] Remove incorrect id_server param from IS spec Fixes https://github.com/matrix-org/matrix-doc/issues/2118 --- api/client-server/administrative_contact.yaml | 4 +-- .../definitions/request_email_validation.yaml | 26 +++++++++++++++++++ .../request_msisdn_validation.yaml | 26 +++++++++++++++++++ api/client-server/registration.yaml | 14 +++++----- .../definitions/request_email_validation.yaml | 9 +------ .../request_msisdn_validation.yaml | 9 +------ .../newsfragments/2124.clarification | 1 + 7 files changed, 64 insertions(+), 25 deletions(-) create mode 100644 api/client-server/definitions/request_email_validation.yaml create mode 100644 api/client-server/definitions/request_msisdn_validation.yaml create mode 100644 changelogs/identity_service/newsfragments/2124.clarification diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index c196c109..0e93e4cd 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -246,7 +246,7 @@ paths: name: body required: true schema: - $ref: "../identity/definitions/request_email_validation.yaml" + $ref: "./definitions/request_email_validation.yaml" responses: 200: description: |- @@ -297,7 +297,7 @@ paths: name: body required: true schema: - $ref: "../identity/definitions/request_msisdn_validation.yaml" + $ref: "./definitions/request_msisdn_validation.yaml" responses: 200: description: An SMS message was sent to the given phone number. diff --git a/api/client-server/definitions/request_email_validation.yaml b/api/client-server/definitions/request_email_validation.yaml new file mode 100644 index 00000000..15bc5b3a --- /dev/null +++ b/api/client-server/definitions/request_email_validation.yaml @@ -0,0 +1,26 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: +- $ref: "../../identity/definitions/request_email_validation.yaml" +- type: object + properties: + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + example: "id.example.com" + required: ["id_server"] diff --git a/api/client-server/definitions/request_msisdn_validation.yaml b/api/client-server/definitions/request_msisdn_validation.yaml new file mode 100644 index 00000000..370a10cc --- /dev/null +++ b/api/client-server/definitions/request_msisdn_validation.yaml @@ -0,0 +1,26 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +type: object +allOf: +- $ref: "../../identity/definitions/request_msisdn_validation.yaml" +- type: object + properties: + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + example: "id.example.com" + required: ["id_server"] diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index d04e1a33..71177d0c 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -242,7 +242,7 @@ paths: name: body required: true schema: - $ref: "../identity/definitions/request_email_validation.yaml" + $ref: "./definitions/request_email_validation.yaml" responses: 200: description: |- @@ -295,7 +295,7 @@ paths: name: body required: true schema: - $ref: "../identity/definitions/request_msisdn_validation.yaml" + $ref: "./definitions/request_msisdn_validation.yaml" responses: 200: description: |- @@ -392,14 +392,14 @@ paths: associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the ``/account/password`` endpoint. - + This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint, except that ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the given email address could be found. The server may instead send an email to the given address prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - + The homeserver has the choice of validating the email address itself, or proxying the request to the ``/validate/email/requestToken`` Identity Service API. The request should be proxied to the domain that @@ -417,7 +417,7 @@ paths: name: body required: true schema: - $ref: "../identity/definitions/request_email_validation.yaml" + $ref: "./definitions/request_email_validation.yaml" responses: 200: description: An email was sent to the given address. @@ -453,14 +453,14 @@ paths: associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the ``/account/password`` endpoint. - + This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint, except that ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the given phone number could be found. The server may instead send the SMS to the given phone number prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - + The homeserver has the choice of validating the phone number itself, or proxying the request to the ``/validate/msisdn/requestToken`` Identity Service API. The request should be proxied to the domain that is sent diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index b99fe121..1a7502c7 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -49,11 +49,4 @@ properties: redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. example: "https://example.org/congratulations.html" - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May optionally - include a port. This parameter is ignored when the homeserver handles - 3PID verification. - example: "id.example.com" -required: ["client_secret", "email", "send_attempt", "id_server"] +required: ["client_secret", "email", "send_attempt"] diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index 08dd0482..018bd733 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -55,11 +55,4 @@ properties: redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request. example: "https://example.org/congratulations.html" - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May optionally - include a port. This parameter is ignored when the homeserver handles - 3PID verification. - example: "id.example.com" -required: ["client_secret", "country", "phone_number", "send_attempt", "id_server"] +required: ["client_secret", "country", "phone_number", "send_attempt"] diff --git a/changelogs/identity_service/newsfragments/2124.clarification b/changelogs/identity_service/newsfragments/2124.clarification new file mode 100644 index 00000000..384af82f --- /dev/null +++ b/changelogs/identity_service/newsfragments/2124.clarification @@ -0,0 +1 @@ +Remove incorrect ``id_server`` parameter from ``/requestToken`` endpoints. From 67ea3b9ce8321499a81961cdc1faddbf2cbacb2a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 12 Jun 2019 15:41:10 -0600 Subject: [PATCH 273/497] Add 403 error to IS unbind Fixes https://github.com/matrix-org/matrix-doc/issues/2117 --- api/identity/associations.yaml | 13 +++++++++++++ .../newsfragments/2126.clarification | 1 + 2 files changed, 14 insertions(+) create mode 100644 changelogs/identity_service/newsfragments/2126.clarification diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index f44fe3cc..8ff4a9ed 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -279,6 +279,19 @@ paths: If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error. + 403: + description: |- + The credentials supplied to authenticate the request were invalid. + This may also be returned if the identity server does not support + the chosen authentication method (such as blocking homeservers from + unbinding identifiers). + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Invalid homeserver signature" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" 501: description: |- If the response body is not a JSON Matrix error, the identity server diff --git a/changelogs/identity_service/newsfragments/2126.clarification b/changelogs/identity_service/newsfragments/2126.clarification new file mode 100644 index 00000000..1475b4b4 --- /dev/null +++ b/changelogs/identity_service/newsfragments/2126.clarification @@ -0,0 +1 @@ +Clarify that identity servers can return 403 for unbind requests. From e670fb1f5a67daefdf4d4351ff33dd21bb945981 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Wed, 12 Jun 2019 14:32:33 -0700 Subject: [PATCH 274/497] Add missing format fields to m.room.message$m.notice schema. Signed-off-by: Jimmy Cuadra --- .../client_server/newsfragments/2125.clarification | 1 + event-schemas/schema/m.room.message$m.notice | 10 ++++++++++ 2 files changed, 11 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2125.clarification diff --git a/changelogs/client_server/newsfragments/2125.clarification b/changelogs/client_server/newsfragments/2125.clarification new file mode 100644 index 00000000..c71cdfff --- /dev/null +++ b/changelogs/client_server/newsfragments/2125.clarification @@ -0,0 +1 @@ +Add missing format fields to ``m.room.message$m.notice`` schema. diff --git a/event-schemas/schema/m.room.message$m.notice b/event-schemas/schema/m.room.message$m.notice index ef97e28a..19c4f985 100644 --- a/event-schemas/schema/m.room.message$m.notice +++ b/event-schemas/schema/m.room.message$m.notice @@ -12,6 +12,16 @@ properties: enum: - m.notice type: string + format: + description: |- + The format used in the ``formatted_body``. Currently only + ``org.matrix.custom.html`` is supported. + type: string + formatted_body: + description: |- + The formatted version of the ``body``. This is required if ``format`` + is specified. + type: string required: - msgtype - body From decb75555c103cd4c00066fe49ea9dc4757aabcc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 12 Jun 2019 18:09:15 -0600 Subject: [PATCH 275/497] =?UTF-8?q?We're=20stable=20now=20=F0=9F=8E=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0b814fb9..fc5b146f 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -75,10 +75,8 @@ ask. Adding to the changelog ~~~~~~~~~~~~~~~~~~~~~~~ -Currently only changes to the client-server API need to end up in a changelog. The -other APIs are not yet stable and therefore do not have a changelog. Adding to the -changelog can only be done after you've opened your pull request, so be sure to do -that first. +All API specifications require a changelog entry. Adding to the changelog can only +be done after you've opened your pull request, so be sure to do that first. The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the form of "news fragments". The news fragments for the client-server API are stored From 2dd0da7d50ed8209ba277c5b10bacf7f1ebdecd2 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Fri, 14 Jun 2019 13:46:20 -0700 Subject: [PATCH 276/497] Fix typo in key verification framework section. Signed-off-by: Jimmy Cuadra --- changelogs/client_server/newsfragments/2131.clarification | 1 + specification/modules/end_to_end_encryption.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2131.clarification diff --git a/changelogs/client_server/newsfragments/2131.clarification b/changelogs/client_server/newsfragments/2131.clarification new file mode 100644 index 00000000..3c41fb60 --- /dev/null +++ b/changelogs/client_server/newsfragments/2131.clarification @@ -0,0 +1 @@ +Fix typo in key verification framework section. diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 36336c74..f94fec2d 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -419,7 +419,7 @@ Key verification framework Verifying keys manually by reading out the Ed25519 key is not very user friendly, and can lead to errors. In order to help mitigate errors, and to make the process -eaiser for users, some verification methods are supported by the specification. +easier for users, some verification methods are supported by the specification. The methods all use a common framework for negotiating the key verification. To use this framework, Alice's client would send ``m.key.verification.request`` From b885714d94aa694fe267e3d36318b12d48499934 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Thu, 13 Jun 2019 17:21:11 -0700 Subject: [PATCH 277/497] Remove the "required" designation from the `url` field of certain m.room.message msgtypes. Now that content referenced by the *m.audio*, *m.file*, *m.image*, and *m.video* message types can be encrypted, the `url` field is required *only* if the content is unencrypted. The "required" designation in the event schemas (which prefixes the field description with "Required" in bold in the generated HTML) is used to indicate fields which must always be present, and this is no longer the case. Signed-off-by: Jimmy Cuadra --- changelogs/client_server/newsfragments/2129.clarification | 1 + event-schemas/schema/m.room.message$m.audio | 3 +-- event-schemas/schema/m.room.message$m.file | 1 - event-schemas/schema/m.room.message$m.image | 1 - event-schemas/schema/m.room.message$m.video | 1 - 5 files changed, 2 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2129.clarification diff --git a/changelogs/client_server/newsfragments/2129.clarification b/changelogs/client_server/newsfragments/2129.clarification new file mode 100644 index 00000000..82ed4fce --- /dev/null +++ b/changelogs/client_server/newsfragments/2129.clarification @@ -0,0 +1 @@ +Remove "required" designation from the ``url`` field of certain ``m`.room.message` msgtypes. diff --git a/event-schemas/schema/m.room.message$m.audio b/event-schemas/schema/m.room.message$m.audio index 88b459ec..fb049fc9 100644 --- a/event-schemas/schema/m.room.message$m.audio +++ b/event-schemas/schema/m.room.message$m.audio @@ -28,7 +28,7 @@ properties: type: string url: description: |- - Required if the file is not encrypted. The URL (typically `MXC URI`_) + Required if the file is unencrypted. The URL (typically `MXC URI`_) to the audio clip. type: string file: @@ -40,7 +40,6 @@ properties: required: - msgtype - body - - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message$m.file b/event-schemas/schema/m.room.message$m.file index 9f4fdf07..54a999ec 100644 --- a/event-schemas/schema/m.room.message$m.file +++ b/event-schemas/schema/m.room.message$m.file @@ -55,7 +55,6 @@ properties: required: - msgtype - body - - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message$m.image b/event-schemas/schema/m.room.message$m.image index a466562a..8944ce96 100644 --- a/event-schemas/schema/m.room.message$m.image +++ b/event-schemas/schema/m.room.message$m.image @@ -30,7 +30,6 @@ properties: required: - msgtype - body - - url type: object type: enum: diff --git a/event-schemas/schema/m.room.message$m.video b/event-schemas/schema/m.room.message$m.video index b23c2392..1a3c3e40 100644 --- a/event-schemas/schema/m.room.message$m.video +++ b/event-schemas/schema/m.room.message$m.video @@ -61,7 +61,6 @@ properties: required: - msgtype - body - - url type: object type: enum: From bc71dacaf4f65e2a27705a658fc4b303ecba16c9 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Fri, 14 Jun 2019 16:05:25 -0700 Subject: [PATCH 278/497] Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. Currently the *m.key.verification.start* event appears twice with the exact same title, in the "Key verification framework" section and the "Short Authentication (SAS) verification" section. It's not immediately clear that the first occurrence describes the format of the event in general terms and that the second occurrence describes the fields when the *m.sas.v1* verification method is being used. This is a similar relationship to the *m.room.message* event and its various *msgtype* variants. This commit does three things: * It tweaks the generation of the documentation to change the title of the second occurrence of *m.key.verification.start* to distinguish it from the first. * It updates the language in the description of the two versions of the event to better describe the relationship between the two. * It adds the optional `next_method` field to the schema of the *m.sas.v1* variant, as specified in the general form of *m.key.verification.start*. Signed-off-by: Jimmy Cuadra --- .../client_server/newsfragments/2132.clarification | 1 + event-schemas/schema/m.key.verification.start | 2 +- event-schemas/schema/m.key.verification.start$m.sas.v1 | 8 ++++++-- scripts/templating/matrix_templates/units.py | 9 +++++++++ 4 files changed, 17 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2132.clarification diff --git a/changelogs/client_server/newsfragments/2132.clarification b/changelogs/client_server/newsfragments/2132.clarification new file mode 100644 index 00000000..53063400 --- /dev/null +++ b/changelogs/client_server/newsfragments/2132.clarification @@ -0,0 +1 @@ +Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start index ad59d6c7..99b4998e 100644 --- a/event-schemas/schema/m.key.verification.start +++ b/event-schemas/schema/m.key.verification.start @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a key verification process. Typically sent as a `to-device`_ event. + Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` field determines the type of verification. The fields in the event will differ depending on the ``method``. This definition includes fields that are in common among all variants. properties: content: properties: diff --git a/event-schemas/schema/m.key.verification.start$m.sas.v1 b/event-schemas/schema/m.key.verification.start$m.sas.v1 index 867ca820..a42f20e7 100644 --- a/event-schemas/schema/m.key.verification.start$m.sas.v1 +++ b/event-schemas/schema/m.key.verification.start$m.sas.v1 @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a SAS key verification process. Typically sent as a `to-device`_ event. + Begins an SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event. properties: content: properties: @@ -22,7 +22,11 @@ properties: type: string enum: ["m.sas.v1"] description: |- - The verification method to use. Must be ``m.sas.v1``. + The verification method to use. + next_method: + type: string + description: |- + Optional method to use to verify the other user's key with. key_agreement_protocols: type: array description: |- diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 157fa5a1..8538de2d 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -902,6 +902,15 @@ class MatrixUnits(Units): "`m.room.message msgtypes`_." ) + # method types for m.key.verification.start + if schema["type"] == "m.key.verification.start": + methods = Units.prop( + json_schema, "properties/content/properties/method/enum" + ) + if methods: + schema["type_with_msgtype"] = schema["type"] + " (" + methods[0] + ")" + + # Assign state key info if it has some if schema["typeof"] == "State Event": skey_desc = Units.prop( From 5384b61d95c82dcde6e924ce40f037f7f659d70f Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Fri, 14 Jun 2019 17:35:39 -0700 Subject: [PATCH 279/497] Fix style issues brought up during code review. Signed-off-by: Jimmy Cuadra --- changelogs/client_server/newsfragments/2132.clarification | 2 +- event-schemas/schema/m.key.verification.start | 4 +++- scripts/templating/matrix_templates/units.py | 1 - 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/changelogs/client_server/newsfragments/2132.clarification b/changelogs/client_server/newsfragments/2132.clarification index 53063400..1c458340 100644 --- a/changelogs/client_server/newsfragments/2132.clarification +++ b/changelogs/client_server/newsfragments/2132.clarification @@ -1 +1 @@ -Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. +Clarify the distinction between ``m`.key.verification.start` and its `m`.`sas.v1` variant. diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start index 99b4998e..28926f4f 100644 --- a/event-schemas/schema/m.key.verification.start +++ b/event-schemas/schema/m.key.verification.start @@ -3,7 +3,9 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` field determines the type of verification. The fields in the event will differ depending on the ``method``. This definition includes fields that are in common among all variants. + Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` + field determines the type of verification. The fields in the event will differ depending + on the ``method``. This definition includes fields that are in common among all variants. properties: content: properties: diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 8538de2d..04e6f8a9 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -910,7 +910,6 @@ class MatrixUnits(Units): if methods: schema["type_with_msgtype"] = schema["type"] + " (" + methods[0] + ")" - # Assign state key info if it has some if schema["typeof"] == "State Event": skey_desc = Units.prop( From 33ca891e71e6673ff6bdd3706d34c9c45d16da03 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 14 Jun 2019 22:22:43 -0600 Subject: [PATCH 280/497] Fix link to Olm signing specification See https://github.com/matrix-org/matrix.org/issues/478 --- changelogs/client_server/newsfragments/2133.clarification | 1 + specification/modules/end_to_end_encryption.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2133.clarification diff --git a/changelogs/client_server/newsfragments/2133.clarification b/changelogs/client_server/newsfragments/2133.clarification new file mode 100644 index 00000000..3a003179 --- /dev/null +++ b/changelogs/client_server/newsfragments/2133.clarification @@ -0,0 +1 @@ +Fix link to Olm signing specification. diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index f94fec2d..27ba4998 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -411,7 +411,7 @@ Device verification may reach one of several conclusions. For example: protocol to verify that a given message was sent from a device holding that Ed25519 private key, or to encrypt a message so that it may only be decrypted by such a device. For the Olm protocol, this is documented at - https://matrix.org/git/olm/about/docs/signing.rst. + https://matrix.org/docs/spec/olm_signing.html. Key verification framework From 6f460ad70aa6c642b582bc9a3b140ffbcab41271 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 14 Jun 2019 22:26:29 -0600 Subject: [PATCH 281/497] minus spec according to the apache .htaccess we use --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 27ba4998..329c0170 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -411,7 +411,7 @@ Device verification may reach one of several conclusions. For example: protocol to verify that a given message was sent from a device holding that Ed25519 private key, or to encrypt a message so that it may only be decrypted by such a device. For the Olm protocol, this is documented at - https://matrix.org/docs/spec/olm_signing.html. + https://matrix.org/docs/olm_signing.html. Key verification framework From 3eff76b00aabfc34cc267dafe857cedc7bf564f6 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sat, 15 Jun 2019 12:36:57 +0100 Subject: [PATCH 282/497] MSC 2134 --- proposals/2134-identity-hash-lookup.md | 56 ++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 proposals/2134-identity-hash-lookup.md diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md new file mode 100644 index 00000000..af732cfe --- /dev/null +++ b/proposals/2134-identity-hash-lookup.md @@ -0,0 +1,56 @@ +# MSC 2134: Identity Hash Lookups + +[Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been recently created in response to a security issue brought up by an independant party. To summarise the issue, lookups (of matrix userids) are performed using non-hashed 3pids which means that the 3pid is identifiable to anyone who can see the payload (e.g. willh AT matrix.org can be identified by a human). + +The problem with this, is that a malicious identity service could then store the plaintext 3pid and make an assumption that the requesting entity knows the holder of the 3pid, even if the identity service does not know of the 3pid beforehand. + +If the 3pid is hashed, the identity service could not determine the owner of the 3pid unless the identity service has already been made aware of the 3pid by the owner themselves (using the /bind mechanism). + +Note that this proposal does not stop a identity service from mapping hashed 3pids to many users, in an attempt to form a social graph. However the identity of the 3pid will remain a mystery until /bind is used. + +It should be clear that there is a need to hide any address from the identity service that has not been explicitly bound to it, and this proposal aims to solve that for the lookup API. + + +## Proposal + +This proposal suggests making changes to the Identity Service API's lookup endpoints. Due to the nature of this proposal, the new endpoints should be +on a `v2` path: + +- `/_matrix/identity/api/v2/lookup` +- `/_matrix/identity/api/v2/bulk_lookup` + +The parameters will remain the same, but `address` should no longer be in a plain-text format. Medium will now take a SHA-256 format hash value, and the resulting digest should be encoded in base64 format. For example: + +```python +address = "willh@matrix.org" +digest = hashlib.sha256(address.encode()).digest() +result_address = base64.encodebytes(digest).decode() +print(result_address) +CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w= +``` + +SHA-256 has been chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) in the Matrix protocol, and the only requirement for the hashing algorithm is that it cannot be used to guess the real value of the address + +No parameter changes will be made to /bind, but identity services should keep a hashed value for each address it knows about in order to process lookups quicker and it is the recommendation that this is done at the time of bind. + +`v1` versions of these endpoints may be disabled at the discretion of the implementation, and should return a `M_FORBIDDEN` `errcode` if so. + + +## Tradeoffs + +* This approach means that the client now needs to calculate a hash by itself, but the belief is that most librarys provide a mechanism for doing so. +* There is a small cost incurred by doing hashes before requests, but this is outweighed by the privacy implications of sending plaintext addresses. + + +## Potential issues + +This proposal does not force a identity service to stop handling plaintext requests, because a large amount of the matrix ecosystem relies upon this behavior. However, a conscious effort should be made by all users to use the privacy respecting endpoints outlined above. Identity services may disallow use of the v1 endpoint. + + +## Security considerations + +None + +## Conclusion + +This proposal outlines a quick and effective method to stop bulk collection of users contact lists and their social graphs without any disasterous side effects. All functionality which depends on the lookup service should continue to function unhindered by the use of hashes. \ No newline at end of file From a8c26d208b8ceae31b2d9d55f5a2c75c3a6ba4d4 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sat, 15 Jun 2019 12:43:20 +0100 Subject: [PATCH 283/497] Wrap --- proposals/2134-identity-hash-lookup.md | 56 ++++++++++++++++++-------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index af732cfe..1bc48e9a 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -1,25 +1,38 @@ -# MSC 2134: Identity Hash Lookups +# MSC2134: Identity Hash Lookups -[Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been recently created in response to a security issue brought up by an independant party. To summarise the issue, lookups (of matrix userids) are performed using non-hashed 3pids which means that the 3pid is identifiable to anyone who can see the payload (e.g. willh AT matrix.org can be identified by a human). +[Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been recently +created in response to a security issue brought up by an independant party. To summarise +the issue, lookups (of matrix userids) are performed using non-hashed 3pids which means +that the 3pid is identifiable to anyone who can see the payload (e.g. willh AT matrix.org +can be identified by a human). -The problem with this, is that a malicious identity service could then store the plaintext 3pid and make an assumption that the requesting entity knows the holder of the 3pid, even if the identity service does not know of the 3pid beforehand. +The problem with this, is that a malicious identity service could then store the plaintext +3pid and make an assumption that the requesting entity knows the holder of the 3pid, even +if the identity service does not know of the 3pid beforehand. -If the 3pid is hashed, the identity service could not determine the owner of the 3pid unless the identity service has already been made aware of the 3pid by the owner themselves (using the /bind mechanism). +If the 3pid is hashed, the identity service could not determinethe owner of the 3pid +unless the identity service has already been made aware of the 3pid by the owner +themselves (using the /bind mechanism). -Note that this proposal does not stop a identity service from mapping hashed 3pids to many users, in an attempt to form a social graph. However the identity of the 3pid will remain a mystery until /bind is used. +Note that this proposal does not stop a identity service from mapping hashed 3pids to many +users, in an attempt to form a social graph. However the identity of the 3pid will remain +a mystery until /bind is used. -It should be clear that there is a need to hide any address from the identity service that has not been explicitly bound to it, and this proposal aims to solve that for the lookup API. +It should be clear that there is a need to hide any address from the identity service that +has not been explicitly bound to it, and this proposal aims to solve that for the lookup API. ## Proposal -This proposal suggests making changes to the Identity Service API's lookup endpoints. Due to the nature of this proposal, the new endpoints should be -on a `v2` path: +This proposal suggests making changes to the Identity Service API's lookup endpoints. Due +to the nature of this proposal, the new endpoints should be on a `v2` path: - `/_matrix/identity/api/v2/lookup` - `/_matrix/identity/api/v2/bulk_lookup` -The parameters will remain the same, but `address` should no longer be in a plain-text format. Medium will now take a SHA-256 format hash value, and the resulting digest should be encoded in base64 format. For example: +The parameters will remain the same, but `address` should no longer be in a plain-text +format. Medium will now take a SHA-256 format hash value, and the resulting digest should +be encoded in base64 format. For example: ```python address = "willh@matrix.org" @@ -29,22 +42,31 @@ print(result_address) CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w= ``` -SHA-256 has been chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) in the Matrix protocol, and the only requirement for the hashing algorithm is that it cannot be used to guess the real value of the address +SHA-256 has been chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) in the Matrix protocol, and the only +requirement for the hashing algorithm is that it cannot be used to guess the real value of the address -No parameter changes will be made to /bind, but identity services should keep a hashed value for each address it knows about in order to process lookups quicker and it is the recommendation that this is done at the time of bind. +No parameter changes will be made to /bind, but identity services should keep a hashed value +for each address it knows about in order to process lookups quicker and it is the recommendation +that this is done at the time of bind. -`v1` versions of these endpoints may be disabled at the discretion of the implementation, and should return a `M_FORBIDDEN` `errcode` if so. +`v1` versions of these endpoints may be disabled at the discretion of the implementation, and +should return a `M_FORBIDDEN` `errcode` if so. ## Tradeoffs -* This approach means that the client now needs to calculate a hash by itself, but the belief is that most librarys provide a mechanism for doing so. -* There is a small cost incurred by doing hashes before requests, but this is outweighed by the privacy implications of sending plaintext addresses. +* This approach means that the client now needs to calculate a hash by itself, but the belief + is that most librarys provide a mechanism for doing so. +* There is a small cost incurred by doing hashes before requests, but this is outweighed by + the privacy implications of sending plaintext addresses. ## Potential issues -This proposal does not force a identity service to stop handling plaintext requests, because a large amount of the matrix ecosystem relies upon this behavior. However, a conscious effort should be made by all users to use the privacy respecting endpoints outlined above. Identity services may disallow use of the v1 endpoint. +This proposal does not force a identity service to stop handling plaintext requests, because +a large amount of the matrix ecosystem relies upon this behavior. However, a conscious effort +should be made by all users to use the privacy respecting endpoints outlined above. Identity +services may disallow use of the v1 endpoint. ## Security considerations @@ -53,4 +75,6 @@ None ## Conclusion -This proposal outlines a quick and effective method to stop bulk collection of users contact lists and their social graphs without any disasterous side effects. All functionality which depends on the lookup service should continue to function unhindered by the use of hashes. \ No newline at end of file +This proposal outlines a quick and effective method to stop bulk collection of users contact +lists and their social graphs without any disasterous side effects. All functionality which +depends on the lookup service should continue to function unhindered by the use of hashes. \ No newline at end of file From 8b92df74abfd6c045bf348a05b67281328cdcb6a Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sat, 15 Jun 2019 13:25:42 +0100 Subject: [PATCH 284/497] s/medium/address --- proposals/2134-identity-hash-lookup.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 1bc48e9a..29144ec6 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -31,7 +31,7 @@ to the nature of this proposal, the new endpoints should be on a `v2` path: - `/_matrix/identity/api/v2/bulk_lookup` The parameters will remain the same, but `address` should no longer be in a plain-text -format. Medium will now take a SHA-256 format hash value, and the resulting digest should +format. `address` will now take a SHA-256 format hash value, and the resulting digest should be encoded in base64 format. For example: ```python @@ -42,6 +42,8 @@ print(result_address) CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w= ``` +### Example request + SHA-256 has been chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) in the Matrix protocol, and the only requirement for the hashing algorithm is that it cannot be used to guess the real value of the address From 12431f1a4e4f5ef0a7d61c1bcf3f1989d227c7f5 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sat, 15 Jun 2019 13:29:59 +0100 Subject: [PATCH 285/497] Base64 potential issue --- proposals/2134-identity-hash-lookup.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 29144ec6..54e8bcbf 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -2,15 +2,15 @@ [Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been recently created in response to a security issue brought up by an independant party. To summarise -the issue, lookups (of matrix userids) are performed using non-hashed 3pids which means -that the 3pid is identifiable to anyone who can see the payload (e.g. willh AT matrix.org -can be identified by a human). +the issue, lookups (of matrix user ids) are performed using non-hashed 3pids which means +that the 3pid is identifiable to anyone who can see the payload (e.g. willh@matrix.org +can be identified). The problem with this, is that a malicious identity service could then store the plaintext 3pid and make an assumption that the requesting entity knows the holder of the 3pid, even if the identity service does not know of the 3pid beforehand. -If the 3pid is hashed, the identity service could not determinethe owner of the 3pid +If the 3pid is hashed, the identity service could not determine the owner of the 3pid unless the identity service has already been made aware of the 3pid by the owner themselves (using the /bind mechanism). @@ -21,7 +21,6 @@ a mystery until /bind is used. It should be clear that there is a need to hide any address from the identity service that has not been explicitly bound to it, and this proposal aims to solve that for the lookup API. - ## Proposal This proposal suggests making changes to the Identity Service API's lookup endpoints. Due @@ -58,7 +57,7 @@ should return a `M_FORBIDDEN` `errcode` if so. ## Tradeoffs * This approach means that the client now needs to calculate a hash by itself, but the belief - is that most librarys provide a mechanism for doing so. + is that most languages provide a mechanism for doing so. * There is a small cost incurred by doing hashes before requests, but this is outweighed by the privacy implications of sending plaintext addresses. @@ -70,6 +69,10 @@ a large amount of the matrix ecosystem relies upon this behavior. However, a con should be made by all users to use the privacy respecting endpoints outlined above. Identity services may disallow use of the v1 endpoint. +Base64 has been chosen to encode the value due to it's ubiquitous support in many languages, +however it does mean that special characters in the address will have to be encoded when used +as a parameter value. + ## Security considerations From 8affb23e5ef62e01ba5c43d3d91f633748580994 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Sat, 15 Jun 2019 13:44:58 -0700 Subject: [PATCH 286/497] Address feedback from code review. * Switch "an SAS" back to "a SAS" * Remove the `next_method` field from m.key.verification.start$m.sas.v1 but add additional clarification to its description on m.key.verification.start that it is never present for methods that verify keys both ways. --- event-schemas/schema/m.key.verification.start | 3 ++- event-schemas/schema/m.key.verification.start$m.sas.v1 | 6 +----- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start index 28926f4f..faa7a96a 100644 --- a/event-schemas/schema/m.key.verification.start +++ b/event-schemas/schema/m.key.verification.start @@ -28,7 +28,8 @@ properties: type: string description: |- Optional method to use to verify the other user's key with. Applicable - when the ``method`` chosen only verifies one user's key. + when the ``method`` chosen only verifies one user's key. This field will + never be present if the ``method`` verifies keys both ways. required: - from_device - transaction_id diff --git a/event-schemas/schema/m.key.verification.start$m.sas.v1 b/event-schemas/schema/m.key.verification.start$m.sas.v1 index a42f20e7..daf6fa39 100644 --- a/event-schemas/schema/m.key.verification.start$m.sas.v1 +++ b/event-schemas/schema/m.key.verification.start$m.sas.v1 @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins an SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event. + Begins a SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event. properties: content: properties: @@ -23,10 +23,6 @@ properties: enum: ["m.sas.v1"] description: |- The verification method to use. - next_method: - type: string - description: |- - Optional method to use to verify the other user's key with. key_agreement_protocols: type: array description: |- From 802b90d1132407efb1b1ae6adc6511901f9ace46 Mon Sep 17 00:00:00 2001 From: Anatoly Sablin Date: Sun, 16 Jun 2019 22:24:06 +0300 Subject: [PATCH 287/497] Typo. --- event-schemas/schema/m.key.verification.accept | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event-schemas/schema/m.key.verification.accept b/event-schemas/schema/m.key.verification.accept index 41c59968..ad54488e 100644 --- a/event-schemas/schema/m.key.verification.accept +++ b/event-schemas/schema/m.key.verification.accept @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Accepts a previously sent ``m.key.verification.start`` messge. Typically sent as a + Accepts a previously sent ``m.key.verification.start`` message. Typically sent as a `to-device`_ event. properties: content: From c63b5aff697c71c80b34b73ddf3ba327dae7c3b9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 17 Jun 2019 00:10:59 -0600 Subject: [PATCH 288/497] Create 2136.clarification --- changelogs/client_server/newsfragments/2136.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2136.clarification diff --git a/changelogs/client_server/newsfragments/2136.clarification b/changelogs/client_server/newsfragments/2136.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/2136.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. From f8dbf2b360b8b2f220b9c43c450b2845db10a1e1 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 17 Jun 2019 13:17:57 +0100 Subject: [PATCH 289/497] Update proposals/2134-identity-hash-lookup.md Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2134-identity-hash-lookup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 54e8bcbf..ad00c6fc 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -80,6 +80,6 @@ None ## Conclusion -This proposal outlines a quick and effective method to stop bulk collection of users contact +This proposal outlines a quick and effective method to stop bulk collection of user's contact lists and their social graphs without any disasterous side effects. All functionality which -depends on the lookup service should continue to function unhindered by the use of hashes. \ No newline at end of file +depends on the lookup service should continue to function unhindered by the use of hashes. From d09af5b191472fd7078aeff1b5c13558ab4a1212 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 17 Jun 2019 11:18:24 -0600 Subject: [PATCH 290/497] Identity r0.2.1 --- changelogs/identity_service.rst | 10 ++++++++++ .../identity_service/newsfragments/2124.clarification | 1 - .../identity_service/newsfragments/2126.clarification | 1 - 3 files changed, 10 insertions(+), 2 deletions(-) delete mode 100644 changelogs/identity_service/newsfragments/2124.clarification delete mode 100644 changelogs/identity_service/newsfragments/2126.clarification diff --git a/changelogs/identity_service.rst b/changelogs/identity_service.rst index d60812b8..cb06709d 100644 --- a/changelogs/identity_service.rst +++ b/changelogs/identity_service.rst @@ -1,3 +1,13 @@ +r0.2.1 +====== + +Spec Clarifications +------------------- + +- Remove incorrect ``id_server`` parameter from ``/requestToken`` endpoints. (`#2124 `_) +- Clarify that identity servers can return 403 for unbind requests. (`#2126 `_) + + r0.2.0 ====== diff --git a/changelogs/identity_service/newsfragments/2124.clarification b/changelogs/identity_service/newsfragments/2124.clarification deleted file mode 100644 index 384af82f..00000000 --- a/changelogs/identity_service/newsfragments/2124.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove incorrect ``id_server`` parameter from ``/requestToken`` endpoints. diff --git a/changelogs/identity_service/newsfragments/2126.clarification b/changelogs/identity_service/newsfragments/2126.clarification deleted file mode 100644 index 1475b4b4..00000000 --- a/changelogs/identity_service/newsfragments/2126.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that identity servers can return 403 for unbind requests. From d2b47a585d5fbdba44b8d461f30a8e72a1e50e25 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 18 Jun 2019 16:37:02 +0100 Subject: [PATCH 291/497] Allow for changing the hashing algo and add at-rest details --- proposals/2134-identity-hash-lookup.md | 99 ++++++++++++++------------ 1 file changed, 55 insertions(+), 44 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index ad00c6fc..9b448d68 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -1,57 +1,59 @@ # MSC2134: Identity Hash Lookups -[Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been recently -created in response to a security issue brought up by an independant party. To summarise -the issue, lookups (of matrix user ids) are performed using non-hashed 3pids which means -that the 3pid is identifiable to anyone who can see the payload (e.g. willh@matrix.org -can be identified). +[Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been +recently created in response to a security issue brought up by an independent +party. To summarise the issue, lookups (of matrix user ids) are performed using +non-hashed 3pids (third-party IDs) which means that the identity server can +identify and record every 3pid that the user wants to check, whether that +address is already known by the identity server or not. -The problem with this, is that a malicious identity service could then store the plaintext -3pid and make an assumption that the requesting entity knows the holder of the 3pid, even -if the identity service does not know of the 3pid beforehand. +If the 3pid is hashed, the identity service could not determine the address +unless it has already seen that address in plain-text during a previous call of +the /bind mechanism. -If the 3pid is hashed, the identity service could not determine the owner of the 3pid -unless the identity service has already been made aware of the 3pid by the owner -themselves (using the /bind mechanism). +Note that in terms of privacy, this proposal does not stop an identity service +from mapping hashed 3pids to users, resulting in a social graph. However, the +identity of the 3pid will at least remain a mystery until /bind is used. -Note that this proposal does not stop a identity service from mapping hashed 3pids to many -users, in an attempt to form a social graph. However the identity of the 3pid will remain -a mystery until /bind is used. - -It should be clear that there is a need to hide any address from the identity service that -has not been explicitly bound to it, and this proposal aims to solve that for the lookup API. +This proposal thus calls for the Identity Service’s /lookup API to use hashed +3pids instead of their plain-text counterparts. ## Proposal -This proposal suggests making changes to the Identity Service API's lookup endpoints. Due -to the nature of this proposal, the new endpoints should be on a `v2` path: +This proposal suggests making changes to the Identity Service API's lookup +endpoints. Due to the nature of this proposal, the new endpoints should be on a +`v2` path: - `/_matrix/identity/api/v2/lookup` - `/_matrix/identity/api/v2/bulk_lookup` -The parameters will remain the same, but `address` should no longer be in a plain-text -format. `address` will now take a SHA-256 format hash value, and the resulting digest should -be encoded in base64 format. For example: +The parameters will remain the same, but `address` should no longer be in a +plain-text format. `address` will now take a hash value, and the resulting +digest should be encoded in unpadded base64. For example: ```python -address = "willh@matrix.org" +address = "user@example.org" digest = hashlib.sha256(address.encode()).digest() -result_address = base64.encodebytes(digest).decode() +result_address = unpaddedbase64.encode_base64(digest) print(result_address) -CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w= +CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w ``` ### Example request -SHA-256 has been chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) in the Matrix protocol, and the only -requirement for the hashing algorithm is that it cannot be used to guess the real value of the address +SHA-256 has been chosen as it is [currently used +elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) +in the Matrix protocol. As time goes on, this algorithm may be changed provided +a spec bump is performed. Then, clients making a request to `/lookup` must use +the hashing algorithm defined in whichever version of the CS spec they and the +IS have agreed to speaking. -No parameter changes will be made to /bind, but identity services should keep a hashed value -for each address it knows about in order to process lookups quicker and it is the recommendation -that this is done at the time of bind. +No parameter changes will be made to /bind, but identity services should keep a +hashed value for each address it knows about in order to process lookups +quicker. It is the recommendation that this is done during the act of binding. -`v1` versions of these endpoints may be disabled at the discretion of the implementation, and -should return a `M_FORBIDDEN` `errcode` if so. +`v1` versions of these endpoints may be disabled at the discretion of the +implementation, and should return a `M_FORBIDDEN` `errcode` if so. ## Tradeoffs @@ -59,20 +61,27 @@ should return a `M_FORBIDDEN` `errcode` if so. * This approach means that the client now needs to calculate a hash by itself, but the belief is that most languages provide a mechanism for doing so. * There is a small cost incurred by doing hashes before requests, but this is outweighed by - the privacy implications of sending plaintext addresses. - + the privacy implications of sending plain-text addresses. ## Potential issues -This proposal does not force a identity service to stop handling plaintext requests, because -a large amount of the matrix ecosystem relies upon this behavior. However, a conscious effort -should be made by all users to use the privacy respecting endpoints outlined above. Identity -services may disallow use of the v1 endpoint. +This proposal does not force an identity service to stop handling plain-text +requests, because a large amount of the matrix ecosystem relies upon this +behavior. However, a conscious effort should be made by all users to use the +privacy respecting endpoints outlined above. Identity services may disallow use +of the v1 endpoint. -Base64 has been chosen to encode the value due to it's ubiquitous support in many languages, -however it does mean that special characters in the address will have to be encoded when used -as a parameter value. +Unpadded base64 has been chosen to encode the value due to its ubiquitous +support in many languages, however it does mean that special characters in the +address will have to be encoded when used as a parameter value. +## Other considered solutions + +Ideally identity servers would never receive plain-text addresses, however it +is necessary for the identity server to send an email/sms message during a +bind, as it cannot trust a homeserver to do so as the homeserver may be lying. +Additionally, only storing 3pid hashes at rest instead of the plain-text +versions is impractical if the hashing algorithm ever needs to be changed. ## Security considerations @@ -80,6 +89,8 @@ None ## Conclusion -This proposal outlines a quick and effective method to stop bulk collection of user's contact -lists and their social graphs without any disasterous side effects. All functionality which -depends on the lookup service should continue to function unhindered by the use of hashes. +This proposal outlines an effective method to stop bulk collection of user's +contact lists and their social graphs without any disastrous side effects. All +functionality which depends on the lookup service should continue to function +unhindered by the use of hashes. + From 063b9f60e0441f252df7cdf00fc5b5ee1774b99a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 18 Jun 2019 16:50:47 +0100 Subject: [PATCH 292/497] Require a salt to defend against rainbow tables --- proposals/2134-identity-hash-lookup.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 9b448d68..bc25b92e 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -43,10 +43,12 @@ CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w SHA-256 has been chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) -in the Matrix protocol. As time goes on, this algorithm may be changed provided -a spec bump is performed. Then, clients making a request to `/lookup` must use -the hashing algorithm defined in whichever version of the CS spec they and the -IS have agreed to speaking. +in the Matrix protocol. Additionally a hardcoded salt (“matrix” or something) +must be prepended to the data before hashing in order to serve as a weak +defense against existing rainbow tables. As time goes on, this algorithm may be +changed provided a spec bump is performed. Then, clients making a request to +`/lookup` must use the hashing algorithm defined in whichever version of the CS +spec they and the IS have agreed to speaking. No parameter changes will be made to /bind, but identity services should keep a hashed value for each address it knows about in order to process lookups From bc9b6c3659e861779367de35234666523b319d2a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 18 Jun 2019 17:03:49 +0100 Subject: [PATCH 293/497] Add salt to example and signal link --- proposals/2134-identity-hash-lookup.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index bc25b92e..a34ee767 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -33,7 +33,8 @@ digest should be encoded in unpadded base64. For example: ```python address = "user@example.org" -digest = hashlib.sha256(address.encode()).digest() +salt = "matrix" +digest = hashlib.sha256((salt + address).encode()).digest() result_address = unpaddedbase64.encode_base64(digest) print(result_address) CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w @@ -85,6 +86,8 @@ bind, as it cannot trust a homeserver to do so as the homeserver may be lying. Additionally, only storing 3pid hashes at rest instead of the plain-text versions is impractical if the hashing algorithm ever needs to be changed. +Bloom filters are an alternative method of providing private contact discovery, however does not scale well due to clients needing to download a large filter that needs updating every time a new bind is made. Further considered solutions are explored in https://signal.org/blog/contact-discovery/ Signal's eventual solution of using SGX is considered impractical for a Matrix-style setup. + ## Security considerations None From 5049e552e7da9ff65ddbaa7610072baa5dfa0827 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 18 Jun 2019 17:05:46 +0100 Subject: [PATCH 294/497] Drop /api from the new endpoint --- proposals/2134-identity-hash-lookup.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index a34ee767..45f7d5f0 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -22,10 +22,11 @@ This proposal thus calls for the Identity Service’s /lookup API to use hashed This proposal suggests making changes to the Identity Service API's lookup endpoints. Due to the nature of this proposal, the new endpoints should be on a -`v2` path: +`v2` path (we also drop the `/api` in order to preserve consistency across +other endpoints): -- `/_matrix/identity/api/v2/lookup` -- `/_matrix/identity/api/v2/bulk_lookup` +- `/_matrix/identity/v2/lookup` +- `/_matrix/identity/v2/bulk_lookup` The parameters will remain the same, but `address` should no longer be in a plain-text format. `address` will now take a hash value, and the resulting From 6bb4a9e9110e58bd9a383b3957b909db7ca54222 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 18 Jun 2019 17:09:06 +0100 Subject: [PATCH 295/497] Add per-is salt consideration --- proposals/2134-identity-hash-lookup.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 45f7d5f0..f7c36e74 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -89,6 +89,10 @@ versions is impractical if the hashing algorithm ever needs to be changed. Bloom filters are an alternative method of providing private contact discovery, however does not scale well due to clients needing to download a large filter that needs updating every time a new bind is made. Further considered solutions are explored in https://signal.org/blog/contact-discovery/ Signal's eventual solution of using SGX is considered impractical for a Matrix-style setup. +We could let an identity server specify its own salt for the hashes, however it +would require an extra network call before uploading 3pid hashes in order for +the client to ask the server which salt it requires. + ## Security considerations None From f41ed02c9e8f1c12a307567a38a15e71295e3495 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 18 Jun 2019 17:22:28 +0100 Subject: [PATCH 296/497] remove sec concerns --- proposals/2134-identity-hash-lookup.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index f7c36e74..8451f72c 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -93,10 +93,6 @@ We could let an identity server specify its own salt for the hashes, however it would require an extra network call before uploading 3pid hashes in order for the client to ask the server which salt it requires. -## Security considerations - -None - ## Conclusion This proposal outlines an effective method to stop bulk collection of user's From 82463833300121a2ddc5b2676e5e8fd64f4263d3 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Tue, 18 Jun 2019 16:37:37 -0700 Subject: [PATCH 297/497] Fix typos in changelog entry. --- changelogs/client_server/newsfragments/2132.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2132.clarification b/changelogs/client_server/newsfragments/2132.clarification index 1c458340..b8a4cc8a 100644 --- a/changelogs/client_server/newsfragments/2132.clarification +++ b/changelogs/client_server/newsfragments/2132.clarification @@ -1 +1 @@ -Clarify the distinction between ``m`.key.verification.start` and its `m`.`sas.v1` variant. +Clarify the distinction between ``m.key.verification.start`` and its ``m.sas.v1`` variant. From 3ee27d38180a6142237b86499830c2d4b4c610a5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 19 Jun 2019 15:14:30 +0100 Subject: [PATCH 298/497] salt->pepper. 1 pepper/is. add multi-hash idea --- proposals/2134-identity-hash-lookup.md | 94 +++++++++++++++++++++----- 1 file changed, 76 insertions(+), 18 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 8451f72c..cd5e3868 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -28,31 +28,81 @@ other endpoints): - `/_matrix/identity/v2/lookup` - `/_matrix/identity/v2/bulk_lookup` -The parameters will remain the same, but `address` should no longer be in a -plain-text format. `address` will now take a hash value, and the resulting -digest should be encoded in unpadded base64. For example: +`address` should no longer be in a plain-text format, but will now take a hash +value, and the resulting digest should be encoded in unpadded base64. For +example: ```python address = "user@example.org" -salt = "matrix" -digest = hashlib.sha256((salt + address).encode()).digest() +pepper = "matrix" +digest = hashlib.sha256((pepper + address).encode()).digest() result_address = unpaddedbase64.encode_base64(digest) print(result_address) CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w ``` -### Example request - SHA-256 has been chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) -in the Matrix protocol. Additionally a hardcoded salt (“matrix” or something) -must be prepended to the data before hashing in order to serve as a weak -defense against existing rainbow tables. As time goes on, this algorithm may be -changed provided a spec bump is performed. Then, clients making a request to -`/lookup` must use the hashing algorithm defined in whichever version of the CS -spec they and the IS have agreed to speaking. +in the Matrix protocol. Additionally a +[pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography)) must be prepended +to the data before hashing in order to serve as a weak defense against existing +rainbow tables. This pepper will be specified by the identity server in order +to prevent a single rainbow table being generated for all identity servers. As +time goes on, this algorithm may be changed provided a spec bump is performed. +Then, clients making a request to `/lookup` must use the hashing algorithm +defined in whichever version of the CS spec they and the IS have agreed to +speaking. -No parameter changes will be made to /bind, but identity services should keep a +Identity servers can specify their own peppers, which can be handy if a rainbow table is released for their current one. Identity servers could also set a timer for rotating this value to further impede rainbow table publishing. As such, it must be possible for clients to be able to query what pepper an identity server requires before sending it hashes. Thus a new endpoint must be added: + +``` +GET /_matrix/identity/v2/lookup_pepper +``` + +This endpoint takes no parameters, and simply returns the current pepper as a JSON object: + +``` +{ + "pepper": "matrixrocks" +} +``` + +In addition, the pepper the client used must be appended as a parameter to the +new `/lookup` and `/bulk_lookup` endpoints, ensuring that the client is using +the right one. If it does not match what the server has on file (which may be +the case is it rotated right after the client's request for it), then client +will know to query the pepper again instead of just getting a response saying +no contacts are registered on that identity server. + +Thus, a call to `/bulk_lookup` would look like the following: + +``` +{ + "threepids": [ + [ + "email", + "user@example.org" + ], + [ + "msisdn", + "123456789" + ], + [ + "email", + "user2@example.org" + ] + ], + "pepper": "matrixrocks" +} +``` + +If the pepper does not match the server's, the client should receive a `400 +M_INVALID_PARAM` with the error `Provided pepper value does not match +'$server_pepper'`. Clients should ensure they don't enter an infinite loop if +they receive this error more than once even after changing to the correct +pepper. + +No parameter changes will be made to /bind, but identity servers should keep a hashed value for each address it knows about in order to process lookups quicker. It is the recommendation that this is done during the act of binding. @@ -87,11 +137,19 @@ bind, as it cannot trust a homeserver to do so as the homeserver may be lying. Additionally, only storing 3pid hashes at rest instead of the plain-text versions is impractical if the hashing algorithm ever needs to be changed. -Bloom filters are an alternative method of providing private contact discovery, however does not scale well due to clients needing to download a large filter that needs updating every time a new bind is made. Further considered solutions are explored in https://signal.org/blog/contact-discovery/ Signal's eventual solution of using SGX is considered impractical for a Matrix-style setup. +Bloom filters are an alternative method of providing private contact discovery, +however does not scale well due to clients needing to download a large filter +that needs updating every time a new bind is made. Further considered solutions +are explored in https://signal.org/blog/contact-discovery/ Signal's eventual +solution of using SGX is considered impractical for a Matrix-style setup. -We could let an identity server specify its own salt for the hashes, however it -would require an extra network call before uploading 3pid hashes in order for -the client to ask the server which salt it requires. +Bit out of scope for this MSC, but there was an argument for not keeping all +IDs as hashed on disk in the identity server, that being if a hashing algorithm +was broken, we couldn't update the hashing algorithm without having the +plaintext 3PIDs. Well @toml helpfully said that we could just take the old +hashes and rehash them in the more secure hashing algorithm, thus transforming +the algo from ex. SHA256 to SHA256+SomeBetterAlg. This may spur an MSC in the +future that supports this, unless it is just an implementation detail. ## Conclusion From f28476f0f3887535fe8c21603933c8831db9d203 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 19 Jun 2019 16:29:24 +0100 Subject: [PATCH 299/497] line wrap and fix wording --- proposals/2134-identity-hash-lookup.md | 28 ++++++++++++++++---------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index cd5e3868..8ccfcfce 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -53,7 +53,12 @@ Then, clients making a request to `/lookup` must use the hashing algorithm defined in whichever version of the CS spec they and the IS have agreed to speaking. -Identity servers can specify their own peppers, which can be handy if a rainbow table is released for their current one. Identity servers could also set a timer for rotating this value to further impede rainbow table publishing. As such, it must be possible for clients to be able to query what pepper an identity server requires before sending it hashes. Thus a new endpoint must be added: +Identity servers can specify their own peppers, which can be handy if a rainbow +table is released for their current one. Identity servers could also set a +timer for rotating this value to further impede rainbow table publishing. As +such, it must be possible for clients to be able to query what pepper an +identity server requires before sending it hashes. Thus a new endpoint must be +added: ``` GET /_matrix/identity/v2/lookup_pepper @@ -81,15 +86,15 @@ Thus, a call to `/bulk_lookup` would look like the following: "threepids": [ [ "email", - "user@example.org" + "vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw" ], [ "msisdn", - "123456789" + "0VnvYk7YZpe08fP/CGqs3f39QtRjqAA2lPd14eLZXiw" ], [ "email", - "user2@example.org" + "BJaLI0RrLFDMbsk0eEp5BMsYDYzvOzDneQP/9NTemYA" ] ], "pepper": "matrixrocks" @@ -143,13 +148,14 @@ that needs updating every time a new bind is made. Further considered solutions are explored in https://signal.org/blog/contact-discovery/ Signal's eventual solution of using SGX is considered impractical for a Matrix-style setup. -Bit out of scope for this MSC, but there was an argument for not keeping all -IDs as hashed on disk in the identity server, that being if a hashing algorithm -was broken, we couldn't update the hashing algorithm without having the -plaintext 3PIDs. Well @toml helpfully said that we could just take the old -hashes and rehash them in the more secure hashing algorithm, thus transforming -the algo from ex. SHA256 to SHA256+SomeBetterAlg. This may spur an MSC in the -future that supports this, unless it is just an implementation detail. +While a bit out of scope for this MSC, there has been debate over preventing +3pids as being kept as plain-text on disk. The argument against this was that +if the hashing algorithm (in this case SHA-256) was broken, we couldn't update +the hashing algorithm without having the plaintext 3PIDs. Well @toml helpfully +added that we could just take the old hashes and rehash them in the more secure +hashing algorithm, thus transforming the hash from SHA-256 to +SHA-256+SomeBetterAlg. This may spur on an MSC in the future that supports +this, unless it is just an implementation detail. ## Conclusion From 1343e19a6d36bc624091320182c10452da046727 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 20 Jun 2019 14:36:47 +0100 Subject: [PATCH 300/497] Specify hash algorithm and fallback considerations --- proposals/2134-identity-hash-lookup.md | 44 ++++++++++++++++++-------- 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 8ccfcfce..43154d7c 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -61,23 +61,28 @@ identity server requires before sending it hashes. Thus a new endpoint must be added: ``` -GET /_matrix/identity/v2/lookup_pepper +GET /_matrix/identity/v2/hash_details ``` This endpoint takes no parameters, and simply returns the current pepper as a JSON object: ``` { - "pepper": "matrixrocks" + "pepper": "matrixrocks", + "algorithm": "sha256", } ``` -In addition, the pepper the client used must be appended as a parameter to the -new `/lookup` and `/bulk_lookup` endpoints, ensuring that the client is using -the right one. If it does not match what the server has on file (which may be -the case is it rotated right after the client's request for it), then client -will know to query the pepper again instead of just getting a response saying -no contacts are registered on that identity server. +Clients should request this endpoint every time before making a +`/(bulk_)lookup`, to handle identity servers which may rotate their pepper +values frequently. + +In addition, the pepper and hashing algorithm the client used must be a request +body field for the new `/lookup` and `/bulk_lookup` endpoints, ensuring that +the client is using the right parameters. If it does not match what the server +has on file (which may be the case is it rotated right after the client's +request for it), then the client will know to query the hash details again +instead of assuming that no contacts are registered on that identity server. Thus, a call to `/bulk_lookup` would look like the following: @@ -97,22 +102,33 @@ Thus, a call to `/bulk_lookup` would look like the following: "BJaLI0RrLFDMbsk0eEp5BMsYDYzvOzDneQP/9NTemYA" ] ], - "pepper": "matrixrocks" + "pepper": "matrixrocks", + "algorithm": "sha256" } ``` If the pepper does not match the server's, the client should receive a `400 -M_INVALID_PARAM` with the error `Provided pepper value does not match -'$server_pepper'`. Clients should ensure they don't enter an infinite loop if -they receive this error more than once even after changing to the correct -pepper. +M_INVALID_PARAM` with the error `Provided pepper does not match +'$server_pepper'`. If the algorithm does not match the server's, the client +should receive a `400 M_INVALID_PARAM` with the error `Provided algorithm does +not match '$server_algorithm'`. Clients should ensure they don't enter an +infinite loop if they receive these errors more than once even after changing +to the correct pepper and hash. No parameter changes will be made to /bind, but identity servers should keep a hashed value for each address it knows about in order to process lookups quicker. It is the recommendation that this is done during the act of binding. +## Fallback considerations + `v1` versions of these endpoints may be disabled at the discretion of the -implementation, and should return a `M_FORBIDDEN` `errcode` if so. +implementation, and should return a HTTP 403 with a `M_FORBIDDEN` `errcode` if +so. + +If an identity server is too old and a HTTP 404 is received when accessing the +`v2` endpoint, they should fallback to the `v1` endpoint instead. However, +clients should be aware that plain-text 3pids are required, and should ask for +user consent accordingly. ## Tradeoffs From 23af87e9fc898daffd3823490578f9c46442b85e Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 20 Jun 2019 17:41:19 +0100 Subject: [PATCH 301/497] Proposal for IS & IM TOS API --- proposals/2140-terms-of-service-2.md | 203 +++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 proposals/2140-terms-of-service-2.md diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md new file mode 100644 index 00000000..8c2ee75b --- /dev/null +++ b/proposals/2140-terms-of-service-2.md @@ -0,0 +1,203 @@ +# MSCXXXX: Terms of Service API for Identity Servers and Integration Managers + +MSC1692 introduces a method for homeservers to require that users read and +agree to certain documents before being permitted to use the service. This +proposal introduces a corresponding method that can be used with Identity +Servers and Integration Managers. + +The challenge here is that Identity Servers do not require any kind of user +login to access the service and so are unable to track what users have agreed +to what terms in the way that Homeservers do. We thereforce cannot re-use the +same method for Identity Servers without fundamentally changing the Identity +Service API. + +Requirements for this proposal are: + * ISs and IMs should be able to give multiple documents a user must agree to + abide by + * Each document shoud be versioned + * ISs and IMs must be able to prevent users from using the service if they + have not provided agreement. + * A user should only have to agree to each version of each document once for + their Matrix ID, ie. having agreed to a set of terms in one client, they + should not have to agree to them again when using a different client. + +## Proposal + +Throuhgout this proposal, $prefix will be used to refer to the prefix of the +API in question, ie. `/_matrix/identity/api/v1` for the IS API and +`/_matrix/integrations/v1` for the IM API. + +This proposal introduces: + * The `$prefix/terms` endpoint + * The `m.third_party_terms` section in account data + * The `X-TERMS-TOKEN` HTTP header + +### Terms API + +New API endpoints will be introduced: + +#### `GET $prefix/terms`: +This returns a set of documents that the user must agree to abide by in order +to use the service. Its response is similar to the structure used in the +`m.terms` UI auth flow of the Client/Server API: + +```json +{ + "policies": { + "terms_of_service": { + "version": "2.0", + "en": { + "name": "Terms of Service", + "url": "https://example.org/somewhere/terms-2.0-en.html" + }, + "fr": { + "name": "Conditions d'utilisation", + "url": "https://example.org/somewhere/terms-2.0-fr.html" + } + } + } +} +``` + +Each document (ie. key/value pair in the 'policies' object) MUST be +uniquely identified by its URL. It is therefore strongly recommended +that the URL contains the version number of the document. The name +and version keys, however, are used only to provide a human-readable +description of the document to the user. + +In the IM API, the client should provide authentication for this endpoint. + +#### `POST $prefix/terms`: +Requests to this endpoint have a single key, `user_accepts` whose value is +a list of URLs (given by the `url` field in the GET response) of documents that +the user has agreed to: + +```json +{ + "user_accepts": ["https://example.org/somewhere/terms-2.0-en.html"] +} +``` + +In the IM API, the client should provide authentication for this endpoint. + +The clients MUST include the correct URL for the language of the document that +was presented to the user and they agreed to. How servers store or serialise +acceptance into the `acceptance_token` is not defined, eg. they may internally +transform all URLs to the URL of the English-language version of each document +if the server deems it appropriate to do so. Servers should accept agreement of +any one language of each document as sufficient, regardless of what language a +client is operating in: users should not have to re-consent to documents if +they change their client to a different language. + +The response MAY contain a `acceptance_token` which, if given, is an +opaque string that the client must store for user in subsequent requests +to any endpoint to the same server. + +If the server has stored the fact that the user has agreed to these terms, +(which implies the user is authenticated) it can supply no `acceptance_token`. +The server may instead choose to supply an `acceptance_token`, for example if, +as in the IS API, the user is unauthenticated and therefore the server is +unable to store the fact a user has agreed to a set of terms. + +The `acceptance_token` is opaque and it is up to the server how it computes it, +but the server must be able to given an `acceptance_token`, compute whether it +constitutes agreement to a given set of terms. For example, the simplest (but +most verbose) implemenation would be to make the `acceptance_token` the JSON +array of documents as provided in the request. A smarter implementation may be +a simple hash, or even cryptograhic hash if desired. + +### Third-Party Terms Account Data + +This proposal also defines the `m.third_party_terms` section in User Account +Data in the client/server API that clients SHOULD use to track what sets of +terms the user has consented to. This has an array of URLs under the 'accepted' +key to which the user has agreed to. + +An `m.third_party_terms` section therefore resembles the following: + +```json +{ + "accepted": [ + "https://example.org/somewhere/terms-1.2-en.html", + "https://example.org/somewhere/privacy-1.2-en.html" + ] +} +``` + +Whenever a client submits a `POST $prefix/terms` request to an IS or IM, it +SHOULD update this account data section adding any the URLs of any additional +documents that the user agreed to to this list. + +### Terms Acceptance in the API + +Any request to any endpoint in the IS and IM APIs, with the exception of +`/_matrix/identity/api/v1` may return a `M_TERMS_NOT_SIGNED` errcode. This +indicates that the user must agree to (new) terms in order to use or continue +to use the service. + +The client uses the `GET $prefix/terms` endpoint to get the latest set of terms +that must be agreed to. It then cross-references this set of documents against +the `m.third_party_terms` account data and presents to the user any documents +that they have not already agreed to, along with UI for them to indicate their +agreement. Once the user has indicated their agreement, then, and only then, +must the client use the `POST $prefix/terms` API to signal to the server the +set of documents that the user has agreed to. + +If the server returns an `acceptance_token`, the client should include this +token in the `X-TERMS-TOKEN` HTTP header in all subsequent requests to an +endpoint on the API with the exception of `/_matrix/identity/api/v1`. + +Both making the `POST $prefix/terms` request and providing an `X-TERMS-TOKEN` +header signal that the user consents to the terms contained within the +corresponding documents. That is to say, if a client or user obtains an +acceptance token via means other than a response to the `POST $perfix/terms` +API, inclusion of the acceptance token in an `X-TERMS-TOKEN` header in a +request still constitutes agreement to the terms in the corresponding +documents. + +## Tradeoffs + +This introduces a different way of accepting terms from the client/server API +which uses User-Interactive Authentication. In the client/server API, the use +of UI auth allows terms acceptance to be integrated into the registration flow +in a simple and backwards-compatible way. Indtroducing the UI Auth mechanism +into these other APIs would add significant complexity, so this functionality +has been provided with simpler, dedicated endpoints. + +## Potential issues + +If the server does not authentcate users, some mechanism is required to track +users agreement to terms. The introduction of an extra HTTP header on all +requests adds overhead to every request and complexity to the client to add a +custom header. + + +## Security considerations + +The `acceptance_token` is, in effect, a cookie and could be used to identify +users of the service. Users of the Integration manager must be authenticated +anyway, so this is irrelevant for the IM API. It could allow an Identity Server +to identify users where it may otherwise not be able to do so (if a client was +careful to mask other identifying HTTP headers). Given most requests to the IS +API, by their nature, include 3pids which, even if hashed, will make users +easily identifiable, this probably does not add any significant concern. + +It is assumed that once servers publish a given version of a document at a +given URL, the contents of that URL will not change. This could be mitigated by +identifying documents based on a hash of their contents rather than their URLs. +Agreement to terms in the client/server API makes this assumption, so this +proposal aims to be consistent. + + +## Conclusion + +This proposal adds an error response to all endpoints on the API and a custom +HTTP header on all requests that is used to signal agreement to a set of terms +and conditions. The use of the header is only necessary if the server has no +other means of tracking acceptance of terms per-user. The IS API is not +authenticated so ISes will have no choice but to use the header. The IM API is +authenticated so IMs may either use the header or store acceptance per-user. + +A separate endpoint is specified with a GET request for retrieving the set +of terms required and a POST to indicate that the user consents to those +terms. From 32c7fc638dfb31eb05f484fc0c933cef7b604dc5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 20 Jun 2019 17:44:28 +0100 Subject: [PATCH 302/497] you have a number now --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 8c2ee75b..77d44e60 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -1,4 +1,4 @@ -# MSCXXXX: Terms of Service API for Identity Servers and Integration Managers +# MSC2140: Terms of Service API for Identity Servers and Integration Managers MSC1692 introduces a method for homeservers to require that users read and agree to certain documents before being permitted to use the service. This From cf48030d1fe7c3e180cd5a5617261fa508dbad59 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 20 Jun 2019 17:48:21 +0100 Subject: [PATCH 303/497] One more tradeoff --- proposals/2140-terms-of-service-2.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 77d44e60..bf322676 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -164,6 +164,14 @@ in a simple and backwards-compatible way. Indtroducing the UI Auth mechanism into these other APIs would add significant complexity, so this functionality has been provided with simpler, dedicated endpoints. +The `m.third_party_terms` section contains only URLs of the documents that +have been agreed to. This loses information like the name and version of +the document, but: + * It would be up to the clients to copy this information correctly into + account data. + * Having just the URLs makes it much easier for clients to make a list + of URLs and find documents not already agreed to. + ## Potential issues If the server does not authentcate users, some mechanism is required to track From 276e2b6843b9d27e7782222cf66d2c34f6c528f9 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 21 Jun 2019 09:14:24 +0100 Subject: [PATCH 304/497] Typo Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index bf322676..b678881a 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -90,7 +90,7 @@ client is operating in: users should not have to re-consent to documents if they change their client to a different language. The response MAY contain a `acceptance_token` which, if given, is an -opaque string that the client must store for user in subsequent requests +opaque string that the client must store for use in subsequent requests to any endpoint to the same server. If the server has stored the fact that the user has agreed to these terms, From d4ca0c237a7b744ffc05003b3a84b31f0b064367 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 21 Jun 2019 09:25:16 +0100 Subject: [PATCH 305/497] Specify ID grammar and add comma --- proposals/2140-terms-of-service-2.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index b678881a..dbdad334 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -99,12 +99,13 @@ The server may instead choose to supply an `acceptance_token`, for example if, as in the IS API, the user is unauthenticated and therefore the server is unable to store the fact a user has agreed to a set of terms. -The `acceptance_token` is opaque and it is up to the server how it computes it, -but the server must be able to given an `acceptance_token`, compute whether it -constitutes agreement to a given set of terms. For example, the simplest (but -most verbose) implemenation would be to make the `acceptance_token` the JSON -array of documents as provided in the request. A smarter implementation may be -a simple hash, or even cryptograhic hash if desired. +The `acceptance_token` is an opaque string contining characters +`[a-zA-Z0-9._-]`. It is up to the server how it computes it, but the server +must be able to, given an `acceptance_token`, compute whether it constitutes +agreement to a given set of terms. For example, the simplest (but most verbose) +implemenation would be to make the `acceptance_token` the JSON array of +documents as provided in the request. A smarter implementation may be a simple +hash, or even cryptograhic hash if desired. ### Third-Party Terms Account Data From 9ca3ccc81ce0ddfcf529b6c9445a2d11887707c4 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 21 Jun 2019 09:35:26 +0100 Subject: [PATCH 306/497] Add requirments section for de-duping between services. --- proposals/2140-terms-of-service-2.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index dbdad334..066a1184 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -20,6 +20,11 @@ Requirements for this proposal are: * A user should only have to agree to each version of each document once for their Matrix ID, ie. having agreed to a set of terms in one client, they should not have to agree to them again when using a different client. + * Documents should be de-duplicated between services. If two or more services + are hosted by the same organisation, the organistation should have the + option to give their users a single document that encompasses both services + (bearing in mind that the user must be able to opt-out of components of a + service whilst still being able to use the service without that component). ## Proposal From 1fea604ba9fc79071124181523e6800666194f3c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 21 Jun 2019 11:32:23 +0100 Subject: [PATCH 307/497] Don't define error message --- proposals/2134-identity-hash-lookup.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 43154d7c..8c7a0aca 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -108,12 +108,7 @@ Thus, a call to `/bulk_lookup` would look like the following: ``` If the pepper does not match the server's, the client should receive a `400 -M_INVALID_PARAM` with the error `Provided pepper does not match -'$server_pepper'`. If the algorithm does not match the server's, the client -should receive a `400 M_INVALID_PARAM` with the error `Provided algorithm does -not match '$server_algorithm'`. Clients should ensure they don't enter an -infinite loop if they receive these errors more than once even after changing -to the correct pepper and hash. +M_INVALID_PARAM`. No parameter changes will be made to /bind, but identity servers should keep a hashed value for each address it knows about in order to process lookups From e3b2ad38b5630c38dafad7e18178c6f0f9f98cfd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 21 Jun 2019 12:17:01 +0100 Subject: [PATCH 308/497] pepper -> lookup_pepper --- proposals/2134-identity-hash-lookup.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 8c7a0aca..f85df971 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -68,11 +68,14 @@ This endpoint takes no parameters, and simply returns the current pepper as a JS ``` { - "pepper": "matrixrocks", + "lookup_pepper": "matrixrocks", "algorithm": "sha256", } ``` +`lookup_pepper` was chosen in order to account for pepper values being returned +for other endpoints in the future. + Clients should request this endpoint every time before making a `/(bulk_)lookup`, to handle identity servers which may rotate their pepper values frequently. From c63edc7b97703383e0989eaea5c242124c8a9998 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 21 Jun 2019 14:12:50 +0100 Subject: [PATCH 309/497] Clean up wording around peppers and hashes --- proposals/2134-identity-hash-lookup.md | 97 +++++++++++++------------- 1 file changed, 47 insertions(+), 50 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index f85df971..686a3787 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -28,37 +28,15 @@ other endpoints): - `/_matrix/identity/v2/lookup` - `/_matrix/identity/v2/bulk_lookup` -`address` should no longer be in a plain-text format, but will now take a hash -value, and the resulting digest should be encoded in unpadded base64. For -example: +`address` MUST no longer be in a plain-text format, but rather will be a peppered hash +value, and the resulting digest MUST be encoded in unpadded base64. -```python -address = "user@example.org" -pepper = "matrix" -digest = hashlib.sha256((pepper + address).encode()).digest() -result_address = unpaddedbase64.encode_base64(digest) -print(result_address) -CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w -``` - -SHA-256 has been chosen as it is [currently used -elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) -in the Matrix protocol. Additionally a -[pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography)) must be prepended -to the data before hashing in order to serve as a weak defense against existing -rainbow tables. This pepper will be specified by the identity server in order -to prevent a single rainbow table being generated for all identity servers. As -time goes on, this algorithm may be changed provided a spec bump is performed. -Then, clients making a request to `/lookup` must use the hashing algorithm -defined in whichever version of the CS spec they and the IS have agreed to -speaking. - -Identity servers can specify their own peppers, which can be handy if a rainbow -table is released for their current one. Identity servers could also set a -timer for rotating this value to further impede rainbow table publishing. As -such, it must be possible for clients to be able to query what pepper an -identity server requires before sending it hashes. Thus a new endpoint must be -added: +Identity servers must specify their own hashing algorithms (from a list of +specified values) and peppers, which will be useful if a rainbow table is +released for their current one. Identity servers could also set a timer for +rotating the pepper value to further impede rainbow table publishing. As such, +it must be possible for clients to be able to query what pepper an identity +server requires before sending it hashes. A new endpoint must be added: ``` GET /_matrix/identity/v2/hash_details @@ -73,21 +51,39 @@ This endpoint takes no parameters, and simply returns the current pepper as a JS } ``` -`lookup_pepper` was chosen in order to account for pepper values being returned -for other endpoints in the future. +The name `lookup_pepper` was chosen in order to account for pepper values being +returned for other endpoints in the future. -Clients should request this endpoint every time before making a -`/(bulk_)lookup`, to handle identity servers which may rotate their pepper -values frequently. +Clients should request this endpoint each time before making a `/lookup` or +`/(bulk_)lookup` request, to handle identity servers which may rotate their +pepper values frequently. -In addition, the pepper and hashing algorithm the client used must be a request -body field for the new `/lookup` and `/bulk_lookup` endpoints, ensuring that -the client is using the right parameters. If it does not match what the server -has on file (which may be the case is it rotated right after the client's -request for it), then the client will know to query the hash details again -instead of assuming that no contacts are registered on that identity server. +An example of generating a hash using the above hash and pepper is as follows: -Thus, a call to `/bulk_lookup` would look like the following: +```python +address = "user@example.org" +pepper = "matrixrocks" +digest = hashlib.sha256((pepper + address).encode()).digest() +result_address = unpaddedbase64.encode_base64(digest) +print(result_address) +vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw +``` + +SHA-256 should be the first specified hash function. It has been chosen as it +is [currently used +elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) +in the Matrix protocol, and is reasonably secure as of 2019. + +When performing a lookup, the pepper and hashing algorithm the client used must +be part of the request body. If they do not match what the server has on file +(which may be the case if the pepper was rotated right after the client's +request for it), then the server can inform the client that they need to query +the hash details again, instead of just returning an empty response, which +clients would assume to mean that no contacts are registered on that identity +server. + +Thus, an example client request to `/bulk_lookup` would look like the +following: ``` { @@ -110,17 +106,19 @@ Thus, a call to `/bulk_lookup` would look like the following: } ``` -If the pepper does not match the server's, the client should receive a `400 +If the pepper does not match the server's, the server should return a `400 M_INVALID_PARAM`. No parameter changes will be made to /bind, but identity servers should keep a hashed value for each address it knows about in order to process lookups quicker. It is the recommendation that this is done during the act of binding. +Be wary that these hashes will need to be changed whenever the server's pepper +is rotated. ## Fallback considerations `v1` versions of these endpoints may be disabled at the discretion of the -implementation, and should return a HTTP 403 with a `M_FORBIDDEN` `errcode` if +implementation, and should return a HTTP 400 with a `M_DEPRECATED` `errcode` if so. If an identity server is too old and a HTTP 404 is received when accessing the @@ -128,13 +126,12 @@ If an identity server is too old and a HTTP 404 is received when accessing the clients should be aware that plain-text 3pids are required, and should ask for user consent accordingly. - ## Tradeoffs -* This approach means that the client now needs to calculate a hash by itself, but the belief - is that most languages provide a mechanism for doing so. -* There is a small cost incurred by doing hashes before requests, but this is outweighed by - the privacy implications of sending plain-text addresses. +* This approach means that the client now needs to calculate a hash by itself, + but the belief is that most languages provide a mechanism for doing so. +* There is a small cost incurred by performing hashes before requests, but this + is outweighed by the privacy implications of sending plain-text addresses. ## Potential issues @@ -151,7 +148,7 @@ address will have to be encoded when used as a parameter value. ## Other considered solutions Ideally identity servers would never receive plain-text addresses, however it -is necessary for the identity server to send an email/sms message during a +is necessary for the identity server to send email/sms messages during a bind, as it cannot trust a homeserver to do so as the homeserver may be lying. Additionally, only storing 3pid hashes at rest instead of the plain-text versions is impractical if the hashing algorithm ever needs to be changed. From 2383a55720374181d726bec475aba46943fa60a3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 21 Jun 2019 15:40:26 +0100 Subject: [PATCH 310/497] 404 for deprecated endpoint --- proposals/2134-identity-hash-lookup.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 686a3787..0f7fca27 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -118,8 +118,7 @@ is rotated. ## Fallback considerations `v1` versions of these endpoints may be disabled at the discretion of the -implementation, and should return a HTTP 400 with a `M_DEPRECATED` `errcode` if -so. +implementation, and should return a HTTP 404 if so. If an identity server is too old and a HTTP 404 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. However, From 53f025edfc6ecd126a5ce0fe42f02edcbc7d0bc6 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 21 Jun 2019 15:42:11 +0100 Subject: [PATCH 311/497] Specify optional pepper rotation period --- proposals/2134-identity-hash-lookup.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 0f7fca27..138646ff 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -34,9 +34,12 @@ value, and the resulting digest MUST be encoded in unpadded base64. Identity servers must specify their own hashing algorithms (from a list of specified values) and peppers, which will be useful if a rainbow table is released for their current one. Identity servers could also set a timer for -rotating the pepper value to further impede rainbow table publishing. As such, -it must be possible for clients to be able to query what pepper an identity -server requires before sending it hashes. A new endpoint must be added: +rotating the pepper value to further impede rainbow table publishing (the +recommended period is every 30m, which should be enough for a client to +complete the hashing of all of a user's contacts, but also be nowhere near as +long enough to create a sophisticated rainbow table). As such, it must be +possible for clients to be able to query what pepper an identity server +requires before sending it hashes. A new endpoint must be added: ``` GET /_matrix/identity/v2/hash_details From 21e93a123ede06ef47fd1391fab87efc250a7f18 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 21 Jun 2019 11:36:16 -0600 Subject: [PATCH 312/497] Naming and capitalization --- proposals/2134-identity-hash-lookup.md | 27 +++++++++++++------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 138646ff..dd2b8cc0 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -2,21 +2,21 @@ [Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been recently created in response to a security issue brought up by an independent -party. To summarise the issue, lookups (of matrix user ids) are performed using -non-hashed 3pids (third-party IDs) which means that the identity server can -identify and record every 3pid that the user wants to check, whether that +party. To summarise the issue, lookups (of Matrix user IDs) are performed using +non-hashed 3PIDs (third-party IDs) which means that the identity server can +identify and record every 3PID that the user wants to check, whether that address is already known by the identity server or not. -If the 3pid is hashed, the identity service could not determine the address +If the 3PID is hashed, the identity server could not determine the address unless it has already seen that address in plain-text during a previous call of the /bind mechanism. Note that in terms of privacy, this proposal does not stop an identity service -from mapping hashed 3pids to users, resulting in a social graph. However, the -identity of the 3pid will at least remain a mystery until /bind is used. +from mapping hashed 3PIDs to users, resulting in a social graph. However, the +identity of the 3PID will at least remain a mystery until /bind is used. This proposal thus calls for the Identity Service’s /lookup API to use hashed -3pids instead of their plain-text counterparts. +3PIDs instead of their plain-text counterparts. ## Proposal @@ -125,7 +125,7 @@ implementation, and should return a HTTP 404 if so. If an identity server is too old and a HTTP 404 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. However, -clients should be aware that plain-text 3pids are required, and should ask for +clients should be aware that plain-text 3PIDs are required, and should ask for user consent accordingly. ## Tradeoffs @@ -137,10 +137,10 @@ user consent accordingly. ## Potential issues -This proposal does not force an identity service to stop handling plain-text -requests, because a large amount of the matrix ecosystem relies upon this +This proposal does not force an identity server to stop handling plain-text +requests, because a large amount of the Matrix ecosystem relies upon this behavior. However, a conscious effort should be made by all users to use the -privacy respecting endpoints outlined above. Identity services may disallow use +privacy respecting endpoints outlined above. Identity servers may disallow use of the v1 endpoint. Unpadded base64 has been chosen to encode the value due to its ubiquitous @@ -152,7 +152,7 @@ address will have to be encoded when used as a parameter value. Ideally identity servers would never receive plain-text addresses, however it is necessary for the identity server to send email/sms messages during a bind, as it cannot trust a homeserver to do so as the homeserver may be lying. -Additionally, only storing 3pid hashes at rest instead of the plain-text +Additionally, only storing 3PID hashes at rest instead of the plain-text versions is impractical if the hashing algorithm ever needs to be changed. Bloom filters are an alternative method of providing private contact discovery, @@ -162,7 +162,7 @@ are explored in https://signal.org/blog/contact-discovery/ Signal's eventual solution of using SGX is considered impractical for a Matrix-style setup. While a bit out of scope for this MSC, there has been debate over preventing -3pids as being kept as plain-text on disk. The argument against this was that +3PIDs as being kept as plain-text on disk. The argument against this was that if the hashing algorithm (in this case SHA-256) was broken, we couldn't update the hashing algorithm without having the plaintext 3PIDs. Well @toml helpfully added that we could just take the old hashes and rehash them in the more secure @@ -176,4 +176,3 @@ This proposal outlines an effective method to stop bulk collection of user's contact lists and their social graphs without any disastrous side effects. All functionality which depends on the lookup service should continue to function unhindered by the use of hashes. - From e3ff80291f1607c7f2cf662da1a9f9c55c0cb429 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 24 Jun 2019 11:47:00 +0100 Subject: [PATCH 313/497] http err codes and hash wording fixes --- proposals/2134-identity-hash-lookup.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 138646ff..94e534fd 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -72,8 +72,8 @@ print(result_address) vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw ``` -SHA-256 should be the first specified hash function. It has been chosen as it -is [currently used +SHA-256 MUST be supported at a minimum. It has been chosen as it is [currently +used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) in the Matrix protocol, and is reasonably secure as of 2019. @@ -123,10 +123,10 @@ is rotated. `v1` versions of these endpoints may be disabled at the discretion of the implementation, and should return a HTTP 404 if so. -If an identity server is too old and a HTTP 404 is received when accessing the -`v2` endpoint, they should fallback to the `v1` endpoint instead. However, -clients should be aware that plain-text 3pids are required, and should ask for -user consent accordingly. +If an identity server is too old and a HTTP 404, 405 or 501 is received when +accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. +However, clients should be aware that plain-text 3pids are required, and should +ask for user consent accordingly. ## Tradeoffs From 02ac0f3b339b7df4db2180a7e690431762382335 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 24 Jun 2019 11:56:04 +0100 Subject: [PATCH 314/497] Give the user control! --- proposals/2134-identity-hash-lookup.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 9aa5fe7c..a2b6a26f 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -58,7 +58,7 @@ The name `lookup_pepper` was chosen in order to account for pepper values being returned for other endpoints in the future. Clients should request this endpoint each time before making a `/lookup` or -`/(bulk_)lookup` request, to handle identity servers which may rotate their +`/bulk_lookup` request, to handle identity servers which may rotate their pepper values frequently. An example of generating a hash using the above hash and pepper is as follows: @@ -125,8 +125,9 @@ implementation, and should return a HTTP 404 if so. If an identity server is too old and a HTTP 404, 405 or 501 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. -However, clients should be aware that plain-text 3pids are required, and should -ask for user consent accordingly. +However, clients should be aware that plain-text 3pids are required, and MUST +ask for user consent to send 3pids in plain-text, and be clear about where they +are being sent to. ## Tradeoffs From a63e4420eb9030d4afb5ac036c9617e5247e466e Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 24 Jun 2019 13:17:58 +0100 Subject: [PATCH 315/497] Linkify Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 066a1184..66efa708 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -1,6 +1,6 @@ # MSC2140: Terms of Service API for Identity Servers and Integration Managers -MSC1692 introduces a method for homeservers to require that users read and +[MSC1692](https://github.com/matrix-org/matrix-doc/issues/1692) introduces a method for homeservers to require that users read and agree to certain documents before being permitted to use the service. This proposal introduces a corresponding method that can be used with Identity Servers and Integration Managers. From 4ba9b2a59910ac14d69f92be34e8b123011ea6d5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 24 Jun 2019 13:18:41 +0100 Subject: [PATCH 316/497] perfix --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 66efa708..b43cadf2 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -156,7 +156,7 @@ endpoint on the API with the exception of `/_matrix/identity/api/v1`. Both making the `POST $prefix/terms` request and providing an `X-TERMS-TOKEN` header signal that the user consents to the terms contained within the corresponding documents. That is to say, if a client or user obtains an -acceptance token via means other than a response to the `POST $perfix/terms` +acceptance token via means other than a response to the `POST $prefix/terms` API, inclusion of the acceptance token in an `X-TERMS-TOKEN` header in a request still constitutes agreement to the terms in the corresponding documents. From 25558014580b411249ae3699d798dc9408997978 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 24 Jun 2019 14:56:48 +0100 Subject: [PATCH 317/497] m.third_party_terms -> m.accepted_terms as it will have the HS's terms too --- proposals/2140-terms-of-service-2.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index b43cadf2..8851eda3 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -34,7 +34,7 @@ API in question, ie. `/_matrix/identity/api/v1` for the IS API and This proposal introduces: * The `$prefix/terms` endpoint - * The `m.third_party_terms` section in account data + * The `m.accepted_terms` section in account data * The `X-TERMS-TOKEN` HTTP header ### Terms API @@ -114,12 +114,12 @@ hash, or even cryptograhic hash if desired. ### Third-Party Terms Account Data -This proposal also defines the `m.third_party_terms` section in User Account +This proposal also defines the `m.accepted_terms` section in User Account Data in the client/server API that clients SHOULD use to track what sets of terms the user has consented to. This has an array of URLs under the 'accepted' key to which the user has agreed to. -An `m.third_party_terms` section therefore resembles the following: +An `m.accepted_terms` section therefore resembles the following: ```json { @@ -143,7 +143,7 @@ to use the service. The client uses the `GET $prefix/terms` endpoint to get the latest set of terms that must be agreed to. It then cross-references this set of documents against -the `m.third_party_terms` account data and presents to the user any documents +the `m.accepted_terms` account data and presents to the user any documents that they have not already agreed to, along with UI for them to indicate their agreement. Once the user has indicated their agreement, then, and only then, must the client use the `POST $prefix/terms` API to signal to the server the @@ -170,7 +170,7 @@ in a simple and backwards-compatible way. Indtroducing the UI Auth mechanism into these other APIs would add significant complexity, so this functionality has been provided with simpler, dedicated endpoints. -The `m.third_party_terms` section contains only URLs of the documents that +The `m.accepted_terms` section contains only URLs of the documents that have been agreed to. This loses information like the name and version of the document, but: * It would be up to the clients to copy this information correctly into From 8ae47557c9a9e82e2333894be04583b7d968ca47 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 24 Jun 2019 15:22:19 +0100 Subject: [PATCH 318/497] s/Third Party/Accepted/ --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 8851eda3..f4d78a9d 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -112,7 +112,7 @@ implemenation would be to make the `acceptance_token` the JSON array of documents as provided in the request. A smarter implementation may be a simple hash, or even cryptograhic hash if desired. -### Third-Party Terms Account Data +### Accepted Terms Account Data This proposal also defines the `m.accepted_terms` section in User Account Data in the client/server API that clients SHOULD use to track what sets of From abb407145abe1a51f1ba4d4b7c07e000039791e3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 24 Jun 2019 15:30:19 +0100 Subject: [PATCH 319/497] HS docs must be added too also, unbind must not error when called by HSes and proxy terms token --- proposals/2140-terms-of-service-2.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index f4d78a9d..6c5bb6a5 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -130,16 +130,19 @@ An `m.accepted_terms` section therefore resembles the following: } ``` -Whenever a client submits a `POST $prefix/terms` request to an IS or IM, it -SHOULD update this account data section adding any the URLs of any additional -documents that the user agreed to to this list. +Whenever a client submits a `POST $prefix/terms` request to an IS or IM or +completes an `m.terms` flow on the HS, it SHOULD update this account data +section adding any the URLs of any additional documents that the user agreed to +to this list. ### Terms Acceptance in the API Any request to any endpoint in the IS and IM APIs, with the exception of `/_matrix/identity/api/v1` may return a `M_TERMS_NOT_SIGNED` errcode. This indicates that the user must agree to (new) terms in order to use or continue -to use the service. +to use the service. The `_matrix/identity/api/v1/3pid/unbind` must also not +return the `M_TERMS_NOT_SIGNED` if the request has a valid signature from a +Homeserver. The client uses the `GET $prefix/terms` endpoint to get the latest set of terms that must be agreed to. It then cross-references this set of documents against @@ -153,6 +156,11 @@ If the server returns an `acceptance_token`, the client should include this token in the `X-TERMS-TOKEN` HTTP header in all subsequent requests to an endpoint on the API with the exception of `/_matrix/identity/api/v1`. +The client must also include the X-TERMS-TOKEN on any request to the Homeserver +where it specifies an Identity Server to be used by the Homeserver. Homeservers +must read this header from the request headers of any such endpoint and add it +to the request headers of any request it makes to the Identity Server. + Both making the `POST $prefix/terms` request and providing an `X-TERMS-TOKEN` header signal that the user consents to the terms contained within the corresponding documents. That is to say, if a client or user obtains an From ee10576d609081cca217282692b0c002e660bfab Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 24 Jun 2019 15:43:19 +0100 Subject: [PATCH 320/497] Update with feedback --- proposals/2134-identity-hash-lookup.md | 27 ++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index a2b6a26f..2240b640 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -45,7 +45,8 @@ requires before sending it hashes. A new endpoint must be added: GET /_matrix/identity/v2/hash_details ``` -This endpoint takes no parameters, and simply returns the current pepper as a JSON object: +This endpoint takes no parameters, and simply returns supported hash algorithms +and pepper as a JSON object: ``` { @@ -72,8 +73,8 @@ print(result_address) vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw ``` -SHA-256 MUST be supported at a minimum. It has been chosen as it is [currently -used +SHA-256 MUST be supported by both servers and clients at a minimum. It has been +chosen as it is [currently used elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) in the Matrix protocol, and is reasonably secure as of 2019. @@ -104,7 +105,7 @@ following: "BJaLI0RrLFDMbsk0eEp5BMsYDYzvOzDneQP/9NTemYA" ] ], - "pepper": "matrixrocks", + "lookup_pepper": "matrixrocks", "algorithm": "sha256" } ``` @@ -144,8 +145,8 @@ behavior. However, a conscious effort should be made by all users to use the privacy respecting endpoints outlined above. Identity servers may disallow use of the v1 endpoint. -Unpadded base64 has been chosen to encode the value due to its ubiquitous -support in many languages, however it does mean that special characters in the +Unpadded base64 has been chosen to encode the value due to use in many other +portions of the spec. However, it does mean that special characters in the address will have to be encoded when used as a parameter value. ## Other considered solutions @@ -160,16 +161,22 @@ Bloom filters are an alternative method of providing private contact discovery, however does not scale well due to clients needing to download a large filter that needs updating every time a new bind is made. Further considered solutions are explored in https://signal.org/blog/contact-discovery/ Signal's eventual -solution of using SGX is considered impractical for a Matrix-style setup. +solution of using Software Guard Extensions (detailed in +https://signal.org/blog/private-contact-discovery/) is considered impractical +for a federated network, as it requires specialized hardware. While a bit out of scope for this MSC, there has been debate over preventing 3PIDs as being kept as plain-text on disk. The argument against this was that if the hashing algorithm (in this case SHA-256) was broken, we couldn't update -the hashing algorithm without having the plaintext 3PIDs. Well @toml helpfully +the hashing algorithm without having the plaintext 3PIDs. @lampholder helpfully added that we could just take the old hashes and rehash them in the more secure hashing algorithm, thus transforming the hash from SHA-256 to -SHA-256+SomeBetterAlg. This may spur on an MSC in the future that supports -this, unless it is just an implementation detail. +SHA-256+SomeBetterAlg. However @erikjohnston then pointed out that if +`BrokenAlgo(a) == BrokenAlgo(b)` then `SuperGreatHash(BrokenAlgo(a)) == +SuperGreatHash(BrokenAlgo(b))`, so all you'd need to do is find a match in the +broken algo, and you'd break the new algorithm as well. This means that you +would need the plaintext 3pids to encode a new hash, and thus storing them +hashed on disk is not possible. ## Conclusion From 36a35a33cc975c3a594048cb8cd94d09f36d0f79 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 24 Jun 2019 16:59:58 +0100 Subject: [PATCH 321/497] Clarify how the spec defines hashing algs --- proposals/2134-identity-hash-lookup.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 2240b640..a2b3f157 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -46,12 +46,12 @@ GET /_matrix/identity/v2/hash_details ``` This endpoint takes no parameters, and simply returns supported hash algorithms -and pepper as a JSON object: +and peppers as a JSON object: ``` { "lookup_pepper": "matrixrocks", - "algorithm": "sha256", + "algorithms": ["sha256"], } ``` @@ -60,9 +60,11 @@ returned for other endpoints in the future. Clients should request this endpoint each time before making a `/lookup` or `/bulk_lookup` request, to handle identity servers which may rotate their -pepper values frequently. +pepper values frequently. Clients must choose one of the given hash algorithms +to encrypt the 3pid during lookup. -An example of generating a hash using the above hash and pepper is as follows: +An example of generating a hash using SHA-256 and the provided pepper is as +follows: ```python address = "user@example.org" @@ -73,10 +75,12 @@ print(result_address) vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw ``` -SHA-256 MUST be supported by both servers and clients at a minimum. It has been -chosen as it is [currently used -elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events) -in the Matrix protocol, and is reasonably secure as of 2019. +Possible hashing algorithms will be defined in the Matrix specification, and an +Identity Server can choose to implement one or all of them. Later versions of +the specification may deprecate algorithms when necessary. Currently the only +listed hashing algorithm is SHA-256 as defined by [RFC +4634](https://tools.ietf.org/html/rfc4634) and Identity Servers and clients +MUST agree to its use with the string `sha256`. When performing a lookup, the pepper and hashing algorithm the client used must be part of the request body. If they do not match what the server has on file From 0a4c83ddb9107ed5f8420dfd0df09bc8b4025d19 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 24 Jun 2019 17:54:23 +0100 Subject: [PATCH 322/497] no plural. 3pid -> 3PID --- proposals/2134-identity-hash-lookup.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index a2b3f157..f8389e44 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -45,8 +45,8 @@ requires before sending it hashes. A new endpoint must be added: GET /_matrix/identity/v2/hash_details ``` -This endpoint takes no parameters, and simply returns supported hash algorithms -and peppers as a JSON object: +This endpoint takes no parameters, and simply returns any supported hash +algorithms and pepper as a JSON object: ``` { @@ -61,7 +61,7 @@ returned for other endpoints in the future. Clients should request this endpoint each time before making a `/lookup` or `/bulk_lookup` request, to handle identity servers which may rotate their pepper values frequently. Clients must choose one of the given hash algorithms -to encrypt the 3pid during lookup. +to encrypt the 3PID during lookup. An example of generating a hash using SHA-256 and the provided pepper is as follows: @@ -130,8 +130,8 @@ implementation, and should return a HTTP 404 if so. If an identity server is too old and a HTTP 404, 405 or 501 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. -However, clients should be aware that plain-text 3pids are required, and MUST -ask for user consent to send 3pids in plain-text, and be clear about where they +However, clients should be aware that plain-text 3PIDs are required, and MUST +ask for user consent to send 3PIDs in plain-text, and be clear about where they are being sent to. ## Tradeoffs @@ -179,7 +179,7 @@ SHA-256+SomeBetterAlg. However @erikjohnston then pointed out that if `BrokenAlgo(a) == BrokenAlgo(b)` then `SuperGreatHash(BrokenAlgo(a)) == SuperGreatHash(BrokenAlgo(b))`, so all you'd need to do is find a match in the broken algo, and you'd break the new algorithm as well. This means that you -would need the plaintext 3pids to encode a new hash, and thus storing them +would need the plaintext 3PIDs to encode a new hash, and thus storing them hashed on disk is not possible. ## Conclusion From fae6883cc03341b5eb2c417abd013201875c2279 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 25 Jun 2019 10:18:11 +0100 Subject: [PATCH 323/497] Update with review comments --- proposals/2134-identity-hash-lookup.md | 34 +++++++++++++------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index f8389e44..ccbc38b9 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -11,7 +11,7 @@ If the 3PID is hashed, the identity server could not determine the address unless it has already seen that address in plain-text during a previous call of the /bind mechanism. -Note that in terms of privacy, this proposal does not stop an identity service +Note that in terms of privacy, this proposal does not stop an identity server from mapping hashed 3PIDs to users, resulting in a social graph. However, the identity of the 3PID will at least remain a mystery until /bind is used. @@ -32,13 +32,13 @@ other endpoints): value, and the resulting digest MUST be encoded in unpadded base64. Identity servers must specify their own hashing algorithms (from a list of -specified values) and peppers, which will be useful if a rainbow table is +specified values) and pepper, which will be useful if a rainbow table is released for their current one. Identity servers could also set a timer for rotating the pepper value to further impede rainbow table publishing (the -recommended period is every 30m, which should be enough for a client to +recommended period is every 30 minutes, which should be enough for a client to complete the hashing of all of a user's contacts, but also be nowhere near as long enough to create a sophisticated rainbow table). As such, it must be -possible for clients to be able to query what pepper an identity server +possible for clients to be able to query what pepper the identity server requires before sending it hashes. A new endpoint must be added: ``` @@ -80,12 +80,16 @@ Identity Server can choose to implement one or all of them. Later versions of the specification may deprecate algorithms when necessary. Currently the only listed hashing algorithm is SHA-256 as defined by [RFC 4634](https://tools.ietf.org/html/rfc4634) and Identity Servers and clients -MUST agree to its use with the string `sha256`. +MUST agree to its use with the string `sha256`. SHA-256 was chosen as it is +currently used throughout the Matrix spec, as well as its properties of being +quick to hash. While this reduces the resources necessary to generate a rainbow +table for attackers, a fast hash is necessary if particularly slow mobile +clients are going to be hashing thousands of contacts. When performing a lookup, the pepper and hashing algorithm the client used must be part of the request body. If they do not match what the server has on file (which may be the case if the pepper was rotated right after the client's -request for it), then the server can inform the client that they need to query +request for it), then the server must inform the client that they need to query the hash details again, instead of just returning an empty response, which clients would assume to mean that no contacts are registered on that identity server. @@ -117,20 +121,16 @@ following: If the pepper does not match the server's, the server should return a `400 M_INVALID_PARAM`. -No parameter changes will be made to /bind, but identity servers should keep a -hashed value for each address it knows about in order to process lookups -quicker. It is the recommendation that this is done during the act of binding. -Be wary that these hashes will need to be changed whenever the server's pepper -is rotated. +No parameter changes will be made to /bind. ## Fallback considerations `v1` versions of these endpoints may be disabled at the discretion of the -implementation, and should return a HTTP 404 if so. +implementation, and should return a HTTP 403 if so. If an identity server is too old and a HTTP 404, 405 or 501 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. -However, clients should be aware that plain-text 3PIDs are required, and MUST +However, clients should be aware that plain-text 3PIDs are required, and SHOULD ask for user consent to send 3PIDs in plain-text, and be clear about where they are being sent to. @@ -147,11 +147,10 @@ This proposal does not force an identity server to stop handling plain-text requests, because a large amount of the Matrix ecosystem relies upon this behavior. However, a conscious effort should be made by all users to use the privacy respecting endpoints outlined above. Identity servers may disallow use -of the v1 endpoint. +of the v1 endpoint, as per above. Unpadded base64 has been chosen to encode the value due to use in many other -portions of the spec. However, it does mean that special characters in the -address will have to be encoded when used as a parameter value. +portions of the spec. ## Other considered solutions @@ -180,7 +179,8 @@ SHA-256+SomeBetterAlg. However @erikjohnston then pointed out that if SuperGreatHash(BrokenAlgo(b))`, so all you'd need to do is find a match in the broken algo, and you'd break the new algorithm as well. This means that you would need the plaintext 3PIDs to encode a new hash, and thus storing them -hashed on disk is not possible. +hashed on disk would require a transition period where 3pids were reuploaded in +a strong hash variant. ## Conclusion From f951f312e1ac610b4bcf2d3af1422633d0e13a12 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 25 Jun 2019 10:30:29 +0100 Subject: [PATCH 324/497] Fix terrible wording --- proposals/2134-identity-hash-lookup.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index ccbc38b9..b9a53cb0 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -160,11 +160,11 @@ bind, as it cannot trust a homeserver to do so as the homeserver may be lying. Additionally, only storing 3PID hashes at rest instead of the plain-text versions is impractical if the hashing algorithm ever needs to be changed. -Bloom filters are an alternative method of providing private contact discovery, -however does not scale well due to clients needing to download a large filter -that needs updating every time a new bind is made. Further considered solutions -are explored in https://signal.org/blog/contact-discovery/ Signal's eventual -solution of using Software Guard Extensions (detailed in +Bloom filters are an alternative method of providing private contact discovery. +However, they do not scale well due to requiring clients to download a large +filter that needs updating every time a new bind is made. Further considered +solutions are explored in https://signal.org/blog/contact-discovery/. Signal's +eventual solution of using Software Guard Extensions (detailed in https://signal.org/blog/private-contact-discovery/) is considered impractical for a federated network, as it requires specialized hardware. From 96e43aaf45469998cfa65f097b099fbac5042b14 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 25 Jun 2019 10:37:45 +0100 Subject: [PATCH 325/497] Define what characters lookup_pepper can consist of --- proposals/2134-identity-hash-lookup.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index b9a53cb0..34e9b0a6 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -56,7 +56,8 @@ algorithms and pepper as a JSON object: ``` The name `lookup_pepper` was chosen in order to account for pepper values being -returned for other endpoints in the future. +returned for other endpoints in the future. The contents of `lookup_pepper` +MUST match the regular expression `[a-zA-Z0-9]*`. Clients should request this endpoint each time before making a `/lookup` or `/bulk_lookup` request, to handle identity servers which may rotate their From 2c09580e2798f0cd51590174040df6bde2b996a4 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 25 Jun 2019 11:14:35 +0100 Subject: [PATCH 326/497] line wrap --- proposals/2140-terms-of-service-2.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 6c5bb6a5..42a1ea38 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -1,9 +1,10 @@ # MSC2140: Terms of Service API for Identity Servers and Integration Managers -[MSC1692](https://github.com/matrix-org/matrix-doc/issues/1692) introduces a method for homeservers to require that users read and -agree to certain documents before being permitted to use the service. This -proposal introduces a corresponding method that can be used with Identity -Servers and Integration Managers. +[MSC1692](https://github.com/matrix-org/matrix-doc/issues/1692) introduces a +method for homeservers to require that users read and agree to certain +documents before being permitted to use the service. This proposal introduces a +corresponding method that can be used with Identity Servers and Integration +Managers. The challenge here is that Identity Servers do not require any kind of user login to access the service and so are unable to track what users have agreed From 6f374dc981b6330d59cf5f45022f0176ce19cf16 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 25 Jun 2019 14:58:15 +0100 Subject: [PATCH 327/497] Re-write for OpenID auth --- proposals/2140-terms-of-service-2.md | 143 +++++++++++++++------------ 1 file changed, 80 insertions(+), 63 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 42a1ea38..7b6dd4dc 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -6,16 +6,15 @@ documents before being permitted to use the service. This proposal introduces a corresponding method that can be used with Identity Servers and Integration Managers. -The challenge here is that Identity Servers do not require any kind of user -login to access the service and so are unable to track what users have agreed -to what terms in the way that Homeservers do. We thereforce cannot re-use the -same method for Identity Servers without fundamentally changing the Identity -Service API. - Requirements for this proposal are: * ISs and IMs should be able to give multiple documents a user must agree to abide by * Each document shoud be versioned + * ISes and IMs must, for each request that they handle, know that the user + making the request has agreed to their data being used. This need not be + absolute proof (we will always have to trust that the client actually + showed the document to the user) but it must be reasonably demonstrable that + the user has given informed consent for the client to use that service. * ISs and IMs must be able to prevent users from using the service if they have not provided agreement. * A user should only have to agree to each version of each document once for @@ -27,16 +26,61 @@ Requirements for this proposal are: (bearing in mind that the user must be able to opt-out of components of a service whilst still being able to use the service without that component). +Identity Servers do not currently require any kind of user login to access the +service and so are unable to track what users have agreed to what terms in the +way that Homeservers do. + ## Proposal Throuhgout this proposal, $prefix will be used to refer to the prefix of the -API in question, ie. `/_matrix/identity/api/v1` for the IS API and +API in question, ie. `/_matrix/identity/v2` for the IS API and `/_matrix/integrations/v1` for the IM API. +Note the removal of the `/api` prefix and migration to v2 in the IS API +following convention from +[MSC2134](https://github.com/matrix-org/matrix-doc/issues/2134). + This proposal introduces: * The `$prefix/terms` endpoint * The `m.accepted_terms` section in account data - * The `X-TERMS-TOKEN` HTTP header + +This proposal relies on both Integration Managers and Identity Servers being +able to identity users by their mxid and store the fact that a given mxid has +indicated that they accept the terms given. Integration Managers already +identity users in this way by authenticating them using the OpenID endpoint on +the Homeserver. This proposal introduces the same mechanism to Identity Servers +and adds authentication to accross the Identity Service API. + +### IS API Authentication + +All current endpoints within `/_matrix/identity/api/v1/` will be duplicated +into `/_matrix/identity/v2`. + +Any request to any endpoint within `/_matrix/identity/v2`, with the exception of +`/_matrix/identity/v2` and the new `/_matrix/identity/v2/account/register` may +return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. This +indicates that the user must authenticate with OpenID and supply a valid +`access_token`. + +The existing endpoints under `/_matrix/identity/api/v1/` continue to be unauthenticated. +ISes may support the old v1 API for as long as they wish. Clients must update to use +the v2 API as soon as possible. + +OpenID authentication in the IS API will work the same as in the Integration Manager +API, as specified in [MSC1961](https://github.com/matrix-org/matrix-doc/issues/1961). + +### IS Register API + +The following new APIs will be introduced to support OpenID auth as per +[MSC1961](https://github.com/matrix-org/matrix-doc/issues/1961): + + * `/_matrix/identity/v2/account/register` + * `/_matrix/identity/v2/account` + * `/_matrix/identity/v2/account/logout` + +Note again the removal of the `/api` prefix and migration to v2 following +convention from +[MSC2134](https://github.com/matrix-org/matrix-doc/issues/2134). ### Terms API @@ -71,7 +115,7 @@ that the URL contains the version number of the document. The name and version keys, however, are used only to provide a human-readable description of the document to the user. -In the IM API, the client should provide authentication for this endpoint. +The client should provide authentication for this endpoint. #### `POST $prefix/terms`: Requests to this endpoint have a single key, `user_accepts` whose value is @@ -84,7 +128,7 @@ the user has agreed to: } ``` -In the IM API, the client should provide authentication for this endpoint. +The client should provide authentication for this endpoint. The clients MUST include the correct URL for the language of the document that was presented to the user and they agreed to. How servers store or serialise @@ -95,24 +139,6 @@ any one language of each document as sufficient, regardless of what language a client is operating in: users should not have to re-consent to documents if they change their client to a different language. -The response MAY contain a `acceptance_token` which, if given, is an -opaque string that the client must store for use in subsequent requests -to any endpoint to the same server. - -If the server has stored the fact that the user has agreed to these terms, -(which implies the user is authenticated) it can supply no `acceptance_token`. -The server may instead choose to supply an `acceptance_token`, for example if, -as in the IS API, the user is unauthenticated and therefore the server is -unable to store the fact a user has agreed to a set of terms. - -The `acceptance_token` is an opaque string contining characters -`[a-zA-Z0-9._-]`. It is up to the server how it computes it, but the server -must be able to, given an `acceptance_token`, compute whether it constitutes -agreement to a given set of terms. For example, the simplest (but most verbose) -implemenation would be to make the `acceptance_token` the JSON array of -documents as provided in the request. A smarter implementation may be a simple -hash, or even cryptograhic hash if desired. - ### Accepted Terms Account Data This proposal also defines the `m.accepted_terms` section in User Account @@ -138,12 +164,17 @@ to this list. ### Terms Acceptance in the API -Any request to any endpoint in the IS and IM APIs, with the exception of -`/_matrix/identity/api/v1` may return a `M_TERMS_NOT_SIGNED` errcode. This -indicates that the user must agree to (new) terms in order to use or continue -to use the service. The `_matrix/identity/api/v1/3pid/unbind` must also not -return the `M_TERMS_NOT_SIGNED` if the request has a valid signature from a -Homeserver. +Any request to any endpoint in the IM API, and the `_matrix/identity/v2/` +namespace of the IS API, with the exception of `/_matrix/identity/v2` itself, +may return: + + * `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that + the user must authenticate with OpenID and supply a valid `access_token`. + * `M_TERMS_NOT_SIGNED` errcode. This indicates that the user must agree to + (new) terms in order to use or continue to use the service. + +The `_matrix/identity/v2/3pid/unbind` must not return either of these +errors if the request has a valid signature from a Homeserver. The client uses the `GET $prefix/terms` endpoint to get the latest set of terms that must be agreed to. It then cross-references this set of documents against @@ -153,25 +184,17 @@ agreement. Once the user has indicated their agreement, then, and only then, must the client use the `POST $prefix/terms` API to signal to the server the set of documents that the user has agreed to. -If the server returns an `acceptance_token`, the client should include this -token in the `X-TERMS-TOKEN` HTTP header in all subsequent requests to an -endpoint on the API with the exception of `/_matrix/identity/api/v1`. - -The client must also include the X-TERMS-TOKEN on any request to the Homeserver -where it specifies an Identity Server to be used by the Homeserver. Homeservers -must read this header from the request headers of any such endpoint and add it -to the request headers of any request it makes to the Identity Server. - -Both making the `POST $prefix/terms` request and providing an `X-TERMS-TOKEN` -header signal that the user consents to the terms contained within the -corresponding documents. That is to say, if a client or user obtains an -acceptance token via means other than a response to the `POST $prefix/terms` -API, inclusion of the acceptance token in an `X-TERMS-TOKEN` header in a -request still constitutes agreement to the terms in the corresponding -documents. - ## Tradeoffs +The Identity Service API previously did not require authentication, and OpenID +is reasonably complex, adding a significant burden to both clients and servers. +A custom HTTP Header was also considered that could be added to assert that the +client agrees to a particular set of terms. We decided against this in favour +of re-using existing primitives that already exist in the Matrix ecosystem. +Custom HTTP Headers are not used anywhere else within Matrix. This also gives a +very simple and natural way for ISes to enforce that users may only bind 3pids +to their own mxids. + This introduces a different way of accepting terms from the client/server API which uses User-Interactive Authentication. In the client/server API, the use of UI auth allows terms acceptance to be integrated into the registration flow @@ -189,21 +212,15 @@ the document, but: ## Potential issues -If the server does not authentcate users, some mechanism is required to track -users agreement to terms. The introduction of an extra HTTP header on all -requests adds overhead to every request and complexity to the client to add a -custom header. - +This change is not backwards compatible: clients implementing older versions of +the specification will expect to be able to access all IS API endpoints without +authentication. Care should be taken to manage the rollout of authentication +on IS APIs. ## Security considerations -The `acceptance_token` is, in effect, a cookie and could be used to identify -users of the service. Users of the Integration manager must be authenticated -anyway, so this is irrelevant for the IM API. It could allow an Identity Server -to identify users where it may otherwise not be able to do so (if a client was -careful to mask other identifying HTTP headers). Given most requests to the IS -API, by their nature, include 3pids which, even if hashed, will make users -easily identifiable, this probably does not add any significant concern. +Requiring authentication on the IS API means it will no longer be possible to +use it anonymously. It is assumed that once servers publish a given version of a document at a given URL, the contents of that URL will not change. This could be mitigated by From 4f83cc1c244b78d9c34abde492116f4dcdae4047 Mon Sep 17 00:00:00 2001 From: Sorunome Date: Tue, 25 Jun 2019 16:19:29 +0200 Subject: [PATCH 328/497] moved client spoiler conversion to potential issues --- proposals/2010-spoilers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index 40feed29..fc470fcc 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -52,10 +52,6 @@ however that wouldn't be HTML-compliant. Instead of limiting the proposed `data-mx-spoiler` attribute only to the ``-tag it could be added to all tags, however it might make implementations for clients more complicated. -Clients would have to come up with a way how to input spoilers. This could be done, for example, -by adding a custom markdown tag (like discord does), so that you do `Text ||spoiler||`, however -that doesn't take a spoiler reason into account. - ## Potential issues Depending on context it might make sense to put other events, such as `m.image`, into spoilers, too. This MSC doesn't address that at all. Using @@ -63,5 +59,9 @@ too. This MSC doesn't address that at all. Using This MSC doesn't take HTML block elements into account. +Clients would have to come up with a way how to input spoilers. This could be done, for example, +by adding a custom markdown tag (like discord does), so that you do `Text ||spoiler||`, however +that doesn't take a spoiler reason into account. + ## Security considerations The spoiler reason needs to be properly escaped when rendered. From 0dae2d5812d0d22350c9237b84634e81e0306b24 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 25 Jun 2019 15:52:55 +0100 Subject: [PATCH 329/497] GET terms must be unauthed. Detail process for new auth (don't register until consent given). Specifically mention the authentication header. --- proposals/2140-terms-of-service-2.md | 55 +++++++++++++++++++++------- 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 7b6dd4dc..67e6a2eb 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -56,11 +56,15 @@ and adds authentication to accross the Identity Service API. All current endpoints within `/_matrix/identity/api/v1/` will be duplicated into `/_matrix/identity/v2`. -Any request to any endpoint within `/_matrix/identity/v2`, with the exception of -`/_matrix/identity/v2` and the new `/_matrix/identity/v2/account/register` may -return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. This -indicates that the user must authenticate with OpenID and supply a valid -`access_token`. +Any request to any endpoint within `/_matrix/identity/v2`, with the exception +of `/_matrix/identity/v2` and the new `/_matrix/identity/v2/account/register` +and `GET /_matrix/identity/v2/terms` may return an error with `M_UNAUTHORIZED` +errcode with HTTP status code 401. This indicates that the user must +authenticate with OpenID and supply a valid `access_token`. + +These endpoints require authentication by the client supplying an access token +either via an `Authorization` header with a `Bearer` token or an `access_token` +query parameter. The existing endpoints under `/_matrix/identity/api/v1/` continue to be unauthenticated. ISes may support the old v1 API for as long as they wish. Clients must update to use @@ -115,7 +119,7 @@ that the URL contains the version number of the document. The name and version keys, however, are used only to provide a human-readable description of the document to the user. -The client should provide authentication for this endpoint. +This endpoint does *not* require authentication. #### `POST $prefix/terms`: Requests to this endpoint have a single key, `user_accepts` whose value is @@ -128,7 +132,7 @@ the user has agreed to: } ``` -The client should provide authentication for this endpoint. +This endpoint requires authentication. The clients MUST include the correct URL for the language of the document that was presented to the user and they agreed to. How servers store or serialise @@ -164,6 +168,22 @@ to this list. ### Terms Acceptance in the API +Before any requests are made to an Identity Server or Integration Manager, +the client must use the `GET $prefix/terms` endpoint to fetch the set of +documents that the user must agree to in order to use the service. + +It then cross-references this set of documents against the `m.accepted_terms` +account data and presents to the user any documents that they have not already +agreed to, along with UI for them to indicate their agreement. Once the user +has indicated their agreement, it adds these URLs to `m.accepted_terms` account +data. Once this has succeeded, then, and only then, must the client perform +OpenID authentication, getting a token from the Homeserver and submitting this +to the service using the `register` endpoint. + +Having done this, if the user agreed to any new documents, it performs a `POST +$prefix/terms` request to signal to the server the set of documents that the +user has agreed to. + Any request to any endpoint in the IM API, and the `_matrix/identity/v2/` namespace of the IS API, with the exception of `/_matrix/identity/v2` itself, may return: @@ -176,13 +196,20 @@ may return: The `_matrix/identity/v2/3pid/unbind` must not return either of these errors if the request has a valid signature from a Homeserver. -The client uses the `GET $prefix/terms` endpoint to get the latest set of terms -that must be agreed to. It then cross-references this set of documents against -the `m.accepted_terms` account data and presents to the user any documents -that they have not already agreed to, along with UI for them to indicate their -agreement. Once the user has indicated their agreement, then, and only then, -must the client use the `POST $prefix/terms` API to signal to the server the -set of documents that the user has agreed to. +In summary, the process for using a service that has not previously been used +in the current login sessions is: + + * `GET $prefix/terms` + * Compare result with `m.accepted_terms` account data, get set of documents + pending agreement + * If non-empty, show this set of documents to the user and wait for the user + to indicate their agreement. + * Add the newly agreed documents to `m.accepted_terms` + * On success, or if there were no documents pending agreement, get an OpenID + token from the Homeserver and submit this token to the `register` endpoint. + Store the resulting access token. + * If the set of documents pending agreement was non-empty, Perform a + `POST $prefix/terms` request to the servcie with these documents. ## Tradeoffs From 4997abc4b7cd36722003be98f7efae8d37f3f476 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 25 Jun 2019 16:47:10 +0100 Subject: [PATCH 330/497] as as -> as --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 9b16abc3..39a2fd3d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1314,7 +1314,7 @@ to keep moving forwards. Filtering --------- -Filters can be created on the server and can be passed as as a parameter to APIs +Filters can be created on the server and can be passed as a parameter to APIs which return events. These filters alter the data returned from those APIs. Not all APIs accept filters. From e88a074c9ff9f2fa2f9c1aa129a0376a0bc5c617 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 25 Jun 2019 17:02:39 +0100 Subject: [PATCH 331/497] Add changelog --- changelogs/client_server/newsfragments/2148.misc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2148.misc diff --git a/changelogs/client_server/newsfragments/2148.misc b/changelogs/client_server/newsfragments/2148.misc new file mode 100644 index 00000000..d5514131 --- /dev/null +++ b/changelogs/client_server/newsfragments/2148.misc @@ -0,0 +1 @@ +Fix a small duplicated "as". From 9e0d8b9cb29807d2e16b2332dc59f7b0aaad1fb2 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 25 Jun 2019 17:17:39 +0100 Subject: [PATCH 332/497] Use M_CONSENT_NOT_GIVEN No idea where I got the other one from: we already have one in the spec, so use it. --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 67e6a2eb..b0b15b07 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -190,7 +190,7 @@ may return: * `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that the user must authenticate with OpenID and supply a valid `access_token`. - * `M_TERMS_NOT_SIGNED` errcode. This indicates that the user must agree to + * `M_CONSENT_NOT_GIVEN` errcode. This indicates that the user must agree to (new) terms in order to use or continue to use the service. The `_matrix/identity/v2/3pid/unbind` must not return either of these From df88b13ce13690fb46e8a587d81f4011019c0acc Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 25 Jun 2019 18:15:02 +0100 Subject: [PATCH 333/497] Update proposals/2134-identity-hash-lookup.md Co-Authored-By: Hubert Chathi --- proposals/2134-identity-hash-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 34e9b0a6..ba1d974e 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -29,7 +29,7 @@ other endpoints): - `/_matrix/identity/v2/bulk_lookup` `address` MUST no longer be in a plain-text format, but rather will be a peppered hash -value, and the resulting digest MUST be encoded in unpadded base64. +value encoded in unpadded base64. Identity servers must specify their own hashing algorithms (from a list of specified values) and pepper, which will be useful if a rainbow table is From dfb37fcce1932fed58700a21b336687bba061a1e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 25 Jun 2019 18:55:18 +0100 Subject: [PATCH 334/497] update with feedback --- proposals/2134-identity-hash-lookup.md | 30 ++++++++++++-------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index ba1d974e..94cd4e48 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -31,15 +31,11 @@ other endpoints): `address` MUST no longer be in a plain-text format, but rather will be a peppered hash value encoded in unpadded base64. -Identity servers must specify their own hashing algorithms (from a list of -specified values) and pepper, which will be useful if a rainbow table is -released for their current one. Identity servers could also set a timer for -rotating the pepper value to further impede rainbow table publishing (the -recommended period is every 30 minutes, which should be enough for a client to -complete the hashing of all of a user's contacts, but also be nowhere near as -long enough to create a sophisticated rainbow table). As such, it must be -possible for clients to be able to query what pepper the identity server -requires before sending it hashes. A new endpoint must be added: +Identity servers must specify the hashing algorithms and a pepper that they +support, which will allow for rotation if a rainbow table is ever released +coinciding with their current hash and pepper. As such, it must be possible for +clients to be able to query what pepper the identity server requires before +sending it hashes. A new endpoint must be added: ``` GET /_matrix/identity/v2/hash_details @@ -64,13 +60,13 @@ Clients should request this endpoint each time before making a `/lookup` or pepper values frequently. Clients must choose one of the given hash algorithms to encrypt the 3PID during lookup. -An example of generating a hash using SHA-256 and the provided pepper is as -follows: +Peppers are appended to the end of the 3PID before hashing. An example of +generating a hash using SHA-256 and the provided pepper is as follows: ```python address = "user@example.org" pepper = "matrixrocks" -digest = hashlib.sha256((pepper + address).encode()).digest() +digest = hashlib.sha256((address + pepper).encode()).digest() result_address = unpaddedbase64.encode_base64(digest) print(result_address) vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw @@ -119,15 +115,17 @@ following: } ``` -If the pepper does not match the server's, the server should return a `400 -M_INVALID_PARAM`. +If the algorithm does not match the server's, the server should return a 400 +`M_INVALID_PARAM`. If the pepper does not match the server's, the server should +return a new error code, 400 `M_INVALID_PEPPER`. A new error code is not +defined for an invalid algorithm as that is considered a client bug. No parameter changes will be made to /bind. ## Fallback considerations `v1` versions of these endpoints may be disabled at the discretion of the -implementation, and should return a HTTP 403 if so. +implementation, and should return a 403 `M_FORBIDDEN` error if so. If an identity server is too old and a HTTP 404, 405 or 501 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. @@ -180,7 +178,7 @@ SHA-256+SomeBetterAlg. However @erikjohnston then pointed out that if SuperGreatHash(BrokenAlgo(b))`, so all you'd need to do is find a match in the broken algo, and you'd break the new algorithm as well. This means that you would need the plaintext 3PIDs to encode a new hash, and thus storing them -hashed on disk would require a transition period where 3pids were reuploaded in +hashed on disk would require a transition period where 3PIDs were reuploaded in a strong hash variant. ## Conclusion From 0fd4fe254207badb98be9eb1fc968db8913bc323 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 Jun 2019 10:55:44 +0100 Subject: [PATCH 335/497] Add algo/pepper to err resp --- proposals/2134-identity-hash-lookup.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 34e9b0a6..accadc25 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -28,8 +28,10 @@ other endpoints): - `/_matrix/identity/v2/lookup` - `/_matrix/identity/v2/bulk_lookup` -`address` MUST no longer be in a plain-text format, but rather will be a peppered hash -value, and the resulting digest MUST be encoded in unpadded base64. +`address` MUST no longer be in a plain-text format, but rather will be a +peppered hash value, and the resulting digest MUST be encoded in URL-safe +unpadded base64 (similar to [room version 4's event +IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). Identity servers must specify their own hashing algorithms (from a list of specified values) and pepper, which will be useful if a rainbow table is @@ -119,8 +121,23 @@ following: } ``` -If the pepper does not match the server's, the server should return a `400 -M_INVALID_PARAM`. +If the algorithm does not match the server's, the server should return a `400 +M_INVALID_PARAM`. If the pepper does not match the server's, the server should +return a new error code, 400 `M_INVALID_PEPPER`. A new error code is not +defined for an invalid algorithm as that is considered a client bug. Each of +these error responses should contain the correct `algorithm` and +`lookup_pepper` fields. This is to prevent the client from needing to query +`/hash_details` again, thus saving a round-trip. An example response to an +incorrect pepper would be: + +``` +{ + "error": "Incorrect value for lookup_pepper", + "errcode": "M_INVALID_PEPPER", + "algorithm": "sha256", + "lookup_pepper": "matrixrocks" +} +``` No parameter changes will be made to /bind. From 57094276ce01e324b174a74c40b63ea8afdc0ba8 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 14:36:15 +0100 Subject: [PATCH 336/497] Typing hard is Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index b0b15b07..a483607b 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -21,7 +21,7 @@ Requirements for this proposal are: their Matrix ID, ie. having agreed to a set of terms in one client, they should not have to agree to them again when using a different client. * Documents should be de-duplicated between services. If two or more services - are hosted by the same organisation, the organistation should have the + are hosted by the same organisation, the organisation should have the option to give their users a single document that encompasses both services (bearing in mind that the user must be able to opt-out of components of a service whilst still being able to use the service without that component). From af691b5a8ad09ea82cfc49f596eae90448aa4725 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 14:37:06 +0100 Subject: [PATCH 337/497] Clarify this applies to 2134 Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index a483607b..b508a9e2 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -54,7 +54,7 @@ and adds authentication to accross the Identity Service API. ### IS API Authentication All current endpoints within `/_matrix/identity/api/v1/` will be duplicated -into `/_matrix/identity/v2`. +into `/_matrix/identity/v2`, noting that MSC2134 changes the behaviour of lookups. Authentication is still expected on MSC2134's proposed endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception of `/_matrix/identity/v2` and the new `/_matrix/identity/v2/account/register` From 1d75828c71bb442ceed735c4ee6593171a08319c Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 14:45:25 +0100 Subject: [PATCH 338/497] Clarify what to do if no (new) docs --- proposals/2140-terms-of-service-2.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index b508a9e2..ad617508 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -174,11 +174,13 @@ documents that the user must agree to in order to use the service. It then cross-references this set of documents against the `m.accepted_terms` account data and presents to the user any documents that they have not already -agreed to, along with UI for them to indicate their agreement. Once the user -has indicated their agreement, it adds these URLs to `m.accepted_terms` account -data. Once this has succeeded, then, and only then, must the client perform -OpenID authentication, getting a token from the Homeserver and submitting this -to the service using the `register` endpoint. +agreed to, along with UI for them to indicate their agreement. If there are no +such documents (ie. if the `policies` dict is empty or the user has already +agreed to all documents) the client proceeds to perform the OpenID +registration. Once the user has indicated their agreement, it adds these URLs +to `m.accepted_terms` account data. Once this has succeeded, then, and only +then, must the client perform OpenID authentication, getting a token from the +Homeserver and submitting this to the service using the `register` endpoint. Having done this, if the user agreed to any new documents, it performs a `POST $prefix/terms` request to signal to the server the set of documents that the From ba7047ce7746733f77dbf4d6163767304690a2c7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 14:51:11 +0100 Subject: [PATCH 339/497] Clarify we must be accepting HS auth Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index ad617508..631ff5e8 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -196,7 +196,7 @@ may return: (new) terms in order to use or continue to use the service. The `_matrix/identity/v2/3pid/unbind` must not return either of these -errors if the request has a valid signature from a Homeserver. +errors if the request has a valid signature from a Homeserver, and is being authenticated as such. In summary, the process for using a service that has not previously been used in the current login sessions is: From 4edf826c9371aad7c5c22fec7434a1889d66b74c Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 14:52:19 +0100 Subject: [PATCH 340/497] Capitalise on our identifiers --- proposals/2140-terms-of-service-2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 631ff5e8..fc7d33b2 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -45,7 +45,7 @@ This proposal introduces: * The `m.accepted_terms` section in account data This proposal relies on both Integration Managers and Identity Servers being -able to identity users by their mxid and store the fact that a given mxid has +able to identity users by their MXID and store the fact that a given MXID has indicated that they accept the terms given. Integration Managers already identity users in this way by authenticating them using the OpenID endpoint on the Homeserver. This proposal introduces the same mechanism to Identity Servers @@ -221,8 +221,8 @@ A custom HTTP Header was also considered that could be added to assert that the client agrees to a particular set of terms. We decided against this in favour of re-using existing primitives that already exist in the Matrix ecosystem. Custom HTTP Headers are not used anywhere else within Matrix. This also gives a -very simple and natural way for ISes to enforce that users may only bind 3pids -to their own mxids. +very simple and natural way for ISes to enforce that users may only bind 3PIDs +to their own MXIDs. This introduces a different way of accepting terms from the client/server API which uses User-Interactive Authentication. In the client/server API, the use From 6273868323ab19ed42edaaa7d8d4ac5f738e718f Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 15:05:43 +0100 Subject: [PATCH 341/497] Clarify v1 API deprecation --- proposals/2140-terms-of-service-2.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index fc7d33b2..6963c965 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -66,9 +66,11 @@ These endpoints require authentication by the client supplying an access token either via an `Authorization` header with a `Bearer` token or an `access_token` query parameter. -The existing endpoints under `/_matrix/identity/api/v1/` continue to be unauthenticated. -ISes may support the old v1 API for as long as they wish. Clients must update to use -the v2 API as soon as possible. +The existing endpoints under `/_matrix/identity/api/v1/` continue to be +unauthenticated but will be deprecated. ISes may support the old v1 API for as +long as they wish. Once ISes remove support for the old APIs, those endpoints +must return HTTP Status 404. Clients must update to use the v2 API as soon as +possible. OpenID authentication in the IS API will work the same as in the Integration Manager API, as specified in [MSC1961](https://github.com/matrix-org/matrix-doc/issues/1961). From 58cf083a6a93e273385cad5a1621895ca15272f5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 15:31:11 +0100 Subject: [PATCH 342/497] backwards compat --- proposals/2140-terms-of-service-2.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 6963c965..7018e364 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -243,10 +243,8 @@ the document, but: ## Potential issues -This change is not backwards compatible: clients implementing older versions of -the specification will expect to be able to access all IS API endpoints without -authentication. Care should be taken to manage the rollout of authentication -on IS APIs. +This change deprecates all v1 endpoints and so will require clients to update +to continue working. ## Security considerations From 2694bb1090d565a10ef934a45ce01ae06a009804 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 17:41:21 +0100 Subject: [PATCH 343/497] Add really horrible custom HTTP header for giving the IS token to the HS --- proposals/2140-terms-of-service-2.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 7018e364..ed1269a9 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -75,6 +75,12 @@ possible. OpenID authentication in the IS API will work the same as in the Integration Manager API, as specified in [MSC1961](https://github.com/matrix-org/matrix-doc/issues/1961). +When clients supply an identity server to the Homeserver in order for the Homeserver +to make calls to the IS on its behalf, it must also supply its access token for the +Identity Server either as the `is_token` query parameter or a bearer token in the +`X-Identity-Authorization` HTTP header with the same syntax as an `Authorizationn` +header. + ### IS Register API The following new APIs will be introduced to support OpenID auth as per From 21b9eaf8de06d2562c6326dedda66e334f03d6b0 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 26 Jun 2019 17:56:41 +0100 Subject: [PATCH 344/497] No custom HTTP headers Use the obvious way: in the same place as the ID server address --- proposals/2140-terms-of-service-2.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index ed1269a9..00a6ba52 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -77,9 +77,13 @@ API, as specified in [MSC1961](https://github.com/matrix-org/matrix-doc/issues/1 When clients supply an identity server to the Homeserver in order for the Homeserver to make calls to the IS on its behalf, it must also supply its access token for the -Identity Server either as the `is_token` query parameter or a bearer token in the -`X-Identity-Authorization` HTTP header with the same syntax as an `Authorizationn` -header. +Identity Server alongside in the `is_token` key of the same JSON object. That is, +in the main request object for a `requestToken` request and in the `threepidCreds` +object when supplying 3PID credentials (eg. in the `m.email.identity` UI auth stage). +Exxceptions to this are any requests where the only IS operation the Homeserver may +perform is unbinding, ie. `/_matrix/client/r0/account/deactivate` and +`/_matrix/client/r0/account/3pid/delete`, in which case the unbind is authenticated +by a signed request from the Homeserver. ### IS Register API From 6260871a21a00cd9959396c6ad07797fe526f089 Mon Sep 17 00:00:00 2001 From: Sorunome Date: Thu, 27 Jun 2019 13:07:08 +0200 Subject: [PATCH 345/497] spoiler fallback to uploaded media --- proposals/2010-spoilers.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index fc470fcc..7b128078 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -22,8 +22,9 @@ the spoiler by setting the attribute string. It could be rendered, for example, ![Spoiler rendering idea](https://user-images.githubusercontent.com/2433620/59299700-95063480-8c8d-11e9-9348-3e2c8bc94bdc.gif) -The plain-text fallback could be rendered as `(Spoiler: )` and -`(Spoiler for : )` respectively. +To preserve the semantics of a spoiler in the plaintext fallback it is recommended to upload the contents of the spoiler +as a text file and then link this: `[Spoiler](mxc://someserver/somefile)` and +`[Spoiler for reason](mxc://someserver/somefile)` respectively. ### Example Without reason: @@ -32,7 +33,7 @@ Without reason: "msgtype": "m.text", "format": "org.matrix.custom.html", "body": "Hello there, the movie was (Spoiler: awesome)", - "formatted_body": "Hello there, the movie was awesome" + "formatted_body": "Hello there, the movie was [Spoiler](mxc://someserver/somefile)" } ``` With reason: @@ -41,7 +42,7 @@ With reason: "msgtype": "m.text", "format": "org.matrix.custom.html", "body": "Hey (Spoiler for movie: the movie was awesome)", - "formatted_body": "Hey the movie was awesome" + "formatted_body": "Hey [Spoiler for movie](mxc://someserver/somefile)" } ``` From 540aab82a18bc65aef87cd2b434231d5ce50578e Mon Sep 17 00:00:00 2001 From: Sorunome Date: Thu, 27 Jun 2019 13:09:15 +0200 Subject: [PATCH 346/497] accidentally formatted the wrong entry --- proposals/2010-spoilers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index 7b128078..df7fd6c1 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -32,8 +32,8 @@ Without reason: { "msgtype": "m.text", "format": "org.matrix.custom.html", - "body": "Hello there, the movie was (Spoiler: awesome)", - "formatted_body": "Hello there, the movie was [Spoiler](mxc://someserver/somefile)" + "body": "Hello there, the movie was [spoiler](mxc://someserver/somefile)", + "formatted_body": "Hello there, the movie was awesome" } ``` With reason: @@ -41,8 +41,8 @@ With reason: { "msgtype": "m.text", "format": "org.matrix.custom.html", - "body": "Hey (Spoiler for movie: the movie was awesome)", - "formatted_body": "Hey [Spoiler for movie](mxc://someserver/somefile)" + "body": "Hey [Spoiler for movie](mxc://someserver/somefile)", + "formatted_body": "Hey the movie was awesome" } ``` From b5326de1c4c9d894d668cc4e5ec031226b7ad442 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 27 Jun 2019 16:34:46 +0100 Subject: [PATCH 347/497] Exclude requestToken endpoints from auth requirement --- proposals/2140-terms-of-service-2.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 00a6ba52..22bdb1f4 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -57,12 +57,20 @@ All current endpoints within `/_matrix/identity/api/v1/` will be duplicated into `/_matrix/identity/v2`, noting that MSC2134 changes the behaviour of lookups. Authentication is still expected on MSC2134's proposed endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception -of `/_matrix/identity/v2` and the new `/_matrix/identity/v2/account/register` -and `GET /_matrix/identity/v2/terms` may return an error with `M_UNAUTHORIZED` -errcode with HTTP status code 401. This indicates that the user must -authenticate with OpenID and supply a valid `access_token`. +of `/_matrix/identity/v2`, any `requestToken` endpoint and the new +`/_matrix/identity/v2/account/register` and `GET /_matrix/identity/v2/terms` +may return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. +This indicates that the user must authenticate with OpenID and supply a valid +`access_token`. -These endpoints require authentication by the client supplying an access token +`requestToken` endpoints are excluded from the auth check because they are used +in the registration process before the user has an MXID and therefore cannot +log in with OpenID. It is up to the IS to manage its privacy obligations +appropriately when fulfilling these requests, bearing in mind that the user has +not explictly incicated their agreement to any documents, and may abort the +registration process without doing so. + +All other endpoints require authentication by the client supplying an access token either via an `Authorization` header with a `Bearer` token or an `access_token` query parameter. From 10a6a59a12924243c2a321df111eec64d01f0234 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 27 Jun 2019 16:58:22 +0100 Subject: [PATCH 348/497] Deprecate `bind_email` / `bind_msisdn` --- proposals/2140-terms-of-service-2.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 22bdb1f4..74923e64 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -93,6 +93,13 @@ perform is unbinding, ie. `/_matrix/client/r0/account/deactivate` and `/_matrix/client/r0/account/3pid/delete`, in which case the unbind is authenticated by a signed request from the Homeserver. +### HS Register API + +The `bind_email` and `bind_msisdn` options to `/_matrix/client/r0/register` in +the client/server API will be deprecated. Due to the fact that +`/_matrix/identity/v2/3pid/bind` requires authentication, it will no longer be +possible for the Homeserver to bind 3PIDs as part of the registration process. + ### IS Register API The following new APIs will be introduced to support OpenID auth as per From f95197b4228aec45111c75923bca8f499a38eff7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 27 Jun 2019 17:30:36 +0100 Subject: [PATCH 349/497] make the many-anded sentence a list --- proposals/2140-terms-of-service-2.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 74923e64..b06b38eb 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -57,9 +57,13 @@ All current endpoints within `/_matrix/identity/api/v1/` will be duplicated into `/_matrix/identity/v2`, noting that MSC2134 changes the behaviour of lookups. Authentication is still expected on MSC2134's proposed endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception -of `/_matrix/identity/v2`, any `requestToken` endpoint and the new -`/_matrix/identity/v2/account/register` and `GET /_matrix/identity/v2/terms` -may return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. +of: + * `/_matrix/identity/v2` + * any `requestToken` endpoint + * The new `/_matrix/identity/v2/account/register` + * The new `GET /_matrix/identity/v2/terms` + +...may return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that the user must authenticate with OpenID and supply a valid `access_token`. From 4be283ccb3c25008e53f987c94c3749c40baea14 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 27 Jun 2019 17:31:15 +0100 Subject: [PATCH 350/497] Typing Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index b06b38eb..cd6be68b 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -71,7 +71,7 @@ This indicates that the user must authenticate with OpenID and supply a valid in the registration process before the user has an MXID and therefore cannot log in with OpenID. It is up to the IS to manage its privacy obligations appropriately when fulfilling these requests, bearing in mind that the user has -not explictly incicated their agreement to any documents, and may abort the +not explicitly indicated their agreement to any documents, and may abort the registration process without doing so. All other endpoints require authentication by the client supplying an access token From e80753e56c70001bb71ac490f063993479db2440 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Jun 2019 18:24:42 -0600 Subject: [PATCH 351/497] Add .well-known discovery --- proposals/1957-integrations-discovery.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index fd6bc8f9..cef17098 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -106,6 +106,30 @@ Integration managers shown in this way must be treated like widgets, regardless this means exposing the Widget API to the manager and applying necessary scoping to keep the manager as an account widget rather than a room widget. +#### Discovering a manager by only the domain name + +Clients may wish to ask users for a single canonical domain name so they can find the manager to add +to the user's account transparently. Similar to the .well-known discovery done by servers (and clients +during login), clients which have an integrations domain (eg: "example.org") make a regular HTTPS +request to `https://example.org/.well-known/matrix/integrations` which returns an object which looks +like the following: +```json +{ + "m.integrations_widget": { + "url": "https://integrations.example.org/ui?displayName=$matrix_display_name", + "data": { + "api_url": "https://integrations.example.org" + } + } +} +``` + +The response should be parsed as JSON. If the endpoint returns an error or is missing the `m.integrations_widget` +property, the client should assume there is no integrations manager running on that domain. The +`m.integrations_widget` is an object which has the exact same format as the account widget for +an integration manager, described above. The client should wrap the object verbatim into the appropriate +account data location. + ## Tradeoffs From d8283b9cdf15f3b37990f67f2d7c49d5b863f9af Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Jun 2019 20:44:49 -0600 Subject: [PATCH 352/497] Add option to use query string --- proposals/1961-integrations-auth.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1961-integrations-auth.md b/proposals/1961-integrations-auth.md index 863ea325..cf69af27 100644 --- a/proposals/1961-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -8,7 +8,8 @@ manager. This proposal covers the authentication portion of that API. All specified APIs (except `/register`) will take an `Authorization` header with a `Bearer` token returned from a call to `/register`. This token is used to authorize the request and to identify who is making the -request. +request. The token may also be specified as the `access_token` query string parameter, similar to the +Client-Server API. #### POST /_matrix/integrations/v1/account/register From bfd8e52c234d367c9adc4ec686fc77b3b2f02c1d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Jun 2019 20:45:23 -0600 Subject: [PATCH 353/497] Formatting --- proposals/1961-integrations-auth.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/1961-integrations-auth.md b/proposals/1961-integrations-auth.md index cf69af27..7f735607 100644 --- a/proposals/1961-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -11,7 +11,7 @@ from a call to `/register`. This token is used to authorize the request and to i request. The token may also be specified as the `access_token` query string parameter, similar to the Client-Server API. -#### POST /_matrix/integrations/v1/account/register +#### POST `/_matrix/integrations/v1/account/register` Exchanges an OpenID object for a token which can be used to authorize future requests to the manager. @@ -31,7 +31,7 @@ to the `matrix_server_name` provided in the original OpenID object. Applications which register for a token are responsible for tracking which integration manager they are for. This can usually be done by tracking the hostname of the integration manager and matching a token with it. -#### GET /_matrix/integrations/v1/account +#### GET `/_matrix/integrations/v1/account` Gets information about the token's owner, such as the user ID for which it belongs. @@ -56,7 +56,7 @@ here. Preferably, custom information is stored under a namespaced key like so: } ``` -#### POST /_matrix/integrations/v1/account/logout +#### POST `/_matrix/integrations/v1/account/logout` Logs the token out, rendering it useless for future requests. From 83bb3861ba2926bd711930d1d0e89ff08087383e Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 28 Jun 2019 09:31:53 +0100 Subject: [PATCH 354/497] line wrap --- proposals/2140-terms-of-service-2.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index cd6be68b..69696946 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -54,7 +54,8 @@ and adds authentication to accross the Identity Service API. ### IS API Authentication All current endpoints within `/_matrix/identity/api/v1/` will be duplicated -into `/_matrix/identity/v2`, noting that MSC2134 changes the behaviour of lookups. Authentication is still expected on MSC2134's proposed endpoints. +into `/_matrix/identity/v2`, noting that MSC2134 changes the behaviour of +lookups. Authentication is still expected on MSC2134's proposed endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception of: From 45d630951c6c81aaa7796c08e348e71ac6290f72 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 28 Jun 2019 09:32:15 +0100 Subject: [PATCH 355/497] back to M_TERMS_NOT_SIGNED --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 69696946..5bcb58a7 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -224,7 +224,7 @@ may return: * `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that the user must authenticate with OpenID and supply a valid `access_token`. - * `M_CONSENT_NOT_GIVEN` errcode. This indicates that the user must agree to + * `M_TERMS_NOT_SIGNED` errcode. This indicates that the user must agree to (new) terms in order to use or continue to use the service. The `_matrix/identity/v2/3pid/unbind` must not return either of these From 786d5bc281baf8ecbb79e4bf27ead5ab7adbde58 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 28 Jun 2019 10:25:24 +0100 Subject: [PATCH 356/497] rewrite UI auth tradeoffs --- proposals/2140-terms-of-service-2.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 5bcb58a7..f84c026c 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -259,9 +259,10 @@ to their own MXIDs. This introduces a different way of accepting terms from the client/server API which uses User-Interactive Authentication. In the client/server API, the use of UI auth allows terms acceptance to be integrated into the registration flow -in a simple and backwards-compatible way. Indtroducing the UI Auth mechanism -into these other APIs would add significant complexity, so this functionality -has been provided with simpler, dedicated endpoints. +in a simple and backwards-compatible way. Another option here would be to use +UI Auth on the register endpoint. This would also not allow users to register +before accepting the terms. However, this would then make the OpenID +registration process different and non-standard. The `m.accepted_terms` section contains only URLs of the documents that have been agreed to. This loses information like the name and version of From fe14d3c9f0928c037784f029f68af9fa7cd15757 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 28 Jun 2019 18:07:24 +0100 Subject: [PATCH 357/497] Spec terms response --- proposals/2140-terms-of-service-2.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index f84c026c..befa655d 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -175,6 +175,9 @@ any one language of each document as sufficient, regardless of what language a client is operating in: users should not have to re-consent to documents if they change their client to a different language. +The server responds with an empty JSON object. The server must not assume that +the client will agree to all documents in a single request. + ### Accepted Terms Account Data This proposal also defines the `m.accepted_terms` section in User Account From 6f81d3774b61e9482c729d1f5894d2803c2d3d35 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 1 Jul 2019 16:23:28 +0100 Subject: [PATCH 358/497] New hashing method --- proposals/2134-identity-hash-lookup.md | 420 +++++++++++++++++++------ 1 file changed, 325 insertions(+), 95 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 2892ea4e..e6593224 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -3,120 +3,112 @@ [Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been recently created in response to a security issue brought up by an independent party. To summarise the issue, lookups (of Matrix user IDs) are performed using -non-hashed 3PIDs (third-party IDs) which means that the identity server can -identify and record every 3PID that the user wants to check, whether that -address is already known by the identity server or not. +plain-text 3PIDs (third-party IDs) which means that the identity server can +identify and record every 3PID that the user has in their contacts, whether +that email address or phone number is already known by the identity server or +not. If the 3PID is hashed, the identity server could not determine the address unless it has already seen that address in plain-text during a previous call of -the /bind mechanism. +the /bind mechanism (without significant resources to reverse the hashes). -Note that in terms of privacy, this proposal does not stop an identity server -from mapping hashed 3PIDs to users, resulting in a social graph. However, the -identity of the 3PID will at least remain a mystery until /bind is used. - -This proposal thus calls for the Identity Service’s /lookup API to use hashed -3PIDs instead of their plain-text counterparts. +This proposal thus calls for the Identity Service API's /lookup endpoint to use +a back-and-forth mechanism of passing partial hashed 3PIDs instead of their +plain-text counterparts, which should leak mess less data to either party. ## Proposal This proposal suggests making changes to the Identity Service API's lookup -endpoints. Due to the nature of this proposal, the new endpoints should be on a -`v2` path (we also drop the `/api` in order to preserve consistency across -other endpoints): +endpoints. Instead of the `/lookup` and `/bulk_lookup` endpoints, this proposal +replaces them with endpoints `/lookup` and `/lookup_hashes`. Additionally, the +endpoints should be on a `v2` path, to avoid confusion with the original +`/lookup`. We also drop the `/api` in order to preserve consistency across +other endpoints: - `/_matrix/identity/v2/lookup` -- `/_matrix/identity/v2/bulk_lookup` +- `/_matrix/identity/v2/lookup_hashes` -`address` MUST no longer be in a plain-text format, but rather will be a -peppered hash value, and the resulting digest MUST be encoded in URL-safe -unpadded base64 (similar to [room version 4's event -IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). +A third endpoint is added for clients to request information about the form +the server expects hashes in. -Identity servers must specify the hashing algorithms and a pepper that they -support, which will allow for rotation if a rainbow table is ever released -coinciding with their current hash and pepper. As such, it must be possible for -clients to be able to query what pepper the identity server requires before -sending it hashes. A new endpoint must be added: +- `/_matrix/identity/v2/hash_details` -``` -GET /_matrix/identity/v2/hash_details -``` +The following back-and-forth occurs between the client and server. -This endpoint takes no parameters, and simply returns any supported hash -algorithms and pepper as a JSON object: +Let's say the client wants to check the following 3PIDs: -``` -{ - "lookup_pepper": "matrixrocks", - "algorithms": ["sha256"], -} -``` + alice@example.com + bob@example.com + carl@example.com + +1 234 567 8910 + denny@example.com + +The client will hash each 3PID as a concatenation of the medium and address, +separated by a space and a pepper appended to the end. Note that phone numbers +should be formatted as defined by +https://matrix.org/docs/spec/appendices#pstn-phone-numbers, before being +hashed). + + "alice@example.com" -> "email alice@example.com" + "bob@example.com" -> "email bob@example.com" + "carl@example.com" -> "email carl@example.com" + "+1 234 567 8910" -> "msisdn 12345678910" + "denny@example.com" -> "email denny@example.com" + +Hashes must be peppered in order to reduce both the information a client gains +during the process, and attacks the identity server can perform (namely sending +a rainbow table of hashes back in the response to `/lookup`). The resulting +digest MUST be encoded in URL-safe unpadded base64 (similar to [room version +4's event IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). + +In order for clients to know the pepper and hashing algorithm they should use, +Identity Servers must make the information available on the `/hash_details` +endpoint: + + GET /_matrix/identity/v2/hash_details + + { + "lookup_pepper": "matrixrocks", + "algorithms": ["sha256"] + } The name `lookup_pepper` was chosen in order to account for pepper values being returned for other endpoints in the future. The contents of `lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]*`. -Clients should request this endpoint each time before making a `/lookup` or -`/bulk_lookup` request, to handle identity servers which may rotate their -pepper values frequently. Clients must choose one of the given hash algorithms -to encrypt the 3PID during lookup. + The client should append the pepper to the end of the 3pid string before + hashing. -Peppers are appended to the end of the 3PID before hashing. An example of -generating a hash using SHA-256 and the provided pepper is as follows: + "email alice@example.com" -> "email alice@example.commatrixrocks" + "email bob@example.com" -> "email bob@example.commatrixrocks" + "email carl@example.com" -> "email carl@example.commatrixrocks" + "msisdn 12345678910" -> "msisdn 12345678910matrixrocks" + "email denny@example.com" -> "email denny@example.commatrixrocks" -```python -address = "user@example.org" -pepper = "matrixrocks" -digest = hashlib.sha256((address + pepper).encode()).digest() -result_address = unpaddedbase64.encode_base64(digest) -print(result_address) -vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw -``` +Clients SHOULD request this endpoint each time before performing a lookup, to +handle identity servers which may rotate their pepper values frequently. +Clients MUST choose one of the given hash algorithms to encrypt the 3PID during +lookup. -Possible hashing algorithms will be defined in the Matrix specification, and an -Identity Server can choose to implement one or all of them. Later versions of -the specification may deprecate algorithms when necessary. Currently the only -listed hashing algorithm is SHA-256 as defined by [RFC -4634](https://tools.ietf.org/html/rfc4634) and Identity Servers and clients -MUST agree to its use with the string `sha256`. SHA-256 was chosen as it is -currently used throughout the Matrix spec, as well as its properties of being -quick to hash. While this reduces the resources necessary to generate a rainbow -table for attackers, a fast hash is necessary if particularly slow mobile -clients are going to be hashing thousands of contacts. +Note that possible hashing algorithms will be defined in the Matrix +specification, and an Identity Server can choose to implement one or all of +them. Later versions of the specification may deprecate algorithms when +necessary. Currently the only listed hashing algorithm is SHA-256 as defined by +[RFC 4634](https://tools.ietf.org/html/rfc4634) and Identity Servers and +clients MUST agree to its use with the string `sha256`. SHA-256 was chosen as +it is currently used throughout the Matrix spec, as well as its properties of +being quick to hash. While this reduces the resources necessary to generate a +rainbow table for attackers, a fast hash is necessary if particularly slow +mobile clients are going to be hashing thousands of contact details. When performing a lookup, the pepper and hashing algorithm the client used must be part of the request body. If they do not match what the server has on file -(which may be the case if the pepper was rotated right after the client's +(which may be the case if the pepper was changed right after the client's request for it), then the server must inform the client that they need to query the hash details again, instead of just returning an empty response, which clients would assume to mean that no contacts are registered on that identity server. -Thus, an example client request to `/bulk_lookup` would look like the -following: - -``` -{ - "threepids": [ - [ - "email", - "vNjEQuRCOmBp/KTuIpZ7RUJgPAbVAyqa0Uzh770tQaw" - ], - [ - "msisdn", - "0VnvYk7YZpe08fP/CGqs3f39QtRjqAA2lPd14eLZXiw" - ], - [ - "email", - "BJaLI0RrLFDMbsk0eEp5BMsYDYzvOzDneQP/9NTemYA" - ] - ], - "lookup_pepper": "matrixrocks", - "algorithm": "sha256" -} -``` - If the algorithm does not match the server's, the server should return a `400 M_INVALID_PARAM`. If the pepper does not match the server's, the server should return a new error code, 400 `M_INVALID_PEPPER`. A new error code is not @@ -127,14 +119,252 @@ Each of these error responses should contain the correct `algorithm` and `/hash_details` again, thus saving a round-trip. An example response to an incorrect pepper would be: -``` -{ - "error": "Incorrect value for lookup_pepper", - "errcode": "M_INVALID_PEPPER", - "algorithm": "sha256", - "lookup_pepper": "matrixrocks" -} -``` + { + "error": "Incorrect value for lookup_pepper", + "errcode": "M_INVALID_PEPPER", + "algorithm": "sha256", + "lookup_pepper": "matrixrocks" + } + +Now comes time for the lookup. Once hashing has been performed using the +defined hashing algorithm, the client sends the first `k` characters of each +hash in an array, deduplicating any matching entries. + +`k` is a value chosen by the client. It is a tradeoff between leaking the +hashes of 3PIDs that the Identity Server doesn't know about, and the amount of +hashing the server must perform. In addition to k, the client can also set a +`max_k` that it is comfortable with. The recommended values are `k = 4` and +`max_k = 6` (see below for the reasoning behind this). Let's say the client +chooses these values. + + NOTE: Example numbers, not real hash values. + + "email alice@example.commatrixrocks" -> "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" + "email bob@example.commatrixrocks" -> "21375b56a47c2cdc41a0596549a16ec51b64d26eb47b8e915d45b18ed17b72ff" + "email carl@example.commatrixrocks" -> "758afda64cb6a86ee6d540fa7c8b803a2479863e369cbafd71ffd376beef5d5f" + "msisdn 12345678910matrixrocks" -> "21375b3f1b61c975b13c8cecd6481a82e239e6aad644c29dc815836188ae8351" + "email denny@example.commatrixrocks" -> "70b1b5637937ab9846a94a8015e12313643a2f5323ca8f5b4ed6982fc8c3619b" + + Note that pairs (bob@example.com, 12345678910) and (alice@example.com, denny@example.com) + have the same leading characters in their hashed representations. + + POST /_matrix/identity/v2/lookup + + { + "hashes": [ + "70b1", + "2137", + "758a" + ], + "algorithm": "sha256", + "pepper": "matrixrocks" + } + +The identity server, upon receiving these partial hashes, can see that the +client chose `4` as its `k` value, which is the length of the shortest hash +prefix. The identity server has a "minimum k", which is a function of the +amount of 3PID hashes it currently holds and protects it against computing too +many per lookup. Let's say the Identity Server's `min_k = 5` (again, see below +for details). + +The client's `k` value (4) is less than the Identity Server's `min_k` (5), so +it will reject the lookup with the following error: + + { + "errcode": "M_HASH_TOO_SHORT", + "error": "Sent partial hashes are too short", + "minimum_length": "5" + } + +The client then knows it must send values of at least length 5. It's `max_k` is +6, so this is fine. The client sends the values again with `k = 5`: + + POST /_matrix/identity/v2/lookup + + { + "hashes": [ + "70b1b", + "21375", + "758af" + ], + "algorithm": "sha256", + "pepper": "matrixrocks" + } + +The Identity Server sees the hashes are within an acceptable length (5 >= 5), +then checks which hashes it knows of that match the given leading values. It +will then return the next few characters (`n`; implementation-specific; lower +means less information leaked to clients at the result of potentially more +hashing to be done) of each that match: + + The identity server found the following hashes that contain the leading + characters: + + 70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4 + 70b1b1b28dcfcc179a54983f46e1753c3fcdb0884d06fad741582c0180b56fc9 + 21375b3f1b61c975b13c8cecd6481a82e239e6aad644c29dc815836188ae8351 + + And if n = 7, the identity server will send back the following payload: + + { + "hashes": { + "70b1b": ["5637937", "1b28dcf"], + "21375": ["b3f1b61"] + } + } + +The client can then deduce which hashes actually lead to Matrix IDs. In this +case, 70b1b5637937 are the leading characters of "alice@example.com" and +"denny@example.com", while 21375b3f1b61 are the leading characters of +"+12345678910" whereas 70b1b1b28dcf does not match any of the hashes the client +has locally, so it is ignored. "bob@example.com" and "carl@example.com" do not +seem to have Matrix IDs associated with them. + +Finally, the client salts and hashes 3PID hashes that it believes are +associated with Matrix IDs and sends them to the identity server on the +`/lookup_hashes` endpoint. Instead of hashing the 3PIDs again, clients should +reuse the peppered hash that was previously sent to the server. Salting is +performed to prevent an identity server generating a rainbow table to reverse +any non-Matrix 3PIDs that slipped in. Salts MUST match the regular expression +`[a-zA-Z0-9]*`. + + Computed previously: + + "email alice@example.commatrixrocks" + becomes + "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" + + The client should generate a salt. Let's say it generates "salt123". This + value is appended to the hash. + + "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" + becomes + "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4salt123" + + And then hashed: + + "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4salt123" + becomes + "1f64ed6ac9d6da86b65bcc68a39c7c4d083f77193ec7e5adc4b09617f8d0d81a" + +A new salt is generated and applied to each hash **prefix** individually. Doing +so requires the identity server to only rehash the 3PIDs whose unsalted hashes +matched the earlier prefixes (in the case of 70b1b, hashes 5637937... and +1b28dcf...). This adds only a small multiplier of additional hashes needing to +be performed by the Identity Server (the median number of hashes that fit each +prefix, a function of the chosen `k` value). + +An attacker would now need to create a new rainbow table per hash prefix, per +lookup. This reduces the attack surface significantly to only very targeted +attacks. + + POST /_matrix/identity/v2/lookup_hashes + + { + "hashes": { + "70b1b": { + "1": "1f64ed6ac9d6da86b65bcc68a39c7c4d083f77193ec7e5adc4b09617f8d0d81a", + "2": "a32e1c1f3b9e118eab196b0807443871628eace587361b7a02adfb2b77b8d620" + }, + "21375": { + "1": "372bf27a4e7e952d1e794f78f8cdfbff1a3ab2f59c6d44e869bfdd7dd1de3948" + } + }, + "salts": { + "70b1b": "salt123", + "21375": "salt234" + } + } + +The server reads the prefixes and only rehashes those 3PIDs that match these +hashes (being careful to continue to enforce its `min_k` requirement), and +returns them: + + { + "mappings": { + "70b1b": { + "2": "@alice:example.com" + }, + "21375": { + "1": "@fred:example.com" + } + } + } + +The client can now display which 3PIDs link to which Matrix IDs. + +### How to pick k + +The `k` value is a tradeoff between the privacy of the user's contacts, and the +resource-intensiveness of lookups for the identity server. Clients would rather +have a smaller `k`, while servers a larger `k`. A larger `k` also allows the +identity server to learn more about the contacts the client has that are not +Matrix users. Ideally we'd like to balance these two, and with the value also +being a factor of how many records an identity server has, there's no way to +simply give a single `k` value that should be used from the spec. + +Instead, we can have the client and identity server decide it amongst +themselves. The identity server should pick a `k` value based on how many 3PIDs +records they have, and thus how much hashes they will need to perform. An ideal +value can be calculated from the following function: + + C <= N / (64 ^ k) + + Where N is the number of 3PID records an identity server has, k is the number of + characters to truncate each hash to, and C is the median number of hashing rounds + an identity server will need to perform per hash (denoted complexity). 64 is the + number of possible characters per byte in a hash, as hash digests are encoded in + url-safe base64. + + Identity servers should choose a complexity value they're comfortable with. + Let's say 5 (for reference, HIBP's service has set their k value for a complexity + of 478: https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/) + + When C is set (implementation specific), k can then be solved for: + + k >= - log(C/N) + ---------- + - log(64) + + Taking HIBP's amount of passwords as an example, 600,000,000, as N and solving for k, we get: + + k >= 4.47 + + We round k to 5 for it to be a whole number. + + As this is quite a lot of records, we advise clients to start with k = 4, and go from there. + + For reference, a very small identity server with only 600 records would produce a + minimum k of 0.628, or 1. + + From this we can see that even low k values scale to quite a lot of records. + +Clients themselves should pick a reasonable default `k`, and a maximum value +that they are comfortable extending towards if the identity server requests a +higher minimum number. If the identity server requests too high of a minimum +number, clients will need to inform the user, either with an error message, or +more advanced clients could allow users to tweak their k values. + +--- + +Past what they already knew, from this exchange the client and server have learned: + +Client: + +* Unsalted, peppered partial 3PID hash "70b1b1b28dcf" + of some matrix user + (harder to crack, and new rainbow table needed) +* alice@example.com -> @alice:example.com (required) +* +1 234 567 8910 -> @fred:example.com (required) + +Server: + +* Partial hash "758af" (likely useless) +* The server knows some salted hash + 70b1b5637937ab9846a94a8015e12313643a2f5323ca8f5b4ed6982fc8c3619bf + (crackable, new rainbow table needed) + +--- No parameter changes will be made to /bind. @@ -151,10 +381,10 @@ are being sent to. ## Tradeoffs -* This approach means that the client now needs to calculate a hash by itself, - but the belief is that most languages provide a mechanism for doing so. * There is a small cost incurred by performing hashes before requests, but this is outweighed by the privacy implications of sending plain-text addresses. +* Identity services will need to perform a lot of hashing, however with + authentication being added in MSC 2140, effective rate-limiting is possible. ## Potential issues @@ -186,14 +416,14 @@ for a federated network, as it requires specialized hardware. While a bit out of scope for this MSC, there has been debate over preventing 3PIDs as being kept as plain-text on disk. The argument against this was that if the hashing algorithm (in this case SHA-256) was broken, we couldn't update -the hashing algorithm without having the plaintext 3PIDs. @lampholder helpfully +the hashing algorithm without having the plain-text 3PIDs. @lampholder helpfully added that we could just take the old hashes and rehash them in the more secure hashing algorithm, thus transforming the hash from SHA-256 to SHA-256+SomeBetterAlg. However @erikjohnston then pointed out that if `BrokenAlgo(a) == BrokenAlgo(b)` then `SuperGreatHash(BrokenAlgo(a)) == SuperGreatHash(BrokenAlgo(b))`, so all you'd need to do is find a match in the broken algo, and you'd break the new algorithm as well. This means that you -would need the plaintext 3PIDs to encode a new hash, and thus storing them +would need the plain-text 3PIDs to encode a new hash, and thus storing them hashed on disk would require a transition period where 3PIDs were reuploaded in a strong hash variant. From 922a20ba2625cb7205b01817ad383e471b27ebfa Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 1 Jul 2019 16:30:07 +0100 Subject: [PATCH 359/497] small fixes --- proposals/2134-identity-hash-lookup.md | 39 +++++++++++++------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index e6593224..ec2beb47 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -47,7 +47,7 @@ The client will hash each 3PID as a concatenation of the medium and address, separated by a space and a pepper appended to the end. Note that phone numbers should be formatted as defined by https://matrix.org/docs/spec/appendices#pstn-phone-numbers, before being -hashed). +hashed). First the client must prepend the medium to the address: "alice@example.com" -> "email alice@example.com" "bob@example.com" -> "email bob@example.com" @@ -57,9 +57,7 @@ hashed). Hashes must be peppered in order to reduce both the information a client gains during the process, and attacks the identity server can perform (namely sending -a rainbow table of hashes back in the response to `/lookup`). The resulting -digest MUST be encoded in URL-safe unpadded base64 (similar to [room version -4's event IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). +a rainbow table of hashes back in the response to `/lookup`). In order for clients to know the pepper and hashing algorithm they should use, Identity Servers must make the information available on the `/hash_details` @@ -126,9 +124,11 @@ incorrect pepper would be: "lookup_pepper": "matrixrocks" } -Now comes time for the lookup. Once hashing has been performed using the -defined hashing algorithm, the client sends the first `k` characters of each -hash in an array, deduplicating any matching entries. +Now comes time for the lookup. Note that the resulting hash digest MUST be +encoded in URL-safe unpadded base64 (similar to [room version 4's event +IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). Once hashing has been +performed using the defined hashing algorithm, the client sends the first `k` +characters of each hash in an array, deduplicating any matching entries. `k` is a value chosen by the client. It is a tradeoff between leaking the hashes of 3PIDs that the Identity Server doesn't know about, and the amount of @@ -137,7 +137,7 @@ hashing the server must perform. In addition to k, the client can also set a `max_k = 6` (see below for the reasoning behind this). Let's say the client chooses these values. - NOTE: Example numbers, not real hash values. + NOTE: Example digests, not real hash values. "email alice@example.commatrixrocks" -> "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" "email bob@example.commatrixrocks" -> "21375b56a47c2cdc41a0596549a16ec51b64d26eb47b8e915d45b18ed17b72ff" @@ -145,8 +145,9 @@ chooses these values. "msisdn 12345678910matrixrocks" -> "21375b3f1b61c975b13c8cecd6481a82e239e6aad644c29dc815836188ae8351" "email denny@example.commatrixrocks" -> "70b1b5637937ab9846a94a8015e12313643a2f5323ca8f5b4ed6982fc8c3619b" - Note that pairs (bob@example.com, 12345678910) and (alice@example.com, denny@example.com) - have the same leading characters in their hashed representations. + Also note that pairs (bob@example.com, 12345678910) and (alice@example.com, + denny@example.com) have the same leading characters in their hashed + representations. POST /_matrix/identity/v2/lookup @@ -214,9 +215,9 @@ hashing to be done) of each that match: } The client can then deduce which hashes actually lead to Matrix IDs. In this -case, 70b1b5637937 are the leading characters of "alice@example.com" and -"denny@example.com", while 21375b3f1b61 are the leading characters of -"+12345678910" whereas 70b1b1b28dcf does not match any of the hashes the client +case, `70b1b5637937` are the leading characters of "alice@example.com" and +"denny@example.com", while `21375b3f1b61` are the leading characters of +"+12345678910" and `70b1b1b28dcf` does not match any of the hashes the client has locally, so it is ignored. "bob@example.com" and "carl@example.com" do not seem to have Matrix IDs associated with them. @@ -247,12 +248,12 @@ any non-Matrix 3PIDs that slipped in. Salts MUST match the regular expression becomes "1f64ed6ac9d6da86b65bcc68a39c7c4d083f77193ec7e5adc4b09617f8d0d81a" -A new salt is generated and applied to each hash **prefix** individually. Doing -so requires the identity server to only rehash the 3PIDs whose unsalted hashes -matched the earlier prefixes (in the case of 70b1b, hashes 5637937... and -1b28dcf...). This adds only a small multiplier of additional hashes needing to -be performed by the Identity Server (the median number of hashes that fit each -prefix, a function of the chosen `k` value). +A new salt is generated per **hash prefix** and applied to each hash +individually. Doing so requires the identity server to only rehash the 3PIDs +whose unsalted hashes matched the earlier prefixes (in the case of `70b1b`, +hashes `5637937...` and `1b28dcf...`). This adds only a small multiplier of +additional hashes needing to be performed by the Identity Server (the median +number of hashes that fit each prefix, a function of the chosen `k` value). An attacker would now need to create a new rainbow table per hash prefix, per lookup. This reduces the attack surface significantly to only very targeted From 8af35be13faff18010407f135d9b894fdded5768 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 10:56:12 +0100 Subject: [PATCH 360/497] Typo Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index befa655d..e47584bb 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -47,7 +47,7 @@ This proposal introduces: This proposal relies on both Integration Managers and Identity Servers being able to identity users by their MXID and store the fact that a given MXID has indicated that they accept the terms given. Integration Managers already -identity users in this way by authenticating them using the OpenID endpoint on +identify users in this way by authenticating them using the OpenID endpoint on the Homeserver. This proposal introduces the same mechanism to Identity Servers and adds authentication to accross the Identity Service API. From 2d11217d4ed1282d4c80e97faffd544de2b34bcb Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 10:56:32 +0100 Subject: [PATCH 361/497] Typo Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index e47584bb..2beeafbc 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -49,7 +49,7 @@ able to identity users by their MXID and store the fact that a given MXID has indicated that they accept the terms given. Integration Managers already identify users in this way by authenticating them using the OpenID endpoint on the Homeserver. This proposal introduces the same mechanism to Identity Servers -and adds authentication to accross the Identity Service API. +and adds authentication across the Identity Service API. ### IS API Authentication From 5374030cc0644dadb40bb53a7cde63cb58353376 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 10:59:08 +0100 Subject: [PATCH 362/497] Drop application/x-form-www-urlencoded in v2 --- proposals/2140-terms-of-service-2.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 2beeafbc..0d4a9f7c 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -56,6 +56,8 @@ and adds authentication across the Identity Service API. All current endpoints within `/_matrix/identity/api/v1/` will be duplicated into `/_matrix/identity/v2`, noting that MSC2134 changes the behaviour of lookups. Authentication is still expected on MSC2134's proposed endpoints. +Support for `application/x-form-www-urlencoded` parameters in requests will +be dropped from all endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception of: From f02e4c2e9cae69d6cb2a7ffe0dc08edffde30a13 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:00:39 +0100 Subject: [PATCH 363/497] both registers are excluded from auth Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 0d4a9f7c..e4a3083b 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -63,7 +63,7 @@ Any request to any endpoint within `/_matrix/identity/v2`, with the exception of: * `/_matrix/identity/v2` * any `requestToken` endpoint - * The new `/_matrix/identity/v2/account/register` + * The new `$prefix/account/register` endpoint * The new `GET /_matrix/identity/v2/terms` ...may return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. From d00dfb78226b2015633aac4b612f8ea28b9fefdd Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:04:06 +0100 Subject: [PATCH 364/497] exclude submittoken too --- proposals/2140-terms-of-service-2.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index e4a3083b..568a50df 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -62,20 +62,21 @@ be dropped from all endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception of: * `/_matrix/identity/v2` - * any `requestToken` endpoint + * any `requestToken` or `submitToken` endpoint * The new `$prefix/account/register` endpoint * The new `GET /_matrix/identity/v2/terms` + * `$prefix/logout` ...may return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that the user must authenticate with OpenID and supply a valid `access_token`. -`requestToken` endpoints are excluded from the auth check because they are used -in the registration process before the user has an MXID and therefore cannot -log in with OpenID. It is up to the IS to manage its privacy obligations -appropriately when fulfilling these requests, bearing in mind that the user has -not explicitly indicated their agreement to any documents, and may abort the -registration process without doing so. +`requestToken` and `submitToken` endpoints are excluded from the auth check +because they are used in the registration process before the user has an MXID +and therefore cannot log in with OpenID. It is up to the IS to manage its +privacy obligations appropriately when fulfilling these requests, bearing in +mind that the user has not explicitly indicated their agreement to any +documents, and may abort the registration process without doing so. All other endpoints require authentication by the client supplying an access token either via an `Authorization` header with a `Bearer` token or an `access_token` From 03e6ab0103fad0cf80d31ef0d4003f577bd130d3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:11:50 +0100 Subject: [PATCH 365/497] re-word double openid --- proposals/2140-terms-of-service-2.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 568a50df..2e874ee8 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -215,10 +215,11 @@ account data and presents to the user any documents that they have not already agreed to, along with UI for them to indicate their agreement. If there are no such documents (ie. if the `policies` dict is empty or the user has already agreed to all documents) the client proceeds to perform the OpenID -registration. Once the user has indicated their agreement, it adds these URLs -to `m.accepted_terms` account data. Once this has succeeded, then, and only -then, must the client perform OpenID authentication, getting a token from the -Homeserver and submitting this to the service using the `register` endpoint. +registration. If there are new terms documents, the client prompts the user for +agreement, then once the user has indicated their agreement, it adds these URLs +to `m.accepted_terms` account data and then proceeds with OpenID +authentication, getting a token from the Homeserver and submitting this to the +service using the `register` endpoint. Having done this, if the user agreed to any new documents, it performs a `POST $prefix/terms` request to signal to the server the set of documents that the From 7f653648045fded42b8e2321de52ed996dc81da2 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:13:12 +0100 Subject: [PATCH 366/497] Typo Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 2e874ee8..f7b43376 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -96,7 +96,7 @@ to make calls to the IS on its behalf, it must also supply its access token for Identity Server alongside in the `is_token` key of the same JSON object. That is, in the main request object for a `requestToken` request and in the `threepidCreds` object when supplying 3PID credentials (eg. in the `m.email.identity` UI auth stage). -Exxceptions to this are any requests where the only IS operation the Homeserver may +Exceptions to this are any requests where the only IS operation the Homeserver may perform is unbinding, ie. `/_matrix/client/r0/account/deactivate` and `/_matrix/client/r0/account/3pid/delete`, in which case the unbind is authenticated by a signed request from the Homeserver. From ac6b9bdb7ccf316ee77f65c3bd07edaed4a927f2 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:16:25 +0100 Subject: [PATCH 367/497] s/deprecate/remove/ --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index f7b43376..152f28d3 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -104,7 +104,7 @@ by a signed request from the Homeserver. ### HS Register API The `bind_email` and `bind_msisdn` options to `/_matrix/client/r0/register` in -the client/server API will be deprecated. Due to the fact that +the client/server API will be removed. Due to the fact that `/_matrix/identity/v2/3pid/bind` requires authentication, it will no longer be possible for the Homeserver to bind 3PIDs as part of the registration process. From 79dbad2914b1feeff57a908556fc95254c4de112 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:17:27 +0100 Subject: [PATCH 368/497] remove acceptance token mention --- proposals/2140-terms-of-service-2.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 152f28d3..cb373678 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -170,12 +170,9 @@ the user has agreed to: This endpoint requires authentication. The clients MUST include the correct URL for the language of the document that -was presented to the user and they agreed to. How servers store or serialise -acceptance into the `acceptance_token` is not defined, eg. they may internally -transform all URLs to the URL of the English-language version of each document -if the server deems it appropriate to do so. Servers should accept agreement of -any one language of each document as sufficient, regardless of what language a -client is operating in: users should not have to re-consent to documents if +was presented to the user and they agreed to. Servers should accept agreement +of any one language of each document as sufficient, regardless of what language +a client is operating in: users should not have to re-consent to documents if they change their client to a different language. The server responds with an empty JSON object. The server must not assume that From 10858bf83b6c01cf8962d63d20f4db3c57e5fde6 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:22:41 +0100 Subject: [PATCH 369/497] set account data after registration --- proposals/2140-terms-of-service-2.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index cb373678..0ee4ae20 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -197,9 +197,10 @@ An `m.accepted_terms` section therefore resembles the following: ``` Whenever a client submits a `POST $prefix/terms` request to an IS or IM or -completes an `m.terms` flow on the HS, it SHOULD update this account data -section adding any the URLs of any additional documents that the user agreed to -to this list. +completes an `m.terms` flow on the HS (or as soon as possible afterwards, ie. +after registration is complete), it SHOULD update this account data section +adding any the URLs of any additional documents that the user agreed to to this +list. ### Terms Acceptance in the API From 4c72c37b80aefef94c2ab1bc30719351e2f88ece Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:24:51 +0100 Subject: [PATCH 370/497] slash Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 0ee4ae20..40278b37 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -223,7 +223,7 @@ Having done this, if the user agreed to any new documents, it performs a `POST $prefix/terms` request to signal to the server the set of documents that the user has agreed to. -Any request to any endpoint in the IM API, and the `_matrix/identity/v2/` +Any request to any endpoint in the IM API, and the `/_matrix/identity/v2/` namespace of the IS API, with the exception of `/_matrix/identity/v2` itself, may return: From e28f7aad7203fab769ea0c18638fdfd10275e6f3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:25:12 +0100 Subject: [PATCH 371/497] slash Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 40278b37..e5fd21d6 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -232,7 +232,7 @@ may return: * `M_TERMS_NOT_SIGNED` errcode. This indicates that the user must agree to (new) terms in order to use or continue to use the service. -The `_matrix/identity/v2/3pid/unbind` must not return either of these +The `/_matrix/identity/v2/3pid/unbind` endpoint must not return either of these errors if the request has a valid signature from a Homeserver, and is being authenticated as such. In summary, the process for using a service that has not previously been used From d15c9df115a09b02cee265063cc328072a4ddaf2 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:25:26 +0100 Subject: [PATCH 372/497] fullstop Co-Authored-By: Travis Ralston --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index e5fd21d6..4a69ee03 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -240,7 +240,7 @@ in the current login sessions is: * `GET $prefix/terms` * Compare result with `m.accepted_terms` account data, get set of documents - pending agreement + pending agreement. * If non-empty, show this set of documents to the user and wait for the user to indicate their agreement. * Add the newly agreed documents to `m.accepted_terms` From 1a669348d8de4e83675e4847abbc67595ac0863b Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 2 Jul 2019 11:27:46 +0100 Subject: [PATCH 373/497] http status code --- proposals/2140-terms-of-service-2.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 4a69ee03..dbdb19f6 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -229,8 +229,9 @@ may return: * `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that the user must authenticate with OpenID and supply a valid `access_token`. - * `M_TERMS_NOT_SIGNED` errcode. This indicates that the user must agree to - (new) terms in order to use or continue to use the service. + * `M_TERMS_NOT_SIGNED` errcode with HTTP status code 403. This indicates + that the user must agree to (new) terms in order to use or continue to + use the service. The `/_matrix/identity/v2/3pid/unbind` endpoint must not return either of these errors if the request has a valid signature from a Homeserver, and is being authenticated as such. From 53bd384f2ec87f2bde7c8f3bc1da3ee785cef96e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 3 Jul 2019 09:59:38 +0100 Subject: [PATCH 374/497] Clarify salting --- proposals/2134-identity-hash-lookup.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index ec2beb47..3711d9c8 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -236,13 +236,14 @@ any non-Matrix 3PIDs that slipped in. Salts MUST match the regular expression "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" The client should generate a salt. Let's say it generates "salt123". This - value is appended to the hash. + value is appended to the base64-representation of the hash digest of the + initial 3pid and pepper. "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" becomes "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4salt123" - And then hashed: + Which is then hashed: "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4salt123" becomes From 8033ab1c86d239f5c614cc837973a22cb446bd40 Mon Sep 17 00:00:00 2001 From: reivilibre Date: Wed, 3 Jul 2019 10:36:16 +0100 Subject: [PATCH 375/497] Fix Push Gateway API example: Field renamed to event_id I believe this was forgotten in: 71cb646541ed2611e8f623fc28fac55b3aa73fbb --- api/push-gateway/push_notifier.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 4a6cb8f7..754c325a 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -57,7 +57,7 @@ paths: type: object example: { "notification": { - "id": "$3957tyerfgewrf384", + "event_id": "$3957tyerfgewrf384", "room_id": "!slw48wfj34rtnrf:example.com", "type": "m.room.message", "sender": "@exampleuser:matrix.org", From 4c65660b96335339d08e558856b6a2dd6a6fc9c8 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Wed, 3 Jul 2019 10:59:38 +0100 Subject: [PATCH 376/497] Clarify `.m.rule.room_one_to_one` push rule This clarifies the `.m.rule.room_one_to_one` push rule by adding a condition on event type. Some parts of the spec already had this info, while others were missing it. Synapse has had this behaviour since the push rule appeared. Fixes https://github.com/matrix-org/matrix-doc/issues/2150 --- api/client-server/pushrules.yaml | 9 +++++++-- event-schemas/examples/m.push_rules | 9 +++++++-- specification/modules/push.rst | 5 +++++ 3 files changed, 19 insertions(+), 4 deletions(-) diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index e23c9189..a1cbc354 100644 --- a/api/client-server/pushrules.yaml +++ b/api/client-server/pushrules.yaml @@ -159,8 +159,13 @@ paths: ], "conditions": [ { - "is": "2", - "kind": "room_member_count" + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" } ], "default": true, diff --git a/event-schemas/examples/m.push_rules b/event-schemas/examples/m.push_rules index e4f0a959..34bc2fe6 100644 --- a/event-schemas/examples/m.push_rules +++ b/event-schemas/examples/m.push_rules @@ -107,8 +107,13 @@ ], "conditions": [ { - "is": "2", - "kind": "room_member_count" + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" } ], "default": true, diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 33ca7fd7..b16ed8a6 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -563,6 +563,11 @@ Definition: { "kind": "room_member_count", "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" } ], "actions": [ From 9208c5cd13e8006a8bb01a4c4e6537db04b2dd3f Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Wed, 3 Jul 2019 11:34:00 +0100 Subject: [PATCH 377/497] Add changelog --- changelogs/client_server/newsfragments/2152.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2152.clarification diff --git a/changelogs/client_server/newsfragments/2152.clarification b/changelogs/client_server/newsfragments/2152.clarification new file mode 100644 index 00000000..03fde9ff --- /dev/null +++ b/changelogs/client_server/newsfragments/2152.clarification @@ -0,0 +1 @@ +Clarify the conditions for the ``.m.rule.room_one_to_one`` push rule. From f4a1e0288419f16500ed047df91cb4ddfc63445e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 4 Jul 2019 16:28:15 +0100 Subject: [PATCH 378/497] simple method once more --- proposals/2134-identity-hash-lookup.md | 319 +++++-------------------- 1 file changed, 59 insertions(+), 260 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 3711d9c8..76f527cb 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -13,22 +13,20 @@ unless it has already seen that address in plain-text during a previous call of the /bind mechanism (without significant resources to reverse the hashes). This proposal thus calls for the Identity Service API's /lookup endpoint to use -a back-and-forth mechanism of passing partial hashed 3PIDs instead of their -plain-text counterparts, which should leak mess less data to either party. +hashed 3PIDs instead of their plain-text counterparts, which will leak less +data to identity servers. ## Proposal This proposal suggests making changes to the Identity Service API's lookup -endpoints. Instead of the `/lookup` and `/bulk_lookup` endpoints, this proposal -replaces them with endpoints `/lookup` and `/lookup_hashes`. Additionally, the -endpoints should be on a `v2` path, to avoid confusion with the original -`/lookup`. We also drop the `/api` in order to preserve consistency across -other endpoints: +endpoints. Instead, this proposal consolidates them into a single `/lookup` +endpoint. Additionally, the endpoint should be on a `v2` path, to avoid +confusion with the original `/lookup`. We also drop the `/api` in order to +preserve consistency across other endpoints: - `/_matrix/identity/v2/lookup` -- `/_matrix/identity/v2/lookup_hashes` -A third endpoint is added for clients to request information about the form +A second endpoint is added for clients to request information about the form the server expects hashes in. - `/_matrix/identity/v2/hash_details` @@ -127,248 +125,43 @@ incorrect pepper would be: Now comes time for the lookup. Note that the resulting hash digest MUST be encoded in URL-safe unpadded base64 (similar to [room version 4's event IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). Once hashing has been -performed using the defined hashing algorithm, the client sends the first `k` -characters of each hash in an array, deduplicating any matching entries. +performed using the defined hashing algorithm, the client sends each hash in an +array. -`k` is a value chosen by the client. It is a tradeoff between leaking the -hashes of 3PIDs that the Identity Server doesn't know about, and the amount of -hashing the server must perform. In addition to k, the client can also set a -`max_k` that it is comfortable with. The recommended values are `k = 4` and -`max_k = 6` (see below for the reasoning behind this). Let's say the client -chooses these values. - - NOTE: Example digests, not real hash values. - - "email alice@example.commatrixrocks" -> "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" - "email bob@example.commatrixrocks" -> "21375b56a47c2cdc41a0596549a16ec51b64d26eb47b8e915d45b18ed17b72ff" - "email carl@example.commatrixrocks" -> "758afda64cb6a86ee6d540fa7c8b803a2479863e369cbafd71ffd376beef5d5f" - "msisdn 12345678910matrixrocks" -> "21375b3f1b61c975b13c8cecd6481a82e239e6aad644c29dc815836188ae8351" - "email denny@example.commatrixrocks" -> "70b1b5637937ab9846a94a8015e12313643a2f5323ca8f5b4ed6982fc8c3619b" - - Also note that pairs (bob@example.com, 12345678910) and (alice@example.com, - denny@example.com) have the same leading characters in their hashed - representations. + "email alice@example.commatrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" + "email bob@example.commatrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" + "email carl@example.commatrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" + "msisdn 12345678910matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" + "email denny@example.commatrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" POST /_matrix/identity/v2/lookup { "hashes": [ - "70b1", - "2137", - "758a" + "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs", + "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE", + "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw", + "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens", + "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" ], "algorithm": "sha256", "pepper": "matrixrocks" } -The identity server, upon receiving these partial hashes, can see that the -client chose `4` as its `k` value, which is the length of the shortest hash -prefix. The identity server has a "minimum k", which is a function of the -amount of 3PID hashes it currently holds and protects it against computing too -many per lookup. Let's say the Identity Server's `min_k = 5` (again, see below -for details). - -The client's `k` value (4) is less than the Identity Server's `min_k` (5), so -it will reject the lookup with the following error: - - { - "errcode": "M_HASH_TOO_SHORT", - "error": "Sent partial hashes are too short", - "minimum_length": "5" - } - -The client then knows it must send values of at least length 5. It's `max_k` is -6, so this is fine. The client sends the values again with `k = 5`: - - POST /_matrix/identity/v2/lookup - - { - "hashes": [ - "70b1b", - "21375", - "758af" - ], - "algorithm": "sha256", - "pepper": "matrixrocks" - } - -The Identity Server sees the hashes are within an acceptable length (5 >= 5), -then checks which hashes it knows of that match the given leading values. It -will then return the next few characters (`n`; implementation-specific; lower -means less information leaked to clients at the result of potentially more -hashing to be done) of each that match: - - The identity server found the following hashes that contain the leading - characters: - - 70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4 - 70b1b1b28dcfcc179a54983f46e1753c3fcdb0884d06fad741582c0180b56fc9 - 21375b3f1b61c975b13c8cecd6481a82e239e6aad644c29dc815836188ae8351 - - And if n = 7, the identity server will send back the following payload: - - { - "hashes": { - "70b1b": ["5637937", "1b28dcf"], - "21375": ["b3f1b61"] - } - } - -The client can then deduce which hashes actually lead to Matrix IDs. In this -case, `70b1b5637937` are the leading characters of "alice@example.com" and -"denny@example.com", while `21375b3f1b61` are the leading characters of -"+12345678910" and `70b1b1b28dcf` does not match any of the hashes the client -has locally, so it is ignored. "bob@example.com" and "carl@example.com" do not -seem to have Matrix IDs associated with them. - -Finally, the client salts and hashes 3PID hashes that it believes are -associated with Matrix IDs and sends them to the identity server on the -`/lookup_hashes` endpoint. Instead of hashing the 3PIDs again, clients should -reuse the peppered hash that was previously sent to the server. Salting is -performed to prevent an identity server generating a rainbow table to reverse -any non-Matrix 3PIDs that slipped in. Salts MUST match the regular expression -`[a-zA-Z0-9]*`. - - Computed previously: - - "email alice@example.commatrixrocks" - becomes - "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" - - The client should generate a salt. Let's say it generates "salt123". This - value is appended to the base64-representation of the hash digest of the - initial 3pid and pepper. - - "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4" - becomes - "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4salt123" - - Which is then hashed: - - "70b1b5637937ab99f6aad01f694b3665541a5b9cbdfe54880462b3f1ad35d1f4salt123" - becomes - "1f64ed6ac9d6da86b65bcc68a39c7c4d083f77193ec7e5adc4b09617f8d0d81a" - -A new salt is generated per **hash prefix** and applied to each hash -individually. Doing so requires the identity server to only rehash the 3PIDs -whose unsalted hashes matched the earlier prefixes (in the case of `70b1b`, -hashes `5637937...` and `1b28dcf...`). This adds only a small multiplier of -additional hashes needing to be performed by the Identity Server (the median -number of hashes that fit each prefix, a function of the chosen `k` value). - -An attacker would now need to create a new rainbow table per hash prefix, per -lookup. This reduces the attack surface significantly to only very targeted -attacks. - - POST /_matrix/identity/v2/lookup_hashes - - { - "hashes": { - "70b1b": { - "1": "1f64ed6ac9d6da86b65bcc68a39c7c4d083f77193ec7e5adc4b09617f8d0d81a", - "2": "a32e1c1f3b9e118eab196b0807443871628eace587361b7a02adfb2b77b8d620" - }, - "21375": { - "1": "372bf27a4e7e952d1e794f78f8cdfbff1a3ab2f59c6d44e869bfdd7dd1de3948" - } - }, - "salts": { - "70b1b": "salt123", - "21375": "salt234" - } - } - -The server reads the prefixes and only rehashes those 3PIDs that match these -hashes (being careful to continue to enforce its `min_k` requirement), and -returns them: +The identity server, upon receiving these hashes, can simply compare against +the hashes of the 3PIDs it stores. The server then responds with the Matrix +IDs of those that match: { "mappings": { - "70b1b": { - "2": "@alice:example.com" - }, - "21375": { - "1": "@fred:example.com" - } + "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs": "@alice:example.com", + "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens": "@fred:example.com" } } The client can now display which 3PIDs link to which Matrix IDs. -### How to pick k - -The `k` value is a tradeoff between the privacy of the user's contacts, and the -resource-intensiveness of lookups for the identity server. Clients would rather -have a smaller `k`, while servers a larger `k`. A larger `k` also allows the -identity server to learn more about the contacts the client has that are not -Matrix users. Ideally we'd like to balance these two, and with the value also -being a factor of how many records an identity server has, there's no way to -simply give a single `k` value that should be used from the spec. - -Instead, we can have the client and identity server decide it amongst -themselves. The identity server should pick a `k` value based on how many 3PIDs -records they have, and thus how much hashes they will need to perform. An ideal -value can be calculated from the following function: - - C <= N / (64 ^ k) - - Where N is the number of 3PID records an identity server has, k is the number of - characters to truncate each hash to, and C is the median number of hashing rounds - an identity server will need to perform per hash (denoted complexity). 64 is the - number of possible characters per byte in a hash, as hash digests are encoded in - url-safe base64. - - Identity servers should choose a complexity value they're comfortable with. - Let's say 5 (for reference, HIBP's service has set their k value for a complexity - of 478: https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/) - - When C is set (implementation specific), k can then be solved for: - - k >= - log(C/N) - ---------- - - log(64) - - Taking HIBP's amount of passwords as an example, 600,000,000, as N and solving for k, we get: - - k >= 4.47 - - We round k to 5 for it to be a whole number. - - As this is quite a lot of records, we advise clients to start with k = 4, and go from there. - - For reference, a very small identity server with only 600 records would produce a - minimum k of 0.628, or 1. - - From this we can see that even low k values scale to quite a lot of records. - -Clients themselves should pick a reasonable default `k`, and a maximum value -that they are comfortable extending towards if the identity server requests a -higher minimum number. If the identity server requests too high of a minimum -number, clients will need to inform the user, either with an error message, or -more advanced clients could allow users to tweak their k values. - ---- - -Past what they already knew, from this exchange the client and server have learned: - -Client: - -* Unsalted, peppered partial 3PID hash "70b1b1b28dcf" - of some matrix user - (harder to crack, and new rainbow table needed) -* alice@example.com -> @alice:example.com (required) -* +1 234 567 8910 -> @fred:example.com (required) - -Server: - -* Partial hash "758af" (likely useless) -* The server knows some salted hash - 70b1b5637937ab9846a94a8015e12313643a2f5323ca8f5b4ed6982fc8c3619bf - (crackable, new rainbow table needed) - ---- - -No parameter changes will be made to /bind. +No parameter changes will be made to /bind as part of this proposal. ## Fallback considerations @@ -377,35 +170,34 @@ implementation, and should return a 403 `M_FORBIDDEN` error if so. If an identity server is too old and a HTTP 404, 405 or 501 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. -However, clients should be aware that plain-text 3PIDs are required, and SHOULD -ask for user consent to send 3PIDs in plain-text, and be clear about where they -are being sent to. +However, clients should be aware that plain-text 3PIDs are required for the +`v1` endpoint, and SHOULD ask for user consent to send 3PIDs in plain-text, and +be clear about where they are being sent to. ## Tradeoffs * There is a small cost incurred by performing hashes before requests, but this is outweighed by the privacy implications of sending plain-text addresses. -* Identity services will need to perform a lot of hashing, however with - authentication being added in MSC 2140, effective rate-limiting is possible. ## Potential issues -This proposal does not force an identity server to stop handling plain-text -requests, because a large amount of the Matrix ecosystem relies upon this -behavior. However, a conscious effort should be made by all users to use the -privacy respecting endpoints outlined above. Identity servers may disallow use -of the v1 endpoint, as per above. +Hashes are still reversible with a rainbow table, but hopefully the provided +pepper, which can be rotated by identity servers at will, should help mitigate +this to some extent. -Unpadded base64 has been chosen to encode the value due to use in many other -portions of the spec. +Additionally, this proposal does not stop an identity server from storing +plain-text 3PIDs. There is a GDPR argument in keeping email addresses, such +that if a breach happens, users must be notified of such. Ideally this would be +done over Matrix, but people may've stuck their email in an identity server and +then left Matrix forever. Perhaps if only hashes were being stored on the +identity server then that isn't considered personal information? In any case, a +discussion for another MSC. ## Other considered solutions Ideally identity servers would never receive plain-text addresses, however it is necessary for the identity server to send email/sms messages during a bind, as it cannot trust a homeserver to do so as the homeserver may be lying. -Additionally, only storing 3PID hashes at rest instead of the plain-text -versions is impractical if the hashing algorithm ever needs to be changed. Bloom filters are an alternative method of providing private contact discovery. However, they do not scale well due to requiring clients to download a large @@ -415,23 +207,30 @@ eventual solution of using Software Guard Extensions (detailed in https://signal.org/blog/private-contact-discovery/) is considered impractical for a federated network, as it requires specialized hardware. -While a bit out of scope for this MSC, there has been debate over preventing -3PIDs as being kept as plain-text on disk. The argument against this was that -if the hashing algorithm (in this case SHA-256) was broken, we couldn't update -the hashing algorithm without having the plain-text 3PIDs. @lampholder helpfully -added that we could just take the old hashes and rehash them in the more secure -hashing algorithm, thus transforming the hash from SHA-256 to -SHA-256+SomeBetterAlg. However @erikjohnston then pointed out that if -`BrokenAlgo(a) == BrokenAlgo(b)` then `SuperGreatHash(BrokenAlgo(a)) == -SuperGreatHash(BrokenAlgo(b))`, so all you'd need to do is find a match in the -broken algo, and you'd break the new algorithm as well. This means that you -would need the plain-text 3PIDs to encode a new hash, and thus storing them -hashed on disk would require a transition period where 3PIDs were reuploaded in -a strong hash variant. +k-anonymity was considered as an alternative, in which the identity server +would never receive a full hash of a 3PID that it did not already know about. +While this has been considered plausible, it comes with heightened resource +requirements (much more hashing by the identity server). The conclusion was +that it may not provide more privacy if an identity server decided to be evil, +however it would significantly raise the resource requirements to run an evil +identity server. + +Discussion and a walk-through of what a client/identity-server interaction would +look like are documented [in this Github +comment](https://github.com/matrix-org/matrix-doc/pull/2134#discussion_r298691748). + +Additionally, a radical model was also considered where the first portion of +the above scheme was done with an identity server, and the second would be done +with various homeservers who originally reported the 3PID to the identity +server. While interesting and a more decentralised model, some attacks are +still possible if the identity server is running an evil homeserver which it +can direct the client to send its hashes to. Discussion on this matter has +taken place in the MSC-specific room [starting at this +message](https://matrix.to/#/!LlraCeVuFgMaxvRySN:amorgan.xyz/$4wzTSsspbLVa6Lx5cBq6toh6P3TY3YnoxALZuO8n9gk?via=amorgan.xyz&via=matrix.org&via=matrix.vgorcum.com). ## Conclusion -This proposal outlines an effective method to stop bulk collection of user's +This proposal outlines a simple method to stop bulk collection of user's contact lists and their social graphs without any disastrous side effects. All functionality which depends on the lookup service should continue to function unhindered by the use of hashes. From 30dcc28f9b7280f88cc6898182ffa3891c1b18e7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 4 Jul 2019 18:38:31 +0100 Subject: [PATCH 379/497] try & clarify that HS signature isn't the only acceptable auth for unbind --- proposals/2140-terms-of-service-2.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index dbdb19f6..2f6c88d8 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -91,15 +91,16 @@ possible. OpenID authentication in the IS API will work the same as in the Integration Manager API, as specified in [MSC1961](https://github.com/matrix-org/matrix-doc/issues/1961). -When clients supply an identity server to the Homeserver in order for the Homeserver -to make calls to the IS on its behalf, it must also supply its access token for the -Identity Server alongside in the `is_token` key of the same JSON object. That is, -in the main request object for a `requestToken` request and in the `threepidCreds` -object when supplying 3PID credentials (eg. in the `m.email.identity` UI auth stage). -Exceptions to this are any requests where the only IS operation the Homeserver may -perform is unbinding, ie. `/_matrix/client/r0/account/deactivate` and -`/_matrix/client/r0/account/3pid/delete`, in which case the unbind is authenticated -by a signed request from the Homeserver. +When clients supply an identity server to the Homeserver in order for the +Homeserver to make calls to the IS on its behalf, it must also supply its +access token for the Identity Server alongside in the `is_token` key of the +same JSON object. That is, in the main request object for a `requestToken` +request and in the `threepidCreds` object when supplying 3PID credentials (eg. +in the `m.email.identity` UI auth stage). Exceptions to this are any requests +where the only IS operation the Homeserver may perform is unbinding, ie. +`/_matrix/client/r0/account/deactivate` and +`/_matrix/client/r0/account/3pid/delete`, in which case the unbind will be +authenticated by a signed request from the Homeserver. ### HS Register API From 370266942488f56f1fb4aab5d4bab1e3b0989d9d Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 5 Jul 2019 15:59:29 +0100 Subject: [PATCH 380/497] update from comments --- proposals/2134-identity-hash-lookup.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 76f527cb..33bda297 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -10,11 +10,16 @@ not. If the 3PID is hashed, the identity server could not determine the address unless it has already seen that address in plain-text during a previous call of -the /bind mechanism (without significant resources to reverse the hashes). +the [/bind +mechanism](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-3pid-bind) +(without significant resources to reverse the hashes). -This proposal thus calls for the Identity Service API's /lookup endpoint to use -hashed 3PIDs instead of their plain-text counterparts, which will leak less -data to identity servers. +This proposal thus calls for the Identity Service API's +[/lookup](https://matrix.org/docs/spec/identity_service/r0.2.1#get-matrix-identity-api-v1-lookup) +endpoint to use hashed 3PIDs instead of their plain-text counterparts (and to +deprecate both it and +[/bulk_lookup](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-bulk-lookup)), +which will leak less data to identity servers. ## Proposal @@ -161,14 +166,16 @@ IDs of those that match: The client can now display which 3PIDs link to which Matrix IDs. -No parameter changes will be made to /bind as part of this proposal. +No parameter changes will be made to +[/bind](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-3pid-bind) +as part of this proposal. ## Fallback considerations `v1` versions of these endpoints may be disabled at the discretion of the implementation, and should return a 403 `M_FORBIDDEN` error if so. -If an identity server is too old and a HTTP 404, 405 or 501 is received when +If an identity server is too old and a HTTP 400 or 404 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. However, clients should be aware that plain-text 3PIDs are required for the `v1` endpoint, and SHOULD ask for user consent to send 3PIDs in plain-text, and From bf8a1e5d5f14855470ba607976ed4ae4f1c1898c Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 5 Jul 2019 18:11:42 +0100 Subject: [PATCH 381/497] Add way to get the HS to bind/unbind existing 3pids --- proposals/2140-terms-of-service-2.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 2f6c88d8..e203ffcf 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -41,8 +41,14 @@ following convention from [MSC2134](https://github.com/matrix-org/matrix-doc/issues/2134). This proposal introduces: + * A v2 API prefix, with authentication, for the Identity Service * The `$prefix/terms` endpoint * The `m.accepted_terms` section in account data + * `POST /_matrix/client/r0/account/3pid/unbind` endpoints on the client/server + API + +This proposal removes: + * The `bind_email` and `bind_msisdn` on the Homeserver `/register` endpoint This proposal relies on both Integration Managers and Identity Servers being able to identity users by their MXID and store the fact that a given MXID has @@ -252,6 +258,20 @@ in the current login sessions is: * If the set of documents pending agreement was non-empty, Perform a `POST $prefix/terms` request to the servcie with these documents. +### `POST /_matrix/client/r0/account/3pid/unbind` + +A client uses this client/server API endpoint to request that the Homeserver +removes the given 3PID from the given Identity Server, or all Identity Servers. +Takes parameters the same parameters as +`POST /_matrix/client/r0/account/3pid/delete`, ie. `id_server`, `medium`, +`address` and the newly added `is_token`. + +Returns the same as `POST /_matrix/client/r0/account/3pid/delete`. + +Clients may add IS bindings for 3PIDs that already exist on the user's +Homeserver account by using the `POST /_matrix/client/r0/account/3pid` +to re-add the 3PID. + ## Tradeoffs The Identity Service API previously did not require authentication, and OpenID From 701d340da18b9fbfdc98f4f5aff1f8e6ea2e7f54 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 5 Jul 2019 19:00:15 +0100 Subject: [PATCH 382/497] Remove exception for request/submitToken --- proposals/2140-terms-of-service-2.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index e203ffcf..9608093a 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -68,7 +68,6 @@ be dropped from all endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception of: * `/_matrix/identity/v2` - * any `requestToken` or `submitToken` endpoint * The new `$prefix/account/register` endpoint * The new `GET /_matrix/identity/v2/terms` * `$prefix/logout` @@ -77,13 +76,6 @@ of: This indicates that the user must authenticate with OpenID and supply a valid `access_token`. -`requestToken` and `submitToken` endpoints are excluded from the auth check -because they are used in the registration process before the user has an MXID -and therefore cannot log in with OpenID. It is up to the IS to manage its -privacy obligations appropriately when fulfilling these requests, bearing in -mind that the user has not explicitly indicated their agreement to any -documents, and may abort the registration process without doing so. - All other endpoints require authentication by the client supplying an access token either via an `Authorization` header with a `Bearer` token or an `access_token` query parameter. From dd8a6549c9bfb149c40ef8e83d978c624590a003 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 8 Jul 2019 11:55:37 +0100 Subject: [PATCH 383/497] Address review comments --- proposals/2134-identity-hash-lookup.md | 169 ++++++++++++++----------- 1 file changed, 93 insertions(+), 76 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 33bda297..f1df605f 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -9,10 +9,12 @@ that email address or phone number is already known by the identity server or not. If the 3PID is hashed, the identity server could not determine the address -unless it has already seen that address in plain-text during a previous call of -the [/bind +unless it has already seen that address in plain-text during a previous call +of the [/bind mechanism](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-3pid-bind) -(without significant resources to reverse the hashes). +(without significant resources to reverse the hashes). This helps prevent +bulk collection of user's contact lists by the identity server and reduces +its ability to build social graphs. This proposal thus calls for the Identity Service API's [/lookup](https://matrix.org/docs/spec/identity_service/r0.2.1#get-matrix-identity-api-v1-lookup) @@ -25,7 +27,7 @@ which will leak less data to identity servers. This proposal suggests making changes to the Identity Service API's lookup endpoints. Instead, this proposal consolidates them into a single `/lookup` -endpoint. Additionally, the endpoint should be on a `v2` path, to avoid +endpoint. Additionally, the endpoint is to be on a `v2` path, to avoid confusion with the original `/lookup`. We also drop the `/api` in order to preserve consistency across other endpoints: @@ -40,11 +42,13 @@ The following back-and-forth occurs between the client and server. Let's say the client wants to check the following 3PIDs: - alice@example.com - bob@example.com - carl@example.com - +1 234 567 8910 - denny@example.com +``` +alice@example.com +bob@example.com +carl@example.com ++1 234 567 8910 +denny@example.com +``` The client will hash each 3PID as a concatenation of the medium and address, separated by a space and a pepper appended to the end. Note that phone numbers @@ -52,55 +56,59 @@ should be formatted as defined by https://matrix.org/docs/spec/appendices#pstn-phone-numbers, before being hashed). First the client must prepend the medium to the address: - "alice@example.com" -> "email alice@example.com" - "bob@example.com" -> "email bob@example.com" - "carl@example.com" -> "email carl@example.com" - "+1 234 567 8910" -> "msisdn 12345678910" - "denny@example.com" -> "email denny@example.com" +``` +"alice@example.com" -> "email alice@example.com" +"bob@example.com" -> "email bob@example.com" +"carl@example.com" -> "email carl@example.com" +"+1 234 567 8910" -> "msisdn 12345678910" +"denny@example.com" -> "email denny@example.com" +``` Hashes must be peppered in order to reduce both the information a client gains during the process, and attacks the identity server can perform (namely sending a rainbow table of hashes back in the response to `/lookup`). In order for clients to know the pepper and hashing algorithm they should use, -Identity Servers must make the information available on the `/hash_details` +Identity servers must make the information available on the `/hash_details` endpoint: - GET /_matrix/identity/v2/hash_details +``` +GET /_matrix/identity/v2/hash_details - { - "lookup_pepper": "matrixrocks", - "algorithms": ["sha256"] - } +{ + "lookup_pepper": "matrixrocks", + "algorithms": ["sha256"] +} +``` The name `lookup_pepper` was chosen in order to account for pepper values being returned for other endpoints in the future. The contents of `lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]*`. - The client should append the pepper to the end of the 3pid string before - hashing. +``` +The client should append the pepper to the end of the 3PID string before +hashing. - "email alice@example.com" -> "email alice@example.commatrixrocks" - "email bob@example.com" -> "email bob@example.commatrixrocks" - "email carl@example.com" -> "email carl@example.commatrixrocks" - "msisdn 12345678910" -> "msisdn 12345678910matrixrocks" - "email denny@example.com" -> "email denny@example.commatrixrocks" +"email alice@example.com" -> "email alice@example.commatrixrocks" +"email bob@example.com" -> "email bob@example.commatrixrocks" +"email carl@example.com" -> "email carl@example.commatrixrocks" +"msisdn 12345678910" -> "msisdn 12345678910matrixrocks" +"email denny@example.com" -> "email denny@example.commatrixrocks" +``` Clients SHOULD request this endpoint each time before performing a lookup, to handle identity servers which may rotate their pepper values frequently. Clients MUST choose one of the given hash algorithms to encrypt the 3PID during lookup. -Note that possible hashing algorithms will be defined in the Matrix -specification, and an Identity Server can choose to implement one or all of -them. Later versions of the specification may deprecate algorithms when -necessary. Currently the only listed hashing algorithm is SHA-256 as defined by -[RFC 4634](https://tools.ietf.org/html/rfc4634) and Identity Servers and -clients MUST agree to its use with the string `sha256`. SHA-256 was chosen as -it is currently used throughout the Matrix spec, as well as its properties of -being quick to hash. While this reduces the resources necessary to generate a -rainbow table for attackers, a fast hash is necessary if particularly slow -mobile clients are going to be hashing thousands of contact details. +At a minimum, clients and identity servers MUST support SHA-256 as defined by +[RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the +`algorithm` value `"sha256"`. SHA-256 was chosen as it is currently used +throughout the Matrix spec, as well as its properties of being quick to hash. +While this reduces the resources necessary to generate a rainbow table for +attackers, a fast hash is necessary if particularly slow mobile clients are +going to be hashing thousands of contact details. Other algorithms can be +negotiated by the client and server at their discretion. When performing a lookup, the pepper and hashing algorithm the client used must be part of the request body. If they do not match what the server has on file @@ -112,20 +120,23 @@ server. If the algorithm does not match the server's, the server should return a `400 M_INVALID_PARAM`. If the pepper does not match the server's, the server should -return a new error code, 400 `M_INVALID_PEPPER`. A new error code is not +return a new error code, `400 M_INVALID_PEPPER`. A new error code is not defined for an invalid algorithm as that is considered a client bug. -Each of these error responses should contain the correct `algorithm` and -`lookup_pepper` fields. This is to prevent the client from needing to query -`/hash_details` again, thus saving a round-trip. An example response to an -incorrect pepper would be: +The `M_INVALID_PEPPER` error response should contain the correct `algorithm` +and `lookup_pepper` fields. This is to prevent the client from needing to +query `/hash_details` again, thus saving a round-trip. `M_INVALID_PARAM` does +not include these fields. An example response to an incorrect pepper would +be: - { - "error": "Incorrect value for lookup_pepper", - "errcode": "M_INVALID_PEPPER", - "algorithm": "sha256", - "lookup_pepper": "matrixrocks" - } +``` +{ + "error": "Incorrect value for lookup_pepper", + "errcode": "M_INVALID_PEPPER", + "algorithm": "sha256", + "lookup_pepper": "matrixrocks" +} +``` Now comes time for the lookup. Note that the resulting hash digest MUST be encoded in URL-safe unpadded base64 (similar to [room version 4's event @@ -133,36 +144,40 @@ IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). Once hashing has been performed using the defined hashing algorithm, the client sends each hash in an array. - "email alice@example.commatrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" - "email bob@example.commatrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" - "email carl@example.commatrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" - "msisdn 12345678910matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" - "email denny@example.commatrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" +``` +"email alice@example.commatrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" +"email bob@example.commatrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" +"email carl@example.commatrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" +"msisdn 12345678910matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" +"email denny@example.commatrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" - POST /_matrix/identity/v2/lookup +POST /_matrix/identity/v2/lookup - { - "hashes": [ - "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs", - "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE", - "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw", - "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens", - "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" - ], - "algorithm": "sha256", - "pepper": "matrixrocks" - } +{ + "hashes": [ + "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs", + "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE", + "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw", + "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens", + "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" + ], + "algorithm": "sha256", + "pepper": "matrixrocks" +} +``` The identity server, upon receiving these hashes, can simply compare against the hashes of the 3PIDs it stores. The server then responds with the Matrix IDs of those that match: - { - "mappings": { - "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs": "@alice:example.com", - "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens": "@fred:example.com" - } - } +``` +{ + "mappings": { + "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs": "@alice:example.com", + "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens": "@fred:example.com" + } +} +``` The client can now display which 3PIDs link to which Matrix IDs. @@ -173,7 +188,7 @@ as part of this proposal. ## Fallback considerations `v1` versions of these endpoints may be disabled at the discretion of the -implementation, and should return a 403 `M_FORBIDDEN` error if so. +implementation, and should return a `403 M_FORBIDDEN` error if so. If an identity server is too old and a HTTP 400 or 404 is received when accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. @@ -186,11 +201,13 @@ be clear about where they are being sent to. * There is a small cost incurred by performing hashes before requests, but this is outweighed by the privacy implications of sending plain-text addresses. -## Potential issues +## Security Considerations -Hashes are still reversible with a rainbow table, but hopefully the provided -pepper, which can be rotated by identity servers at will, should help mitigate -this to some extent. +Hashes are still reversible with a rainbow table, but the provided pepper, +which can be rotated by identity servers at will, should help mitigate this. +Phone numbers (with their relatively short possible address space of 12 +numbers), short email addresses, and addresses of both type that have been +leaked in database dumps are more susceptible to hash reversal. Additionally, this proposal does not stop an identity server from storing plain-text 3PIDs. There is a GDPR argument in keeping email addresses, such From 1963a24832eeb4539fbcdc7449cc0bded4bfff13 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 8 Jul 2019 13:27:38 +0100 Subject: [PATCH 384/497] fix attacks paragraph --- proposals/2134-identity-hash-lookup.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index f1df605f..2ac074af 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -64,9 +64,12 @@ hashed). First the client must prepend the medium to the address: "denny@example.com" -> "email denny@example.com" ``` -Hashes must be peppered in order to reduce both the information a client gains -during the process, and attacks the identity server can perform (namely sending -a rainbow table of hashes back in the response to `/lookup`). +Hashes must be peppered in order to reduce both the information an identity +server gains during the process, and attacks the client can perform. Clients +will have to generate a full rainbow table specific to the set pepper to +obtain all registered MXIDs, while the server has to generate a full rainbow +table with the specific pepper to get the plaintext 3pids for non-matrix +users. In order for clients to know the pepper and hashing algorithm they should use, Identity servers must make the information available on the `/hash_details` From ed67e26037650b2781661bbe78f3593209778c5c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 8 Jul 2019 17:02:33 +0100 Subject: [PATCH 385/497] pepper must not be an empty string, append medium --- proposals/2134-identity-hash-lookup.md | 45 +++++++++++++++----------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 2ac074af..18ecece7 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -54,14 +54,14 @@ The client will hash each 3PID as a concatenation of the medium and address, separated by a space and a pepper appended to the end. Note that phone numbers should be formatted as defined by https://matrix.org/docs/spec/appendices#pstn-phone-numbers, before being -hashed). First the client must prepend the medium to the address: +hashed). First the client must append the medium to the address: ``` -"alice@example.com" -> "email alice@example.com" -"bob@example.com" -> "email bob@example.com" -"carl@example.com" -> "email carl@example.com" -"+1 234 567 8910" -> "msisdn 12345678910" -"denny@example.com" -> "email denny@example.com" +"alice@example.com" -> "alice@example.com email" +"bob@example.com" -> "bob@example.com email" +"carl@example.com" -> "carl@example.com email" +"+1 234 567 8910" -> "12345678910 msisdn" +"denny@example.com" -> "denny@example.com email" ``` Hashes must be peppered in order to reduce both the information an identity @@ -84,19 +84,20 @@ GET /_matrix/identity/v2/hash_details } ``` -The name `lookup_pepper` was chosen in order to account for pepper values being -returned for other endpoints in the future. The contents of `lookup_pepper` -MUST match the regular expression `[a-zA-Z0-9]*`. +The name `lookup_pepper` was chosen in order to account for pepper values +being returned for other endpoints in the future. The contents of +`lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+`. If +`lookup_pepper` is an empty string, clients MUST cease the lookup operation. ``` The client should append the pepper to the end of the 3PID string before hashing. -"email alice@example.com" -> "email alice@example.commatrixrocks" -"email bob@example.com" -> "email bob@example.commatrixrocks" -"email carl@example.com" -> "email carl@example.commatrixrocks" -"msisdn 12345678910" -> "msisdn 12345678910matrixrocks" -"email denny@example.com" -> "email denny@example.commatrixrocks" +"alice@example.com email" -> "alice@example.com emailmatrixrocks" +"bob@example.com email" -> "bob@example.com emailmatrixrocks" +"carl@example.com email" -> "carl@example.com emailmatrixrocks" +"12345678910 msdisn" -> "12345678910 msisdnmatrixrocks" +"denny@example.com email" -> "denny@example.com emailmatrixrocks" ``` Clients SHOULD request this endpoint each time before performing a lookup, to @@ -148,11 +149,13 @@ performed using the defined hashing algorithm, the client sends each hash in an array. ``` -"email alice@example.commatrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" -"email bob@example.commatrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" -"email carl@example.commatrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" -"msisdn 12345678910matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" -"email denny@example.commatrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" +NOTE: Hashes are not real values + +"alice@example.com emailmatrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" +"bob@example.com emailmatrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" +"carl@example.com emailmatrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" +"12345678910 msisdnmatrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" +"denny@example.com emailmatrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" POST /_matrix/identity/v2/lookup @@ -212,6 +215,10 @@ Phone numbers (with their relatively short possible address space of 12 numbers), short email addresses, and addresses of both type that have been leaked in database dumps are more susceptible to hash reversal. +Mediums and peppers are appended to the address as to prevent a common prefix +for each plain-text string, which prevents attackers from pre-computing bits +of a stream cipher. + Additionally, this proposal does not stop an identity server from storing plain-text 3PIDs. There is a GDPR argument in keeping email addresses, such that if a breach happens, users must be notified of such. Ideally this would be From 9ed19a37ada6dd085ecc717b2d80d01bc369acd0 Mon Sep 17 00:00:00 2001 From: Alexey Andreyev Date: Mon, 8 Jul 2019 16:30:54 +0300 Subject: [PATCH 386/497] Client-server: Fix upload keys example request Contributes to #1733 Signed-off-by: Alexey Andreyev --- api/client-server/definitions/device_keys.yaml | 2 +- api/client-server/keys.yaml | 4 ++-- api/server-server/user_keys.yaml | 4 ++-- changelogs/client_server/newsfragments/2157.clarification | 1 + changelogs/server_server/newsfragments/2157.clarification | 1 + 5 files changed, 7 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2157.clarification create mode 100644 changelogs/server_server/newsfragments/2157.clarification diff --git a/api/client-server/definitions/device_keys.yaml b/api/client-server/definitions/device_keys.yaml index 888c93a4..41504aba 100644 --- a/api/client-server/definitions/device_keys.yaml +++ b/api/client-server/definitions/device_keys.yaml @@ -33,7 +33,7 @@ properties: type: string description: |- The encryption algorithms supported by this device. - example: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"] + example: ["m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2"] keys: type: object description: |- diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index cce0edca..69e39def 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -217,8 +217,8 @@ paths: "user_id": "@alice:example.com", "device_id": "JLAFKJWSCS", "algorithms": [ - "m.olm.v1.curve25519-aes-sha256", - "m.megolm.v1.aes-sha" + "m.olm.v1.curve25519-aes-sha2", + "m.megolm.v1.aes-sha2" ], "keys": { "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index ea59de2d..93237d80 100644 --- a/api/server-server/user_keys.yaml +++ b/api/server-server/user_keys.yaml @@ -180,8 +180,8 @@ paths: "user_id": "@alice:example.com", "device_id": "JLAFKJWSCS", "algorithms": [ - "m.olm.v1.curve25519-aes-sha256", - "m.megolm.v1.aes-sha" + "m.olm.v1.curve25519-aes-sha2", + "m.megolm.v1.aes-sha2" ], "keys": { "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", diff --git a/changelogs/client_server/newsfragments/2157.clarification b/changelogs/client_server/newsfragments/2157.clarification new file mode 100644 index 00000000..5c1d549b --- /dev/null +++ b/changelogs/client_server/newsfragments/2157.clarification @@ -0,0 +1 @@ +Clarify the encryption algorithms supported by the device of the device keys example. diff --git a/changelogs/server_server/newsfragments/2157.clarification b/changelogs/server_server/newsfragments/2157.clarification new file mode 100644 index 00000000..0acf7495 --- /dev/null +++ b/changelogs/server_server/newsfragments/2157.clarification @@ -0,0 +1 @@ + Clarify the encryption algorithms supported by the device of the user keys query example. From 5df86dabe0f58f8552a6c5f0839664b547bd6045 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Tue, 9 Jul 2019 01:12:07 -0700 Subject: [PATCH 387/497] Clarify the purpose of reference hashes. The server-server specification describes a "reference hash" of an event and how to calculate it, but is otherwise not mentioned anywhere else in the document. This change adds a sentence to explain that they are used for event identifiers in later room versions, which are described in other documents. Signed-off-by: Jimmy Cuadra --- changelogs/server_server/newsfragments/2159.clarification | 1 + specification/server_server_api.rst | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/2159.clarification diff --git a/changelogs/server_server/newsfragments/2159.clarification b/changelogs/server_server/newsfragments/2159.clarification new file mode 100644 index 00000000..d7b79ccf --- /dev/null +++ b/changelogs/server_server/newsfragments/2159.clarification @@ -0,0 +1 @@ +Clarify the purpose of reference hashes. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 03c624ab..2e96dc85 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1134,7 +1134,8 @@ Calculating the reference hash for an event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The *reference hash* of an event covers the essential fields of an event, -including content hashes. It is calculated as follows. +including content hashes. It is used for event identifiers in room versions 3 and +higher. It is calculated as follows. 1. The event is put through the redaction algorithm. From 52643a92c6981e04e68d9d5b4be34edff1509d9c Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 9 Jul 2019 17:54:45 +0100 Subject: [PATCH 388/497] Less confusing wording on Application Service's Legacy Routes (#2160) https://matrix.org/docs/spec/application_service/r0.1.1#legacy-routes The "becomes" wording made it a little bit confusing for which was the new route and which was the old. --- .../newsfragments/2160.clarification | 1 + specification/application_service_api.rst | 16 ++++++++-------- 2 files changed, 9 insertions(+), 8 deletions(-) create mode 100644 changelogs/application_service/newsfragments/2160.clarification diff --git a/changelogs/application_service/newsfragments/2160.clarification b/changelogs/application_service/newsfragments/2160.clarification new file mode 100644 index 00000000..3e9c1c02 --- /dev/null +++ b/changelogs/application_service/newsfragments/2160.clarification @@ -0,0 +1 @@ +Clearer wording for the legacy routes section. diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 11a07839..302f0980 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -213,14 +213,14 @@ should fall back to the older endpoints for the application service. The older endpoints have the exact same request body and response format, they just belong at a different path. The equivalent path for each is as follows: -* ``/_matrix/app/v1/transactions/{txnId}`` becomes ``/transactions/{txnId}`` -* ``/_matrix/app/v1/users/{userId}`` becomes ``/users/{userId}`` -* ``/_matrix/app/v1/rooms/{roomAlias}`` becomes ``/rooms/{roomAlias}`` -* ``/_matrix/app/v1/thirdparty/protocol/{protocol}`` becomes ``/_matrix/app/unstable/thirdparty/protocol/{protocol}`` -* ``/_matrix/app/v1/thirdparty/user/{user}`` becomes ``/_matrix/app/unstable/thirdparty/user/{user}`` -* ``/_matrix/app/v1/thirdparty/location/{location}`` becomes ``/_matrix/app/unstable/thirdparty/location/{location}`` -* ``/_matrix/app/v1/thirdparty/user`` becomes ``/_matrix/app/unstable/thirdparty/user`` -* ``/_matrix/app/v1/thirdparty/location`` becomes ``/_matrix/app/unstable/thirdparty/location`` +* ``/_matrix/app/v1/transactions/{txnId}`` should fall back to ``/transactions/{txnId}`` +* ``/_matrix/app/v1/users/{userId}`` should fall back to ``/users/{userId}`` +* ``/_matrix/app/v1/rooms/{roomAlias}`` should fall back to ``/rooms/{roomAlias}`` +* ``/_matrix/app/v1/thirdparty/protocol/{protocol}`` should fall back to ``/_matrix/app/unstable/thirdparty/protocol/{protocol}`` +* ``/_matrix/app/v1/thirdparty/user/{user}`` should fall back to ``/_matrix/app/unstable/thirdparty/user/{user}`` +* ``/_matrix/app/v1/thirdparty/location/{location}`` should fall back to ``/_matrix/app/unstable/thirdparty/location/{location}`` +* ``/_matrix/app/v1/thirdparty/user`` should fall back to ``/_matrix/app/unstable/thirdparty/user`` +* ``/_matrix/app/v1/thirdparty/location`` should fall back to ``/_matrix/app/unstable/thirdparty/location`` Homeservers should periodically try again for the newer endpoints because the application service may have been updated. From a3d2d14dae745b5460809b62b1fa46027154ae90 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Tue, 9 Jul 2019 15:25:23 -0700 Subject: [PATCH 389/497] Rephrase explanation of the purpose of reference hashes and link to the room version spec. Signed-off-by: Jimmy Cuadra --- specification/server_server_api.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 2e96dc85..62f6916a 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1134,8 +1134,9 @@ Calculating the reference hash for an event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The *reference hash* of an event covers the essential fields of an event, -including content hashes. It is used for event identifiers in room versions 3 and -higher. It is calculated as follows. +including content hashes. It is used for event identifiers in some room versions. +See the `room version specification`_ for more information. It is calculated as +follows. 1. The event is put through the redaction algorithm. From 9bb6ad80d1c01e6d1588cf77f05fc84af1260e98 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 10 Jul 2019 16:13:38 +0100 Subject: [PATCH 390/497] typo --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 9608093a..fa89f603 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -248,7 +248,7 @@ in the current login sessions is: token from the Homeserver and submit this token to the `register` endpoint. Store the resulting access token. * If the set of documents pending agreement was non-empty, Perform a - `POST $prefix/terms` request to the servcie with these documents. + `POST $prefix/terms` request to the service with these documents. ### `POST /_matrix/client/r0/account/3pid/unbind` From 3514437d24399462fef62b9c32e15a57eefe13fd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 12 Jul 2019 11:37:38 +0100 Subject: [PATCH 391/497] Ability for client/server to decide on no hashing --- proposals/2134-identity-hash-lookup.md | 31 +++++++++++++++++--------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 18ecece7..3f869f0d 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -86,8 +86,9 @@ GET /_matrix/identity/v2/hash_details The name `lookup_pepper` was chosen in order to account for pepper values being returned for other endpoints in the future. The contents of -`lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+`. If -`lookup_pepper` is an empty string, clients MUST cease the lookup operation. +`lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+` (unless no +hashing is being performed, as described below). If `lookup_pepper` is an +empty string, clients MUST cease the lookup operation. ``` The client should append the pepper to the end of the 3PID string before @@ -102,8 +103,8 @@ hashing. Clients SHOULD request this endpoint each time before performing a lookup, to handle identity servers which may rotate their pepper values frequently. -Clients MUST choose one of the given hash algorithms to encrypt the 3PID during -lookup. +Clients MUST choose one of the given hash algorithms to encrypt the 3PID +during lookup. At a minimum, clients and identity servers MUST support SHA-256 as defined by [RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the @@ -114,13 +115,21 @@ attackers, a fast hash is necessary if particularly slow mobile clients are going to be hashing thousands of contact details. Other algorithms can be negotiated by the client and server at their discretion. -When performing a lookup, the pepper and hashing algorithm the client used must -be part of the request body. If they do not match what the server has on file -(which may be the case if the pepper was changed right after the client's -request for it), then the server must inform the client that they need to query -the hash details again, instead of just returning an empty response, which -clients would assume to mean that no contacts are registered on that identity -server. +There are certain situations when an identity server cannot be expected to +compare hashed 3PID values; When a server is connected to a backend provider +such as LDAP, there is no way for the identity server to efficiently pull all +of the addresses and hash them. For this case, the `algorithm` field of `GET +/hash_details` may be set to `"none"`, and `lookup_pepper` will be an empty +string. No hashing will be performed if the client and server decide on this, +and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. + +When performing a lookup, the pepper and hashing algorithm the client used +must be part of the request body (even when using the `"none"` algorithm +value). If they do not match what the server has on file (which may be the +case if the pepper was changed right after the client's request for it), then +the server must inform the client that they need to query the hash details +again, instead of just returning an empty response, which clients would +assume to mean that no contacts are registered on that identity server. If the algorithm does not match the server's, the server should return a `400 M_INVALID_PARAM`. If the pepper does not match the server's, the server should From f474b31f5f8b74604ae652ec62eb3090615a80ee Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 12 Jul 2019 11:54:45 +0100 Subject: [PATCH 392/497] typo Co-Authored-By: J. Ryan Stinnett --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index fa89f603..b840932c 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -51,7 +51,7 @@ This proposal removes: * The `bind_email` and `bind_msisdn` on the Homeserver `/register` endpoint This proposal relies on both Integration Managers and Identity Servers being -able to identity users by their MXID and store the fact that a given MXID has +able to identify users by their MXID and store the fact that a given MXID has indicated that they accept the terms given. Integration Managers already identify users in this way by authenticating them using the OpenID endpoint on the Homeserver. This proposal introduces the same mechanism to Identity Servers From 6e061b1baf8e03de4b01525b9aa39d4eb7e82c8b Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 12 Jul 2019 11:55:11 +0100 Subject: [PATCH 393/497] unnecessary capital Co-Authored-By: J. Ryan Stinnett --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index b840932c..21caa305 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -268,7 +268,7 @@ to re-add the 3PID. The Identity Service API previously did not require authentication, and OpenID is reasonably complex, adding a significant burden to both clients and servers. -A custom HTTP Header was also considered that could be added to assert that the +A custom HTTP header was also considered that could be added to assert that the client agrees to a particular set of terms. We decided against this in favour of re-using existing primitives that already exist in the Matrix ecosystem. Custom HTTP Headers are not used anywhere else within Matrix. This also gives a From 25a47afa329d39538b0856a1b6df3b4bec293197 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 12 Jul 2019 11:55:40 +0100 Subject: [PATCH 394/497] unnecessary capital mk. 2 Co-Authored-By: J. Ryan Stinnett --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 21caa305..eb4fd75c 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -271,7 +271,7 @@ is reasonably complex, adding a significant burden to both clients and servers. A custom HTTP header was also considered that could be added to assert that the client agrees to a particular set of terms. We decided against this in favour of re-using existing primitives that already exist in the Matrix ecosystem. -Custom HTTP Headers are not used anywhere else within Matrix. This also gives a +Custom HTTP headers are not used anywhere else within Matrix. This also gives a very simple and natural way for ISes to enforce that users may only bind 3PIDs to their own MXIDs. From 78d46b289097f67adf27b35fcc14dd1fdc0ae379 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Sun, 14 Jul 2019 20:20:09 +0100 Subject: [PATCH 395/497] Proposal to move the `redacts` key to a sane place --- proposals/2174-move-redacts-key.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 proposals/2174-move-redacts-key.md diff --git a/proposals/2174-move-redacts-key.md b/proposals/2174-move-redacts-key.md new file mode 100644 index 00000000..d93deaf5 --- /dev/null +++ b/proposals/2174-move-redacts-key.md @@ -0,0 +1,8 @@ +# MSC2174: move the `redacts` property to `content` + +`m.room.redaction` events currently have an *event-level* property `redacts` +which gives the event ID of the event being redacted. + +The presence of this field at the event level, rather than under the `content` +key, is anomalous. This MSC proposes that, in a future room version, the +`redacts` property be moved under the `content` key. From b09d48a9f764baf0624757e06b325c001215356a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Sun, 14 Jul 2019 20:22:39 +0100 Subject: [PATCH 396/497] Spec link --- proposals/2174-move-redacts-key.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/2174-move-redacts-key.md b/proposals/2174-move-redacts-key.md index d93deaf5..ca3083a6 100644 --- a/proposals/2174-move-redacts-key.md +++ b/proposals/2174-move-redacts-key.md @@ -1,7 +1,8 @@ # MSC2174: move the `redacts` property to `content` -`m.room.redaction` events currently have an *event-level* property `redacts` -which gives the event ID of the event being redacted. +[`m.room.redaction`](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-redaction) +events currently have an *event-level* property `redacts` which gives the event +ID of the event being redacted. The presence of this field at the event level, rather than under the `content` key, is anomalous. This MSC proposes that, in a future room version, the From a1de6ff63445c0e59233875a9c53eee6efc9a9e5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 15 Jul 2019 10:20:25 +0100 Subject: [PATCH 397/497] Hopefully clarify some bits --- proposals/2140-terms-of-service-2.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index eb4fd75c..1120373f 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -76,9 +76,8 @@ of: This indicates that the user must authenticate with OpenID and supply a valid `access_token`. -All other endpoints require authentication by the client supplying an access token -either via an `Authorization` header with a `Bearer` token or an `access_token` -query parameter. +Clients authenticate either via an `Authorization` header with a `Bearer` token +or an `access_token` query parameter. The existing endpoints under `/_matrix/identity/api/v1/` continue to be unauthenticated but will be deprecated. ISes may support the old v1 API for as @@ -142,6 +141,17 @@ to use the service. Its response is similar to the structure used in the "name": "Conditions d'utilisation", "url": "https://example.org/somewhere/terms-2.0-fr.html" } + }, + "privacy_policy": { + "version": "1.2", + "en": { + "name": "Privacy Policy", + "url": "https://example.org/somewhere/privaacy-1.2-en.html" + }, + "fr": { + "name": "Politique de confidentialité", + "url": "https://example.org/somewhere/privacy-1.2-fr.html" + } } } } From d9269b084f6fbb6e95364c9bb919596919f3a3f3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 15 Jul 2019 16:58:24 +0100 Subject: [PATCH 398/497] Exclude pubkey endpoints from auth --- proposals/2140-terms-of-service-2.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 1120373f..557376cc 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -68,6 +68,7 @@ be dropped from all endpoints. Any request to any endpoint within `/_matrix/identity/v2`, with the exception of: * `/_matrix/identity/v2` + * `/_matrix/identity/v2/pubkey/*` * The new `$prefix/account/register` endpoint * The new `GET /_matrix/identity/v2/terms` * `$prefix/logout` From 1f786ae6dc2f74069cd008fe69fc2b08ac8be3dc Mon Sep 17 00:00:00 2001 From: Sorunome Date: Mon, 15 Jul 2019 20:52:24 +0200 Subject: [PATCH 399/497] commit image into repo, fix typo --- proposals/2010-spoilers.md | 4 ++-- proposals/images/2010-spoiler-example.gif | Bin 0 -> 55001 bytes 2 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 proposals/images/2010-spoiler-example.gif diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index df7fd6c1..cf969902 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -5,7 +5,7 @@ For example, when discussing a new movie or a TV series, not everyone might have In such cases it would make sense to add a spoiler so that only those who have seen the movie or don't mind spoilers read the content. Another example would be e.g. in mental health communities where certain people have certain -triggers. People could put talking about abuse or thelike into a spoiler, to not accidentally +triggers. People could put talking about abuse or the like into a spoiler, to not accidentally trigger anyone just reading along the conversation. Furthermore this is helpful for bridging to other networks that already have a spoiler feature. @@ -20,7 +20,7 @@ It adds a new attribute, `data-mx-spoiler`, to the `` tag. If the attribut contents of the span tag should be rendered as a spoiler. Optionally, you can specify a reason for the spoiler by setting the attribute string. It could be rendered, for example, similar to this: -![Spoiler rendering idea](https://user-images.githubusercontent.com/2433620/59299700-95063480-8c8d-11e9-9348-3e2c8bc94bdc.gif) +![Spoiler rendering idea](images/2010-spoiler-example.gif) To preserve the semantics of a spoiler in the plaintext fallback it is recommended to upload the contents of the spoiler as a text file and then link this: `[Spoiler](mxc://someserver/somefile)` and diff --git a/proposals/images/2010-spoiler-example.gif b/proposals/images/2010-spoiler-example.gif new file mode 100644 index 0000000000000000000000000000000000000000..3716bd7755940ea959cab8d162b90e365358a181 GIT binary patch literal 55001 zcmeFYXH=7KzqXl#gcOnxI#M)9ZxTSN0-<*dAiWq6>0szxLg+;Zy$J;A)d*4r4WOVD z0YNDOVnILwv4HruFg$zD?7ioGXTHr^^X199KV+?Z$V#s3cPH0z9;czPfvTEY5%4PD z2T&ex@;C-Sp-{9Wij|FnU4fm8hoAe@8E#E3UVb570U=&99$tH{Q#fTlLE(R0$`|-G z^#o3f2x7$q@uvm#j0FwN1ud)vZ3G0p_)ZIno)!{6t#szJo%3lo{xha$u)^Y4cTa4v zfRM2GSy8F8V&~2}Vb2DK3yaGMTb>b)i5C%<77>>bNlF(LmlloSqm?Ngb!JD1TmAUg?5@qO!ty6$Rysisw}n zmDLngwH3WZ&MT{)SJgUy!QlMm^GYhJN*4^2)zp>Mw3OAfmDRPCU6qu5R8%e+s$RIL zdI7I$Dye=^LtR7bf|kw&ZS#wPCr`CBE~#tc@tQhDS~@yfI(k~s7x6kecwIyMb!}}w zX&qfX9eq6=LxPU;1w8|OeM2LCBNKfyNBt;0gCqk(Vyf~l388Ntrn!ovKLrG>e%g}tgpp7|x)%a`oE374G+zBYsmOX~_N8+#{Pr>l0h z#`ZQ=4#YsmW_zb=k(P*gxLi4Kr;FyyZl2cHTTRm8ia;-4K zqp-NFsO)x8d0lDKSb3pGIjym(ww;#iU(?uGR}$6Ga<7Hnf9KwV&g#&v{zv!QqVGQ# z8*Gkw&=vb&c#1JJJT&%vbaLTock=l3^5pF5?8~?F!|5+qHebE@^!ojm_3@lHo8R7T zfB&%abNgA|&V13%*S~w8zwR$r?5|aQTdDZIRCe&H^6*u~kE5fXYgNa`$3n*}7W$X1 zb+rll3g>W4z>{$h`U!?006>7uzh>iKV*-F312|v;Ms(UxB8)@I`3b#xBo!lUa?9xM z?Z=tCioPpP?$(UuV0AMDj5}(d=1W*NJ3sBHn<&Oz9lvGVSwB^-8uD@FX=lT9m8_{6 zOGI|ngOE433PI!dn&uj`lzQP2Icoz^-+%8aHeav2%S#x^5Hz**XbSwa|0bpe3_Tj73z~ZUbV^rbef$%;1S0EN%4~!6q zIr-|huky;#<{jH}jZW(K7j~zh9LnymaKMqIRMxSzRj1aR_ILA)M3#kK-`5YK?p=J8 zlJJHJf{--JQY+kD8C-MvS*VU1xc}ob%w_WU{yFreomZTySbL%__>AXdUd3Eb*N=-l zg5r%^ZX!mR%m}jhI$4RUGe`6D)>#S)7fS{}OQPri&~*_eGleDZ$2m5?Ip=0k8qOGP zs0x@3n;=o&YvueqE%7l09gIPoff4qT&UT1!TuJ%9&9QJ%K#BMWf<}T9GK|F3o{KGn zhH#!f6}gXgD*e)X1f{YJyE>^Z5FBP_pi@aAKvXeoNu_W+<`LxLcZ@bGKe&;C z2zc<6iB0u97E|WivF!=fz|4ZcK8L5Uw2RKP_cc*moksF5+rt26$i;-4%GLIYXw`QG z@5~iS2WF>i2EKeNHxTC?NA}U zTk2X_3!6&T;%f-zJI%jT^fv-qyOL6PQ*Pnt-LzVy432#2C9dY0!iG0fretghc~oUk zzW$P`pf+h3H77-)q=PE(dUtgZwQcwjcIO1V)IOE*P#n=p$Llo`8%D&xQ^_F23PvY) zHDz*M9r~a%Tj8w7jGkES<+Ch`S3E!&G6H&PcPwivMk)+N?-7%jWY@7&kPxqYLc5_D ziB5lXR**ib&Fb=f)<9(N!yNn`9?Yux=;z%h#9tos8uKM|BJ(BOHx|XU$j+O}%k~s9 zoaOwNn_8hkb<+kM=a1=~AVC025JODee7{@uyvxBT>KDuYNU~fd;|1b;rTiFw74P8( zHQDZIjd2eK1A0khWJ<1sXpL6Aj>H3*V69&**8WNRG!5o+A>2(%S|b74q>eJAhm2JS zK}`D6m7${nwlcpvZ9AV1d>Jw%4MWO8+W(k+Iub5cFh>%|XD98gQN^YBEp6s|lZh%? zzp`FUDVBJJ4x#jRqID`B*Y|yB)s{#A^>R>jy4Ecw5Ja*LDG}hnh!+PC;b5Aw_{P8ooJf|5H_}WaSw?7lpDMsScw2thnG$3$F67VF? zXjDO}mUGd;Omj~NeJwVTZvc=gAUg!$P#xhc>xIb8kb%69QkV?S*I*%PIXml<;hW?X zfiZdHxqWSpk=|rnGh4>8o;Wpe(u4h`eAz&N_o-L*9tweOH{D>uTphezJQt}TwD;FS z&n#^rjUJ&E@>lDPv{4)*H_MiO_S8G0Q4VEA1A9J>q{l-R*WB+SH1~)3Xi}nz;ni?^ z{0QFw2E?RFn7kSt67pJ^s zA4An)I_wl!l88tURAFX_BMlKm0y8f;Dmh@x(6g;zWB&a%q3KmSk60#6)(d|i% zMnhsu=<^9I9yke}QF5wKmK)N;d&Hzq?Ri;>8Plb-Bnvz3n_h$(UiF)gq|VBN%K28S)_psnk{q*>U*c>o9P2q4Q9=RoW;pc+B@D3fa?9@;D%{!PMoUNkl){rZwE<)5??a z=1%pYkG4wtHrz9KsOHfSYX%|d%n<{sJ_AIVv@E}%blrXR;@s7)U(2hvyZYl@WUj{j za-xeBLuzGZeXaeju%AD?Gq1E4gfd(HHu_`uYh6Oz#PaK7cNNB z!A~1OIf}^lsC?eO4_&0_rIvT+I(Z&^a|uW{&+-se{5k1u@hwj}b{Ud+>KMHGr#&;^ zHlQu97_2y>&E}6xmhyNrZCgU&q>XYl| zf1a1v%9Ze&gF1b?9_K9?h#}lj1QD>{Wh1*c$DJPte^U;jo&6^9_dQr{iT?H>nxht2o9d+2%! zG)bhXIOb9#9|-|h8ufL@E#V0}LxOygV{%q!*WhHpbhIsnb6hY;N!8^odqZ#ETt%`J z@5;>2y^iYSKYql{;t7?#ZzFSYftkgBSU4{w&b?S?R=F7WmV0`*MQhdd$6Kd4_tf6y zSLoCS_cc)5cR;P50=Mt*Yrb|n6T$t`JTOf0@0a-Of%p8Z`=L$=>%4|X$c(mxq8tx+ zCqo~%NCiL}&+_!`gS3MaSezH#S>apYk6yD=Sq$e7=MB@Qg4#n;Xd_GTqdo)1Yz$>x zM+CumY@1WLc~)Ww;eAQ>RRe44_I($WWlqe{(6$cJ;Te|wK_S`KbYZMp3FU3xh8 z6Ae{+QjOlflPK^z`%lJ1#rrC;hn!CW_R>BN{t2T(qjBUYT)Zza-mW1`tl0ORLAdv3 zJb@>HU>L+{pMX(K;Q9fv-S^dBXF9)5q7hWsI|lm0ObDEg>Qlj7!?6e_us9JzjW%N)$l?AA5xbi=_6$>B*u`^? zMcObT3sp$3#^MNANRk9(?Z@@mv50V3e0XnK)G?MEhe^-lO^+r(qhOIP#IWCD5LTWz z|4n89EIkefOI(M>5z@K*E3TP)mKnW}t$cXd2$YwH2GZx772GGp_+tjhW!?La{-aNpE&}e9F7-EAU zqT3kKz(5Dl05kyWtO4fXX2<~sC4y(#m|=lqvftTf!!fMyNFk={=t3I6oq;x{0$$<~ zkOV{)L$G}Y{)oZsk3kNtBhYwICm#8T0jq03@WEsJX}R5)#33?*uMZ5z!yB={$>Pu% zFXoV~8^EKq9NzeEW0~B?c2S!}2{GOfoAr$1g~+=`;cU>1U~EQyNkQHgv{n_CvR_c^ zozb|(T*B*pOAHdXmEILuz_bW8+b&4KXEaDa0~azimr^r-qyiS=pZ65*8|IUY^S`JR zhf2mr*vD}!K&)wCeHxPtJvebAnC}gssTj};0E6UN%y2*;1z|?bYs6xz@W}RkHZ@hu zg(s-{ILsE7`A=ks-WI9{hk1ny-G{}-5LiX9n1^JPYEP-tR_PZS9CVju1&5hs1kBR? zTY4ZMHx_P5;3G_80Upjl&O?)tP-+SS4|2i+rwEiPOz9i|24%pSX#jsJ3;TY6IwsKc z2juy&Vd`gbGE*Z|DJnlYGTa9mq1G4ZbBg3uoJJx*qt^>-VTI)QunI>d`0#4 zkG5jDaf_Cb9#HRLv1u_Wd~8v1sJ=m$D;)zcU_8I6#{OkzW{~YTmTo*;QjMh@hhnEQ zJ(+<+`ygW_06ZQEok0RSAl+1eDIUpA2TpD>JyU^fbVnGd<&)H)AGa$n9K#c=iu2VS zs?9f<4b?JGe6(MsO_$)bV@cZ8(hScinhT*I?ne>JIL%zL&?AaW{Yd6&F077hHulNj zZ!Xv@g?{C^?Sh3c8kvR{qr^?voAGe*+Z35JN>*u}J_y!K0M!=f6%b;0f@9{+*7L>(FVC21E;gJJ79tsAjq4#huh_57^F>Ch5mD7uQezOgDjv! z#ta)CQ2|p}O!Roeqji9nK1gQ2;;mR_)nY_uNlWpQ{F^2T)+*KQMRABh!}PjWhtT9KbZeJgx%d-?xeCc5NDscQlUcH7Y!%dh#!fr0oEqHx_+u3O|Ud z68dzvV5_<-qf#Y3y{y+q>Qf*3*9~Rkc&>&(t?fA7^nPGOb!tXqPGn24aq&%~RMqXw zs(Pk!C@4|XYv?Y@LlyH9Uk;}tKFpv$;*k2sdFWYNl$|t-;gb+%OQu;Ix)95}g~PNF zYhS$@e9iyhGjHtr40?x%N|P+ZIo3QmDuJ&9Jji>ki40!5(#_T_mfo9GN4sEqdqeJY4yK`8>CZrQwti>D#N2P z`(la%#+nmS;@_(T`m1Gbd&ON^xX=G2F6BvTJ8U4@FjMvSqx)%bOA$fS_oKw5+Cu6v zKC0~9B#6U{3fE+>P0>cIz;Jcd2PuA}W5oqSSnM8t_8!>-#6Qw$^a zHiBZ6Ay>t#?wEwV^70n$A(y`-ZyraCW%(z7ibn^V-EN8BbJ)TB;bR{YcO}X=)?V{P zLW6JBk6zgfx{?}ZWiXyv>|?T!{`W_C&T{jxAB`F6%hzy?$P+GeYa)?%e2>}pVbOSv z^SE1T;Sm1>09uu~nJ@7vP{Y8V)a_6h%Tea(n#u6xYuX|8rAe{hrrZMnON0yMkrL+<~%FWdk;kA3L3v^-zktrY$=!_{Y0q@_Esr zD?)bKca(@aBz7pd;blF3b-6IToHexd0x^eJ&{IT$Vhiw(AhFVcT=fc=TxyEIW!2`G5)L!#I4+N zvFpG2>Sf&OV#Vt6;Offi>e}(2)pfzOw;F5jUDhhUj|<@S%#9O91$wd`TxvMDZTtW^%~}?7k1cSxH)v>8EGBvcz$&{D104W zxsDr+J&$dSEt;qd_f8k{RB3z7qv=&I%=XgBtGWw>XaOfhhhN_G?aU&5+aUVBfbG!B zaPpuXMjf0O0MdTI4SX;9fak&tdYjyXkw-TG91}jq%BA0EzZj;O9wa#yr365ToMtbh zmx*Fo^&z!f2@mu&*=XX?wO-MU4betkR}<;_Wj#$Xm6s z$;^D=Xz=NymN_Sm3&#Z36NsW`&t~NKflZqtmPQ#}rj#)yDi|fgiHT=`Am(kr+Y6W% z1eTTclN&~@2m!UvK;Nfs#;b$iPGADAndV(3n9-sF?=LmFJ$s+|16KMb8NEkD*HSgG z4CL-Q`V~1(I~ws}9lf!B@)H1l#XxV<+nDaMjF1P9BruCJAu~nU2MqKU9k_x+t^im+ z0%A?+sJ$8VBr(8`fMxWx}93i8D?5u0#5`SUL27Ol)hh~UlR4r~^*iQm}W!fi$w92+JvqLm0d)V&)wx~#c zI@21lHhl)oB!qfOPu70;8KYg&98r?qS90@biIik%0i1n{(FLaiw`aa@q7}Z9m^rYl zDiXjw+7~{?m(y~ULaZHF>2&3+Vm_nW@ugqc@u07?L5L7AQVzpDgErx19Vk5*g0fpRZG3qT1Gz!>?;@gfB16okw_M~fVRw!|Y|yVbV2K>Y`SSr$j!jAm^LOvIzDUja z{@VgTgvA#6ksK?1X{!njKG?qvC!+b{`=Y|Zo#)~TGdg>Hk2GHump2?CjtTHJ`okD$ z%=q;0XJ_h$dA`_;qt-DfNJ9J68R#9-<_9WFCFh@vXIqcGLY`@2&J$Px2_lyF!H_yp z=`{3Z?G%)tW)iRETfGb}S=UD;mhTL*PuW;n5va2bU{Q)>2_`Qu5lp^ZNVKLtAJ1kV zv++IBT}=Y7_{wMT7*Yl_AcFTUY~Y7e*rY=_E!{Uv`BZ{GzMsuk@~gZU_MQ=x{~?o0 zR6lf*H}^?J5*2Q=;=Vv?te_h5i^3d9IrqUaFcUE7j+I)^u2dZpUxUY>AS6!AR=S!f z5XEt*u#$q)R*%Fgferrf^*=hC2!st%{K+EFow=;N{7?k9){)yzfaBP@>y8!OFpYD`T&*l zumm6@I580SQ%VAwVcCk*gG ziPX*W^LPbg;i;p*jE>lnge10?C7&Tai#`nkxA;H_rQz#uMn}NU*{qSF2%TX*nLgw9 z)dq`_+H&DHh-s5g>5}45-cR4Dh`<#eaXt*f1Y+u+Cy6^w;Je+|#2y~0D{o~iUU$#R zRL}}9iK;ArGqz2m4`-a~$97ykYuE+K5ceS_fH9;HK(DD+U6-xX^~VR#%|z{e!CT(@ z)oEwzt##lM+4_fz?l}^}shzbeWV@o^x^73mJC6^SUBtI?leoNT+R!sMj!WI$DHaB$ zcCO+8b?<78qC>Ze90PTqx?<0MpN6Uwb>F6j`u=miEq6xM{n~my^!wd;$b7;7?wHtp z|ITTH3jtjVp7#TKUZ-3L?AxrrA9(+>t19-tBZNYr`$>{;k}AN!046Z_-!A}U{{5Bw zZ<|5*WP_jq>?gaV6~OxY+br6aoCsq>h+yl8!$}|r#{T`Y`H@66I4{{_x*#DH1cc$R ziTQ(OQ0!k0V>|_EeR#SFjLoZMw>=c7Lt;AWna{XHE=?o`iJIS3sFh(yq&Cc!?f&zp z-1oETC3q{0_nQH&Wt1wsxTJ`!t|-rugp5nr2b==BEo*WI6n9P7pE}Ht`0bU!(Dn=L zD_xFaynA+j?@3oa@QWLd5j%2cAT21EO#UB98R{e{O9yKFM^eW0|C*G6IK1c6{%=W{ zm`b4DeKSZ6g!%mVi7KH#ZIF^a!^v;ajn~^j&ev8T8 zAeTD4plM|+_gCBT62&VJvzhu2(=?S3w0Zx%lcdbL#dWH`>(c`L>O`ga{cv~h?vPLC zjxH@GtTKGg9F1i!d|rRz!n$y>LSHvqQaPy41^UD0Mj*WQ9@Fz*KCR2M9z*dAfJnsJ zNK5fW*ZW9|Lxngw*#y1xUq|1d>l~Iwe~$so66<6zxA%GiOssL8f>hpGPh`&9X9a*T z*aT$#Bd;?_0^wV4C}_?!9k@RJ`=eBe`o^~zGTmEmnXR+9>fT@)0AO z=NZ;;W*YrWE%6$K3n7Hx+BMvYtV|zfk(;NFpz+|0N3^7~Y~HkZv3^}t)=S1_O|0@q ziP{2NU&-1$&*jG3xBmVdPEzn)u+Ta#@XZm7vF-P{o!XtTRh8v>EG1oEW})s^+x5>= zpPJa`rJHvc9Y$VN@t_1fc2k)*k2)sA%JtY2`x^>E6=Ree|J4q9?=RqaPgr-61yL;LB{~xa_SB;dPWS zgK$lq6S`BqVjJ7|VBT>@s``sqc`L_hVfi<(-Nmb9@ZtQ>aP8h{#OJXIO*4JYDV-Sk zQL=CAw`ZTZ)#Whs!{`Qv9*^vLC4?y#JnTqz8$CtPMUBp*rv<)rYVsgtt1sFiKX;x^ z-IecDke(!sV2*`#FO1p?BZ0%-9El58;sx}F9bsLkK0oZYna+!{_JG{*%vFPeW-$!B9rI6MNx)*ZP+Upc()jfY;qyoJ5_?e z*R?Ld=pn>NUM4Tt;LEsk6xGRUv=FR+7Z?B?1XU#*kAKNHChKxDA@FBSFl1K&2|yXI zrSSR}p%A35antw``)wNJ50I1`ex%Dgwm1y%%qCZv*6cKTGS>S7-RS(TUnEL~)thJH zlgVCHGkaW z;JZWyov)P8>PtaTzGit5d7mJ=8hK)`Ydg{P&w&7G>;nugAdH!Rk2A~pD349_Nbele zK81_zixv=nn_TcjPn=Hz@IiWrb7OPz_xrc{5>Fnph}rcG76vEhBgI9Z!tj^JvqQ>+ ziBfZ_0|M^oyxjSki<@f3I@q_BM|w%TzX-=ql`iUV0tuA0z{ZD$U#H`v-wSIBCcsiY z<|oU&ce)UyY8Xk$P39f+W>M*%&9Z%t4pMbR7BfsfYr`;R5<~21mLL-v2x3f>ya57$ ze-8jkL`nLxHldTh1-@u@5DWnfw$xv^&h#HmkMZYot5m_X)4MRdFdrM)jxG#%WdtH5 zn_RA`KMVLMp)EQtgsCqg^N&B8KJ9q?N5@WGft^F7Yvm^wckoETFzfC8EG`t^OY`0 zqgaD!jsK*J*|Y$YM8N>wDbYZ9mfw7^%xo7;BEdR7^X6rwIafjNv`i8_O#|k^EeD{; zf_32PZ`e-;rwnpC>5KqA>FeEgmS=af^;?%r zeTU%9N|LFr7_vqIxmy?k;CFTa+5EOG`JoL_@Ep2b`F68mtE%h;xmp^2Ofedoz`D?sH7}3SzT_Vq%&%hq|t(8cUf~5PneL6=S0`5+?HBKNU|De9d(_vH2rCqySi0EmG|YV-ZSSF zxjuhm3B(1h?%q&QG{vIAdta^Udl-oB4}vxMOHsfQeE?||4t%BaRu1z+9ESSBmR_Fz z*keS=#YtxT@j1p|3%B*TDLcr&(u0W}M1?ozs3;dKB()&hqo}k?UE$_A{h+Z{MVhvSKN2^X{Mo zcHmah6OF%)>X`#zS8RRVmrZjP%H59YN{>_4abpTa90lPb2lcz#ez$Z74>GQKUp;Vi z9~b*oIqi9=F+K8#S#$Q&B?XU9dSBO3Qv+FFJ|N1x6^zWna{S1?W zb*}i-GcmTHUb?B?p_3CGN+z?20)p@aW-~JA><`e?jCYP_)WSVzA5D6+L;q)@8Z^wk z#>SY3(?r3`K=F_$)JPZ^3%M&EFq2}RPP0GK3t;0?!Y*pP)w7ebOT4`h!=ZN-#7Rl) zB3kua)hvnCT2Rw6u(BU>l>REGF^sY-IJ1Z`ZzH2YxyZ-!H$H`&>A?WL0Q3Rukmm$+ z83wvdK68hN`jMOLw3s|2YW@z3StLP30q7Tcf!i+v9=;$y!eX|CgLt7qKs?f*{>pC~ zYlRKS-c7DB!&h53_Zux0 z?X(*o;cT(;t8=lBdUKeA&ByFP;C#igukxAaEyeE{yiL>BjW=C%O`S7X@o%PS95wIM<(3 z{dSFvys#p62_Gq(d#O(s>7evVSH3MNU%jvBKo{5lJfD)NimX+g(p8;Glu6-GWaZRG zE~%TSX()B7o(qwQOfN7xrELFB@tLrEL?0gd-2j$^pVw7?rXZ*N&V=x!sBB4igd#0F zr|7_>>Y`XCr&}24QREb*n$@S&_FS^*?B3wOEoQt25N z2l?l4>4hlCH$HL&d6m-+mCJdO1;gdbYE{NM;)hQwdh)9NS*jRTlilyDq6Sy}fYZQ^ zw4C9}V>Rg?+gL4~D)c`zOqsY4do`zHHTSYGkZ^{lzgl3q8qJRRA14kBkO#mA!2Z{X zgFvKEU>ss*3_|q?1u3j~i}&suz0?!fq*r43)_@|YaRZ65dOym3;^xW72iKVviC<~Y zlC<7W<+N*uFsN9>m;yGotTBwhgg(#7myFSD z^sd%c^e*u>hyc#y{v3>I4sAXqhj|MqUITG<}(7l=Fg>;N3#L1hQY0CT^`^bgGt0&?v2zFoJ+jf`vV6p<#R)9b1p@yYbs&HufKvee|5_>>An#GWtXXL zfK)jAKfmFW{IlrL`JDVFKp6A6*v6oB9zA9z5vfx|szi*f!vZXv^l0UF0)U+fL+1tP2=0o2Rm;g_AiPM_8?Rb( z#z_*029m*W2DS@+ti~9XY>O z^=3`4_`_2=H@-MnV{FjG(LRUJy=bBIGO53X*(z_G7($l_r|6d;R zM9-bq56LHV#jKZpLRUDXT_=0*zB}=dO)Jg%IyNRs6#dpF`#LwLX}X!G|DWhe_wK9S zkWXt<_j^9SKJk#xSPb-jdG{n=`pUC`zHgf|HKtV-gZ*KhK^=atpADXP$m=7S$7e1* z82I^ZYp&(W^n<})Kla~ERK*WI_;W&6KE0lP`0)7uqAO1v0L)?%{1jWrI`$fJ{4p(& zO-jNg+0oK|F^SjpfaV|=?JX246m4_cNt|-@BGs*~L?|<;PxY)f=SzF8ETKkf1@!XeiRV$6*<3Xj?nHj2(VGT%&m8auR6Vv9D= zzp3y2#;Nq`%g16wi}}XHvVh>9o>xo>yg6vwtZP>*{;oFJRRUFYswFPB9@RJ+vx`a4 zqWdB}YV0+W2lKUU9)A^M~KS%tG`Lt|$mT8Cf?M;QH4iR*RxoH9KE$y~Tg+K(BM z3;y4xR5wrP%Ecc$-=^_U+3z!YJOSUk@1Jh_{@hGu_xl{dQ1)Q{vR%Nz3wy7&gO|<` zy9W!zRN2EtkK%yCCGUo|!)5=T-NRR;G1(t0p)uT;{~pBuISc=G^8fAR|J%v`x0C;G zC;xwS@{RHUa1;D&hT}cXSYFU6kvH(9HEs4#UJ71AD(wPn=(dD;lZoB<^P>Lmb-0^N zW?m+9Wy{~|Ri~OPBF5(`$L|TDNsbGq<@OSd-l89 zVl|wu%w)eDXqdV~h6=p?bK7n(|K@gR+XV5GZ+9o&h{Dl|0VviAp*&#>o(GuZ{k$I! z0TyyWS}|9CGZzm|hnF&BYYnTsTb#gXg>l|ii!Y4I`qewf>=BA{Xw>BkyA3Y4Jyc6|j!sYXg>S0gSk>n}7C-#p0 zl&ouKg}C{)$!mu(3lb$Vcim%6%)TF4-O<=G;IJz;gz%y2p8k!4Y4!HAMmjWOOCxyOZxzQAo_k+=C!;L7I}T#E&NmLBNNL^tk0v)S`b7^sdJtOu z@K>_p#Tc|pc31Hm8nb~R@JXHlsC&2d-D&arW2KtmIh%r?qo?_op00hX4l+*`B}GH; zBsUc_44|xNm-!orKI-FSkl#H}{e?zvftgwB!1>{J#;y!|(SEYhdpAr92`r))n3mV0 z{xa;C$|T_3#_SvM=KkJV$Zf^n5XGx80}uWl@@H`Kx^-03ST~DP=wJ$IW`!nCEs)PK`2qA%Xyu0VG zhac~atp57?t#ac1=eRT3H=^yQt5>XzhFLG7t`(wJZvQLspaB0P@%S~yT*QU!BapKQ zpelNN=RU}eD^g+umE2>MS{#}A!)l945(PwQK+s&?mVFGHK4Mgf3N(%ktFSv!*C{W= zV@2$uZ>(RF*<>#J5n~(?>qB$%+z*h5h{cO1wtRp(iU(Ii;c56J1BvMQVu}eYTK0$% zg%9*qxuK;B!={E+7gKIilO4U|vWc)bQY@E2*qfr@IRigiyJUmLu-f7ErK&dy9 z0N*(22GHP~k5O#)mN7&Y>=R}=Iukz+AaETj+>m6ym9?-LCGvwZ^CQSsB3PU!(aS!X zo^qo_IZgt0^KE1D``+XQ!{9`$-#uoi0W|nFG}_oZ&e0oj8=rH+OmV%;JB!fETa^3I zq@f0iaU^BdK292zQ?U^B#XBw^M_nq0`tCza$*EB=UlySCH7bh)j>R8;vH;*_5_t$f zZfB4=lR>=%W|Rc0%u?O~A@aokFZa&8l@?jKh}b!%!X!wDeR?`~SOVt@*Z~2Br-L^D z$P1GBqWFAK4C@9t^4dC@MgRpd&{FBBCXCC8bChnzk_86tK4}8r;rSbg zM`Yw5C@jE-CG%fZgd$f0sDg|b<8>44iLxu9lrrEO5+zAblU*XCTRvn%OT*?HeSh=D zx-9xWT*&%rpIzir`rR8*s#Y@3Q|kKiS{yF!nFNATnp}E{rOYQgjhgLxc$4Z7-NqdI z#=b1cxUAbayQ?Xw*0}tB6Xgg7WjD?}D7N~MY9&Wyi6MZ_s9hFt$Ze+ORgn>#$%rR7 z7JH?1E}QhVnS^Z&RAMGQa})LOm|(erkJ3s{(CJGP#UYmopjQr-t3NB4?LZ6$s=x-7 zY=^S;u^gJo6(zHD0-PTKz!LlL0sz=)J^l#+G-40J)1h)R$oMqGiGDsuA{VS9kYy|t z2TTq1%q`rpol&K|#&Hfj3t3fAxcJBHLWi95{iWZ$%MMf#_2jY#v{L2q zWGbWVt}={Dril2K-Nhry(#srS(T{lI^r9)cy(tKXGDF`S!?L=;^qfGtAxa{W8^}~sEFzJO&7yS3BP_+y^Cr-z)-XC-d)yb;l$6?c1Ai1HnU-yD7pK}^V_H^PgFW#< z0YCz(j@nw9-g;nGLZFTG~wI5G@1Z@@O$sSo~v31N|GpYI5T(=ONodU?c zLIp=Qrb>&}b8a9i@D537ApFVDF2RvcVD0-f-2*sHDxFkTkvxX#p;|@%Q~A)llIt2e zPQ8)qT4VYGT|y~Abf0Aza4ntG#GQ=vDQgmCFb@$e$vopQD@x-?B<3iU_$bv|64&lz z;ZTq?7SsKBpgl;)0hG1hgWm@=6Ug0|AlNT5t_l6L3BtfbvP@2vF8`@9LL=SkB^_1X zn2>y8*<$-d@qI-TcU@=D%sotZ2yoGT#Lcp_zv(O>-fF2nNDKhhOX`>dfUhyY60~ME z^=hu@PVrv}F&N6NjcRKQz=sxN0Hwa`r#_GhPTMZ4>KR;0jTVxM%{q3tw<3kGEH9n) zZM#M60@7iguS#7P!(_*@Ev2$+eA;dk5O~LE36HZ_rRxmik_Ayt5LULcPz-@ zn1&wiYj+g%?>Ie1WqVmJk`qqCpj{gJDTBP~074sD_R!E4+nEwvkmoazK~ywXvM6WR z(5Zo;n2-6VRMCxTC_4g3Ak8Y!w_Yl$!}}BxslwuM3MohK@GiYYN=F7efYP=gFH4J~ zdW#!IWA%6f|G;WwRFk~RgLk&d92y>8sgD8lg}ps2c^6Z93jnwEWAy>Rzn4>ld1_s4 z1Np+41NUz_?7&j7N$>b#asSj_+G3`dQRZ2mIM+u#=b>gF)8W_s zVV=~8VM$W#QN*oQD^$NtAL;&7OQ1F0tz|Pn!5&)nBeC5e*}@(=_rc$)_r@wL+1)#| z(J*l8N05Q^Js+9isP)zy4B!|8sK>@>{Tf>`yctM!`^gRPT`y_%jFwxx(KhM(80zUu zaC_a8V^9nYp-sqcGV7~Mk$8iHWP$^Z9tU^_i}xhTrba{?#+SwBR>V$A9wgA5L1kfC zTKn!7KDcNUd%qJ1km7kZ7tY)p9y9aHUnU}v-*dciGB_*T&zBgs0ISg}hXxY6mTBM# zV%M#ivS0iGzKpm(+*hqh-cvjQ(mbBiA7=iMcp`qR;ptxN^|mJzAvo)~5c^^)rq}<* z{ho2>(O|PNug$~jGd9zRglUVLL5reZX3Sx3sdE#Xt^A{I4DPU)`VgX*cdBx@Da}ib zx4Shfm=eouLwn%A+j?goqLTIkNQIpK;Caqqyt5~^r}%nwJ;a3^5y$LLfW9QlE;}qbe$DadFtJNzBqgM{OJgnLRuU2?< z7JL1*MFj`~05h{ef&k5RroV-2+e#i)aVvm!PinY_Y53a4lt)p~`nI4qEM;{mV0uOH z&Fb#zKajOYFI@GDoOu7P{(9j$+_mFdK9&BiIIlKPdAX>b6R_7{0eEZFuNrdcN$o0X0?L(*N`+ytPZjU!YT{k5m zAkV#4tM%4H98=o0O=rkuvgVd^_GVOI*Pmk?DBfbregnh)c#HaADdol%kb#ENw{rKa zF%VNIZZfqJok;|gYkn*b0WjkMjg=ppvp+J^6>I-~Tnz?vXnwk<`H6nxQ*Y%bd^G@# z1+wFS9CRQb0QAUphmW)~jNW;$_X&-aKCJyTlg%@*_h}3b%CG<}R_-opf>tbc_^3M* zdpon5dr|VcLxH;@bkKSFo;r=`lLeC^?xe{FTG9kz_jfrMJ9>J1zt=bg-hJW+fVMT6 z)YqA`2w+&%zScU^?%zEb`Yx6Z{CRHgkL#EFYoA6eK#F)KO#;}E1}0#>3f%#lkidrI zeU{IAiuljMG$6XFr;pv#+3%uGx{eRqfx>i<`aaVcEl6L{iz_n_7b>J51rfah z)}nnCnfb~w1KYua0jNsB@li{bWS+aSPQj@eDuoBosn(DdHEbqF|@ zrI*aoO^3o~;1E@o)q8CJ*{Hbo`V&9>n>qn(LV%E5B7$kb&$%bEUP7!1Up4Ve((B*Z z=|AP}G9BQVC|6jx6VNo$(YgP%4*UCm)?tf2vtduVo$G+@V?4zE%764N@CcAL=mmgv zht5(h2dtR})v-cch|Fyb(C?RyM|*+;$!;zL$jNCQP<@pdj`5pRBh0`mE`-!_ijYeH z;Lh;9ZrOyiy#lp}jhA?{j+-w1PHaMZeB85+chVN6MDd0jocE)5W&+lgv-mHD(Xi*1 zKC}xeV&E?eGGYF9fUvJCcVAt#`gpn7rp@(nnawBLc9+2$5Ps#MJZHGGOG26-R0iS?y=oeoF!CbwoA@7|r0_Q*wl@`fC%c4KJN} zR&lWPR2Z7gujJWpr1mv&G=nXDMGea)=PN*DJr*|k)_rvZ7s~oBiYbp=s*<*0Rm8ig z=q?-{5^*u^i0O0&_{&?7MavxKM~rmNT7_1CO9$%0fUzmHadp?@RN-dwnJa%||2f#b z@MJ?2*uD<;lrLQux?EyJX1|R6CyCc?Clgkoh+W23?6N<33QT*ib`=zL+XN4a5J)sr z7_U77DNg;fFRZV1aiS)B_W98;LNsG0A^GJ>E*TtkzS@L>63U}h7&K3S&mOQZGM#3D zj~FzEMh+yG24}QB=1XfGvAD3ee19Lg@WBL&juKO4KkL)0_kR%gmTzq~>b7qJ!7T|+ zk>IYyr6mv`xVsehQmhmyGz9nHZo#!^kwS}Gf#Rh=DPEw!3zPya^kp;Wnrp9l&RP4~ z`@_Dj^A{vvp7D(5zVGoH-xTmaIksv`eXVz=QH9C!H!zhOY(!akY63E4j&X;1U*KoD z(4M%*jorz@4!bDX{1n%0BkBF`um3-+Vc1iqC695%X}_RE6X@~SHZ}41&Z3z-8WUV+ zRVf48WKFKTV?+Ww&!QiAV^iI;xu)W_sh`^Z)L9bX-oc;c-(KcnV>pCkCqdKx6gu}e z`I456Mx{fNs*lu5B5kP%n-oca`V}Ba7&bDE^Wed^ir6qc7aZcu%tbYFCRc(vh{;ST zA!j`gWM20CT3}P&f{JW`POWfLmB^EQlO{mxd^S1en(6)w(&LMRLLCZK1uaLqR;Bqv zdmBNj6i&Z1V}}Y*OR;Y@TNn-6cDr1PzknPWETdKXft|jeu^-<6#_?z^xiA2ss^bRX zJIM3vdpBW3h0NM@>*Zyj3sNiqfFLP!owiaNwwC0x%gj@o^9J+b?ZU^MQQaEu5=0%e zTmUX65`{PB;l8Nmjx?jnx#&VuSZy?ua&{C?p$+BMcOFr#x#b7Z)z(6I*(K)`&R6-o+#X% zW3S4B&tON^{{$0V7%-74g^gS3GX4pg6MaJJ54(?E{MDuI$hW6~a-|3eizWP%+sw-y zv-ZQ3iMo?D!_c@5$zENk=y(7|VLQ{9o z;O%DW1+ll`P}Qs9(tttkgk83zPSVN@OW;TJ87L4NCq2V;389K&KJ*bG9vh8*l!mkt z%Px?I7EU_HlhzQ5zO-p7iha)S6jE2S1Tvii*1*>1@2S%N~ z?DrsN?qahEOPcwdQG~NtW|x+;X=ZvWs0h0dM9D|B7^x-~Ba(`nLu5djLD&1Ay*77Tg(h{|(Ve-wu_4LxNR2 z!=Kp*nV1x0011#L4+xmb6)@urI)GY5GDm6 z_W|7*N+?1ZS~jRg{!T9kwnmIdV{dT(`8yE2&do+?&&-Ui?oHsgUE^d zc+?mC5~#|Bej{u4zStfG1gv&RV47`urPzQtN)eX<0l2*7 z<OL?H!cIoYC}vF4n)Ice2QKU2H(ZBdm` zd0s}YrB-#ev3CauU47Sn7Y}5{n+nPhPFj9H^}e8yBK!Kya-Ng|IG5uSPM>J@lD3#5 zmZY35W*#8Nxmr~0?dDUqf`-i@J4Eo!C^HQkdNXiT#_ouHrHIwSHq*TGsX2}00M^_o z{6j9&E4ttcUMvTiut84p`ntj~epYMy42YIA5pYNnU>-{p-@vZ3Q@GdEc>cl21 zBxIN1oll7VyRUcc$pCWjx=Gxh=B*(0zu zazeJhMaJY!z^M*OZLog(WjHnz17r2Kz`l!&Jt2D?uWGdZ3(*`in3NKFtqgNophVc@ zY(YwAaoA|++F{*3;pq{0s%`!6b(D@@9f#=d`D5`Y+0I@;wbsGmf#XR&Ske%P^%Wlh z@nZp(#EG|a5GHB)zu`%-r`yY?&b&h=do9qw;?=|N}gx)1J^k)UZxm) z0KxrXmyz}Yq5~>x6oS{(y-=R8Knr#10da2G$bHzw=K!Hd$WT(Z=g7+k4%XJBYb&s5jpTD>CAAaL*5&z0$#rL5 z_Res|L!OGQ8sw&E%=;V*aV*5!jODRD5#K^Sz@G)j;ysd3bgSFXVh(p5!~gyBwR%!| z*Tpvp)h%a@|w|+K3zfH zXGc=3^JM@sFrBAR1IE;ax9fuHQ<@`WUdMDXa%;Tt-sCMF!*o{g7*z}syXgfi@2|Qn z0TPkxoW*kweOYh6woeuVTRB((Dhm6DBy`Rr9D2q$CGHY5@2z~IrtK#--L6R|U*8uW z<+<3agT@}7z>B`V+>@o~o{7=9z*1Nfsp@vmWlvvJ5d2$ya{#~r7zEJ%>r_qve$R$P z<503`jd{cRqyNc}1*ZN=Nd@gakY;$6Wn11D6D zw6&PHdb-neg2F3?BXuhFk7&8Aq0bI62SpNcsK_8YFdkG?&ima=OJuE9nsPs}!nJ)| z7Og?=-#x$lV(4Hz8bg9-Y@};VJ7O<`OH2L1HkTe)9)j%_Gr7$rVD%7z_1s9J11$Nd3=+K`mPd_C>-7Zt={c zCIsKCr-OExW`XYqhU;C3x!AIi-v|19u5>Ml^3%Itp9PIdU?U=JE59|ld=$&Z1$Uat z$b^$HxMW3(t^?d~9#?&mq9xmCBlcOd;1A3#Mn5dM6s1W7o#jAH)e>zu5WvGo;#Rf7 zOq)DHXo+Xp7bIQs7$(L-G_a&BW8uB3#_sQ5-W6XS%MkHRJ!AdIgULL(2 zx^k<}Ewg?L$(4+|?N8zjI2zFAvOUsImMFvVZ? zLSmVwT}|>1V&&~_t`)78NCS_8uVW0e9P_d9np9HiWN}*~>_~XBmcq1XT;Ej4Ia{>5 z;K`$PX&tHn;KSQxJED42v_x7d5r=1^pE5LB0xQb*y2RFS0I4cI=0g&h35b~K!zZXw z>{BQK;33c|UrSQK9`ai+0(fTG?=19_-8pa>7Tp=V$i?6-#u3!Q9}p5aeP!R>N~u?s z;f(GbWzg^>As5WBh>bD1K7s%}8aF6OnN5%<@nlFG_4Rz$hljl4sXRJy zsFbWwdXPI7!8_L6j3`1r8b>0c{{~09I1iA|AC=H7p<+!vl_`PX4e~T^V&FtQD8VX% zQmj?s1M0gMj<;6t3h7HR6=c|ZE9oK7zu-Z5u&Mz zhOjPKk%&Rupaj>Dvu=c?oCmA}f>CU-YI`Ux-W+Y>$Oh4%##@h^ zC48qnl5iXOnb{`wqf!=%xWhH-FkmKUjl4xJ zd$FeDg>?j14xGLtnn%@Foy0l~1*FKX2*u;e(yTqV|y~|q*0(*>>`;8gIq1WZ#Mrq<|efX5YU=GIz zO15M4_V>ARz^`$=^;k1(0rNU^4)(wniNmIZE;x#uu+{m92u{Q_zclC8QDxK~P5{3M zMCcJb$~w>0pUalf{H0}-+^Uc;@GZsDIUWo|J@~D)uk_&eOsrR|22znc4gj0QB)64w zlcg)XRR)4*0TohH2Rb3Y=S#@jtK-x2)dLY{wO#Xkl=1sp&kHPZjQ? z3?V4gE+EwexMepDB`0yt4gVr)a~p$ZF7)#7d0UF1lQztEa(1W;Q-N8sOqOgq6;Si{ zvVuN*>O=;+_#+v-7VnrxiPw(95&CZwq$h$?%t2g zfC5ZC{^d5KqTC6E?Ma7CxYGs~pJR#@eNfxva^q&E_)@3$sb8&|MJ%~|W$AFTHs{L` zefFP5>5-JXvDq}x^O?*sW3r%DO`>t{R$Oq0(EyX$lH<7&{mIxUB%aR(4=bSv2q%+v z8cv@eiEG+k5nhvzLCctO>L;7NAEWGprnt>blW^(*DdcS3ffU&pDqNqWofhi>-x^QeUX-k>er$YE*~TX8wGAN#?Btua*D`T__3=obAi~P zIAnwCapwj0g|?iXgzVD#R;pm>*QjW0HE#Hwt5wd=deKQ8xsoQ5G`&ZrMDn&-GsGdl z3Tu0u!35R)H$Tjhw0jSFD+HjHkn*?{ z4#{KtN8zp0>!(&(lE;DD#(=cU4TOS=z!E>xg(GiU>=J~@GYDl{P?ahQ z=c)OUEjUrVtg-fl;?EiTTwC=dI9}d;LCTepJGLM#hHy2k)H};osxt})3?@HHP@!Zy z7fUW;EQofd28s1;(7OsG7dSj;L#c6c{Vm_UKJ~Iyw12Eu%Qazp?@gpp=$H*iOftK| z$)o!@QxPZMvSx;J{N@u8nans}12oUdwRj0zjFfHqNT2JeF^!a# zP~puH`*$ict(9S^L&8CE!YJ%_h6+xh5!q@Z@v|rDmj~MakfaPDaLBG|&fcHl|%|v}`G8f6~0^D~G&7)VhT`9J6>MEw0q-v6u;iPhJ zY}z?ACxFWRRB=73oE&0_CP44`f2fh+y&7eJQYA7M^rGeB6n9uqIOnD*|Di^lLl9j) zVU7VE`}f|hRJuGl>?Y9da)SZk^RXYAQ0IF|(lY8BoYu1FYaKE+?{`{~cIvs8q*?V= zHKOuPWn1=hTSI)KBQV}4xQ-I96JYz+V1ODZa)u*234laN)kqkmh|6)5euWbWB3PdM zgz3+Vtkj#KUn$Nm7y;Ig&?Qn@JCRu>oPj?y3{jWmh6)x72o(h<(m^s}iJv(3@nI%7 zA4wG2(Nl@L8Lh5F2N?kjYAX6nZLM z=5Bz0V2X6#21ejiYnfXf*1XS9HbfR0Me-xQHX}SWeZX{mgEUkACMqw|K9~RitrbMl z7)~+Q(pO@GIx@YOi6%*{H|!ruSYmoI36lH>bi$;`$|t^TvMo>KBBNcjqs0q(({@58DL-qIt^ugz~aam1M?y`hJ&1 zx^N_z^twuz%KLJL&F<(7vl`Qz0I^^%k_HlpCyBblz7iqc&v*&e%7_8zVv}DESA@ln zecoMp6S59)ds?#WG6=S5soQa%mgrZEq4KIOUT*Nvb6qFNN#~ za&5L0qK>vKEq`s`3*%6{K;p77)h7@uD`io4pGJu!mXZq3DJ8lp6Ft1gV!WtUPALbo z;ct|Jg<_CHOhOR=tXV91{MZneY%}MRKrB@ia+uHJEZ%GqOVcqnEEFsnBYnF?g^TlF zc^5VS8^9Jw|IazYJ!gil&kR5V`d@WWsHJe?W3Q3_n+}Tq$bRw6LhrL*WHlnZh;qqN zC5akwfMK0!ijKs@&kCBrpF4{W_*1Oor1$eo>B z&7({Vq+04WvpL&1`K_>!o+x!4m3pdC=K_r+mVEgr4nU2Mc2ZI8i%$O!Lz9Hgjk3?( z<}sSMZ^MqoCFegIFgZN$&X+P-G&WjOmFki8C1#WJm=EhG z3mlmlq6H4Camj53x(OWsPN?l#<}V{WW1au z9*jcL3FJ*Imr3@*q`qjDVNSS$OBs)NU!)b6dYwZWlcpFu?kH<&vI=qkyf|+{H0avO z06xbI%vgGHZIiw93NmEP-iZI;#QxLOE|c#IE5?@{rt`7RWc!ocM+;R~-pe4!FXH5hrqeE0lw&7xF zUTEuQSz1)&8~<^4rUv&Ksf!JnaM~wNTDi08vXv*}O8L6x8ZoJ0UWRMG6=wD|(Lm>wrbNwSj6;6(*dIYqOfrpZD!tBfx> zq$c$eq%W^0$4;>mxxeFKgck3prXgr2Sm_M=y4WT}1Q6M5zH1XeJ~;oO%C6DWn9%f^ElQnWl~D~d80QFM zYtsX0Nn@-Uz-&MHi%GlEa_Lu2qorR?EHk!{vF@D4DAs3L3$fjQDl(kK?odVpwBQ&< z*jb#OycPrY|0N-33A^cN+JBdj|6jAK|H~hz0gwSaf!zNTw%2(7-75CK%5^qn37Gz? zT&Hs99!@dwuW}t{WT@nSmh1de*cMzmK`Q?<)LN!d_h6nD0-?8lrq25HEt`J2O7nKME6bzCs49WF1p!=ya z7(8%|=UMz4sl~O3K;cRlap3ZNvLxr2p=Klz**ps`L9Q~!tqoGn>cWT*9#w1$rPU2l zB+X!cx(1e-@my?+0Et+GhN@x~7 zQse4F`WUe|cl3(F8>IBGXD_>@FfuJPS3aLA2ZB!IH zNgp){W-jKJh#4sIx0n}p#yPB4+Tp#B{S9BC_s-|=p%rBjxbuyt6BKD{IPLl#dePo1 z9GHKd7eO|zI`a~j^`$+WRLxp1R;m?#=^H4dqxaZzhmIiPn3_rjaF3yGXtj-@N=k(o z9)Hh029iH<_jpjABw53_pmXRxw>L#ko=F2ZsR<(0m$Lw8yZ|(Rle{g*bE;2HwRJ7< z2Yh$3i8!Am*s$2c9o{5!S-b@U&hccHgZCwaJnpHvkBet~S2!!`k=;yfYd1T^6`gkf zK8pbY2m#SRrGG6v{uM$eL#zL{WmszQwlrb?+cK>GCWQX~cwUVUX+>EFU4b{lTA%Ji z=r*L|Z=NFC|1E?*@U-IpAcW4?A!wFbpiB{PW72l;zFf1|CRFNv@$MEEC`soAt zk-xg;t0-Pm_Ws(Hc2U;diX_evw!jLgD}4zLSX~a6D)Q@a8!b}or}tk&zgxt&e*TF* z)=CN2#-%iB);eZ2yqEeLQv@tJupnXvZ_G})u^sQLO6wwE2x?Jp7sC{`EILZ>veN;2 z{>j+I8g;0UV;3L{t}04BL9C`yZf@h8#C)?IsHPyR-7 z#4%Kk?nEj59ccI5!@y^R!J`0(Pn~2DyjccXAK}RQ86Lh(@9w?AOQ!?713G$TJd&+R z!5Y-^SH#-WSy$E?G=snoCS=lIs-x^i*>hvrG`K=!(a7R}`unpE)*uZ$>fcPiJ!-F2 zfVAJyP`{_omcF~Ei7A%jeev2LoVIS#ydsdl0cOAnTt)+R)Fo6Dr z*Ywusq#4xek@!{mlWAHOQSw|wnPucXh%I7B~M z30Bo@NxPQPk0un;JgM%EW{LIuaWdm_f%rKsFvaRa>G{6 z(}hA+1+^(pU5`=v!ESXit#jc0F-NlaTd}q&^p+=A3X;FO|J6nFNQur+Y-*SWp-Yw`Y}jv~kG>U%Lw~mo+-<5=t@;YECk0%Hvabd^ zp-kMGhZ!((C;h=R ziA@{6G9!gW(hTF3*+^G*`w`^h+bo8o8A$>(Ipnp+%F4y)d)>ltbZ{-=gUw~Vi-ZUz z4~N}EcZb-=3b4h^&0tcpWX$?*93|T%3z2p|u}R-RO#LYy|D7bkyYl{O6k{UnJwokE5&QVa?&@+Z4za`P;&Ze%VX`NnUm_aY zgo*-Fc8Td+pBcK-m2np0!FA&1(qb-bI0XgvF`vTW2mI+#7K*|krc9sEx}3otbBh)mM4Ey$`$HL z$})hZi@&hpV)S8OW8KQ#)N;9+%pGI-TO=>V&!u(F_3i^bD>f&Bid(G9<)b)rI%es1 zkL|<08h4;iHqJdkXipEWwmf6ra$5Nm(?=VG4$)LEr;Ro=pVW%w z6d9(fsqBe9VIcWS-+(IV6n6)Kf8WM1L*#K&$a;(F)i9Z(veq^?mHIR*e@j_b8wumc zpHO~+Q7T`|!)28YAJKL;sDj_WO*B}+I)Rk2iURKZ{V$@EYJeCWg+ohI9%7TD*@n`$ zsfl_4bLAE(ahV*$>fF53rCb@6YYBL~m;)1+J7XM35I}j%pZ9)B^OK$HLt!zE8vNF0 zE4Q7AQ~BFWZGDZ1Q$fj5<@)$%t;wf`*!o(ES^6Ors3W*Ia~Frdi~BJjnW`VG%=Am} z+K%k^&Y)oSy>k#>!RzEgxAMI22C zHMm6J;vVHx;;rrWgZt$h+iIiA1iSySOmd_A)ypC=JpgU0%+%}vu{^uxyJT3WsWdy&SN6q6$b9$p!KhENn zJs;~>C{bs@qW(~Q*`fUao%Rr_5LPYVbX1~5@jT+kIhZg}_?=qL+*T<}r(?EIgODe0 zA;sY_fvGH0r!pAv8D@?ix3f_P1yk{IYFnGijDpt%jbR;r+@E-ZWxZ9XesZvmpL#x_ zSe+mC`!4+l_Jl5$T%)A?1U9B%H}G67GJ(WH@o&jABOX@4vM8 zl+4H#nVFR$$T|1r>mSD+8tPuJKYk}w`HAFPJ0&W>6?Q##HGZs)x!rrLLNuN7?xITf z&!Oer@8ys0E;~N{ISIMD*`RpOa6PK~_j&%^?Y{2&-=9AIJv>zN=it@j+o*d$+5hYg z{fAwO|Nq#fbIt$WE+yXnU$9H<-&LKTh=r#Ovqlhzf9<(v_FQ76o~^dIwMO<0p}E{v z|BczRMnm&|!tB|AR%@2<=nu7djMX^2FY1+kEnECoVVi~JGu*f{j6 z`wE1yQd%nMKEvs$}z4`gqr?SU)ERStuuW7&Z#&GKvbouQ|bh?a^-}d~u z*{JwlRn&Vm^?ML_&jvQ3GTWfi7f4<6osv*13j5tG#T51x?phkSBf(wbtJrB;6m+F7 zW#c!I=~@tTrjPs*CGcj9E#z3HQ#t<6FEvVUAeU$q^^+VQRR-srGdwy1A=Y6ucW}?{j6f#s})=#mq#M>`nsx@7uK zyK&}nb*r%xQy#y`Poi8@D@azT1;#KwUjW8DaIXgL&>At);bkMY%=ge5kE-m_{k;Mi zeM_R_3#cqqe-C4-(6cJ3nM(&Yapos?(vFxUS$BN8CuTkz5z|j6cr%;g4|l6d@?tBR z)G@WY_e8FywZ#5EG^zKLWClpG8~|?1;I)vd#u9eH>IH}sTH(Pc)dt(Plw`TXvJL1$ zc+;GO!eMz`O76Ceoq4IMWnO)(B4uw5^D9&Dm%dKnHGh++VS^9_YD~V;#0OM^%$7%0 zm)L`|QCLiYaARwlXH@I-Fn2?{@TS=s)st#{HI@iE93l=$3T$g9rJ=lcf9lDq1Eyn7 zmiO(+yAJ|`w$~(042h~_5(_cG{6d{!k#fz9-Ua;SvsUior}b{P-|?|qOQh-m=?7wC zLtcbIP0K9B;|}w8OSM<)!P$4mFV@>tnVS0cD$k-6k+)6CZ7*Ba(q2g1mN)>sc0>s| zk{y$~_ByjI zc5bH-zzTK@Q9y#JoX0GHA5)M2LIRR)!+uO-{gnHlDvwtC?a21U))^-_+haoOoFy$+ zr+$BXJbCt4*oQ$DZjrIa1!Qc&@v^2z^{NjEy@VnrDWiB!uLujYwIVBVzxLrs#t_t! zxkxWCk^3ymd<<&zlS;7t>u!ZcLAsn3aB$QAd-)r53&t9j`L=+a+2=8t`)Szpe8FER z7m3GfGhmDK2mljLqqmQbb7+(Ko}{aaq)BSh1EW$#l{3{pPxbwATJsn(J9_x0&r+uR zO0l(FG=4_PucUpGOZ5eNHm(t!(3jdu$d%gyq zN&Q&+9KM Bt7(guy2f;)dHotDO_}zO6~?L&baRmE)YS()6U89Sz@$DDg?Hq=t(M z#&BL8ieR6VgxjyzeG+&5nul8P*OXkMcl%m~^#fFuJp1yvGTIhJzPWuzPH@w+NrU>P zDBHF|THWQxEL#twaLL@n2{d#aehX3T%2!Ry)l8>n^oK^Ypy~OtN5b6oiuxC9)$VFk z9ei>8-j}hkMC^C{#`}?5Mz<$YSfdnvQN~bVcKEQEKEX!AFE19sNvx)!W|zeVpb>Od zd%YK<;NDyvt+=VLGGS78NCkak7|}T0HI!8}L~``ga+P>)iIPm);L{{06 zEh2Vmg!y^PV9ya3sHI=!6k6X%9i>uNt*erBW+}DG#m&_pcWk3yAa{H;IUx%Vt<-KV zRd5G{5t-d;E42&XDp5gWEboH>9ld`VRE?UMdZE>NxE!S`muCH@_$4l`ksJIS_%RGw zrx6wjIeLbH=IC2-Km>RU(qRd{{W2L5R87}SD)DgGT_5f7oe9s5aa)w_uVQ%;miQZ@ zalnx;&aM~sfIgKa3bhW3 zI4JD0gvJG5=h)K~;Zw*?NVKDb11S#kAx~I&^Y!_XRhL-R)?v3LKX(bgB@ME^0SCs- z#R@pl$egbZs3yNV(&vcyGEaEit)%be{yDrMmOI>Mf+knIP)Ugw!38Brxg>;ewiD{~{U6`YQuTFW>b%MFT~ z;j*BK4vzaA6jLONVG3F{aU5ojAks$F!4bq%`dJyO`^c zzxc0qU;t=fEV*k_@%Lq$+ta&u346~^;8ALAcq5hP&?ps5gIrprEwUeBZ(Z@ zhT^E)eB0E;tERHLW?wOp#;abA05SM;jU)kWikNEs z+*FIiw$qZ3F9e2jwH|jT9#CR4>QVg~T5p#cRNG^xxNJNny;NG9aU%t!PdVZXi0JW~ z&UX{&W1MAQZMt)Mn7yTRO4EKCP_^|*A$+NjNmArs)wogsa`U56uf6%eWRuTAJV(eX zDBFotUi$dkOliWd;F;%qs(xv*eD$dv%}2L|&bx3*K=K1A;9NNoQ?R%%zd^vKOepHn z&&3wb#^h_M@5gs0{`v(j&N-zv;lrskEbhpepR{h)sI#cxt-=>Y!N5eWoUqwhr&aGR zJV_N(j_7@sSOET*x#>A%X~9s>`clalNhn^*;Ju))#w?GIQ3E{hvn#rHP#s0CyuLJj zA(h&+G$w2~sunJ#4W_o?sto3vfwK7KqfrC_Sp_fclaP#=RK(^nDWRYlF3f(Eq;rP8 zj+>PWbp7CS(Q#;MRir7tg>5vB@fjHUI1*uyD8>dtC|l>0Mkj|}h>lg@^qRXd%i$BL zrJBUk^tq59%dEV@fyP_;q*eM9VVY|1avidRdU$7GS>5Ah$%w}6%^DZ`gW3nOOALLm zQLd1Kd~ZgXmDcxRsjMzW40NcdW#^k(%!&nF9fthpZ*ws-WK2(iTcpRO33SXI~6go ztWSGm&W%uA(m3{uxdi^#CcXmRS-`Sydif$!jD8hjpSqhGLvO2pH1^6yR%7>VxIU9h z_)5ApaHbUa&p{sGG%MaXlX9dKG`cZI?BfA#m@*FF{bhlE0yLX+d|Z7Mn6OLm8Zg3Hf= z1Wi|`gWFSYwqzb?No_e3=*pjQ-hFY-#yLhx9Ove}ySUUaocwdeDV(pimY?}O2;fA= z@wv>Tyu*Qov+U6sSHXt$C@VgVA0^U^;fbb&Tfqelan=?#x1M)@wLV4D`;QULXLYnqrM#$9X0F09!Ta&W z5mrb?2qR1fHCQE}f7C7y-AQi}ZqdJv7~3j7psRXpoz(P7T+ReY-w7u@c^W?8XUmJ| zA2tBlMua$60&Y*aUjJl`?fU?u?jTgvL41s8`d+-dp)$~Vb{rHq$&P=}(Loce>l5Tk zW8!&DH36Y)d}5Yk1(H(dX_4R3&k1~4PV#k(H(PzvWp#X-{NY?W;N`c6 z%-ha?Wd+DvjU2^MSc2$(QjbdSCD^?4w|(%7OOoJxuEeW;`D>V?M3i}anUH_^ieze= z(*a3&Q;2!XR?M3o_*Pixq^Nz+ z&{N!&$iVK@)WqUOP_fo9ZMis-M1ZbK-MG~d%pd_0k9@dxJV3v|;=}JjeqexUl;}tv zPnM6w+aL0ekrch#qHI*MKI#z~sb`DAC&kZukb>42wd&W3+=axxzfYBhl`aL7*Kt0| z*HCPF{xEKWKTWak{Na>EdoID}ew9aZ6%p;8CbjJh!Q|pRS$K)P_`a{-j~Gr3uaiB& zr$qOs(LJ0e*3ue^d-iiq)3)1M&}eb1HdQ>J;?!H+j)T)&Q$z*jlQ_kf=Y~G^T3EcNW?~MPO-7a2N4;P!$!E3)Wp$IHN^y!NTMVwPTwL$nNW0USviA}@A9MbWhfV@L0R`nOZoqgIVneUdYfCOA zJ0jhM7Fxe=qo1$M$@)IcrG{fTT>JiRGF*`I@_kUb%G7mjkiqoy&oyjo;wI3B;Sqa+ z$4hpE=6ImyN*dK(&xi<{4`Ct}=iIvt#4Y`TP+#ZV8}oJT8=sn=z5m9K^nDb*+223>#q59jixNV`CR-E>eg%&e9ZVg- z0S*TN&XuwKOmr{kII2YzlTsc?p?m0B993Xyu-ZtvjWKuvP!?J*n$9(f=C))L%_--G zW>7nLy*wM(7|Ws42KpmM)Z>9TaNP;L3m7rKm!!Djn9o<_0D6P-wJvc^ng5O#Nhm3Q8{ zOSEa2L8XqSO#|%v72rHqtrM}L^$B2JA4z@FbflcA5CToympR_el07~V>JoW|dTrgw zM=`Tow?5x)jg!kP&-!%l!IXEB_RY7{37)~KJ0mv}>9y`X5}IdPowlyEoEj%>b5XGG zNnS^9g>pFiJexyP+i9OT9=w5Q%0nF2d{{X@WtucJ1QfeB9%rkVg;rE;Jhu+Di}rA< zh5$U=cE07AzRVmoS0etEO&#%M_?kL#bR5YJCl6j+^D*SG%hm!7(|%Pfg@~)r*6eoZ zGl4|iSl~CJqnWRy52Y(i9G&O^F?dtg7N&0HT&!VUeRj@F-XH)$o*SRJUZ@GFG@b*# z3Oy?S`A%w8`tPTsobdSJSa$b@(CgAj7N|vOX|%>Zk4K~3FG{$Ie$)U)nl%+c^CW{# zkr{XaIjjclmbw63yGtzsA{*T?)PIccYBGJFXqnH1;){;Ez)Kj!ku2}M7MvrVMEi49 zhsMex0UzQmFtq_*ZC2Q;I9E*Wa%E7}123Dpr^sJlsxnhB+EH$94(6#VRTD}rM{lR1 z-D``U^Bh#Rzu3}nHJwd%Yj{&~X_3}?qI7?#|AA)5v9kdmW}jP~mnSd)qW3&iEg2|1 z42_E}k4|%2>UZqJW?8xS6<4m+jdMxmI_I=#6I%c>i$Z3yklm?Otw5`uRMyGA^8~70 zWosJ7T%qN)@OmGT^A704RX;}s%gMN5+6QSOy}!EL_Nsz7NIZuz8TbCeMb6i!M}76) zcvKfL*0xM`%l(9%7~D24d|O zg)W=#>JwfR<5g7RhnV1ek;1nIqE(n9vN7H4T{82$y9yz`effw+=9M2GNAS*Z z!7BZ)Yq~Ta!zxud&XT3@hopk#GNC`l&r*#JNcNLKB~6j04{<{Im+uOSOEM@u$_vrY z`;;lnkaOpu9rW16xAMYkgpK>3>yA5}QK+3j`k9}*W|x(3u=dHlmj;@(whu$Q@(Rr! zadPCrq>0Tr4JUaNY*&;4EY~8EB|+PJ-?Jpnr9?Ts1Pe0f%s5!CFlHcYV2=lLCS1tN zCyoqS?S_|`gJc&5i(1n|eIgzDT_E>Nv`^@SM{u}`;CPi8^=Fz~=Ty!0sjAi8h1r!mTO?;WtjYcNRQJAI@&*`iPR7 zX$L%*o9^3kZ?@J=ZoCdOZ1D_!g&(zig0wx2`q?_Whtdm459zGgEx~<;oAw_uMN~~E zJTg!~+8>NF%Adt$2kq7TF>KPS>Eq`JGKpKXtOh03weD<9Wz+ayFK@hj80hG#UC>fIin=-1V2~v7Iq|Mn zi=sngVEX08i7kp^-K&kWzmu&fe)cT}vUS0SdHA*;T=Fuw2?O-aoh!O`q;jo!0)r;! zy9c|Pf9&|$iXApM{CUrJchyLlFK;%u4_~Qp5Uq^;^Cjm_L2)Y`0aT9SJZtf={#Tef z<^=+HYMg{w7?(2YHPg=wa}^a)Z8-Vz<8%t0MSr7nQ;QFLE0@QB{71;?$TBB(F3r}v z5iuld#6`-oUo!QWnWISX2%N@+D9{<@eoVVe-XcX;2dpU6GCMbNl#iSxBmxxut=vJc zdcx-G9T+ZZCXcwPhEA42iC=w@R((#dVdS8AEO-A)OU$cemI;*Ot@M2N(Utu7zW~$A z$H(IX9TBB>*Cd|`R%frZ z=}lPr>*#7*7InHp*1j1qo`j#qzlz`{oL+x-I(%xtLS^@Q`Ks=wiJ5ln@Vl}s?z=KZ z)nANF?P^Q8UoDAm96VyV@wI{;NeJM&du>({Q+_T%#oxx5MzQbJn~ZGWb95e8h#(s@ zf3KMfXyCyAzysg=NA1D_&Wa^3T?6PS73Xn;*C09-^0GM_>0#-4pcYl zmFcbO;d~j1P;N7Pt#O95=wwo3p7&_cag(CX60UdF#nKG+@tgpZnZ&@rYG|{A9+0#s zH!WmVH_J;_wF_c1-(5MKced-X{esemiFT~yNuPkOV~(Y|(?zTncS0?1%PFFa%<*Wu zY{pzny15YxkCF?kU6uaD^s}kn5~n)*9d<3d9qGSUzxd)X9yT)Rs-@LDH)3Cnzo%2O z%RWW*Za+6p?HZ{zvDiB{(1|7k*35~@7wV(KmBx7*LPH9phMt`F_24b%bzPXS;Dx{sbS;RtdJd`|fbjJ7H;+0;gE1EHODU*e?tmp! z5PzzW*XwZDTYL6cD{P-o~RCzlzqE zOlx$3ICdfjqZkeUr8kvC=9I_;~? zBn#m;NX69$oCRlX4Q08}`Qfk3wtGi{P?Ft_s8kB+V~U(y6=a^txAkCMP`)Dxz4G}% z8bYO|BYdg(T;m8&Ks)vJpAT?x4hiswj*!O|QluhS+~*3R=ab<#&>QbNI-H>3l3$@Y9tV)t!1pePsCa!?=X0bav+huweg2G4tX? z`;fWB@15c8K9H=ja71y{-DOsmPE5J|{a)Y|0B^E1FktMn5VgZHbQ z%qB-uUt6y7yM0@7I8BG|qzK-Rq?O-_BlMO&*0}_jNMs)@J6dElOvtbNzSFDv#OnKI z?Yj{9TP|ARQEUqGJlNx$pxmT9KR__%k+H;X+9Rt=a=zo%Z-XfL0oAe*LxrL@qL+*0 z+v6p!E1vw&ArF(+er6_p|JNt3x58at9wh2*zvAF>?~>TO-v0AP|Iwmup?~fD*bgD^ zq(6BoGn~Be{6vCY@<6#M^mGCEw%HJOao&RDdjF=w1j*J!q3}YT`7jfV2xr~pLDt9kPdp>Z{Ei*BC z>gl(m(mQ%1+A9(lP2cR3d4W-*Kr2|@%Wp#Uy2zmEIGYR43idF=zmvm~%9S)M(K90({of^hc+0eMAoh^1cki)Q4^yF@`+)4U0t?Kgo zmkv@NDl+}F9(vX%J=cE1wBtTpy*MOptW#gt;`74XZL-g(mPBQPw&sg@2Ef&HytcgK z68YXzOet;QR(>8ygyG$tT)90^9#A9D(a6|ruWsg3I{AD-OX_arBbAIRhJ2WYbkz>4 z*6`D+mXnSFx#yp?%b)@UiRDTns6UgodWqMou#qycvRMfOn0XXdpR5-aVt3!5sJo}; zNLbr%#^vnZas#_YV^nhxv3*$jr0zOS-Iqn#F)WMhwDBlm2bS{3ERCQsB(E%xT2ZrN z6SMkEf-Reybsg7K{^qdRsfoor@E{Ed_sRh*SDa3GKlQRt6b4=1bL)aMpX5lXyC%ND za>Bg1yju!u@gw{Ewj~D{9Z~k%X-<(pyTaHC(!f^LS$hRMmmR%TC-h~qaWvBGO8lo_o{U~1c z>uYdBlDG)yljbQ~%p3kS)8i#m&a3*%6%Z{IopHqzfjbFIUkx!le=@A~L-Ih+>*NJ& z!oqNiga>*D11Hiuvi!I6zgPRfP_T4%b8%8r+j@nG zS&HbXs6WHyvbXDnPaRWyoUZEs7*&aVK0NUvJiAntUe32N?-b`(a%nWI)2EA1*RwZi zz38i@%OiPos8}Y{Dv;^O)OwyW#K&uY<&k_dcg|(^U-H;|J@p;>I#Ci#mq&8i@kmVO z;yUSy?|6pKo>%bgzY@tG zdpv1Ze&k9G1wT_TAS%6dZG3y>sPh7W4>?IV%_)%=zzhOAzZ26O_YKGZHP$V&YkwS{ z7Egg(1f@f?{sc^eHZJo01OCDWh|&eY_5SS>3?1FSL<7##Cm-oP(Pw98H7_^)FLeLk z$?g9{_rrX(Tze7X|B3Fee^jQW927m6=UL0C{hyLmI58f(gV5K#z=(!0_CL`5E9K2y z!8TBKjA=0iGz>@5eIl$3PJ*!ss#zAxche=SqJ-%_x%1imE^*|sWWU&_#i6h@Yhe4# z=hwaII8(nVM-|sTFTtN|4|`QN1}J>~jucwU`={b&sgiL~BUu7!USn4td5yg64t+by zmVNM%@Px?t;kawhCFk2A&)#&G^Ir%XJfGX(hO7ADa!0WI66{2I&-c$M{c%So3cc~4 zwo8Nyj33?qZAA4}FZab6q~?g8%HTd+9!g~wR--wVoeOaAbB`$~Y$yv4BVAhXDUfUs za+&McL519&F-9{L3h%o`&e|NfTs|sM#ltyJFvbf~N=6#X$o=TkF zKHS3@(~9@FVj|;Ni!{MBiC&e2nHro^w+*NvDL&SE&CEL(wOrIu80~SzLM3J;Uv^SU z_%h~AgGXM-)`kbM`;qCpLg&!Hjf&_X?dlMLQ6_Ng);F2PIOa4-Q6|+*ykRchK6j+X zk$x|68_V_9UIpGvG~}x~H8@_Rcs2Q!daU@%6$kUiV7Ln$V~4L4!;ZAjjd6b({PN7P z%E>i3j$+WfpS~{x8=rOHr9<5J8@6vf)ac)CYFzp5*MRAfoWGXn!i|-JIWw3WZQ^sW z>J2`0el)LQZ(E?9wW~B<{||nZ+cEOX$i0K8nPi?^YnS(Rk8WhVPv@KTt46FS0E6U*MpT`vtI{qLqws=^o82nhL6ArlSg9 zbK8GBe-DpXOFP%im7Sk~d(&xa1B7D`*kb}v`~)_x$J0UY`kf<`wtB5fDsZ=nb| zdJz-fx5|uo_|7&fl@*!)ROtNC7U)xh{*d{3;?h-{2o#~^XgNjDGe16p_rd)>(W^`? z=9k9fkJ!fE5gWoIcxWP_L9dGC^)&A}@0|U7|3>Pc&CS}YA|3Y~?aL!ZRqb0yPsEQY zvm6IebBPSi5OO9TbS;79c=vWLJ$_(B%vk6Paua8`#oE-K@d#Yl=qi-H6Lzq@7#GQ_0VXgFNi1W>+A1-2)gX4LJ^ILzy~zr zc+(S~q?Q*g+tSIguPuDCe|iY-Qc{`MtB65Z!pnuI+paTHp|OdS1!I}+ypo+HafPah z`-EfqmNtthWMnm(PECIpA+*pm14|;J4mD@vT*mCMgGLn7ETMQ!%d*H5;=ix3`BJUA1 z?sbFX^0=kns-+)PMo7$Ce(6P*`7H>kXN8$zV1ym-ISe#{`I^Z9PKdxF6}E;6k4&4v zR$Y@#s21W3zrk~wqz0whxI%M9=D>&}HsmxKxMvFJzGgaImn{+atThQdj38n#G*qn; zT#jFv=L{l;Ed-w?FN95SmPz8gGbOB?blt`aZWGvuA4ejwO!lUx#0~GDPYZG2t`Lq`pC>Tx5;eU7*B`PJ^`#Vpa?OQI$^(y4%e_`$= z*OhQNI>??)+2ZUZDC{AtoP_Sic-jeaygSd5)kf@75M8DRqPBWyI-e{nQw7%{fS&Mv zy`7_l2JQ|)5$uCWOa(9=O9CCnvcu%nBQ7=JT|Lv&!ID5RU^Q&nget`vDNzPzh zI96Kd#~KL`I|3Nf!ol5yOo+W5Sa9bC2Tc#(}X zh=HR=?X`7VZ~uT7T6-*mN&UpRu?h77=9D0ZC#3_1iD83o$&!sFE>o2{7EDfEJ}tH~eL~*DygX*X>mPMu3Gb`6;Sa$l&IU zyu$sA0O@0(eqtMLg$7)%1vTJJW~)z*B-k4WuFPumTo?M*#89<`x7I($1td6b<3LRZ z8n_e@*CphoItv*F!L47u2qn*{$Ra?6cah0nhH&ebAH#PkD(N;x?o@9C;mo5;4_j_3 z4dzwy+qCRVbq`)Y|F!M>=&_UL?ENqA>YVVEJ0lq}DX2%(R;NttOWGd@Jo}1lQKB$> zG;@0X?Pj^qs&(0+oNy;QB$J7ITJBc1HgXu%ZH1M4SVi_6wsU>vRILC8I2z1qVKe+D zN0P%t_Jq#C@!5teKx?~Nye)?ibH}LHJ={l<3}IC6S_t?qg0)Zw{m^qA_`nMc;9*R7 zTWKCv&JM^;3Q(}a^jQUb(^E8a1xMr7#|*o7YMSK@YkzvC*osUj9FD;(#E|w*S@>G4 z7oHj2i;exJS;s5O>~m^w*Kx4()Fzk4?dSTR?94LfEV{?EhUO9s8!fkPpOmqSZ!_?k z>W;TgJEc?cDVVGWWIIy^8}FUFX%KUs_ws2Vja@Z7*Y~_=kM-dO3ptiAfrL5 zAr*LQ{raMkr2@Uk;L+%(@zGmW?J2Hh7kBtHB_U0p>uYj%iulc%3#WV1c*4)C9_60c z@l0;}g6f`CRvwZg@M|h^X$Emgl@)6@4XU?7aHPb5`jj|Glrr^}N}#yr1+E0Dj9Kx4 zB6U}R(wJVZrFr&ZTqD2or)SzYXvEPVW^PxyW*}`mjXRfL*q;;AHK^QJo$fWOGUt?i z?1FqRSh-hAx3Opr6_1KWOT>7B$o#<;%`O!}TvX2j?`yOO3HELLj%M0yFPxyOH z6z6DGp%T8JADN0>oRw^Cl)P;#cFC5!8X#@GD{5$)l5#=o@vMTC3Il#ntbjfxaZ45@ zE9kN!Te*VbOCYbBito>ePDkX0)+jLMiz(pIdQVk#s&iBV)pNCYr^AK#jszr+2TJKq z1IzDa?Ho)*qD$ z02sEzv1&B-4%SX3=@X^p;1t#NFvX(>f!2ds!^P^U8BnIX11b$FLL z-KAP}TCHUUScY6HU|#Evs`t{V*XygbLe<%3K!W<}gLLX_UFxix>s-z2nV9P%V;iDN z8w7&tPnXu4Q6UyfkOa9#Vjske3_16s9$#9gc%;-2D@Td?(U_;xRNw-3jjhKLAy>B` z_7teg4wSIebi*8Kk8MmTZ9G$2cg>~gr$AHdk7jB{t;Nd*Q$%A$EXL&}+9{#4in1mlJ2wpTig!HApp zezdp{pu-suY*?KQBLw@yuaH`)ORJopW@bb+eVJ@MC~b$DLnCS_YtzgY=51Z((1qr< zC}KD~jv7T^d@Xm=3xL)2K{opstizbym}?t|5J^hZwhI_=Xy0wB`Q?0;ucck8zbdkb zg+BElxdZm(WevgK8X&W%O~ECPc9cC{nZEgdDsC%HG#sIrFFYe%>StaHf<|Ih6L%}5?;Ke zaTa`&c1yg}&mHg%N4MWwqO%w<|73#9BY=-PEJt#kkQSJ6S!dc3JZ%S_)8A>C*=fUa z^Fa_4$pVQZvb#1j;XC#I^fJuQF2BOVewMJeQ4w*}N-vuC)-=nXLzaoKjs<{~uZ67? z52njbHMJn#ll>kdfG-GucoytS^ZwPzFrQw1gf$LF0Cc4>&@|lV>^(jg7>EeIO{0Gx zizS6wjC_4F*biT+tZY)fHKEaEP1vB3gMeYwSW zb-E`VElE7v5)Gn@xa)=jzMlopqHoPT@Ah1* zv^jI%e)_UoGZaMYqKmmpQoGz1*$au_rhWz)1n`i`@XLj5g$W1+fDKs|`K1o8;Csfc z6s7LIH~j-4(~Xi8=K9RrKhyt8ZDC5;Th4+5*CB3GtP=f<>WBx&`t^!mJ|IwG;Q$S6 zNefZvweF`fZ$r*3(iDjh5SE!PkTJJ->(kE7+1r(clp2!jeMxfPpO`VpX%^8VR%V%L zmWAoAA4c5z8A+}TKTF`gkrgivIo1ix3fN&2y-7y%^KO0jUdMI+=?#^f3Klm% zy@Qx~&B*G;(oc?ug0N7D{s(hGqd^Eplm5<-SEG!qUE$a+0e&{= zuph=KNVE9RLk^}{WOmxc!CbJdQ`AH3N-Jieaerlgr%Ve=wy44HZJ{@w~w#`Y& z`1YP)HOX>7lE&7))X^<8BdOHmaDsJ;i&_#i`l4^fbg`3hyYqAz4RdTv`ZqXzn#DEq z>2GH?5CW=8o8QQK^fG>E2+>}OZU58DW^tQ-=Gpx}K9!`f(=W3IH%pJ6 z74%aO92OPxi_|+_Ve|OcFF}3H$Cz2WKUCHdjKAvKij(ho#@F^VcE$yO^-Z=hvve{2 zWV8+LMU?fnd;?pc7eEB|-o;An&H!`A9g(Sfk_g84w7!=V#G8HU80HoJ=LjC$?I^_JIe zW}q6V=T>b`uCZmTTK%YXY+em*Zp`efGq7GGh^#|{*3Mk3^SiO;cf7&l_+Ocx&_C;5 zay4NmHzKc9iMnh=-`IdU9}2oIt}eXO~~s3Tmai~g_LZ5x0EM1a3! zMUVe&DrEqWM9Nu4Q{c%^v!&hfS?d3Tswk zx#;k+Srw#%_s~@FHJ%Pga6fTbL-J>iziU12{mVio%c;{nv2jwfj@QhsvO@>_B1@gZ z$AE0B~p?oiC>x8vQpnG&>hZrS%DsUXV5;JP}dyl7NE0sCJjmH|e9 z;J-}l`nQQoG~~a$IZgTNP3HJwyq94H%P|f61Njo;bS8CZv>1Nz!PR~1JOfV~PaRuH z@PY(DD*%A~h)&CcV9LZ*z+P&hgboCA>nHw^@FXzI6ho$DUgPv7h7-(FUE0#r8|NEf zx3Ana$8XP9Gdyx1cAEcScMCKZ>Qgp<%(M@@=FSRqeR$9=%JPTx$9dnS1XWNEhenApkvhjYGJ(mmnGySmP>`^!we49h6AY(i{juq zB~Ip4gxLLnhNhK~ERIX87MGN77-gYZMgxnlu}v1x6@HRRY}PGG8P2W5H(u~JEP>SI z(q5Z7r+`?7as1%qjT##I>y{*Cz=Y3z zf0s7LN(4M)GqFQvX0hk{uN-+T{>(d62AEpm{9lbJcLK@(%* zjV0LVI!Pb~?R$1;r%IX8y{Z>!goGN?-2GpSSRzQEeA`zJg>HHVVWe+B3N}SHE{ECO zseiMzb(kh*5w084Ys_?$+xeEcr<+c@%wDZXA95T3zAfE z!b3sQ)KyVYwtqB7E(7)e7r;R`;wIe)dE{Rs;0)Ub*RzZVgmsbP@n23?DDkPQ+$RT+ zhffKAj6NrWy9F5oM3_vOw5w{((nbDb^{*=(P1pkyH)N4ooFWJGXD4yepIwJc2?SRe z`kIqHC*MdkSaGmJ@pD90$<}RcuhM5r^EXjRk;}e{9Pgx&MwlkN62A@XZn>55t-b;y9h(d7&< zKq6ITJ`77C-HwH7A+bOnAZes=iG9cEqdO@Mv}d8T1N2R`GXQAXBBw66)A>};nXVvW zvvoy%qR$d`hXEFCQF;6|kpx)~7F~E8+kffv!fk0r*3Y_~l0wfX*c zZ4LtH?qy(d_~6e`Dw+h}*n8(Q`Gzlz@!2my%;cL~b$&*d7cz1;aukE~*)88~dOV0K zX>DYsNIcOH8{B>&@m+cXht>x3lfC3{d{HXn?|sy%ws)_B=#rpfSegpBy4LjlcZQM7 zASwU>uvh>91p@KP!KWFSkgL0CQ0$#g&VBoSch5C=62M>>1}K`=q_L8ILm*@%VCy}W z=rgVaUwQkg@fw6)&BU5xbn#L{U|1b|Go;l)?xK2?5PJc``1WSpR9 zK8&nAA}8a~gttsYQK!duwZE=D$hWApe%(piT4?(x!T$f)?)$&-!e4T#7=ZqbMBk*D z|8H_CmGbM@>XA%-)gYn9cKeZRdi(0``1#t2d>OlD*QVW9pduyj$#S#Xf7@68jhw2p zai)geQgoZ_41AJf{g>?KndcqSGMGOR(iQahy8BRuutj(43wleDKE2)Dw)nTDSYdI8 z-oA?d`j6>t%O2|TkdF-oeUPxkk$8$|DAnU_LPTXT$hiOFHF}qDii|eX?~BX>OtB11 z1ZP#;;}9ML5n)=!$3@3_!x9y8=O&P^I_2Jfpt?iqeo#!u8b8`qB;0p;?-e(Re48(* znQ}SmD{V9<-|6VE+L*0eXLDvK-0n?piDFkul5$#$~Z-c zXXKUXj$-IN-0$FDp@OX^$Rc+z1aB0h}+a>_N$3_Xu=gakzV|AHwG}pwK6_UP1fQ6G)bcigk(j-0N@5!*BvgI|WM1OOCXyjVnoi zUM(XTRBKfw7;1v3%|_CRxE3yNA5WY1t|>`L;(!Ve@xhBmS@ZtIUAzJaY`_ovSlEQ0 zP-$V+A)cv}?Vnv&UjPTl{VO>6d$+RUtLgWL3{uLlXNNMBz#xH)Y($J?X7b5<*&j?( z=tFDD^9#5<%qX9_tzXE3@`^#GE)k&rVImJ>N-QXly)b56B!UxeRBU1A8mku?6Kd?@X?OlTiu{1rz3a}l;=m9^TEVj1Y?YhKW3mNS~c``e$rSn}k1 z5upGwojxqbup_~!OvC?4i3(`GqKvCr%TcH%O?Ac>_neA*RPPp|;s2;wr)=_7%xtBq zSv;L17i>!8%ag4<3g@mUjB#3jRJQUf{zRlmU3D_?FyHL9;7!~?ApTgY$@Nmwa$^-_84gx`)QM$TzE#O>M2Vz^xLeF@}mN~)7a@SuT#>q z1$IFk&lV^~GIc&Y#u&K$n1;R~H)B<@#suDohlH>Ji$byb7D&%Eyu_zSxh$ZbwII=; zA|u_Q1yB$a=VYr)SlDUv-7GKq^9_C}06!ZIsR}Y;5>t1)7m6bi&K$V8@6p2Rj__;!6jF8SP7>3N_6v zWy*jWx6>||a~1Mwj07}uLuDQTj2;@z&jQTE-P^Z;_Xi2))u+sKJ}rpZdg2mweVyNZ zlgU@|q@Yg7ef6HWL5CU+2hPb@JGPs;Ni{*TT|0q>JR>d*Oa2xuJ=~)}%m;;*6ROfz zj&I&;f1o8lKMxm_rW2N64455eiO0rjoCSGd>JWp8)M4Vc4NB8!Ei z^T8k}+gzT>VDtzmPu3ZDmB!Dq2$jzbO3JsOQ`2S_@~_^SSE~BV-rOmso2@p18a1EV z+SWxf_1DRAUHnp*!Zx=q!_@@zcYsrDm|oOEWo}XPnB*y~os9C3l3cT6{?8KN$j?@L zcs54}A(cP4bx$A3l8rTr%vtc|j(TBZ^vpzttc1`*l6M9j-8zb28=>KQvt71Qznyv02k z$-%}mvJgl?7cZwdK)r)Fk^-=)+C4qiP5D#&FVm1*~7|@yFKjV|`^C|-9bzmBq zMcTWgR$-6O8L?NjZdk&s-<#Ac*%a@&h`UQ59dix6{coPhzGJpUN{_+2R|~)LL0KkQ z&o3gklH6?Kl-#?3-`%;uJP%x}M3C#8yuWYbKmcBzv%y^TJNmQ0z7sSRTzf z3tWV;poWblSFkxCcL>qMW~p14QJUFD1OMg*zzU7^R#93RMzUJ4S|*A61Ep)W`XRDP zH;gVYkOBvsXO`PZZ{&hlXirzLm)sc>;DY}+Eq@<_4`8N0h9SVPO&{x_XSc72!gNfF z*pMW<1dMPdj4}*-B)AO*q>rF`R&nqyoQx4@5oXWF=6`!vWxyRg zT7m0;2(~A}gRy&B2vdoRIgMHa-5*#BWf;v=;&YRj3o%>_+ge7C-L=m}bs7yhUUO{` z=5YqeGMp3A4)B$#25gzuADvsX9LRMDwVF8Va>e;4*M>t4Me$GLZ3A1uP7L~~`YkWp zOr>+_pdqIIZ5IVVA|H+`~E5PZV@dvSZ!eek(2?r5UXw=stCC$hS`leDfj48Mh$7%#)(gAA8<2;-9Wv_|LKu)jK$tqLV8N%aM#;y7^yQ?fW& zk}$t;=ndx-H@LDcbi!btm0!uD+Onhfo%oY9#VE{-%El83>q0Hx6}5>OI-qVB(yeOJ zic+#8Z)1BfUfC@{zx0rjlLbwa)%zzShF@@sKOt-oovWRyywUdaS}TxA6?w-Z#mrfY zvtK0)E_7m?Eq9a)wbSIv64pLkBrX)oCRRUupIfPFN1WSa!%U(K%UvJr`(_mGER6e0 zd?+wwO*l2<*HqslT^l~g6!|fF=5FCrEVV{ zX)MOlzs?bAe{A;0qrb5wO*;@CE|2+_U-nHCOVsLwOUs1%rJ}4&?~Gj*x+&&FxWKP& zf?{{bWjsS{!i|I~QfXWkXP_5(`R(IzBRLE&Y7zxPTdPv|Pnr9>ID~_iZIP~0q~YuP z(4}!~xdJCNP&;srOJAyDb^UBifJCxEl#|&rb4Fh^9wwm^_Je1Ilsh@~gpL_tfeSFQ zL1h*U!Da$pIxwm!xP`Z_0praBb&*OhWljEB(D0}GU*OXv? z9yc-BfQ?89)939MclQK_FX1as#_W<$v_v)W$eIxi=W1su_+rA`+2qPifj@=96QI$c-5-FGRfsm>-^#dsZkAy6GU` zcfD!V_}rCe%P@XtjNg(ut{0OpkO!Sl6^&ai%H;;duaDZM9ZH?ST@(|0dM2pHbH3ce zXVn1Z52bQjXE=X*YHSoS_RP{!7@8tLAioeYu8y3chlfV1Tt!01h8-;NzOfMFMYtIL z6zHJC@ce^w1+QI+;+O&xF|lw%b^%FMN*0M(Yo&h$Cv@~ZV!viB$TqxwBg!(WKn3Qykg71H@}K6m^_mObu+iB z-eDKg3Z08rm*{MKkz!>O%L;5IKdyD|9;{kyI88j6h+StQXevGj9Kh(qj%n`!5?USH z`$LkgT#qaU#kc9)@*#!J7I)Z=Y;nj58eB1M)W%*1LbtS1AQLlECd1B*{A%N0R;T1i zVUK@Dj&WeZp29T^^#EyWaE|EFXZEI;8#;kWLB>ARzHgWp$?fb*n?Em+SDec(dDn;J zS?`&aD-m@is>RuB>&> zW~%z%+ZQ@G9L$aIwaeLvHDklF9f#MQ>GSZbVTDPFJFs!x=@9c?SS537$GZln#CS1TKP`A3P48lJXn`*0 z2+IHnA5>c^9Zs~W)Ydk>yB|bU(0LGgxttFfFkK1li>l?@#mW*Nz!plox^UJV3=gC9 z;BA4)9_kzg3U?2KXUefTDL(trp`?$nPcp2xG6gg*&NI(Pc1|dVe2s(7E1&T7)GM^9 zvplqo`WW!C#_W4j{zbyw^aq=Mx&E0D^dvU(0Q4dpEaqj)&GUtu#=&B>Tp^hE&6C&V z5)>$R^I@8Uy0RE0bNb1ByL3jxh|S&*sJ}cj;v`qK@C@tGIqqoQ_=v8vrs=o`Ha722 z8*yr!faIB9W!)Px>vQv)O~Rr(O5#QCX^|mv&+v#`u^?sx5jzM+VEGu>-t%O5 zoV$eAXBD8~ub!kX71|+FoNctBjRcS72V1rZ)>TmV%e+4H0{X&t!Q6U+C zV$j^e03vNDl~v*s-sxTP2%ij|8zVz~hfQGQf-QVOq)+5aiRxrEPJ0ovpeL9i>0zD# z+B8qWd8O9>Nrgoo#;iBbbL2Y8J4!80e3_l3Q-PnUUSr{Jwr|283KVP_CMjuOQRAni zU@>|PH?(W~tj?+jKOy!u8@1$9x#yNDC(>sd&cT;}zMrP|@^GS+(j+1@=7T~583 zkn!hbUO(^0het6L4yJxQ5IEt|DXg0znhCmn(QHlFdOwtV)1Jz8EM;Ti@M|i9J~{yZ z^5@-#+Ln669jT7^NR5v)vy&||uLW}@40EVQu*dz;-o1{l3`Z}%+OA*7yD=cN|8?v~ z&G()5Bi>KKy}Wk|5mM=zD$=FcT} zNus?jG>Xx+pM<_RMOe9vI@=2R+Ao&c@$jBG>ln$M!{N~w?hxGWFuY;x^IM?M@!||L z8G9|VV8X}ExqIlwV;*i>g4PBuCv zKGQMG413|u^IQ(_-*CqkzGq;ZQ~KQBl-DM*z+@_R&&WiFyc5vgoU+KN9n;86?AffB z&xdVwf4GUoj6){+MgExz|DWe5_JBJ5NB%!D4(=Y@04)*zS5GBunR;bENjTu|U;@DS zBV1+eF>NFV4HY@iG%Yv*7PE5{a=ujqN|f^!7b;14`ryjPt?^f~yOq~;77O6F{d3BZ zOnP>x1AlCWEQ8y^1lnY7Zn&05u=nTp(?nKLFhoHDZJtqZMVspQ?>+>bFaklK_aS=e zeF*#%8PaPM3WAI1ouS?nh&zTgUO%=fyjQS3j zawSCTIuRv65HuYwxEi@W2gXH8J&X%`z3 z$kGPbGL88C^U^*4ma%)q!?3TLnh<<@#oeFZ>GPA7rypD~GTavs7dPC@Ir;@Z6r%`V zT>vfNE@1dg5-teIkWs-{__Bb%7JQVC;MzEnVlT8goQl@z7)H{Cz6~#%);3mWU^{z; z*uQ?9Udd9sf8fQYco*qSfhrT5)k5i?J!2k3(8{K>9AgTZG-+$21)BV?|gaiLuclW;! zmMH583H(D3$ATnbcK<&s^C?;H@eNNZ|I*Mm=QdbY|En@TS37gV>ThMKA zYwL#53G>#UQ@y8dw3S>4L`ax!zPT5dbbbb9-Qf2zw)@Mw@%*1{zXdeYdDN;uOmkL@ zW(g=b?!h?Y6Sn3jhcb^uPoMPjNo~_U4}6JFVW-cNj8`5FjqPnIMCJe;1G-;!0hr8E za96VNAgkH|ewfo7yG%(mmkA%{+-dgx z7j22#Enci9%Plh3h{qNy=E-@=)ifc6OAQGyWoIL>;_M_PTlJ>#I-fMWvGy!G_~VSH z%e(ShFCg2GC={e)yr(fLsG!Lh6O1i8{rn#|ET$_re42uvn_=#uYXMjRe z*+y53hY1!y2xf^W2U=Y*vg}<-$UGK@nKr8dY0>zUCTgp#&N_#74`k?YR~hnn)Got> z!p6lITf%ydmPbp1qLh=9PEJ$7WMqJxK%v^+p|ngQ?+0E%T?|oQiCJma3@oW+F$kBlRY?_V)v;Kt;9vtT~t^`=rpi)rWlxoaA9@s>~u~kNjN{9GF^aVu=DV+ zBt3?KSh)Z_5TcBRL^0B`@`B5+14{iwPNLo?2&JvVu%XM)=cem2;Zb{S7*OBm}MD-!I}f+j_=rzXbcyz2pJGY;V?0sp*Kwy7RO#kZ%nnL{34IU zMmSGx>gbDq(!wT8GYx|t7S2ZB9)cb3=Ot=lF-uf~HN*ObhwMyd-`H{e`v!oF9=8dY zwm)nw&RnbC4F+Lug9>LcQ5rf9Bq~-$7?~`?+jxo?0-j}3rS2I$^sJXy};bopmoxD{vKXD66 zJI$e&tZl5H2%tR^nKqXUq8arO%?ZenaNf>hU%jTK?uPpEyA_6vf z`u>U7+ZC}UOP+f4ycoy9^BdKj=*@Mt;g&2q70|2*Fu#D=_o*F6e{Hi-17uNnH@x z9`-dtSNEI*548nz?5n8`Bk(S+;yv;etw7FsVA6q_;edRwbfigpPdH=UIdshY`&6;1 z1fW<<(^c6F5`nU4iL{TnM|s8dA(&7j>0__ z+DS-+QG`etWK$x1!x)Cj zzpd7vc;3X$RzKwWYt!H09{5vOgT?FqPUFT(rtI_4LvEjb)a$-&x*0ttc>P2DsOo_1 zqjSbX?w<-qb!WP`Vm2&1Zo8goY+BCp-=FfBV`bF)#zrMFS}uVF4`^^}YQm|sDX6Z~ zz&{Hy|K~x-|NjmE4gnbc$(i;4FUkM@l4t?|zzV?VF^~bk@$3KD&@xa!bPj14&(;7M$odKZ literal 0 HcmV?d00001 From 36cb8ed894895a6bd1e7ab3755f6adde6ec77d21 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 16 Jul 2019 10:44:02 +0100 Subject: [PATCH 400/497] none -> m.none --- proposals/2134-identity-hash-lookup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 3f869f0d..09e4748a 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -119,12 +119,12 @@ There are certain situations when an identity server cannot be expected to compare hashed 3PID values; When a server is connected to a backend provider such as LDAP, there is no way for the identity server to efficiently pull all of the addresses and hash them. For this case, the `algorithm` field of `GET -/hash_details` may be set to `"none"`, and `lookup_pepper` will be an empty +/hash_details` may be set to `"m.none"`, and `lookup_pepper` will be an empty string. No hashing will be performed if the client and server decide on this, and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. When performing a lookup, the pepper and hashing algorithm the client used -must be part of the request body (even when using the `"none"` algorithm +must be part of the request body (even when using the `"m.none"` algorithm value). If they do not match what the server has on file (which may be the case if the pepper was changed right after the client's request for it), then the server must inform the client that they need to query the hash details From 9ebcff5758d43e18d4062334f873c678660eb54d Mon Sep 17 00:00:00 2001 From: Sorunome Date: Tue, 16 Jul 2019 17:11:07 +0200 Subject: [PATCH 401/497] fix typo, add section on html details element --- proposals/2010-spoilers.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/proposals/2010-spoilers.md b/proposals/2010-spoilers.md index cf969902..1d9f4dc9 100644 --- a/proposals/2010-spoilers.md +++ b/proposals/2010-spoilers.md @@ -53,6 +53,12 @@ however that wouldn't be HTML-compliant. Instead of limiting the proposed `data-mx-spoiler` attribute only to the ``-tag it could be added to all tags, however it might make implementations for clients more complicated. +Alternatively the [details](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) tag could +be used. This, however, is a block element, and the spoilers are span elements. Furthermore +semantically there is a slight difference: with the details tag you hide something for a person +as it uses up a lot of screen space, while with a spoiler you hide something as a person might not +want to see it. + ## Potential issues Depending on context it might make sense to put other events, such as `m.image`, into spoilers, too. This MSC doesn't address that at all. Using @@ -60,7 +66,7 @@ too. This MSC doesn't address that at all. Using This MSC doesn't take HTML block elements into account. -Clients would have to come up with a way how to input spoilers. This could be done, for example, +Clients would have to come up with a way to input spoilers. This could be done, for example, by adding a custom markdown tag (like discord does), so that you do `Text ||spoiler||`, however that doesn't take a spoiler reason into account. From 15994c61a54c1010a7a422ce9e39ca04db422bdf Mon Sep 17 00:00:00 2001 From: Luca Becker Date: Tue, 16 Jul 2019 17:33:13 +0200 Subject: [PATCH 402/497] Clarification regarding authorisation rules The rules for m.room.power_levels power were somewhat unclear regarding the behaviour towards the always present keys, such as kick and ban. Additionally, it is now also clarified that in the users and events dictionary also added and removed keys are taken into consideration. --- specification/rooms/v1.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index b5ef217a..ba25fa21 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -243,14 +243,15 @@ The rules are as follows: #. If there is no previous ``m.room.power_levels`` event in the room, allow. - #. For each of the keys ``users_default``, ``events_default``, - ``state_default``, ``ban``, ``redact``, ``kick``, ``invite``, as well as - each entry being changed under the ``events`` or ``users`` keys: + #. For the keys ``users_default``, ``events_default``, + ``state_default``, ``ban``, ``redact``, ``kick``, ``invite`` check if they were changed. + For each of the changed keys, as well as + each entry being added, changed or removed under the ``events`` or ``users`` keys: - i. If the current value is higher than the ``sender``'s current power level, + i. If the current value is present and higher than the ``sender``'s current power level, reject. - #. If the new value is higher than the ``sender``'s current power level, + #. If the new value is present and higher than the ``sender``'s current power level, reject. #. For each entry being changed under the ``users`` key, other than the From 8aece4f6448394ca9dc8635b0d6c1b89809e07e4 Mon Sep 17 00:00:00 2001 From: Luca Becker Date: Wed, 17 Jul 2019 23:26:10 +0200 Subject: [PATCH 403/497] Incorporated @richvdh suggestions --- specification/rooms/v1.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index ba25fa21..6d79323f 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -245,14 +245,23 @@ The rules are as follows: #. For the keys ``users_default``, ``events_default``, ``state_default``, ``ban``, ``redact``, ``kick``, ``invite`` check if they were changed. - For each of the changed keys, as well as - each entry being added, changed or removed under the ``events`` or ``users`` keys: + For each of the changed keys: - i. If the current value is present and higher than the ``sender``'s current power level, + i. If the current value is higher than the ``sender``'s current power level, reject. - #. If the new value is present and higher than the ``sender``'s current power level, + #. If the new value is higher than the ``sender``'s current power level, reject. + + #. For each entry being added, changed or removed in both the ``events`` and ``users`` keys: + + i. If the current value is higher than the ``sender``'s current power level, + reject. + + #. If the new value is higher than the ``sender``'s current power level, + reject. + + #. (Note: current/new value can also denote the inferred value from either ``users_default``, ``events_default`` or ``state_default``) #. For each entry being changed under the ``users`` key, other than the ``sender``'s own entry: From 094005dca1fd79796a731d5669c0fe0fe6808e0e Mon Sep 17 00:00:00 2001 From: Luca Becker Date: Thu, 18 Jul 2019 08:55:58 +0200 Subject: [PATCH 404/497] Incorporated @turt2live suggestions. Added missing added and removed to the rule, because these keys are not required for m.room.power_levels. Also moved the note down to the Note section. --- specification/rooms/v1.rst | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index 6d79323f..eb453b58 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -244,8 +244,8 @@ The rules are as follows: #. If there is no previous ``m.room.power_levels`` event in the room, allow. #. For the keys ``users_default``, ``events_default``, - ``state_default``, ``ban``, ``redact``, ``kick``, ``invite`` check if they were changed. - For each of the changed keys: + ``state_default``, ``ban``, ``redact``, ``kick``, ``invite`` check if they + were added, changed or removed. For each found alteration: i. If the current value is higher than the ``sender``'s current power level, reject. @@ -253,15 +253,14 @@ The rules are as follows: #. If the new value is higher than the ``sender``'s current power level, reject. - #. For each entry being added, changed or removed in both the ``events`` and ``users`` keys: + #. For each entry being added, changed or removed in both the ``events`` and + ``users`` keys: i. If the current value is higher than the ``sender``'s current power level, reject. #. If the new value is higher than the ``sender``'s current power level, reject. - - #. (Note: current/new value can also denote the inferred value from either ``users_default``, ``events_default`` or ``state_default``) #. For each entry being changed under the ``users`` key, other than the ``sender``'s own entry: @@ -285,15 +284,19 @@ The rules are as follows: .. NOTE:: - Some consequences of these rules: + * Some consequences of these rules: - * Unless you are a member of the room, the only permitted operations (apart - from the initial create/join) are: joining a public room; accepting or - rejecting an invitation to a room. + * Unless you are a member of the room, the only permitted operations (apart + from the initial create/join) are: joining a public room; accepting or + rejecting an invitation to a room. - * To unban somebody, you must have power level greater than or equal to both - the kick *and* ban levels, *and* greater than the target user's power - level. + * To unban somebody, you must have power level greater than or equal to both + the kick *and* ban levels, *and* greater than the target user's power + level. + + * Power levels may also be inferred from defaults. So, mentions of, for example, + the ``sender``'s power level might also refer to a default power level that is + applied. The same holds true for events. Event format ~~~~~~~~~~~~ From 4503327450c1017d1266c363268ceb8c3c670f01 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 22 Jul 2019 15:17:52 +0100 Subject: [PATCH 405/497] Add some compatibility hacks. --- proposals/2174-move-redacts-key.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proposals/2174-move-redacts-key.md b/proposals/2174-move-redacts-key.md index ca3083a6..21212257 100644 --- a/proposals/2174-move-redacts-key.md +++ b/proposals/2174-move-redacts-key.md @@ -7,3 +7,11 @@ ID of the event being redacted. The presence of this field at the event level, rather than under the `content` key, is anomalous. This MSC proposes that, in a future room version, the `redacts` property be moved under the `content` key. + +For backwards-compatibility with *older* clients, servers should add a `redacts` +property to the top level of `m.room.redaction` events in *newer* room versions +when serving such events over the Client-Server API. + +For improved compatibility with *newer* clients, servers should add a `redacts` +property to the `content` of `m.room.redaction` events in *older* room versions +when serving such events over the Client-Server API. From 0444c8016b469540717ec2054799f3d80eb6a700 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 22 Jul 2019 15:33:49 +0100 Subject: [PATCH 406/497] review comments --- proposals/2134-identity-hash-lookup.md | 52 +++++++++++++++----------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 09e4748a..3fc92b53 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -65,11 +65,7 @@ hashed). First the client must append the medium to the address: ``` Hashes must be peppered in order to reduce both the information an identity -server gains during the process, and attacks the client can perform. Clients -will have to generate a full rainbow table specific to the set pepper to -obtain all registered MXIDs, while the server has to generate a full rainbow -table with the specific pepper to get the plaintext 3pids for non-matrix -users. +server gains during the process, and attacks the client can perform. [0] In order for clients to know the pepper and hashing algorithm they should use, Identity servers must make the information available on the `/hash_details` @@ -87,13 +83,14 @@ GET /_matrix/identity/v2/hash_details The name `lookup_pepper` was chosen in order to account for pepper values being returned for other endpoints in the future. The contents of `lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+` (unless no -hashing is being performed, as described below). If `lookup_pepper` is an -empty string, clients MUST cease the lookup operation. +hashing is being performed, as described below). If hashing is being +performed, and `lookup_pepper` is an empty string, clients MUST cease the +lookup operation. -``` The client should append the pepper to the end of the 3PID string before hashing. +``` "alice@example.com email" -> "alice@example.com emailmatrixrocks" "bob@example.com email" -> "bob@example.com emailmatrixrocks" "carl@example.com email" -> "carl@example.com emailmatrixrocks" @@ -106,22 +103,26 @@ handle identity servers which may rotate their pepper values frequently. Clients MUST choose one of the given hash algorithms to encrypt the 3PID during lookup. -At a minimum, clients and identity servers MUST support SHA-256 as defined by -[RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the -`algorithm` value `"sha256"`. SHA-256 was chosen as it is currently used -throughout the Matrix spec, as well as its properties of being quick to hash. -While this reduces the resources necessary to generate a rainbow table for -attackers, a fast hash is necessary if particularly slow mobile clients are -going to be hashing thousands of contact details. Other algorithms can be -negotiated by the client and server at their discretion. +Clients and identity servers MUST support SHA-256 as defined by [RFC +4634](https://tools.ietf.org/html/rfc4634), identified by the `algorithm` +value `"sha256"`. SHA-256 was chosen as it is currently used throughout the +Matrix spec, as well as its properties of being quick to hash. While this +reduces the resources necessary to generate a rainbow table for attackers, a +fast hash is necessary if particularly slow mobile clients are going to be +hashing thousands of contact details. Other algorithms can be negotiated by +the client and server at their discretion. There are certain situations when an identity server cannot be expected to -compare hashed 3PID values; When a server is connected to a backend provider -such as LDAP, there is no way for the identity server to efficiently pull all -of the addresses and hash them. For this case, the `algorithm` field of `GET -/hash_details` may be set to `"m.none"`, and `lookup_pepper` will be an empty -string. No hashing will be performed if the client and server decide on this, -and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. +compare hashed 3PID values; for example, when a server is connected to a +backend provider such as LDAP, there is no way for the identity server to +efficiently pull all of the addresses and hash them. For this case, clients +and server MUST also support sending plain-text 3PID values. To agree upon +this, the `algorithm` field of `GET /hash_details` MUST be set to `"m.none"`, +whereas `lookup_pepper` will be an empty string. No hashing will be performed +if the client and server decide on this, and 3PIDs will be sent in +plain-text, similar to the v1 `/lookup` API. When this occurs, it is STRONGLY +RECOMMENDED for the client to prompt the user before continuing, and receive +consent for sending 3PID details in plain-text to the identity server. When performing a lookup, the pepper and hashing algorithm the client used must be part of the request body (even when using the `"m.none"` algorithm @@ -277,3 +278,10 @@ This proposal outlines a simple method to stop bulk collection of user's contact lists and their social graphs without any disastrous side effects. All functionality which depends on the lookup service should continue to function unhindered by the use of hashes. + +## Footnotes + +[0] Clients would have to generate a full rainbow table specific to the set +pepper to obtain all registered MXIDs, while the server would have to +generate a full rainbow table with the specific pepper to get the plaintext +3pids for non-matrix users. From 887cd5e7d056000bc05cee6b28d7d1bf595edfaa Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 22 Jul 2019 16:00:29 +0100 Subject: [PATCH 407/497] I really hope someone doesn't invest none-hash --- proposals/2134-identity-hash-lookup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 3fc92b53..9a5cee11 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -117,7 +117,7 @@ compare hashed 3PID values; for example, when a server is connected to a backend provider such as LDAP, there is no way for the identity server to efficiently pull all of the addresses and hash them. For this case, clients and server MUST also support sending plain-text 3PID values. To agree upon -this, the `algorithm` field of `GET /hash_details` MUST be set to `"m.none"`, +this, the `algorithm` field of `GET /hash_details` MUST be set to `"none"`, whereas `lookup_pepper` will be an empty string. No hashing will be performed if the client and server decide on this, and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. When this occurs, it is STRONGLY @@ -125,7 +125,7 @@ RECOMMENDED for the client to prompt the user before continuing, and receive consent for sending 3PID details in plain-text to the identity server. When performing a lookup, the pepper and hashing algorithm the client used -must be part of the request body (even when using the `"m.none"` algorithm +must be part of the request body (even when using the `"none"` algorithm value). If they do not match what the server has on file (which may be the case if the pepper was changed right after the client's request for it), then the server must inform the client that they need to query the hash details From d43111cdd2cbfa56f1f3113443b2cf8a1fe30b1d Mon Sep 17 00:00:00 2001 From: Luca Becker Date: Tue, 23 Jul 2019 11:25:34 +0200 Subject: [PATCH 408/497] Incorporated @turt2live suggestions. Used **Note** to describe notes around the authorisation rules. Otherwise restored the original state for the consequences from the auth rules. Moved the clarification regarding default power levels up above the auth rules. Removed third sentence. And followed @turt2live's example, but opted for "for users in that room" because the default user power level is applied to all users. --- specification/rooms/v1.rst | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index eb453b58..0b4e4f65 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -109,6 +109,8 @@ The types of state events that affect authorization are: - ``m.room.power_levels`` - ``m.room.third_party_invite`` +**Note:** Power levels are inferred from defaults when not explicitly supplied. For example, mentions of the ``sender``'s power level can also refer to the default power level for users in the room. + The rules are as follows: 1. If type is ``m.room.create``: @@ -282,21 +284,17 @@ The rules are as follows: #. Otherwise, allow. -.. NOTE:: - * Some consequences of these rules: - * Unless you are a member of the room, the only permitted operations (apart - from the initial create/join) are: joining a public room; accepting or - rejecting an invitation to a room. + **Note:** Some consequences of these rules: - * To unban somebody, you must have power level greater than or equal to both - the kick *and* ban levels, *and* greater than the target user's power - level. - - * Power levels may also be inferred from defaults. So, mentions of, for example, - the ``sender``'s power level might also refer to a default power level that is - applied. The same holds true for events. + * Unless you are a member of the room, the only permitted operations (apart + from the initial create/join) are: joining a public room; accepting or + rejecting an invitation to a room. + + * To unban somebody, you must have power level greater than or equal to both + the kick *and* ban levels, *and* greater than the target user's power + level. Event format ~~~~~~~~~~~~ From 577021f12b9edfd3ca0b428fa3774aa540a8b632 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 23 Jul 2019 11:48:01 +0100 Subject: [PATCH 409/497] resolve some comments --- proposals/2134-identity-hash-lookup.md | 90 ++++++++++++-------------- 1 file changed, 42 insertions(+), 48 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 9a5cee11..8db758dc 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -1,8 +1,8 @@ # MSC2134: Identity Hash Lookups [Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been -recently created in response to a security issue brought up by an independent -party. To summarise the issue, lookups (of Matrix user IDs) are performed using +created in response to a security issue brought up by an independent party. +To summarise the issue, lookups (of Matrix user IDs) are performed using plain-text 3PIDs (third-party IDs) which means that the identity server can identify and record every 3PID that the user has in their contacts, whether that email address or phone number is already known by the identity server or @@ -26,10 +26,10 @@ which will leak less data to identity servers. ## Proposal This proposal suggests making changes to the Identity Service API's lookup -endpoints. Instead, this proposal consolidates them into a single `/lookup` -endpoint. Additionally, the endpoint is to be on a `v2` path, to avoid -confusion with the original `/lookup`. We also drop the `/api` in order to -preserve consistency across other endpoints: +endpoints, consolidating them into a single `/lookup` endpoint. The endpoint +is to be on a `v2` path, to avoid confusion with the original `v1` `/lookup`. +The `/api` part is also dropped in order to preserve consistency across other +endpoints: - `/_matrix/identity/v2/lookup` @@ -68,7 +68,7 @@ Hashes must be peppered in order to reduce both the information an identity server gains during the process, and attacks the client can perform. [0] In order for clients to know the pepper and hashing algorithm they should use, -Identity servers must make the information available on the `/hash_details` +identity servers must make the information available on the `/hash_details` endpoint: ``` @@ -104,25 +104,30 @@ Clients MUST choose one of the given hash algorithms to encrypt the 3PID during lookup. Clients and identity servers MUST support SHA-256 as defined by [RFC -4634](https://tools.ietf.org/html/rfc4634), identified by the `algorithm` -value `"sha256"`. SHA-256 was chosen as it is currently used throughout the -Matrix spec, as well as its properties of being quick to hash. While this -reduces the resources necessary to generate a rainbow table for attackers, a -fast hash is necessary if particularly slow mobile clients are going to be -hashing thousands of contact details. Other algorithms can be negotiated by -the client and server at their discretion. +4634](https://tools.ietf.org/html/rfc4634), identified by the value +`"sha256"` in the `algorithms` array. SHA-256 was chosen as it is currently +used throughout the Matrix spec, as well as its properties of being quick to +hash. While this reduces the resources necessary to generate a rainbow table +for attackers, a fast hash is necessary if particularly slow mobile clients +are going to be hashing thousands of contact details. Other algorithms are +negotiated by the client and server at their discretion. There are certain situations when an identity server cannot be expected to compare hashed 3PID values; for example, when a server is connected to a backend provider such as LDAP, there is no way for the identity server to efficiently pull all of the addresses and hash them. For this case, clients and server MUST also support sending plain-text 3PID values. To agree upon -this, the `algorithm` field of `GET /hash_details` MUST be set to `"none"`, -whereas `lookup_pepper` will be an empty string. No hashing will be performed -if the client and server decide on this, and 3PIDs will be sent in -plain-text, similar to the v1 `/lookup` API. When this occurs, it is STRONGLY -RECOMMENDED for the client to prompt the user before continuing, and receive -consent for sending 3PID details in plain-text to the identity server. +this, the `"algorithms"` field of `GET /hash_details` MUST contain the value +`"none"`, and `lookup_pepper` will be an empty string. For this case, the +identity server could only send `"none"` as part of the `"algorithms"` array. +The client can then decide whether it wants to accept this. The identity +server could also send `["none", "sha256"]` and cease from looking up +contacts in LDAP unless `"none"` is decided upon. + +No hashing will be performed if the client and server decide on `"none"`, and +3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. When this +occurs, it is STRONGLY RECOMMENDED for the client to prompt the user before +continuing. When performing a lookup, the pepper and hashing algorithm the client used must be part of the request body (even when using the `"none"` algorithm @@ -132,16 +137,15 @@ the server must inform the client that they need to query the hash details again, instead of just returning an empty response, which clients would assume to mean that no contacts are registered on that identity server. -If the algorithm does not match the server's, the server should return a `400 +If the algorithm is not supported by the server, the server should return a `400 M_INVALID_PARAM`. If the pepper does not match the server's, the server should return a new error code, `400 M_INVALID_PEPPER`. A new error code is not defined for an invalid algorithm as that is considered a client bug. -The `M_INVALID_PEPPER` error response should contain the correct `algorithm` -and `lookup_pepper` fields. This is to prevent the client from needing to -query `/hash_details` again, thus saving a round-trip. `M_INVALID_PARAM` does -not include these fields. An example response to an incorrect pepper would -be: +The `M_INVALID_PEPPER` error response contain the correct `algorithm` and +`lookup_pepper` fields. This is to prevent the client from needing to query +`/hash_details` again, thus saving a request. `M_INVALID_PARAM` does not +include these fields. An example response to an incorrect pepper would be: ``` { @@ -207,10 +211,9 @@ as part of this proposal. implementation, and should return a `403 M_FORBIDDEN` error if so. If an identity server is too old and a HTTP 400 or 404 is received when -accessing the `v2` endpoint, they should fallback to the `v1` endpoint instead. -However, clients should be aware that plain-text 3PIDs are required for the -`v1` endpoint, and SHOULD ask for user consent to send 3PIDs in plain-text, and -be clear about where they are being sent to. +accessing the `v2` endpoint, clients should fallback to the `v1` endpoint +instead. However, clients should be aware that plain-text 3PIDs are required +for the `v1` endpoints, and are strongly encouraged to warn the user of this. ## Tradeoffs @@ -229,14 +232,6 @@ Mediums and peppers are appended to the address as to prevent a common prefix for each plain-text string, which prevents attackers from pre-computing bits of a stream cipher. -Additionally, this proposal does not stop an identity server from storing -plain-text 3PIDs. There is a GDPR argument in keeping email addresses, such -that if a breach happens, users must be notified of such. Ideally this would be -done over Matrix, but people may've stuck their email in an identity server and -then left Matrix forever. Perhaps if only hashes were being stored on the -identity server then that isn't considered personal information? In any case, a -discussion for another MSC. - ## Other considered solutions Ideally identity servers would never receive plain-text addresses, however it @@ -251,16 +246,15 @@ eventual solution of using Software Guard Extensions (detailed in https://signal.org/blog/private-contact-discovery/) is considered impractical for a federated network, as it requires specialized hardware. -k-anonymity was considered as an alternative, in which the identity server -would never receive a full hash of a 3PID that it did not already know about. -While this has been considered plausible, it comes with heightened resource -requirements (much more hashing by the identity server). The conclusion was -that it may not provide more privacy if an identity server decided to be evil, -however it would significantly raise the resource requirements to run an evil -identity server. - -Discussion and a walk-through of what a client/identity-server interaction would -look like are documented [in this Github +k-anonymity was considered as an alternative approach, in which the identity +server would never receive a full hash of a 3PID that it did not already know +about. While this has been considered plausible, it comes with heightened +resource requirements (much more hashing by the identity server). The +conclusion was that it may not provide more privacy if an identity server +decided to be evil, however it would significantly raise the resource +requirements to run an evil identity server. Discussion and a walk-through of +what a client/identity-server interaction would look like are documented [in +this Github comment](https://github.com/matrix-org/matrix-doc/pull/2134#discussion_r298691748). Additionally, a radical model was also considered where the first portion of From b26a9ed1fd7f847a701028efcba55f6aff82d1c3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 23 Jul 2019 13:28:42 +0100 Subject: [PATCH 410/497] Expand on why we can't trust dirty homeservers --- proposals/2134-identity-hash-lookup.md | 30 ++++++++++++++++---------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 8db758dc..5bd4889a 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -234,10 +234,6 @@ of a stream cipher. ## Other considered solutions -Ideally identity servers would never receive plain-text addresses, however it -is necessary for the identity server to send email/sms messages during a -bind, as it cannot trust a homeserver to do so as the homeserver may be lying. - Bloom filters are an alternative method of providing private contact discovery. However, they do not scale well due to requiring clients to download a large filter that needs updating every time a new bind is made. Further considered @@ -257,15 +253,27 @@ what a client/identity-server interaction would look like are documented [in this Github comment](https://github.com/matrix-org/matrix-doc/pull/2134#discussion_r298691748). -Additionally, a radical model was also considered where the first portion of -the above scheme was done with an identity server, and the second would be done -with various homeservers who originally reported the 3PID to the identity -server. While interesting and a more decentralised model, some attacks are -still possible if the identity server is running an evil homeserver which it -can direct the client to send its hashes to. Discussion on this matter has -taken place in the MSC-specific room [starting at this +A radical model was also considered where the first portion of the +k-anonyminity scheme was done with an identity server, and the second would +be done with various homeservers who originally reported the 3PID to the +identity server. While interesting and a more decentralised model, some +attacks are still possible if the identity server is running an evil +homeserver which it can direct the client to send its hashes to. Discussion +on this matter has taken place in the MSC-specific room [starting at this message](https://matrix.to/#/!LlraCeVuFgMaxvRySN:amorgan.xyz/$4wzTSsspbLVa6Lx5cBq6toh6P3TY3YnoxALZuO8n9gk?via=amorgan.xyz&via=matrix.org&via=matrix.vgorcum.com). +Ideally identity servers would never receive plain-text addresses, just +storing and receiving hash values instead. However, it is necessary for the +identity server to have plain-text addresses during a +[bind](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-3pid-bind) +call, in order to send a verification email or sms message. It is not +feasible to defer this job to a homeserver, as the identity server cannot +trust that the homeserver has actually performed verification. Thus it may +not be possible to prevent plain-text 3PIDs of registered Matrix users from +being sent to the identity server at least once. Yet, we can still do our +best by coming up with creative ways to prevent non-matrix user 3PIDs from +leaking to the identity server, when they're sent in a lookup. + ## Conclusion This proposal outlines a simple method to stop bulk collection of user's From 9fd6bd318461cba6226fffdbc00f2fac6b839036 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 23 Jul 2019 15:16:27 +0100 Subject: [PATCH 411/497] Add details about why this proposal should exist --- proposals/2134-identity-hash-lookup.md | 47 ++++++++++++++++++-------- 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 5bd4889a..23c155f4 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -6,22 +6,41 @@ To summarise the issue, lookups (of Matrix user IDs) are performed using plain-text 3PIDs (third-party IDs) which means that the identity server can identify and record every 3PID that the user has in their contacts, whether that email address or phone number is already known by the identity server or -not. +not. In the latter case, an identity server is able to collect email +addresses and phone numbers that have a high probability of being connected +to a real person. It could then use this data for marketing or other +purposes. -If the 3PID is hashed, the identity server could not determine the address -unless it has already seen that address in plain-text during a previous call -of the [/bind -mechanism](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-3pid-bind) -(without significant resources to reverse the hashes). This helps prevent -bulk collection of user's contact lists by the identity server and reduces -its ability to build social graphs. +However, if the email addresses and phone numbers are hashed before they are +sent to the identity server, the server would have a more difficult time of +being able to recover the original addresses. This prevents contact +information of non-Matrix users being exposed by the lookup service. -This proposal thus calls for the Identity Service API's -[/lookup](https://matrix.org/docs/spec/identity_service/r0.2.1#get-matrix-identity-api-v1-lookup) -endpoint to use hashed 3PIDs instead of their plain-text counterparts (and to -deprecate both it and -[/bulk_lookup](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-bulk-lookup)), -which will leak less data to identity servers. +However, hashing is not perfect. While reversing a hash is not possible, it +is possible to build a [rainbow +table](https://en.wikipedia.org/wiki/Rainbow_table), which could map many +known email addresses and phone numbers to their hash equivalents. When the +identity server receives a hash, it would then be able to look it up in this +table, and find the email address or phone number associated with it. In an +ideal world, one would use a hashing algorithm such as +[bcrypt](https://en.wikipedia.org/wiki/Bcrypt), with many rounds, which would +make building such a rainbow table an extraordinarily expensive process. +Unfortunately, this is impractical for our use case, as it would require +clients to perform many, many rounds of hashing, linearly dependent on their +address book size, which would likely result in lower-end mobile phones +becoming overwhelmed. Thus, we must use a fast hashing algorithm, at the cost +of making rainbow tables easy to build. + +The rainbow table attack is not perfect. While there are only so many +possible phone numbers, and thus it is simple to generate the hash value for +each one, the address space of email addresses is much, much wider. Therefore +if your email address is decently long and is not publicly known to +attackers, it is unlikely that it would be included in a rainbow table. + +Thus the approach of hashing, while adding complexity to implementation and +minor resource consumption of the client and identity server, does provide +added difficultly for the identity server to carry out contact detail +harvesting, which should be considered worthwhile. ## Proposal From 3031df79cc67419c40851afe6eea6985cc18c843 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 23 Jul 2019 16:33:24 +0100 Subject: [PATCH 412/497] Add example for none algo --- proposals/2134-identity-hash-lookup.md | 157 +++++++++++++++++-------- 1 file changed, 107 insertions(+), 50 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 23c155f4..d6cb0506 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -2,45 +2,46 @@ [Issue #2130](https://github.com/matrix-org/matrix-doc/issues/2130) has been created in response to a security issue brought up by an independent party. -To summarise the issue, lookups (of Matrix user IDs) are performed using -plain-text 3PIDs (third-party IDs) which means that the identity server can -identify and record every 3PID that the user has in their contacts, whether -that email address or phone number is already known by the identity server or -not. In the latter case, an identity server is able to collect email -addresses and phone numbers that have a high probability of being connected -to a real person. It could then use this data for marketing or other -purposes. +To summarise the issue, when a user wants to ask an identity server which of +its contacts have registered a Matrix account, it performs a lookup against +an identity server. The client currently sends all of its contact details in +the form of plain-text addresses, meaning that the identity server can +identify and record every third-party ID (3PID) of the user's contacts. This +allows the identity server is able to collect email addresses and phone +numbers that have a high probability of being connected to a real person. +This data could then be used for marketing, political campaigns, etc. -However, if the email addresses and phone numbers are hashed before they are +However, if these email addresses and phone numbers are hashed before they are sent to the identity server, the server would have a more difficult time of being able to recover the original addresses. This prevents contact -information of non-Matrix users being exposed by the lookup service. +information of non-Matrix users being exposed to the lookup service. -However, hashing is not perfect. While reversing a hash is not possible, it -is possible to build a [rainbow -table](https://en.wikipedia.org/wiki/Rainbow_table), which could map many -known email addresses and phone numbers to their hash equivalents. When the -identity server receives a hash, it would then be able to look it up in this -table, and find the email address or phone number associated with it. In an -ideal world, one would use a hashing algorithm such as -[bcrypt](https://en.wikipedia.org/wiki/Bcrypt), with many rounds, which would -make building such a rainbow table an extraordinarily expensive process. -Unfortunately, this is impractical for our use case, as it would require -clients to perform many, many rounds of hashing, linearly dependent on their -address book size, which would likely result in lower-end mobile phones -becoming overwhelmed. Thus, we must use a fast hashing algorithm, at the cost -of making rainbow tables easy to build. +Yet, hashing is not perfect. While reversing a hash is not possible, it is +possible to build a [rainbow +table](https://en.wikipedia.org/wiki/Rainbow_table), which maps known email +addresses and phone numbers to their hash equivalents. When the identity +server receives a hash, it is then be able to look it up in its rainbow table +and find the corresponding 3PID. To prevent this, one would use a hashing +algorithm such as [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) with many +rounds, making the construction of a large rainbow table an infeasibly +expensive process. Unfortunately, this is impractical for our use case, as it +would require clients to also perform many, many rounds of hashing, linearly +dependent on the size of their address book, which would likely result in +lower-end mobile phones becoming overwhelmed. We are then forced to use a +fast hashing algorithm, at the cost of making rainbow tables easy to build. -The rainbow table attack is not perfect. While there are only so many -possible phone numbers, and thus it is simple to generate the hash value for -each one, the address space of email addresses is much, much wider. Therefore -if your email address is decently long and is not publicly known to -attackers, it is unlikely that it would be included in a rainbow table. +The rainbow table attack is not perfect, because one does need to know email +addresses and phone numbers to build it. While there are only so many +possible phone numbers, and thus it is relatively inexpensive to generate the +hash value for each one, the address space of email addresses is much, much +wider. If your email address is decently long and is not publicly +known to attackers, it is unlikely that it would be included in a rainbow +table. Thus the approach of hashing, while adding complexity to implementation and -minor resource consumption of the client and identity server, does provide -added difficultly for the identity server to carry out contact detail -harvesting, which should be considered worthwhile. +resource consumption of the client and identity server, does provide added +difficulty for the identity server to carry out contact detail harvesting, +which should be considered worthwhile. ## Proposal @@ -106,8 +107,7 @@ hashing is being performed, as described below). If hashing is being performed, and `lookup_pepper` is an empty string, clients MUST cease the lookup operation. -The client should append the pepper to the end of the 3PID string before -hashing. +If hashing, the client should append the pepper to the end of the 3PID string. ``` "alice@example.com email" -> "alice@example.com emailmatrixrocks" @@ -119,8 +119,8 @@ hashing. Clients SHOULD request this endpoint each time before performing a lookup, to handle identity servers which may rotate their pepper values frequently. -Clients MUST choose one of the given hash algorithms to encrypt the 3PID -during lookup. +Clients MUST choose one of the given `algorithms` values to encrypt the +3PID during lookup. Clients and identity servers MUST support SHA-256 as defined by [RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the value @@ -133,15 +133,11 @@ negotiated by the client and server at their discretion. There are certain situations when an identity server cannot be expected to compare hashed 3PID values; for example, when a server is connected to a -backend provider such as LDAP, there is no way for the identity server to -efficiently pull all of the addresses and hash them. For this case, clients +backend provider such as LDAP, it is not efficient for the identity server to +pull all of the addresses and hash them on lookup. For this case, clients and server MUST also support sending plain-text 3PID values. To agree upon this, the `"algorithms"` field of `GET /hash_details` MUST contain the value -`"none"`, and `lookup_pepper` will be an empty string. For this case, the -identity server could only send `"none"` as part of the `"algorithms"` array. -The client can then decide whether it wants to accept this. The identity -server could also send `["none", "sha256"]` and cease from looking up -contacts in LDAP unless `"none"` is decided upon. +`"none"`. No hashing will be performed if the client and server decide on `"none"`, and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. When this @@ -153,7 +149,7 @@ must be part of the request body (even when using the `"none"` algorithm value). If they do not match what the server has on file (which may be the case if the pepper was changed right after the client's request for it), then the server must inform the client that they need to query the hash details -again, instead of just returning an empty response, which clients would +again, as opposed to just returning an empty response, which clients would assume to mean that no contacts are registered on that identity server. If the algorithm is not supported by the server, the server should return a `400 @@ -175,11 +171,11 @@ include these fields. An example response to an incorrect pepper would be: } ``` -Now comes time for the lookup. Note that the resulting hash digest MUST be -encoded in URL-safe unpadded base64 (similar to [room version 4's event +Now comes time for the lookup. We'll first cover an example of the client +choosing the `"sha256"` algorithm. Note that the resulting hash digest MUST +be encoded in URL-safe unpadded base64 (similar to [room version 4's event IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). Once hashing has been -performed using the defined hashing algorithm, the client sends each hash in an -array. +performed, the client sends each hash in an array. ``` NOTE: Hashes are not real values @@ -193,7 +189,7 @@ NOTE: Hashes are not real values POST /_matrix/identity/v2/lookup { - "hashes": [ + "addresses": [ "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs", "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE", "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw", @@ -206,7 +202,7 @@ POST /_matrix/identity/v2/lookup ``` The identity server, upon receiving these hashes, can simply compare against -the hashes of the 3PIDs it stores. The server then responds with the Matrix +the hashes of the 3PIDs it stores. The server then responds with the Matrix IDs of those that match: ``` @@ -220,6 +216,67 @@ IDs of those that match: The client can now display which 3PIDs link to which Matrix IDs. +For the case of the identity server sending, and the client choosing, +`"none"` as the algorithm, we would do the following. + +The client would first make `GET` a request to `/hash_details`, perhaps +receiving the response: + +``` +{ + "lookup_pepper": "matrixrocks", + "algorithms": ["none", "sha256"] +} +``` + +The client decides that it would like to use `"none"`, and thus ignores the +lookup pepper, as no hashing will occur. Appending a space and the 3PID +medium to each address is still necessary: + +``` +"alice@example.com" -> "alice@example.com email" +"bob@example.com" -> "bob@example.com email" +"carl@example.com" -> "carl@example.com email" +"12345678910" -> "12345678910 msisdn" +"denny@example.com" -> "denny@example.com email" +``` + +The client then sends these off to the identity server in a `POST` request to +`/lookup`: + +``` +POST /_matrix/identity/v2/lookup + +{ + "addresses": [ + "alice@example.com email", + "bob@example.com email", + "carl@example.com email", + "12345678910 msisdn", + "denny@example.com email" + ], + "algorithm": "none", + "pepper": "matrixrocks" +} +``` + +Note that even though we haven't used the `lookup_pepper` value, we still +include the same one sent to us by the identity server in `/hash_details`. +The identity server should still return `400 M_INVALID_PEPPER` if the pepper +is incorrect. This is intended to make implementation simpler. + +Finally, the identity server will check its database for the Matrix user IDs +it has that correspond to these 3PID addresses, and returns them: + +``` +{ + "mappings": { + "alice@example.com email": "@alice:example.com", + "12345678910 msisdn": "@fred:example.com" + } +} +``` + No parameter changes will be made to [/bind](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-3pid-bind) as part of this proposal. From 3b8c57e06ca961c6842ab409b64f825b8884c573 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 23 Jul 2019 16:43:55 +0100 Subject: [PATCH 413/497] Don't require servers/clients to support "none" --- proposals/2134-identity-hash-lookup.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index d6cb0506..b40f9f28 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -134,10 +134,11 @@ negotiated by the client and server at their discretion. There are certain situations when an identity server cannot be expected to compare hashed 3PID values; for example, when a server is connected to a backend provider such as LDAP, it is not efficient for the identity server to -pull all of the addresses and hash them on lookup. For this case, clients -and server MUST also support sending plain-text 3PID values. To agree upon -this, the `"algorithms"` field of `GET /hash_details` MUST contain the value -`"none"`. +pull all of the addresses and hash them upon lookup. For this case, can also +support receiving plain-text 3PID addresses from clients. To agree upon this, +the value `"none"` can be added to the `"algorithms"` array of `GET +/hash_details`. The client can then choose to send plain-text values by +setting the `"algorithm"` value in `POST /lookup` to `"none"`. No hashing will be performed if the client and server decide on `"none"`, and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. When this From c7a23557d4f4f88e09d15317861164db1b2a97b6 Mon Sep 17 00:00:00 2001 From: Luca Becker Date: Tue, 23 Jul 2019 17:57:22 +0200 Subject: [PATCH 414/497] Last cosmetic changes switched back to the use of `.. NOTE::` --- specification/rooms/v1.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index 0b4e4f65..02e4f3e4 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -109,7 +109,11 @@ The types of state events that affect authorization are: - ``m.room.power_levels`` - ``m.room.third_party_invite`` -**Note:** Power levels are inferred from defaults when not explicitly supplied. For example, mentions of the ``sender``'s power level can also refer to the default power level for users in the room. +.. NOTE:: + + Power levels are inferred from defaults when not explicitly supplied. + For example, mentions of the ``sender``'s power level can also refer + to the default power level for users in the room. The rules are as follows: @@ -284,11 +288,11 @@ The rules are as follows: #. Otherwise, allow. +.. NOTE:: + Some consequences of these rules: - **Note:** Some consequences of these rules: - - * Unless you are a member of the room, the only permitted operations (apart + * Unless you are a member of the room, the only permitted operations (apart from the initial create/join) are: joining a public room; accepting or rejecting an invitation to a room. From f4d6b6c26124de47c88ed4c73f788864fb37b97c Mon Sep 17 00:00:00 2001 From: Luca Becker Date: Tue, 23 Jul 2019 17:58:40 +0200 Subject: [PATCH 415/497] Fixed broken indentations --- specification/rooms/v1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/rooms/v1.rst b/specification/rooms/v1.rst index 02e4f3e4..a720b41a 100644 --- a/specification/rooms/v1.rst +++ b/specification/rooms/v1.rst @@ -292,7 +292,7 @@ The rules are as follows: Some consequences of these rules: - * Unless you are a member of the room, the only permitted operations (apart + * Unless you are a member of the room, the only permitted operations (apart from the initial create/join) are: joining a public room; accepting or rejecting an invitation to a room. From 8f3e58870830569693afae86c42b44dc8cb30f0b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 24 Jul 2019 15:27:48 +0100 Subject: [PATCH 416/497] pepper is not a secret val. Still needs to be around. --- proposals/2134-identity-hash-lookup.md | 28 +++++++++++++++----------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index b40f9f28..72bc4e53 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -7,9 +7,9 @@ its contacts have registered a Matrix account, it performs a lookup against an identity server. The client currently sends all of its contact details in the form of plain-text addresses, meaning that the identity server can identify and record every third-party ID (3PID) of the user's contacts. This -allows the identity server is able to collect email addresses and phone -numbers that have a high probability of being connected to a real person. -This data could then be used for marketing, political campaigns, etc. +allows the identity server to collect email addresses and phone numbers that +have a high probability of being connected to a real person. This data could +then be used for marketing, political campaigns, etc. However, if these email addresses and phone numbers are hashed before they are sent to the identity server, the server would have a more difficult time of @@ -71,10 +71,14 @@ denny@example.com ``` The client will hash each 3PID as a concatenation of the medium and address, -separated by a space and a pepper appended to the end. Note that phone numbers -should be formatted as defined by +separated by a space and a pepper appended to the end. Note that phone +numbers should be formatted as defined by https://matrix.org/docs/spec/appendices#pstn-phone-numbers, before being -hashed). First the client must append the medium to the address: +hashed). Note that "pepper" in this proposal simply refers to a public, +opaque string that is used to produce different hash results between identity +servers. Its value is not secret. + +First the client must append the medium to the address: ``` "alice@example.com" -> "alice@example.com email" @@ -102,12 +106,11 @@ GET /_matrix/identity/v2/hash_details The name `lookup_pepper` was chosen in order to account for pepper values being returned for other endpoints in the future. The contents of -`lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+` (unless no -hashing is being performed, as described below). If hashing is being -performed, and `lookup_pepper` is an empty string, clients MUST cease the -lookup operation. +`lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+`, whether +hashing is being performed or not. When no hashing is occuring, a pepper +value of at least length 1 is still required. -If hashing, the client should append the pepper to the end of the 3PID string. +If hashing, the client appends the pepper to the end of the 3PID string. ``` "alice@example.com email" -> "alice@example.com emailmatrixrocks" @@ -264,7 +267,8 @@ POST /_matrix/identity/v2/lookup Note that even though we haven't used the `lookup_pepper` value, we still include the same one sent to us by the identity server in `/hash_details`. The identity server should still return `400 M_INVALID_PEPPER` if the pepper -is incorrect. This is intended to make implementation simpler. +is incorrect. This simplifies things and can help ensure the client is +requesting `/hash_details` properly before each lookup request. Finally, the identity server will check its database for the Matrix user IDs it has that correspond to these 3PID addresses, and returns them: From c6dd5951a15cf1be34c8794ffd6ca2657f34af27 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 25 Jul 2019 18:53:32 +0100 Subject: [PATCH 417/497] Clients can cache the hash details if they want to --- proposals/2134-identity-hash-lookup.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 72bc4e53..83b0dceb 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -120,10 +120,10 @@ If hashing, the client appends the pepper to the end of the 3PID string. "denny@example.com email" -> "denny@example.com emailmatrixrocks" ``` -Clients SHOULD request this endpoint each time before performing a lookup, to -handle identity servers which may rotate their pepper values frequently. -Clients MUST choose one of the given `algorithms` values to encrypt the -3PID during lookup. +Clients can cache the result of this endpoint, but should re-request it +during an error on `/lookup`, to handle identity servers which may rotate +their pepper values frequently. Clients MUST choose one of the given +`algorithms` values to encrypt the 3PID during lookup. Clients and identity servers MUST support SHA-256 as defined by [RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the value From da876bb340ddd1130bba69afc5b09a3ac40000da Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 25 Jul 2019 18:54:02 +0100 Subject: [PATCH 418/497] missing word --- proposals/2134-identity-hash-lookup.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 83b0dceb..0151808b 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -137,11 +137,11 @@ negotiated by the client and server at their discretion. There are certain situations when an identity server cannot be expected to compare hashed 3PID values; for example, when a server is connected to a backend provider such as LDAP, it is not efficient for the identity server to -pull all of the addresses and hash them upon lookup. For this case, can also -support receiving plain-text 3PID addresses from clients. To agree upon this, -the value `"none"` can be added to the `"algorithms"` array of `GET -/hash_details`. The client can then choose to send plain-text values by -setting the `"algorithm"` value in `POST /lookup` to `"none"`. +pull all of the addresses and hash them upon lookup. For this case, identity +servers can also support receiving plain-text 3PID addresses from clients. To +agree upon this, the value `"none"` can be added to the `"algorithms"` array +of `GET /hash_details`. The client can then choose to send plain-text values +by setting the `"algorithm"` value in `POST /lookup` to `"none"`. No hashing will be performed if the client and server decide on `"none"`, and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. When this From 0ac70b268accded4d7f1c563eca7048ff95d1658 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 25 Jul 2019 18:55:57 +0100 Subject: [PATCH 419/497] Clarify peppering should not happen on none algo --- proposals/2134-identity-hash-lookup.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 0151808b..0eb996be 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -143,10 +143,10 @@ agree upon this, the value `"none"` can be added to the `"algorithms"` array of `GET /hash_details`. The client can then choose to send plain-text values by setting the `"algorithm"` value in `POST /lookup` to `"none"`. -No hashing will be performed if the client and server decide on `"none"`, and -3PIDs will be sent in plain-text, similar to the v1 `/lookup` API. When this -occurs, it is STRONGLY RECOMMENDED for the client to prompt the user before -continuing. +No hashing nor peppering will be performed if the client and server decide on +`"none"`, and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` +API. When this occurs, it is STRONGLY RECOMMENDED for the client to prompt +the user before continuing. When performing a lookup, the pepper and hashing algorithm the client used must be part of the request body (even when using the `"none"` algorithm From 20c72a3649139889d2f86f872972e4a94182ea38 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 25 Jul 2019 18:56:17 +0100 Subject: [PATCH 420/497] Update proposals/2134-identity-hash-lookup.md Co-Authored-By: David Baker --- proposals/2134-identity-hash-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 72bc4e53..1d797086 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -161,7 +161,7 @@ M_INVALID_PARAM`. If the pepper does not match the server's, the server should return a new error code, `400 M_INVALID_PEPPER`. A new error code is not defined for an invalid algorithm as that is considered a client bug. -The `M_INVALID_PEPPER` error response contain the correct `algorithm` and +The `M_INVALID_PEPPER` error response contains the correct `algorithm` and `lookup_pepper` fields. This is to prevent the client from needing to query `/hash_details` again, thus saving a request. `M_INVALID_PARAM` does not include these fields. An example response to an incorrect pepper would be: From 6119b9a50dea51c67790b7ac1916ad9d2f1df472 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 25 Jul 2019 19:03:43 +0100 Subject: [PATCH 421/497] *@hobnobbob.com is unlikely to be guessed --- proposals/2134-identity-hash-lookup.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 0eb996be..d6512c5a 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -34,9 +34,9 @@ The rainbow table attack is not perfect, because one does need to know email addresses and phone numbers to build it. While there are only so many possible phone numbers, and thus it is relatively inexpensive to generate the hash value for each one, the address space of email addresses is much, much -wider. If your email address is decently long and is not publicly -known to attackers, it is unlikely that it would be included in a rainbow -table. +wider. If your email address is not share a common mailserver, decently long +or is not publicly known to attackers, it is unlikely that it would be +included in a rainbow table. Thus the approach of hashing, while adding complexity to implementation and resource consumption of the client and identity server, does provide added @@ -306,8 +306,9 @@ for the `v1` endpoints, and are strongly encouraged to warn the user of this. Hashes are still reversible with a rainbow table, but the provided pepper, which can be rotated by identity servers at will, should help mitigate this. Phone numbers (with their relatively short possible address space of 12 -numbers), short email addresses, and addresses of both type that have been -leaked in database dumps are more susceptible to hash reversal. +numbers), short email addresses at popular domains, and addresses of both +type that have been leaked in database dumps are more susceptible to hash +reversal. Mediums and peppers are appended to the address as to prevent a common prefix for each plain-text string, which prevents attackers from pre-computing bits From ffbfde8a09cad00fa178e2dd1817b7cac1abf9e5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Fri, 26 Jul 2019 11:40:20 +0100 Subject: [PATCH 422/497] Update proposals/2134-identity-hash-lookup.md Co-Authored-By: Hubert Chathi --- proposals/2134-identity-hash-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 2abbc5a9..1872af69 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -34,7 +34,7 @@ The rainbow table attack is not perfect, because one does need to know email addresses and phone numbers to build it. While there are only so many possible phone numbers, and thus it is relatively inexpensive to generate the hash value for each one, the address space of email addresses is much, much -wider. If your email address is not share a common mailserver, decently long +wider. If your email address does not use a common mail server, is decently long or is not publicly known to attackers, it is unlikely that it would be included in a rainbow table. From 5580a2a1a9796d68eab2c71dbee3f67d31ebe1ad Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Fri, 26 Jul 2019 11:40:38 +0100 Subject: [PATCH 423/497] Update proposals/2134-identity-hash-lookup.md Co-Authored-By: Hubert Chathi --- proposals/2134-identity-hash-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 1872af69..1df58df1 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -70,7 +70,7 @@ carl@example.com denny@example.com ``` -The client will hash each 3PID as a concatenation of the medium and address, +The client will hash each 3PID as a concatenation of the address and medium, separated by a space and a pepper appended to the end. Note that phone numbers should be formatted as defined by https://matrix.org/docs/spec/appendices#pstn-phone-numbers, before being From a17c74f592bafebb7d4d4c8b49318e37ec0d8c92 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 26 Jul 2019 12:00:53 +0100 Subject: [PATCH 424/497] switch medium and address around, space between address and pepper --- proposals/2134-identity-hash-lookup.md | 63 +++++++++++++------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 2abbc5a9..8e20d250 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -71,21 +71,21 @@ denny@example.com ``` The client will hash each 3PID as a concatenation of the medium and address, -separated by a space and a pepper appended to the end. Note that phone -numbers should be formatted as defined by +separated by a space and a pepper, also separated by a space, appended to the +end. Note that phone numbers should be formatted as defined by https://matrix.org/docs/spec/appendices#pstn-phone-numbers, before being hashed). Note that "pepper" in this proposal simply refers to a public, opaque string that is used to produce different hash results between identity servers. Its value is not secret. -First the client must append the medium to the address: +First the client must prepend the medium (plus a space) to the address: ``` -"alice@example.com" -> "alice@example.com email" -"bob@example.com" -> "bob@example.com email" -"carl@example.com" -> "carl@example.com email" -"+1 234 567 8910" -> "12345678910 msisdn" -"denny@example.com" -> "denny@example.com email" +"alice@example.com" -> "email alice@example.com" +"bob@example.com" -> "email bob@example.com" +"carl@example.com" -> "email carl@example.com" +"+1 234 567 8910" -> "msisdn 12345678910" +"denny@example.com" -> "email denny@example.com" ``` Hashes must be peppered in order to reduce both the information an identity @@ -110,14 +110,15 @@ being returned for other endpoints in the future. The contents of hashing is being performed or not. When no hashing is occuring, a pepper value of at least length 1 is still required. -If hashing, the client appends the pepper to the end of the 3PID string. +If hashing, the client appends the pepper to the end of the 3PID string, +after a space. ``` -"alice@example.com email" -> "alice@example.com emailmatrixrocks" -"bob@example.com email" -> "bob@example.com emailmatrixrocks" -"carl@example.com email" -> "carl@example.com emailmatrixrocks" -"12345678910 msdisn" -> "12345678910 msisdnmatrixrocks" -"denny@example.com email" -> "denny@example.com emailmatrixrocks" +"alice@example.com email" -> "email alice@example.com matrixrocks" +"bob@example.com email" -> "email bob@example.com matrixrocks" +"carl@example.com email" -> "email carl@example.com matrixrocks" +"12345678910 msdisn" -> "msisdn 12345678910 matrixrocks" +"denny@example.com email" -> "email denny@example.com matrixrocks" ``` Clients can cache the result of this endpoint, but should re-request it @@ -184,11 +185,11 @@ performed, the client sends each hash in an array. ``` NOTE: Hashes are not real values -"alice@example.com emailmatrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" -"bob@example.com emailmatrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" -"carl@example.com emailmatrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" -"12345678910 msisdnmatrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" -"denny@example.com emailmatrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" +"email alice@example.com matrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" +"email bob@example.com matrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" +"email carl@example.com matrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" +"msisdn 12345678910 matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" +"email denny@example.com matrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" POST /_matrix/identity/v2/lookup @@ -238,11 +239,11 @@ lookup pepper, as no hashing will occur. Appending a space and the 3PID medium to each address is still necessary: ``` -"alice@example.com" -> "alice@example.com email" -"bob@example.com" -> "bob@example.com email" -"carl@example.com" -> "carl@example.com email" -"12345678910" -> "12345678910 msisdn" -"denny@example.com" -> "denny@example.com email" +"alice@example.com" -> "email alice@example.com" +"bob@example.com" -> "email bob@example.com" +"carl@example.com" -> "email carl@example.com" +"+1 234 567 8910" -> "msisdn 12345678910" +"denny@example.com" -> "email denny@example.com" ``` The client then sends these off to the identity server in a `POST` request to @@ -253,11 +254,11 @@ POST /_matrix/identity/v2/lookup { "addresses": [ - "alice@example.com email", - "bob@example.com email", - "carl@example.com email", - "12345678910 msisdn", - "denny@example.com email" + "email alice@example.com", + "email bob@example.com", + "email carl@example.com", + "msisdn 12345678910", + "email denny@example.com" ], "algorithm": "none", "pepper": "matrixrocks" @@ -276,8 +277,8 @@ it has that correspond to these 3PID addresses, and returns them: ``` { "mappings": { - "alice@example.com email": "@alice:example.com", - "12345678910 msisdn": "@fred:example.com" + "email alice@example.com": "@alice:example.com", + "msisdn 12345678910": "@fred:example.com" } } ``` From 6660768d85f2f8eac2ec9efa2613884e159d6576 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 26 Jul 2019 12:04:17 +0100 Subject: [PATCH 425/497] Don't repeat fast hash bit --- proposals/2134-identity-hash-lookup.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index de11221a..7b3edbc5 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -130,10 +130,7 @@ Clients and identity servers MUST support SHA-256 as defined by [RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the value `"sha256"` in the `algorithms` array. SHA-256 was chosen as it is currently used throughout the Matrix spec, as well as its properties of being quick to -hash. While this reduces the resources necessary to generate a rainbow table -for attackers, a fast hash is necessary if particularly slow mobile clients -are going to be hashing thousands of contact details. Other algorithms are -negotiated by the client and server at their discretion. +hash. There are certain situations when an identity server cannot be expected to compare hashed 3PID values; for example, when a server is connected to a From 4d1f2ea4f40d3fedce718f42c4151fb970fe9aa4 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Fri, 26 Jul 2019 12:05:41 +0100 Subject: [PATCH 426/497] Apply suggestions from code review Co-Authored-By: Hubert Chathi --- proposals/2134-identity-hash-lookup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index de11221a..13cea82e 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -124,7 +124,7 @@ after a space. Clients can cache the result of this endpoint, but should re-request it during an error on `/lookup`, to handle identity servers which may rotate their pepper values frequently. Clients MUST choose one of the given -`algorithms` values to encrypt the 3PID during lookup. +`algorithms` values to hash the 3PID during lookup. Clients and identity servers MUST support SHA-256 as defined by [RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the value @@ -160,7 +160,7 @@ assume to mean that no contacts are registered on that identity server. If the algorithm is not supported by the server, the server should return a `400 M_INVALID_PARAM`. If the pepper does not match the server's, the server should return a new error code, `400 M_INVALID_PEPPER`. A new error code is not -defined for an invalid algorithm as that is considered a client bug. +defined for an unsupported algorithm as that is considered a client bug. The `M_INVALID_PEPPER` error response contains the correct `algorithm` and `lookup_pepper` fields. This is to prevent the client from needing to query @@ -308,7 +308,7 @@ Hashes are still reversible with a rainbow table, but the provided pepper, which can be rotated by identity servers at will, should help mitigate this. Phone numbers (with their relatively short possible address space of 12 numbers), short email addresses at popular domains, and addresses of both -type that have been leaked in database dumps are more susceptible to hash +types that have been leaked in database dumps are more susceptible to hash reversal. Mediums and peppers are appended to the address as to prevent a common prefix From 4c22eb86b50d1fb6bd28d98d9c29037aba2b2cac Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Mon, 29 Jul 2019 16:30:25 +0100 Subject: [PATCH 427/497] MSC for Search Filtering in Federation /publicRooms Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 proposals/2197-search_filter_in_federation_publicrooms.md diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md new file mode 100644 index 00000000..60d35333 --- /dev/null +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -0,0 +1,108 @@ +# MSC2197 – Search Filtering in Public Room Directory over Federation + +This MSC proposes introducing the `POST` method to the `/publicRooms` Federation API endpoint, +including a `filter` argument which allows server-side filtering of rooms. + +We are motivated by the opportunity to make searching the public Room Directory more efficient over +Federation. + +## Motivation + +Although the Client-Server API includes the filtering capability in `/publicRooms`, the Federation API +currently does not. + +This leads to a situation that is wasteful of effort and network traffic for both homeservers; searching +a remote server involves first downloading its entire room list and then filtering afterwards. + +## Proposal + +Having a filtered `/publicRooms` API endpoint means that irrelevant or uninteresting rooms can be +excluded from a room directory query response. In turn, this means that these room directory query +responses can be generated more quickly and then, due to their smaller size, transmitted over the network more quickly, owing to their +smaller size. + +These benefits have been exploited in the Client-Server API, which implements search filtering +using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. + +It should be noted that the Client-Server and Federation APIs both currently possess `/publicRooms` +endpoints which, whilst similar, are not equivalent. + +Ignoring the `server` parameter in the Client-Server API, the following specific differences are +noticed: + +* the Federation API endpoint only accepts the `GET` method whereas the Client-Server API accepts + the `POST` method as well. +* the Federation API accepts `third_party_instance_id` and `include_all_networks` parameters through + the `GET` method, whereas the Client-Server API only features these in the `POST` method. + +This MSC proposes to introduce support for the `POST` method in the Federation API's `/publicRooms` +endpoint, with all but one of the parameters from that of the Client-Server API. The copied parameters +shall have the same semantics as they do in the Client-Server API. + +In the interest of clarity, the proposed parameter set is listed below, along with a repetition of the +definitions of used substructures. The response format has been omitted as it is the same as that of +the current Client-Server and Federation APIs, which do not differ in this respect. + +### `POST /_matrix/federation/v1/publicRooms` + +#### Query Parameters + +There are no query parameters. Notably, we intentionally do not inherit the `server` query parameter +from the Client-Server API. + +#### JSON Body Parameters + +* `limit` (`integer`): Limit the number of search results returned. +* `since` (`string`): A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. +* `filter` (`Filter`): Filter to apply to the results. +* `include_all_networks` (`boolean`): Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to false. +* `third_party_instance_id` (`boolean`): The specific third party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. + +### `Filter` Parameters + +* `generic_search_term` (`string`): A string to search for in the room metadata, e.g. name, topic, canonical alias etc. (Optional). + +## Tradeoffs + +An alternative approach might be for implementations to carry on as they are but also +cache (and potentially index) remote homeservers' room directories. This would not require +a spec change. + +However, this would be unsatisfactory because it would lead to outdated room directory results and/or +caches that provide no benefit (as room directory searches are generally infrequent enough that a cache +would be outdated before being reused, on small – if not most – homeservers). + +## Potential issues + +### Backwards Compatibility + +After this proposal is implemented, outdated homeservers will still exist which do not support the room +filtering functionality specified in this MSC. In this case, homeservers will have to fall-back to downloading +the entire room directory and performing the filtering themselves, as currently happens. This is not considered +a problem since it will not lead to a situation that is any worse than the current one, and it is expected that +large homeservers – which cause the most work with the current search implementations – would be quick to upgrade +to support this feature once it is available. + +In addition, as the `POST` method was not previously accepted on the `/publicRooms` endpoint over federation, +then it is not a difficult task to use a `405 Method Not Allowed` HTTP response as a signal that fallback is required. + +## Security considerations + +There are no known security considerations. + +## Privacy considerations + +At current, remote homeservers do not learn about what a user has searched for. + +However, under this proposal, in the context of using the Federation API to forward on queries from the Client-Server +API, a client's homeserver would end up sharing the client's search terms with a remote homeserver, which may not be +operated by the same party or even trusted. For example, users' search terms could be logged. + +It is uncertain, to the author of this MSC, what implications this has with regards to legislation, such as GDPR. + +## Conclusion + +By allowing homeservers to pass on search filters, we enable remote homeservers' room directories to be +efficiently searched, because, realistically speaking, only the remote homeserver is in a position to be +able to perform search efficiently, by taking advantage of indexing and other such optimisations. + From 62f7a4f82cb26bfa21e896f2342356bc90e7e36d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 29 Jul 2019 21:06:17 -0600 Subject: [PATCH 428/497] Fix/add changelogs The push spec one was missed in https://github.com/matrix-org/matrix-doc/pull/2151 --- changelogs/client_server/newsfragments/2129.clarification | 2 +- changelogs/push_gateway/newsfragments/2151.clarification | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/push_gateway/newsfragments/2151.clarification diff --git a/changelogs/client_server/newsfragments/2129.clarification b/changelogs/client_server/newsfragments/2129.clarification index 82ed4fce..9d67deac 100644 --- a/changelogs/client_server/newsfragments/2129.clarification +++ b/changelogs/client_server/newsfragments/2129.clarification @@ -1 +1 @@ -Remove "required" designation from the ``url`` field of certain ``m`.room.message` msgtypes. +Remove "required" designation from the ``url`` field of certain ``m.room.message`` msgtypes. diff --git a/changelogs/push_gateway/newsfragments/2151.clarification b/changelogs/push_gateway/newsfragments/2151.clarification new file mode 100644 index 00000000..8908eed2 --- /dev/null +++ b/changelogs/push_gateway/newsfragments/2151.clarification @@ -0,0 +1 @@ +Fix ``event_id`` field in push request body. From 40e6f82cbdf736841ab45d4e7e7fd9da1159c76e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 30 Jul 2019 12:54:50 -0600 Subject: [PATCH 429/497] Push r0.1.1 changelog --- changelogs/push_gateway.rst | 9 +++++++++ changelogs/push_gateway/newsfragments/2151.clarification | 1 - 2 files changed, 9 insertions(+), 1 deletion(-) delete mode 100644 changelogs/push_gateway/newsfragments/2151.clarification diff --git a/changelogs/push_gateway.rst b/changelogs/push_gateway.rst index 33a7683c..2afb2a9e 100644 --- a/changelogs/push_gateway.rst +++ b/changelogs/push_gateway.rst @@ -1,3 +1,12 @@ +r0.1.1 +====== + +Spec Clarifications +------------------- + +- Fix ``event_id`` field in push request body. (`#2151 `_) + + r0.1.0 ====== diff --git a/changelogs/push_gateway/newsfragments/2151.clarification b/changelogs/push_gateway/newsfragments/2151.clarification deleted file mode 100644 index 8908eed2..00000000 --- a/changelogs/push_gateway/newsfragments/2151.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix ``event_id`` field in push request body. From 0b49112399772ffaaff827a2c71828ff12e77551 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 30 Jul 2019 13:02:04 -0600 Subject: [PATCH 430/497] Appservices r0.1.2 changelog --- changelogs/application_service.rst | 9 +++++++++ .../application_service/newsfragments/2160.clarification | 1 - 2 files changed, 9 insertions(+), 1 deletion(-) delete mode 100644 changelogs/application_service/newsfragments/2160.clarification diff --git a/changelogs/application_service.rst b/changelogs/application_service.rst index bbc461b2..51a97637 100644 --- a/changelogs/application_service.rst +++ b/changelogs/application_service.rst @@ -1,3 +1,12 @@ +r0.1.2 +====== + +Spec Clarifications +------------------- + +- Clearer wording for the legacy routes section. (`#2160 `_) + + r0.1.1 ====== diff --git a/changelogs/application_service/newsfragments/2160.clarification b/changelogs/application_service/newsfragments/2160.clarification deleted file mode 100644 index 3e9c1c02..00000000 --- a/changelogs/application_service/newsfragments/2160.clarification +++ /dev/null @@ -1 +0,0 @@ -Clearer wording for the legacy routes section. From 26c2ce8a9242bd498646db16c1cc18bec6dc91f4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 30 Jul 2019 13:05:32 -0600 Subject: [PATCH 431/497] Server-server r0.1.3 changelog --- changelogs/server_server.rst | 10 ++++++++++ .../server_server/newsfragments/2157.clarification | 1 - .../server_server/newsfragments/2159.clarification | 1 - 3 files changed, 10 insertions(+), 2 deletions(-) delete mode 100644 changelogs/server_server/newsfragments/2157.clarification delete mode 100644 changelogs/server_server/newsfragments/2159.clarification diff --git a/changelogs/server_server.rst b/changelogs/server_server.rst index 11f99a5f..22da543c 100644 --- a/changelogs/server_server.rst +++ b/changelogs/server_server.rst @@ -1,3 +1,13 @@ +r0.1.3 +====== + +Spec Clarifications +------------------- + +- Clarify the encryption algorithms supported by the device of the user keys query example. (`#2157 `_) +- Clarify the purpose of reference hashes. (`#2159 `_) + + r0.1.2 ====== diff --git a/changelogs/server_server/newsfragments/2157.clarification b/changelogs/server_server/newsfragments/2157.clarification deleted file mode 100644 index 0acf7495..00000000 --- a/changelogs/server_server/newsfragments/2157.clarification +++ /dev/null @@ -1 +0,0 @@ - Clarify the encryption algorithms supported by the device of the user keys query example. diff --git a/changelogs/server_server/newsfragments/2159.clarification b/changelogs/server_server/newsfragments/2159.clarification deleted file mode 100644 index d7b79ccf..00000000 --- a/changelogs/server_server/newsfragments/2159.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the purpose of reference hashes. From 57de107ea914924fb02fc98b607b214b7a1bc3b6 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 31 Jul 2019 11:07:22 +0100 Subject: [PATCH 432/497] Move medium back behind the address --- proposals/2134-identity-hash-lookup.md | 56 +++++++++++++------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 5f500b6c..06a8486a 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -78,14 +78,14 @@ hashed). Note that "pepper" in this proposal simply refers to a public, opaque string that is used to produce different hash results between identity servers. Its value is not secret. -First the client must prepend the medium (plus a space) to the address: +First the client must append the medium (plus a space) to the address: ``` -"alice@example.com" -> "email alice@example.com" -"bob@example.com" -> "email bob@example.com" -"carl@example.com" -> "email carl@example.com" -"+1 234 567 8910" -> "msisdn 12345678910" -"denny@example.com" -> "email denny@example.com" +"alice@example.com" -> "alice@example.com email" +"bob@example.com" -> "bob@example.com email" +"carl@example.com" -> "carl@example.com email" +"+1 234 567 8910" -> "12345678910 msisdn" +"denny@example.com" -> "denny@example.com email" ``` Hashes must be peppered in order to reduce both the information an identity @@ -114,11 +114,11 @@ If hashing, the client appends the pepper to the end of the 3PID string, after a space. ``` -"alice@example.com email" -> "email alice@example.com matrixrocks" -"bob@example.com email" -> "email bob@example.com matrixrocks" -"carl@example.com email" -> "email carl@example.com matrixrocks" -"12345678910 msdisn" -> "msisdn 12345678910 matrixrocks" -"denny@example.com email" -> "email denny@example.com matrixrocks" +"alice@example.com email" -> "alice@example.com email matrixrocks" +"bob@example.com email" -> "bob@example.com email matrixrocks" +"carl@example.com email" -> "carl@example.com email matrixrocks" +"12345678910 msdisn" -> "12345678910 msisdn matrixrocks" +"denny@example.com email" -> "denny@example.com email matrixrocks" ``` Clients can cache the result of this endpoint, but should re-request it @@ -182,11 +182,11 @@ performed, the client sends each hash in an array. ``` NOTE: Hashes are not real values -"email alice@example.com matrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" -"email bob@example.com matrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" -"email carl@example.com matrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" -"msisdn 12345678910 matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" -"email denny@example.com matrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" +"alice@example.com email matrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" +"bob@example.com email matrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" +"carl@example.com email matrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" +"12345678910 msisdn matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" +"denny@example.com email matrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" POST /_matrix/identity/v2/lookup @@ -236,11 +236,11 @@ lookup pepper, as no hashing will occur. Appending a space and the 3PID medium to each address is still necessary: ``` -"alice@example.com" -> "email alice@example.com" -"bob@example.com" -> "email bob@example.com" -"carl@example.com" -> "email carl@example.com" -"+1 234 567 8910" -> "msisdn 12345678910" -"denny@example.com" -> "email denny@example.com" +"alice@example.com" -> "alice@example.com email" +"bob@example.com" -> "bob@example.com email" +"carl@example.com" -> "carl@example.com email" +"+1 234 567 8910" -> "12345678910 msisdn" +"denny@example.com" -> "denny@example.com email" ``` The client then sends these off to the identity server in a `POST` request to @@ -251,11 +251,11 @@ POST /_matrix/identity/v2/lookup { "addresses": [ - "email alice@example.com", - "email bob@example.com", - "email carl@example.com", - "msisdn 12345678910", - "email denny@example.com" + "alice@example.com email", + "bob@example.com email", + "carl@example.com email", + "12345678910 msisdn", + "denny@example.com email" ], "algorithm": "none", "pepper": "matrixrocks" @@ -274,8 +274,8 @@ it has that correspond to these 3PID addresses, and returns them: ``` { "mappings": { - "email alice@example.com": "@alice:example.com", - "msisdn 12345678910": "@fred:example.com" + "alice@example.com email": "@alice:example.com", + "12345678910 msisdn": "@fred:example.com" } } ``` From 9913f5bc298328f0daff702bdbd9ec892fe8c582 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 31 Jul 2019 11:16:58 +0100 Subject: [PATCH 433/497] Slightly clarify pepper value --- proposals/2134-identity-hash-lookup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 06a8486a..28c78918 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -107,8 +107,8 @@ GET /_matrix/identity/v2/hash_details The name `lookup_pepper` was chosen in order to account for pepper values being returned for other endpoints in the future. The contents of `lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+`, whether -hashing is being performed or not. When no hashing is occuring, a pepper -value of at least length 1 is still required. +hashing is being performed or not. When no hashing is occuring, a valid +pepper value of at least length 1 is still required. If hashing, the client appends the pepper to the end of the 3PID string, after a space. From 33d22c3320892c57e1e83724a67a4d6b716edf8f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 31 Jul 2019 11:47:03 +0100 Subject: [PATCH 434/497] hashes are not stream ciphers --- proposals/2134-identity-hash-lookup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 28c78918..e156d158 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -309,8 +309,8 @@ types that have been leaked in database dumps are more susceptible to hash reversal. Mediums and peppers are appended to the address as to prevent a common prefix -for each plain-text string, which prevents attackers from pre-computing bits -of a stream cipher. +for each plain-text string, which prevents attackers from pre-computing the +internal state of the hash function ## Other considered solutions From 0c7c48bd12222fef69e30986899be2ea3f515c8e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 31 Jul 2019 13:13:38 +0100 Subject: [PATCH 435/497] MSC2175: Remove the `creator` field from `m.room.create` events (#2175) Fixes #1193 --- proposals/2175-remove-creator-field.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 proposals/2175-remove-creator-field.md diff --git a/proposals/2175-remove-creator-field.md b/proposals/2175-remove-creator-field.md new file mode 100644 index 00000000..6a9d8f3c --- /dev/null +++ b/proposals/2175-remove-creator-field.md @@ -0,0 +1,17 @@ +# MSC2175: Remove the `creator` field from `m.room.create` events + +[`m.room.create`](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-create) +events have a mandatory `creator` property giving the ID of the user who +created the room. This field is redundant as it is always identical to the +`sender` of the create event. + +This MSC proposes that, in a future room version, this field should be removed +and that the `sender` field be used instead. + +Note that `creator` is mentioned in the [auth +rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules). It can +safely be removed. + +`creator` is also mentioned as a key to be preserved during [Event +redaction](https://matrix.org/docs/spec/client_server/r0.5.0#redactions). It +should be removed from that list. From f989263872e7ccd1cc3463bf7683727c84474b8b Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 31 Jul 2019 13:14:02 +0100 Subject: [PATCH 436/497] MSC2181: Add an Error Code for Signaling a Deactivated User (#2181) --- proposals/2181-user-deactivated-errcode.md | 50 ++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 proposals/2181-user-deactivated-errcode.md diff --git a/proposals/2181-user-deactivated-errcode.md b/proposals/2181-user-deactivated-errcode.md new file mode 100644 index 00000000..8d2e1893 --- /dev/null +++ b/proposals/2181-user-deactivated-errcode.md @@ -0,0 +1,50 @@ +# Add an Error Code for Signaling a Deactivated User + +Currently, when a user attempts to log in, they will receive an `M_FORBIDDEN` +error code if their password is incorrect. However, if the user's account is +deactivated, they will also receive an `M_FORBIDDEN`, leaving clients in a +state where they are unable to inform the user that the reason they cannot +log in is that their account has been deactivated. This leads to confusion +and password resetting which ultimately results in frustration. + +## Proposal + +This proposal asks to create a new error code, `M_USER_DEACTIVATED`, that may +be returned whenever an action is attempted that requires an activited user, +but the authenticating user is deactivated. The HTTP code to return alongside +is `403`. + +An example of this could be returning `M_USER_DEACTIVATED` on `/login`, when +an identifier of a deactivated user is sent to the homeserver. Whether the +password has to be correct depends on whether the Homeserver implementation +removes login information on deactivation. This is an implementation detail. + +It should be noted that this proposal is not requiring implementations to +return `M_USER_DEACTIVATED` on any endpoints when a request from a +deactivated user appears. Instead it is simply defining the new error code, +recommends that it should be used in situations as described above, and that +the client should understand the meaning of it when it is received. + +## Tradeoffs + +The alternative is to continue returning an `M_FORBIDDEN`, but send back a +different error message. This is undesirable as clients are supposed to treat +the message as an opaque string, and should not be performing any +pattern-matching on it. + +## Potential issues + +None + +## Security considerations + +While the existence of a user was already public knowledge (one can check if +the User ID is available through +[/_matrix/client/r0/register/available](https://matrix.org/docs/spec/client_server/r0.5.0#get-matrix-client-r0-register-available), +this proposal would allow any user to be able to detect if a registered +account has been deactivated, depending on the homeserver's implementation. + +## Conclusion + +Adding `M_USER_DEACTIVATED` would better inform clients about the state of a +user's account, and lead to less confusion when they cannot log in. From af60889eeefaf4b249761009a5bf97a81d9677cf Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 31 Jul 2019 15:14:38 +0100 Subject: [PATCH 437/497] Clarify that /rooms/{roomId}/event/{eventId}'s 404 should be M_NOT_FOUND (#2204) No error code is specified for this endpoint's 404. State that it should be an `M_NOT_FOUND`. --- api/client-server/rooms.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index 8af433b2..566e695a 100644 --- a/api/client-server/rooms.yaml +++ b/api/client-server/rooms.yaml @@ -62,6 +62,13 @@ paths: - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml" 404: description: The event was not found or you do not have permission to read this event. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } + schema: + "$ref": "definitions/errors/error.yaml" tags: - Room participation "/rooms/{roomId}/state/{eventType}/{stateKey}": From 28596a6c7463aee92d480126a5e84aa99a4c51ac Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 31 Jul 2019 15:21:40 +0100 Subject: [PATCH 438/497] Add missing changelog for #2204. --- changelogs/client_server/newsfragments/2204.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2204.clarification diff --git a/changelogs/client_server/newsfragments/2204.clarification b/changelogs/client_server/newsfragments/2204.clarification new file mode 100644 index 00000000..7a66b08b --- /dev/null +++ b/changelogs/client_server/newsfragments/2204.clarification @@ -0,0 +1 @@ +Clarify that ``/rooms/:roomId/event/:eventId`` returns a Matrix error. From 36e43ee32620e6936cfe7d758f6f94390e2929b6 Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Thu, 1 Aug 2019 09:28:30 +0100 Subject: [PATCH 439/497] Rewrap lines in MSC2917 to 80 chars wide Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 133 ++++++++++-------- 1 file changed, 78 insertions(+), 55 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 60d35333..04413c86 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -1,90 +1,109 @@ # MSC2197 – Search Filtering in Public Room Directory over Federation -This MSC proposes introducing the `POST` method to the `/publicRooms` Federation API endpoint, -including a `filter` argument which allows server-side filtering of rooms. +This MSC proposes introducing the `POST` method to the `/publicRooms` Federation +API endpoint, including a `filter` argument which allows server-side filtering +of rooms. -We are motivated by the opportunity to make searching the public Room Directory more efficient over -Federation. +We are motivated by the opportunity to make searching the public Room Directory +more efficient over Federation. ## Motivation -Although the Client-Server API includes the filtering capability in `/publicRooms`, the Federation API -currently does not. +Although the Client-Server API includes the filtering capability in +`/publicRooms`, the Federation API currently does not. -This leads to a situation that is wasteful of effort and network traffic for both homeservers; searching -a remote server involves first downloading its entire room list and then filtering afterwards. +This leads to a situation that is wasteful of effort and network traffic for +both homeservers; searching a remote server involves first downloading its +entire room list and then filtering afterwards. ## Proposal -Having a filtered `/publicRooms` API endpoint means that irrelevant or uninteresting rooms can be -excluded from a room directory query response. In turn, this means that these room directory query -responses can be generated more quickly and then, due to their smaller size, transmitted over the network more quickly, owing to their -smaller size. +Having a filtered `/publicRooms` API endpoint means that irrelevant or +uninteresting rooms can be excluded from a room directory query response. +In turn, this means that these room directory query responses can be generated +more quickly and then, due to their smaller size, transmitted over the network +more quickly, owing to their smaller size. -These benefits have been exploited in the Client-Server API, which implements search filtering -using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. +These benefits have been exploited in the Client-Server API, which implements +search filtering using the `filter` JSON body parameter in the `POST` method on +the `/publicRooms` endpoint. -It should be noted that the Client-Server and Federation APIs both currently possess `/publicRooms` -endpoints which, whilst similar, are not equivalent. +It should be noted that the Client-Server and Federation APIs both currently +possess `/publicRooms` endpoints which, whilst similar, are not equivalent. -Ignoring the `server` parameter in the Client-Server API, the following specific differences are -noticed: +Ignoring the `server` parameter in the Client-Server API, the following specific +differences are noticed: -* the Federation API endpoint only accepts the `GET` method whereas the Client-Server API accepts - the `POST` method as well. -* the Federation API accepts `third_party_instance_id` and `include_all_networks` parameters through - the `GET` method, whereas the Client-Server API only features these in the `POST` method. +* the Federation API endpoint only accepts the `GET` method whereas the + Client-Server API accepts the `POST` method as well. +* the Federation API accepts `third_party_instance_id` and + `include_all_networks` parameters through the `GET` method, whereas the + Client-Server API only features these in the `POST` method. -This MSC proposes to introduce support for the `POST` method in the Federation API's `/publicRooms` -endpoint, with all but one of the parameters from that of the Client-Server API. The copied parameters -shall have the same semantics as they do in the Client-Server API. +This MSC proposes to introduce support for the `POST` method in the Federation +API's `/publicRooms` endpoint, with all but one of the parameters from that of +the Client-Server API. The copied parameters shall have the same semantics as +they do in the Client-Server API. -In the interest of clarity, the proposed parameter set is listed below, along with a repetition of the -definitions of used substructures. The response format has been omitted as it is the same as that of -the current Client-Server and Federation APIs, which do not differ in this respect. +In the interest of clarity, the proposed parameter set is listed below, along +with a repetition of the definitions of used substructures. The response format +has been omitted as it is the same as that of the current Client-Server and +Federation APIs, which do not differ in this respect. ### `POST /_matrix/federation/v1/publicRooms` #### Query Parameters -There are no query parameters. Notably, we intentionally do not inherit the `server` query parameter -from the Client-Server API. +There are no query parameters. Notably, we intentionally do not inherit the +`server` query parameter from the Client-Server API. #### JSON Body Parameters * `limit` (`integer`): Limit the number of search results returned. -* `since` (`string`): A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. +* `since` (`string`): A pagination token from a previous request, allowing + clients to get the next (or previous) batch of rooms. The direction of + pagination is specified solely by which token is supplied, rather than via an + explicit flag. * `filter` (`Filter`): Filter to apply to the results. -* `include_all_networks` (`boolean`): Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to false. -* `third_party_instance_id` (`boolean`): The specific third party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. +* `include_all_networks` (`boolean`): Whether or not to include all known + networks/protocols from application services on the homeserver. + Defaults to false. +* `third_party_instance_id` (`boolean`): The specific third party + network/protocol to request from the homeserver. + Can only be used if `include_all_networks` is false. ### `Filter` Parameters -* `generic_search_term` (`string`): A string to search for in the room metadata, e.g. name, topic, canonical alias etc. (Optional). +* `generic_search_term` (`string`): A string to search for in the room metadata, +e.g. name, topic, canonical alias etc. (Optional). ## Tradeoffs -An alternative approach might be for implementations to carry on as they are but also -cache (and potentially index) remote homeservers' room directories. This would not require -a spec change. +An alternative approach might be for implementations to carry on as they are but +also cache (and potentially index) remote homeservers' room directories. +This would not require a spec change. -However, this would be unsatisfactory because it would lead to outdated room directory results and/or -caches that provide no benefit (as room directory searches are generally infrequent enough that a cache -would be outdated before being reused, on small – if not most – homeservers). +However, this would be unsatisfactory because it would lead to outdated room +directory results and/or caches that provide no benefit (as room directory +searches are generally infrequent enough that a cache would be outdated before +being reused, on small – if not most – homeservers). ## Potential issues ### Backwards Compatibility -After this proposal is implemented, outdated homeservers will still exist which do not support the room -filtering functionality specified in this MSC. In this case, homeservers will have to fall-back to downloading -the entire room directory and performing the filtering themselves, as currently happens. This is not considered -a problem since it will not lead to a situation that is any worse than the current one, and it is expected that -large homeservers – which cause the most work with the current search implementations – would be quick to upgrade -to support this feature once it is available. +After this proposal is implemented, outdated homeservers will still exist which +do not support the room filtering functionality specified in this MSC. In this +case, homeservers will have to fall-back to downloading the entire room +directory and performing the filtering themselves, as currently happens. +This is not considered a problem since it will not lead to a situation that is +any worse than the current one, and it is expected that large homeservers +– which cause the most work with the current search implementations – +would be quick to upgrade to support this feature once it is available. -In addition, as the `POST` method was not previously accepted on the `/publicRooms` endpoint over federation, -then it is not a difficult task to use a `405 Method Not Allowed` HTTP response as a signal that fallback is required. +In addition, as the `POST` method was not previously accepted on the +`/publicRooms` endpoint over federation, then it is not a difficult task to use +a `405 Method Not Allowed` HTTP response as a signal that fallback is required. ## Security considerations @@ -94,15 +113,19 @@ There are no known security considerations. At current, remote homeservers do not learn about what a user has searched for. -However, under this proposal, in the context of using the Federation API to forward on queries from the Client-Server -API, a client's homeserver would end up sharing the client's search terms with a remote homeserver, which may not be -operated by the same party or even trusted. For example, users' search terms could be logged. +However, under this proposal, in the context of using the Federation API to +forward on queries from the Client-Server API, a client's homeserver would end +up sharing the client's search terms with a remote homeserver, which may not be +operated by the same party or even trusted. For example, users' search terms +could be logged. -It is uncertain, to the author of this MSC, what implications this has with regards to legislation, such as GDPR. +It is uncertain, to the author of this MSC, what implications this has with +regards to legislation, such as GDPR. ## Conclusion -By allowing homeservers to pass on search filters, we enable remote homeservers' room directories to be -efficiently searched, because, realistically speaking, only the remote homeserver is in a position to be -able to perform search efficiently, by taking advantage of indexing and other such optimisations. +By allowing homeservers to pass on search filters, we enable remote homeservers' +room directories to be efficiently searched, because, realistically speaking, +only the remote homeserver is in a position to be able to perform search +efficiently, by taking advantage of indexing and other such optimisations. From 3789d828fd0d767d93a6c801fe8b1c95c32c6de2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 1 Aug 2019 14:51:26 +0100 Subject: [PATCH 440/497] Incorporate solution analysis from the context of attacks --- proposals/2134-identity-hash-lookup.md | 125 +++++++++++++++++++++---- 1 file changed, 105 insertions(+), 20 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 5f500b6c..0881d1cb 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -316,43 +316,128 @@ of a stream cipher. Bloom filters are an alternative method of providing private contact discovery. However, they do not scale well due to requiring clients to download a large -filter that needs updating every time a new bind is made. Further considered -solutions are explored in https://signal.org/blog/contact-discovery/. Signal's -eventual solution of using Software Guard Extensions (detailed in +filter that needs updating every time a new bind is made. + +Further considered solutions are explored in +https://signal.org/blog/contact-discovery/. Signal's eventual solution of +using Software Guard Extensions (detailed in https://signal.org/blog/private-contact-discovery/) is considered impractical for a federated network, as it requires specialized hardware. k-anonymity was considered as an alternative approach, in which the identity server would never receive a full hash of a 3PID that it did not already know -about. While this has been considered plausible, it comes with heightened -resource requirements (much more hashing by the identity server). The -conclusion was that it may not provide more privacy if an identity server -decided to be evil, however it would significantly raise the resource -requirements to run an evil identity server. Discussion and a walk-through of -what a client/identity-server interaction would look like are documented [in -this Github +about. Discussion and a walk-through of what a client/identity-server +interaction would look like are documented [in this Github comment](https://github.com/matrix-org/matrix-doc/pull/2134#discussion_r298691748). +While this solution seems like a win for privacy, its actual benefits are a +lot more naunced. Let's explore them by performing threat-model analysis: + +We consider three attackers: + + 1. A malicious third party trying to discover the identity server mappings + in the homeserver. + + The malicious third party scenario can only be protected against by rate + limiting lookups, given otherwise it looks identical to legitimate traffic. + + 1. An attacker who has stolen an IS db + + In theory the 3PIDs could be stored hashed with a static salt to protect + a stolen DB. This has been descoped from this MSC, and is largely an + orthogonal problem. + + 1. A compromised or malicious identity server, who may be trying to + determine the contents of a user's addressbook (including non-Matrix users) + +Our approaches for protecting against a malicious identity server are: + + * We resign ourselves to the IS knowing the 3PIDs at point of bind, as + otherwise it can't validate them. + + * To protect the 3PIDs of non-Matrix users: + + 1. We could hash the uploaded 3PIDs with a static pepper; however, a + malicious IS could pre-generate a rainbow table to reverse these hashes. + + 1. We could hash the uploaded 3PIDs with a slowly rotating pepper; a + malicious IS could generate a rainbow table in retrospect to reverse these + hashes (but wouldn't be able to reuse the table) + + 1. We could send partial hashes of the uploaded 3PIDs (with full salted + hashes to disambiguate the 3PIDs), have the IS respond with anonymised + partial results, to allow the IS to avoid reversing the 3PIDs (a + k-anonymity approach). However, the IS could still claim to have mappings + for all 3PIDs, and so receive all the salted hashes, and be able to + reverse them via rainbow tables for that salt. + +So, in terms of computational complexity for the attacker, respectively: + + 1. The attacker has to generate a rainbow table over all possible IDs once, + which can then be reused for subsequent attacks. + + 1. The attacker has to generate a rainbow table over all possible IDs for a + given lookup timeframe, which cannot be reused for subsequent attacks. + + 1. The attacker has to generate multiple but partial rainbow tables, one + per group of 3PIDs that share similar hash prefixes, which cannot then be + reused for any other attack. + +For making life hardest for an attacker, option 3 (k-anon) wins. However, it +also makes things harder for the client and server: + + * The client has to calculate new salted hashes for all 3PIDs every time it + uploads. + + * The server has to calculate new salted hashes for all partially-matching + 3PIDs hashes as it looks them up. + +It's worth noting that one could always just go and load up a malicious IS DB +with a huge pre-image set of mappings and thus see what uploaded 3PIDs match, +no matter what algorithm is used. + +For k-anon this would put the most computational onus on the server (as it +would effectively be creating a partial rainbow table for every lookup), but +this is probably not infeasible - so we've gone and added a lot of complexity +and computational cost for not much benefit, given the system can still be +trivially attacked. + +Finally, as more and more users come onto Matrix, their contact lists will +get more and more exposed anyway given the IS server has to be able to +identity Matrix-enabled 3PIDs to perform the lookup. + +Thus the conclusion is that while k-anon is harder to attack, it's unclear +that this is actually enough of an obstacle to meaningfully stop a malicious +IS. Therefore we should KISS and go for a simple hash lookup with a rotating +pepper (which is not much harder than a static pepper, especially if our +initial implementation doesn't bother rotating the pepper). Rather than trying +to make the k-anon approach work, we'd be better off spending that time +figuring out how to store 3pids as hashes in the DB (and in 3pid bindings +etc), or how to decentralise ISes in general. + A radical model was also considered where the first portion of the k-anonyminity scheme was done with an identity server, and the second would be done with various homeservers who originally reported the 3PID to the -identity server. While interesting and a more decentralised model, some -attacks are still possible if the identity server is running an evil -homeserver which it can direct the client to send its hashes to. Discussion -on this matter has taken place in the MSC-specific room [starting at this +identity server. While interesting and more decentralised, some attacks are +still possible if the identity server is running an evil homeserver which it +can direct the client to send its hashes to. Discussion on this matter has +taken place in the MSC-specific room [starting at this message](https://matrix.to/#/!LlraCeVuFgMaxvRySN:amorgan.xyz/$4wzTSsspbLVa6Lx5cBq6toh6P3TY3YnoxALZuO8n9gk?via=amorgan.xyz&via=matrix.org&via=matrix.vgorcum.com). -Ideally identity servers would never receive plain-text addresses, just -storing and receiving hash values instead. However, it is necessary for the -identity server to have plain-text addresses during a +Tangentially, identity servers would ideally just never receive plain-text +addresses, just storing and receiving hash values instead. However, it is +necessary for the identity server to have plain-text addresses during a [bind](https://matrix.org/docs/spec/identity_service/r0.2.1#post-matrix-identity-api-v1-3pid-bind) call, in order to send a verification email or sms message. It is not feasible to defer this job to a homeserver, as the identity server cannot trust that the homeserver has actually performed verification. Thus it may not be possible to prevent plain-text 3PIDs of registered Matrix users from -being sent to the identity server at least once. Yet, we can still do our -best by coming up with creative ways to prevent non-matrix user 3PIDs from -leaking to the identity server, when they're sent in a lookup. +being sent to the identity server at least once. Yet, it is possible that with +a few changes to other Identity Service endpoints, as described in [this +review +comment](https://github.com/matrix-org/matrix-doc/pull/2134#discussion_r309617900), +identity servers could refrain from storing any plaintext 3PIDs at rest. This +however, is a topic for a future MSC. ## Conclusion From c401a4d47b7f1edf63ed3aa5c2341f8554b824b1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 1 Aug 2019 14:53:41 +0100 Subject: [PATCH 441/497] punctuation --- proposals/2134-identity-hash-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index f4a5e36c..fd17475b 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -310,7 +310,7 @@ reversal. Mediums and peppers are appended to the address as to prevent a common prefix for each plain-text string, which prevents attackers from pre-computing the -internal state of the hash function +internal state of the hash function. ## Other considered solutions From 387772477497362f6b2714ee8ce1a6c2a6a9132b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 1 Aug 2019 15:01:05 +0100 Subject: [PATCH 442/497] fix speeling --- proposals/2134-identity-hash-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index fd17475b..11ea3258 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -331,7 +331,7 @@ interaction would look like are documented [in this Github comment](https://github.com/matrix-org/matrix-doc/pull/2134#discussion_r298691748). While this solution seems like a win for privacy, its actual benefits are a -lot more naunced. Let's explore them by performing threat-model analysis: +lot more nuanced. Let's explore them by performing a threat-model analysis: We consider three attackers: From 96e06b6f5f94c6d2f13ec1c50bca4e16469ed797 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 1 Aug 2019 15:04:38 +0100 Subject: [PATCH 443/497] Add line, britishise --- proposals/2134-identity-hash-lookup.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 11ea3258..6c3bbe63 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -322,7 +322,7 @@ Further considered solutions are explored in https://signal.org/blog/contact-discovery/. Signal's eventual solution of using Software Guard Extensions (detailed in https://signal.org/blog/private-contact-discovery/) is considered impractical -for a federated network, as it requires specialized hardware. +for a federated network, as it requires specialised hardware. k-anonymity was considered as an alternative approach, in which the identity server would never receive a full hash of a 3PID that it did not already know @@ -410,10 +410,12 @@ Thus the conclusion is that while k-anon is harder to attack, it's unclear that this is actually enough of an obstacle to meaningfully stop a malicious IS. Therefore we should KISS and go for a simple hash lookup with a rotating pepper (which is not much harder than a static pepper, especially if our -initial implementation doesn't bother rotating the pepper). Rather than trying -to make the k-anon approach work, we'd be better off spending that time -figuring out how to store 3pids as hashes in the DB (and in 3pid bindings -etc), or how to decentralise ISes in general. +initial implementation doesn't bother rotating the pepper). Rather than +trying to make the k-anon approach work, we'd be better off spending that +time figuring out how to store 3pids as hashes in the DB (and in 3pid +bindings etc), or how to decentralise ISes in general. It's also worth noting +that a malicious server may fail to rotate the pepper, making the rotation +logic of questionable benefit. A radical model was also considered where the first portion of the k-anonyminity scheme was done with an identity server, and the second would From 3edf5e3c16989a603d9f9e7996acdac5f6596ab3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 2 Aug 2019 11:25:28 +0100 Subject: [PATCH 444/497] Make hashes real values --- proposals/2134-identity-hash-lookup.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/proposals/2134-identity-hash-lookup.md b/proposals/2134-identity-hash-lookup.md index 6c3bbe63..2fdda034 100644 --- a/proposals/2134-identity-hash-lookup.md +++ b/proposals/2134-identity-hash-lookup.md @@ -180,23 +180,21 @@ IDs](https://matrix.org/docs/spec/rooms/v4#event-ids)). Once hashing has been performed, the client sends each hash in an array. ``` -NOTE: Hashes are not real values - -"alice@example.com email matrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs" -"bob@example.com email matrixrocks" -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE" -"carl@example.com email matrixrocks" -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw" -"12345678910 msisdn matrixrocks" -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens" -"denny@example.com email matrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" +"alice@example.com email matrixrocks" -> "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc" +"bob@example.com email matrixrocks" -> "LJwSazmv46n0hlMlsb_iYxI0_HXEqy_yj6Jm636cdT8" +"carl@example.com email matrixrocks" -> "jDh2YLwYJg3vg9pEn3kaaXAP9jx-LlcotoH51Zgb9MA" +"12345678910 msisdn matrixrocks" -> "S11EvvwnUWBDZtI4MTRKgVuiRx76Z9HnkbyRlWkBqJs" +"denny@example.com email matrixrocks" -> "2tZto1arl2fUYtF6tQPJND69il3xke9OBlgFgnUt2ww" POST /_matrix/identity/v2/lookup { "addresses": [ - "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs", - "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE", - "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw", - "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens", - "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY" + "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc", + "LJwSazmv46n0hlMlsb_iYxI0_HXEqy_yj6Jm636cdT8", + "jDh2YLwYJg3vg9pEn3kaaXAP9jx-LlcotoH51Zgb9MA", + "S11EvvwnUWBDZtI4MTRKgVuiRx76Z9HnkbyRlWkBqJs", + "2tZto1arl2fUYtF6tQPJND69il3xke9OBlgFgnUt2ww" ], "algorithm": "sha256", "pepper": "matrixrocks" @@ -210,8 +208,8 @@ IDs of those that match: ``` { "mappings": { - "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs": "@alice:example.com", - "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens": "@fred:example.com" + "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.com", + "S11EvvwnUWBDZtI4MTRKgVuiRx76Z9HnkbyRlWkBqJs": "@fred:example.com" } } ``` From a63fab20ee136e4b58eae94ed567e4faeda605cb Mon Sep 17 00:00:00 2001 From: Dominic Fischer Date: Sat, 3 Aug 2019 17:25:54 +0100 Subject: [PATCH 445/497] Fix some typos Signed-off-by: Dominic Fischer --- api/client-server/definitions/sync_filter.yaml | 4 ++-- changelogs/client_server/newsfragments/2215.clarification | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2215.clarification diff --git a/api/client-server/definitions/sync_filter.yaml b/api/client-server/definitions/sync_filter.yaml index 45a269c7..fc37fb48 100644 --- a/api/client-server/definitions/sync_filter.yaml +++ b/api/client-server/definitions/sync_filter.yaml @@ -16,7 +16,7 @@ title: Filter properties: event_fields: description: List of event fields to include. If this list is absent then all - fields are included. The entries may include '.' charaters to indicate sub-fields. + fields are included. The entries may include '.' characters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested. @@ -25,7 +25,7 @@ properties: type: array event_format: description: The format to use for events. 'client' will return the events in - a format suitable for clients. 'federation' will return the raw event as receieved + a format suitable for clients. 'federation' will return the raw event as received over federation. The default is 'client'. enum: - client diff --git a/changelogs/client_server/newsfragments/2215.clarification b/changelogs/client_server/newsfragments/2215.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/2215.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. From 493bb062afb1eef49c9282cc1162e72a022f2ff1 Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Mon, 5 Aug 2019 09:50:24 +0100 Subject: [PATCH 446/497] MSC2197: update with privacy perspective Includes recommendations for client developers. Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 04413c86..bc1a74a9 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -119,8 +119,23 @@ up sharing the client's search terms with a remote homeserver, which may not be operated by the same party or even trusted. For example, users' search terms could be logged. -It is uncertain, to the author of this MSC, what implications this has with -regards to legislation, such as GDPR. +The privacy implications of this proposal are not overly major, as the data +that's being shared is [\[1\]][1]: + +- only covered by GDPR if: + - the search terms contain personal data, or + - the user's homeserver IP address is uniquely identifying (because it's a + single-person homeserver, perhaps) +- likely to be *expected* to be shared with the remote homeserver + +[1]: https://github.com/matrix-org/matrix-doc/pull/2197#issuecomment-517641751 + +For the sake of clarity, clients SHOULD display a warning that a remote search +will take the user's data outside the jurisdiction of their own homeserver, +before using the `server` parameter of the Client-Server API `/publicRooms`, as +it can be assumed that this will lead to the server invoking the Federation +API's `/publicRooms` – on the specified remote server – with the user's search +terms. ## Conclusion From a171d5f6fdc90057020d416af1b4bf79524e091f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 8 Aug 2019 09:29:52 -0600 Subject: [PATCH 447/497] Check for a state_key on the tombstone push rule This is an oversight from the proposal. --- changelogs/client_server/newsfragments/2223.clarification | 1 + proposals/1930-tombstone-notifications.md | 5 +++++ specification/modules/push.rst | 7 ++++++- 3 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2223.clarification diff --git a/changelogs/client_server/newsfragments/2223.clarification b/changelogs/client_server/newsfragments/2223.clarification new file mode 100644 index 00000000..165b7e13 --- /dev/null +++ b/changelogs/client_server/newsfragments/2223.clarification @@ -0,0 +1 @@ +Add a missing ``state_key`` check on ``.m.rule.tombstone``. diff --git a/proposals/1930-tombstone-notifications.md b/proposals/1930-tombstone-notifications.md index 715921aa..253bf826 100644 --- a/proposals/1930-tombstone-notifications.md +++ b/proposals/1930-tombstone-notifications.md @@ -19,6 +19,11 @@ A new default override rule is to be added which is similar to `@room` notificat "kind": "event_match", "key": "type", "pattern": "m.room.tombstone" + }, + { + "kind": "event_match", + "key": "state_key", + "pattern": "" } ], "actions": [ diff --git a/specification/modules/push.rst b/specification/modules/push.rst index b16ed8a6..c9489987 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -382,7 +382,7 @@ Definition: ``.m.rule.tombstone`` ````````````````````` -Matches any event whose type is ``m.room.tombstone``. This is intended +Matches any state event whose type is ``m.room.tombstone``. This is intended to notify users of a room when it is upgraded, similar to what an ``@room`` notification would accomplish. @@ -399,6 +399,11 @@ Definition: "kind": "event_match", "key": "type", "pattern": "m.room.tombstone" + }, + { + "kind": "event_match", + "key": "state_key", + "pattern": "" } ], "actions": [ From 60cbc4567b62a50f2c10b84525be0efb0452aa3e Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Fri, 9 Aug 2019 11:21:39 +0100 Subject: [PATCH 448/497] Addresses some of Andrew's comments Signed-off-by: Olivier Wilkinson (reivilibre) --- ...search_filter_in_federation_publicrooms.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index bc1a74a9..3ac9f3c4 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -22,17 +22,15 @@ Having a filtered `/publicRooms` API endpoint means that irrelevant or uninteresting rooms can be excluded from a room directory query response. In turn, this means that these room directory query responses can be generated more quickly and then, due to their smaller size, transmitted over the network -more quickly, owing to their smaller size. +more quickly. These benefits have been exploited in the Client-Server API, which implements search filtering using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. -It should be noted that the Client-Server and Federation APIs both currently -possess `/publicRooms` endpoints which, whilst similar, are not equivalent. - Ignoring the `server` parameter in the Client-Server API, the following specific -differences are noticed: +differences are noticed between the Client-Server and Federation API's +`/publicRooms` endpoints: * the Federation API endpoint only accepts the `GET` method whereas the Client-Server API accepts the `POST` method as well. @@ -42,7 +40,13 @@ differences are noticed: This MSC proposes to introduce support for the `POST` method in the Federation API's `/publicRooms` endpoint, with all but one of the parameters from that of -the Client-Server API. The copied parameters shall have the same semantics as +the Client-Server API. + +The parameter that is intentionally omitted is the `server` query parameter, as +it does not make sense to include it – the requesting homeserver could make a +direct request instead of requesting that a request be relayed. + +The parameters which are copied, however, shall have the same semantics as they do in the Client-Server API. In the interest of clarity, the proposed parameter set is listed below, along @@ -103,7 +107,8 @@ would be quick to upgrade to support this feature once it is available. In addition, as the `POST` method was not previously accepted on the `/publicRooms` endpoint over federation, then it is not a difficult task to use -a `405 Method Not Allowed` HTTP response as a signal that fallback is required. +an `M_UNRECOGNIZED` standard error response `errcode` as a signal that fallback +is required. ## Security considerations From 783fd78a6f740b5dffc76184f1103f2d36a523ae Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 12 Aug 2019 17:13:37 +0100 Subject: [PATCH 449/497] wip --- proposals/xxxx-existing-3pid-allowed.md | 108 ++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 proposals/xxxx-existing-3pid-allowed.md diff --git a/proposals/xxxx-existing-3pid-allowed.md b/proposals/xxxx-existing-3pid-allowed.md new file mode 100644 index 00000000..f3daa533 --- /dev/null +++ b/proposals/xxxx-existing-3pid-allowed.md @@ -0,0 +1,108 @@ +# Allowing 3PID Owners to Rebind + +This is a proposal to allow 3PID owners to rebind their 3PIDs using the `POST +/_matrix/client/r0/account/3pid/email/requestToken` endpoint. The spec +currently states that if a user tries to call this endpoint with an email +address they already own, then the request should be rejected. + +This MSC calls for those requests to be accepted iff the requesting user +currently has the 3PID bound to their Matrix ID, marking them as the user in +control of this 3PID. + +This would allow users to bind their 3PIDs to different servers, even if the +homeserver has already been made aware of it. + +--- TODO, below --- + +## Proposal + +*Here is where you'll reinforce your position from the introduction in more detail, as well as cover +the technical points of your proposal. Including rationale for your proposed solution and detailing +why parts are important helps reviewers understand the problem at hand. Not including enough detail +can result in people guessing, leading to confusing arguments in the comments section. The example +here covers why templates are important again, giving a stronger argument as to why we should have +a template. Afterwards, it goes on to cover the specifics of what the template could look like.* + +Having a default template that everyone can use is important. Without a template, proposals would be +all over the place and the minimum amount of detail may be left out. Introducing a template to the +proposal process helps ensure that some amount of consistency is present across multiple proposals, +even if each author decides to abandon the template. + +The default template should be a markdown document because the MSC process requires authors to write +a proposal in markdown. Using other formats wouldn't make much sense because that would prevent authors +from copy/pasting the template. + +The template should have the following sections: + +* **Introduction** - This should cover the primary problem and broad description of the solution. +* **Proposal** - The gory details of the proposal. +* **Tradeoffs** - Any items of the proposal that are less desirable should be listed here. Alternative + solutions to the same problem could also be listed here. +* **Potential issues** - This is where problems with the proposal would be listed, such as changes + that are not backwards compatible. +* **Security considerations** - Discussion of what steps were taken to avoid security issues in the + future and any potential risks in the proposal. +* **Conclusion** - A repeat of the problem and solution. + +Furthermore, the template should not be required to be followed. However it is strongly recommended to +maintain some sense of consistency between proposals. + + +## Tradeoffs + +*This is where alternative solutions could be listed. There's almost always another way to do things +and this section gives you the opportunity to highlight why those ways are not as desirable. The +argument made in this example is that all of the text provided by the template could be integrated +into the proposals introduction, although with some risk of losing clarity.* + +Instead of adding a template to the repository, the assistance it provides could be integrated into +the proposal process itself. There is an argument to be had that the proposal process should be as +descriptive as possible, although having even more detail in the proposals introduction could lead to +some confusion or lack of understanding. Not to mention if the document is too large then potential +authors could be scared off as the process suddenly looks a lot more complicated than it is. For those +reasons, this proposal does not consider integrating the template in the proposals introduction a good +idea. + + +## Potential issues + +*Not all proposals are perfect. Sometimes there's a known disadvantage to implementing the proposal, +and they should be documented here. There should be some explanation for why the disadvantage is +acceptable, however - just like in this example.* + +Someone is going to have to spend the time to figure out what the template should actually have in it. +It could be a document with just a few headers or a supplementary document to the process explanation, +however more detail should be included. A template that actually proposes something should be considered +because it not only gives an opportunity to show what a basic proposal looks like, it also means that +explanations for each section can be described. Spending the time to work out the content of the template +is beneficial and not considered a significant problem because it will lead to a document that everyone +can follow. + + +## Security considerations + +*Some proposals may have some security aspect to them that was addressed in the proposed solution. This +section is a great place to outline some of the security-sensitive components of your proposal, such as +why a particular approach was (or wasn't) taken. The example here is a bit of a stretch and unlikely to +actually be worthwhile of including in a proposal, but it is generally a good idea to list these kinds +of concerns where possible.* + +By having a template available, people would know what the desired detail for a proposal is. This is not +considered a risk because it is important that people understand the proposal process from start to end. + + +## Conclusion + +*Repeating the problem and solution in different words helps reviewers understand the problem a bit more. +This section should wrap up any loose ends left in the document, as well as cover a brief overview of the +content in each section. Note that the example here doesn't touch on the specific implementation details +described in the "Proposal" section - just the high-level points made there.* + +Not having a template for people to follow when making their proposals could lead to large differences +between each MSC. This would make it difficult for reviewers, and there's a potential that some information +could be left out by accident. A template written in the same format the proposal process requires would +give authors the ability to understand how to better explain their own proposal. + +A descriptive template would help potential authors comprehend what the proposal process requires by +demonstrating what is expected of a proposal. Although this is more effort up front, it would lead to more +time saved in the future due to questions about the process. From 6330fff5a4bdb1691898ccd7bfb435cbfda98b11 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 12 Aug 2019 18:13:58 +0100 Subject: [PATCH 450/497] Draft for IS URL in account data --- .../xxxx-identity-server-account-data.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 proposals/xxxx-identity-server-account-data.md diff --git a/proposals/xxxx-identity-server-account-data.md b/proposals/xxxx-identity-server-account-data.md new file mode 100644 index 00000000..da539f2a --- /dev/null +++ b/proposals/xxxx-identity-server-account-data.md @@ -0,0 +1,74 @@ +# Store Identity Server in Account Data + +The URL of the Identity Sever to use is currently specified at registration and +login time and then used for the lifetime of a login session. If users wish to +specify a custom one, they must do so each time they log in on every client. +Once they have chosen an Identity Server to advertise their 3PIDs on, it would +be normal that they would wish to continue using this Identity Server for all +Identity requests in their account accross all clients. This proposal aims to +make this easier. + +## Proposal + +The base URL of the Identity Server is to be stored in user account data. It +shall be stored in the same format as in a .well-known file under the key, +`m.identity_server` and shall comprise a single key, `base_url` which is the +base URL of the ID Server to use (that is, the part before `/_matrix`). + +Upon registration or login, a client MUST refrain from performing any requests +to the Identity Server until the account data has been fetched from the server. +Once it has the account data, it MUST check for the presence of the +`m.identity_server` key. If present, the `base_url` in this key MUST be used +as the Identity Server base URL for the duration of the login session. If this +key is not present, the client SHOULD populate it with the ID Server URL +that was or would have been used in the login/registration process. This may +be either from user input, a .well-known lookup, or a default in the client. + +Client MUST listen for changes in the `m.identity_server` account data value +and update the URL that they use for ID Server requests accordingly UNLESS +the login session and choice of ID Server base URL predates this change, in +which case they SHOULD continue to use the value they are currently using. + +Clients MAY offer a way for users to change the ID server being used. If they +do, the client MUST update the value of `m.identity_server` accordingly. + +The `m.identity_server` may be present with a value of `null`. In this case, +clients MUST treat this as no ID Server URL being set and not perform ID +Server requests, disabling any functionality that requires such requests. + +Conversely, if a user wishes to disable ID Server functionality, the client +shall action this by setting the `base_url` of the `m.identity_server` +account data entry to `null`. + +### Transition Period + +Clients currently logged in with a value configured for the ID Server base +URL SHOULD use the value from `m.identity_server` if it exists or is created, +but otherwise continue to use the URL they had previously. They MUST NOT +populate the `m.identity_server` with their current ID Server base URL. + +## Tradeoffs + +There are a number of ways to transition to this new scheme. Clients could +populate the account data with their current ID Server URL as soon as +possible, and immediately use any new value seen on account data. This +would a much faster migration but any users with clients using different +ID Servers would suddenly find all their clients using the ID Server of +whichever client they updated first. + +## Potential issues + +Users will no longer be able to have different clients configured with +different ID Servers. + +## Security considerations + +An attacker would be able to force all a user clients to use a given ID Server +if they gained control of any of a user's logins. + +## Conclusion + +This makes the ID server an account setting which means it persists between +logins. The intention would be to phase out clients ever asking for an ID +Server URL at registration or login: this will be much easier for users to +understand whilst still retaining the flexibilty for those who want it. From ed4d805d2f087ba242969d3b561e7c5e2cb234e5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 13 Aug 2019 11:11:22 +0100 Subject: [PATCH 451/497] flesh out --- proposals/xxxx-existing-3pid-allowed.md | 140 +++++++++--------------- 1 file changed, 54 insertions(+), 86 deletions(-) diff --git a/proposals/xxxx-existing-3pid-allowed.md b/proposals/xxxx-existing-3pid-allowed.md index f3daa533..c10eec27 100644 --- a/proposals/xxxx-existing-3pid-allowed.md +++ b/proposals/xxxx-existing-3pid-allowed.md @@ -1,108 +1,76 @@ # Allowing 3PID Owners to Rebind -This is a proposal to allow 3PID owners to rebind their 3PIDs using the `POST -/_matrix/client/r0/account/3pid/email/requestToken` endpoint. The spec -currently states that if a user tries to call this endpoint with an email -address they already own, then the request should be rejected. +3PID + noun + A third-party identifier such as an email address or phone number, that + can be tied to your Matrix ID in order for your contacts outside of + Matrix to find you, typically with the help of an [identity + server](https://matrix.org/docs/spec/identity_service/r0.2.1.html). -This MSC calls for those requests to be accepted iff the requesting user -currently has the 3PID bound to their Matrix ID, marking them as the user in -control of this 3PID. +As part of the on-going privacy work, Matrix client applications are +attempting to make the concept of an identity server more clear to the user, +as well as allowing a user to interact with multiple identity servers while +they're logged in. -This would allow users to bind their 3PIDs to different servers, even if the -homeserver has already been made aware of it. +As part of facilitating this work, Matrix clients should be able to allow +users, while logged in, the ability to pick an identity server, see what +3PIDs they currently have bound to their Matrix ID, and bind/unbind as they +desire. ---- TODO, below --- +When implementating this functionality, a technicality in the spec was found +to prevent the ability to bind the same 3PID to multiple identity servers. +The line "The homeserver must check that the given email address is **not** +already associated with an account on this homeserver." appears under the +[POST +/_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) +line. The same goes for the [equivalent msisdn +endpoint](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken). + +If a user binds their email address, through the homeserver to identity +server A, then switches to identity server B to try and do the same, the +homeserver will reject the second request as this email address has already +been bound. This is due to the homeserver attaching the email address user's +accounts whenever a bind is performed through them. ## Proposal -*Here is where you'll reinforce your position from the introduction in more detail, as well as cover -the technical points of your proposal. Including rationale for your proposed solution and detailing -why parts are important helps reviewers understand the problem at hand. Not including enough detail -can result in people guessing, leading to confusing arguments in the comments section. The example -here covers why templates are important again, giving a stronger argument as to why we should have -a template. Afterwards, it goes on to cover the specifics of what the template could look like.* +This proposal calls for allowing 3PID owners to rebind their 3PIDs using the +[POST +/_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) and [POST +/_matrix/client/r0/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +endpoints by extending the definition of what homeservers should check before rejecting a bind. -Having a default template that everyone can use is important. Without a template, proposals would be -all over the place and the minimum amount of detail may be left out. Introducing a template to the -proposal process helps ensure that some amount of consistency is present across multiple proposals, -even if each author decides to abandon the template. - -The default template should be a markdown document because the MSC process requires authors to write -a proposal in markdown. Using other formats wouldn't make much sense because that would prevent authors -from copy/pasting the template. - -The template should have the following sections: - -* **Introduction** - This should cover the primary problem and broad description of the solution. -* **Proposal** - The gory details of the proposal. -* **Tradeoffs** - Any items of the proposal that are less desirable should be listed here. Alternative - solutions to the same problem could also be listed here. -* **Potential issues** - This is where problems with the proposal would be listed, such as changes - that are not backwards compatible. -* **Security considerations** - Discussion of what steps were taken to avoid security issues in the - future and any potential risks in the proposal. -* **Conclusion** - A repeat of the problem and solution. - -Furthermore, the template should not be required to be followed. However it is strongly recommended to -maintain some sense of consistency between proposals. +Homeservers should reject the binding of a 3PID if it already been bound, +**unless** the requesting user is the one who originally bound that 3PID. If +so, then they should be able to bind it again if they choose. +In doing so, it would allow users to bind their 3PIDs to multiple identity +servers, even if the homeserver has already been made aware of it. ## Tradeoffs -*This is where alternative solutions could be listed. There's almost always another way to do things -and this section gives you the opportunity to highlight why those ways are not as desirable. The -argument made in this example is that all of the text provided by the template could be integrated -into the proposals introduction, although with some risk of losing clarity.* - -Instead of adding a template to the repository, the assistance it provides could be integrated into -the proposal process itself. There is an argument to be had that the proposal process should be as -descriptive as possible, although having even more detail in the proposals introduction could lead to -some confusion or lack of understanding. Not to mention if the document is too large then potential -authors could be scared off as the process suddenly looks a lot more complicated than it is. For those -reasons, this proposal does not consider integrating the template in the proposals introduction a good -idea. - +Identity servers will still let 3PIDs be rebound to another Matrix ID, while +a single homeserver won't let a 3PID transition between two users. If one +thinks about typical internet services however, you aren't allowed to simply +take an email address from another account even if you have control of it. ## Potential issues -*Not all proposals are perfect. Sometimes there's a known disadvantage to implementing the proposal, -and they should be documented here. There should be some explanation for why the disadvantage is -acceptable, however - just like in this example.* - -Someone is going to have to spend the time to figure out what the template should actually have in it. -It could be a document with just a few headers or a supplementary document to the process explanation, -however more detail should be included. A template that actually proposes something should be considered -because it not only gives an opportunity to show what a basic proposal looks like, it also means that -explanations for each section can be described. Spending the time to work out the content of the template -is beneficial and not considered a significant problem because it will lead to a document that everyone -can follow. - +Newer clients will expect homeservers to allow them to switch between +identity servers and bind/rebind emails as they please. If dealing with an +older homeserver, clients will receive an `HTTP 400 M_THREEPID_IN_USE`. +Clients should be prepared to understand that this may just mean they are +dealing with an old homeserver, versus the 3PID already being bound on this +homeserver by another user. ## Security considerations -*Some proposals may have some security aspect to them that was addressed in the proposed solution. This -section is a great place to outline some of the security-sensitive components of your proposal, such as -why a particular approach was (or wasn't) taken. The example here is a bit of a stretch and unlikely to -actually be worthwhile of including in a proposal, but it is generally a good idea to list these kinds -of concerns where possible.* - -By having a template available, people would know what the desired detail for a proposal is. This is not -considered a risk because it is important that people understand the proposal process from start to end. - +None. ## Conclusion -*Repeating the problem and solution in different words helps reviewers understand the problem a bit more. -This section should wrap up any loose ends left in the document, as well as cover a brief overview of the -content in each section. Note that the example here doesn't touch on the specific implementation details -described in the "Proposal" section - just the high-level points made there.* - -Not having a template for people to follow when making their proposals could lead to large differences -between each MSC. This would make it difficult for reviewers, and there's a potential that some information -could be left out by accident. A template written in the same format the proposal process requires would -give authors the ability to understand how to better explain their own proposal. - -A descriptive template would help potential authors comprehend what the proposal process requires by -demonstrating what is expected of a proposal. Although this is more effort up front, it would lead to more -time saved in the future due to questions about the process. +By lifting the restriction of not allowing a user to bind a 3PID multiple +times, we unlock the ability to interact with multiple identity servers on +the same account. This not only allows the user to play around and gain a +better understanding of the purpose of an identity server, but it is also one +step towards further decentralisation in the identity server space. From 6ed0ae36badb5e978c6a8898d8bb058d1aa17263 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 13 Aug 2019 11:12:04 +0100 Subject: [PATCH 452/497] rename msc # --- ...xxxx-existing-3pid-allowed.md => 2229-rebind-existing-3pid.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-existing-3pid-allowed.md => 2229-rebind-existing-3pid.md} (100%) diff --git a/proposals/xxxx-existing-3pid-allowed.md b/proposals/2229-rebind-existing-3pid.md similarity index 100% rename from proposals/xxxx-existing-3pid-allowed.md rename to proposals/2229-rebind-existing-3pid.md From be77b5823c50808dd4545804fd66caaa29052460 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 13 Aug 2019 11:24:37 +0100 Subject: [PATCH 453/497] fix up --- proposals/2229-rebind-existing-3pid.md | 48 ++++++++++++++++---------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index c10eec27..ce2547e2 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -1,20 +1,25 @@ # Allowing 3PID Owners to Rebind +``` 3PID noun - A third-party identifier such as an email address or phone number, that + + A "third-party identifier" such as an email address or phone number, that can be tied to your Matrix ID in order for your contacts outside of - Matrix to find you, typically with the help of an [identity - server](https://matrix.org/docs/spec/identity_service/r0.2.1.html). + Matrix to find you, typically with the help of an identity server. + +Identity server + noun + + A queryable server that holds mappings between 3PIDs and Matrix IDs. +``` As part of the on-going privacy work, Matrix client applications are -attempting to make the concept of an identity server more clear to the user, -as well as allowing a user to interact with multiple identity servers while -they're logged in. - -As part of facilitating this work, Matrix clients should be able to allow -users, while logged in, the ability to pick an identity server, see what -3PIDs they currently have bound to their Matrix ID, and bind/unbind as they +attempting to make the concept of an identity server clearer to the user, as +well as allowing a user to interact with multiple identity servers while +logged in. In facilitating this, Matrix clients should be able to allow +logged-in users the ability to pick an identity server, see what 3PIDs they +currently have bound to their Matrix ID, and bind/unbind addresses as they desire. When implementating this functionality, a technicality in the spec was found @@ -23,14 +28,14 @@ The line "The homeserver must check that the given email address is **not** already associated with an account on this homeserver." appears under the [POST /_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) -line. The same goes for the [equivalent msisdn +endpoint description. The same goes for the [equivalent msisdn (phone) endpoint](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken). -If a user binds their email address, through the homeserver to identity -server A, then switches to identity server B to try and do the same, the -homeserver will reject the second request as this email address has already -been bound. This is due to the homeserver attaching the email address user's -accounts whenever a bind is performed through them. +When a user binds their 3PID through a homeserver to identity server A, the +homeserver keeps a record and attaches the address to the local account. +Then, if the user switches to identity server B to try and do the same, the +homeserver will reject the second request as this address has already been +bound. ## Proposal @@ -38,13 +43,14 @@ This proposal calls for allowing 3PID owners to rebind their 3PIDs using the [POST /_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) and [POST /_matrix/client/r0/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) -endpoints by extending the definition of what homeservers should check before rejecting a bind. +endpoints by extending the definition of what homeservers should check before +rejecting a bind. Homeservers should reject the binding of a 3PID if it already been bound, **unless** the requesting user is the one who originally bound that 3PID. If -so, then they should be able to bind it again if they choose. +so, then they should be able to bind it again and again if they so choose. -In doing so, it would allow users to bind their 3PIDs to multiple identity +In doing so, users would be able to bind their 3PIDs to multiple identity servers, even if the homeserver has already been made aware of it. ## Tradeoffs @@ -63,6 +69,10 @@ Clients should be prepared to understand that this may just mean they are dealing with an old homeserver, versus the 3PID already being bound on this homeserver by another user. +Homeservers will need to keep track of each identity server that an address +has been bound with, and upon user account deactivation, should attempt to +unbind all of them. + ## Security considerations None. From f313b49c2652f3ad13cab6d51098db5e5f4a83b3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 13 Aug 2019 11:40:34 +0100 Subject: [PATCH 454/497] Add bind def. --- proposals/2229-rebind-existing-3pid.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index ce2547e2..11b2e370 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -12,6 +12,12 @@ Identity server noun A queryable server that holds mappings between 3PIDs and Matrix IDs. + +Bind + verb + + Create a mapping between a 3PID and a Matrix ID. Useful for people to + find a user based on their existing third-party contact information. ``` As part of the on-going privacy work, Matrix client applications are From cb1e3b8373d04d2b2e9ca659d2517299027335af Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 13 Aug 2019 13:29:35 +0100 Subject: [PATCH 455/497] Take into account the 1 is case --- proposals/2229-rebind-existing-3pid.md | 44 ++++++++++++++++---------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index 11b2e370..ce658121 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -29,19 +29,28 @@ currently have bound to their Matrix ID, and bind/unbind addresses as they desire. When implementating this functionality, a technicality in the spec was found -to prevent the ability to bind the same 3PID to multiple identity servers. -The line "The homeserver must check that the given email address is **not** -already associated with an account on this homeserver." appears under the -[POST +to prevent certain abilities for a user. A user could not add a 3PID to their +homeserver before binding it to an identity server. It also prevents users +from binding the same 3PID to multiple identity servers. The line "The +homeserver must check that the given email address is **not** already +associated with an account on this homeserver." appears under the [POST /_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) endpoint description. The same goes for the [equivalent msisdn (phone) endpoint](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken). -When a user binds their 3PID through a homeserver to identity server A, the -homeserver keeps a record and attaches the address to the local account. -Then, if the user switches to identity server B to try and do the same, the -homeserver will reject the second request as this address has already been -bound. +When a user adds an email to their account on their homeserver, they can +choose to bind that email to an identity server at the same time. This is +specified through a `bind` boolean. If the user first adds the 3PID with +`bind: false`, then decides they want to bind that 3PID to an identity server +to make themselves discoverable by it, by making another request with `bind: +true`. The homeserver will reject the second request, because this 3PID is +already tied to the user's account. + +Similarly, when a user initially sends their 3PID with `bind: true` through a +homeserver to identity server A, the homeserver keeps a record and attaches +the address to the local account. If the user then switches to identity +server B to try and do the same, the homeserver will reject the second +request as this address has already been bound. ## Proposal @@ -56,15 +65,16 @@ Homeservers should reject the binding of a 3PID if it already been bound, **unless** the requesting user is the one who originally bound that 3PID. If so, then they should be able to bind it again and again if they so choose. -In doing so, users would be able to bind their 3PIDs to multiple identity -servers, even if the homeserver has already been made aware of it. +In doing so, users would be able to rebind their 3PIDs, even if the +homeserver has already been made aware of it. ## Tradeoffs Identity servers will still let 3PIDs be rebound to another Matrix ID, while a single homeserver won't let a 3PID transition between two users. If one thinks about typical internet services however, you aren't allowed to simply -take an email address from another account even if you have control of it. +take an email address from another account even if you have control of it, so +this shouldn't be too unintuitive. ## Potential issues @@ -86,7 +96,9 @@ None. ## Conclusion By lifting the restriction of not allowing a user to bind a 3PID multiple -times, we unlock the ability to interact with multiple identity servers on -the same account. This not only allows the user to play around and gain a -better understanding of the purpose of an identity server, but it is also one -step towards further decentralisation in the identity server space. +times, we allow the basic ability of publishing a 3PID after associating it +with an account, as well as allow users to interact with multiple identity +servers on the same account with the same 3PIDs. This not only allows the +user to play around and gain a better understanding of the purpose of an +identity server, but it is also one step towards further decentralisation in +the identity server space. From 5b1ea4ffcb9db8e721c630d3740d6103fee6de15 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 13 Aug 2019 17:13:48 +0100 Subject: [PATCH 456/497] Update proposals/2229-rebind-existing-3pid.md Co-Authored-By: J. Ryan Stinnett --- proposals/2229-rebind-existing-3pid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index ce658121..dd89ecc3 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -43,7 +43,7 @@ choose to bind that email to an identity server at the same time. This is specified through a `bind` boolean. If the user first adds the 3PID with `bind: false`, then decides they want to bind that 3PID to an identity server to make themselves discoverable by it, by making another request with `bind: -true`. The homeserver will reject the second request, because this 3PID is +true`, the homeserver will reject the second request, because this 3PID is already tied to the user's account. Similarly, when a user initially sends their 3PID with `bind: true` through a From 01fc54faaeb353f5b0084d9f0d4ddb1e28fe60ae Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 13 Aug 2019 17:15:48 +0100 Subject: [PATCH 457/497] Update proposals/2229-rebind-existing-3pid.md Co-Authored-By: Travis Ralston --- proposals/2229-rebind-existing-3pid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index dd89ecc3..276e45c5 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -61,7 +61,7 @@ This proposal calls for allowing 3PID owners to rebind their 3PIDs using the endpoints by extending the definition of what homeservers should check before rejecting a bind. -Homeservers should reject the binding of a 3PID if it already been bound, +Homeservers should reject the binding of a 3PID if it has already been bound, **unless** the requesting user is the one who originally bound that 3PID. If so, then they should be able to bind it again and again if they so choose. From 2547cc443c9b3de68fee289139f95884a645c005 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 13 Aug 2019 17:17:06 +0100 Subject: [PATCH 458/497] backticks --- proposals/2229-rebind-existing-3pid.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index ce658121..9854d7d9 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -55,9 +55,10 @@ request as this address has already been bound. ## Proposal This proposal calls for allowing 3PID owners to rebind their 3PIDs using the -[POST -/_matrix/client/r0/account/3pid/email/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) and [POST -/_matrix/client/r0/account/3pid/msisdn/requestToken](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) +[`POST +/_matrix/client/r0/account/3pid/email/requestToken`](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-email-requesttoken) +and [`POST +/_matrix/client/r0/account/3pid/msisdn/requestToken`](https://matrix.org/docs/spec/client_server/r0.5.0#post-matrix-client-r0-account-3pid-msisdn-requesttoken) endpoints by extending the definition of what homeservers should check before rejecting a bind. From 2c8d112089e9ab1290118d72c40b93a28b29e014 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 13 Aug 2019 18:03:43 +0100 Subject: [PATCH 459/497] assign number --- ...ver-account-data.md => 2230-identity-server-account-data.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-identity-server-account-data.md => 2230-identity-server-account-data.md} (98%) diff --git a/proposals/xxxx-identity-server-account-data.md b/proposals/2230-identity-server-account-data.md similarity index 98% rename from proposals/xxxx-identity-server-account-data.md rename to proposals/2230-identity-server-account-data.md index da539f2a..b863cc59 100644 --- a/proposals/xxxx-identity-server-account-data.md +++ b/proposals/2230-identity-server-account-data.md @@ -1,4 +1,4 @@ -# Store Identity Server in Account Data +# MSC2230: Store Identity Server in Account Data The URL of the Identity Sever to use is currently specified at registration and login time and then used for the lifetime of a login session. If users wish to From 7758e0701cb4535af50586fb0b8c31608ce03c03 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 13 Aug 2019 18:22:06 +0100 Subject: [PATCH 460/497] Remove homeserver warning --- proposals/2229-rebind-existing-3pid.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index 6cd1d155..bd765a5e 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -86,10 +86,6 @@ Clients should be prepared to understand that this may just mean they are dealing with an old homeserver, versus the 3PID already being bound on this homeserver by another user. -Homeservers will need to keep track of each identity server that an address -has been bound with, and upon user account deactivation, should attempt to -unbind all of them. - ## Security considerations None. From 229cb67b01c92925dcc5a00c7660189b82fa318e Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 14 Aug 2019 09:51:27 +0100 Subject: [PATCH 461/497] Apply suggestions from code review Use fewer formal MUST etc in proposal Co-Authored-By: Travis Ralston --- proposals/2230-identity-server-account-data.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/2230-identity-server-account-data.md b/proposals/2230-identity-server-account-data.md index b863cc59..3a81fa8e 100644 --- a/proposals/2230-identity-server-account-data.md +++ b/proposals/2230-identity-server-account-data.md @@ -15,21 +15,21 @@ shall be stored in the same format as in a .well-known file under the key, `m.identity_server` and shall comprise a single key, `base_url` which is the base URL of the ID Server to use (that is, the part before `/_matrix`). -Upon registration or login, a client MUST refrain from performing any requests +Upon registration or login, a client SHOULD refrain from performing any requests to the Identity Server until the account data has been fetched from the server. -Once it has the account data, it MUST check for the presence of the -`m.identity_server` key. If present, the `base_url` in this key MUST be used +Once it has the account data, it SHOULD check for the presence of the +`m.identity_server` key. If present, the `base_url` in this key SHOULD be used as the Identity Server base URL for the duration of the login session. If this key is not present, the client SHOULD populate it with the ID Server URL -that was or would have been used in the login/registration process. This may +that was or would have been used in the login/registration process. This could be either from user input, a .well-known lookup, or a default in the client. -Client MUST listen for changes in the `m.identity_server` account data value -and update the URL that they use for ID Server requests accordingly UNLESS +Client SHOULD listen for changes in the `m.identity_server` account data value +and update the URL that they use for ID Server requests accordingly unless the login session and choice of ID Server base URL predates this change, in which case they SHOULD continue to use the value they are currently using. -Clients MAY offer a way for users to change the ID server being used. If they +Clients can offer a way for users to change the ID server being used. If they do, the client MUST update the value of `m.identity_server` accordingly. The `m.identity_server` may be present with a value of `null`. In this case, From b9b984ae60172892c13efc5702d68c438ceac0e5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 14 Aug 2019 09:52:13 +0100 Subject: [PATCH 462/497] clarify --- proposals/2230-identity-server-account-data.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2230-identity-server-account-data.md b/proposals/2230-identity-server-account-data.md index 3a81fa8e..d26de3e2 100644 --- a/proposals/2230-identity-server-account-data.md +++ b/proposals/2230-identity-server-account-data.md @@ -13,7 +13,8 @@ make this easier. The base URL of the Identity Server is to be stored in user account data. It shall be stored in the same format as in a .well-known file under the key, `m.identity_server` and shall comprise a single key, `base_url` which is the -base URL of the ID Server to use (that is, the part before `/_matrix`). +base URL of the ID Server to use (that is, the part before `/_matrix`, including +`https://`). Upon registration or login, a client SHOULD refrain from performing any requests to the Identity Server until the account data has been fetched from the server. From 97f856d70650afdd3e3934e7c4b9780396a40b9b Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Wed, 14 Aug 2019 11:00:03 +0100 Subject: [PATCH 463/497] Domain name is potentially personally-identifying Thanks to @turt2live Signed-off-by: Olivier Wilkinson (reivilibre) --- proposals/2197-search_filter_in_federation_publicrooms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 3ac9f3c4..37e3fe7d 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -129,8 +129,8 @@ that's being shared is [\[1\]][1]: - only covered by GDPR if: - the search terms contain personal data, or - - the user's homeserver IP address is uniquely identifying (because it's a - single-person homeserver, perhaps) + - the user's homeserver IP address or domain name is uniquely identifying + (because it's a single-person homeserver, perhaps) - likely to be *expected* to be shared with the remote homeserver [1]: https://github.com/matrix-org/matrix-doc/pull/2197#issuecomment-517641751 From 7e85b9d56afb78b8cfd867db30db7d6b70f007d6 Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Wed, 14 Aug 2019 11:03:55 +0100 Subject: [PATCH 464/497] Acknowledge other potential error responses for fallback Signed-off-by: Olivier Wilkinson (reivilibre) --- .../2197-search_filter_in_federation_publicrooms.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 37e3fe7d..5d1ae7c1 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -106,9 +106,14 @@ any worse than the current one, and it is expected that large homeservers would be quick to upgrade to support this feature once it is available. In addition, as the `POST` method was not previously accepted on the -`/publicRooms` endpoint over federation, then it is not a difficult task to use -an `M_UNRECOGNIZED` standard error response `errcode` as a signal that fallback -is required. +`/publicRooms` endpoint over federation, then it is possible to fall back to the +old behaviour, if one of the following errors is encountered: + +- an `M_UNRECOGNIZED` standard error response `errcode` (this is what would be + typically expected in this situation) +- an `M_NOT_FOUND` standard error response +- a `404 Not Found` HTTP error response +- a `405 Method Not Allowed` HTTP error response ## Security considerations From 4219e272ec5382a7ac0992bc43b9717a72f25ddb Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Wed, 14 Aug 2019 11:06:45 +0100 Subject: [PATCH 465/497] Drop the hard SHOULD Adopts @turt2live's phrasing Signed-off-by: Olivier Wilkinson (reivilibre) --- .../2197-search_filter_in_federation_publicrooms.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index 5d1ae7c1..b3ce3dc3 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -140,12 +140,12 @@ that's being shared is [\[1\]][1]: [1]: https://github.com/matrix-org/matrix-doc/pull/2197#issuecomment-517641751 -For the sake of clarity, clients SHOULD display a warning that a remote search -will take the user's data outside the jurisdiction of their own homeserver, -before using the `server` parameter of the Client-Server API `/publicRooms`, as -it can be assumed that this will lead to the server invoking the Federation -API's `/publicRooms` – on the specified remote server – with the user's search -terms. +For the sake of clarity, clients are strongly encouraged to display a warning +that a remote search will take the user's data outside the jurisdiction of their +own homeserver, before using the `server` parameter of the Client-Server API +`/publicRooms`, as it can be assumed that this will lead to the server invoking +the Federation API's `/publicRooms` – on the specified remote server – with the +user's search terms. ## Conclusion From 4059661c29b15c6bc04cdebcdb6c5deb477910ac Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 14 Aug 2019 11:38:53 +0100 Subject: [PATCH 466/497] Update proposals/2229-rebind-existing-3pid.md Co-Authored-By: Kitsune Ral --- proposals/2229-rebind-existing-3pid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2229-rebind-existing-3pid.md b/proposals/2229-rebind-existing-3pid.md index bd765a5e..83883c78 100644 --- a/proposals/2229-rebind-existing-3pid.md +++ b/proposals/2229-rebind-existing-3pid.md @@ -28,7 +28,7 @@ logged-in users the ability to pick an identity server, see what 3PIDs they currently have bound to their Matrix ID, and bind/unbind addresses as they desire. -When implementating this functionality, a technicality in the spec was found +When implementing this functionality, a technicality in the spec was found to prevent certain abilities for a user. A user could not add a 3PID to their homeserver before binding it to an identity server. It also prevents users from binding the same 3PID to multiple identity servers. The line "The From 92c6f4c38e9cad7c42b813d2a4c89e9cc4f88105 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 15 Aug 2019 18:10:38 +0100 Subject: [PATCH 467/497] Add M_USER_DEACTIVATED to list of error codes (#2234) Spec PR for [MSC 2181](https://github.com/matrix-org/matrix-doc/pull/2181). Adds the `M_USER_DEACTIVATED` error code and a short description to the client-server API. --- api/client-server/login.yaml | 7 +++++-- changelogs/client_server/newsfragments/2234.feature | 1 + specification/client_server_api.rst | 4 ++++ 3 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2234.feature diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index 98914a06..f6c92638 100644 --- a/api/client-server/login.yaml +++ b/api/client-server/login.yaml @@ -194,10 +194,13 @@ paths: "$ref": "definitions/errors/error.yaml" 403: description: |- - The login attempt failed. For example, the password may have been incorrect. + The login attempt failed. This can include one of the following error codes: + * ``M_FORBIDDEN``: The provided authentication data was incorrect. + * ``M_USER_DEACTIVATED``: The user has been deactivated. examples: application/json: { - "errcode": "M_FORBIDDEN"} + "errcode": "M_FORBIDDEN" + } schema: "$ref": "definitions/errors/error.yaml" 429: diff --git a/changelogs/client_server/newsfragments/2234.feature b/changelogs/client_server/newsfragments/2234.feature new file mode 100644 index 00000000..bb1883b3 --- /dev/null +++ b/changelogs/client_server/newsfragments/2234.feature @@ -0,0 +1 @@ +Add ``M_USER_DEACTIVATED`` error code. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 39a2fd3d..916604a3 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -150,6 +150,10 @@ Other error codes the client might encounter are: :``M_UNAUTHORIZED``: The request was not correctly authorized. Usually due to login failures. +:``M_USER_DEACTIVATED``: + The user ID associated with the request has been deactivated. Typically for + endpoints that prove authentication, such as ``/login``. + :``M_USER_IN_USE``: Encountered when trying to register a user ID which has been taken. From 475c64de8c2827b772372ba0b6c53051b9d94e27 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 16 Aug 2019 19:52:35 -0600 Subject: [PATCH 468/497] Disclose origin story --- proposals/1961-integrations-auth.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/1961-integrations-auth.md b/proposals/1961-integrations-auth.md index 7f735607..1f868e4c 100644 --- a/proposals/1961-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -3,6 +3,9 @@ A set of common APIs needs to be defined for clients to be able to interact with an integration manager. This proposal covers the authentication portion of that API. +**Note**: this proposal is part of a larger "Integrations API" which has not yet been defined. +See [MSC1956](https://github.com/matrix-org/matrix-doc/pull/1956) for details. + ## Proposal From 22c96926848fae3089673c761c0284637bc763d8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 16 Aug 2019 19:53:28 -0600 Subject: [PATCH 469/497] Disclose origin story better --- proposals/1957-integrations-discovery.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index cef17098..feac7451 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -1,6 +1,7 @@ # MSC1957: Integration manager discovery -*Note*: This is a required component of [MSC1956 - Integrations API](https://github.com/matrix-org/matrix-doc/pull/1956) +**Note**: this proposal is part of a larger "Integrations API" which has not yet been defined. +See [MSC1956](https://github.com/matrix-org/matrix-doc/pull/1956) for details. Users should have the freedom to choose which integration manager they want to use in their client, while also accepting suggestions from their homeserver and client. Clients need to know where to find the different From 865d3da0f866cb8afa126df1c56558e6dc353616 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 16 Aug 2019 19:59:32 -0600 Subject: [PATCH 470/497] General clarity improvements --- proposals/1957-integrations-discovery.md | 26 ++++++++++++++---------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index feac7451..b305c18f 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -79,15 +79,16 @@ The user is able to have multiple integration managers through use of multiple w #### Display order of integration managers -Clients which have support for integration managers should display at least 1 manager, but may decide -to display multiple via something like tabs. Clients must prefer to display the user's configured +Clients which have support for integration managers should display at least 1 manager, but should +display multiple via something like tabs. Clients must prefer to display the user's configured integration managers over any defaults, and if only displaying one manager must pick the first -manager after sorting the `state_key`s in lexicographical order. Clients may additionally display -default managers if they so wish, and should preserve the order defined in the various defaults. -If the user has no configured integration managers, the client must prefer to display one or more -of the managers suggested by the homeserver over the managers recommended by the client. +manager after sorting the `state_key`s of the applicable widgets in lexicographical order. Clients +can additionally display default managers if they so wish, and should preserve the order defined in +the various defaults. If the user has no configured integration managers, the client must prefer +to display one or more of the managers suggested by the homeserver over the managers recommended +by the client. -The client may optionally support a way to entirely disable integration manager support, even if the +The client can optionally support a way to entirely disable integration manager support, even if the user and homeserver have managers defined. The rationale for having the client prefer to use the user's integration managers first is so that @@ -157,7 +158,10 @@ Some things which may be desirable in the future are: ## Security considerations -When displaying integration managers, clients should not trust that the input is sanitary. Integration -managers may only be at HTTP(S) endpoints and may still have malicious intent. Ensure any sandboxing -on the manager is appropriate such that it can communicate with the client, but cannot perform unauthorized -actions. +When displaying integration managers, clients should not trust that the input is sanitary. Per the +proposal above, an intergration manager is only permitted to be served from HTTP(S) URIs. A given +integration manager can still have malicious intent however, and clients should ensure any sandboxing +on the manager is appropriate such that it can communicate with the client, but cannot perform +unauthorized actions. Other URI schemes are just as dangerous and could potentially be allowed by +this proposal - use cases are less defined and desirable for schemes like `file://` and are excluded +by this proposal. They can be added in a future proposal if a use case arises. From 76f9196ff39a00c25423582a215c7017f3c9dc8a Mon Sep 17 00:00:00 2001 From: "Olivier Wilkinson (reivilibre)" Date: Mon, 19 Aug 2019 07:44:37 +0100 Subject: [PATCH 471/497] Address @richvdh's comments --- ...search_filter_in_federation_publicrooms.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/proposals/2197-search_filter_in_federation_publicrooms.md b/proposals/2197-search_filter_in_federation_publicrooms.md index b3ce3dc3..ef1521d1 100644 --- a/proposals/2197-search_filter_in_federation_publicrooms.md +++ b/proposals/2197-search_filter_in_federation_publicrooms.md @@ -24,7 +24,7 @@ In turn, this means that these room directory query responses can be generated more quickly and then, due to their smaller size, transmitted over the network more quickly. -These benefits have been exploited in the Client-Server API, which implements +These benefits have been utilised in the Client-Server API, which implements search filtering using the `filter` JSON body parameter in the `POST` method on the `/publicRooms` endpoint. @@ -105,15 +105,14 @@ any worse than the current one, and it is expected that large homeservers – which cause the most work with the current search implementations – would be quick to upgrade to support this feature once it is available. -In addition, as the `POST` method was not previously accepted on the -`/publicRooms` endpoint over federation, then it is possible to fall back to the -old behaviour, if one of the following errors is encountered: +As the `POST` method was not previously accepted on the `/publicRooms` endpoint +over federation, then requesting servers should fall back to the old behaviour, +if one of the following errors is encountered: -- an `M_UNRECOGNIZED` standard error response `errcode` (this is what would be - typically expected in this situation) -- an `M_NOT_FOUND` standard error response -- a `404 Not Found` HTTP error response -- a `405 Method Not Allowed` HTTP error response +- an HTTP `400` response with an `M_UNRECOGNIZED` standard error response + `errcode` (this is what would be typically expected in this situation) +- a `404` (Not Found) HTTP error response +- a `405` (Method Not Allowed) HTTP error response ## Security considerations @@ -121,7 +120,7 @@ There are no known security considerations. ## Privacy considerations -At current, remote homeservers do not learn about what a user has searched for. +At present, remote homeservers do not learn about what a user has searched for. However, under this proposal, in the context of using the Federation API to forward on queries from the Client-Server API, a client's homeserver would end From e4bdc283fd6cdeb2bf90b5a79a180fb19a8e9c63 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 19 Aug 2019 11:45:46 +0100 Subject: [PATCH 472/497] Apply suggestions from code review Typos / spelling Co-Authored-By: Hubert Chathi --- proposals/2140-terms-of-service-2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 557376cc..78a682d7 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -7,7 +7,7 @@ corresponding method that can be used with Identity Servers and Integration Managers. Requirements for this proposal are: - * ISs and IMs should be able to give multiple documents a user must agree to + * ISes and IMs should be able to give multiple documents a user must agree to abide by * Each document shoud be versioned * ISes and IMs must, for each request that they handle, know that the user @@ -15,7 +15,7 @@ Requirements for this proposal are: absolute proof (we will always have to trust that the client actually showed the document to the user) but it must be reasonably demonstrable that the user has given informed consent for the client to use that service. - * ISs and IMs must be able to prevent users from using the service if they + * ISes and IMs must be able to prevent users from using the service if they have not provided agreement. * A user should only have to agree to each version of each document once for their Matrix ID, ie. having agreed to a set of terms in one client, they @@ -265,7 +265,7 @@ in the current login sessions is: A client uses this client/server API endpoint to request that the Homeserver removes the given 3PID from the given Identity Server, or all Identity Servers. -Takes parameters the same parameters as +Takes the same parameters as `POST /_matrix/client/r0/account/3pid/delete`, ie. `id_server`, `medium`, `address` and the newly added `is_token`. From 12377fbf50515989004bc133071ca56c34ae300f Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 19 Aug 2019 11:53:41 +0100 Subject: [PATCH 473/497] /account/logout not /logout Co-Authored-By: Hubert Chathi --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 78a682d7..c19a1ea9 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -71,7 +71,7 @@ of: * `/_matrix/identity/v2/pubkey/*` * The new `$prefix/account/register` endpoint * The new `GET /_matrix/identity/v2/terms` - * `$prefix/logout` + * `$prefix/account/logout` ...may return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that the user must authenticate with OpenID and supply a valid From 6d0067320c5703d3408c19952d68fb5b41c588f0 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 19 Aug 2019 13:31:20 +0100 Subject: [PATCH 474/497] clarify error proxying --- proposals/2140-terms-of-service-2.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index c19a1ea9..ed8e740e 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -94,7 +94,8 @@ Homeserver to make calls to the IS on its behalf, it must also supply its access token for the Identity Server alongside in the `is_token` key of the same JSON object. That is, in the main request object for a `requestToken` request and in the `threepidCreds` object when supplying 3PID credentials (eg. -in the `m.email.identity` UI auth stage). Exceptions to this are any requests +in the `m.email.identity` UI auth stage). The server must also relay +`M_TERMS_NOT_SIGNED` errors back to the client. Exceptions to this are any requests where the only IS operation the Homeserver may perform is unbinding, ie. `/_matrix/client/r0/account/deactivate` and `/_matrix/client/r0/account/3pid/delete`, in which case the unbind will be From 9e073e9647eef1bfff0dad0a7f0fc46013b66ddc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 19 Aug 2019 10:42:30 -0600 Subject: [PATCH 475/497] Speeeeeeling Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/1957-integrations-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index b305c18f..f6ac5aa4 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -100,7 +100,7 @@ user so they don't get left out. #### Displaying integration managers Clients simply open the `ui_url` (or equivalent) in an `iframe` or similar. In the current ecosystem, -integration managers would receive a `scalar_token` to idenitify the user - this is no longer the case +integration managers would receive a `scalar_token` to identify the user - this is no longer the case and instead integration managers must seek other avenues for determining the user ID. Other proposals cover how to do this in the context of the integrations API. @@ -159,7 +159,7 @@ Some things which may be desirable in the future are: ## Security considerations When displaying integration managers, clients should not trust that the input is sanitary. Per the -proposal above, an intergration manager is only permitted to be served from HTTP(S) URIs. A given +proposal above, an integration manager is only permitted to be served from HTTP(S) URIs. A given integration manager can still have malicious intent however, and clients should ensure any sandboxing on the manager is appropriate such that it can communicate with the client, but cannot perform unauthorized actions. Other URI schemes are just as dangerous and could potentially be allowed by From 9b2ca3cdfe99414e4cf2047c13a20991e32d6aae Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 20 Aug 2019 16:19:15 +0100 Subject: [PATCH 476/497] typoes / clarifications Co-Authored-By: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2230-identity-server-account-data.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2230-identity-server-account-data.md b/proposals/2230-identity-server-account-data.md index d26de3e2..98fcfbf1 100644 --- a/proposals/2230-identity-server-account-data.md +++ b/proposals/2230-identity-server-account-data.md @@ -1,6 +1,6 @@ # MSC2230: Store Identity Server in Account Data -The URL of the Identity Sever to use is currently specified at registration and +The URL of the Identity Server to use is currently specified at registration and login time and then used for the lifetime of a login session. If users wish to specify a custom one, they must do so each time they log in on every client. Once they have chosen an Identity Server to advertise their 3PIDs on, it would @@ -11,7 +11,7 @@ make this easier. ## Proposal The base URL of the Identity Server is to be stored in user account data. It -shall be stored in the same format as in a .well-known file under the key, +shall be stored in the same format as in a .well-known file under the event type `m.identity_server` and shall comprise a single key, `base_url` which is the base URL of the ID Server to use (that is, the part before `/_matrix`, including `https://`). @@ -33,7 +33,7 @@ which case they SHOULD continue to use the value they are currently using. Clients can offer a way for users to change the ID server being used. If they do, the client MUST update the value of `m.identity_server` accordingly. -The `m.identity_server` may be present with a value of `null`. In this case, +The `m.identity_server` may be present with a `base_url` of `null`. In this case, clients MUST treat this as no ID Server URL being set and not perform ID Server requests, disabling any functionality that requires such requests. From 788796e1c6b1f8b57a10530d633a50004f6b27d3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 20 Aug 2019 09:20:07 -0600 Subject: [PATCH 477/497] Multiple clarifications --- proposals/1957-integrations-discovery.md | 35 ++++++++++++++++-------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index f6ac5aa4..201f28c8 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -45,10 +45,10 @@ As shown, the homeserver is able to suggest multiple integration managers throug must have an `api_url` which must be an `http` or `https` URL. The `ui_url` is optional and if not provided is the same as the `api_url`. Like the `api_url`, the `ui_url` must be `http` or `https` if supplied. -The `ui_url` is ultimately treated the same as a widget, except that the custom `data` is not present and -must not be templated here. Variables like `$matrix_display_name` are able to function, however. Integration -managers should never use the `$matrix_user_id` as authoritative and instead seek other ways to determine the -user ID. This is covered by other proposals. +The `ui_url` is ultimately treated the same as a widget, except that the `data` object from the widget is not +present and must not be templated here. Variables like `$matrix_display_name` are able to function, however. +Integration managers should never use the `$matrix_user_id` as authoritative and instead seek other ways to +determine the user ID. This is covered by other proposals. The `api_url` is the URL clients will use when *not* embedding the integration manager, and instead showing its own purpose-built interface. @@ -56,7 +56,8 @@ its own purpose-built interface. Clients should query the `.well-known` information for the homeserver periodically to update the integration manager settings for that homeserver. The client is not expected to validate or use any other information contained in the response. Current recommendations are to query the configuration when the client starts up -and every 8 hours after that. +and every 8 hours after that. Clients can additionally refresh the configuration whenever they feel is +necessary (such as every time the user opens the integration manager). #### User-configured integration managers @@ -111,10 +112,15 @@ as an account widget rather than a room widget. #### Discovering a manager by only the domain name Clients may wish to ask users for a single canonical domain name so they can find the manager to add -to the user's account transparently. Similar to the .well-known discovery done by servers (and clients -during login), clients which have an integrations domain (eg: "example.org") make a regular HTTPS -request to `https://example.org/.well-known/matrix/integrations` which returns an object which looks -like the following: +to the user's account transparently. This differs from the .well-known discovery which allows homeservers +to recommend their own integration manager: the homeserver is not recommending a default here. The +user has instead opted to pick an integration manager (identified only by domain name) and the client +is expected to resolve that to a set of URLs it can use for the manager. + +Similar to the .well-known discovery done by servers (and clients during login), clients which have an +integrations domain (eg: "example.org") make a regular HTTPS request to +`https://example.org/.well-known/matrix/integrations` which returns an object which looks like the +following: ```json { "m.integrations_widget": { @@ -132,6 +138,13 @@ property, the client should assume there is no integrations manager running on t an integration manager, described above. The client should wrap the object verbatim into the appropriate account data location. +Because the .well-known file would be accessed by web browsers, among other platforms, the server +should be using appropriate CORS headers for the request. The recommended headers are the same as those +which are already recommended for homeserver discovery in the Client-Server API. + +*Note*: this could reuse the client-server mechanic for discovery and just omit the homeserver information +however that conflates many concerns together on the one endpoint. A new endpoint is instead proposed +to keep the concerns isolated. ## Tradeoffs @@ -144,8 +157,8 @@ support this use case, even if it is moderately rare. We could also define the integration managers in a custom account data event rather than defining them as a widget. Doing so just adds clutter to the account data and risks duplicating code in clients as -using widgets gets us URL templating for free (see the section later on in this proposal about account -widgets for more information). +using widgets gets us URL templating for free (see the section earlier on in this proposal about account +widgets for more information: "User-configured integration managers"). ## Future extensions From 1f8cfd57298f68837a315008f8e280eac23e75b4 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 21 Aug 2019 14:19:20 +0100 Subject: [PATCH 478/497] Update migration mechanism --- proposals/2230-identity-server-account-data.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/proposals/2230-identity-server-account-data.md b/proposals/2230-identity-server-account-data.md index 98fcfbf1..19fb3062 100644 --- a/proposals/2230-identity-server-account-data.md +++ b/proposals/2230-identity-server-account-data.md @@ -21,14 +21,11 @@ to the Identity Server until the account data has been fetched from the server. Once it has the account data, it SHOULD check for the presence of the `m.identity_server` key. If present, the `base_url` in this key SHOULD be used as the Identity Server base URL for the duration of the login session. If this -key is not present, the client SHOULD populate it with the ID Server URL -that was or would have been used in the login/registration process. This could -be either from user input, a .well-known lookup, or a default in the client. +key is not present, the client SHOULD use whatever value it would have used prior +to this MSC. It should not update the account data in this situation. Client SHOULD listen for changes in the `m.identity_server` account data value -and update the URL that they use for ID Server requests accordingly unless -the login session and choice of ID Server base URL predates this change, in -which case they SHOULD continue to use the value they are currently using. +and update the URL that they use for ID Server requests accordingly. Clients can offer a way for users to change the ID server being used. If they do, the client MUST update the value of `m.identity_server` accordingly. @@ -43,10 +40,9 @@ account data entry to `null`. ### Transition Period -Clients currently logged in with a value configured for the ID Server base -URL SHOULD use the value from `m.identity_server` if it exists or is created, -but otherwise continue to use the URL they had previously. They MUST NOT -populate the `m.identity_server` with their current ID Server base URL. +Clients will continue to use whatever IS URLs they currently use until the +user sets one explicitly, at which point it will be written to account data +and all clients will start using this value. ## Tradeoffs From 4073d940da7d0a3ed25dd30f820dd83692389a47 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 21 Aug 2019 15:11:10 +0100 Subject: [PATCH 479/497] Typo Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index ed8e740e..3e2456bd 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -148,7 +148,7 @@ to use the service. Its response is similar to the structure used in the "version": "1.2", "en": { "name": "Privacy Policy", - "url": "https://example.org/somewhere/privaacy-1.2-en.html" + "url": "https://example.org/somewhere/privacy-1.2-en.html" }, "fr": { "name": "Politique de confidentialité", From 69315417b5c576e4e7966fda4f40503f2c2d3ad4 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 21 Aug 2019 15:12:25 +0100 Subject: [PATCH 480/497] Typo Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 3e2456bd..d256fa88 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -248,7 +248,7 @@ The `/_matrix/identity/v2/3pid/unbind` endpoint must not return either of these errors if the request has a valid signature from a Homeserver, and is being authenticated as such. In summary, the process for using a service that has not previously been used -in the current login sessions is: +in the current login session is: * `GET $prefix/terms` * Compare result with `m.accepted_terms` account data, get set of documents From 8bd9d7caeb2b5185878482eda0c81f50bc873468 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 21 Aug 2019 15:12:45 +0100 Subject: [PATCH 481/497] Add full stop Co-Authored-By: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2140-terms-of-service-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index d256fa88..49042aaf 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -255,7 +255,7 @@ in the current login session is: pending agreement. * If non-empty, show this set of documents to the user and wait for the user to indicate their agreement. - * Add the newly agreed documents to `m.accepted_terms` + * Add the newly agreed documents to `m.accepted_terms`. * On success, or if there were no documents pending agreement, get an OpenID token from the Homeserver and submit this token to the `register` endpoint. Store the resulting access token. From 4ea8f645d6a6f134a137f86e81c4599e1cd057f7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 21 Aug 2019 18:13:50 +0100 Subject: [PATCH 482/497] is_token -> id_access_token and add invite to proxy list --- proposals/2140-terms-of-service-2.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/proposals/2140-terms-of-service-2.md b/proposals/2140-terms-of-service-2.md index 49042aaf..9f96a00b 100644 --- a/proposals/2140-terms-of-service-2.md +++ b/proposals/2140-terms-of-service-2.md @@ -91,13 +91,14 @@ API, as specified in [MSC1961](https://github.com/matrix-org/matrix-doc/issues/1 When clients supply an identity server to the Homeserver in order for the Homeserver to make calls to the IS on its behalf, it must also supply its -access token for the Identity Server alongside in the `is_token` key of the -same JSON object. That is, in the main request object for a `requestToken` -request and in the `threepidCreds` object when supplying 3PID credentials (eg. -in the `m.email.identity` UI auth stage). The server must also relay -`M_TERMS_NOT_SIGNED` errors back to the client. Exceptions to this are any requests -where the only IS operation the Homeserver may perform is unbinding, ie. -`/_matrix/client/r0/account/deactivate` and +access token for the Identity Server alongside in the `id_access_token` key of +the same JSON object. That is, in the main request object for `requestToken` +and `/_matrix/client/r0/rooms/{roomId}/invite` requests and in the +`threepidCreds` object when supplying 3PID credentials (eg. in the +`m.email.identity` UI auth stage). The server must also relay +`M_TERMS_NOT_SIGNED` errors back to the client. Exceptions to this are any +requests where the only IS operation the Homeserver may perform is unbinding, +ie. `/_matrix/client/r0/account/deactivate` and `/_matrix/client/r0/account/3pid/delete`, in which case the unbind will be authenticated by a signed request from the Homeserver. From 8b85fda52cc27db4c424d1552a1c3a84fd176e10 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 21 Aug 2019 17:47:55 -0600 Subject: [PATCH 483/497] Add a link to the widget MSC to try and stem questions --- proposals/1957-integrations-discovery.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index 201f28c8..bb5ada55 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -3,6 +3,9 @@ **Note**: this proposal is part of a larger "Integrations API" which has not yet been defined. See [MSC1956](https://github.com/matrix-org/matrix-doc/pull/1956) for details. +**Note**: this proposal makes use of the existing Widget API proposed by +[MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236). + Users should have the freedom to choose which integration manager they want to use in their client, while also accepting suggestions from their homeserver and client. Clients need to know where to find the different integration managers and how to contact them. From b6f0e8e8ed663ad018baf233cada68782a426799 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 21 Aug 2019 17:50:18 -0600 Subject: [PATCH 484/497] Clarify that the query string is because they are widgets --- proposals/1957-integrations-discovery.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/1957-integrations-discovery.md b/proposals/1957-integrations-discovery.md index bb5ada55..85939726 100644 --- a/proposals/1957-integrations-discovery.md +++ b/proposals/1957-integrations-discovery.md @@ -81,6 +81,9 @@ widget rules apply here. The user is able to have multiple integration managers through use of multiple widgets. +The query string shown in the example is to demonstrate that integration managers are widgets and can +make use of the template options provided to widgets. + #### Display order of integration managers Clients which have support for integration managers should display at least 1 manager, but should @@ -149,6 +152,9 @@ which are already recommended for homeserver discovery in the Client-Server API. however that conflates many concerns together on the one endpoint. A new endpoint is instead proposed to keep the concerns isolated. +The query string shown in the example is to demonstrate that integration managers are widgets and can +make use of the template options provided to widgets. + ## Tradeoffs We could limit the user (and by extension, the homeserver and client) to exactly 1 integration manager From a96a2f3fcea9897817f44e4b5194d61e13becf9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Mon, 26 Aug 2019 12:11:11 +0200 Subject: [PATCH 485/497] Fix the action of a room key request cancellation. The spec states that the action of a room key request cancellation should be "cancel_request" but every known implementation uses "request_cancellation" instead. This patch fixes the spec to reflect the implementations. --- event-schemas/examples/m.room_key_request$cancel_request | 2 +- event-schemas/schema/m.room_key_request | 2 +- specification/modules/end_to_end_encryption.rst | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/event-schemas/examples/m.room_key_request$cancel_request b/event-schemas/examples/m.room_key_request$cancel_request index c6eb25de..afc1c350 100644 --- a/event-schemas/examples/m.room_key_request$cancel_request +++ b/event-schemas/examples/m.room_key_request$cancel_request @@ -1,6 +1,6 @@ { "content": { - "action": "cancel_request", + "action": "request_cancellation", "requesting_device_id": "RJYKSTBOIE", "request_id": "1495474790150.19" }, diff --git a/event-schemas/schema/m.room_key_request b/event-schemas/schema/m.room_key_request index 007d0086..c08ac0e3 100644 --- a/event-schemas/schema/m.room_key_request +++ b/event-schemas/schema/m.room_key_request @@ -38,7 +38,7 @@ properties: action: enum: - request - - cancel_request + - request_cancellation type: string requesting_device_id: description: ID of the device requesting the key. diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 329c0170..7758e2c1 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -756,8 +756,8 @@ sending `m.room_key_request`_ to-device messages to other devices with device, it can forward the keys to the first device by sending an encrypted `m.forwarded_room_key`_ to-device message. The first device should then send an `m.room_key_request`_ to-device message with ``action`` set to -``cancel_request`` to the other devices that it had originally sent the key -request to; a device that receives a ``cancel_request`` should disregard any +``request_cancellation`` to the other devices that it had originally sent the key +request to; a device that receives a ``request_cancellation`` should disregard any previously-received ``request`` message with the same ``request_id`` and ``requesting_device_id``. From 35eb1993d91d27c8abe350ffc4f756a4b866b23d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Mon, 26 Aug 2019 17:40:32 +0200 Subject: [PATCH 486/497] Add a changelog fragment for the room key request action fix. --- changelogs/client_server/newsfragments/2247.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2247.clarification diff --git a/changelogs/client_server/newsfragments/2247.clarification b/changelogs/client_server/newsfragments/2247.clarification new file mode 100644 index 00000000..43553399 --- /dev/null +++ b/changelogs/client_server/newsfragments/2247.clarification @@ -0,0 +1 @@ +Fix the ``m.room_key_request`` ``action`` value, setting it from ``cancel_request`` to ``request_cancellation``. From de3802cd5c3d33c62bbbd50d50e82275011a7711 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 27 Aug 2019 19:24:13 -0600 Subject: [PATCH 487/497] List deprecated endpoints as deprecated Affects the title and the table of contents. We can't realistically alter just the table of contents, but the table of contents is generated from this header. Fixes https://github.com/matrix-org/matrix-doc/issues/1800 --- .../templating/matrix_templates/templates/http-api.tmpl | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/templating/matrix_templates/templates/http-api.tmpl b/scripts/templating/matrix_templates/templates/http-api.tmpl index 74836045..d2ee3ff7 100644 --- a/scripts/templating/matrix_templates/templates/http-api.tmpl +++ b/scripts/templating/matrix_templates/templates/http-api.tmpl @@ -1,11 +1,15 @@ {% import 'tables.tmpl' as tables -%} -``{{endpoint.method}} {{endpoint.path}}`` -{{(5 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}} {% if "deprecated" in endpoint and endpoint.deprecated -%} +Deprecated: ``{{endpoint.method}} {{endpoint.path}}`` +{{(17 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}} + .. WARNING:: This API is deprecated and will be removed from a future release. +{% else %} +``{{endpoint.method}} {{endpoint.path}}`` +{{(5 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}} {% endif -%} {{endpoint.desc}} From b8a3f970eebfe6d321587adaced8c75656986e68 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 28 Aug 2019 13:39:42 -0600 Subject: [PATCH 488/497] Add security definition for access token --- api/identity/definitions/security.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 api/identity/definitions/security.yaml diff --git a/api/identity/definitions/security.yaml b/api/identity/definitions/security.yaml new file mode 100644 index 00000000..ef49ff5c --- /dev/null +++ b/api/identity/definitions/security.yaml @@ -0,0 +1,18 @@ +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +accessToken: + type: apiKey + description: The access_token returned by a call to ``/register``. + name: access_token + in: query From 5b53b3d0b82dcc6c7b140f4e091892cb70b3f4de Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 28 Aug 2019 13:47:06 -0600 Subject: [PATCH 489/497] Clone v1 APIs verbatim --- api/identity/v2_associations.yaml | 300 ++++++++++++++++++++++++ api/identity/v2_email_associations.yaml | 175 ++++++++++++++ api/identity/v2_invitation_signing.yaml | 97 ++++++++ api/identity/v2_phone_associations.yaml | 177 ++++++++++++++ api/identity/v2_ping.yaml | 46 ++++ api/identity/v2_pubkey.yaml | 127 ++++++++++ api/identity/v2_store_invite.yaml | 161 +++++++++++++ 7 files changed, 1083 insertions(+) create mode 100644 api/identity/v2_associations.yaml create mode 100644 api/identity/v2_email_associations.yaml create mode 100644 api/identity/v2_invitation_signing.yaml create mode 100644 api/identity/v2_phone_associations.yaml create mode 100644 api/identity/v2_ping.yaml create mode 100644 api/identity/v2_pubkey.yaml create mode 100644 api/identity/v2_store_invite.yaml diff --git a/api/identity/v2_associations.yaml b/api/identity/v2_associations.yaml new file mode 100644 index 00000000..247e1b4c --- /dev/null +++ b/api/identity/v2_associations.yaml @@ -0,0 +1,300 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Establishing Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/3pid/getValidated3pid": + get: + summary: Check whether ownership of a 3pid was validated. + description: |- + Determines if a given 3pid has been validated by a user. + operationId: getValidated3pid + parameters: + - in: query + type: string + name: sid + description: The Session ID generated by the ``requestToken`` call. + required: true + x-example: 1234 + - in: query + type: string + name: client_secret + description: The client secret passed to the ``requestToken`` call. + required: true + x-example: monkeys_are_GREAT + responses: + 200: + description: Validation information for the session. + examples: + application/json: { + "medium": "email", + "validated_at": 1457622739026, + "address": "louise@bobs.burgers" + } + schema: + type: object + properties: + medium: + type: string + description: The medium type of the 3pid. + address: + type: string + description: The address of the 3pid being looked up. + validated_at: + type: integer + description: |- + Timestamp, in milliseconds, indicating the time that the 3pid + was validated. + required: ['medium', 'address', 'validated_at'] + 400: + description: |- + The session has not been validated. + + If the session has not been validated, then ``errcode`` will be + ``M_SESSION_NOT_VALIDATED``. If the session has timed out, then + ``errcode`` will be ``M_SESSION_EXPIRED``. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: The Session ID or client secret were not found. + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/3pid/bind": + post: + summary: Publish an association between a session and a Matrix user ID. + description: |- + Publish an association between a session and a Matrix user ID. + + Future calls to ``/lookup`` for any of the session\'s 3pids will return + this association. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: bind + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:matrix.org" + } + properties: + sid: + type: string + description: The Session ID generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret passed to the ``requestToken`` call. + mxid: + type: string + description: The Matrix user ID to associate with the 3pids. + required: ["sid", "client_secret", "mxid"] + responses: + 200: + description: The association was published. + examples: + application/json: { + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" + } + } + } + schema: + type: object + properties: + address: + type: string + description: The 3pid address of the user being looked up. + medium: + type: string + description: The medium type of the 3pid. + mxid: + type: string + description: The Matrix user ID associated with the 3pid. + not_before: + type: integer + description: A unix timestamp before which the association is not known to be valid. + not_after: + type: integer + description: A unix timestamp after which the association is not known to be valid. + ts: + type: integer + description: The unix timestamp at which the association was verified. + signatures: + type: object + description: |- + The signatures of the verifying identity servers which show that the + association should be trusted, if you trust the verifying identity + services. + $ref: "../../schemas/server-signatures.yaml" + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures + 400: + description: |- + The association was not published. + + If the session has not been validated, then ``errcode`` will be + ``M_SESSION_NOT_VALIDATED``. If the session has timed out, then + ``errcode`` will be ``M_SESSION_EXPIRED``. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 404: + description: The Session ID or client secret were not found + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/3pid/unbind": + post: + summary: Remove an association between a session and a Matrix user ID. + description: |- + Remove an association between a session and a Matrix user ID. + + Future calls to ``/lookup`` for any of the session's 3pids will not + return the removed association. + + The identity server should authenticate the request in one of two + ways: + + 1. The request is signed by the homeserver which controls the ``user_id``. + 2. The request includes the ``sid`` and ``client_secret`` parameters, + as per ``/3pid/bind``, which proves ownership of the 3PID. + + If this endpoint returns a JSON Matrix error, that error should be passed + through to the client requesting an unbind through a homeserver, if the + homeserver is acting on behalf of a client. + operationId: unbind + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:example.org", + "threepid": { + "medium": "email", + "address": "monkeys_have_ears@example.org" + } + } + properties: + sid: + type: string + description: The Session ID generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret passed to the ``requestToken`` call. + mxid: + type: string + description: The Matrix user ID to remove from the 3pids. + threepid: + type: object + title: 3PID + description: |- + The 3PID to remove. Must match the 3PID used to generate the session + if using ``sid`` and ``client_secret`` to authenticate this request. + properties: + medium: + type: string + description: |- + A medium from the `3PID Types`_ Appendix, matching the medium + of the identifier to unbind. + address: + type: string + description: The 3PID address to remove. + required: ['medium', 'address'] + required: ["threepid", "mxid"] + responses: + 200: + description: The association was successfully removed. + examples: + application/json: {} + schema: + type: object + 400: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 404: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + 403: + description: |- + The credentials supplied to authenticate the request were invalid. + This may also be returned if the identity server does not support + the chosen authentication method (such as blocking homeservers from + unbinding identifiers). + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "Invalid homeserver signature" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + 501: + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. diff --git a/api/identity/v2_email_associations.yaml b/api/identity/v2_email_associations.yaml new file mode 100644 index 00000000..9911bc5d --- /dev/null +++ b/api/identity/v2_email_associations.yaml @@ -0,0 +1,175 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Email Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/validate/email/requestToken": + post: + summary: Request a token for validating an email address. + description: |- + Create a session for validating an email address. + + The identity server will send an email containing a token. If that + token is presented to the identity server in the future, it indicates + that that user was able to read the email for that email address, and + so we validate ownership of the email address. + + Note that homeservers offer APIs that proxy this API, adding + additional behaviour on top, for example, + ``/register/email/requestToken`` is designed specifically for use when + registering an account and therefore will inform the user if the email + address given is already registered on the server. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: emailRequestToken + parameters: + - in: body + name: body + schema: + $ref: "definitions/request_email_validation.yaml" + responses: + 200: + description: Session created. + schema: + $ref: "definitions/sid.yaml" + 400: + description: | + An error ocurred. Some possible errors are: + + - ``M_INVALID_EMAIL``: The email address provided was invalid. + - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent. + examples: + application/json: { + "errcode": "M_INVALID_EMAIL", + "error": "The email address is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/validate/email/submitToken": + post: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + associate the email address with any Matrix user ID. Specifically, + calls to ``/lookup`` will not show a binding. + + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: emailSubmitTokenPost + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret that was supplied to the ``requestToken`` call. + token: + type: string + description: The token generated by the ``requestToken`` call and emailed to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: ['success'] + get: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + associate the email address with any Matrix user ID. Specifically, + calls to ``/lookup`` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: emailSubmitTokenGet + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the ``requestToken`` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the ``requestToken`` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the ``requestToken`` call and emailed to the user. + x-example: atoken + responses: + "200": + description: Email address is validated. + "3xx": + description: |- + Email address is validated, and the ``next_link`` parameter was + provided to the ``requestToken`` call. The user must be redirected + to the URL provided by the ``next_link`` parameter. + "4xx": + description: + Validation failed. diff --git a/api/identity/v2_invitation_signing.yaml b/api/identity/v2_invitation_signing.yaml new file mode 100644 index 00000000..f2d2933d --- /dev/null +++ b/api/identity/v2_invitation_signing.yaml @@ -0,0 +1,97 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Ephemeral Invitation Signing API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/sign-ed25519": + post: + summary: Sign invitation details + description: |- + Sign invitation details. + + The identity server will look up ``token`` which was stored in a call + to ``store-invite``, and fetch the sender of the invite. + operationId: blindlySignStuff + parameters: + - in: body + name: body + schema: + type: object + example: { + "mxid": "@foo:bar.com", + "token": "sometoken", + "private_key": "base64encodedkey" + } + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + token: + type: string + description: The token from the call to ``store-invite``. + private_key: + type: string + description: The private key, encoded as `Unpadded base64`_. + required: ["mxid", "token", "private_key"] + responses: + 200: + description: The signed JSON of the mxid, sender, and token. + schema: + type: object + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + sender: + type: string + description: The Matrix user ID of the user who sent the invitation. + signatures: + type: object + description: The signature of the mxid, sender, and token. + $ref: "../../schemas/server-signatures.yaml" + token: + type: string + description: The token for the invitation. + required: ['mxid', 'sender', 'signatures', 'token'] + examples: + application/json: { + "mxid": "@foo:bar.com", + "sender": "@baz:bar.com", + "signatures": { + "my.id.server": { + "ed25519:0": "def987" + } + }, + "token": "abc123" + } + 404: + description: The token was not found. + examples: + application/json: { + "errcode": "M_UNRECOGNIZED", + "error": "Didn't recognize token" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" diff --git a/api/identity/v2_phone_associations.yaml b/api/identity/v2_phone_associations.yaml new file mode 100644 index 00000000..8d0da628 --- /dev/null +++ b/api/identity/v2_phone_associations.yaml @@ -0,0 +1,177 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Phone Number Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/validate/msisdn/requestToken": + post: + summary: Request a token for validating a phone number. + description: |- + Create a session for validating a phone number. + + The identity server will send an SMS message containing a token. If + that token is presented to the identity server in the future, it + indicates that that user was able to read the SMS for that phone + number, and so we validate ownership of the phone number. + + Note that homeservers offer APIs that proxy this API, adding + additional behaviour on top, for example, + ``/register/msisdn/requestToken`` is designed specifically for use when + registering an account and therefore will inform the user if the phone + number given is already registered on the server. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: msisdnRequestToken + parameters: + - in: body + name: body + schema: + $ref: "definitions/request_msisdn_validation.yaml" + responses: + 200: + description: Session created. + schema: + $ref: "definitions/sid.yaml" + 400: + description: | + An error ocurred. Some possible errors are: + + - ``M_INVALID_ADDRESS``: The phone number provided was invalid. + - ``M_SEND_ERROR``: The validation SMS could not be sent. + - ``M_DESTINATION_REJECTED``: The identity server cannot deliver an + SMS to the provided country or region. + examples: + application/json: { + "errcode": "M_INVALID_ADDRESS", + "error": "The phone number is not valid" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/validate/msisdn/submitToken": + post: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the phone number is considered to + have been validated. This does not publish any information publicly, or + associate the phone number address with any Matrix user + ID. Specifically, calls to ``/lookup`` will not show a binding. + + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + + Note: for backwards compatibility with previous drafts of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: msisdnSubmitTokenPost + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret that was supplied to the ``requestToken`` call. + token: + type: string + description: The token generated by the ``requestToken`` call and sent to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: ['success'] + get: + summary: Validate ownership of a phone number. + description: |- + Validate ownership of a phone number. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the phone number address is + considered to have been validated. This does not publish any + information publicly, or associate the phone number with any Matrix + user ID. Specifically, calls to ``/lookup`` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: msisdnSubmitTokenGet + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the ``requestToken`` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the ``requestToken`` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the ``requestToken`` call and sent to the user. + x-example: atoken + responses: + "200": + description: Phone number is validated. + "3xx": + description: |- + Phone number address is validated, and the ``next_link`` parameter + was provided to the ``requestToken`` call. The user must be + redirected to the URL provided by the ``next_link`` parameter. + "4xx": + description: + Validation failed. diff --git a/api/identity/v2_ping.yaml b/api/identity/v2_ping.yaml new file mode 100644 index 00000000..fd81c7c3 --- /dev/null +++ b/api/identity/v2_ping.yaml @@ -0,0 +1,46 @@ +# Copyright 2018 Kamax Sàrl +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +swagger: "2.0" +info: + title: "Matrix Identity Service Ping API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity +produces: + - application/json +paths: + "/api/v1": + get: + summary: Checks that an identity server is available at this API endpoint. + description: |- + Checks that an identity server is available at this API endpoint. + + To discover that an identity server is available at a specific URL, + this endpoint can be queried and will return an empty object. + + This is primarly used for auto-discovery and health check purposes + by entities acting as a client for the identity server. + operationId: ping + responses: + 200: + description: An identity server is ready to serve requests. + examples: + application/json: {} + schema: + type: object diff --git a/api/identity/v2_pubkey.yaml b/api/identity/v2_pubkey.yaml new file mode 100644 index 00000000..48446ace --- /dev/null +++ b/api/identity/v2_pubkey.yaml @@ -0,0 +1,127 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Public Key API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/pubkey/{keyId}": + get: + summary: Get a public key. + description: |- + Get the public key for the passed key ID. + operationId: getPubKey + parameters: + - in: path + type: string + name: keyId + required: true + description: |- + The ID of the key. This should take the form algorithm:identifier + where algorithm identifies the signing algorithm, and the identifier + is an opaque string. + x-example: "ed25519:0" + responses: + 200: + description: + The public key exists. + examples: + application/json: { + "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + } + schema: + type: object + properties: + public_key: + type: string + description: Unpadded Base64 encoded public key. + required: ['public_key'] + 404: + description: + The public key was not found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "The public key was not found" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" + "/pubkey/isvalid": + get: + summary: Check whether a long-term public key is valid. + description: |- + Check whether a long-term public key is valid. The response should always + be the same, provided the key exists. + operationId: isPubKeyValid + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: ['valid'] + "/pubkey/ephemeral/isvalid": + get: + summary: Check whether a short-term public key is valid. + description: |- + Check whether a short-term public key is valid. + operationId: isEphemeralPubKeyValid + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: ['valid'] diff --git a/api/identity/v2_store_invite.yaml b/api/identity/v2_store_invite.yaml new file mode 100644 index 00000000..802478dc --- /dev/null +++ b/api/identity/v2_store_invite.yaml @@ -0,0 +1,161 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2019 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Identity Service Store Invitations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https +basePath: /_matrix/identity/api/v1 +consumes: + - application/json +produces: + - application/json +paths: + "/store-invite": + post: + summary: Store pending invitations to a user's 3pid. + description: |- + Store pending invitations to a user's 3pid. + + In addition to the request parameters specified below, an arbitrary + number of other parameters may also be specified. These may be used in + the invite message generation described below. + + The service will generate a random token and an ephemeral key used for + accepting the invite. + + The service also generates a ``display_name`` for the inviter, which is + a redacted version of ``address`` which does not leak the full contents + of the ``address``. + + The service records persistently all of the above information. + + It also generates an email containing all of this data, sent to the + ``address`` parameter, notifying them of the invitation. + + Also, the generated ephemeral public key will be listed as valid on + requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. + + Currently, invites may only be issued for 3pids of the ``email`` medium. + + Optional fields in the request should be populated to the best of the + server's ability. Identity servers may use these variables when notifying + the ``address`` of the pending invite for display purposes. + operationId: storeInvite + parameters: + - in: body + name: body + schema: + type: object + properties: + medium: + type: string + description: The literal string ``email``. + example: "email" + address: + type: string + description: The email address of the invited user. + example: "foo@example.com" + room_id: + type: string + description: The Matrix room ID to which the user is invited + example: "!something:example.org" + sender: + type: string + description: The Matrix user ID of the inviting user + example: "@bob:example.com" + room_alias: + type: string + description: |- + The Matrix room alias for the room to which the user is + invited. This should be retrieved from the ``m.room.canonical_alias`` + state event. + example: "#somewhere:exmaple.org" + room_avatar_url: + type: string + description: |- + The Content URI for the room to which the user is invited. This should + be retrieved from the ``m.room.avatar`` state event. + example: "mxc://example.org/s0meM3dia" + room_join_rules: + type: string + description: |- + The ``join_rule`` for the room to which the user is invited. This should + be retrieved from the ``m.room.join_rules`` state event. + example: "public" + room_name: + type: string + description: |- + The name of the room to which the user is invited. This should be retrieved + from the ``m.room.name`` state event. + example: "Bob's Emporium of Messages" + sender_display_name: + type: string + description: The display name of the user ID initiating the invite. + example: "Bob Smith" + sender_avatar_url: + type: string + description: The Content URI for the avatar of the user ID initiating the invite. + example: "mxc://example.org/an0th3rM3dia" + required: ["medium", "address", "room_id", "sender"] + responses: + 200: + description: The invitation was stored. + schema: + type: object + properties: + token: + type: string + description: | + The generated token. Must be a string consisting of the + characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed + 255 characters and it must not be empty. + public_keys: + type: array + description: | + A list of [server's long-term public key, generated ephemeral + public key]. + items: + type: string + display_name: + type: string + description: The generated (redacted) display_name. + required: ['token', 'public_keys', 'display_name'] + example: + application/json: { + "token": "sometoken", + "public_keys": [ + "serverpublickey", + "ephemeralpublickey" + ], + "display_name": "f...@b..." + } + 400: + description: | + An error has occured. + + If the 3pid is already bound to a Matrix user ID, the error code + will be ``M_THREEPID_IN_USE``. If the medium is unsupported, the + error code will be ``M_UNRECOGNIZED``. + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "Binding already known", + "mxid": "@alice:example.com" + } + schema: + $ref: "../client-server/definitions/errors/error.yaml" From a47c5aeb426eb5c5be7c50dbdd7c82418e839484 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 28 Aug 2019 14:17:51 -0600 Subject: [PATCH 490/497] v2-ify the v2 api Note that ping and pubkey doesn't require auth - see MSC2140 for more information. --- api/identity/v2_associations.yaml | 18 +++++++++++++----- api/identity/v2_email_associations.yaml | 18 +++++++++++++----- api/identity/v2_invitation_signing.yaml | 10 +++++++--- api/identity/v2_phone_associations.yaml | 18 +++++++++++++----- api/identity/v2_ping.yaml | 6 +++--- api/identity/v2_pubkey.yaml | 10 +++++----- api/identity/v2_store_invite.yaml | 12 ++++++++---- 7 files changed, 62 insertions(+), 30 deletions(-) diff --git a/api/identity/v2_associations.yaml b/api/identity/v2_associations.yaml index 247e1b4c..d1b29a8f 100644 --- a/api/identity/v2_associations.yaml +++ b/api/identity/v2_associations.yaml @@ -15,22 +15,26 @@ swagger: '2.0' info: title: "Matrix Identity Service Establishing Associations API" - version: "1.0.0" + version: "2.0.0" host: localhost:8090 schemes: - https -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/v2 consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/3pid/getValidated3pid": get: summary: Check whether ownership of a 3pid was validated. description: |- Determines if a given 3pid has been validated by a user. - operationId: getValidated3pid + operationId: getValidated3pidV2 + security: + - accessToken: [] parameters: - in: query type: string @@ -104,7 +108,9 @@ paths: specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. - operationId: bind + operationId: bindV2 + security: + - accessToken: [] parameters: - in: body name: body @@ -221,7 +227,9 @@ paths: If this endpoint returns a JSON Matrix error, that error should be passed through to the client requesting an unbind through a homeserver, if the homeserver is acting on behalf of a client. - operationId: unbind + operationId: unbindV2 + security: + - accessToken: [] parameters: - in: body name: body diff --git a/api/identity/v2_email_associations.yaml b/api/identity/v2_email_associations.yaml index 9911bc5d..eff18eaf 100644 --- a/api/identity/v2_email_associations.yaml +++ b/api/identity/v2_email_associations.yaml @@ -15,15 +15,17 @@ swagger: '2.0' info: title: "Matrix Identity Service Email Associations API" - version: "1.0.0" + version: "2.0.0" host: localhost:8090 schemes: - https -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/v2 consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/validate/email/requestToken": post: @@ -46,7 +48,9 @@ paths: specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. - operationId: emailRequestToken + operationId: emailRequestTokenV2 + security: + - accessToken: [] parameters: - in: body name: body @@ -92,7 +96,9 @@ paths: specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. - operationId: emailSubmitTokenPost + operationId: emailSubmitTokenPostV2 + security: + - accessToken: [] parameters: - in: body name: body @@ -142,7 +148,9 @@ paths: Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. - operationId: emailSubmitTokenGet + operationId: emailSubmitTokenGetV2 + security: + - accessToken: [] parameters: - in: query type: string diff --git a/api/identity/v2_invitation_signing.yaml b/api/identity/v2_invitation_signing.yaml index f2d2933d..c1267bdc 100644 --- a/api/identity/v2_invitation_signing.yaml +++ b/api/identity/v2_invitation_signing.yaml @@ -15,15 +15,17 @@ swagger: '2.0' info: title: "Matrix Identity Service Ephemeral Invitation Signing API" - version: "1.0.0" + version: "2.0.0" host: localhost:8090 schemes: - https -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/v2 consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/sign-ed25519": post: @@ -33,7 +35,9 @@ paths: The identity server will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. - operationId: blindlySignStuff + operationId: blindlySignStuffV2 + security: + - accessToken: [] parameters: - in: body name: body diff --git a/api/identity/v2_phone_associations.yaml b/api/identity/v2_phone_associations.yaml index 8d0da628..cfaea410 100644 --- a/api/identity/v2_phone_associations.yaml +++ b/api/identity/v2_phone_associations.yaml @@ -15,15 +15,17 @@ swagger: '2.0' info: title: "Matrix Identity Service Phone Number Associations API" - version: "1.0.0" + version: "2.0.0" host: localhost:8090 schemes: - https -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/v2 consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/validate/msisdn/requestToken": post: @@ -46,7 +48,9 @@ paths: specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. - operationId: msisdnRequestToken + operationId: msisdnRequestTokenV2 + security: + - accessToken: [] parameters: - in: body name: body @@ -94,7 +98,9 @@ paths: specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. - operationId: msisdnSubmitTokenPost + operationId: msisdnSubmitTokenPostV2 + security: + - accessToken: [] parameters: - in: body name: body @@ -144,7 +150,9 @@ paths: Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. - operationId: msisdnSubmitTokenGet + operationId: msisdnSubmitTokenGetV2 + security: + - accessToken: [] parameters: - in: query type: string diff --git a/api/identity/v2_ping.yaml b/api/identity/v2_ping.yaml index fd81c7c3..61f5d35b 100644 --- a/api/identity/v2_ping.yaml +++ b/api/identity/v2_ping.yaml @@ -17,7 +17,7 @@ swagger: "2.0" info: title: "Matrix Identity Service Ping API" - version: "1.0.0" + version: "2.0.0" host: localhost:8090 schemes: - https @@ -25,7 +25,7 @@ basePath: /_matrix/identity produces: - application/json paths: - "/api/v1": + "/v2": get: summary: Checks that an identity server is available at this API endpoint. description: |- @@ -36,7 +36,7 @@ paths: This is primarly used for auto-discovery and health check purposes by entities acting as a client for the identity server. - operationId: ping + operationId: pingV2 responses: 200: description: An identity server is ready to serve requests. diff --git a/api/identity/v2_pubkey.yaml b/api/identity/v2_pubkey.yaml index 48446ace..68facd68 100644 --- a/api/identity/v2_pubkey.yaml +++ b/api/identity/v2_pubkey.yaml @@ -15,11 +15,11 @@ swagger: '2.0' info: title: "Matrix Identity Service Public Key API" - version: "1.0.0" + version: "2.0.0" host: localhost:8090 schemes: - https -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/v2 consumes: - application/json produces: @@ -30,7 +30,7 @@ paths: summary: Get a public key. description: |- Get the public key for the passed key ID. - operationId: getPubKey + operationId: getPubKeyV2 parameters: - in: path type: string @@ -72,7 +72,7 @@ paths: description: |- Check whether a long-term public key is valid. The response should always be the same, provided the key exists. - operationId: isPubKeyValid + operationId: isPubKeyValidV2 parameters: - in: query type: string @@ -101,7 +101,7 @@ paths: summary: Check whether a short-term public key is valid. description: |- Check whether a short-term public key is valid. - operationId: isEphemeralPubKeyValid + operationId: isEphemeralPubKeyValidV2 parameters: - in: query type: string diff --git a/api/identity/v2_store_invite.yaml b/api/identity/v2_store_invite.yaml index 802478dc..afc41a1c 100644 --- a/api/identity/v2_store_invite.yaml +++ b/api/identity/v2_store_invite.yaml @@ -15,15 +15,17 @@ swagger: '2.0' info: title: "Matrix Identity Service Store Invitations API" - version: "1.0.0" + version: "2.0.0" host: localhost:8090 schemes: - https -basePath: /_matrix/identity/api/v1 +basePath: /_matrix/identity/v2 consumes: - application/json produces: - application/json +securityDefinitions: + $ref: definitions/security.yaml paths: "/store-invite": post: @@ -48,14 +50,16 @@ paths: ``address`` parameter, notifying them of the invitation. Also, the generated ephemeral public key will be listed as valid on - requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. + requests to ``/_matrix/identity/v2/pubkey/ephemeral/isvalid``. Currently, invites may only be issued for 3pids of the ``email`` medium. Optional fields in the request should be populated to the best of the server's ability. Identity servers may use these variables when notifying the ``address`` of the pending invite for display purposes. - operationId: storeInvite + operationId: storeInviteV2 + security: + - accessToken: [] parameters: - in: body name: body From b0acaeddfadb5e7753201e9e0f79dab581b7a3f6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 28 Aug 2019 14:18:11 -0600 Subject: [PATCH 491/497] Reference the v2 API where possible --- specification/identity_service_api.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 89604644..f8211f70 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -57,6 +57,8 @@ The following other versions are also available, in reverse chronological order: General principles ------------------ +.. TODO: TravisR - Define auth for IS v2 API in a future PR + The purpose of an identity server is to validate, store, and answer questions about the identities of users. In particular, it stores associations of the form "identifier X represents the same user as identifier Y", where identities may @@ -176,6 +178,8 @@ Status check {{ping_is_http_api}} +{{v2_ping_is_http_api}} + Key management -------------- @@ -195,11 +199,15 @@ service's long-term keys. {{pubkey_is_http_api}} +{{v2_pubkey_is_http_api}} + Association lookup ------------------ {{lookup_is_http_api}} +.. TODO: TravisR - Add v2 lookup API in future PR + Establishing associations ------------------------- @@ -243,16 +251,22 @@ Email associations {{email_associations_is_http_api}} +{{v2_email_associations_is_http_api}} + Phone number associations ~~~~~~~~~~~~~~~~~~~~~~~~~ {{phone_associations_is_http_api}} +{{v2_phone_associations_is_http_api}} + General ~~~~~~~ {{associations_is_http_api}} +{{v2_associations_is_http_api}} + Invitation storage ------------------ @@ -267,6 +281,8 @@ long-term private key for the identity server. {{store_invite_is_http_api}} +{{v2_store_invite_is_http_api}} + Ephemeral invitation signing ---------------------------- @@ -277,6 +293,8 @@ this isn't possible. {{invitation_signing_is_http_api}} +{{v2_invitation_signing_is_http_api}} + .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types .. _`Signing JSON`: ../appendices.html#signing-json From ca4d9d8636a883cfdf122e3df41562786ff823ef Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 28 Aug 2019 14:19:13 -0600 Subject: [PATCH 492/497] Deprecate the v1 IS API --- api/identity/associations.yaml | 3 +++ api/identity/email_associations.yaml | 3 +++ api/identity/invitation_signing.yaml | 1 + api/identity/lookup.yaml | 2 ++ api/identity/phone_associations.yaml | 3 +++ api/identity/ping.yaml | 1 + api/identity/pubkey.yaml | 3 +++ api/identity/store_invite.yaml | 1 + 8 files changed, 17 insertions(+) diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index 8ff4a9ed..82c70fb8 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -30,6 +30,7 @@ paths: description: |- Determines if a given 3pid has been validated by a user. operationId: getValidated3pid + deprecated: true parameters: - in: query type: string @@ -104,6 +105,7 @@ paths: ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. operationId: bind + deprecated: true parameters: - in: body name: body @@ -221,6 +223,7 @@ paths: through to the client requesting an unbind through a homeserver, if the homeserver is acting on behalf of a client. operationId: unbind + deprecated: true parameters: - in: body name: body diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 38186432..6ac28cd0 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -46,6 +46,7 @@ paths: ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. operationId: emailRequestToken + deprecated: true parameters: - in: body name: body @@ -92,6 +93,7 @@ paths: ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. operationId: emailSubmitTokenPost + deprecated: true parameters: - in: body name: body @@ -142,6 +144,7 @@ paths: Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. operationId: emailSubmitTokenGet + deprecated: true parameters: - in: query type: string diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 4e10e2b5..e2ac28b0 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -33,6 +33,7 @@ paths: The identity server will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. operationId: blindlySignStuff + deprecated: true parameters: - in: body name: body diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index fd50f94b..166b0962 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -32,6 +32,7 @@ paths: summary: Look up the Matrix user ID for a 3pid. description: Look up the Matrix user ID for a 3pid. operationId: lookupUser + deprecated: true parameters: - in: query type: string @@ -101,6 +102,7 @@ paths: summary: Lookup Matrix user IDs for a list of 3pids. description: Lookup Matrix user IDs for a list of 3pids. operationId: lookupUsers + deprecated: true parameters: - in: body name: body diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index b9933f1a..28312a4d 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -46,6 +46,7 @@ paths: ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. operationId: msisdnRequestToken + deprecated: true parameters: - in: body name: body @@ -94,6 +95,7 @@ paths: ``application/x-form-www-urlencoded`` data. However, this usage is deprecated. operationId: msisdnSubmitTokenPost + deprecated: true parameters: - in: body name: body @@ -144,6 +146,7 @@ paths: Note that, in contrast with the POST version, this endpoint will be used by end-users, and so the response should be human-readable. operationId: msisdnSubmitTokenGet + deprecated: true parameters: - in: query type: string diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index 05e12a87..d7249a77 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -36,6 +36,7 @@ paths: This is primarly used for auto-discovery and health check purposes by entities acting as a client for the identity server. operationId: ping + deprecated: true responses: 200: description: An identity server is ready to serve requests. diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index e657c61c..a585e7ec 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -30,6 +30,7 @@ paths: description: |- Get the public key for the passed key ID. operationId: getPubKey + deprecated: true parameters: - in: path type: string @@ -72,6 +73,7 @@ paths: Check whether a long-term public key is valid. The response should always be the same, provided the key exists. operationId: isPubKeyValid + deprecated: true parameters: - in: query type: string @@ -101,6 +103,7 @@ paths: description: |- Check whether a short-term public key is valid. operationId: isEphemeralPubKeyValid + deprecated: true parameters: - in: query type: string diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index bca78d7e..4a5d525d 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -55,6 +55,7 @@ paths: server's ability. Identity servers may use these variables when notifying the ``address`` of the pending invite for display purposes. operationId: storeInvite + deprecated: true parameters: - in: body name: body From 62cc11eee658ead69eb18cad153193a4082daa1f Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 30 Aug 2019 13:49:54 +0100 Subject: [PATCH 493/497] add missing github-labels file --- README.rst | 2 +- meta/github-labels.rst | 91 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 meta/github-labels.rst diff --git a/README.rst b/README.rst index b8847bfb..ace8ebdd 100644 --- a/README.rst +++ b/README.rst @@ -138,4 +138,4 @@ Issue tracking Issues with the Matrix specification are tracked in `GitHub `_. -See `meta/labels.rst `_ for notes on what the labels mean. +See `meta/github-labels.rst `_ for notes on what the labels mean. diff --git a/meta/github-labels.rst b/meta/github-labels.rst new file mode 100644 index 00000000..f674b81b --- /dev/null +++ b/meta/github-labels.rst @@ -0,0 +1,91 @@ +The following labels are used to help categorize issues: + +`spec-omission `_ +-------------------------------------------------------------------------------- + +Things which have been implemented but not currently specified. These may range +from entire API endpoints, to particular options or return parameters. + +Issues with this label will have been implemented in `Synapse +`_. Normally there will be a design +document in Google Docs or similar which describes the feature. + +Examples: + +* `Spec PUT /directory/list `_ +* `Unspec'd server_name request param for /join/{roomIdOrAlias} + `_ + +`clarification `_ +-------------------------------------------------------------------------------- + +An area where the spec could do with being more explicit. + +Examples: + +* `Spec the implicit limit on /syncs + `_ + +* `Clarify the meaning of the currently_active flags in presence events + `_ + +`spec-bug `_ +---------------------------------------------------------------------- + +Something which is in the spec, but is wrong. + +Note: this is *not* for things that are badly designed or don't work well +(for which see 'improvement' or 'feature') - it is for places where the +spec doesn't match reality. + +Examples: + +* `swagger is wrong for directory PUT + `_ + +* `receipts section still refers to initialSync + `_ + +`improvement `_ +---------------------------------------------------------------------------- + +A suggestion for a relatively simple improvement to the protocol. + +Examples: + +* `We need a 'remove 3PID' API so that users can remove mappings + `_ +* `We should mandate that /publicRooms requires an access_token + `_ + +`feature `_ +-------------------------------------------------------------------- + +A suggestion for a significant extension to the matrix protocol which +needs considerable consideration before implementation. + +Examples: + +* `Peer-to-peer Matrix `_ +* `Specify a means for clients to "edit" previous messages + `_ + + +`wart `_ +-------------------------------------------------------------- + +A point where the protocol is inconsistent or inelegant, but which isn't really +causing anybody any problems right now. Might be nice to consider fixing one +day. + + +`question `_ +---------------------------------------------------------------------- + +A thought or idea about the protocol which we aren't really sure whether to +pursue or not. + +Examples: + +* `Should we prepend anti-eval code to our json responses? + `_ From 5acac5a44e0d4fb04010ed166069e96fc369c3e9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 30 Aug 2019 09:12:02 -0600 Subject: [PATCH 494/497] Try bumping golang version --- .circleci/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 659380b0..b37478bf 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -97,7 +97,7 @@ jobs: command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL build-dev-scripts: docker: - - image: golang:1.8 + - image: golang:1.10 steps: - checkout - run: From 6d71a41e225f1f0cc227e3528c917f6042d4f148 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 31 Aug 2019 16:01:04 +0100 Subject: [PATCH 495/497] Proposal for ignoring invites --- proposals/2270-ignore-invites.md | 47 ++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 proposals/2270-ignore-invites.md diff --git a/proposals/2270-ignore-invites.md b/proposals/2270-ignore-invites.md new file mode 100644 index 00000000..c6e51e70 --- /dev/null +++ b/proposals/2270-ignore-invites.md @@ -0,0 +1,47 @@ +# Proposal for ignoring invites + +## Problem + +There is currently no way to ignore an invite in Matrix without explicitly +rejecting it and informing the inviter of the rejection. There are many social +situations where a user may want to silently ignore the invite instead. + +The closest you can currently get is to ignore the user who sent the invite - +but this will then ignore all activity from that user, which may not be +desirable. + +## Solution + +Currently we support ignoring users by maintaining an `m.ignored_user_list` event in +account_data, as per https://matrix.org/docs/spec/client_server/r0.5.0#id189. + +We could do also silently ignore rooms (including invites) with an equivalent +`m.ignored_room_list` event, with precisely the same semantics but listing +room IDs rather than user IDs. + +## Tradeoffs + + * We're limited to ~65KB worth of room IDs (although we could change the + limits for account_data 'events', given they're more freeform JSON than + events) + * We waste initial sync bandwidth with account_data info for ignored rooms + which we may never care about ever again. + * The list will grow unbounded over time (unless the user occasionally + unignores and explicitly rejects the invites), especially if invite spam + accelerates. + * We could instead have a dedicated API for this: + * `PUT /user/{userId}/ignore/{txnId}` + * `PUT /rooms/{roomId}/ignore/{txnId}` + * `GET /user/{userId}/ignore` + * `GET /rooms/{roomId}/ignore` + * `GET /ignore` (for querying the current lists) + * ...and a custom block in `/sync` responses to synchronise ignore changes + * ...except it feels that yet another custom API & custom response block + is even more complicated and clunky than making account_data a bit more + flexible. + * Alternatively, we could extend `/leave` with a `silent` parameter of some kind, + and rely on the invitee's HS to track these 'silent' leaves and ignore the + room on behalf of the invitee. However, it may be nice to let the user track + ignored invites cross-client so they can undo if necessary, which account_data + gives us for free. Plus semantically it seems a bit wrong to use `/leave` + to describe the act of ignoring an invite, when you're not actually leaving it. \ No newline at end of file From a805d2b77961816f6f15ce0a44ee3dfde838fb37 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 31 Aug 2019 16:04:55 +0100 Subject: [PATCH 496/497] oops, premature merge --- proposals/2270-ignore-invites.md | 47 -------------------------------- 1 file changed, 47 deletions(-) delete mode 100644 proposals/2270-ignore-invites.md diff --git a/proposals/2270-ignore-invites.md b/proposals/2270-ignore-invites.md deleted file mode 100644 index c6e51e70..00000000 --- a/proposals/2270-ignore-invites.md +++ /dev/null @@ -1,47 +0,0 @@ -# Proposal for ignoring invites - -## Problem - -There is currently no way to ignore an invite in Matrix without explicitly -rejecting it and informing the inviter of the rejection. There are many social -situations where a user may want to silently ignore the invite instead. - -The closest you can currently get is to ignore the user who sent the invite - -but this will then ignore all activity from that user, which may not be -desirable. - -## Solution - -Currently we support ignoring users by maintaining an `m.ignored_user_list` event in -account_data, as per https://matrix.org/docs/spec/client_server/r0.5.0#id189. - -We could do also silently ignore rooms (including invites) with an equivalent -`m.ignored_room_list` event, with precisely the same semantics but listing -room IDs rather than user IDs. - -## Tradeoffs - - * We're limited to ~65KB worth of room IDs (although we could change the - limits for account_data 'events', given they're more freeform JSON than - events) - * We waste initial sync bandwidth with account_data info for ignored rooms - which we may never care about ever again. - * The list will grow unbounded over time (unless the user occasionally - unignores and explicitly rejects the invites), especially if invite spam - accelerates. - * We could instead have a dedicated API for this: - * `PUT /user/{userId}/ignore/{txnId}` - * `PUT /rooms/{roomId}/ignore/{txnId}` - * `GET /user/{userId}/ignore` - * `GET /rooms/{roomId}/ignore` - * `GET /ignore` (for querying the current lists) - * ...and a custom block in `/sync` responses to synchronise ignore changes - * ...except it feels that yet another custom API & custom response block - is even more complicated and clunky than making account_data a bit more - flexible. - * Alternatively, we could extend `/leave` with a `silent` parameter of some kind, - and rely on the invitee's HS to track these 'silent' leaves and ignore the - room on behalf of the invitee. However, it may be nice to let the user track - ignored invites cross-client so they can undo if necessary, which account_data - gives us for free. Plus semantically it seems a bit wrong to use `/leave` - to describe the act of ignoring an invite, when you're not actually leaving it. \ No newline at end of file From 1f2acbcf29ecfe4495cf53a7d9f749e9ec0f37c3 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sat, 31 Aug 2019 16:45:53 +0100 Subject: [PATCH 497/497] RST is not MD --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 20cfd48d..de65ba27 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -79,7 +79,7 @@ their proposed changes to the Matrix protocol: * Pragmatism rather than perfection * Proof rather than conjecture -Please see [MSC1779](https://github.com/matrix-org/matrix-doc/blob/matthew/msc1779/proposals/1779-open-governance.md) +Please see `MSC1779 `_ for full details of the project's Guiding Principles. Technical notes