arminius_lib_events/

transitions.rs

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

//! Core `RoomEvent<S>` type and state transition logic.
//!
//! This module contains the main `RoomEvent<S>` generic type that enforces
//! type-system enforced state transitions throughout the event lifecycle.
//!
//! 🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️🏳️‍⚧️

use std::collections::HashMap;

use ruma::{
	MilliSecondsSinceUnixEpoch, OwnedEventId, OwnedRoomId, OwnedServerName, OwnedUserId,
	api::client::filter,
	events::{
		AnyStrippedStateEvent, StateEventType, TimelineEventType, room::member::MembershipState,
	},
	room_version_rules::EventIdFormatVersion,
	serde::{Base64, Raw},
	signatures::{Ed25519KeyPair, PublicKeyMap, PublicKeySet},
	state_res,
};
use serde::{Deserialize, Serialize};
use serde_json::{json, value::RawValue as RawJsonValue};

use crate::{
	ClientContext, ContextualizedFields as _, EventHash, EventRefs, KnownRoomVersionId,
	VerificationMetadata,
	conversions::{build_unsigned, extract_signatures, raw_json},
	errors::{
		AuthorizationError, EventContextualizationError, EventIsNotStateEvent, FromPduError,
		SigningError, SigningValidationError, ValidationError,
	},
	pdu::{ClientEvent, Pdu},
	states::{Contextualized, Draft, Signed, Verified},
	types::StateKey,
};

/// A Matrix room event in a specific lifecycle state.
///
/// `RoomEvent<S>` is a generic wrapper that ensures type-safe state transitions
/// throughout the event lifecycle. The type parameter `S` determines which
/// methods are available and which transitions are permitted.
///
/// ## Type States
///
/// - [`RoomEvent<Draft>`]: Initial creation from user input
/// - [`RoomEvent<Contextualized>`]: Contextualized in the room DAG
/// - [`RoomEvent<Signed>`]: Signed with event ID and cryptographic signatures
/// - [`RoomEvent<Verified>`]: Verified and ready for persistence/distribution
///
/// ## Design Philosophy
///
/// The state-based design enforces correctness at compile-time:
///
/// - You cannot sign an event without first contextualizing it
/// - You cannot store an event without first verifying it
/// - You cannot send an event to federation without signatures
///
/// This prevents entire classes of security bugs by making invalid states
/// unrepresentable.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RoomEvent<S> {
	/// The state-specific data
	pub(crate) state: S,
}

impl RoomEvent<Draft> {
	/// Creates a draft event
	///
	/// ## Errors
	///
	/// Returns a `serde_json::Error` if the event content does not have the
	/// fields expected of its type.
	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> {
		Ok(Self { state: Draft::new(event_type, content, state_key, sender, redacts)? })
	}

	/// Contextualize the draft into the room DAG to create a [`Contextualized`]
	/// event.
	///
	/// This method places the draft event in the context of the room's directed
	/// acyclic graph by adding references to auth events and previous events,
	/// along with server timestamp and room version information.
	///
	/// ## Room Version
	///
	/// The `room_version` parameter determines:
	///
	/// - Event ID format (hashed vs. reference-based)
	/// - Event reference format (V1 hashed vs. V3+ plain)
	/// - Authorization rules
	/// - Signature requirements
	///
	/// ## Parameters
	///
	/// - `room_id`: The ID of the room the event is in. If the event type is `m.room.create` and
	///   the `room_version` is 12 or above, this should be None.
	/// - `room_version`: Room version rules determining event format and authorization.
	/// - `depth`: Depth of the event in the DAG.
	/// - `auth_events`: Auth event references for authorization chain.
	/// - `prev_events`: Previous event references establishing DAG position.
	/// - `origin_server_ts`: Server-assigned timestamp for the event.
	///
	/// ## Returns
	///
	/// A [`Contextualized`] event ready to be signed.
	pub fn contextualize(
		self,
		room_id: Option<OwnedRoomId>,
		room_version: KnownRoomVersionId,
		depth: u64,
		auth_events: EventRefs,
		prev_events: EventRefs,
		origin_server_ts: MilliSecondsSinceUnixEpoch,
	) -> Result<RoomEvent<Contextualized>, EventContextualizationError> {
		Ok(RoomEvent {
			state: Contextualized::new(
				self.state,
				depth,
				room_version,
				auth_events,
				prev_events,
				None,
				None,
				None,
				origin_server_ts,
				None,
				room_id,
				None,
			)?,
		})
	}
}

