arminius_lib_events/

states.rs

// SPDX-FileCopyrightText: 2025 BWI GmbH
//
// SPDX-License-Identifier: Apache-2.0

//! Event lifecycle state type definitions.
//!
//! This module defines the four states an event can be in during its lifecycle:
//!
//! - [`Draft`]: Raw user intent (content + type only)
//! - [`Contextualized`]: Contextualized in the DAG with auth/prev events
//! - [`Signed`]: Signed with event ID and signatures
//! - [`Verified`]: Verified signatures and authorization

use ruma::{
	CanonicalJsonObject, CanonicalJsonValue, MilliSecondsSinceUnixEpoch, OwnedEventId, OwnedRoomId,
	OwnedServerName, OwnedUserId,
	canonical_json::{self},
	events::{
		AnyMessageLikeEventContent, AnyStateEventContent, RawExt as _, TimelineEventType,
		room::{create::RoomCreateEventContent, member::MembershipState},
	},
	room_version_rules::EventIdFormatVersion,
	serde::Raw,
};
use serde::{Deserialize, Serialize};

use crate::{
	EventFormatOptions, EventHash, Pdu, PduCommon, V1Pdu, V3Pdu, V12Pdu,
	conversions::raw_json,
	errors::{
		EventContextualizationError, EventIdGenerationError, MismatchedEventRefsError, SigningError,
	},
	pdu::V6Pdu,
	types::{
		EventRefs, KnownEventsReferenceFormatVersion, KnownRoomVersionId, PduFormat, StateKey,
		VerificationMetadata,
	},
};

/// State representing a draft event containing only user intent.
///
/// A draft is the initial state of an event,
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Draft {
	/// Matrix timeline event type.
	pub timeline_event_type: TimelineEventType,
	/// Raw JSON event content.
	pub content: Box<serde_json::value::RawValue>,
	/// State key for state events (`Some`), or `None` for message-like
	/// events. State events may carry an empty-string state key (e.g.
	/// `m.room.create`).
	pub state_key: Option<StateKey>,
	/// The user that sent the event
	pub(crate) sender: OwnedUserId,
	/// Redacted event id for redaction events
	pub(crate) redacts: Option<OwnedEventId>,
}

impl Draft {
	/// Initializes a [`Draft`] from, validating content
	/// shape.
	///
	/// ## Errors
	///
	/// Returns a `serde_json::Error` if the `content` does not have the format
	/// expected of the `event_type`
	///
	/// > "Re-fried deep fried beans!"
	pub fn new(
		event_type: TimelineEventType,
		content: Box<serde_json::value::RawValue>,
		state_key: Option<StateKey>,
		sender: OwnedUserId,
		redacts: Option<OwnedEventId>,
	) -> Result<Self, serde_json::Error> {
		Self::build(event_type, content, state_key, sender, redacts, false)
	}

	/// Initializes a [`Draft`] from the content of a federation PDU, tolerating
	/// redacted content.
	///
	/// Unlike [`Draft::new`], empty (`{}`) message-like content is accepted
	/// rather than rejected, since a redacted event may have had its content
	/// stripped to `{}`. This is only appropriate for already-signed events
	/// received over federation, never for client-originated content, which
	/// must go through [`Draft::new`].
	///
	/// This constructor lives on [`Draft`] rather than on [`Signed`] because it
	/// runs while a PDU is being parsed into a [`Signed`], before that value
	/// exists.
	///
	/// ## Errors
	///
	/// Returns a `serde_json::Error` if the `content` does not have the format
	/// expected of the `event_type`.
	pub(crate) fn from_signed(
		event_type: TimelineEventType,
		content: Box<serde_json::value::RawValue>,
		state_key: Option<StateKey>,
		sender: OwnedUserId,
		redacts: Option<OwnedEventId>,
	) -> Result<Self, serde_json::Error> {
		Self::build(event_type, content, state_key, sender, redacts, true)
	}

