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 }