impl RoomEvent<Contextualized> {
	/// Sign the event to produce a [`Verified`] event.
	///
	/// Check [`VerificationMetadata::soft_failed`]
	/// to determine whether the event should be excluded from leaf events and
	/// client relay.
	///
	/// This method performs the following operations:
	///
	/// 1. Canonicalizes the event JSON according to Matrix specification
	/// 2. Computes the reference hash to generate the event ID
	/// 3. Signs the canonical JSON with the provided key pair
	/// 4. Attaches the signature to the event
	/// 5. Verifies that the event follows authorization rules
	/// 6. Returns a [`Verified`] event (signing implicitly verifies)
	///
	/// ## Implicit Verification
	///
	/// Events signed by our own server are implicitly verified - we trust our
	/// own signing process. This is why `sign()` returns [`Verified`] rather
	/// than [`Signed`].
	///
	/// ## Parameters
	///
	/// - `server_name`: The origin server name (e.g., "avastar.example.com") used to namespace the
	///   signature in the `signatures` field.
	/// - `signing_key`: The Ed25519 key pair used to generate and verify the cryptographic
	///   signature.
	/// - `previous_state`: The room state corresponding to the resolution of the state of this
	///   event's `prev_events`.
	/// - `auth_events`: The specific auth events referenced by this event.
	/// - `current_state`: The room state at the time the event is being
	///   verified. If the event fails this auth check, it will be
	///   soft-failed: the returned [`RoomEvent<Verified>`] will have
	///   [`VerificationMetadata::soft_failed`] set to `true`. See
	///   <https://spec.matrix.org/v1.17/server-server-api/#soft-failure> for more information.
	///
	/// ## Returns
	///
	/// A [`RoomEvent<Verified>`] with event ID and signatures, ready for
	/// persistence or federation.
	///
	/// ## Errors
	///
	/// Returns [`SigningValidationError`] if:
	///
	/// - Event content is not a valid JSON object
	/// - Canonical JSON generation fails
	/// - Reference hash computation fails
	/// - Cryptographic signing fails
	/// - Event ID parsing fails
	/// - Event fails authorization rules
	pub fn sign_and_verify(
		self,
		server_name: &ruma::ServerName,
		signing_key: &Ed25519KeyPair,
		previous_state: &HashMap<(StateEventType, StateKey), RoomEvent<Verified>>,
		auth_events: &HashMap<(StateEventType, StateKey), RoomEvent<Verified>>,
		current_state: &HashMap<(StateEventType, StateKey), RoomEvent<Verified>>,
	) -> Result<RoomEvent<Verified>, SigningValidationError> {
		let event = self.sign_event(server_name, signing_key)?;
		let event = RoomEvent { state: event.state.signed };

		let verify_key_map = PublicKeyMap::from([(
			server_name.to_string(),
			PublicKeySet::from([(
				format!("ed25519:{}", signing_key.version()),
				Base64::new(signing_key.public_key().to_vec()),
			)]),
		)]);

		event
			.verify(previous_state, auth_events, current_state, &verify_key_map)
			.map_err(SigningValidationError::ValidationError)
	}

