Skip to main content

tuwunel_service/integrity/
token_expiry.rs

1//! Access-token expiries a foreign database keeps in a column of its own.
2//!
3//! That column is keyed by device, while this server keeps the expiry beside the
4//! owner in the shared token column. A token the origin issued reads as never
5//! expiring here until its expiry is adopted, which waits for an OIDC provider
6//! the session can refresh against.
7
8use std::{fmt, str::from_utf8, sync::Arc};
9
10use futures::{FutureExt, Stream, TryStreamExt, future::BoxFuture};
11use ruma::{DeviceId, OwnedDeviceId, OwnedUserId, UserId};
12use tuwunel_core::{
13	Result,
14	result::NotFound,
15	smallstr::SmallString,
16	utils::{IterStream, TryReadyExt, stream::TryBroadbandExt},
17};
18use tuwunel_database::{KeyBuf, Map, SEP};
19
20use super::{Check, Report, ScanExt, Summary, leading_record, tally};
21use crate::{Services, users::device::TOKEN_LENGTH};
22
23type AccessToken = SmallString<[u8; TOKEN_LENGTH]>;
24
25type Column = Option<Arc<Map>>;
26
27type Findings = (Option<Finding>, Option<Finding>);
28
29pub(super) static CHECK: Check = Check {
30	name: "foreign-token-expiry",
31	about: "Where a foreign column records token expiries, no token it names stays in the \
32	        foreign shape while an OIDC provider is configured, and none carries the recorded \
33	        expiry while none is",
34	quiescent: true,
35	walk,
36};
37
38const ORIGIN_COLUMN: &str = "userdeviceid_tokenexpires";
39
40/// A token a foreign expiry column names whose expiry is not as this server needs
41/// it, or a row this check cannot read.
42///
43/// The adoption gives a token in the foreign shape its recorded expiry once an
44/// OIDC provider is configured, and the restore takes it back while none is.
45pub enum Finding {
46	/// The token is in the foreign shape while a provider could refresh it.
47	Unadopted {
48		/// The user the origin row names.
49		user_id: OwnedUserId,
50
51		/// The device the origin row names.
52		device_id: OwnedDeviceId,
53	},
54
55	/// The token is in the foreign shape, and its adoption waits for a provider.
56	Waiting {
57		/// The user the origin row names.
58		user_id: OwnedUserId,
59
60		/// The device the origin row names.
61		device_id: OwnedDeviceId,
62	},
63
64	/// The token carries the recorded expiry while no provider could refresh it.
65	Unrefreshable {
66		/// The user the origin row names.
67		user_id: OwnedUserId,
68
69		/// The device the origin row names.
70		device_id: OwnedDeviceId,
71	},
72
73	/// The origin row's key is not a user id and a device id.
74	UnparsableDevice {
75		/// The stored key.
76		key: KeyBuf,
77	},
78
79	/// The origin row's value is not an expiry.
80	UnparsableExpiry {
81		/// The user the origin row names.
82		user_id: OwnedUserId,
83
84		/// The device the origin row names.
85		device_id: OwnedDeviceId,
86	},
87
88	/// The device's stored token, or the value stored for that token, does not
89	/// decode.
90	UnparsableToken {
91		/// The user the origin row names.
92		user_id: OwnedUserId,
93
94		/// The device the origin row names.
95		device_id: OwnedDeviceId,
96	},
97
98	/// The origin row holds records past its device and expiry, which both
99	/// passes ignore.
100	ExtraRecords {
101		/// The user the origin row names.
102		user_id: OwnedUserId,
103
104		/// The device the origin row names.
105		device_id: OwnedDeviceId,
106	},
107}
108
109/// One row of the origin column, decoded.
110///
111/// The check and both passes over the column walk the same rows, so they agree
112/// on which devices the column names.
113pub(crate) enum Row {
114	/// The row names a device and records an expiry for its token.
115	Expiry {
116		/// The user the row names.
117		user_id: OwnedUserId,
118
119		/// The device the row names.
120		device_id: OwnedDeviceId,
121
122		/// The recorded expiry, in seconds since the epoch.
123		expires: u64,
124
125		/// Whether the row holds records past its device and expiry.
126		extra: bool,
127	},
128
129	/// The key is not a user id and a device id.
130	UnparsableDevice {
131		/// The stored key.
132		key: KeyBuf,
133	},
134
135	/// The value is not an expiry.
136	UnparsableExpiry {
137		/// The user the row names.
138		user_id: OwnedUserId,
139
140		/// The device the row names.
141		device_id: OwnedDeviceId,
142	},
143}
144
145/// The token an origin row's device holds here, as both passes read it.
146///
147/// Only a token in the foreign shape is adoptable, and only one carrying the
148/// recorded expiry is restorable.
149pub(crate) enum Token {
150	/// The device holds no access token here.
151	Absent,
152
153	/// The device's stored token does not decode.
154	Unparsable,
155
156	/// This server does not hold the device's token.
157	Unheld,
158
159	/// The value stored for the token does not decode.
160	UnparsableValue,
161
162	/// The stored value is in the foreign shape, with no expiry field.
163	Adoptable(Held),
164
165	/// The stored value carries the recorded expiry.
166	Adopted(Held),
167
168	/// The stored value is one this server wrote, or carries another expiry.
169	Kept,
170}
171
172/// A token this server holds, with the owner its stored value names.
173///
174/// A pass rewriting the token keeps that owner rather than the origin row's.
175pub(crate) struct Held {
176	/// The access token.
177	pub(crate) token: AccessToken,
178
179	/// The user the stored value names.
180	pub(crate) user_id: OwnedUserId,
181
182	/// The device the stored value names.
183	pub(crate) device_id: OwnedDeviceId,
184}
185
186/// Opens the origin column, if the database holds one.
187///
188/// A database no foreign server has opened holds none, which is no defect.
189pub fn origin(services: &Services) -> Result<Column> { services.db.open_cf(ORIGIN_COLUMN) }
190
191/// Streams each token the origin column names whose expiry is not as this
192/// server needs it.
193///
194/// Whether an OIDC provider is configured decides between a defect and a wait:
195/// a token in the foreign shape is unadopted with one and waiting without, and
196/// a token carrying the recorded expiry is reported only without one. A row
197/// holding records past its shape, or one this check cannot read, is reported
198/// too, while a device holding no token here and a token this server does not
199/// hold are not.
200#[tracing::instrument(level = "trace", skip_all)]
201pub fn scan<'a>(
202	services: &'a Services,
203	tokenexpires: &'a Arc<Map>,
204) -> impl Stream<Item = Result<Finding>> + Send + 'a {
205	let refreshable = services.oauth.get_server().is_ok();
206
207	rows(services, tokenexpires)
208		.broad_and_then(move |row| findings(services, row, refreshable))
209		.map_ok(|(verdict, extra)| verdict.into_iter().chain(extra).try_stream())
210		.try_flatten()
211}
212
213/// Streams every row of the origin column, decoded.
214///
215/// A row is split by hand and read as a release build decodes it, from its
216/// leading records with any more ignored, never reaching the record count a
217/// debug build asserts. Nothing is buffered, so a pass consuming the rows one at
218/// a time reads each token after its writes to earlier ones.
219#[tracing::instrument(level = "trace", skip_all)]
220pub(crate) fn rows<'a>(
221	services: &'a Services,
222	tokenexpires: &'a Arc<Map>,
223) -> impl Stream<Item = Result<Row>> + Send + 'a {
224	tokenexpires
225		.raw_scan()
226		.scanned(&services.server)
227		.ready_and_then(|(key, value)| Ok(row(key, value)))
228}
229
230/// Reads the token a device holds here and classifies its stored value against
231/// the recorded expiry.
232///
233/// Both point reads are made as this is called, so a pass calling it once per
234/// row decides each row against its own earlier writes. Only a failed read is
235/// an error.
236#[tracing::instrument(level = "debug", skip_all)]
237pub(crate) async fn token(
238	services: &Services,
239	user_id: &UserId,
240	device_id: &DeviceId,
241	expires: u64,
242) -> Result<Token> {
243	let Some(token) = services.db["userdeviceid_token"]
244		.qry(&(user_id, device_id))
245		.await
246		.optional()?
247	else {
248		return Ok(Token::Absent);
249	};
250
251	let Ok(token) = from_utf8(leading_record(&token).0) else {
252		return Ok(Token::Unparsable);
253	};
254
255	let Some(stored) = services.db["token_userdeviceid"]
256		.get(token)
257		.await
258		.optional()?
259	else {
260		return Ok(Token::Unheld);
261	};
262
263	Ok(classify(token, &stored, expires))
264}
265
266impl Report for Finding {
267	fn kind(&self) -> &'static str {
268		match self {
269			| Self::Unadopted { .. } => "unadopted-expiry",
270			| Self::Waiting { .. } => "waiting-for-provider",
271			| Self::Unrefreshable { .. } => "unrefreshable-expiry",
272			| Self::UnparsableDevice { .. } => "unparsable-device",
273			| Self::UnparsableExpiry { .. } => "unparsable-expiry",
274			| Self::UnparsableToken { .. } => "unparsable-token",
275			| Self::ExtraRecords { .. } => "extra-records",
276		}
277	}
278}
279
280impl fmt::Display for Finding {
281	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
282		match self {
283			| Self::Unadopted { user_id, device_id } => write!(
284				f,
285				"token of {user_id} device {device_id} does not carry its foreign expiry"
286			),
287			| Self::Waiting { user_id, device_id } => write!(
288				f,
289				"token of {user_id} device {device_id} waits for an OIDC provider to adopt its \
290				 foreign expiry"
291			),
292			| Self::Unrefreshable { user_id, device_id } => write!(
293				f,
294				"token of {user_id} device {device_id} carries its foreign expiry with no OIDC \
295				 provider to refresh it"
296			),
297			| Self::UnparsableDevice { key } => {
298				write!(f, "foreign token expiry key {} is not a device", key.escape_ascii())
299			},
300			| Self::UnparsableExpiry { user_id, device_id } => {
301				write!(f, "foreign token expiry of {user_id} device {device_id} does not decode")
302			},
303			| Self::UnparsableToken { user_id, device_id } => {
304				write!(f, "token of {user_id} device {device_id} does not decode")
305			},
306			| Self::ExtraRecords { user_id, device_id } => write!(
307				f,
308				"foreign token expiry of {user_id} device {device_id} holds records past its \
309				 shape"
310			),
311		}
312	}
313}
314
315// The opened column lives in this future, since the walk borrows it.
316fn walk(services: &Services, limit: usize) -> BoxFuture<'_, Result<Summary>> {
317	async move {
318		let Some(tokenexpires) = origin(services)? else {
319			return Ok(Summary::default());
320		};
321
322		tally(scan(services, &tokenexpires), limit).await
323	}
324	.boxed() // type-erasure boundary
325}
326
327#[tracing::instrument(level = "debug", skip_all)]
328async fn findings(services: &Services, row: Row, refreshable: bool) -> Result<Findings> {
329	let (user_id, device_id, expires, extra) = match row {
330		| Row::Expiry { user_id, device_id, expires, extra } =>
331			(user_id, device_id, expires, extra),
332		| Row::UnparsableDevice { key } =>
333			return Ok((Some(Finding::UnparsableDevice { key }), None)),
334		| Row::UnparsableExpiry { user_id, device_id } => {
335			return Ok((Some(Finding::UnparsableExpiry { user_id, device_id }), None));
336		},
337	};
338
339	let token = token(services, &user_id, &device_id, expires).await?;
340	let extra = extra.then(|| Finding::ExtraRecords {
341		user_id: user_id.clone(),
342		device_id: device_id.clone(),
343	});
344
345	let verdict = match (token, refreshable) {
346		| (Token::Adoptable(_), true) => Some(Finding::Unadopted { user_id, device_id }),
347		| (Token::Adoptable(_), false) => Some(Finding::Waiting { user_id, device_id }),
348		| (Token::Adopted(_), false) => Some(Finding::Unrefreshable { user_id, device_id }),
349		| (Token::Unparsable | Token::UnparsableValue, _) =>
350			Some(Finding::UnparsableToken { user_id, device_id }),
351		| (Token::Absent | Token::Unheld | Token::Kept | Token::Adopted(_), _) => None,
352	};
353
354	Ok((verdict, extra))
355}
356
357fn row(key: &[u8], value: &[u8]) -> Row {
358	let Some((user_id, device_id, extra)) = device(key) else {
359		return Row::UnparsableDevice { key: KeyBuf::from_slice(key) };
360	};
361
362	let (user_id, device_id) = (user_id.to_owned(), device_id.to_owned());
363	let expires = value
364		.get(..8)
365		.and_then(|expires| expires.try_into().ok());
366
367	match expires {
368		| Some(expires) => Row::Expiry {
369			user_id,
370			device_id,
371			expires: u64::from_be_bytes(expires),
372			extra: extra || value.len() > 8,
373		},
374		| None => Row::UnparsableExpiry { user_id, device_id },
375	}
376}
377
378/// Reads a key as a user id and a device id, as a release build decodes it.
379///
380/// A key with no separator reads as an empty device id, and any records past the
381/// second are ignored, which the flag reports.
382fn device(key: &[u8]) -> Option<(&UserId, &DeviceId, bool)> {
383	let (user_id, device_id, rest) = pair(key);
384	let device_id = from_utf8(device_id).ok()?;
385
386	from_utf8(user_id)
387		.ok()
388		.and_then(|user_id| <&UserId>::try_from(user_id).ok())
389		.map(|user_id| (user_id, device_id.into(), rest.is_some()))
390}
391
392/// Classifies a stored token value as both passes read it.
393///
394/// A foreign value is exactly an owner and a device, while every value this
395/// server writes has an expiry field, so a value with none is adoptable
396/// whatever its expiry would be. A value is restorable only when it carries
397/// exactly the recorded expiry, the adoption's own write.
398pub(super) fn classify(token: &str, stored: &[u8], expires: u64) -> Token {
399	let Some((user_id, device_id, carried)) = token_value(stored) else {
400		return Token::UnparsableValue;
401	};
402
403	let held = || Held {
404		token: token.into(),
405		user_id: user_id.to_owned(),
406		device_id: device_id.to_owned(),
407	};
408
409	let fields = user_id
410		.as_str()
411		.len()
412		.saturating_add(1)
413		.saturating_add(device_id.as_str().len());
414
415	let foreign = carried.is_none() && stored.len() == fields;
416
417	match carried {
418		| None if foreign => Token::Adoptable(held()),
419		| Some(carried) if carried == expires => Token::Adopted(held()),
420		| None | Some(_) => Token::Kept,
421	}
422}
423
424/// Reads a stored token value as a release build decodes it.
425///
426/// A value with no separator reads as an empty device id, an expiry field that
427/// is empty or begins with a separator reads as none, and anything past the
428/// eight bytes of an expiry is ignored. The expiry's own bytes can hold a
429/// separator, so only the first two separators split.
430fn token_value(stored: &[u8]) -> Option<(&UserId, &DeviceId, Option<u64>)> {
431	let (user_id, device_id, expiry) = pair(stored);
432	let device_id = from_utf8(device_id).ok()?;
433	let carried = match expiry {
434		| None | Some([] | [SEP, ..]) => None,
435		| Some(expiry) => Some(u64::from_be_bytes(expiry.get(..8)?.try_into().ok()?)),
436	};
437
438	from_utf8(user_id)
439		.ok()
440		.and_then(|user_id| <&UserId>::try_from(user_id).ok())
441		.map(|user_id| (user_id, device_id.into(), carried))
442}
443
444/// Splits a key or value into its first two records and whatever follows them,
445/// as a release build reads a pair.
446///
447/// With no separator the second record is empty, and the rest is `None` unless
448/// a separator ends the second record.
449fn pair(bytes: &[u8]) -> (&[u8], &[u8], Option<&[u8]>) {
450	let (first, rest) = leading_record(bytes);
451	let (second, rest) = rest.map(leading_record).unwrap_or_default();
452
453	(first, second, rest)
454}