Skip to main content

tuwunel_service/integrity/
account_status.rs

1//! Account states a foreign database keeps outside the password column.
2//!
3//! Some databases mark deactivation in a column of its own while leaving the
4//! hash in place, and spell an account an identity provider authenticates as an
5//! empty hash. This server reads both states from the password alone, so until
6//! they are adopted the first reads as active and the second as deactivated.
7
8use std::{fmt, str::from_utf8, sync::Arc};
9
10use futures::{
11	FutureExt, Stream, StreamExt, TryFutureExt, TryStreamExt, future::BoxFuture, stream::once,
12};
13use ruma::{OwnedUserId, ServerName, UserId};
14use tuwunel_core::{
15	Result,
16	result::NotFound,
17	smallstr::SmallString,
18	utils::{BoolExt, IterStream, TryReadyExt, option::OptionExt, stream::TryBroadbandExt},
19};
20use tuwunel_database::{KeyBuf, Map};
21
22use super::{Check, Report, ScanExt, Summary, leading_record, tally};
23use crate::{
24	Services,
25	migrations::{ADOPT_ACCOUNT_STATUS, local_user_id, marker_present},
26};
27
28type Findings = (Option<Finding>, Option<Finding>);
29
30type Text = SmallString<[u8; 48]>;
31
32pub(super) static CHECK: Check = Check {
33	name: "foreign-account-status",
34	about: "Reports only while the foreign account status adoption is unstamped: every account \
35	        here a foreign column marks deactivated has an empty password, and every one a \
36	        foreign provider subject names has a non-empty one unless so marked",
37	quiescent: true,
38	walk,
39};
40
41const DEACTIVATED_COLUMN: &str = "userid_deactivated";
42
43const SUBJECTS_COLUMN: &str = "openidsubject_localpart";
44
45/// The foreign account columns the database holds, opened.
46///
47/// A walk borrows the columns it reads, so whoever walks them holds these for as
48/// long as the walk runs.
49pub struct Columns {
50	/// The column marking deactivated accounts, keyed by user id.
51	pub deactivated: Option<Arc<Map>>,
52
53	/// The column naming the localpart each provider subject authenticates.
54	pub subjects: Option<Arc<Map>>,
55}
56
57/// An account whose password here does not say what a foreign column records,
58/// or a foreign row this check cannot read.
59///
60/// The adoption empties the password of a marked account and gives an unmarked
61/// passwordless one the sentinel.
62pub enum Finding {
63	/// A foreign column marks the account deactivated, while its password here is
64	/// not empty.
65	Deactivation {
66		/// The account.
67		user_id: OwnedUserId,
68	},
69
70	/// A foreign provider subject names the account, whose password here is empty
71	/// while no foreign column marks it deactivated.
72	Passwordless {
73		/// The account.
74		user_id: OwnedUserId,
75	},
76
77	/// A key of the deactivation column is not a user id.
78	UnparsableAccount {
79		/// The stored key.
80		key: KeyBuf,
81	},
82
83	/// A row of the subject column is not text.
84	UnparsableSubject {
85		/// The stored key.
86		key: KeyBuf,
87	},
88
89	/// A subject's localpart forms no user id here.
90	UnusableLocalpart {
91		/// The stored localpart.
92		localpart: Text,
93	},
94
95	/// A foreign row naming the account holds records past its shape, which the
96	/// adoption ignores.
97	ExtraRecords {
98		/// The account.
99		user_id: OwnedUserId,
100	},
101}
102
103/// An account the foreign deactivation column names, or the key of a row
104/// naming none.
105///
106/// The key names the row in a finding, and the adoption counts such a row as
107/// unreadable.
108pub(crate) type Account = Result<Named, KeyBuf>;
109
110/// The account a foreign row names, read as a release build decodes the row.
111///
112/// Records past the ones naming the account are ignored, which the flag reports.
113pub(crate) struct Named {
114	/// The account.
115	pub(crate) user_id: OwnedUserId,
116
117	/// Whether the row holds records past the ones naming the account.
118	pub(crate) extra: bool,
119}
120
121/// What a row of the foreign subject column names.
122///
123/// The adoption skips a subject naming no account here without counting it, and
124/// counts a row that is not text as unreadable.
125pub(crate) enum Subject {
126	/// The account the subject's localpart names here.
127	Account(Named),
128
129	/// The localpart forms no user id here.
130	UnusableLocalpart {
131		/// The stored localpart.
132		localpart: Text,
133	},
134
135	/// The row is not text.
136	Unparsable {
137		/// The stored key.
138		key: KeyBuf,
139	},
140}
141
142/// Opens each foreign account column the database holds.
143///
144/// A column the database lacks is left closed, since its absence is no defect.
145pub fn columns(services: &Services) -> Result<Columns> {
146	Ok(Columns {
147		deactivated: services.db.open_cf(DEACTIVATED_COLUMN)?,
148		subjects: services.db.open_cf(SUBJECTS_COLUMN)?,
149	})
150}
151
152/// Streams each account whose password does not say what a foreign column
153/// records, only while the adoption is unstamped.
154///
155/// A foreign row holding records past its shape, or one this check cannot read,
156/// is reported too. Once the adoption is stamped, local administration owns the
157/// password column and the foreign columns no longer describe it, so nothing is
158/// reported. An account with no password row here is never reported.
159#[tracing::instrument(level = "trace", skip_all)]
160pub fn scan<'a>(
161	services: &'a Services,
162	columns: &'a Columns,
163) -> impl Stream<Item = Result<Finding>> + Send + 'a {
164	once(marker_present(services, ADOPT_ACCOUNT_STATUS))
165		.map_ok(move |adopted| {
166			adopted
167				.is_false()
168				.then(|| findings(services, columns))
169		})
170		.ready_try_filter_map(Ok)
171		.try_flatten()
172}
173
174/// Streams every account the foreign deactivation column marks.
175///
176/// A key is read as a release build decodes it, as a user id in its leading
177/// record with any more ignored, and one naming none is named by its key
178/// instead. Nothing is buffered.
179#[tracing::instrument(level = "trace", skip_all)]
180pub(crate) fn deactivations<'a>(
181	services: &'a Services,
182	deactivated: &'a Arc<Map>,
183) -> impl Stream<Item = Result<Account>> + Send + 'a {
184	deactivated
185		.raw_scan()
186		.scanned(&services.server)
187		.ready_and_then(|(key, _)| Ok(account(key)))
188}
189
190/// Streams what every row of the foreign subject column names.
191///
192/// Each part of a row is read from its leading record, as a release build
193/// decodes it. Every row is yielded, including one whose localpart forms no user
194/// id here and one that is not text. Nothing is buffered.
195#[tracing::instrument(level = "trace", skip_all)]
196pub(crate) fn subjects<'a>(
197	services: &'a Services,
198	subjects: &'a Arc<Map>,
199) -> impl Stream<Item = Result<Subject>> + Send + 'a {
200	let server_name = services.globals.server_name();
201
202	subjects
203		.raw_scan()
204		.scanned(&services.server)
205		.ready_and_then(move |(key, value)| Ok(subject(key, value, server_name)))
206}
207
208/// Whether the account has a password row here that is not empty.
209///
210/// That is how a foreign deactivation reads here while the foreign hash survives.
211/// An account with no row is not one, and a failed read is an error.
212#[tracing::instrument(level = "debug", skip_all)]
213pub(crate) async fn hash_kept(services: &Services, user_id: &UserId) -> Result<bool> {
214	hash_empty(services, user_id)
215		.map_ok(|empty| empty == Some(false))
216		.await
217}
218
219/// Whether the account's password here is empty while no foreign column marks
220/// it deactivated.
221///
222/// The empty password a foreign database gives an account authenticated
223/// elsewhere is the byte pattern this server writes for a deactivation, so the
224/// foreign marker is the only thing separating them. A row neither side can
225/// read is reported rather than guessed at.
226#[tracing::instrument(level = "debug", skip_all)]
227pub(crate) async fn unmarked_passwordless(
228	services: &Services,
229	deactivated: Option<&Arc<Map>>,
230	user_id: &UserId,
231) -> Result<bool> {
232	let passwordless = hash_empty(services, user_id)
233		.map_ok(|empty| empty == Some(true))
234		.await?;
235
236	let marked = match deactivated
237		.map_async(|deactivated| deactivated.exists(user_id))
238		.await
239	{
240		| None => false,
241		| Some(Ok(())) => true,
242		| Some(Err(e)) if e.is_not_found() => false,
243		| Some(Err(e)) => return Err(e),
244	};
245
246	Ok(passwordless && !marked)
247}
248
249impl Report for Finding {
250	fn kind(&self) -> &'static str {
251		match self {
252			| Self::Deactivation { .. } => "unadopted-deactivation",
253			| Self::Passwordless { .. } => "unadopted-passwordless",
254			| Self::UnparsableAccount { .. } => "unparsable-account",
255			| Self::UnparsableSubject { .. } => "unparsable-subject",
256			| Self::UnusableLocalpart { .. } => "unusable-localpart",
257			| Self::ExtraRecords { .. } => "extra-records",
258		}
259	}
260}
261
262impl fmt::Display for Finding {
263	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
264		match self {
265			| Self::Deactivation { user_id } => {
266				write!(f, "{user_id} is deactivated in a foreign column but has a password here")
267			},
268			| Self::Passwordless { user_id } => write!(
269				f,
270				"{user_id} is authenticated by a foreign provider but reads as deactivated here"
271			),
272			| Self::UnparsableAccount { key } => {
273				write!(f, "foreign deactivation key {} is not a user id", key.escape_ascii())
274			},
275			| Self::UnparsableSubject { key } => {
276				write!(f, "foreign provider subject {} is not text", key.escape_ascii())
277			},
278			| Self::UnusableLocalpart { localpart } => {
279				write!(
280					f,
281					"foreign provider subject localpart {localpart:?} forms no user id here"
282				)
283			},
284			| Self::ExtraRecords { user_id } => {
285				write!(f, "a foreign row naming {user_id} holds records past its shape")
286			},
287		}
288	}
289}
290
291// The opened columns live in this future, since the walk borrows them.
292fn walk(services: &Services, limit: usize) -> BoxFuture<'_, Result<Summary>> {
293	async move {
294		let columns = columns(services)?;
295
296		tally(scan(services, &columns), limit).await
297	}
298	.boxed() // type-erasure boundary
299}
300
301fn findings<'a>(
302	services: &'a Services,
303	columns: &'a Columns,
304) -> impl Stream<Item = Result<Finding>> + Send + 'a {
305	let deactivated = columns.deactivated.as_ref();
306
307	let marked = deactivated
308		.stream()
309		.flat_map(move |column| deactivations(services, column))
310		.broad_and_then(move |account| deactivation(services, account));
311
312	let authenticated = columns
313		.subjects
314		.as_ref()
315		.stream()
316		.flat_map(move |column| subjects(services, column))
317		.broad_and_then(move |subject| passwordless(services, deactivated, subject));
318
319	marked
320		.chain(authenticated)
321		.map_ok(|(verdict, extra)| verdict.into_iter().chain(extra).try_stream())
322		.try_flatten()
323}
324
325#[tracing::instrument(level = "debug", skip_all)]
326async fn deactivation(services: &Services, account: Account) -> Result<Findings> {
327	let Named { user_id, extra } = match account {
328		| Ok(named) => named,
329		| Err(key) => return Ok((Some(Finding::UnparsableAccount { key }), None)),
330	};
331
332	let kept = hash_kept(services, &user_id).await?;
333	let extra = extra.then(|| Finding::ExtraRecords { user_id: user_id.clone() });
334	let verdict = kept.then_some(Finding::Deactivation { user_id });
335
336	Ok((verdict, extra))
337}
338
339#[tracing::instrument(level = "debug", skip_all)]
340async fn passwordless(
341	services: &Services,
342	deactivated: Option<&Arc<Map>>,
343	subject: Subject,
344) -> Result<Findings> {
345	let Named { user_id, extra } = match subject {
346		| Subject::Account(named) => named,
347		| Subject::UnusableLocalpart { localpart } => {
348			return Ok((Some(Finding::UnusableLocalpart { localpart }), None));
349		},
350		| Subject::Unparsable { key } =>
351			return Ok((Some(Finding::UnparsableSubject { key }), None)),
352	};
353
354	let passwordless = unmarked_passwordless(services, deactivated, &user_id).await?;
355	let extra = extra.then(|| Finding::ExtraRecords { user_id: user_id.clone() });
356	let verdict = passwordless.then_some(Finding::Passwordless { user_id });
357
358	Ok((verdict, extra))
359}
360
361fn account(key: &[u8]) -> Account {
362	let (user_id, rest) = leading_record(key);
363
364	from_utf8(user_id)
365		.ok()
366		.and_then(|user_id| <&UserId>::try_from(user_id).ok())
367		.map(|user_id| Named {
368			user_id: user_id.to_owned(),
369			extra: rest.is_some(),
370		})
371		.ok_or_else(|| KeyBuf::from_slice(key))
372}
373
374fn subject(key: &[u8], value: &[u8], server_name: &ServerName) -> Subject {
375	let ((subject, key_rest), (localpart, value_rest)) =
376		(leading_record(key), leading_record(value));
377
378	let (Ok(_), Ok(localpart)) = (from_utf8(subject), from_utf8(localpart)) else {
379		return Subject::Unparsable { key: KeyBuf::from_slice(key) };
380	};
381
382	match local_user_id(localpart, server_name) {
383		| Some(user_id) => Subject::Account(Named {
384			user_id,
385			extra: key_rest.or(value_rest).is_some(),
386		}),
387		| None => Subject::UnusableLocalpart { localpart: localpart.into() },
388	}
389}
390
391/// Whether the account's stored password is empty, or `None` when it has no
392/// row at all.
393///
394/// Both adoptions need the three states kept apart: a read failure is neither
395/// an active account nor a deactivated one, and mistaking it for either is how a
396/// pass that runs once leaves an account in the wrong state for good.
397#[tracing::instrument(level = "debug", skip_all)]
398async fn hash_empty(services: &Services, user_id: &UserId) -> Result<Option<bool>> {
399	services.db["userid_password"]
400		.get(user_id)
401		.map_ok(|hash| hash.is_empty())
402		.await
403		.optional()
404}