From 66cc23209185fa693c8367feb0b40990f0138bd2 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 7 Sep 2022 09:21:01 +0100
Subject: [PATCH 01/33] Simple rendezvous capability

---
 .../xxxx-simple-rendezvous-capability.md      | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 proposals/xxxx-simple-rendezvous-capability.md

diff --git a/proposals/xxxx-simple-rendezvous-capability.md b/proposals/xxxx-simple-rendezvous-capability.md
new file mode 100644
index 0000000000..4dbff84975
--- /dev/null
+++ b/proposals/xxxx-simple-rendezvous-capability.md
@@ -0,0 +1,83 @@
+# MSCxxxx: Simple rendezvous capability
+
+In MSCyyyy a proposal is made to allow a user to login on a new device using an existing device by means of scanning a
+QR code.
+
+In order to facilitate this the two devices need some bi-directional communication channel which they can use to exchange
+information such as:
+
+- the homserver being used
+- the user ID
+- facilitation of issuing a new access token
+- device ID for end-to-end encryption
+- device keys for end-to-end encryption
+
+To enable MSCyyyy and support any future proposals this MSC proposes a simple HTTP based protocol that can be used to
+establish a direct communication channel between two IP connected devices.
+
+It will work with devices behind NAT. It doesn't require homeserver administrators to deploy a separate server.
+
+## Proposal
+
+### Protocol
+
+`POST /`
+
+`PUT /<channel id>`
+
+`GET /<channel id>`
+
+`DELETE /<channel id>`
+
+### CORS
+
+### Choice of server
+
+Ultimately it will be up to the Matrix client implementation to decide which rendezvous server to use.
+
+However, it is suggested that the following logic is used by the device/client to choose the rendezvous server in order
+of preference:
+
+1. If the client is already logged in: try and use current homeserver.
+1. If the client is not logged in and it is known which homeserver the user wants to connect to: try and use that homeserver.
+1. Otherwise use a default server.
+
+## Potential issues
+
+Because this is an entirely new set of functionality it should not cause issue with any existing Matrix functions or capabilities.
+
+The proposed protocol requires the devices to have IP connectivity to the server which might not be the case in P2P scenarios.
+
+## Alternatives
+
+Try and do something with STUN or TURN or [COAP](http://coap.technology/).
+
+## Security considerations
+
+### Confidentiality of data
+
+Whilst the data transmitted can be encrypted in transit via HTTP/TLS the rendezvous server does have visibility over the
+data.
+
+As such, for the purposes of authentication and end-to-end encryption the channel should be treated as untrusted and some
+form of secure layer should be used on top of the channel.
+
+### Denial of Service attack surface
+
+Because the protocol allows for the creation of arbitrary channels and storage of arbitrary data, it is possible to use
+it as a denial of service attack surface.
+
+As such, the following standard mitigations such as the following may be deemed appropriate by homeserver implementations
+and administrators:
+
+- rate limiting of requests
+- imposing a low maximum payload size (e.g. kilobytes not megabytes)
+- limiting the number of concurrent channels
+
+## Unstable prefix
+
+None.
+
+## Dependencies
+
+None.

From e15fda025e11cf51d59124c55cbb1172e03561db Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 7 Sep 2022 09:21:53 +0100
Subject: [PATCH 02/33] MSC3886: Simple rendezvous capability

---
 ...zvous-capability.md => 3886-simple-rendezvous-capability.md} | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 rename proposals/{xxxx-simple-rendezvous-capability.md => 3886-simple-rendezvous-capability.md} (98%)

diff --git a/proposals/xxxx-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
similarity index 98%
rename from proposals/xxxx-simple-rendezvous-capability.md
rename to proposals/3886-simple-rendezvous-capability.md
index 4dbff84975..c95ef4e40b 100644
--- a/proposals/xxxx-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -1,4 +1,4 @@
-# MSCxxxx: Simple rendezvous capability
+# MSC3886: Simple rendezvous capability
 
 In MSCyyyy a proposal is made to allow a user to login on a new device using an existing device by means of scanning a
 QR code.

From 0350bf8c80bcd24a46f5a8102a4a23232150ecf0 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 7 Sep 2022 13:42:32 +0100
Subject: [PATCH 03/33] Note that it is client rendezvous rather than anything
 else

---
 proposals/3886-simple-rendezvous-capability.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index c95ef4e40b..20585316a2 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -1,4 +1,4 @@
-# MSC3886: Simple rendezvous capability
+# MSC3886: Simple client rendezvous capability
 
 In MSCyyyy a proposal is made to allow a user to login on a new device using an existing device by means of scanning a
 QR code.

From fcc327041a616d4feec467bf62c8c2f9a222105a Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 7 Sep 2022 15:22:53 +0100
Subject: [PATCH 04/33] Describe protocol + more notes

---
 .../3886-simple-rendezvous-capability.md      | 165 +++++++++++++++++-
 1 file changed, 159 insertions(+), 6 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 20585316a2..8c176fee9b 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -19,18 +19,164 @@ It will work with devices behind NAT. It doesn't require homeserver administrato
 
 ## Proposal
 
+It is proposed that a general purpose HTTP based protocol be used to establish ephemeral bi-directional communication
+channels over which arbitrary data can be exchanged.
+
+A typical flow might look like this where device A is initiating the rendezvous with device B:
+
+```mermaid
+
+sequenceDiagram
+  participant A as Device A
+  participant R as Rendezvous Server
+  participant B as Device B
+  Note over A: Device A determines which rendezvous server to use
+
+  A->R: POST / Hello from A
+  R->A: 200 OK {"id": "<rendezvous ID>"}
+
+  A-->B: Rendezvous URI between clients, perhaps as QR code: https://rendzvous-server/<rendezvous ID>
+
+  Note over A: Device A starts polling for contact at the rendezvous
+
+  B->R: GET /<rendezvous ID>
+  R->B: 200 OK Hello from A
+
+  loop Device A polls for rendezvous updates
+    A->R: GET /<rendezvous ID> If-None-Match: <ETag>
+    R->A: 304 Not Modified
+  end
+
+  B->R: PUT /<rendezvous ID> Hello from B
+  R->B: 202 Accepted 
+
+  Note over A,B: Rendezvous now established
+```
+
+Please note that it is intentional that this protocol does nothing to ensure the integrity of the data exchanged at a rendezvous.
+
 ### Protocol
 
