Skip to main content

tuwunel_service/integrity/
email_bindings.rs

1//! Email bindings a foreign database keeps in a column of its own.
2//!
3//! Some databases hold one address per localpart there rather than in the
4//! third-party identifier store this server reads, so until the binding is
5//! adopted the address looks unclaimed here.
6
7use std::{fmt, str::from_utf8, sync::Arc};
8
9use futures::{FutureExt, Stream, TryStreamExt, future::BoxFuture, stream::once};
10use ruma::{OwnedUserId, ServerName, UserId};
11use tuwunel_core::{
12	Result,
13	result::NotFound,
14	smallstr::SmallString,
15	utils::{BoolExt, IterStream, TryReadyExt, stream::TryBroadbandExt},
16};
17use tuwunel_database::{KeyBuf, Map};
18
19use super::{Check, Report, ScanExt, Summary, leading_record, tally};
20use crate::{
21	Services,
22	migrations::{ADOPT_EMAIL_BINDINGS, local_user_id, marker_present},
23	threepid::canonicalize_email,
24};
25
26type Text = SmallString<[u8; 48]>;
27
28type Column = Option<Arc<Map>>;
29
30type Findings = (Option<Finding>, Option<Finding>);
31
32pub(super) static CHECK: Check = Check {
33	name: "foreign-email-bindings",
34	about: "Reports only while the foreign email binding adoption is unstamped: every address a \
35	        foreign column binds to an account here other than the server's own is bound to \
36	        that account",
37	quiescent: true,
38	walk,
39};
40
41const COLUMN: &str = "localpart_email";
42
43/// A foreign binding whose address is not bound to its account here, or a row
44/// this check cannot read.
45///
46/// The adoption binds each address held by no account, and leaves one held by
47/// another account, which the store cannot bind twice.
48pub enum Finding {
49	/// The address is bound to no account here.
50	Unadopted {
51		/// The account the binding names.
52		user_id: OwnedUserId,
53	},
54
55	/// The address is bound to another account here.
56	Claimed {
57		/// The account the binding names.
58		user_id: OwnedUserId,
59
60		/// The account holding the address.
61		owner: OwnedUserId,
62	},
63
64	/// The localpart forms no user id here.
65	UnusableLocalpart {
66		/// The stored localpart.
67		localpart: Text,
68	},
69
70	/// The address is not one an account can be bound to.
71	UnusableAddress {
72		/// The account the binding names.
73		user_id: OwnedUserId,
74	},
75
76	/// The row is not text.
77	Unparsable {
78		/// The stored key.
79		key: KeyBuf,
80	},
81
82	/// The account holding the address here does not decode.
83	UnparsableOwner {
84		/// The account the binding names.
85		user_id: OwnedUserId,
86	},
87
88	/// The row holds records past its localpart and address, which the adoption
89	/// ignores.
90	ExtraRecords {
91		/// The account the binding names.
92		user_id: OwnedUserId,
93	},
94}
95
96/// One row of the foreign binding column, decoded.
97///
98/// The check and the adoption walk the same rows, so they agree on which
99/// bindings the column holds.
100pub(crate) enum Row {
101	/// The account the localpart names here, with the address bound to it.
102	Binding {
103		/// The account the localpart names.
104		user_id: OwnedUserId,
105
106		/// The address as stored.
107		address: Text,
108
109		/// Whether the row holds records past its localpart and address.
110		extra: bool,
111	},
112
113	/// The localpart forms no user id here.
114	UnusableLocalpart {
115		/// The stored localpart.
116		localpart: Text,
117	},
118
119	/// The row is not text.
120	Unparsable {
121		/// The stored key.
122		key: KeyBuf,
123	},
124}
125
126/// What a foreign binding's account and address are here, as the adoption reads
127/// them.
128///
129/// Only a binding with an account and a usable address goes on to be bound.
130pub(crate) enum Bindable {
131	/// No account holds the localpart here, or it is the server's own.
132	NoAccount,
133
134	/// The address does not canonicalize.
135	UnusableAddress,
136
137	/// The address in its canonical form.
138	Canonical(String),
139}
140
141/// Opens the foreign binding column, if the database holds one.
142///
143/// A database no foreign server has opened holds none, which is no defect.
144pub fn column(services: &Services) -> Result<Column> { services.db.open_cf(COLUMN) }
145
146/// Streams each foreign binding whose address is not bound to its account here,
147/// only while the adoption is unstamped.
148///
149/// A row holding records past its shape, or one this check cannot read, is
150/// reported too.
151/// Once the adoption is stamped, local administration owns the bindings and the
152/// foreign column no longer describes them, so nothing is reported. A binding
153/// naming no account here is never reported. Only the reverse row resolving the
154/// address is read, not the account's own listing.
155#[tracing::instrument(level = "trace", skip_all)]
156pub fn scan<'a>(
157	services: &'a Services,
158	localpart_email: &'a Arc<Map>,
159) -> impl Stream<Item = Result<Finding>> + Send + 'a {
160	once(marker_present(services, ADOPT_EMAIL_BINDINGS))
161		.map_ok(move |adopted| {
162			adopted
163				.is_false()
164				.then(|| rows(services, localpart_email))
165		})
166		.ready_try_filter_map(Ok)
167		.try_flatten()
168		.broad_and_then(|row| findings(services, row))
169		.map_ok(|(verdict, extra)| verdict.into_iter().chain(extra).try_stream())
170		.try_flatten()
171}
172
173/// Streams every row of the foreign binding column, decoded.
174///
175/// The localpart and the address are each read from their leading record, as a
176/// release build decodes them. Nothing is buffered, so a pass consuming the rows one at a time decides each
177/// binding after its writes for earlier ones, as when two addresses fold onto
178/// one canonical form.
179#[tracing::instrument(level = "trace", skip_all)]
180pub(crate) fn rows<'a>(
181	services: &'a Services,
182	localpart_email: &'a Arc<Map>,
183) -> impl Stream<Item = Result<Row>> + Send + 'a {
184	let server_name = services.globals.server_name();
185
186	localpart_email
187		.raw_scan()
188		.scanned(&services.server)
189		.ready_and_then(move |(key, value)| Ok(row(key, value, server_name)))
190}
191
192/// Reads whether a binding's account is one an address can be bound to, and the
193/// address's canonical form.
194///
195/// A deactivated account still reserves its address, since neither server
196/// unhooks a binding on deactivation. Only a failed read is an error.
197#[tracing::instrument(level = "debug", skip_all)]
198pub(crate) async fn bindable(
199	services: &Services,
200	user_id: &UserId,
201	address: &str,
202) -> Result<Bindable> {
203	match services.db["userid_password"].get(user_id).await {
204		| Ok(_) if user_id != services.globals.server_user => (),
205		| Ok(_) => return Ok(Bindable::NoAccount),
206		| Err(e) if e.is_not_found() => return Ok(Bindable::NoAccount),
207		| Err(e) => return Err(e),
208	}
209
210	let bindable = canonicalize_email(address)
211		.map(Bindable::Canonical)
212		.unwrap_or(Bindable::UnusableAddress);
213
214	Ok(bindable)
215}
216
217impl Report for Finding {
218	fn kind(&self) -> &'static str {
219		match self {
220			| Self::Unadopted { .. } => "unadopted-binding",
221			| Self::Claimed { .. } => "claimed-elsewhere",
222			| Self::UnusableLocalpart { .. } => "unusable-localpart",
223			| Self::UnusableAddress { .. } => "unusable-address",
224			| Self::Unparsable { .. } => "unparsable-binding",
225			| Self::UnparsableOwner { .. } => "unparsable-owner",
226			| Self::ExtraRecords { .. } => "extra-records",
227		}
228	}
229}
230
231impl fmt::Display for Finding {
232	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
233		match self {
234			| Self::Unadopted { user_id } => {
235				write!(
236					f,
237					"the address a foreign column binds to {user_id} is bound to no one here"
238				)
239			},
240			| Self::Claimed { user_id, owner } => write!(
241				f,
242				"the address a foreign column binds to {user_id} is bound to {owner} here"
243			),
244			| Self::UnusableLocalpart { localpart } => {
245				write!(f, "foreign binding localpart {localpart:?} forms no user id here")
246			},
247			| Self::UnusableAddress { user_id } => {
248				write!(f, "the address a foreign column binds to {user_id} is not an address")
249			},
250			| Self::Unparsable { key } => {
251				write!(f, "foreign binding {} is not text", key.escape_ascii())
252			},
253			| Self::UnparsableOwner { user_id } => write!(
254				f,
255				"the account holding the address a foreign column binds to {user_id} does not \
256				 decode"
257			),
258			| Self::ExtraRecords { user_id } => {
259				write!(f, "the foreign binding of {user_id} holds records past its shape")
260			},
261		}
262	}
263}
264
265// The opened column lives in this future, since the walk borrows it.
266fn walk(services: &Services, limit: usize) -> BoxFuture<'_, Result<Summary>> {
267	async move {
268		let Some(localpart_email) = column(services)? else {
269			return Ok(Summary::default());
270		};
271
272		tally(scan(services, &localpart_email), limit).await
273	}
274	.boxed() // type-erasure boundary
275}
276
277#[tracing::instrument(level = "debug", skip_all)]
278async fn findings(services: &Services, row: Row) -> Result<Findings> {
279	let (user_id, address, extra) = match row {
280		| Row::Binding { user_id, address, extra } => (user_id, address, extra),
281		| Row::UnusableLocalpart { localpart } => {
282			return Ok((Some(Finding::UnusableLocalpart { localpart }), None));
283		},
284		| Row::Unparsable { key } => return Ok((Some(Finding::Unparsable { key }), None)),
285	};
286
287	let extra = extra.then(|| Finding::ExtraRecords { user_id: user_id.clone() });
288	let verdict = verdict(services, user_id, &address).await?;
289
290	Ok((verdict, extra))
291}
292
293#[tracing::instrument(level = "debug", skip_all)]
294async fn verdict(
295	services: &Services,
296	user_id: OwnedUserId,
297	address: &str,
298) -> Result<Option<Finding>> {
299	let email_canon = match bindable(services, &user_id, address).await? {
300		| Bindable::NoAccount => return Ok(None),
301		| Bindable::UnusableAddress => return Ok(Some(Finding::UnusableAddress { user_id })),
302		| Bindable::Canonical(email_canon) => email_canon,
303	};
304
305	let bound = services.db["email_userid"]
306		.get(&email_canon)
307		.await
308		.optional()?;
309
310	let finding = match bound.as_deref().map(owner) {
311		| None => Some(Finding::Unadopted { user_id }),
312		| Some(Some(owner)) if owner == user_id => None,
313		| Some(Some(owner)) => Some(Finding::Claimed { user_id, owner: owner.to_owned() }),
314		| Some(None) => Some(Finding::UnparsableOwner { user_id }),
315	};
316
317	Ok(finding)
318}
319
320fn row(key: &[u8], value: &[u8], server_name: &ServerName) -> Row {
321	let ((localpart, key_rest), (address, value_rest)) =
322		(leading_record(key), leading_record(value));
323
324	let (Ok(localpart), Ok(address)) = (from_utf8(localpart), from_utf8(address)) else {
325		return Row::Unparsable { key: KeyBuf::from_slice(key) };
326	};
327
328	match local_user_id(localpart, server_name) {
329		| Some(user_id) => Row::Binding {
330			user_id,
331			address: address.into(),
332			extra: key_rest.or(value_rest).is_some(),
333		},
334		| None => Row::UnusableLocalpart { localpart: localpart.into() },
335	}
336}
337
338fn owner(value: &[u8]) -> Option<&UserId> {
339	from_utf8(leading_record(value).0)
340		.ok()
341		.and_then(|owner| <&UserId>::try_from(owner).ok())
342}