	/// Sign a membership event, producing a PDU to send over federation
	/// This method only accepts membership events. It's intended for use
	/// when joining rooms over federation, as specified in
	/// <https://spec.matrix.org/v1.18/server-server-api/#joining-rooms>
	///
	/// The events produced by this method should **NOT** be persisted directly
	/// in the database. Instead, they should be sent over federation with the
	/// `/send_join` request, where we as a response will get the state events
	/// required to check the authorization rules.
	///
	/// This method performs the following operations:
	///
	/// 1. Canonicalizes the event JSON according to Matrix specification
	/// 2. Computes the reference hash to generate the event ID
	/// 3. Signs the canonical JSON with the provided key pair
	/// 4. Attaches the signature to the event
	/// 5. Returns a [`Pdu`]
	///
	/// ## Parameters
	///
	/// - `server_name`: The origin server name (e.g., "avastar.example.com") used to namespace the
	///   signature in the `signatures` field.
	/// - `signing_key`: The Ed25519 key pair used to generate and verify the cryptographic
	///   signature.
	///
	/// ## Returns
	///
	/// A [`Pdu`] to be sent to another homeserver to counter-sign
	///
	/// ## Errors
	///
	/// Returns [`SigningError`] if:
	///
	/// - Event content is not a valid JSON object
	/// - Event is not a membership event
	/// - Canonical JSON generation fails
	/// - Reference hash computation fails
	/// - Cryptographic signing fails
	/// - Event ID parsing fails
	pub fn sign_join_event(
		self,
		server_name: &ruma::ServerName,
		signing_key: &Ed25519KeyPair,
	) -> Result<Pdu, SigningError> {
		if self.state.draft.timeline_event_type != TimelineEventType::RoomMember {
			return Err(SigningError::InvalidContent(
				"Refusing to sign non-member event".to_owned(),
			));
		}
		let event = self.sign_event(server_name, signing_key)?;
		Ok(event.to_pdu())
	}

	/// Signs the event
	fn sign_event(
		self,
		server_name: &ruma::ServerName,
		signing_key: &Ed25519KeyPair,
	) -> Result<RoomEvent<Verified>, SigningError> {
		let room_version_rules = &self.state.room_version.rules();
		let mut canonical = self.state.build_canonical_event_object()?;

		// For room versions where event_id is part of the PDU (V1/V2 rooms):
		// the redaction algorithm retains `event_id` in the signed form, so
		// it must be inserted into the canonical before hash_and_sign_event
		if room_version_rules.event_id_format == EventIdFormatVersion::V1 {
			canonical.insert(
				"event_id".to_owned(),
				ruma::CanonicalJsonValue::String(self.event_id().to_string()),
			);
		}

		canonical.insert("hashes".to_owned(), self.hashes().to_canonical_json_value());

		ruma::signatures::sign_event(
			server_name.as_str(),
			signing_key,
			&mut canonical,
			&room_version_rules.redaction,
		)
		.map_err(|error| SigningError::SignatureCreation(error.to_string()))?;

		let signatures = extract_signatures(&canonical)?;

		let metadata = VerificationMetadata {
			attempted_at: MilliSecondsSinceUnixEpoch::now(),
			signature_verification: crate::types::PartsVerified::CompleteEvent,
			room_version: self.state.room_version,
			soft_failed: false,
		};

		let signed = Signed { contextualized: self.state, signatures };

		let event = RoomEvent { state: Verified { signed, metadata } };
		Ok(event)
	}
}

impl RoomEvent<Signed> {
	/// Create a new signed event (e.g. from federation)
	///
	/// ## Parameters
	///
	/// - `content`: Raw JSON content of the event.
	/// - `depth`: Depth of the event in the DAG.
	/// - `event_type`: Matrix event type.
	/// - `room_id`: Room ID the event belongs to.
	/// - `sender`: User ID that sent the event.
	/// - `state_key`: State key for state events.
	/// - `redacts`: Event ID that is redacted, if applicable.
	/// - `room_version`: Room version for the event.
	/// - `auth_events`: Auth event references required for authorization.
	/// - `prev_events`: Previous event references preceding the event.
	/// - `origin_server_ts`: Timestamp server assigned to the event.
	/// - `event_id`: Event ID of the signed event, if known.
	/// - `signatures`: Signature map of the event.
	/// - `hashes`: Content hashes of the event.
	///
	/// ## Errors
	///
	/// Returns [`FromPduError`] if:
	///
	/// - Event content fails draft validation
	/// - Event refs contextualization fails
	/// - Event ID generation fails
	#[expect(clippy::too_many_arguments, reason = "Constructor mirrors event fields")]
	pub fn new_signed(
		content: Box<serde_json::value::RawValue>,
		depth: u64,
		event_type: TimelineEventType,
		room_id: Option<OwnedRoomId>,
		sender: OwnedUserId,
		state_key: Option<String>,
		redacts: Option<OwnedEventId>,
		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>,
		signatures: ruma::ServerSignatures,
		hashes: EventHash,
	) -> Result<Self, FromPduError> {
		let contextualized = Contextualized::new(
			Draft::from_signed(event_type, content, state_key, sender, redacts)?,
			depth,
			room_version,
			auth_events,
			prev_events,
			prev_state,
			membership,
			origin,
			origin_server_ts,
			event_id,
			room_id,
			Some(hashes),
		)?;

		Ok(Self { state: Signed { contextualized, signatures } })
	}