-`POST /`
+#### Create a new rendezvous point: `POST /`
+
+HTTP request headers:
+
+- `Content-Type` - optional, server should assume `application/octet-stream` if not specified
+
+HTTP request body:
+
+- any data up to maximum size allowed by the server
+
+HTTP response codes:
+
+- `200 OK` - rendezvous created
+- `403 Forbidden` - forbidden by server policy
+- `413 Payload Too Large` - the supplied payload is too large
+- `429 Too Many Requests` - the request has been rate limited
+
+HTTP response headers for `200 OK`:
+
+- `Content-Type` - required, always `application/json`
+- `ETag` - required, ETag for the current payload at the rendezvous point as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.etag)
+- `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)
+- `Last-Modified` - required, the last modified date of the payload as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
+
+HTTP response body for `200 OK`:
+
+- `id` - required, the identifier to use with subsequent requests
+- `max_bytes` - required, the maximum allowed bytes for the payload
+
+Example:
+
+```json
+{
+    "id": "<rendezvous id>",
+    "max_bytes": 102400,
+}
+```
+
+#### Update payload at rendezvous point: `PUT /<rendezvous id>`
+
+HTTP request headers:
+
+- `Content-Type` - optional, server should assume `application/octet-stream` if not specified
+- `If-Match` - optional, as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.if-match) server will assume `*`
+if not specified
 
-`PUT /<channel id>`
+HTTP request body:
 
-`GET /<channel id>`
+- any data up to maximum size allowed by the server
 
-`DELETE /<channel id>`
+HTTP response codes:
+
+- `202 Accepted` - payload set
+- `404 Not Found` - rendezvous ID is not valid (it could have expired)
+- `413 Payload Too Large` - the supplied payload is too large
+- `412 Precondition Failed` - when `If-Match` is supplied and the ETag does not match
+- `429 Too Many Requests` - the request has been rate limited
+
+HTTP response headers for `202 Accepted` and `412 Precondition Failed`:
+
+- `ETag` - required, ETag for the current payload at the rendezvous point as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.etag)
+- `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)
+- `Last-Modified` - required, the last modified date of the payload as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
+
+#### Get payload from rendezvous point: `GET /<rendezvous id>`
+
+HTTP request headers:
+
+- `If-None-Match` - optional, as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.if-none-match) server will
+only return data if given ETag does not match
+
+HTTP response codes:
+
+- `200 OK` - payload returned
+- `404 Not Found` - rendezvous ID is not valid (it could have expired)
+- `304 Not Modified` - when `If-None-Match` is supplied and the ETag does not match
+- `429 Too Many Requests` - the request has been rate limited
+
+HTTP response headers for `200 OK` and `304 Not Modified`:
+
+- `ETag` - required, ETag for the current payload at the rendezvous point as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.etag)
+- `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)
+- `Last-Modified` - required, the last modified date of the payload as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
+
+- `Content-Type` - required for `200 OK`
+
+#### Cancel a rendezvous: `DELETE /<rendezvous id>`
+
+HTTP response codes:
+
+- `204 No Content` - rendezvous cancelled
+- `404 Not Found` - rendezvous ID is not valid (it could have expired)
+- `429 Too Many Requests` - the request has been rate limited
+
+### Maximum payload size
+
+The server should enforce a maximum payload size for the payload size. It is recommended that this be no less than 10KB.
+
+### Maximum duration of a rendezvous
+
+The rendezvous only needs to persist for the duration of the handshake. So a timeout such as 30 seconds is adequate.
+
+Clients should handle the case of the rendezvous being cancelled or timed out by the server.
+
+### ETags
+
+The ETag generated should be unique to the rendezvous point and the last modified time so that two clients can
+distinguish between identical payloads sent by either client.
 
 ### CORS
 
+To support usage from web browsers, the server should allow CORS requests from any origin and expose the ETag header:
+
+```http
+Access-Control-Allow-Headers: Content-type
+Access-Control-Allow-Methods: GET,PUT,POST,DELETE
+Access-Control-Allow-Origin: *
+Access-Control-Expose-Headers: ETag
+```
+
 ### Choice of server
 
 Ultimately it will be up to the Matrix client implementation to decide which rendezvous server to use.
@@ -52,15 +198,17 @@ The proposed protocol requires the devices to have IP connectivity to the server
 
 Try and do something with STUN or TURN or [COAP](http://coap.technology/).
 
+Rather than requiring the devices to poll for updated "long-polling" could be used instead similar to `/sync`.
+
 ## Security considerations
 
 ### Confidentiality of data
 
 Whilst the data transmitted can be encrypted in transit via HTTP/TLS the rendezvous server does have visibility over the
-data.
+data and can also perform man in the middle attacks.
 
 As such, for the purposes of authentication and end-to-end encryption the channel should be treated as untrusted and some
-form of secure layer should be used on top of the channel.
+form of secure layer should be used on top of the channel such as a Diffie-Hellman key exchange.
 
 ### Denial of Service attack surface
 
@@ -81,3 +229,8 @@ None.
 ## Dependencies
 
 None.
+
+## Credits
+
+This proposal was influenced by https://wiki.mozilla.org/Services/KeyExchange which also has some helpful discussion
+around DoS mitigation.

From 60f8115034c73ad40ee82c4f55093a63e44994cf Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 7 Sep 2022 15:43:04 +0100
Subject: [PATCH 05/33] Use HTTP response headers only instead of JSON for POST
 /

---
 .../3886-simple-rendezvous-capability.md      | 30 +++++++++----------
 1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 8c176fee9b..4c8bf2e2a7 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -69,30 +69,27 @@ HTTP request body:
 
 HTTP response codes:
 
-- `200 OK` - rendezvous created
+- `201 Accepted` - rendezvous created
 - `403 Forbidden` - forbidden by server policy
 - `413 Payload Too Large` - the supplied payload is too large
 - `429 Too Many Requests` - the request has been rate limited
 
-HTTP response headers for `200 OK`:
+HTTP response headers for `201 OK`:
 
-- `Content-Type` - required, always `application/json`
+- `Location` - required, the allocated rendezvous ID represented as a relative path
+- `X-Max-Bytes` - required, the maximum allowed bytes for the payload
 - `ETag` - required, ETag for the current payload at the rendezvous point as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.etag)
 - `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)
 - `Last-Modified` - required, the last modified date of the payload as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
 
-HTTP response body for `200 OK`:
+Example response headers:
 
-- `id` - required, the identifier to use with subsequent requests
-- `max_bytes` - required, the maximum allowed bytes for the payload
-
-Example:
-
-```json
-{
-    "id": "<rendezvous id>",
-    "max_bytes": 102400,
-}
+```http
+Location: abcdEFG12345
+X-Max-Bytes: 10240
+ETag: VmbxF13QDusTgOCt8aoa0d2PQcnBOXeIxEqhw5aQ03o=
+Expires: Wed, 07 Sep 2022 14:28:51 GMT
+Last-Modified: Wed, 07 Sep 2022 14:27:51 GMT
 ```
 
 #### Update payload at rendezvous point: `PUT /<rendezvous id>`
@@ -168,13 +165,14 @@ distinguish between identical payloads sent by either client.
 
 ### CORS
 
-To support usage from web browsers, the server should allow CORS requests from any origin and expose the ETag header:
+To support usage from web browsers, the server should allow CORS requests from any origin and expose the `ETag` and
+`Location` headers:
 
 ```http
 Access-Control-Allow-Headers: Content-type
 Access-Control-Allow-Methods: GET,PUT,POST,DELETE
 Access-Control-Allow-Origin: *