	/// Shared constructor validating content shape.
	///
	/// When `allow_redacted_content` is set, empty (`{}`) message-like content
	/// is accepted instead of being validated, to allow loading redacted
	/// events.
	fn build(
		event_type: TimelineEventType,
		content: Box<serde_json::value::RawValue>,
		state_key: Option<StateKey>,
		sender: OwnedUserId,
		redacts: Option<OwnedEventId>,
		allow_redacted_content: bool,
	) -> Result<Self, serde_json::Error> {
		// Deserialize it once, to make sure the body has all the required
		// fields

		if state_key.is_some() {
			Raw::<AnyStateEventContent>::from_json(content.clone())
				.deserialize_with_type(&event_type.to_string())?;
		} else {
			// FIXME(#198): Accept redacted state events too.
			//
			// Skipping validation for empty (`{}`) message-like content is a
			// temporary hack to import rooms from Synapse servers, which
			// contain redacted events. Redacting an event strips its content
			// down to the keys the room version's redaction rules preserve for
			// that event type; for some message-like events that leaves `{}`,
			// which no typed content can parse. Accepting `{}` here lets those
			// redacted events load without validation.
			//
			// This is only a heuristic: `{}` is not a reliable marker of
			// redaction. Some events keep content keys after redaction (e.g.
			// `m.room.redaction`, itself a message-like event, keeps
			// `content.redacts` from room version 11 on), and some non-redacted
			// events may legitimately carry empty content. We restrict the skip
			// to message-like events only because redacted *state* events
			// aren't handled yet; rooms rarely redact state events, so
			// this unblocks testing for now.
			let is_empty_content =
				serde_json::from_str::<serde_json::Map<String, serde_json::Value>>(content.get())
					.is_ok_and(|map| map.is_empty());
			if !(allow_redacted_content && is_empty_content) {
				Raw::<AnyMessageLikeEventContent>::from_json(content.clone())
					.deserialize_with_type(&event_type.to_string())?;
			}
		}

		Ok(Self { timeline_event_type: event_type, content, state_key, sender, redacts })
	}

	/// Initialize a new Draft state, assuming it has been redacted.
	///
	/// This function assumes that the event content is correct event content,
	/// which has passed through the [`Draft::new`], and subsequently the
	/// redaction module. Therefore, no explicit verification is made
	///
	/// ## Errors
	///
	/// Returns a `serde_json::Error` if, for a room-create event, the redacted
	/// content cannot be parsed as `m.room.create` content.
	pub fn redact(
		&mut self,
		redacted_content: Box<serde_json::value::RawValue>,
	) -> Result<(), serde_json::Error> {
		// FIXME(#1889): This requirement should be enforced on the compiler
		// level, e.g. by a type
		if self.timeline_event_type == TimelineEventType::RoomCreate {
			serde_json::from_str::<RoomCreateEventContent>(redacted_content.get())?;
		}
		self.content = redacted_content;
		Ok(())
	}

	/// Get the event content as a JSON object map.
	///
	/// ## Panics
	///
	/// Panics if the content is not a valid JSON object.
	/// [`crate::states::Draft::new`] guarantees that the content is valid, so
	/// this is only reachable for events constructed bypassing that
	/// constructor.
	pub(crate) fn content_to_map(&self) -> serde_json::Map<String, serde_json::Value> {
		#[expect(
			clippy::expect_used,
			reason = "The Draft struct guarantees that the draft field is always correct"
		)]
		serde_json::from_str(self.content.get())
			.expect("We guarantee that the content field here is correct")
	}
}

/// Used for checking round-trip correctness of converting an event to and from
/// a PDU
///
/// Only enabled for tests, because the way we compare the content is not
/// completely good
#[cfg(any(feature = "test_utils", test))]
impl PartialEq for Draft {
	fn eq(&self, other: &Self) -> bool {
		if self.timeline_event_type != other.timeline_event_type
			|| self.sender != other.sender
			|| self.state_key != other.state_key
			|| self.redacts != other.redacts
		{
			return false;
		}
		let v1 = serde_json::from_str::<serde_json::Value>(self.content.get());
		let v2 = serde_json::from_str::<serde_json::Value>(other.content.get());
		match (v1, v2) {
			(Ok(v1), Ok(v2)) => v1 == v2,
			(Ok(_), Err(_)) | (Err(_), Ok(_)) => false,
			(Err(_), Err(_)) => self.content.get() == other.content.get(),
		}
	}
}

