MSC4388: Secure out-of-band channel for sign in with QR - 2025 version of rendezvous

[hughns]

Tracking issue for MSC4388 part of the 2025 version of Sign in with QR feature.

Warning

Support for MSC4388 is very limited at present, and is expected to remain that way until the MSC is accepted. If you want to try using Sign in with QR then it is recommended to use the 2024 version from #19434

Context

MSC4108 provides a way for an existing Matrix client to help a new Matrix client sign in. See the intro to MSC4108 for more context.

This MSC4388 experimental feature is the implementation for the secure rendezvous session that is used by MSC4108.

This is only one part of the stack that is necessary to achieve the whole of MSC4108.

The other server-side part of this is having MAS support the Device Authorization Grant from MSC4341. Support for what has become MSC4341 has been in MAS since v0.8.0.

Important

The is also a Synapse feature for an earlier version of MSC4108 (referred to as the "2024" version/revision) which is tracked at #19434. This version from MSC4388 is part of the "2025" version of MSC4108.

Current design in Synapse

This is implemented as a set of servlet handlers written in Rust first introduced by PR #19127. They add some new Client-Server API endpoints.

The choice of of Rust servlets was based on the prior art from #19434

Usage

Prerequisites:

• Synapse is configured to use the OAuth 2.0 API via the matrix_authentication_service configuration options

The feature is configured using:

experimental_features:
  msc4388_mode: <mode>

Where mode is one of:

• off (default): feature is disabled
• authenticated: enabled and requires an authenticated user to create a rendezvous
• public: enabled and no authentication is required

Caveats to be aware of

• in progress rendezvous sessions are dropped during a server restart
• currently restricted to the main process
• no specific rate limit controls
• maximum session duration is not configurable
• the maxmimum concurrent sessions is not configurable
• would it be more maintainable implemented in Python rather than the Rust implementation?

How do we know when to remove this

The feature could be removed if:

• the MSC is closed
• the MSC is accepted - the feature would graduate to main configuration

Notes for graduation

Once the MSC is accepted into the spec I would propose that after an appropriate incubation period the default mode in Synapse be authenticated.

The is a trade-off between capabilities across the modes:

Mode	Existing device can generate QR	New device can generate QR
authenticated	✅	❌
public	✅	✅

For Element clients the user flow impact would be as follows:

Mode	New EX can sign in using QR	New EW can sign in using QR	Existing EX can sign in a new EW/EX	Existing EW can sign in a new EX
authenticated	✅	❌	✅	✅
public	✅	✅	✅	✅