-Access-Control-Expose-Headers: ETag
+Access-Control-Expose-Headers: ETag,Location
 ```
 
 ### Choice of server

From 5a9c3c78f7b52f7421236720872a1cdd73bffd7d Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 7 Sep 2022 15:48:18 +0100
Subject: [PATCH 06/33] Fix POST response code

---
 proposals/3886-simple-rendezvous-capability.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 4c8bf2e2a7..899a0f402f 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -33,7 +33,7 @@ sequenceDiagram
   Note over A: Device A determines which rendezvous server to use
 
   A->R: POST / Hello from A
-  R->A: 200 OK {"id": "<rendezvous ID>"}
+  R->A: 201 Created Location: <rendezvous ID>
 
   A-->B: Rendezvous URI between clients, perhaps as QR code: https://rendzvous-server/<rendezvous ID>
 
@@ -69,12 +69,12 @@ HTTP request body:
 
 HTTP response codes:
 
-- `201 Accepted` - rendezvous created
+- `201 Created` - rendezvous created
 - `403 Forbidden` - forbidden by server policy
 - `413 Payload Too Large` - the supplied payload is too large
 - `429 Too Many Requests` - the request has been rate limited
 
-HTTP response headers for `201 OK`:
+HTTP response headers for `201 Created`:
 
 - `Location` - required, the allocated rendezvous ID represented as a relative path
 - `X-Max-Bytes` - required, the maximum allowed bytes for the payload
@@ -106,7 +106,7 @@ HTTP request body:
 
 HTTP response codes:
 
-- `202 Accepted` - payload set
+- `202 Accepted` - payload updated
 - `404 Not Found` - rendezvous ID is not valid (it could have expired)
 - `413 Payload Too Large` - the supplied payload is too large
 - `412 Precondition Failed` - when `If-Match` is supplied and the ETag does not match

From fac41d15ef9974b37e4fb74d82ac83eafa11804e Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Fri, 9 Sep 2022 12:19:03 +0100
Subject: [PATCH 07/33] Add extra emphasis to relative nature of Location
 header

---
 proposals/3886-simple-rendezvous-capability.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 899a0f402f..45c9566b5f 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -76,7 +76,7 @@ HTTP response codes:
 
 HTTP response headers for `201 Created`:
 
-- `Location` - required, the allocated rendezvous ID represented as a relative path
+- `Location` - required, the allocated rendezvous ID represented as a URI safe **relative path**. e.g. `Location: abc-def-1234`
 - `X-Max-Bytes` - required, the maximum allowed bytes for the payload
 - `ETag` - required, ETag for the current payload at the rendezvous point as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.etag)
 - `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)

From cbffa672d6c09bc828ab0ded6d75c544f1929b4a Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Fri, 9 Sep 2022 13:21:44 +0100
Subject: [PATCH 08/33] Use rendezvous URI not IDs

---
 .../3886-simple-rendezvous-capability.md      | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 45c9566b5f..f2d10025d0 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -33,21 +33,21 @@ sequenceDiagram
   Note over A: Device A determines which rendezvous server to use
 
   A->R: POST / Hello from A
-  R->A: 201 Created Location: <rendezvous ID>
+  R->A: 201 Created Location: /abc-def-123-456
 
-  A-->B: Rendezvous URI between clients, perhaps as QR code: https://rendzvous-server/<rendezvous ID>
+  A-->B: Rendezvous URI between clients, perhaps as QR code: e.g. https://rendzvous-server/abc-def-123-456
 
   Note over A: Device A starts polling for contact at the rendezvous
 
-  B->R: GET /<rendezvous ID>
+  B->R: GET <rendezvous URI>
   R->B: 200 OK Hello from A
 
   loop Device A polls for rendezvous updates
-    A->R: GET /<rendezvous ID> If-None-Match: <ETag>
+    A->R: GET <rendezvous URI> If-None-Match: <ETag>
     R->A: 304 Not Modified
   end
 
-  B->R: PUT /<rendezvous ID> Hello from B
+  B->R: PUT <rendezvous URI> Hello from B
   R->B: 202 Accepted 
 
   Note over A,B: Rendezvous now established
@@ -76,7 +76,7 @@ HTTP response codes:
 
 HTTP response headers for `201 Created`:
 
-- `Location` - required, the allocated rendezvous ID represented as a URI safe **relative path**. e.g. `Location: abc-def-1234`
+- `Location` - required, the allocated rendezvous URI which can be on a different server
 - `X-Max-Bytes` - required, the maximum allowed bytes for the payload
 - `ETag` - required, ETag for the current payload at the rendezvous point as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.etag)
 - `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)
@@ -85,14 +85,14 @@ HTTP response headers for `201 Created`:
 Example response headers:
 
 ```http
-Location: abcdEFG12345
+Location: /abcdEFG12345
 X-Max-Bytes: 10240
 ETag: VmbxF13QDusTgOCt8aoa0d2PQcnBOXeIxEqhw5aQ03o=
 Expires: Wed, 07 Sep 2022 14:28:51 GMT
 Last-Modified: Wed, 07 Sep 2022 14:27:51 GMT
 ```
 
-#### Update payload at rendezvous point: `PUT /<rendezvous id>`
+#### Update payload at rendezvous point: `PUT <rendezvous URI>`
 
 HTTP request headers:
 
@@ -107,7 +107,7 @@ HTTP request body:
 HTTP response codes:
 
 - `202 Accepted` - payload updated
-- `404 Not Found` - rendezvous ID is not valid (it could have expired)
+- `404 Not Found` - rendezvous URI is not valid (it could have expired)
 - `413 Payload Too Large` - the supplied payload is too large
 - `412 Precondition Failed` - when `If-Match` is supplied and the ETag does not match
 - `429 Too Many Requests` - the request has been rate limited
@@ -118,7 +118,7 @@ HTTP response headers for `202 Accepted` and `412 Precondition Failed`:
 - `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)
 - `Last-Modified` - required, the last modified date of the payload as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
 
-#### Get payload from rendezvous point: `GET /<rendezvous id>`
+#### Get payload from rendezvous point: `GET <rendezvous URI>`
 
 HTTP request headers:
 
@@ -128,7 +128,7 @@ only return data if given ETag does not match
 HTTP response codes:
 
 - `200 OK` - payload returned
