Files
coa-server-manager/crates/coa-control-proto/src/app.rs
T

585 lines
19 KiB
Rust

//! 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::<String>()
.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<String>,
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<String, Vec<u32>>,
},
OwnedTransferOffer {
transfer_id: Uuid,
character_id: Uuid,
ruleset: String,
canonical_revision: u64,
content_hash: String,
total_size: usize,
collections: BTreeMap<String, Vec<u32>>,
},
/// 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<String>,
/// 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<String>,
},
Provisioned {
username: String,
created: bool,
reset: bool,
},
Characters {
characters: Vec<CharacterEntry>,
},
/// 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<String, Vec<u32>>,
},
Linked {
username: String,
},
Done,
RouteInfo {
address: Option<String>,
},
/// 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<u32>,
notes: Vec<String>,
},
/// 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<u8> {
serde_json::to_vec(r).expect("a request serialises")
}
pub fn decode_request(bytes: &[u8]) -> Result<Request> {
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<u8> {
serde_json::to_vec(r).expect("a response serialises")
}
pub fn decode_response(bytes: &[u8]) -> Result<Response> {
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<char> = (0..200)
.flat_map(|_| generate_password().chars().collect::<Vec<_>>())
.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("<script>"), "SCRIPT");
assert!(
valid_username(&sanitize_username("")) && valid_username(&sanitize_username("日本語"))
);
let p = Uuid::now_v7();
let alt = alternative_username("DMITRY", &p, 0);
assert!(
valid_username(&alt) && alt.starts_with("DMITRY_") && alt.len() == 11,
"{alt}"
);
assert_eq!(
alt,
alternative_username("DMITRY", &p, 0),
"stable for the same player"
);
assert_ne!(
alt,
alternative_username("DMITRY", &p, 1),
"another attempt, another suffix"
);
assert_ne!(alt, alternative_username("DMITRY", &Uuid::now_v7(), 0));
assert_eq!(
alternative_username("ABCDEFGHIJKLMNOP", &p, 0).len(),
16,
"a long name is shortened to make room"
);
}
#[test]
fn requests_are_strict() {
let ok = encode_request(&Request::Provision {
desired: Some("DMITRY".into()),
password: generate_password(),
have_credentials: false,
});
assert!(decode_request(&ok).is_ok());
for bad in [
br#"{"op":"provision","desired":null,"password":"short","have_credentials":false}"#.as_slice(),
br#"{"op":"provision","desired":null,"password":"has space 123456","have_credentials":false}"#,
br#"{"op":"claim","token":1,"extra":true}"#,
br#"{"op":"link","login":"a b","password":"secret1"}"#,
br#"{"op":"unknown"}"#,
b"not json",
] {
assert!(decode_request(bad).is_err(), "{}", String::from_utf8_lossy(bad));
}
assert!(decode_request(&vec![b' '; MAX_REQUEST_BYTES + 1]).is_err());
assert!(decode_request(br#"{"op":"list_characters"}"#).is_ok());
assert!(
valid_password_for_link("pa55-w0rd")
&& !valid_password_for_link("has\"quote")
&& !valid_password_for_link("short")
);
}
#[test]
fn transfer_messages_roundtrip_and_validate() {
let tid = Uuid::new_v4();
let cid = Uuid::new_v4();
let hash = "a".repeat(64);
let offer = Request::TransferOffer {
transfer_id: tid,
character_id: cid,
ruleset: "coa".into(),
canonical_revision: 5,
content_hash: hash.clone(),
total_size: 1024,
collections: BTreeMap::new(),
};
let encoded = encode_request(&offer);
let decoded = decode_request(&encoded).unwrap();
assert_eq!(offer, decoded);
let bad_hash = Request::TransferOffer {
transfer_id: tid,
character_id: cid,
ruleset: "coa".into(),
canonical_revision: 5,
content_hash: "too_short".into(),
total_size: 1024,
collections: BTreeMap::new(),
};
assert!(decode_request(&encode_request(&bad_hash)).is_err());
let chunk = Request::TransferChunk {
transfer_id: tid,
offset: 0,
data: "aGVsbG8=".into(),
};
assert_eq!(chunk, decode_request(&encode_request(&chunk)).unwrap());
let resp = Response::TransferCommitted {
transfer_id: tid,
character_id: cid,
local_guid: 42,
session_id: Uuid::new_v4(),
projected_level: Some(60),
notes: vec!["Projected".into()],
};
let resp_dec = decode_response(&encode_response(&resp)).unwrap();
assert_eq!(resp, resp_dec);
// Control protocol v2 requires ruleset in TransferOffer; missing is rejected
let missing_ruleset_json = serde_json::json!({
"op": "transfer_offer",
"transfer_id": tid,
"character_id": cid,
"canonical_revision": 5,
"content_hash": hash,
"total_size": 1024,
"collections": {}
});
let encoded_missing = serde_json::to_vec(&missing_ruleset_json).unwrap();
assert!(
decode_request(&encoded_missing).is_err(),
"missing ruleset in v2 must be rejected"
);
}
}