#[cfg(any(feature = "test_utils", test))]
impl Eq for Draft {}

/// State representing an event contextualized in the room DAG.
///
/// A contextualized event has been placed in the context of the room's directed
/// acyclic graph (DAG) by adding `auth_events` and `prev_events` references,
/// along with the `origin_server_ts` and room version rules.
///
/// This state does not guarantee authorization - that check happens during
/// verification via [`super::RoomEvent<Signed>::verify()`].
#[cfg_attr(any(feature = "test_utils", test), derive(Eq, PartialEq))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Contextualized {
	/// The draft event data
	pub(crate) draft: Draft,
	/// The depth of the event
	pub(crate) depth: u64,
	/// Room version for the event
	pub(crate) room_version: KnownRoomVersionId,
	/// The auth events
	pub(crate) auth_events: EventRefs,
	/// The previous events
	pub(crate) prev_events: EventRefs,
	/// The previous state field.
	///
	/// Not externally visible outside of the crate, but used by some room
	/// versions for nothing
	pub(crate) prev_state: Option<EventRefs>,
	/// The membership field.
	///
	/// Not externally visible outside of the crate, but used by some room
	/// versions for nothing
	pub(crate) membership: Option<MembershipState>,
	/// The origin field.
	///
	/// Not externally visible outside of NLE, but used by some room versions
	/// for nothing
	pub(crate) origin: Option<OwnedServerName>,
	/// The origin server timestamp
	pub(crate) origin_server_ts: MilliSecondsSinceUnixEpoch,
	/// The event ID
	pub(crate) event_id: OwnedEventId,
	/// The room ID
	pub(crate) room_id: OwnedRoomId,
	/// The content hashes
	pub(crate) hashes: EventHash,
}

