diff --git a/README.md b/README.md index 928fa27..c92268b 100644 --- a/README.md +++ b/README.md @@ -59,9 +59,16 @@ Manager at the one you have, or let it download one for you. ## Status -Phases 0–10 of the plan in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) are done: foundation, import, start/stop, -config engine, backups, clean install from signed packages, updates, companions, client launch, friends, polish. -Remaining work (translation review by native speakers, optional extras) is listed in section 9 of that document. Translation notes: [docs/TRANSLATIONS.md](docs/TRANSLATIONS.md). +Phases 0–15 are complete: foundation, import, start/stop, config engine, backups, clean install from signed packages, +updates, companions, client launch, friends, public registry, end-to-end control plane (Noise XX), portable characters +with remote transfer and level projection, game relay fallback, verified direct connectivity (UPnP / NAT-PMP), +and security/release hardening. + +### Known Limitations +* **Native client login prefill**: Ascension's 3.3.5 client does not accept command-line credentials; users type their password once or link an existing account. +* **Non-Windows SecretStore**: Windows uses DPAPI (`CryptProtectData`) with domain separation entropy. On Linux/macOS, keys fall back to strict 0600 file permissions. +* **Direct to Relay migration**: Established direct TCP sessions cannot migrate mid-stream to Relay; network breaks trigger automatic fallback on the next JOIN. +* **WorkerThreads**: `CharacterDatabase.WorkerThreads` must be set to `1` (the default) for safe remote portable character imports. ## Develop ``` diff --git a/crates/coa-control-proto/src/app.rs b/crates/coa-control-proto/src/app.rs index 37dee1e..cbbc792 100644 --- a/crates/coa-control-proto/src/app.rs +++ b/crates/coa-control-proto/src/app.rs @@ -18,7 +18,10 @@ pub const MAX_CHARACTERS: usize = 200; /// 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('_') + (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). @@ -43,17 +46,28 @@ pub fn generate_password() -> String { /// 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 = 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() } + 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 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}") @@ -62,14 +76,28 @@ pub fn alternative_username(base: &str, player: &Uuid, attempt: u32) -> String { #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(tag = "op", rename_all = "snake_case", deny_unknown_fields)] pub enum Request { - Hello { protocol: u32, client: String }, + 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 }, + Provision { + desired: Option, + password: String, + have_credentials: bool, + }, ListCharacters, - Claim { token: u32 }, - ClaimAck { character_id: Uuid }, + Claim { + token: u32, + }, + ClaimAck { + character_id: Uuid, + }, /// Link an account the realm already has (one time). - Link { login: String, password: String }, + Link { + login: String, + password: String, + }, Route, /// Phase 12.1: Start or resume a remote portable character transfer. TransferOffer { @@ -105,7 +133,6 @@ pub enum Request { }, } - #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum AppError { @@ -144,19 +171,45 @@ pub struct CharacterEntry { #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(tag = "op", rename_all = "snake_case")] pub enum Response { - Welcome { realm_id: coa_registry_proto::RealmId, automatic: bool, existing_only: bool, route: Option }, - Provisioned { username: String, created: bool, reset: bool }, - Characters { characters: Vec }, + 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, sha256: String, payload: String, collections: BTreeMap> }, - Linked { username: String }, + Claimed { + character_id: Uuid, + sha256: String, + payload: String, + collections: BTreeMap>, + }, + Linked { + username: String, + }, Done, - RouteInfo { address: Option }, + 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 }, + TransferReady { + transfer_id: Uuid, + received_offset: usize, + }, /// Acknowledgement of a transfer chunk. - TransferChunkAck { transfer_id: Uuid, received_offset: usize }, + TransferChunkAck { + transfer_id: Uuid, + received_offset: usize, + }, /// Successful commit and session arm. TransferCommitted { transfer_id: Uuid, @@ -174,10 +227,12 @@ pub enum Response { token: String, expires_at: i64, }, - Error { code: AppError, message: String }, + Error { + code: AppError, + message: String, + }, } - pub fn encode_request(r: &Request) -> Vec { serde_json::to_vec(r).expect("a request serialises") } @@ -186,13 +241,26 @@ 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::TransferChunk { .. }) && bytes.len() > MAX_CONTROL_REQUEST_BYTES { - return Err(ControlError::Limit("a standard control request exceeds 4096 bytes".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::TransferChunk { .. } + ) && bytes.len() > MAX_CONTROL_REQUEST_BYTES + { + return Err(ControlError::Limit( + "a standard control request exceeds 4096 bytes".into(), + )); } match &r { - Request::Provision { desired, password, .. } => { - if !valid_password(password) || desired.as_deref().is_some_and(|d| d.len() > 64 || d.chars().any(char::is_control)) { + 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"); } } @@ -201,20 +269,41 @@ pub fn decode_request(bytes: &[u8]) -> Result { 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 { content_hash, total_size, collections, .. } => { + Request::Hello { client, .. } if client.len() > 64 => { + return invalid("the client name is too long") + } + Request::TransferOffer { + content_hash, + total_size, + collections, + .. + } => { 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())); + 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())); + return Err(ControlError::Limit( + "collection mapping exceeds 100,000 entries".into(), + )); } } - Request::TransferChunk { data, .. } => { + 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())); } @@ -226,7 +315,9 @@ pub fn decode_request(bytes: &[u8]) -> Result { /// 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 != '\\') + (6..=16).contains(&s.len()) + && s.chars() + .all(|c| c.is_ascii_graphic() && c != '"' && c != '\'' && c != '\\') } pub fn encode_response(r: &Response) -> Vec { @@ -234,7 +325,11 @@ pub fn encode_response(r: &Response) -> Vec { } pub fn decode_response(bytes: &[u8]) -> Result { - serde_json::from_slice(bytes).map_err(|_| ControlError::Invalid("a response is not valid".into())) + 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)] @@ -246,12 +341,20 @@ mod tests { 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}"); + 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(); + let symbols: std::collections::HashSet = (0..200) + .flat_map(|_| generate_password().chars().collect::>()) + .collect(); assert_eq!(symbols.len(), 36, "every symbol occurs"); } @@ -260,21 +363,45 @@ mod tests { 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("a very long player name indeed"), + "AVERYLONGPLAYERN" + ); assert_eq!(sanitize_username("