Skip to main content

tuwunel_core/config/
rendezvous.rs

1//! Configures QR sign-in rendezvous sessions.
2//!
3//! Payload size, lifetime, and session count bound retained handshakes.
4//! Authentication policy and per-IP throttling govern discovery and
5//! creation.
6
7use serde::Deserialize;
8use tuwunel_macros::config_example_generator;
9
10use super::true_fn;
11
12/// QR code sign-in
13///
14/// Relays the short handshake between a new device and a signed-in one
15/// during QR code sign-in (MSC4108 and MSC4388), before an OAuth device
16/// grant completes the login. On by default, but sessions can be created
17/// only while the built-in OIDC server runs, which needs `well_known.client`
18/// plus an `identity_provider` or `authentication.oidc.native_auth`.
19/// Sessions live in memory and are lost on restart.
20///
21/// Tips:
22/// - Reverse proxies must not cache or compress responses under the
23///   rendezvous paths; compression weakens the `ETag` and sign-in fails
24///   right after the scan. See
25///   <https://tuwunel.chat/authentication/qr-login.html>.
26#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
27#[derive(Clone, Copy, Debug, Deserialize)]
28#[config_example_generator(
29	filename = "tuwunel-example.toml",
30	section = "global.rendezvous",
31	group = "true"
32)]
33pub struct Rendezvous {
34	/// Enables QR sign-in rendezvous sessions under
35	/// [MSC4108](https://github.com/matrix-org/matrix-spec-proposals/pull/4108)
36	/// and
37	/// [MSC4388](https://github.com/matrix-org/matrix-spec-proposals/pull/4388).
38	///
39	/// Sessions relay the handshake between two devices before an OAuth
40	/// device-authorization grant completes sign-in, requiring the built-in
41	/// OIDC server. When disabled, clients hide the feature and the endpoints
42	/// return an unrecognized response.
43	///
44	/// reloadable: yes
45	/// default: true
46	/// legacy: rendezvous_enabled
47	#[serde(default = "true_fn")]
48	pub enable: bool,
49
50	/// Limits rendezvous session payloads in bytes, with a default much larger
51	/// than normal QR sign-in handshake messages.
52	///
53	/// reloadable: yes
54	/// default: 4096
55	/// legacy: rendezvous_session_max_bytes
56	#[serde(default = "default_session_max_bytes")]
57	pub session_max_bytes: usize,
58
59	/// Sets the rendezvous session lifetime in seconds after its last write.
60	///
61	/// Each update restarts the window, but the device showing the QR code
62	/// times the whole sign-in against the expiry advertised at creation. The
63	/// default allows time for interactive account login on the approval page.
64	///
65	/// reloadable: yes
66	/// default: 600
67	/// legacy: rendezvous_session_ttl
68	#[serde(default = "default_session_ttl")]
69	pub session_ttl: u64,
70
71	/// Limits concurrent rendezvous sessions.
72	///
73	/// Creating beyond the limit evicts the oldest session instead of failing.
74	/// Zero retains one session so creation remains available.
75	///
76	/// reloadable: yes
77	/// default: 100
78	/// legacy: rendezvous_max_sessions
79	#[serde(default = "default_max_sessions")]
80	pub max_sessions: usize,
81
82	/// Requires an access token for
83	/// [MSC4388](https://github.com/matrix-org/matrix-spec-proposals/pull/4388)
84	/// session creation.
85	///
86	/// When enabled, discovery tells a client without a token that it cannot
87	/// create a session. The
88	/// [MSC4108](https://github.com/matrix-org/matrix-spec-proposals/pull/4108)
89	/// endpoint stays open in either mode.
90	///
91	/// reloadable: yes
92	/// default: true
93	/// legacy: rendezvous_authenticated_only
94	#[serde(default = "true_fn")]
95	pub authenticated_only: bool,
96
97	/// Sets the per-client-IP refill rate for
98	/// [MSC4388](https://github.com/matrix-org/matrix-spec-proposals/pull/4388)
99	/// rendezvous requests.
100	///
101	/// Zero is treated as one request per second.
102	///
103	/// reloadable: yes
104	/// default: 10
105	/// legacy: rendezvous_rc_per_second
106	#[serde(default = "default_rc_per_second")]
107	pub rc_per_second: u32,
108
109	/// Sets the token-bucket depth for the rendezvous request throttle under
110	/// [MSC4388](https://github.com/matrix-org/matrix-spec-proposals/pull/4388).
111	///
112	/// This is the requests one client IP can make in a burst before
113	/// `rendezvous.rc_per_second` governs replenishment. Zero is treated as
114	/// one.
115	///
116	/// reloadable: yes
117	/// default: 20
118	/// legacy: rendezvous_rc_burst_count
119	#[serde(default = "default_rc_burst_count")]
120	pub rc_burst_count: u32,
121}
122
123impl Default for Rendezvous {
124	fn default() -> Self {
125		Self {
126			enable: true_fn(),
127			session_max_bytes: default_session_max_bytes(),
128			session_ttl: default_session_ttl(),
129			max_sessions: default_max_sessions(),
130			authenticated_only: true_fn(),
131			rc_per_second: default_rc_per_second(),
132			rc_burst_count: default_rc_burst_count(),
133		}
134	}
135}
136
137fn default_session_max_bytes() -> usize { 4096 }
138
139fn default_session_ttl() -> u64 { 600 }
140
141fn default_max_sessions() -> usize { 100 }
142
143fn default_rc_per_second() -> u32 { 10 }
144
145fn default_rc_burst_count() -> u32 { 20 }