Merge pull request #1 from matrix-org/master

Merge from origin

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+patreon: matrixdotorg
+liberapay: matrixdotorg

.github/PULL_REQUEST_TEMPLATE/ready-proposal.md

@@ -0,0 +1,19 @@
+---
+name: Proposal ready for review
+about: A proposal that is ready for review by the core team and community.
+title: ''
+labels: proposal, proposal-in-review
+assignees: ''
+
+---
+
+<!-- Put your "rendered" link here -->
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] Pull request includes ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
+* [ ] Pull request title and file name include this PR's number as the MSC number.

.github/PULL_REQUEST_TEMPLATE/spec-change.md

@@ -0,0 +1,16 @@
+---
+name: Spec clarification/not a proposal
+about: A change that's not a spec proposal, such as a clarification to the spec itself.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#other-changes)

.github/PULL_REQUEST_TEMPLATE/wip-proposal.md

@@ -0,0 +1,20 @@
+---
+name: WIP Proposal
+about: A proposal that isn't quite ready for formal review yet.
+title: '[WIP] Your Proposal Title'
+labels: proposal
+assignees: ''
+
+---
+
+<!-- Put your "rendered" link here -->
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
+
+* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
+* [ ] A ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
+* [ ] Update the title and file name of your proposal to match this PR's number (after opening).
+* [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get this marked as ready for review, once it is ready for review.

api/client-server/users.yaml

@@ -31,7 +31,7 @@ paths:
     post:
       summary: Searches the user directory.
       description: |-
-        Performs a search for users on the homeserver. The homeserver may
+        Performs a search for users. The homeserver may
         determine which subset of users are searched, however the homeserver
         MUST at a minimum consider the users the requesting user shares a
         room with and those who reside in public rooms (known to the homeserver).

changelogs/client_server/newsfragments/2369.clarification

@@ -0,0 +1 @@
+Minor clarifications to token-based User-Interactive Authentication.

changelogs/client_server/newsfragments/2381.clarification

@@ -0,0 +1 @@
+Minor clarification for what the user directory searches.

proposals/0000-proposal-template.md

@@ -93,3 +93,13 @@ 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.
+
+## Unstable prefix
+
+*If a proposal is implemented before it is included in the spec, then implementers must ensure that the
+implementation is compatible with the final version that lands in the spec. This generally means that
+experimental implementations should use `/unstable` endpoints, and use vendor prefixes where necessary.
+For more information, see [MSC2324](https://github.com/matrix-org/matrix-doc/pull/2324). This section
+should be used to document things such as what endpoints and names are being used while the feature is
+in development, the name of the unstable feature flag to use to detect support for the feature, or what
+migration steps are needed to switch to newer versions of the proposal.*

proposals/1756-cross-signing.md

@@ -216,12 +216,12 @@ response:
 }
 ```
 
-Similarly, the federation endpoints `GET /user/keys/query` and `POST
+Similarly, the federation endpoints `POST /user/keys/query` and `POST
 /user/devices/{userId}` will include the master and self-signing keys.  (It
 will not include the user-signing key because it is not intended to be visible
 to other users.)
 
-`POST /keys/query`
+`POST /user/keys/query`
 
 ``` json
 {
@@ -432,27 +432,31 @@ response:
       }
     }
   },
-  "master_key": {
+  "master_keys": {
-    "user_id": "@alice:example.com",
+    "@alice:example.com": {
-    "usage": ["master"],
+      "user_id": "@alice:example.com",
-    "keys": {
+      "usage": ["master"],
-      "ed25519:base64+master+public+key": "base64+master+public+key"
+      "keys": {
-    },
+        "ed25519:base64+master+public+key": "base64+master+public+key"
-    "signatures": {
+      },
-      "@alice:example.com": {
+      "signatures": {
-        "ed25519:HIJKLMN": "base64+signature+of+master+key"
+        "@alice:example.com": {
+          "ed25519:HIJKLMN": "base64+signature+of+master+key"
+        }
       }
     }
   },
-  "self_signing_key": {
+  "self_signing_keys": {
-    "user_id": "@alice:example.com",
+    "@alice:example.com": {
-    "usage": ["self_signing"],
+      "user_id": "@alice:example.com",
-    "keys": {
+      "usage": ["self_signing"],
-      "ed25519:base64+self+signing+public+key": "base64+self+signing+public+key"
+      "keys": {
-    },
+        "ed25519:base64+self+signing+public+key": "base64+self+signing+public+key"
-    "signatures": {
+      },
-      "@alice:example.com": {
+      "signatures": {
-        "ed25519:base64+master+public+key": "base64+signature"
+        "@alice:example.com": {
+          "ed25519:base64+master+public+key": "base64+signature"
+        }
       }
     }
   }

proposals/2324-when-to-ship.md

@@ -0,0 +1,124 @@
+# MSC2324: Facilitating early releases of software dependent on spec
+
+*Note*: This is a process change MSC, not a change to the spec itself.
+
+There's currently an unanswered question by the spec process: when is it
+safe to start using stable endpoints or to present a feature as "stable"?
+Historically this question would receive very different answers depending
+on who you asked, so in an effort to come up with a concise answer the
+following process change is proposed.
+
+## Proposal
+
+The new process, from start to finish, is proposed as:
+
+1. Have an idea for a feature.
+2. Optionally: implement the feature using unstable endpoints, vendor prefixes,
+   and unstable feature flags as appropriate.
+   * When using unstable endpoints, they MUST include a vendor prefix. For
+     example: `/_matrix/client/unstable/com.example/login`. Vendor prefixes
+     throughout this proposal always use the Java package naming convention.
+   * Unstable endpoints **do not** inherit from stable (`/r0`) APIs. Previously,
+     one could access the entirety of the Matrix API through `/unstable` however
+     this is generally considered a bad practice. Therefore an implementation
+     can no longer assume that because its feature-specific endpoint exists that
+     any other endpoint will exist in the same unstable namespace.
+   * If the client needs to be sure the server supports the feature, an unstable
+     feature flag that MUST be vendor prefixed is to be used. This kind of flag
+     shows up in the `unstable_features` field of `/versions` as, for example,
+     `com.example.new_login`.
+   * You can ship the feature at *any* time, so long as you are able to accept
+     the technical debt that results from needing to provide adequate backwards
+     and forwards compatibility for the vendor prefixed implementation. The
+     implementation MUST support the flag disappearing and be generally safe for
+     users. Note that implementations early in the MSC review process may also be
+     required to provide backwards compatibility with earlier editions of the
+     proposal.
+   * If you don't want to support the technical debt (or if it's impossible to
+     provide adequate backwards/forwards compatibility - e.g. a user authentication
+     change which can't be safely rolled back), do not implement the feature and
+     wait for Step 7.
+   * If at any point the idea changes, the feature flag should also change so
+     that implementations can adapt as needed.
+3. In parallel, or ahead of implementation, open an MSC and solicit review.
+4. Before a FCP (Final Comment Period) can be called, the Spec Core Team will
+   require that evidence to prove the MSC works be presented. A typical example
+   of this is an implementation of the MSC (which does not necessarily need to have been shipped anywhere).
+5. FCP is gone through, and assuming nothing is flagged the MSC lands.
+6. A spec PR is written to incorporate the changes into Matrix.
+7. A spec release happens.
+8. Implementations switch to using stable prefixes (e.g.: `/r0`) if the server
+   supports the specification version released. If the server doesn't advertise
+   the specification version, but does have the feature flag, unstable prefixes
+   should still be used.
+9. A transition period of about 2 months starts immediately after the spec release, before
+   implementations start to loudly encourage other implementations to switch to stable
+   endpoints. For example, the Synapse team should start asking the Riot team to
+   support the stable endpoints (as per Step 8) 2 months after the spec release if they
+   haven't already.
+
+It's worth repeating that this process generally only applies if the implementation
+wants to ship the feature ahead of the spec being available. By doing so, it takes
+on the risk that the spec/MSC may change and it must adapt. If the implementation
+is unable to take on that risk, or simply doesn't mind waiting, it should go through
+the spec process without shipping an unstable implementation.
+
+To help MSCs get incorporated by implementations as stable features, the spec core
+team plans to release the specification more often. How often is undefined and is
+largely a case-by-case basis.
+
+To reiterate:
+
+* Implementations MUST NOT use stable endpoints before the MSC is in the spec. This
+  includes NOT using stable endpoints post-FCP.
+* Implementations CAN ship features that are exposed by default to users before an
+  MSC has been merged to the spec, provided they follow the process above.
+* Implementations SHOULD be wary of the technical debt they are incurring by moving
+  faster than the spec.
+
+To clarify:
+
+* The vendor prefix is chosen by the developer of the feature, using the Java package
+  naming convention. For example, `org.matrix` is the foundation's vendor prefix.
+* The vendor prefixes, unstable feature flags, and unstable endpoints should be included
+  in the MSC so other developers can benefit. The MSC MUST still say what the stable
+  endpoints are to look like.
+
+### Specific examples outside of the client-server API
+
+There are some instances where a change might be made outside of the client-server API,
+which is where much of this proposal is targetted. The general spirit of the process
+should be followed where possible, if implementations decide to work ahead of spec releases.
+
+#### Room versions
+
+When a new room version is needed, implementations MUST use vendor-prefixed versions
+before using the namespace reserved for Matrix (see https://matrix.org/docs/spec/#room-versions).
+A room version is considered released once it is listed as an "available room version" in
+the spec. Often a new room version is accompanied with a server-server API release, but
+doesn't have to be.
+
+#### Server-server / Identity / Push / Appservice API
+
+These APIs don't yet have a `/versions` endpoint or similar. Typically behaviour changes in
+these APIs are introduced with backwards compatibility in mind (try X and if that fails fall
+back to Y) and therefore don't always need a flag to indicate support. If a flag were to
+be required, an `unstable_features` or similar array would need to be exposed somewhere.
+
+#### Changes to request/response parameters
+
+Parameters being added to request/response bodies and query strings MUST be vendor-prefixed
+per the proposed process. For example, a new JSON field might be `{"org.matrix.example": true}`
+with the proposal being for `example` being added. A query string parameter would be prefixed
+the same way: `?org.matrix.example=true`.
+
+If the MSC is simply adding fields to already-versioned endpoints, it does not need to put
+the whole endpoint into the `/unstable` namespace provided the new parameters are prefixed
+appropriately.
+
+#### .well-known and other APIs that can't be versioned
+
+Best effort is appreciated. Typically these endpoints will be receiving minor behavioural
+changes or new fields. New fields should be appropriately prefixed, and behaviour changes
+should be rolled out cautiously by implementations (waiting until after FCP has concluded
+is probably best to ensure there's no major problems with the new behaviour).

proposals/2367-membership-reasons.md

@@ -0,0 +1,81 @@
+# Allowing Reasons in all Membership Events
+
+Currently users can specify a reason for kicking or banning users in a room
+that both the target and other users in a room can see. This is useful to
+explain *why* an action without having to send separate messages.
+
+The proposal extends this to all events, including invites, invite rejections
+and leaves for similar reasons.
+
+## Proposal
+
+Allow `reason` field to be specified for all of the following APIs:
+
+```
+POST /_matrix/client/r0/rooms/{roomId}/invite
+POST /_matrix/client/r0/rooms/{roomId}/leave
+POST /_matrix/client/r0/rooms/{roomId}/kick
+POST /_matrix/client/r0/rooms/{roomId}/ban
+POST /_matrix/client/r0/rooms/{roomId}/unban
+POST /_matrix/client/r0/rooms/{roomId}/join
+POST /_matrix/client/r0/join/{roomIdOrAlias}
+PUT  /_matrix/client/r0/rooms/{roomId}/state/m.room.member/{userID}
+```
+
+If specified the `reason` field will be added to the generated membership
+event's content.
+
+*Note: `/state/m.room.member` API currently allows this as clients can specify
+arbitrary content already*
+
+Clients may choose to display the reason for membership events in a room,
+though may not do so if e.g. they have collapsed a set of membership changes.
+
+Clients should not display an invite reason by default to the invitee as this
+allows a classic abuse and harassment vector. However, clients may wish to show
+invite reasons from known¹ senders, or have a button that allows viewing any
+invite reason.
+
+## Use Cases
+
+Some basic use cases and examples are given below.
+
+### Kick/ban
+
+Kicking and banning already allow specifying a reason to allow giving a reason
+for the moderation action (e.g. "Banned for spamming").
+
+### Leaving a Room
+
+A user may wish to leave a room e.g. because the room is no longer relevant
+to them, allowing them to specify a reason means they can easily step out of
+the room quietly without having to send a message to explain their actions.
+
+### Invite
+
+This can be useful to give some context for an invite, e.g. "Alice invites Bob
+to get some feedback on the membership reasons MSC".
+
+### Rejecting an Invite
+
+If Alice has invited Bob (and many others) to a room to discuss going to a
+concert then Bob may wish to simply reject the invite if he can't make it.
+Adding a "will be out of town" reason to the rejection helps Alice to know why
+her invite was rejected.
+
+### Joining room
+
+Adding a reason for joining could be used e.g. by automated bots to say why
+they're joining. For example a bridge bot may join a room when asked to bridge
+the room to an external network, in which case they may have a reason such as
+"BridgeBot joined to bridge the room to RemoteNetwork at the request of Alice".
+
+## Potential Issues
+
+The main issue here is ensuring that the invite reason cannot be used as an
+abuse vector, however if clients follow the recommendations above this concern
+should be mitigated.
+
+---
+
+¹ This is left up to implementations to decide, if they wish to do so.

specification/client_server_api.rst

@@ -740,22 +740,23 @@ To use this authentication type, clients should submit an auth dict as follows:
     "session": "<session ID>"
   }
 
-The ``nonce`` should be a random string generated by the client for the
-request. The same ``nonce`` should be used if retrying the request.
 
 A client may receive a login ``token`` via some external service, such as email
 or SMS. Note that a login token is separate from an access token, the latter
 providing general authentication to various API endpoints.
 
-The ``txn_id`` may be used by the server to disallow other devices from using
+Additionally, the server must encode the user ID in the ``token``; there is
-the token, thus providing "single use" tokens while still allowing the device
+therefore no need for the client to submit a separate username.
-to retry the request. This would be done by tying the token to the ``txn_id``
+
+The ``txn_id`` should be a random string generated by the client for the
+request. The same ``txn_id`` should be used if retrying the request. The
+``txn_id`` may be used by the server to disallow other devices from using the
+token, thus providing "single use" tokens while still allowing the device to
+retry the request. This would be done by tying the token to the ``txn_id``
 server side, as well as potentially invalidating the token completely once the
 device has successfully logged in (e.g. when we receive a request from the
 newly provisioned access_token).
 
-The server must encode the user id in the ``token``. There is therefore no need
-for the client to submit a separate username.
 
 OAuth2-based
 <<<<<<<<<<<<

specification/rooms/v1.rst

@@ -94,7 +94,7 @@ results of the resolution so far.
   passes authentication in :math:`R` and add it to :math:`R`.
 
 A *conflict* occurs between states where those states have different
-``event_ids`` for the same ``(state_type, state_key)``. The events thus
+``event_ids`` for the same ``(event_type, state_key)``. The events thus
 affected are said to be *conflicting* events.