-- `404 Not Found` - rendezvous ID is not valid (it could have expired)
+- `404 Not Found` - rendezvous URI is not valid (it could have expired)
 - `304 Not Modified` - when `If-None-Match` is supplied and the ETag does not match
 - `429 Too Many Requests` - the request has been rate limited
 
@@ -140,12 +140,12 @@ HTTP response headers for `200 OK` and `304 Not Modified`:
 
 - `Content-Type` - required for `200 OK`
 
-#### Cancel a rendezvous: `DELETE /<rendezvous id>`
+#### Cancel a rendezvous: `DELETE <rendezvous URI>`
 
 HTTP response codes:
 
 - `204 No Content` - rendezvous cancelled
-- `404 Not Found` - rendezvous ID is not valid (it could have expired)
+- `404 Not Found` - rendezvous URI is not valid (it could have expired)
 - `429 Too Many Requests` - the request has been rate limited
 
 ### Maximum payload size

From c67a3d6d46876986f8e566dd1087b60a44e83b79 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Fri, 9 Sep 2022 15:04:41 +0100
Subject: [PATCH 09/33] Update CORS with more headers

---
 proposals/3886-simple-rendezvous-capability.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index f2d10025d0..142d9ce428 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -165,14 +165,14 @@ distinguish between identical payloads sent by either client.
 
 ### CORS
 
-To support usage from web browsers, the server should allow CORS requests from any origin and expose the `ETag` and
-`Location` headers:
+To support usage from web browsers, the server should allow CORS requests from any origin and expose the `ETag`,
+`Location` and `X-Max-Bytes` headers as:
 
 ```http
-Access-Control-Allow-Headers: Content-type
+Access-Control-Allow-Headers: Content-Type,If-Match,If-None-Match
 Access-Control-Allow-Methods: GET,PUT,POST,DELETE
 Access-Control-Allow-Origin: *
-Access-Control-Expose-Headers: ETag,Location
+Access-Control-Expose-Headers: ETag,Location,X-Max-Bytes
 ```
 
 ### Choice of server

From 1ec9ce252fd70dc39144ffa7deb8479745d97b34 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Fri, 9 Sep 2022 17:41:53 +0100
Subject: [PATCH 10/33] Sort HTTP response codes

---
 proposals/3886-simple-rendezvous-capability.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 142d9ce428..61e59aa7f4 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -108,8 +108,8 @@ HTTP response codes:
 
 - `202 Accepted` - payload updated
 - `404 Not Found` - rendezvous URI is not valid (it could have expired)
-- `413 Payload Too Large` - the supplied payload is too large
 - `412 Precondition Failed` - when `If-Match` is supplied and the ETag does not match
+- `413 Payload Too Large` - the supplied payload is too large
 - `429 Too Many Requests` - the request has been rate limited
 
 HTTP response headers for `202 Accepted` and `412 Precondition Failed`:
@@ -128,8 +128,8 @@ only return data if given ETag does not match
 HTTP response codes:
 
 - `200 OK` - payload returned
-- `404 Not Found` - rendezvous URI is not valid (it could have expired)
 - `304 Not Modified` - when `If-None-Match` is supplied and the ETag does not match
+- `404 Not Found` - rendezvous URI is not valid (it could have expired)
 - `429 Too Many Requests` - the request has been rate limited
 
 HTTP response headers for `200 OK` and `304 Not Modified`:

From 8a0d5598bb71972321ae54aaee5b31fa3561e9cd Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Fri, 9 Sep 2022 17:42:46 +0100
Subject: [PATCH 11/33] Add requirement for content-length header on POST and
 PUT

---
 proposals/3886-simple-rendezvous-capability.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 61e59aa7f4..e9d3646a35 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -61,6 +61,7 @@ Please note that it is intentional that this protocol does nothing to ensure the
 
 HTTP request headers:
 
+- `Content-Length` - required
 - `Content-Type` - optional, server should assume `application/octet-stream` if not specified
 
 HTTP request body:
@@ -96,6 +97,7 @@ Last-Modified: Wed, 07 Sep 2022 14:27:51 GMT
 
 HTTP request headers:
 
+- `Content-Length` - required
 - `Content-Type` - optional, server should assume `application/octet-stream` if not specified
 - `If-Match` - optional, as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.if-match) server will assume `*`
 if not specified

From cacae4e2c5bcb43e118dde6398c7f4445a73c672 Mon Sep 17 00:00:00 2001
From: Matthew Hodgson <matthew@matrix.org>
Date: Sun, 11 Sep 2022 21:49:45 +0100
Subject: [PATCH 12/33] fix typo & clarification

---
 proposals/3886-simple-rendezvous-capability.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index e9d3646a35..4e6553859e 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -1,12 +1,12 @@
 # MSC3886: Simple client rendezvous capability
 
-In MSCyyyy a proposal is made to allow a user to login on a new device using an existing device by means of scanning a
+In MSCyyyy (to be published) a proposal is made to allow a user to login on a new device using an existing device by means of scanning a
 QR code.
 
 In order to facilitate this the two devices need some bi-directional communication channel which they can use to exchange
 information such as:
 
-- the homserver being used
+- the homeserver being used
 - the user ID
 - facilitation of issuing a new access token
 - device ID for end-to-end encryption

From 94ef9ddd2b69f0ca32781d5f5ef0f590c77b7100 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Fri, 30 Sep 2022 12:17:45 +0100
Subject: [PATCH 13/33] Add link to current CORS headers