	/// Recovers the authored [`Draft`] from a signed event, discarding its DAG
	/// context, signatures and hashes.
	///
	/// Re-validates through [`Draft::new`], the same gate client events pass,
	/// so content the tolerant federation parser accepted (e.g. a redacted
	/// event stripped to `{}`) cannot be re-signed under our own key.
	///
	/// ## Errors
	///
	/// Returns a `serde_json::Error` if the content does not pass
	/// [`Draft::new`] validation for its event type.
	pub fn into_draft(self) -> Result<RoomEvent<Draft>, serde_json::Error> {
		let draft = self.state.contextualized.draft;
		RoomEvent::new(
			draft.timeline_event_type,
			draft.content,
			draft.state_key,
			draft.sender,
			draft.redacts,
		)
	}

	/// Sign an already signed membership event, producing a PDU to send over
	/// federation.
	///
	/// ## Errors
	///
	/// Returns [`SigningError`] if the event is not a membership event or
	/// signing fails.
	pub fn sign_member_event(
		self,
		server_name: &ruma::ServerName,
		signing_key: &Ed25519KeyPair,
	) -> Result<Pdu, SigningError> {
		if self.state.contextualized.draft.timeline_event_type != TimelineEventType::RoomMember {
			return Err(SigningError::InvalidContent(
				"Refusing to sign non-member event".to_owned(),
			));
		}
		let room_version = self.state.contextualized.room_version;
		let mut signatures = self.state.signatures.clone();
		let room_event = RoomEvent { state: Contextualized::from_signed_for_resign(self.state)? };
		let mut event = room_event.sign_event(server_name, signing_key)?;
		signatures.append(&mut event.state.signed.signatures);
		let event = RoomEvent {
			state: Verified {
				signed: Signed { signatures, ..event.state.signed },
				metadata: VerificationMetadata {
					attempted_at: MilliSecondsSinceUnixEpoch::now(),
					signature_verification: crate::types::PartsVerified::CompleteEvent,
					room_version,
					soft_failed: false,
				},
			},
		};
		Ok(event.to_pdu())
	}

	/// Sign an event without checking authorization rules
	///
	/// Only enabled in tests, because it allows you to do insecure things, and doing insecure
	/// things should be as difficult as possible.
	#[cfg(any(feature = "test_utils", test))]
	pub fn sign_nonverified_event(
		self,
		server_name: &ruma::ServerName,
		signing_key: &Ed25519KeyPair,
	) -> Result<RoomEvent<Verified>, SigningError> {
		let room_version = self.state.contextualized.room_version;
		let mut signatures = self.state.signatures.clone();
		let room_event = RoomEvent { state: self.state.contextualized };
		let mut event = room_event.sign_event(server_name, signing_key)?;
		signatures.append(&mut event.state.signed.signatures);
		let event = RoomEvent {
			state: Verified {
				signed: Signed { signatures, ..event.state.signed },
				metadata: VerificationMetadata::example(room_version),
			},
		};
		Ok(event)
	}

