Skip to main content

tuwunel_service/membership/
knock.rs

1use std::{borrow::Borrow, iter::once};
2
3use futures::{FutureExt, StreamExt, TryFutureExt};
4use ruma::{
5	CanonicalJsonObject, CanonicalJsonValue, OwnedEventId, OwnedServerName, RoomId,
6	RoomOrAliasId, RoomVersionId, UserId,
7	api::federation::{
8		self,
9		membership::{
10			RawStrippedState,
11			create_knock_event::v1::{
12				Request as SendKnockRequest, Response as SendKnockResponse,
13			},
14		},
15	},
16	canonical_json::to_canonical_value,
17	events::{
18		AnyStrippedStateEvent, StateEventType,
19		receipt::ReceiptThread,
20		room::member::{MembershipState, RoomMemberEventContent},
21	},
22	room_version_rules::RoomVersionRules,
23	serde::Raw,
24	signatures::Verified,
25};
26use tuwunel_core::{
27	Err, Result, async_noinline, at, debug_info, debug_warn, err, implement, info, trace,
28	utils::{self, IterStream, result::LogErr, stream::WidebandExt},
29	warn,
30};
31use tuwunel_matrix::{
32	Event, PduCount,
33	event::gen_event_id,
34	pdu::{PduBuilder, PduEvent},
35	room_version::rules as room_version_rules,
36};
37
38use super::{
39	Service, StrippedCreateVerdict, dedup_stripped_state, enforce_stripped_create,
40	stripped_state::occupies_cell, v12_room_ids, without_member,
41};
42use crate::{
43	membership::join::get_servers_for_room,
44	rooms::{state::RoomMutexGuard, state_cache::MembershipUpdate},
45};
46
47/// The stripped state a knock records as the room's summary for its user.
48///
49/// It is presentation data the user's client shows, never room state.
50type Summary = Vec<Raw<AnyStrippedStateEvent>>;
51
52#[implement(Service)]
53// cross-crate codegen firewall
54#[async_noinline]
55#[tracing::instrument(
56	name = "knock",
57	level = "debug",
58	skip_all,
59	fields(%sender_user, %room_id)
60)]
61pub async fn knock<'a>(
62	&'a self,
63	sender_user: &'a UserId,
64	room_id: &'a RoomId,
65	orig_server_name: Option<&'a RoomOrAliasId>,
66	reason: Option<String>,
67	servers: &'a [OwnedServerName],
68	state_lock: &'a RoomMutexGuard,
69) -> Result {
70	let servers =
71		get_servers_for_room(&self.services, sender_user, room_id, orig_server_name, servers)
72			.await?;
73
74	if self
75		.services
76		.state_cache
77		.is_invited(sender_user, room_id)
78		.await
79	{
80		debug_warn!(%sender_user, %room_id, "Invited user attempted to knock.");
81		return Err!(Request(Forbidden(
82			"You cannot knock on a room you are already invited/accepted to."
83		)));
84	}
85
86	if self
87		.services
88		.state_cache
89		.is_joined(sender_user, room_id)
90		.await
91	{
92		debug_warn!(%sender_user, %room_id, "Joined user attempted to knock.");
93		return Err!(Request(Forbidden("You cannot knock on a room you are already joined in.")));
94	}
95
96	let server_in_room = self
97		.services
98		.state_cache
99		.server_in_room(self.services.globals.server_name(), room_id)
100		.await;
101
102	// Trust a local knock; re-drive a remote one in case we missed a kick.
103	if server_in_room
104		&& self
105			.services
106			.state_cache
107			.is_knocked(sender_user, room_id)
108			.await
109	{
110		debug_warn!(%sender_user, %room_id, "User is already knocking.");
111		return Ok(());
112	}
113
114	if self
115		.banned_from_resident_room(sender_user, room_id)
116		.await
117	{
118		debug_warn!(%sender_user, %room_id, "Banned user attempted to knock.");
119		return Err!(Request(Forbidden("You cannot knock on a room you are banned from.")));
120	}
121
122	let local_knock = server_in_room
123		|| servers.is_empty()
124		|| (servers.len() == 1 && self.services.globals.server_is_ours(&servers[0]));
125
126	if local_knock {
127		self.knock_room_helper_local(sender_user, room_id, reason, &servers, state_lock)
128			.await
129	} else {
130		self.knock_room_helper_remote(sender_user, room_id, reason, &servers)
131			.boxed() // cold arm
132			.await
133	}
134}
135
136#[implement(Service)]
137async fn knock_room_helper_local(
138	&self,
139	sender_user: &UserId,
140	room_id: &RoomId,
141	reason: Option<String>,
142	servers: &[OwnedServerName],
143	state_lock: &RoomMutexGuard,
144) -> Result {
145	debug_info!("We can knock locally");
146
147	let room_version_id = self
148		.services
149		.state
150		.get_room_version(room_id)
151		.await?;
152
153	ensure_room_version_supports_knock(&room_version_id)?;
154
155	let content = self
156		.services
157		.profile
158		.fill_content(sender_user, RoomMemberEventContent {
159			reason: reason.clone(),
160			..RoomMemberEventContent::new(MembershipState::Knock)
161		})
162		.await;
163
164	let Err(error) = self
165		.services
166		.timeline
167		.build_and_append_pdu(
168			PduBuilder::state(sender_user.to_string(), &content),
169			sender_user,
170			room_id,
171			state_lock,
172		)
173		.await
174	else {
175		return Ok(());
176	};
177
178	if servers.is_empty()
179		|| (servers.len() == 1 && self.services.globals.server_is_ours(&servers[0]))
180	{
181		return Err(error);
182	}
183
184	warn!("We couldn't do the knock locally, maybe federation can help to satisfy the knock");
185
186	self.knock_room_local_federation_fallback(sender_user, room_id, reason, servers, state_lock)
187		.boxed() // cold arm
188		.await
189}
190
191fn ensure_room_version_supports_knock(room_version_id: &RoomVersionId) -> Result {
192	if matches!(
193		room_version_id,
194		RoomVersionId::V1
195			| RoomVersionId::V2
196			| RoomVersionId::V3
197			| RoomVersionId::V4
198			| RoomVersionId::V5
199			| RoomVersionId::V6
200	) {
201		return Err!(Request(Forbidden("This room does not support knocking.")));
202	}
203
204	Ok(())
205}
206
207#[implement(Service)]
208async fn knock_room_local_federation_fallback(
209	&self,
210	sender_user: &UserId,
211	room_id: &RoomId,
212	reason: Option<String>,
213	servers: &[OwnedServerName],
214	state_lock: &RoomMutexGuard,
215) -> Result {
216	let (pdu, event) = self
217		.knock_over_federation(sender_user, room_id, reason, servers)
218		.await?;
219
220	info!("Appending room knock event locally");
221	self.services
222		.timeline
223		.append_pdu(&pdu, event, once(pdu.event_id.borrow()), None, state_lock)
224		.await?;
225
226	Ok(())
227}
228
229/// Knocks through a remote server on a room this server is not in.
230///
231/// Of the knock, only the user's membership and the room summary are stored.
232/// None of the summary's events becomes an outlier, room state or a timeline
233/// event, as the summary carries no auth chain to check them against.
234#[implement(Service)]
235async fn knock_room_helper_remote(
236	&self,
237	sender_user: &UserId,
238	room_id: &RoomId,
239	reason: Option<String>,
240	servers: &[OwnedServerName],
241) -> Result {
242	info!("Knocking over federation.");
243
244	self.knock_over_federation(sender_user, room_id, reason, servers)
245		.await?;
246
247	Ok(())
248}
249
250/// Knocks through a server in the room and records the user's knock.
251///
252/// Fails when this server does not support the remote room version. The
253/// membership is recorded with the room summary from the accepting server's
254/// response, as checked by [`Self::knock_summary`]. Returns the knock both
255/// parsed and as the JSON this server signed.
256#[implement(Service)]
257async fn knock_over_federation(
258	&self,
259	sender_user: &UserId,
260	room_id: &RoomId,
261	reason: Option<String>,
262	servers: &[OwnedServerName],
263) -> Result<(PduEvent, CanonicalJsonObject)> {
264	let (make_knock_response, remote_server) = self
265		.make_knock_request(sender_user, room_id, servers)
266		.await?;
267
268	info!("make_knock finished");
269
270	let room_version_id = make_knock_response.room_version.clone();
271
272	self.services
273		.config
274		.require_supported_room_version(&room_version_id)?;
275
276	let (knock_event, event_id) = self
277		.build_knock_event(sender_user, room_id, reason, &make_knock_response, &room_version_id)
278		.await?;
279
280	let send_knock_response = self
281		.execute_send_knock(&remote_server, room_id, &event_id, &knock_event, &room_version_id)
282		.await?;
283
284	self.services
285		.short
286		.get_or_create_shortroomid(room_id)
287		.await;
288
289	info!("Parsing knock event");
290	let pdu = PduEvent::from_object_and_eventid(&event_id, knock_event.clone())
291		.map_err(|e| err!(BadServerResponse("Invalid knock event PDU: {e:?}")))?;
292
293	let summary = self
294		.knock_summary(room_id, &room_version_id, &pdu, send_knock_response.knock_room_state)
295		.await?;
296
297	self.record_knock(room_id, sender_user, &pdu, summary)
298		.await?;
299
300	Ok((pdu, knock_event))
301}
302
303#[implement(Service)]
304async fn build_knock_event(
305	&self,
306	sender_user: &UserId,
307	room_id: &RoomId,
308	reason: Option<String>,
309	make_knock_response: &federation::membership::prepare_knock_event::v1::Response,
310	room_version_id: &RoomVersionId,
311) -> Result<(CanonicalJsonObject, OwnedEventId)> {
312	let mut knock_event_stub: CanonicalJsonObject =
313		serde_json::from_str(make_knock_response.event.get()).map_err(|e| {
314			err!(BadServerResponse("Invalid make_knock event json received from server: {e:?}"))
315		})?;
316
317	let content = self
318		.services
319		.profile
320		.fill_content(sender_user, RoomMemberEventContent {
321			reason,
322			..RoomMemberEventContent::new(MembershipState::Knock)
323		})
324		.await;
325
326	knock_event_stub.insert(
327		"origin".into(),
328		CanonicalJsonValue::String(
329			self.services
330				.globals
331				.server_name()
332				.as_str()
333				.to_owned(),
334		),
335	);
336	knock_event_stub.insert(
337		"origin_server_ts".into(),
338		CanonicalJsonValue::Integer(
339			utils::millis_since_unix_epoch()
340				.try_into()
341				.expect("Timestamp is valid js_int value"),
342		),
343	);
344	knock_event_stub.insert(
345		"content".into(),
346		to_canonical_value(content).expect("event is valid, we just created it"),
347	);
348
349	knock_event_stub
350		.insert("room_id".into(), CanonicalJsonValue::String(room_id.as_str().into()));
351
352	knock_event_stub
353		.insert("state_key".into(), CanonicalJsonValue::String(sender_user.as_str().into()));
354
355	knock_event_stub
356		.insert("sender".into(), CanonicalJsonValue::String(sender_user.as_str().into()));
357
358	knock_event_stub.insert("type".into(), CanonicalJsonValue::String("m.room.member".into()));
359
360	// In order to create a compatible ref hash (EventID) the `hashes` field needs
361	// to be present
362	self.services
363		.server_keys
364		.hash_and_sign_event(&mut knock_event_stub, room_version_id)?;
365
366	let event_id = gen_event_id(&knock_event_stub, room_version_id)?;
367
368	knock_event_stub
369		.insert("event_id".into(), CanonicalJsonValue::String(event_id.clone().into()));
370
371	Ok((knock_event_stub, event_id))
372}
373
374#[implement(Service)]
375async fn execute_send_knock(
376	&self,
377	remote_server: &OwnedServerName,
378	room_id: &RoomId,
379	event_id: &OwnedEventId,
380	knock_event: &CanonicalJsonObject,
381	room_version_id: &RoomVersionId,
382) -> Result<SendKnockResponse> {
383	info!("Asking {remote_server} for send_knock in room {room_id}");
384	let send_knock_request = SendKnockRequest {
385		room_id: room_id.to_owned(),
386		event_id: event_id.clone(),
387		pdu: self
388			.services
389			.federation
390			.format_pdu_into(knock_event.clone(), Some(room_version_id))
391			.await,
392	};
393
394	let response = self
395		.services
396		.federation
397		.execute(remote_server, send_knock_request)
398		.await?;
399
400	info!("send_knock finished");
401
402	// Settled here so all three readers of this array agree.
403	Ok(SendKnockResponse::new(dedup_stripped_state(response.knock_room_state)))
404}
405
406#[implement(Service)]
407async fn make_knock_request(
408	&self,
409	sender_user: &UserId,
410	room_id: &RoomId,
411	servers: &[OwnedServerName],
412) -> Result<(federation::membership::prepare_knock_event::v1::Response, OwnedServerName)> {
413	let mut make_knock_response_and_server =
414		Err!(BadServerResponse("No server available to assist in knocking."));
415
416	let mut make_knock_counter: usize = 0;
417
418	for remote_server in servers {
419		if self
420			.services
421			.globals
422			.server_is_ours(remote_server)
423		{
424			continue;
425		}
426
427		info!("Asking {remote_server} for make_knock ({make_knock_counter})");
428
429		let make_knock_response = self
430			.services
431			.federation
432			.execute(remote_server, federation::membership::prepare_knock_event::v1::Request {
433				room_id: room_id.to_owned(),
434				user_id: sender_user.to_owned(),
435				ver: self
436					.services
437					.config
438					.supported_room_versions()
439					.map(at!(0))
440					.collect(),
441			})
442			.await;
443
444		trace!("make_knock response: {make_knock_response:?}");
445		make_knock_counter = make_knock_counter.saturating_add(1);
446
447		make_knock_response_and_server = make_knock_response.map(|r| (r, remote_server.clone()));
448
449		if make_knock_response_and_server.is_ok() {
450			break;
451		}
452
453		if make_knock_counter > 40 {
454			warn!(
455				"50 servers failed to provide valid make_knock response, assuming no server can \
456				 assist in knocking."
457			);
458			make_knock_response_and_server =
459				Err!(BadServerResponse("No server available to assist in knocking."));
460
461			return make_knock_response_and_server;
462		}
463	}
464
465	make_knock_response_and_server
466}
467
468/// Builds the room summary a knock records for the knocking user.
469///
470/// A full PDU is shown only once its signatures and content hash verify and it
471/// belongs to the room; one that fails is omitted. Legacy entries pass as hints,
472/// a create the MSC4311 policy drops is omitted in either form, and the user's
473/// own membership entry is always the knock this server signed.
474#[implement(Service)]
475#[expect(
476	deprecated,
477	reason = "Matrix 1.16 still permits receiving the legacy stripped variant for backwards \
478	          compatibility."
479)]
480async fn knock_summary(
481	&self,
482	room_id: &RoomId,
483	room_version_id: &RoomVersionId,
484	knock_pdu: &PduEvent,
485	knock_room_state: Vec<RawStrippedState>,
486) -> Result<Summary> {
487	let pdus = knock_room_state
488		.iter()
489		.filter_map(|state| match state {
490			| RawStrippedState::Pdu(pdu) => Some(pdu),
491			| RawStrippedState::Stripped(_) => None,
492		});
493
494	self.services
495		.server_keys
496		.acquire_events_pubkeys(pdus)
497		.await;
498
499	let verdict = self
500		.validate_stripped_create(&knock_room_state, room_id, room_version_id)
501		.await?;
502
503	let enforce = self
504		.services
505		.config
506		.federation
507		.enforce_stripped_state_pdu_validation;
508
509	let drop_create = enforce_stripped_create(verdict, v12_room_ids(room_version_id), enforce);
510
511	if verdict != StrippedCreateVerdict::Valid {
512		debug_warn!(?verdict, %room_id, drop_create, "MSC4311 knock create-event validation failed");
513	}
514
515	let rules = room_version_rules(room_version_id)?;
516	let summary = without_member(knock_room_state, knock_pdu.sender())
517		.filter(|state| !drop_create || !occupies_cell(state, &StateEventType::RoomCreate, ""))
518		.stream()
519		.wide_filter_map(|state| {
520			self.knock_summary_entry(room_id, room_version_id, &rules, state)
521		})
522		.chain(once(knock_pdu.to_format()).stream())
523		.collect()
524		.await;
525
526	Ok(summary)
527}
528
529#[implement(Service)]
530#[expect(
531	deprecated,
532	reason = "Matrix 1.16 still permits receiving the legacy stripped variant for backwards \
533	          compatibility."
534)]
535async fn knock_summary_entry(
536	&self,
537	room_id: &RoomId,
538	room_version_id: &RoomVersionId,
539	rules: &RoomVersionRules,
540	state: RawStrippedState,
541) -> Option<Raw<AnyStrippedStateEvent>> {
542	let pdu = match state {
543		| RawStrippedState::Stripped(raw) => return Some(raw),
544		| RawStrippedState::Pdu(pdu) => pdu,
545	};
546
547	let (event_id, pdu, _, verified) = self
548		.verified_pdu(room_id, room_version_id, rules, &pdu)
549		.inspect_err(
550			|error| debug_warn!(%room_id, %error, "Omitting an invalid knock summary event."),
551		)
552		.map(Result::ok)
553		.await?;
554
555	if verified != Verified::All {
556		debug_warn!(%room_id, %event_id, "Omitting a knock summary event failing its content hash.");
557		return None;
558	}
559
560	Some(pdu.to_format())
561}
562
563#[implement(Service)]
564async fn record_knock(
565	&self,
566	room_id: &RoomId,
567	sender_user: &UserId,
568	pdu: &PduEvent,
569	summary: Summary,
570) -> Result {
571	info!("Updating membership locally to knock state with the room summary");
572	let count = self.services.globals.next_count();
573	let membership_event = pdu.get_content().expect("we just created this");
574
575	// A remote knock appends no event, so its unread counts are cleared here.
576	self.services
577		.pusher
578		.reset_notification_counts_for_thread(
579			sender_user,
580			room_id,
581			None,
582			&ReceiptThread::Unthreaded,
583		)
584		.await;
585
586	self.services
587		.sending
588		.refresh_push_badge(sender_user)
589		.await
590		.log_err()
591		.ok();
592
593	let knock = MembershipUpdate::self_sent(
594		room_id,
595		sender_user,
596		membership_event,
597		PduCount::Normal(*count),
598	);
599
600	self.services
601		.state_cache
602		.update_membership(MembershipUpdate {
603			last_state: Some(summary),
604			update_joined_count: false,
605			..knock
606		})
607		.await
608}
609
610#[cfg(test)]
611mod tests;