Skip to main content

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}