tuwunel_admin/user/mod.rs
1// Fires in clap's Subcommand derive output, which an item-level allow does not reach.
2#![expect(clippy::large_unopt_stack_frames)]
3
4mod add_email;
5mod clear_one_time_keys;
6mod create_user;
7mod deactivate;
8mod deactivate_all;
9mod del_email;
10mod delete_device;
11mod delete_room_tag;
12mod erasure;
13mod force_demote;
14mod force_join_all_local_users;
15mod force_join_list_of_local_users;
16mod force_join_room;
17mod force_leave_room;
18mod force_promote;
19mod get_room_tags;
20mod last_active;
21mod list_joined_rooms;
22mod list_users;
23mod make_user_admin;
24mod put_room_tag;
25mod redact_event;
26mod redact_recent;
27mod refresh_profile;
28mod reject_invites;
29mod reset_password;
30mod revoke_admin;
31mod set_profile_key;
32mod unerase;
33
34use std::num::NonZeroUsize;
35
36use clap::{ArgAction, ArgGroup, Subcommand, ValueEnum};
37use futures::FutureExt;
38use ruma::{OwnedDeviceId, OwnedEventId, OwnedRoomId, OwnedRoomOrAliasId, OwnedUserId, UserId};
39use tuwunel_core::Result;
40use tuwunel_service::{Services, profile::Propagation};
41
42use crate::admin_command_dispatch;
43
44const AUTO_GEN_PASSWORD_LENGTH: usize = 25;
45const BULK_JOIN_REASON: &str = "Bulk force joining this room as initiated by the server admin.";
46
47#[derive(Copy, Clone, Debug, Eq, PartialEq, ValueEnum)]
48pub(super) enum PropagateTo {
49 /// Send a member event to every joined room.
50 All,
51
52 /// Send a member event only to rooms whose current per-room value matches
53 /// the user's prior global value.
54 Unchanged,
55
56 /// Send no member events; update the global profile only.
57 None,
58}
59
60impl From<PropagateTo> for Propagation {
61 fn from(propagate_to: PropagateTo) -> Self {
62 match propagate_to {
63 | PropagateTo::All => Self::All,
64 | PropagateTo::Unchanged => Self::Unchanged,
65 | PropagateTo::None => Self::None,
66 }
67 }
68}
69
70#[admin_command_dispatch]
71#[derive(Debug, Subcommand)]
72pub(super) enum UserCommand {
73 /// - Create a new user
74 #[clap(alias = "create")]
75 CreateUser {
76 /// Username of the new user
77 username: String,
78 /// Password of the new user, if unspecified one is generated
79 password: Option<String>,
80 },
81
82 /// - Reset user password
83 ///
84 /// Logs out every device of the user unless `--no-logout-devices` is given.
85 ResetPassword {
86 /// Keep the user's devices logged in
87 #[arg(long = "no-logout-devices", action = ArgAction::SetFalse)]
88 logout_devices: bool,
89
90 /// Username of the user for whom the password should be reset
91 username: String,
92
93 /// New password for the user, if unspecified one is generated
94 password: Option<String>,
95 },
96
97 /// - Bind an email address to a local user without verification
98 AddEmail {
99 /// Local user to bind the email address to
100 username: String,
101 /// Email address to bind
102 address: String,
103 },
104
105 /// - Remove an email address binding from a local user
106 DelEmail {
107 /// Local user to remove the email address from
108 username: String,
109 /// Email address to remove
110 address: String,
111 },
112
113 /// - Deactivate a user
114 ///
115 /// User will be removed from all rooms by default.
116 /// Use --no-leave-rooms to not leave all rooms by default.
117 Deactivate {
118 #[arg(short, long)]
119 no_leave_rooms: bool,
120 user_id: String,
121 },
122
123 /// - Deactivate a list of users
124 ///
125 /// Recommended to use in conjunction with list-local-users.
126 ///
127 /// Users will be removed from joined rooms by default.
128 ///
129 /// Can be overridden with --no-leave-rooms.
130 ///
131 /// Removing a mass amount of users from a room may cause a significant
132 /// amount of leave events. The time to leave rooms may depend significantly
133 /// on joined rooms and servers.
134 ///
135 /// This command needs a newline separated list of users provided in a
136 /// Markdown code block below the command.
137 DeactivateAll {
138 #[arg(short, long)]
139 /// Does not leave any rooms the user is in on deactivation
140 no_leave_rooms: bool,
141 #[arg(short, long)]
142 /// Also deactivate admin accounts and will assume leave all rooms too
143 force: bool,
144 },
145
146 /// - Show the MSC4025 erasure state of a local user
147 Erasure {
148 user_id: String,
149 },
150
151 /// - Clear the MSC4025 erasure marker of a local user, restoring the
152 /// unredacted view of their events
153 Unerase {
154 user_id: String,
155 },
156
157 /// - Deletes a user's device.
158 DeleteDevice {
159 user_id: OwnedUserId,
160 device_id: OwnedDeviceId,
161 },
162
163 /// - Clear the one-time keys of every local device, or of one user's
164 /// devices
165 ///
166 /// Run it after restoring the database from a backup: keys claimed since
167 /// the backup was taken would otherwise be issued again, and messages
168 /// encrypted with them cannot be decrypted. Clients upload new keys at
169 /// their next sync, and fallback keys are kept; a device that never syncs,
170 /// such as a dehydrated device, relies on its fallback key until replaced.
171 ClearOneTimeKeys {
172 /// Only this local user's devices
173 username: Option<String>,
174 },
175
176 /// - List local users by recent activity.
177 LastActive {
178 #[arg(short, long)]
179 limit: Option<usize>,
180 },
181
182 /// - List local users in the database
183 #[clap(alias = "list")]
184 ListUsers,
185
186 /// - Lists all the rooms (local and remote) that the specified user is
187 /// joined in
188 ListJoinedRooms {
189 user_id: String,
190 },
191
192 /// - Manually join a local user to a room.
193 ForceJoinRoom {
194 user_id: String,
195 room: OwnedRoomOrAliasId,
196 },
197
198 /// - Manually leave a local user from a room.
199 ForceLeaveRoom {
200 user_id: String,
201 room_id: OwnedRoomOrAliasId,
202 },
203
204 /// - Reject all pending invites for a local user.
205 RejectInvites {
206 user_id: String,
207
208 /// Optional reason attached to each rejection.
209 #[arg(long)]
210 reason: Option<String>,
211 },
212
213 /// - Forces the specified user to drop their power levels to the room
214 /// default, if their permissions allow and the auth check permits
215 ForceDemote {
216 user_id: String,
217 room_id: OwnedRoomOrAliasId,
218 },
219
220 /// - Force promote
221 ForcePromote {
222 user_id: String,
223 room_id: OwnedRoomOrAliasId,
224 },
225
226 /// - Grant server-admin privileges to a user.
227 MakeUserAdmin {
228 user_id: String,
229 },
230
231 /// - Revoke server-admin privileges from a user.
232 RevokeAdmin {
233 user_id: String,
234 },
235
236 /// - Set a user profile key (display name, avatar url, etc) to a value
237 #[command(group(
238 ArgGroup::new("value_or_clear")
239 .required(true)
240 .args(["value", "clear"]),
241 ))]
242 SetProfileKey {
243 /// User for whom the profile key should be set; a remote user accepts
244 /// only `--clear`, without `--propagate-to`
245 user_id: String,
246
247 /// Profile key name (e.g. displayname, avatar_url, m.tz, or a custom
248 /// key)
249 key: String,
250
251 /// Value to set (used as string if not parseable as JSON)
252 value: Vec<String>,
253
254 /// Remove the profile key instead of setting a value; a remote user's
255 /// key returns on its next lookup if their server still serves it
256 #[arg(short, long)]
257 clear: bool,
258
259 /// How to propagate the change to the user's joined rooms
260 #[arg(short, long)]
261 propagate_to: Option<PropagateTo>,
262 },
263
264 /// - Re-fetch a remote user's profile, dropping cached fields their server
265 /// no longer serves
266 RefreshProfile {
267 /// Remote user whose cached profile should be refreshed
268 user_id: OwnedUserId,
269 },
270
271 /// - Puts a room tag for the specified user and room ID.
272 ///
273 /// This is primarily useful if you'd like to set your admin room
274 /// to the special "System Alerts" section in Element as a way to
275 /// permanently see your admin room without it being buried away in your
276 /// favourites or rooms. To do this, you would pass your user, your admin
277 /// room's internal ID, and the tag name `m.server_notice`.
278 PutRoomTag {
279 user_id: String,
280 room_id: OwnedRoomId,
281 tag: String,
282 },
283
284 /// - Deletes the room tag for the specified user and room ID
285 DeleteRoomTag {
286 user_id: String,
287 room_id: OwnedRoomId,
288 tag: String,
289 },
290
291 /// - Gets all the room tags for the specified user and room ID
292 GetRoomTags {
293 user_id: String,
294 room_id: OwnedRoomId,
295 },
296
297 /// - Attempts to forcefully redact the specified event ID from the sender
298 /// user
299 ///
300 /// This is only valid for local users
301 RedactEvent {
302 event_id: OwnedEventId,
303 },
304
305 /// - Redact a local user's most recent unredacted messages in a room.
306 ///
307 /// Counts plaintext and encrypted messages, excluding state events.
308 /// Redactions are sent as the original sender, newest first.
309 RedactRecent {
310 user_id: String,
311 room_id: OwnedRoomOrAliasId,
312 count: NonZeroUsize,
313 },
314
315 /// - Force joins a specified list of local users to join the specified
316 /// room.
317 ///
318 /// Specify a codeblock of usernames.
319 ///
320 /// Requires the `--yes-i-want-to-do-this` flag.
321 ForceJoinListOfLocalUsers {
322 room: OwnedRoomOrAliasId,
323
324 #[arg(long)]
325 yes_i_want_to_do_this: bool,
326 },
327
328 /// - Force joins all local users to the specified room.
329 ///
330 /// Requires the `--yes-i-want-to-do-this` flag.
331 ForceJoinAllLocalUsers {
332 room: OwnedRoomOrAliasId,
333
334 #[arg(long)]
335 yes_i_want_to_do_this: bool,
336 },
337}
338
339async fn deactivate_user(services: &Services, user_id: &UserId, no_leave_rooms: bool) -> Result {
340 if !no_leave_rooms {
341 services
342 .deactivate
343 .full_deactivate(user_id, false)
344 .boxed()
345 .await?;
346 } else {
347 services.users.deactivate_account(user_id).await?;
348 }
349
350 Ok(())
351}