//! The application messages inside the end-to-end channel. One request, one response, in order. Nothing here is ever visible to the Coordinator. use std::collections::BTreeMap; use serde::{Deserialize, Serialize}; use uuid::Uuid; use crate::{invalid, ControlError, Result}; pub const MAX_CONTROL_REQUEST_BYTES: usize = 4096; pub const MAX_TRANSFER_REQUEST_BYTES: usize = 4 * 1024 * 1024; // 4 MiB pub const MAX_REQUEST_BYTES: usize = MAX_TRANSFER_REQUEST_BYTES; pub const MIN_USERNAME: usize = 3; pub const MAX_USERNAME: usize = 16; pub const MIN_PASSWORD: usize = 8; pub const MAX_PASSWORD: usize = 16; pub const MAX_CHARACTERS: usize = 200; pub const MAX_SESSION_BYTES: usize = 12 * 1024 * 1024; #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum SessionMessageKind { Started, Checkpoint, Collection, } /// A game account name: 3 to 16 ASCII letters, digits or `_`, not beginning or ending with `_`. pub fn valid_username(s: &str) -> bool { (MIN_USERNAME..=MAX_USERNAME).contains(&s.len()) && s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_') && !s.starts_with('_') && !s.ends_with('_') } /// A game account password: 8 to 16 ASCII letters and digits (the game compares passwords case-insensitively, so letters carry no extra strength; digits and length do). pub fn valid_password(s: &str) -> bool { (MIN_PASSWORD..=MAX_PASSWORD).contains(&s.len()) && s.bytes().all(|b| b.is_ascii_alphanumeric()) } /// A password for a realm, 16 characters of `A-Z0-9` from the operating system's randomness (about 82 bits), unique per realm. pub fn generate_password() -> String { const ALPHABET: &[u8; 36] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"; let mut out = String::with_capacity(16); while out.len() < 16 { for b in Uuid::new_v4().as_bytes() { // rejection sampling: 252 is the largest multiple of 36 below 256, so every symbol is equally likely if *b < 252 && out.len() < 16 { out.push(ALPHABET[(*b % 36) as usize] as char); } } } out } /// The account name wanted, made fit for the game: letters and digits only, upper case, at most 16 characters. pub fn sanitize_username(wanted: &str) -> String { let base: String = wanted .chars() .filter(char::is_ascii_alphanumeric) .collect::() .to_ascii_uppercase(); let base: String = base.chars().take(MAX_USERNAME).collect(); if base.len() >= MIN_USERNAME { base } else { format!("{base}PLAYER").chars().take(MAX_USERNAME).collect() } } /// The stable alternative of an occupied name: `DMITRY` becomes `DMITRY_7K4M`. The suffix is derived from the player's id, so the same player gets the same alternative. pub fn alternative_username(base: &str, player: &Uuid, attempt: u32) -> String { const ALPHABET: &[u8; 32] = b"ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; let bytes = player.as_bytes(); let mix = u32::from_be_bytes([bytes[12], bytes[13], bytes[14], bytes[15]]) .wrapping_add(attempt.wrapping_mul(0x9E37_79B1)); let suffix: String = (0..4) .map(|i| ALPHABET[((mix >> (i * 5)) & 31) as usize] as char) .collect(); let keep = MAX_USERNAME - 5; let head: String = base.chars().take(keep).collect(); format!("{head}_{suffix}") } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(tag = "op", rename_all = "snake_case", deny_unknown_fields)] pub enum Request { Hello { protocol: u32, client: String, }, /// Make the player's account on this realm, or reuse it. `password` is the one the player's Manager keeps for this realm; it travels only inside the channel. Provision { desired: Option, password: String, have_credentials: bool, }, ListCharacters, Claim { token: u32, }, ClaimAck { character_id: Uuid, }, /// Link an account the realm already has (one time). Link { login: String, password: String, }, Route, /// Phase 12.1: Start or resume a remote portable character transfer. TransferOffer { transfer_id: Uuid, character_id: Uuid, ruleset: String, canonical_revision: u64, content_hash: String, total_size: usize, collections: BTreeMap>, }, OwnedTransferOffer { transfer_id: Uuid, character_id: Uuid, ruleset: String, canonical_revision: u64, content_hash: String, total_size: usize, collections: BTreeMap>, }, /// A chunk of the encoded portable character snapshot payload. TransferChunk { transfer_id: Uuid, offset: usize, data: String, }, /// Query status or resume progress of a transfer. TransferStatus { transfer_id: Uuid, }, /// Commit the transferred payload into the realm and arm a session. TransferCommit { transfer_id: Uuid, }, /// Acknowledge successful transfer and session arming. TransferAck { transfer_id: Uuid, character_id: Uuid, }, SessionPoll { character_id: Uuid, session_id: Uuid, }, SessionRead { character_id: Uuid, session_id: Uuid, message_hash: String, offset: usize, }, SessionAck { character_id: Uuid, session_id: Uuid, message_hash: String, offset: usize, total_size: usize, data: String, }, /// Phase 13: Request a short-lived relay allocation for a relayed JOIN. AllocateRelay { player_id: Uuid, }, } #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum AppError { UnsupportedVersion, Invalid, ProvisioningOff, NoAccount, NotAtCharacterSelect, NotYours, AlreadyClaimed, NotEligible, WrongCredentials, AccountTaken, RateLimited, Unavailable, Incompatible, Conflict, RelayUnavailable, } #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct CharacterEntry { /// Opaque to the player: the Host's handle for this character, valid for this realm. pub token: u32, pub name: String, pub class: u32, pub race: u32, pub level: u32, pub eligible: bool, pub reasons: Vec, /// Already portable and claimed by this player. pub yours: bool, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(tag = "op", rename_all = "snake_case")] pub enum Response { SessionPending { kind: SessionMessageKind, total_size: usize, content_hash: String, }, SessionIdle { closed: bool, }, SessionData { offset: usize, data: String, }, SessionAcked { received_size: usize, complete: bool, }, Welcome { realm_id: coa_registry_proto::RealmId, automatic: bool, existing_only: bool, route: Option, }, Provisioned { username: String, created: bool, reset: bool, }, Characters { characters: Vec, }, /// The character as the Host exported it: `payload` is the base64 of the encoded portable snapshot, `sha256` the hash of its canonical JSON, `collections` the account's /// appearance and vanity ids the Host holds for the account (kind -> ids). Claimed { character_id: Uuid, ruleset: String, sha256: String, payload: String, collections: BTreeMap>, }, Linked { username: String, }, Done, RouteInfo { address: Option, }, /// The Host is ready to receive transfer chunks (or indicates an offset to resume from). TransferReady { transfer_id: Uuid, received_offset: usize, }, /// Acknowledgement of a transfer chunk. TransferChunkAck { transfer_id: Uuid, received_offset: usize, }, /// Successful commit and session arm. TransferCommitted { transfer_id: Uuid, character_id: Uuid, local_guid: u32, session_id: Uuid, projected_level: Option, notes: Vec, }, /// Phase 13: Relay allocation details returned to the player. RelayAllocated { relay_host: String, auth_port: u16, world_port: u16, token: String, expires_at: i64, }, Error { code: AppError, message: String, }, } pub fn encode_request(r: &Request) -> Vec { serde_json::to_vec(r).expect("a request serialises") } pub fn decode_request(bytes: &[u8]) -> Result { if bytes.len() > MAX_TRANSFER_REQUEST_BYTES { return Err(ControlError::Limit("a request is too long".into())); } let r: Request = serde_json::from_slice(bytes) .map_err(|_| ControlError::Invalid("a request is not valid".into()))?; if !matches!( &r, Request::TransferOffer { .. } | Request::OwnedTransferOffer { .. } | Request::TransferChunk { .. } | Request::SessionAck { .. } ) && bytes.len() > MAX_CONTROL_REQUEST_BYTES { return Err(ControlError::Limit( "a standard control request exceeds 4096 bytes".into(), )); } match &r { Request::SessionRead { message_hash, offset, .. } => { if message_hash.len() != 64 || !message_hash.bytes().all(|b| b.is_ascii_hexdigit()) || *offset > MAX_SESSION_BYTES { return invalid("invalid portable session read"); } } Request::SessionAck { message_hash, offset, total_size, data, .. } => { if message_hash.len() != 64 || !message_hash.bytes().all(|b| b.is_ascii_hexdigit()) || *total_size > MAX_SESSION_BYTES || *offset > *total_size || data.len() > 48 * 1024 { return invalid("invalid portable session acknowledgement chunk"); } } Request::Provision { desired, password, .. } => { if !valid_password(password) || desired .as_deref() .is_some_and(|d| d.len() > 64 || d.chars().any(char::is_control)) { return invalid("a provisioning request has an unusable password or name"); } } Request::Link { login, password } => { if !valid_username(login) || !valid_password_for_link(password) { return invalid("a link request has an unusable login or password"); } } Request::Hello { client, .. } if client.len() > 64 => { return invalid("the client name is too long") } Request::TransferOffer { ruleset, content_hash, total_size, collections, .. } | Request::OwnedTransferOffer { ruleset, content_hash, total_size, collections, .. } => { if !matches!(ruleset.as_str(), "coa" | "wildcard" | "reborn") { return invalid("transfer ruleset must be coa, wildcard, or reborn"); } if content_hash.len() != 64 || !content_hash.chars().all(|c| c.is_ascii_hexdigit()) { return invalid("transfer content hash must be 64 hex characters"); } if *total_size > crate::noise::MAX_MESSAGE_BYTES { return Err(ControlError::Limit( "transfer total size is too large".into(), )); } if collections.len() > 1000 { return Err(ControlError::Limit( "collections dictionary exceeds 1,000 keys".into(), )); } let total_items: usize = collections.values().map(|v| v.len()).sum(); if total_items > 100_000 { return Err(ControlError::Limit( "collection mapping exceeds 100,000 entries".into(), )); } } Request::TransferChunk { offset, data, .. } => { if *offset > MAX_TRANSFER_REQUEST_BYTES { return Err(ControlError::Limit( "transfer chunk offset exceeds limit".into(), )); } if data.len() > MAX_TRANSFER_REQUEST_BYTES { return Err(ControlError::Limit("transfer chunk is too large".into())); } } _ => {} } Ok(r) } /// An existing account's password may be anything the game accepts (6 to 16 printable characters without spaces or quotes). pub fn valid_password_for_link(s: &str) -> bool { (6..=16).contains(&s.len()) && s.chars() .all(|c| c.is_ascii_graphic() && c != '"' && c != '\'' && c != '\\') } pub fn encode_response(r: &Response) -> Vec { serde_json::to_vec(r).expect("a response serialises") } pub fn decode_response(bytes: &[u8]) -> Result { if bytes.len() > MAX_TRANSFER_REQUEST_BYTES { return Err(ControlError::Limit("a response is too long".into())); } serde_json::from_slice(bytes) .map_err(|_| ControlError::Invalid("a response is not valid".into())) } #[cfg(test)] mod tests { use super::*; #[test] fn passwords_are_random_unique_and_fit_the_game() { let a = generate_password(); let b = generate_password(); assert_ne!(a, b); assert!( valid_password(&a) && a.len() == 16 && a.bytes() .all(|c| c.is_ascii_uppercase() || c.is_ascii_digit()), "{a}" ); let mut seen = std::collections::HashSet::new(); for _ in 0..200 { assert!(seen.insert(generate_password()), "no repeats"); } let symbols: std::collections::HashSet = (0..200) .flat_map(|_| generate_password().chars().collect::>()) .collect(); assert_eq!(symbols.len(), 36, "every symbol occurs"); } #[test] fn names_are_made_fit_and_the_alternative_is_stable() { assert_eq!(sanitize_username("Dmitry"), "DMITRY"); assert_eq!(sanitize_username("d m-i_t.r y"), "DMITRY"); assert_eq!(sanitize_username("ab"), "ABPLAYER"); assert_eq!( sanitize_username("a very long player name indeed"), "AVERYLONGPLAYERN" ); assert_eq!(sanitize_username("