	/// Deserializes a federation PDU and constructs a [`RoomEvent<Signed>`].
	///
	/// ## Parameters
	///
	/// - `pdu`: Raw JSON PDU bytes.
	/// - `room_version`: Room version used to validate `auth_events` and `prev_events` format in
	///   `Contextualized::new`.
	///
	/// ## Errors
	///
	/// Returns [`FromPduError`] if:
	///
	/// - The PDU JSON cannot be deserialized
	/// - Event refs do not match the room version, or exceed allowed counts
	/// - Event content fails draft validation
	/// - Event ID generation fails
	pub fn signed_from_pdu(
		pdu: &serde_json::value::RawValue,
		room_version: KnownRoomVersionId,
	) -> Result<Self, FromPduError> {
		#[derive(serde::Deserialize)]
		struct SignedFederationEvent {
			content: Box<serde_json::value::RawValue>,
			#[serde(rename = "type")]
			event_type: TimelineEventType,
			event_id: Option<OwnedEventId>,
			depth: u64,
			room_id: Option<OwnedRoomId>,
			sender: OwnedUserId,
			hashes: EventHash,
			state_key: Option<String>,
			redacts: Option<OwnedEventId>,
			#[serde(deserialize_with = "EventRefs::pdu_deserialize")]
			auth_events: EventRefs,
			#[serde(deserialize_with = "EventRefs::pdu_deserialize")]
			prev_events: EventRefs,
			membership: Option<MembershipState>,
			origin: Option<OwnedServerName>,
			prev_state: Option<EventRefs>,
			origin_server_ts: MilliSecondsSinceUnixEpoch,
			signatures: ruma::ServerSignatures,
		}

		let SignedFederationEvent {
			content,
			event_type,
			event_id,
			depth,
			room_id,
			sender,
			hashes,
			state_key,
			redacts,
			auth_events,
			prev_events,
			prev_state,
			origin_server_ts,
			signatures,
			membership,
			origin,
		} = serde_json::from_str(pdu.get())?;

		Self::new_signed(
			content,
			depth,
			event_type,
			room_id,
			sender,
			state_key,
			redacts,
			room_version,
			auth_events,
			prev_events,
			prev_state,
			membership,
			origin,
			origin_server_ts,
			event_id,
			signatures,
			hashes,
		)
	}

	/// Validate the signature of the event, without checking auth rules
	pub fn validate_signature(
		&self,
		required_verify_keys: &PublicKeyMap,
	) -> Result<(), ValidationError> {
		let room_version_rules = &self.state.contextualized.room_version.rules();
		let canonical = self
			.state
			.build_event_object()
			.map_err(|error| ValidationError::JsonCanonicalization(error.to_string()))?;

		ruma::signatures::verify_event(required_verify_keys, &canonical, room_version_rules)
			.map_err(|err| ValidationError::SignatureValidation(err.to_string()))?;
		Ok(())
	}

	/// Verify a [`Signed`] event from federation or other external source.
	/// Yields a [`RoomEvent<Verified>`].
	///
	/// This method performs the following steps:
	///
	/// 1. **Signature Verification**: Cryptographically verifies all signatures in the event
	///    against the provided `required_verify_keys`.
	/// 2. **Authorization Check**: Validates the event against room state using ruma's
	///    `state_res::check_state_dependent_auth_rules`.
	///
	/// ## Parameters
	///
	/// - `previous_state`: The room state corresponding to the resolution of the state of this
	///   event's `prev_events`.
	/// - `auth_events`: The specific auth events referenced by this event.
	/// - `current_state`: The room state at the time the event is being verified. If the event
	///   fails this auth check, it will be soft-failed: the returned [`RoomEvent<Verified>`] will
	///   have [`VerificationMetadata::soft_failed`] set to `true`.
	/// - `required_verify_keys`: Pre-fetched public keys used to verify the event signatures.
	///
	/// ## Errors
	///
	/// Returns [`ValidationError`] if:
	///
	/// - **Invalid signature**: Cryptographic signature verification fails
	/// - **Event ID mismatch**: Computed reference hash doesn't match event ID
	/// - **Authorization fails**: Event fails room authorization rules
	/// - **Canonical JSON error**: Cannot canonicalize the event
	pub fn verify(
		self,
		previous_state: &HashMap<(StateEventType, StateKey), RoomEvent<Verified>>,
		auth_events: &HashMap<(StateEventType, StateKey), RoomEvent<Verified>>,
		current_state: &HashMap<(StateEventType, StateKey), RoomEvent<Verified>>,
		required_verify_keys: &PublicKeyMap,
	) -> Result<RoomEvent<Verified>, ValidationError> {
		self.validate_signature(required_verify_keys)?;

		self.check_auth(auth_events)?; // matrix spec: Server-Server: #5.1.4
		self.check_auth(previous_state)?; // matrix spec: Server-Server: #5.1.5
		let soft_failed = self.check_auth(current_state).is_err(); // matrix spec: Server-Server: #5.1.6

		let metadata = VerificationMetadata {
			attempted_at: MilliSecondsSinceUnixEpoch::now(),
			signature_verification: crate::types::PartsVerified::CompleteEvent,
			room_version: self.state.contextualized.room_version,
			soft_failed,
		};

		Ok(RoomEvent { state: Verified { signed: self.state, metadata } })
	}

