Skip to content

MSC4388: Secure out-of-band channel for sign in with QR #4388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hughns wants to merge 29 commits into
base: main
Choose a base branch
from
+1,132 −0
Open

MSC4388: Secure out-of-band channel for sign in with QR #4388

Changes from 1 commit
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
0b6bc0a
Secure out-of-band channel for sign in with QR
hughns Dec 10, 2025
e298500
MSC4388
hughns Dec 10, 2025
86baa15
Overview diagram
hughns Dec 12, 2025
620aa5e
Move example API usage back to after the API definitions
hughns Dec 12, 2025
ac711d4
Switch from ECIES to HPKE
poljar Dec 17, 2025
870d2ad
Standardise on || for concatenation
hughns Jan 7, 2026
a279629
Fix encoding of LoginOkMessage
hughns Jan 7, 2026
98f94a0
Refer to nonce logic described in HPKE
hughns Jan 7, 2026
815583d
Clean up HPKE section
hughns Jan 14, 2026
94ad88c
Update proposals/4388-secure-qr-channel.md
hughns Jan 14, 2026
ac1d9b5
Remove | from concatenated strings
hughns Jan 14, 2026
d081b78
Change expires_ts to expires_in_ms
hughns Jan 21, 2026
d8424cc
Use binary packing for LoginInitiateMEssage and LoginOkMessage
hughns Jan 23, 2026
fbc626b
Fix unstable rendezvious endpoint path
hughns Jan 23, 2026
270c17d
Use HPKE functions directly where possible and don't repeat what is i…
hughns Jan 23, 2026
69a9997
Apply suggestions from code review
hughns Feb 9, 2026
a44815f
Bind secure channel to rendezvous session via additional authenticati…
hughns Feb 25, 2026
db88079
Ensure no leading zero in check code and notes on acceptable limitations
hughns Feb 25, 2026
1963cf1
Add alternative about making `Sec-Fetch` logic explicit
hughns Feb 25, 2026
7d1d413
With note about MUST and SHOULD
hughns Feb 25, 2026
f07df05
Add discovery endpoint and remove unstable_features
hughns Mar 16, 2026
4af6457
Add note about Context_DeviceG_Send exporter secret
hughns Mar 16, 2026
309b0f7
Attempt to clarify maximum size of data
hughns Mar 17, 2026
d638bdd
Clarify the PUT semantics
hughns Mar 17, 2026
69869ec
Add create_available to discovery response body
hughns Mar 18, 2026
62672cf
Correction on discovery response codes
hughns Mar 18, 2026
f95061f
Apply suggestions from review
hughns Apr 8, 2026
d2ba84f
Incorporate helpful note from @uhoreg
hughns Apr 8, 2026
5b6dc1e
Specify maximum length of rendezvous ID and sequence token + delimit …
hughns Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add discovery endpoint and remove unstable_features
  • Loading branch information
@hughns
hughns committed Mar 16, 2026
commit f07df05dd3d8bfd2dd0e503f8d5f331ae82fe15d
45 changes: 33 additions & 12 deletions proposals/4388-secure-qr-channel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,39 @@ The rendezvous session (i.e. the payload) SHOULD expire after a period of time c
`expires_in_ms` field on the `POST` and `GET` response bodies. After this point, any further attempts to query or update
the payload MUST fail. The rendezvous session can be manually expired with a `DELETE` call to the rendezvous session.

### `GET /_matrix/client/v1/rendezvous` - Discover if the rendezvous API is available

Rate-limited: Yes
Requires authentication: Optional - depending on server policy

Clients can use this endpoint to determine if the rendezvous API is available to them. Because the server policy may
require authentication, clients should make this request with their access token if they have one.

HTTP response codes, and Matrix error codes:

- `200 OK` - rendezvous API is available to the requester
- `403 Forbidden` (`M_FORBIDDEN`) - the requester is not authorized to create the rendezvous session
- `404 Not Found` (`M_UNRECOGNIZED`) - the rendezvous API is not enabled
- `429 Too Many Requests` (`M_LIMIT_EXCEEDED`) - the request has been rate limited

The response body for `200 OK` is `application/json` with an empty body. It means that the requester is able to create
a rendezvous session using `POST /_matrix/client/v1/rendezvous`.

Example response:

```http
HTTP 200 OK
Content-Type: application/json

{}
```

The body could be extended in future to provide any other information that the requester might require to use the
rendezvous API.

The server can chose what level of authentication is required to create a rendezvous session. Please see the description
of `POST /_matrix/client/v1/rendezvous` for a description of this.

### `POST /_matrix/client/v1/rendezvous` - Create a rendezvous session and send initial payload

Rate-limited: Yes
Expand Down Expand Up @@ -1001,18 +1034,6 @@ While this feature is in development the new API endpoints should be exposed usi

- `/_matrix/client/unstable/io.element.msc4388/rendezvous` instead of `/_matrix/client/v1/rendezvous`

Additionally, the feature is to be advertised as unstable feature in the `GET /_matrix/client/versions` response, with the
key `io.element.msc4388` set to true. So, the response could look then as following:

```json
{
"versions": ["..."],
"unstable_features": {
"io.element.msc4388": true
}
}
```

### Unstable QR code format

The unstable value of `IO_ELEMENT_MSC4388` should be used instead of `MATRIX` in the QR code.
Expand Down
Loading