---
 proposals/3886-simple-rendezvous-capability.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 4e6553859e..36e4b00730 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -177,6 +177,8 @@ Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: ETag,Location,X-Max-Bytes
 ```
 
+These headers are different from the ones currently specified in the [spec](https://spec.matrix.org/v1.4/client-server-api/#web-browser-clients).
+
 ### Choice of server
 
 Ultimately it will be up to the Matrix client implementation to decide which rendezvous server to use.

From 953c4ee1cbc6873546d66477fd56d9e2f6c47736 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Mon, 3 Oct 2022 13:59:35 +0100
Subject: [PATCH 14/33] Add 307 response for POST

---
 proposals/3886-simple-rendezvous-capability.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 36e4b00730..bc9fa004ab 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -74,6 +74,7 @@ HTTP response codes:
 - `403 Forbidden` - forbidden by server policy
 - `413 Payload Too Large` - the supplied payload is too large
 - `429 Too Many Requests` - the request has been rate limited
+- `307 Temporary Redirect` - if the request should be served from somewhere else specified in the `Location` response header
 
 HTTP response headers for `201 Created`:
 

From ff9a37381797ba35b1fe11e1d3e4978f8b34dbbc Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Mon, 3 Oct 2022 14:01:48 +0100
Subject: [PATCH 15/33] Add unstable prefixes

---
 .../3886-simple-rendezvous-capability.md      | 21 ++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index bc9fa004ab..d8e73d2c1f 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -32,7 +32,7 @@ sequenceDiagram
   participant B as Device B
   Note over A: Device A determines which rendezvous server to use
 
-  A->R: POST / Hello from A
+  A->R: POST /rendezvous Hello from A
   R->A: 201 Created Location: /abc-def-123-456
 
   A-->B: Rendezvous URI between clients, perhaps as QR code: e.g. https://rendzvous-server/abc-def-123-456
@@ -57,7 +57,7 @@ Please note that it is intentional that this protocol does nothing to ensure the
 
 ### Protocol
 
-#### Create a new rendezvous point: `POST /`
+#### Create a new rendezvous point: `POST /rendezvous`
 
 HTTP request headers:
 
@@ -227,7 +227,22 @@ and administrators:
 
 ## Unstable prefix
 
-None.
+While this feature is in development the new endpoint should be exposed using the following unstable prefix:
+
+- `/_matrix/client/unstable/org.matrix.msc3886/rendezvous`
+
+Additionally, the feature is to be advertised as unstable feature in the `GET /_matrix/client/versions`
+response, with the key `org.matrix.msc3886` set to `true`. So, the response could look then as
+following:
+
+```json
+{
+    "versions": ["r0.6.0"],
+    "unstable_features": {
+        "org.matrix.msc3886": true
+    }
+}
+```
 
 ## Dependencies
 

From 6937a86a6acaef5b1e96c835af9be8857639a8fe Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Thu, 13 Oct 2022 11:48:07 +0100
Subject: [PATCH 16/33] MSCyyyy => MSC3906

---
 proposals/3886-simple-rendezvous-capability.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index d8e73d2c1f..f0e48d74c2 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -1,6 +1,6 @@
 # MSC3886: Simple client rendezvous capability
 
-In MSCyyyy (to be published) a proposal is made to allow a user to login on a new device using an existing device by means of scanning a
+In [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) a proposal is made to allow a user to login on a new device using an existing device by means of scanning a
 QR code.
 
 In order to facilitate this the two devices need some bi-directional communication channel which they can use to exchange
@@ -12,7 +12,7 @@ information such as:
 - device ID for end-to-end encryption
 - device keys for end-to-end encryption
 
-To enable MSCyyyy and support any future proposals this MSC proposes a simple HTTP based protocol that can be used to
+To enable [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) and support any future proposals this MSC proposes a simple HTTP based protocol that can be used to
 establish a direct communication channel between two IP connected devices.
 
 It will work with devices behind NAT. It doesn't require homeserver administrators to deploy a separate server.
@@ -246,7 +246,7 @@ following:
 
 ## Dependencies
 
-None.
+None, although it's intended to be used with [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906).
 
 ## Credits
 

From 4ab59f8d4dcbf0d1973cb2b59c042c9b4ca387f4 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Wed, 15 Mar 2023 16:23:13 -0400
Subject: [PATCH 17/33] Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 proposals/3886-simple-rendezvous-capability.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index f0e48d74c2..f98774b538 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -81,7 +81,7 @@ HTTP response headers for `201 Created`:
 - `Location` - required, the allocated rendezvous URI which can be on a different server
 - `X-Max-Bytes` - required, the maximum allowed bytes for the payload
 - `ETag` - required, ETag for the current payload at the rendezvous point as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.etag)
-- `Expires` - required, the expiry time of the rendezvous as per [RFC7233](https://httpwg.org/specs/rfc7234.html#header.expires)
+- `Expires` - required, the expiry time of the rendezvous as per [RFC7234](https://httpwg.org/specs/rfc7234.html#header.expires)
 - `Last-Modified` - required, the last modified date of the payload as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.last-modified)
 
 Example response headers:
@@ -201,7 +201,7 @@ The proposed protocol requires the devices to have IP connectivity to the server
 
 Try and do something with STUN or TURN or [COAP](http://coap.technology/).
 
-Rather than requiring the devices to poll for updated "long-polling" could be used instead similar to `/sync`.
+Rather than requiring the devices to poll for updates, "long-polling" could be used instead similar to `/sync`.
 
 ## Security considerations
 

From 5db0af6a3b5d985d5ac570a64af2d4206ce62e3d Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 15 Mar 2023 16:56:15 -0400
Subject: [PATCH 18/33] Add missing arrows to diagram

---
 proposals/3886-simple-rendezvous-capability.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index f98774b538..50273f3504 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -32,23 +32,23 @@ sequenceDiagram
   participant B as Device B
   Note over A: Device A determines which rendezvous server to use
 
-  A->R: POST /rendezvous Hello from A
-  R->A: 201 Created Location: /abc-def-123-456
+  A->>+R: POST /rendezvous Hello from A
+  R->>-A: 201 Created Location: /abc-def-123-456
 
-  A-->B: Rendezvous URI between clients, perhaps as QR code: e.g. https://rendzvous-server/abc-def-123-456
+  A-->>B: Rendezvous URI between clients, perhaps as QR code: e.g. https://rendzvous-server/abc-def-123-456
 
   Note over A: Device A starts polling for contact at the rendezvous
 
-  B->R: GET <rendezvous URI>
-  R->B: 200 OK Hello from A
+  B->>+R: GET <rendezvous URI>
+  R->>-B: 200 OK Hello from A
 
   loop Device A polls for rendezvous updates
-    A->R: GET <rendezvous URI> If-None-Match: <ETag>
-    R->A: 304 Not Modified
+    A->>+R: GET <rendezvous URI> If-None-Match: <ETag>
+    R->>-A: 304 Not Modified
   end
 
-  B->R: PUT <rendezvous URI> Hello from B
-  R->B: 202 Accepted 
+  B->>+R: PUT <rendezvous URI> Hello from B
+  R->>-B: 202 Accepted 
 
   Note over A,B: Rendezvous now established
 ```

From 8a1af85ccc4552939fb74438376c90feaaff4edd Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 15 Mar 2023 17:10:20 -0400
Subject: [PATCH 19/33] Clarify that CORS changes are not global

---
 proposals/3886-simple-rendezvous-capability.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 50273f3504..613edfa751 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -168,8 +168,8 @@ distinguish between identical payloads sent by either client.
 
 ### CORS
 
-To support usage from web browsers, the server should allow CORS requests from any origin and expose the `ETag`,
-`Location` and `X-Max-Bytes` headers as:
+To support usage from web browsers, the server should allow CORS requests to the `/rendezvous` endpoint from any
+origin and expose the `ETag`, `Location` and `X-Max-Bytes` headers as:
 
 ```http
 Access-Control-Allow-Headers: Content-Type,If-Match,If-None-Match
@@ -178,7 +178,9 @@ Access-Control-Allow-Origin: *
 Access-Control-Expose-Headers: ETag,Location,X-Max-Bytes
 ```
 