	/// Builds a PDU representation for use in authorization checks.
	#[must_use]
	pub fn build_pdu_for_auth(&self) -> Pdu {
		self.state.build_pdu()
	}

	/// Checks authorization rules for the current event
	fn check_auth(
		&self,
		context_events: &HashMap<(StateEventType, StateKey), RoomEvent<Verified>>,
	) -> Result<(), AuthorizationError> {
		let pdu_for_auth = self.build_pdu_for_auth();
		let fetch_state = |event_type: &StateEventType, state_key: &str| -> Option<Pdu> {
			context_events.get(&(event_type.clone(), state_key.to_owned())).map(RoomEvent::to_pdu)
		};
		state_res::check_state_dependent_auth_rules(
			&self.state.contextualized.room_version.rules().authorization,
			pdu_for_auth,
			fetch_state,
		)
		.map_err(AuthorizationError::AuthorizationFailed)?;
		Ok(())
	}
}

impl RoomEvent<Verified> {
	/// Formats the event into a `Box<RawJsonValue>` representation based on the
	/// requested formatting.
	///
	/// This method adapts the internal event state to match the required JSON
	/// schema of the target consumer. Depending on the `event_format`
	/// provided, it generates either:
	///
	/// - A **Client-formatted event**: Strips out federation-specific metadata and injects
	///   client-specific context (such as room state or user relations) using the provided
	///   `ClientContext`. Suitable for the Matrix Client-Server API. For more specific context
	///   check `to_client_event` method.
	/// - A **Federation-formatted event**: Retains all cryptographic data (`signatures`, `hashes`)
	///   and DAG context (`prev_events`, `auth_events`)
	///
	/// ## Parameters
	///
	/// * `event_format` - The target format (`filter::EventFormat::Client` or
	///   `filter::EventFormat::Federation`).
	/// * `ctx` - The client context required for resolving client-specific fields. Unused if
	///   `event_format` is set to `Federation`.
	#[must_use]
	pub fn format_as(
		&self,
		event_format: &filter::EventFormat,
		ctx: ClientContext,
	) -> Box<RawJsonValue> {
		match event_format {
			filter::EventFormat::Federation => raw_json(&self.state.signed.build_event_value()),
			_ => self.to_client_event(ctx),
		}
	}

	/// Create a new verified event from a PDU
	///
	/// As this creates a new `Verified` event, this function is somewhat
	/// dangerous, since it technically lets you bypass verification. Therefore,
	/// care should be taken only to use this function on events from the
	/// database
	///
	/// ## Parameters
	///
	///  - `pdu`: The PDU we're loading
	///  - `metadata`: Verification metadata, stored from earlier
	pub fn verified_from_pdu(
		pdu: &serde_json::value::RawValue,
		metadata: VerificationMetadata,
	) -> Result<Self, FromPduError> {
		let signed = RoomEvent::signed_from_pdu(pdu, metadata.room_version)?;
		Ok(Self { state: Verified { signed: signed.state, metadata } })
	}

	/// Convert the verified event to a PDU (Persistent Data Unit) for
	/// federation.
	///
	/// This method serializes the event into the PDU format required by the
	/// Matrix federation protocol. The output format varies by room version.
	#[must_use]
	pub fn to_pdu(&self) -> Pdu {
		self.state.signed.build_pdu()
	}