impl Contextualized {
	/// Contextualize an event
	///
	/// Can optionally be provided an event ID. If none is provided, one will
	/// always be generated, also for room versions 1 and 2.
	#[expect(clippy::too_many_arguments, reason = "Matches the contents of the struct")]
	pub(crate) fn new(
		draft: Draft,
		depth: u64,
		room_version: KnownRoomVersionId,
		auth_events: EventRefs,
		prev_events: EventRefs,
		prev_state: Option<EventRefs>,
		membership: Option<MembershipState>,
		origin: Option<OwnedServerName>,
		origin_server_ts: MilliSecondsSinceUnixEpoch,
		event_id: Option<OwnedEventId>,
		room_id: Option<OwnedRoomId>,
		hashes: Option<EventHash>,
	) -> Result<Self, EventContextualizationError> {
		match room_version.events_reference_format() {
			KnownEventsReferenceFormatVersion::V1 => {
				if !matches!(auth_events, EventRefs::Hashed(_) | EventRefs::Empty)
					|| !matches!(prev_events, EventRefs::Hashed(_) | EventRefs::Empty)
				{
					return Err(MismatchedEventRefsError::ExpectedV1GotV2.into());
				}
			}
			KnownEventsReferenceFormatVersion::V2 => {
				if !matches!(auth_events, EventRefs::Plain(_) | EventRefs::Empty)
					|| !matches!(prev_events, EventRefs::Plain(_) | EventRefs::Empty)
				{
					return Err(MismatchedEventRefsError::ExpectedV2GotV1.into());
				}
			}
		}
		if auth_events.len() > 10 {
			return Err(EventContextualizationError::TooManyAuthEvents);
		}
		if prev_events.len() > 20 {
			return Err(EventContextualizationError::TooManyPrevEvents);
		}

		// If we don't keep these fields after redaction, there's no point at
		// all to keeping them
		let origin = room_version
			.rules()
			.redaction
			.keep_origin_membership_prev_state
			.then_some(origin)
			.flatten();
		let membership = room_version
			.rules()
			.redaction
			.keep_origin_membership_prev_state
			.then_some(membership)
			.flatten();
		let prev_state = room_version
			.rules()
			.redaction
			.keep_origin_membership_prev_state
			.then_some(prev_state)
			.flatten();

		// We generate a temporary object, just to generate an `event_id` and
		// potentially a `room_id`
		let mut temporary_contextualized = Self {
			draft,
			depth,
			room_version,
			auth_events,
			prev_events,
			membership,
			origin: origin.clone(),
			origin_server_ts,
			prev_state,
			event_id: ruma::owned_event_id!("$event"),
			room_id: room_id.clone().unwrap_or_else(|| ruma::owned_room_id!("!dummy")),
			hashes: EventHash::new(""),
		};

		temporary_contextualized.hashes = match hashes {
			None => temporary_contextualized.generate_hashes()?,
			Some(hashes) => hashes,
		};

		let event_id = match room_version {
			KnownRoomVersionId::V1 | KnownRoomVersionId::V2 => event_id.map_or_else(
				|| {
					temporary_contextualized.generate_event_id(Some(&origin.unwrap_or_else(|| {
						temporary_contextualized.draft.sender.server_name().to_owned()
					})))
				},
				Ok,
			)?,
			KnownRoomVersionId::V3
			| KnownRoomVersionId::V4
			| KnownRoomVersionId::V5
			| KnownRoomVersionId::V6
			| KnownRoomVersionId::V7
			| KnownRoomVersionId::V8
			| KnownRoomVersionId::V9
			| KnownRoomVersionId::V10
			| KnownRoomVersionId::V11
			| KnownRoomVersionId::V12 => temporary_contextualized
				.generate_event_id(Some(temporary_contextualized.draft.sender.server_name()))?,
		};

		#[expect(
			clippy::expect_used,
			reason = "We know that event IDs will have a $ prefix, and that the room ID will be the correct format"
		)]
		let room_id = if let Some(room_id) = room_id {
			room_id
		} else {
			ruma::RoomId::parse(format!(
				"!{}",
				event_id.to_string().strip_prefix("$").expect("We know event IDs have this prefix")
			))
			.expect("We know this must be correct")
		};

		Ok(Self { event_id, room_id, ..temporary_contextualized })
	}

	/// Recovers the [`Contextualized`] event from a [`Signed`] one for
	/// re-signing, discarding the existing signatures and hashes.
	///
	/// Only `m.room.member` events are supported, since re-signing from an
	/// already-signed state is currently only performed on member events.
	/// Room-create events are rejected here rather than special-cased.
	///
	/// The content was already validated when the [`Signed`] event was built,
	/// so the inner [`Contextualized`] is reused as-is without re-validation.
	///
	/// ## Errors
	///
	/// Returns [`SigningError::InvalidContent`] if `signed`'s event type is not
	/// `m.room.member`.
	pub(crate) fn from_signed_for_resign(signed: Signed) -> Result<Self, SigningError> {
		if signed.contextualized.draft.timeline_event_type != TimelineEventType::RoomMember {
			return Err(SigningError::InvalidContent(
				"from_signed_for_resign only reconstructs m.room.member events".to_owned(),
			));
		}
		Ok(signed.contextualized)
	}

	/// Builds the minimal event object for signing and hashing.
	///
	/// ## Panics
	///
	/// Panics if a non-create event has no room ID.
	#[must_use]
	fn build_minimal_event_object(&self) -> serde_json::Map<String, serde_json::Value> {
		let room_version_rules = &self.room_version.rules();
		let event_format = EventFormatOptions::from_room_version(room_version_rules);
		let mut content_map = self.draft.content_to_map();
		let redacts_value =
			self.draft.redacts.as_ref().map(|id| serde_json::Value::String(id.to_string()));
		let redacts_is_content_field = event_format.content_field_redacts;
		if let Some(ref value) = redacts_value
			&& redacts_is_content_field
		{
			content_map.insert("redacts".to_owned(), value.clone());
		}

		let mut event = serde_json::Map::new();
		event.insert(
			"type".to_owned(),
			serde_json::Value::String(self.draft.timeline_event_type.to_string()),
		);
		event.insert("content".to_owned(), serde_json::Value::Object(content_map));

		let is_room_create = !event_format.require_room_create_room_id
			&& matches!(self.draft.timeline_event_type, TimelineEventType::RoomCreate);
		if !is_room_create {
			event.insert("room_id".to_owned(), serde_json::Value::String(self.room_id.to_string()));
		}
		event.insert("sender".to_owned(), serde_json::Value::String(self.draft.sender.to_string()));

		if let Some(membership) = &self.membership {
			event
				.insert("membership".to_owned(), serde_json::Value::String(membership.to_string()));
		}

		if let Some(origin) = &self.origin {
			event.insert("origin".to_owned(), serde_json::Value::String(origin.to_string()));
		}

		event.insert(
			"origin_server_ts".to_owned(),
			serde_json::Value::Number(serde_json::Number::from(u64::from(self.origin_server_ts.0))),
		);

		if let Some(state_key) = &self.draft.state_key {
			event.insert("state_key".to_owned(), serde_json::Value::String(state_key.to_owned()));
		}
		if let Some(value) = redacts_value
			&& !redacts_is_content_field
		{
			event.insert("redacts".to_owned(), value);
		}

		event.insert("auth_events".to_owned(), self.auth_events.pdu_serialize());
		event.insert("prev_events".to_owned(), self.prev_events.pdu_serialize());
		if let Some(prev_state) = &self.prev_state {
			event.insert("prev_state".to_owned(), prev_state.pdu_serialize());
		}
		event.insert("depth".to_owned(), self.depth.into());
		event
	}

	/// Builds the canonical event object for signing and hashing.
	///
	/// ## Errors
	///
	/// Returns a [`SigningError`] if JSON canonicalization fails.
	pub(crate) fn build_canonical_event_object(&self) -> Result<CanonicalJsonObject, SigningError> {
		let value = serde_json::Value::Object(self.build_minimal_event_object());
		let canonical = canonical_json::to_canonical_value(value)
			.map_err(|error| SigningError::JsonCanonicalization(error.to_string()))?;
		let CanonicalJsonValue::Object(object) = canonical else {
			panic!("When canonicalizing a JSON object, the result should also be an object");
		};
		Ok(object)
	}

	/// Generate the content hashes of the object
	///
	/// See here <https://spec.matrix.org/latest/server-server-api/#calculating-the-content-hash-for-an-event>
	///
	/// ## Errors
	///
	/// Returns an [`EventIdGenerationError`] if the event cannot be
	/// canonicalized or hashed, or if a room version 1 event has no server
	/// name.
	fn generate_hashes(&self) -> Result<EventHash, EventIdGenerationError> {
		let canonical = self
			.build_canonical_event_object()
			.map_err(|err| EventIdGenerationError::InvalidEvent(err.to_string()))?;
		let hashes = ruma::signatures::content_hash(&canonical)
			.map_err(|err| EventIdGenerationError::InvalidEvent(err.to_string()))?;
		Ok(EventHash::new(hashes.to_string()))
	}

	/// Generates an event ID matching the room version.
	///
	/// ## Errors
	///
	/// Returns an [`EventIdGenerationError`] if the event cannot be
	/// canonicalized or hashed, or if a room version 1 event has no server
	/// name.
	fn generate_event_id(
		&self,
		server_name: Option<&ruma::ServerName>,
	) -> Result<OwnedEventId, EventIdGenerationError> {
		let mut canonical = self
			.build_canonical_event_object()
			.map_err(|err| EventIdGenerationError::InvalidEvent(err.to_string()))?;
		canonical.insert("hashes".to_owned(), self.hashes.to_canonical_json_value());

		let reference_hash =
			ruma::signatures::reference_hash(&canonical, &self.room_version.rules())
				.map_err(|err| EventIdGenerationError::InvalidEvent(err.to_string()))?;
		let event_id_str = match self.room_version.rules().event_id_format {
			EventIdFormatVersion::V1 => {
				let server_name = server_name.ok_or(EventIdGenerationError::V1MissingServerName)?;
				format!("${reference_hash}:{server_name}")
			}
			_ => format!("${reference_hash}"),
		};
		#[expect(
			clippy::expect_used,
			reason = "This parse is guaranteed to succeed, because we construct the string ourselves"
		)]
		let expected_event_id =
			ruma::EventId::parse(event_id_str).expect("Generated event ID is invalid");
		Ok(expected_event_id)
	}
}

