Skip to main content

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() }