	/// Convert the verified event to a client event for the Matrix
	/// client-server API.
	///
	/// This method transforms the event into the format expected by Matrix
	/// clients, removing federation-only fields and adding client-specific
	/// metadata.
	///
	/// Returns a [`ClientEvent`] (boxed raw JSON) ready to be sent to a Matrix
	/// client via sync, `/rooms/{roomId}/messages`, or other client API
	/// endpoints.
	///
	/// ## Transformations
	///
	/// The conversion:
	/// - Removes federation-only fields: `auth_events`, `prev_events`
	/// - Always includes `event_id` (regardless of room version)
	/// - Adds `unsigned` object with client context:
	///   - `transaction_id`: Local transaction ID if this was sent by the client
	///   - `age`: Event age in milliseconds (for sync responses)
	/// - Removes `depth` field (not used in client API)
	///
	/// ## Client Context
	///
	/// The [`ClientContext`] parameter provides client-specific metadata:
	/// - `transaction_id`: Set when the client sent this event, allowing them to correlate their
	///   send with the resulting event
	/// - `age`: Time since the event was created, useful for clients to show relative timestamps
	///
	/// Both fields are optional - omit them when not applicable.
	///
	/// ## Parameters
	///
	/// - `ctx`: Client-specific context containing optional transaction ID and age.
	#[must_use]
	pub fn to_client_event(&self, ctx: ClientContext) -> ClientEvent {
		let mut event = serde_json::Map::new();
		let content_map = self.state.signed.contextualized.draft.content_to_map();
		event.insert("content".to_owned(), serde_json::Value::Object(content_map));
		event.insert(
			"event_id".to_owned(),
			self.state.signed.contextualized.event_id.to_string().into(),
		);
		event.insert(
			"origin_server_ts".to_owned(),
			serde_json::Value::Number(serde_json::Number::from(u64::from(
				self.state.signed.contextualized.origin_server_ts.0,
			))),
		);
		event.insert(
			"room_id".to_owned(),
			serde_json::Value::String(self.state.signed.contextualized.room_id.to_string()),
		);
		event.insert(
			"sender".to_owned(),
			serde_json::Value::String((self.state.signed.contextualized.draft.sender).to_string()),
		);
		if let Some(state_key) = &self.state.signed.contextualized.draft.state_key {
			event.insert("state_key".to_owned(), serde_json::Value::String(state_key.to_owned()));
		}
		event.insert(
			"type".to_owned(),
			serde_json::Value::String(
				self.state.signed.contextualized.draft.timeline_event_type.to_string(),
			),
		);

		let unsigned = build_unsigned(ctx);
		if let Some(unsigned) = unsigned {
			event.insert("unsigned".to_owned(), unsigned);
		}

		raw_json(&serde_json::Value::Object(event))
	}

	/// Convert the verified event to a stripped state event for the
	/// client-server API.
	///
	/// Specifically, we are following the specification here: <https://spec.matrix.org/v1.18/client-server-api/#stripped-state>
	///
	/// The event contains the fields `content`, `sender`, `state_key` and
	/// `type`
	///
	/// # Errors
	///
	/// This function will return an error if it's called on a non-state event
	pub fn to_stripped_state_event(
		&self,
	) -> Result<Raw<AnyStrippedStateEvent>, EventIsNotStateEvent> {
		let state_key =
			self.state.signed.contextualized.draft.state_key.clone().ok_or(EventIsNotStateEvent)?;
		let event = json!({
			"content": self.state.signed.contextualized.draft.content,
			"sender": self.state.signed.contextualized.draft.sender,
			"state_key": state_key,
			"type": self.state.signed.contextualized.draft.timeline_event_type,
		});
		Ok(Raw::from_json(raw_json(&event)))
	}

	/// Add an additional signature to this already verified event.
	///
	/// ## Rationale
	///
	/// This is used when joining a federated room. The joining server signs
	/// the event, after which the resident server counter-signs it before
	/// persisting and federating it.
	///
	/// ## Errors
	///
	/// Returns a [`SigningError`] if canonical JSON construction or signing
	/// fails for any reason
	pub fn sign(
		self,
		server_name: &ruma::ServerName,
		signing_key: &Ed25519KeyPair,
	) -> Result<Self, SigningError> {
		let room_version_rules = &self.state.signed.contextualized.room_version.rules();
		let mut canonical = self.state.signed.build_event_object()?;
		ruma::signatures::hash_and_sign_event(
			server_name.as_str(),
			signing_key,
			&mut canonical,
			&room_version_rules.redaction,
		)
		.map_err(|error| SigningError::SignatureCreation(error.to_string()))?;

		let signatures = extract_signatures(&canonical)?;

		Ok(Self {
			state: Verified {
				signed: Signed { signatures, ..self.state.signed },
				metadata: self.state.metadata,
			},
		})
	}
}