/// State representing a signed event with event ID and signatures.
///
/// A signed event has been cryptographically signed and has a computed event ID
/// based on the reference hash of the canonical JSON representation.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(any(feature = "test_utils", test), derive(Eq, PartialEq))]
pub struct Signed {
	/// The contextualized event data
	pub(crate) contextualized: Contextualized,
	/// The signatures
	pub(crate) signatures: ruma::ServerSignatures,
}

impl Signed {
	/// Build the event JSON, similar to the one for a Contextualized event, but
	/// with the event_id, signatures, and hashes
	#[must_use]
	pub fn build_event_value(&self) -> serde_json::Value {
		let mut object = self.contextualized.build_minimal_event_object();
		if self.contextualized.room_version.rules().event_id_format == EventIdFormatVersion::V1 {
			object.insert("event_id".to_owned(), self.contextualized.event_id.to_string().into());
		}

		#[expect(
			clippy::expect_used,
			reason = "The object being serialized is a map from strings to strings, which should not be fallible"
		)]
		object.insert(
			"signatures".to_owned(),
			serde_json::to_value(&self.signatures)
				.expect("The serialization of ruma signatures cannot actually fail"),
		);
		object.insert("hashes".to_owned(), self.contextualized.hashes.to_json_value());

		serde_json::Value::Object(object)
	}

	/// Build the event object, similar to the one for a Contextualized event,
	/// but with the event_id, signatures, and hashes
	pub fn build_event_object(&self) -> Result<CanonicalJsonObject, SigningError> {
		let value = self.build_event_value();

		let canonical = canonical_json::to_canonical_value(value)
			.map_err(|error| SigningError::JsonCanonicalization(error.to_string()))?;

		let CanonicalJsonValue::Object(object) = canonical else {
			panic!("Expected an object");
		};
		Ok(object)
	}

	/// Builds a PDU representation for use in authorization checks.
	#[must_use]
	pub fn build_pdu(&self) -> Pdu {
		let room_version = self.contextualized.room_version;
		let pdu_format = PduFormat::from(room_version);
		let value = self.build_event_value();

		let raw = raw_json(&value);

		let common = PduCommon {
			event_id: self.contextualized.event_id.clone(),
			room_id: self.contextualized.room_id.clone(),
			sender: self.contextualized.draft.sender.clone(),
			event_type: self.contextualized.draft.timeline_event_type.clone(),
			content: self.contextualized.draft.content.clone(),
			state_key: self.contextualized.draft.state_key.clone(),
			origin_server_ts: self.contextualized.origin_server_ts,
			redacts: self.contextualized.draft.redacts.clone(),
			rejected: false,
			raw,
		};

		match pdu_format {
			PduFormat::V1 => Pdu::V1(V1Pdu {
				common,
				prev_events: Vec::<OwnedEventId>::from(&self.contextualized.prev_events),
				auth_events: Vec::<OwnedEventId>::from(&self.contextualized.auth_events),
				depth: self.contextualized.depth,
			}),
			PduFormat::V3 => Pdu::V3(V3Pdu {
				common,
				prev_events: Vec::<OwnedEventId>::from(&self.contextualized.prev_events),
				auth_events: Vec::<OwnedEventId>::from(&self.contextualized.auth_events),
				depth: self.contextualized.depth,
			}),
			PduFormat::V6 => Pdu::V6(V6Pdu {
				common,
				prev_events: Vec::<OwnedEventId>::from(&self.contextualized.prev_events),
				auth_events: Vec::<OwnedEventId>::from(&self.contextualized.auth_events),
				depth: self.contextualized.depth,
			}),
			PduFormat::V12 => Pdu::V12(V12Pdu {
				common,
				prev_events: Vec::<OwnedEventId>::from(&self.contextualized.prev_events),
				auth_events: Vec::<OwnedEventId>::from(&self.contextualized.auth_events),
				depth: self.contextualized.depth,
			}),
		}
	}
}

/// State representing a fully verified event ready for persistence or
/// distribution.
///
/// A verified event has passed all cryptographic signature verification and
/// authorization checks. It is safe to store in the database or send to other
/// homeservers.
#[cfg_attr(any(feature = "test_utils", test), derive(Eq, PartialEq))]
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Verified {
	/// The signed event data.
	pub(crate) signed: Signed,
	/// The verification metadata
	pub(crate) metadata: VerificationMetadata,
}