-These headers are different from the ones currently specified in the [spec](https://spec.matrix.org/v1.4/client-server-api/#web-browser-clients).
+Currently the [spec](https://spec.matrix.org/v1.4/client-server-api/#web-browser-clients) specifies a single set of
+CORS headers to be used. Therefore, care will be required to make it clear in the spec that the headers will
+vary depending on the endpoint.
 
 ### Choice of server
 

From 97f17094f197f8f488b47aa06862c608474fe5bc Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 15 Mar 2023 17:44:30 -0400
Subject: [PATCH 20/33] Authentication + 30x clarifications

---
 proposals/3886-simple-rendezvous-capability.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 613edfa751..9476859a9b 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -76,6 +76,10 @@ HTTP response codes:
 - `429 Too Many Requests` - the request has been rate limited
 - `307 Temporary Redirect` - if the request should be served from somewhere else specified in the `Location` response header
 
+n.b. the relatively unusual [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307) response
+code has been chosen explicitly for the behaviour of ensuring that the method and body will not change whilst the user-agent
+follows the redirect. For this reason, no other `30x` response codes are allowed.
+
 HTTP response headers for `201 Created`:
 
 - `Location` - required, the allocated rendezvous URI which can be on a different server
@@ -151,6 +155,11 @@ HTTP response codes:
 - `404 Not Found` - rendezvous URI is not valid (it could have expired)
 - `429 Too Many Requests` - the request has been rate limited
 
+### Authentication
+
+These API endpoints do not require authentication. This is because the protocol is explicitly treated as untrusted,
+with trust established at a higher level outside the scope of the present proposal.
+
 ### Maximum payload size
 
 The server should enforce a maximum payload size for the payload size. It is recommended that this be no less than 10KB.

From b5c6c7a181cc84279bf037b20852c24066e761eb Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 15 Mar 2023 17:49:07 -0400
Subject: [PATCH 21/33] Import section from MSC3903 about to-device messaging

---
 .../3886-simple-rendezvous-capability.md      | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 9476859a9b..13ddeeadd6 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -210,8 +210,43 @@ The proposed protocol requires the devices to have IP connectivity to the server
 
 ## Alternatives
 
+### Send-to-Device messaging
+
+The combination of this proposal and [MSC3903](https://github.com/matrix-org/matrix-spec-proposals/pull/3903) look similar in
+some regards to the existing [Send-to-device messaging](https://spec.matrix.org/v1.6/client-server-api/#send-to-device-messaging)
+capability.
+
+Whilst to-device messaging already provides a mechanism for secure communication
+between two Matrix clients/devices, a key consideration for the anticipated
+login with QR capability is that one of the clients is not yet authenticated with
+a Homeserver.
+
+Furthermore the client might not know which Homeserver the user wishes to
+connect to.
+
+Conceptually, one could create a new type of "guest" login that would allow the
+unauthenticated client to connect to a Homeserver for the purposes of
+communicating with an existing authenticated client via to-device messages.
+
+Some considerations for this:
+
+Where the "actual" Homeserver is not known then the "guest" Homeserver nominated
+by the new client would need to be federated with the "actual" Homeserver.
+
+The "guest" Homeserver would probably want to automatically clean up the "guest"
+accounts after a short period of time.
+
+The "actual" Homeserver operator might not want to open up full "guest" access
+so a second type of "guest" account might be required.
+
+Does the new device/client need to accept the T&Cs of the "guest" Homeserver?
+
+### Other existing protocols
+
 Try and do something with STUN or TURN or [COAP](http://coap.technology/).
 
+### Implementation details
+
 Rather than requiring the devices to poll for updates, "long-polling" could be used instead similar to `/sync`.
 
 ## Security considerations

From 931cf0735a0a0771833144378982cad9a89e0fee Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 13:32:04 +0000
Subject: [PATCH 22/33] Create a rendezvous point via `/_matrix/client`

---
 proposals/3886-simple-rendezvous-capability.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 13ddeeadd6..f70f1edbff 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -57,7 +57,7 @@ Please note that it is intentional that this protocol does nothing to ensure the
 
 ### Protocol
 
-#### Create a new rendezvous point: `POST /rendezvous`
+#### Create a new rendezvous point: `POST /_matrix/client/rendezvous`
 
 HTTP request headers:
 

From aee7d81c774777ba09a79aa86cd5e09d14e9e56f Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 13:47:29 +0000
Subject: [PATCH 23/33] Define Matrix error codes

---
 .../3886-simple-rendezvous-capability.md      | 28 +++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index f70f1edbff..72891faa43 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -68,12 +68,12 @@ HTTP request body:
 
 - any data up to maximum size allowed by the server
 
-HTTP response codes:
+HTTP response codes, and Matrix error codes:
 
 - `201 Created` - rendezvous created
-- `403 Forbidden` - forbidden by server policy
-- `413 Payload Too Large` - the supplied payload is too large
-- `429 Too Many Requests` - the request has been rate limited
+- `403 Forbidden` (`M_FORBIDDEN`) - forbidden by server policy
+- `413 Payload Too Large` (`M_TOO_LARGE`) - the supplied payload is too large
+- `429 Too Many Requests` (`M_UNKNOWN`) - the request has been rate limited
 - `307 Temporary Redirect` - if the request should be served from somewhere else specified in the `Location` response header
 
 n.b. the relatively unusual [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307) response
@@ -111,13 +111,13 @@ HTTP request body:
 
 - any data up to maximum size allowed by the server
 
-HTTP response codes:
+HTTP response codes, and Matrix error codes:
 
 - `202 Accepted` - payload updated
-- `404 Not Found` - rendezvous URI is not valid (it could have expired)
-- `412 Precondition Failed` - when `If-Match` is supplied and the ETag does not match
-- `413 Payload Too Large` - the supplied payload is too large
-- `429 Too Many Requests` - the request has been rate limited
+- `404 Not Found` (`M_NOT_FOUND`) - rendezvous URI is not valid (it could have expired)
+- `412 Precondition Failed` (`M_DIRTY_WRITE`, **a new error code**) - when `If-Match` is supplied and the ETag does not match
+- `413 Payload Too Large` (`M_TOO_LARGE`) - the supplied payload is too large
+- `429 Too Many Requests` (`M_UNKNOWN`) - the request has been rate limited
 
 HTTP response headers for `202 Accepted` and `412 Precondition Failed`:
 
@@ -132,12 +132,12 @@ HTTP request headers:
 - `If-None-Match` - optional, as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.if-none-match) server will
 only return data if given ETag does not match
 
-HTTP response codes:
+HTTP response codes, and Matrix error codes:
 
 - `200 OK` - payload returned
 - `304 Not Modified` - when `If-None-Match` is supplied and the ETag does not match
-- `404 Not Found` - rendezvous URI is not valid (it could have expired)
-- `429 Too Many Requests` - the request has been rate limited
+- `404 Not Found` (`M_NOT_FOUND`) - rendezvous URI is not valid (it could have expired)
+- `429 Too Many Requests` (`M_UNKNOWN`)- the request has been rate limited
 
 HTTP response headers for `200 OK` and `304 Not Modified`:
 
@@ -152,8 +152,8 @@ HTTP response headers for `200 OK` and `304 Not Modified`:
 HTTP response codes:
 
 - `204 No Content` - rendezvous cancelled
-- `404 Not Found` - rendezvous URI is not valid (it could have expired)
-- `429 Too Many Requests` - the request has been rate limited
+- `404 Not Found` (`M_NOT_FOUND`) - rendezvous URI is not valid (it could have expired)
+- `429 Too Many Requests` (`M_UNKNOWN`)- the request has been rate limited
 
 ### Authentication
 

From 90a8b495395ba370cfa71941c6b84d21b46aae93 Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 13:59:55 +0000
Subject: [PATCH 24/33] Define 400 response for missing required headers

---
 proposals/3886-simple-rendezvous-capability.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 72891faa43..185a0ddf4c 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -71,6 +71,7 @@ HTTP request body:
 HTTP response codes, and Matrix error codes:
 
 - `201 Created` - rendezvous created
+- `400 Bad Request` (`M_MISSING_PARAM`) - no `Content-Length` was provided.
 - `403 Forbidden` (`M_FORBIDDEN`) - forbidden by server policy
 - `413 Payload Too Large` (`M_TOO_LARGE`) - the supplied payload is too large
 - `429 Too Many Requests` (`M_UNKNOWN`) - the request has been rate limited
@@ -114,6 +115,7 @@ HTTP request body:
 HTTP response codes, and Matrix error codes:
 
 - `202 Accepted` - payload updated
+- `400 Bad Request` (`M_MISSING_PARAM`) - no `Content-Length` was provided.
 - `404 Not Found` (`M_NOT_FOUND`) - rendezvous URI is not valid (it could have expired)
 - `412 Precondition Failed` (`M_DIRTY_WRITE`, **a new error code**) - when `If-Match` is supplied and the ETag does not match
 - `413 Payload Too Large` (`M_TOO_LARGE`) - the supplied payload is too large

From dcbbcb0f7d5f606a36b65e13f85aacde716372dd Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 15:13:57 +0000
Subject: [PATCH 25/33] Emphasise that the this is an untrusted channel

---
 proposals/3886-simple-rendezvous-capability.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 185a0ddf4c..d73dd76fe8 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -10,11 +10,13 @@ information such as:
 - the user ID
 - facilitation of issuing a new access token
 - device ID for end-to-end encryption
-- device keys for end-to-end encryption
 
 To enable [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) and support any future proposals this MSC proposes a simple HTTP based protocol that can be used to
 establish a direct communication channel between two IP connected devices.
 
+This channel SHOULD be considered untrusted by both devices, and SHOULD NOT be
+used to transmit sensitive data in plaintext.
+
 It will work with devices behind NAT. It doesn't require homeserver administrators to deploy a separate server.
 
 ## Proposal

From 74d90948616b29f3026b1840f5752a0d95e585d0 Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 15:19:10 +0000
Subject: [PATCH 26/33] Refer to MSC3903

For establshing an encrypted channel atop this
---
 proposals/3886-simple-rendezvous-capability.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index d73dd76fe8..cc6ec89dfb 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -10,6 +10,8 @@ information such as:
 - the user ID
 - facilitation of issuing a new access token
 - device ID for end-to-end encryption
+- data for establishing a secure communication channel (e.g. via
+  [MSC3903](https://github.com/matrix-org/matrix-spec-proposals/pull/3903))
 
 To enable [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) and support any future proposals this MSC proposes a simple HTTP based protocol that can be used to
 establish a direct communication channel between two IP connected devices.
@@ -296,7 +298,9 @@ following:
 
 ## Dependencies
 
-None, although it's intended to be used with [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906).
+None, although it's intended to be used with
+[MSC3903](https://github.com/matrix-org/matrix-spec-proposals/pull/3903) and
+[MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906).
 
 ## Credits
 

From 4c634938d2fb289c9f33d9ef4f8f05ee3ae6056f Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 15:25:18 +0000
Subject: [PATCH 27/33] Add internal hyperlink

---
 proposals/3886-simple-rendezvous-capability.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index cc6ec89dfb..940281e6ba 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -16,8 +16,8 @@ information such as:
 To enable [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) and support any future proposals this MSC proposes a simple HTTP based protocol that can be used to
 establish a direct communication channel between two IP connected devices.
 
-This channel SHOULD be considered untrusted by both devices, and SHOULD NOT be
-used to transmit sensitive data in plaintext.
+This channel [SHOULD be considered untrusted](#confidentiality-of-data)
+by both devices, and SHOULD NOT be used to transmit sensitive data in plaintext.
 
 It will work with devices behind NAT. It doesn't require homeserver administrators to deploy a separate server.
 

From 58f1e86fc11d16865fd073153f56a8f33e19552d Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 16:19:56 +0000
Subject: [PATCH 28/33] Require `PUT` to supply an `If-Match`

---
 proposals/3886-simple-rendezvous-capability.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 940281e6ba..44e9c68ae5 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -109,7 +109,8 @@ HTTP request headers:
 
 - `Content-Length` - required
 - `Content-Type` - optional, server should assume `application/octet-stream` if not specified
-- `If-Match` - optional, as per [RFC7232](https://httpwg.org/specs/rfc7232.html#header.if-match) server will assume `*`
+- `If-Match` - required. The ETag of the last payload seen by the requesting device.
+
 if not specified
 
 HTTP request body:
@@ -119,9 +120,9 @@ HTTP request body:
 HTTP response codes, and Matrix error codes:
 
 - `202 Accepted` - payload updated
-- `400 Bad Request` (`M_MISSING_PARAM`) - no `Content-Length` was provided.
+- `400 Bad Request` (`M_MISSING_PARAM`) - a required header was not provided.
 - `404 Not Found` (`M_NOT_FOUND`) - rendezvous URI is not valid (it could have expired)
-- `412 Precondition Failed` (`M_DIRTY_WRITE`, **a new error code**) - when `If-Match` is supplied and the ETag does not match
+- `412 Precondition Failed` (`M_DIRTY_WRITE`, **a new error code**) - when the ETag does not match
 - `413 Payload Too Large` (`M_TOO_LARGE`) - the supplied payload is too large
 - `429 Too Many Requests` (`M_UNKNOWN`) - the request has been rate limited
 

From 65d697c2189bffbe1ca505f2ef6086a26a16d882 Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 16:20:20 +0000
Subject: [PATCH 29/33] High-level description

---
 .../3886-simple-rendezvous-capability.md      | 42 ++++++++++++++++++-
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 44e9c68ae5..ced45b7e72 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -26,6 +26,46 @@ It will work with devices behind NAT. It doesn't require homeserver administrato
 It is proposed that a general purpose HTTP based protocol be used to establish ephemeral bi-directional communication
 channels over which arbitrary data can be exchanged.
 
+Please note that it is intentional that this protocol does nothing to ensure the integrity of the data exchanged at a rendezvous.
+
+### High-level description
+
+Suppose that Device A wants to establish communications with Device B. A can do
+so by creating a _rendezvous session_ via a `POST /_matrix/client/rendezvous`
+call to an appropriate server. Its response includes an HTTP _rendezvous URL_
+which should be shared out-of-band with device B. (This URL may be located on a
+different domain to the initial `POST`.)
+
+The rendezvous URL points to an arbitrary data resource ("the payload"), which
+is initially populated using data from A's `POST` request. There are no
+restrictions on the payload itself, but the rendezvous server SHOULD impose a
+maximum size limit. The payload may be retrieved (`GET`) and updated (`PUT`) by
+anyone—A, B, or a third party—who is able to reach the rendezvous URL.
+
+In this way, A and B can communicate by repeatedly inspecting and updating the
+payload pointed at the rendezvous URL.
+
+#### The update mechanism
+
+Every update request MUST include an `ETag` header, whose value is supplied
+the `ETag` header in the last `GET` response seen by the requester. (The
+initiating device may also use the `ETag` supplied in the initial `POST`
+response to immediately update the payload.) Updates will succeed only if the
+supplied `ETag` matches the server's current revision of the payload. This
+prevents concurrent writes to the payload.
+
+There is no mechanism to retrieve previous payloads after an update.
+
+#### Expiry
+
+The rendezvous session (i.e. the payload) SHOULD expire after a period of time
+communicated to clients via the `Expires` header. After this point, any
+further attempts to query or update the payload MUST fail. The expiry time
+SHOULD be extended every time the payload is updated. The rendezvous session can
+be manually expired with a `DELETE` call to the rendezvous URL.
+
+### Example
+
 A typical flow might look like this where device A is initiating the rendezvous with device B:
 
 ```mermaid
@@ -57,8 +97,6 @@ sequenceDiagram
   Note over A,B: Rendezvous now established
 ```
 
-Please note that it is intentional that this protocol does nothing to ensure the integrity of the data exchanged at a rendezvous.
-
 ### Protocol
 
 #### Create a new rendezvous point: `POST /_matrix/client/rendezvous`

From 43d9871cd757c90c8d41268835462c2004ffd156 Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 16:32:41 +0000
Subject: [PATCH 30/33] Forbid complicated etags

---
 proposals/3886-simple-rendezvous-capability.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index ced45b7e72..90d2a70e7b 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -54,6 +54,11 @@ response to immediately update the payload.) Updates will succeed only if the
 supplied `ETag` matches the server's current revision of the payload. This
 prevents concurrent writes to the payload.
 
+The `ETag` header is standard, described by
+[RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-etag). In this
+proposal we only accept strong, single-valued ETag values; anything else
+constitutes a malformed request.
+
 There is no mechanism to retrieve previous payloads after an update.
 
 #### Expiry

From 3fecfcd5e056a57ebc04ee51be38e89a60ce2d76 Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 16:34:05 +0000
Subject: [PATCH 31/33] Rename M_DIRTY_WRITE -> M_CONCURRENT_WRITE

"Dirty write" refers to a specific SQL phenomenon regarding transaction
isolation, see e.g.
https://blog.acolyer.org/2016/02/24/a-critique-of-ansi-sql-isolation-levels/

Instead, prefer the word "concurrent".
---
 proposals/3886-simple-rendezvous-capability.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 90d2a70e7b..57dfdde40b 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -165,7 +165,7 @@ HTTP response codes, and Matrix error codes:
 - `202 Accepted` - payload updated
 - `400 Bad Request` (`M_MISSING_PARAM`) - a required header was not provided.
 - `404 Not Found` (`M_NOT_FOUND`) - rendezvous URI is not valid (it could have expired)
-- `412 Precondition Failed` (`M_DIRTY_WRITE`, **a new error code**) - when the ETag does not match
+- `412 Precondition Failed` (`M_CONCURRENT_WRITE`, **a new error code**) - when the ETag does not match
 - `413 Payload Too Large` (`M_TOO_LARGE`) - the supplied payload is too large
 - `429 Too Many Requests` (`M_UNKNOWN`) - the request has been rate limited
 

From 82fcb44f64681e2c71594c1733848eebb7f60676 Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Mon, 13 Nov 2023 16:45:39 +0000
Subject: [PATCH 32/33] Explictly reject complicated etags

---
 proposals/3886-simple-rendezvous-capability.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 57dfdde40b..2aaa717197 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -164,6 +164,7 @@ HTTP response codes, and Matrix error codes:
 
 - `202 Accepted` - payload updated
 - `400 Bad Request` (`M_MISSING_PARAM`) - a required header was not provided.
+- `400 Bad Request` (`M_INVALID_PARAM`) - a malformed [`ETag`](#the-update-mechanism) header was provided.
 - `404 Not Found` (`M_NOT_FOUND`) - rendezvous URI is not valid (it could have expired)
 - `412 Precondition Failed` (`M_CONCURRENT_WRITE`, **a new error code**) - when the ETag does not match
 - `413 Payload Too Large` (`M_TOO_LARGE`) - the supplied payload is too large

From a08d14b976f442449243617a65cd613e9c9835d5 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Wed, 21 Feb 2024 10:51:11 +0000
Subject: [PATCH 33/33] Update proposals/3886-simple-rendezvous-capability.md

Co-authored-by: Denis Kasak <dkasak@termina.org.uk>
---
 proposals/3886-simple-rendezvous-capability.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/proposals/3886-simple-rendezvous-capability.md b/proposals/3886-simple-rendezvous-capability.md
index 2aaa717197..193cf7b6eb 100644
--- a/proposals/3886-simple-rendezvous-capability.md
+++ b/proposals/3886-simple-rendezvous-capability.md
@@ -17,7 +17,7 @@ To enable [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/390
 establish a direct communication channel between two IP connected devices.
 
 This channel [SHOULD be considered untrusted](#confidentiality-of-data)
-by both devices, and SHOULD NOT be used to transmit sensitive data in plaintext.
+by both devices, and SHOULD NOT be used to transmit sensitive data in cleartext.
 
 It will work with devices behind NAT. It doesn't require homeserver administrators to deploy a separate server.