tuwunel_core/config/registration.rs
1//! Configures account registration and initial user setup.
2//!
3//! Registration tokens and shared secrets control separate account-creation
4//! paths. New-user defaults and guest policy govern initial account
5//! behavior.
6
7use serde::Deserialize;
8use tuwunel_macros::config_example_generator;
9
10use super::{OwnedRoomOrAliasId, PathBuf, RegexSet, true_fn};
11
12/// Account registration
13///
14/// Controls who may create an ordinary account through `/register` or the
15/// built-in OIDC login page, and how new accounts are set up. Off by
16/// default. Terms users must accept live in
17/// `[global.registration_terms.<ID>]`, and email verification in
18/// `[global.smtp]`.
19///
20/// With `enable`, startup also requires a registration token (`token` or
21/// `token_file`) or a required email stage
22/// (`smtp.require_email_for_registration` with `smtp.connection_uri`).
23/// Without one the server refuses to start unless
24/// `yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse`
25/// is true, which startup warns about.
26///
27/// Minimal example (token-gated):
28///
29/// ```toml
30/// [global.registration]
31/// enable = true
32/// token_file = "/etc/tuwunel/.reg_token"
33/// ```
34///
35/// Tips:
36/// - Startup refuses an empty `token` and an empty or unreadable
37/// `token_file`; both may be set. Tokens from `!admin token issue` also
38/// work at registration but do not satisfy the startup check.
39/// - Password registration also needs `authentication.login.with_password`.
40/// Identity providers (their `registration` key), `jwt.register_user` and
41/// LDAP create accounts without `enable`, and `shared_secret` enables
42/// `/_synapse/admin/v1/register` independently of it.
43#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
44// No Debug: secrets are reachable from this section.
45#[derive(Clone, Deserialize)]
46#[config_example_generator(
47 filename = "tuwunel-example.toml",
48 section = "global.registration",
49 group = "true",
50 ignore = "guests"
51)]
52pub struct Registration {
53 /// Appends text to a new user's display name at registration, separated by
54 /// a space.
55 ///
56 /// Conduit used a lightning-bolt emoji for this suffix. Set to an empty
57 /// string to disable it. It is left out when the name leaves no room for
58 /// it under the 256-character display name limit.
59 ///
60 /// reloadable: yes
61 /// default: "💕"
62 /// legacy: new_user_displayname_suffix
63 #[serde(default = "default_displayname_suffix")]
64 pub displayname_suffix: String,
65
66 /// Enables ordinary new account registration.
67 ///
68 /// When false, ordinary registration is disabled; appservice registration
69 /// is exempt from this switch. Without a configured token, registration
70 /// without a second step requires
71 /// `registration.yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse`
72 /// to be true. For token-only registration, configure `registration.token`
73 /// or `registration.token_file`. Ordinary registration also requires
74 /// `authentication.login.with_password`.
75 ///
76 /// reloadable: yes
77 /// legacy: allow_registration
78 #[serde(default)]
79 pub enable: bool,
80
81 /// Opens registration to anyone without restrictions.
82 ///
83 /// This makes the server vulnerable to abuse.
84 ///
85 /// reloadable: yes
86 /// legacy: yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse
87 #[serde(default)]
88 pub yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse: bool,
89
90 /// Requires new users to supply this static token when creating an
91 /// account.
92 ///
93 /// Configure this value or use `registration.token_file`. If unset while
94 /// `registration.enable` is true, unrestricted registration requires
95 /// `registration.yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse`
96 /// to be true.
97 ///
98 /// reloadable: yes
99 /// example: "o&^uCtes4HPf0Vu@F20jQeeWE7"
100 ///
101 /// display: sensitive
102 /// legacy: registration_token
103 pub token: Option<String>,
104
105 /// Reads additional registration tokens from a file.
106 ///
107 /// Separate multiple tokens with whitespace. The file must be nonempty and
108 /// accessible to the server.
109 ///
110 /// reloadable: yes
111 /// example: "/etc/tuwunel/.reg_token"
112 /// legacy: registration_token_file
113 pub token_file: Option<PathBuf>,
114
115 /// Enables out-of-band account creation with a pre-shared secret.
116 ///
117 /// The Synapse-style `/_synapse/admin/v1/register` endpoint requires a
118 /// build with `synapse_admin` and is not routed when MAS delegation is
119 /// active. Configure this value or `registration.shared_secret_file`;
120 /// requests authenticate with HMAC-SHA1 keyed by the resolved secret and
121 /// bypass UIAA. The file takes precedence when successfully read. Use a
122 /// high-entropy secret of at least 32 bytes and protect it like a server
123 /// admin's access token.
124 ///
125 /// reloadable: yes
126 /// example: "kZ2hN5pQ8wXyL4mR7tBfCgJxV3aD6sE1u"
127 ///
128 /// display: sensitive
129 /// legacy: registration_shared_secret
130 pub shared_secret: Option<String>,
131
132 /// Reads the registration shared secret from a file.
133 ///
134 /// This takes precedence over `registration.shared_secret` and falls back
135 /// to it only when the file cannot be read. Surrounding whitespace is
136 /// trimmed, so a trailing newline is not part of the secret. A present but
137 /// blank file resolves to no secret without falling back.
138 ///
139 /// reloadable: yes
140 /// example: "/etc/tuwunel/.reg_shared_secret"
141 /// legacy: registration_shared_secret_file
142 pub shared_secret_file: Option<PathBuf>,
143
144 #[expect(clippy::doc_link_with_quotes)]
145 /// Lists room IDs or aliases that eligible newly registered users
146 /// automatically join.
147 ///
148 /// The server must already participate in each room, and the user must
149 /// satisfy its normal join authorization rules, including for restricted
150 /// rooms. Rooms are processed in configured order, so an earlier join can
151 /// satisfy a later room's membership requirement. Appservice registrations
152 /// are excluded; guests require `registration.guests.allow_auto_join_rooms`.
153 /// Failed joins are logged without failing registration.
154 ///
155 /// reloadable: yes
156 /// example: ["#tuwunel:grin.hu",
157 /// "!l2xV0sd51lraysuRcsWVECge4NULaH3g-ou95vgDgiM"]
158 ///
159 /// default: []
160 /// legacy: auto_join_rooms
161 #[serde(default = "Vec::new")]
162 pub auto_join_rooms: Vec<OwnedRoomOrAliasId>,
163
164 /// Forbids usernames matching listed patterns.
165 ///
166 /// Use regular expressions or plain words for containment matches, as in
167 /// the example. Checks run during username-availability requests and
168 /// registration, with startup warnings for existing local users whose
169 /// names match.
170 ///
171 /// reloadable: yes
172 /// example: ["administrator", "b[a4]dusernam[3e]", "badphrase"]
173 ///
174 /// default: []
175 /// legacy: forbidden_usernames
176 #[serde(default, with = "serde_regex")]
177 pub forbidden_usernames: RegexSet,
178
179 /// Grants admin privileges during eligible registration by joining the
180 /// user to the admin room.
181 ///
182 /// The registering user must be neither a guest nor an appservice user,
183 /// and the registration caller must permit the first-user grant. The admin
184 /// room must exist and have exactly one joined member, normally the server
185 /// user; an empty admin room does not qualify.
186 ///
187 /// reloadable: yes
188 /// default: true
189 /// legacy: grant_admin_to_first_user
190 #[serde(default = "true_fn")]
191 pub grant_admin_to_first_user: bool,
192
193 /// Settings for registration guests.
194 ///
195 /// display: section
196 #[serde(default)]
197 pub guests: Guests,
198}
199
200/// Guest accounts
201///
202/// Guests are password-less accounts with a generated user ID that a client
203/// can create without credentials. Off by default.
204///
205/// Tips:
206/// - Guest registration also requires `registration.enable`, then skips
207/// interactive auth (token, email and terms stages), so enabling it on a
208/// token-gated server lets anyone create guest accounts.
209/// - New guests are announced in the admin room only with
210/// `admin.room.log_guest_registrations`.
211#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
212#[derive(Clone, Copy, Debug, Deserialize, Default)]
213#[config_example_generator(
214 filename = "tuwunel-example.toml",
215 section = "global.registration.guests",
216 group = "true"
217)]
218pub struct Guests {
219 /// Allows registrations with user type "guest".
220 ///
221 /// reloadable: yes
222 /// legacy: allow_guest_registration
223 #[serde(default)]
224 pub enable: bool,
225
226 /// Allows guest users to automatically join rooms listed in
227 /// `registration.auto_join_rooms`.
228 ///
229 /// reloadable: yes
230 /// legacy: allow_guests_auto_join_rooms
231 #[serde(default)]
232 pub allow_auto_join_rooms: bool,
233}
234
235impl Default for Registration {
236 fn default() -> Self {
237 Self {
238 displayname_suffix: default_displayname_suffix(),
239 enable: Default::default(),
240 yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse:
241 Default::default(),
242 token: None,
243 token_file: None,
244 shared_secret: None,
245 shared_secret_file: None,
246 auto_join_rooms: Vec::new(),
247 forbidden_usernames: Default::default(),
248 grant_admin_to_first_user: true_fn(),
249 guests: Guests::default(),
250 }
251 }
252}
253
254fn default_displayname_suffix() -> String { "💕".to_owned() }