//! The player's operations on a remote realm, over a verified [`PlayerChannel`]: get or reuse an account, link an existing one, list and claim characters. //! The player's realm credentials are kept in the protected store and nowhere else; the control database remembers only account names. use std::collections::BTreeMap; use std::path::Path; use std::sync::{Arc, Mutex}; use base64::Engine; use coa_control_proto::app::{self, AppError, CharacterEntry, Request, Response}; use coa_control_proto::coord; use coa_registry_proto::{RealmDetail, RealmId}; use ed25519_dalek::VerifyingKey; use serde::{Deserialize, Serialize}; use uuid::Uuid; use super::identity::PlayerIdentity; use super::player::PlayerChannel; use super::secrets::SecretStore; use super::store::{AccountKind, ControlStore}; use super::transport::{self, LinkError}; use crate::{Error, Result}; mod portable_sync; /// Where and as whom to reach a realm. #[derive(Clone, Debug)] pub struct RealmTarget { pub realm_id: RealmId, pub key: VerifyingKey, /// The Coordinator's player endpoint (no query). pub coordinator: String, } impl RealmTarget { /// From the Registry's public record of the realm; the key published there is what the Host must prove it holds. pub fn from_detail(registry_url: &str, detail: &RealmDetail) -> Result { let key = coord::decode_public_key(&detail.public_key) .map_err(|e| Error::Invalid(e.to_string()))?; let coordinator = transport::coordinator_url(registry_url, "/coord/v1/player").ok_or_else(|| { Error::Invalid("the Registry address is not usable for a connection".into()) })?; Ok(RealmTarget { realm_id: detail.realm_id, key, coordinator, }) } } #[derive(Debug)] pub enum ControlFail { Link(LinkError), App { code: AppError, message: String }, Local(String), } impl ControlFail { pub fn code(&self) -> String { match self { ControlFail::Link(e) => e.code().to_string(), ControlFail::App { code, .. } => serde_json::to_value(code) .ok() .and_then(|v| v.as_str().map(str::to_string)) .unwrap_or_else(|| "error".into()), ControlFail::Local(_) => "local".into(), } } } impl std::fmt::Display for ControlFail { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { ControlFail::Link(e) => write!(f, "{e}"), ControlFail::App { message, .. } => write!(f, "{message}"), ControlFail::Local(m) => write!(f, "{m}"), } } } impl std::error::Error for ControlFail {} impl From for ControlFail { fn from(e: LinkError) -> Self { ControlFail::Link(e) } } impl From for ControlFail { fn from(e: Error) -> Self { ControlFail::Local(e.to_string()) } } type R = std::result::Result; /// What the player types into the game's login window. The password is shown or copied on request and never logged. #[derive(Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Credentials { pub username: String, pub password: String, } impl std::fmt::Debug for Credentials { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "Credentials({}, ****)", self.username) } } #[derive(Clone, Debug, PartialEq, Eq, Serialize)] pub struct AccountOutcome { pub username: String, pub created: bool, pub password_reset: bool, } #[derive(Debug, Clone)] pub struct Claimed { pub character_id: Uuid, pub ruleset: String, pub payload: Vec, pub sha256: [u8; 32], pub collections: BTreeMap>, } pub struct PlayerControl { pub identity: PlayerIdentity, secrets: Arc, store: Mutex, } fn secret_name(realm: &RealmId) -> String { format!("realm-{}", realm.to_string().replace('-', "")) } fn clock() -> i64 { std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .map(|d| d.as_secs() as i64) .unwrap_or(0) } fn expect( response: Response, ok: impl FnOnce(Response) -> std::result::Result, ) -> R { match ok(response) { Ok(v) => Ok(v), Err(Response::Error { code, message }) => Err(ControlFail::App { code, message }), Err(_) => Err(ControlFail::Link(LinkError::Protocol( "the answer does not match the question".into(), ))), } } impl PlayerControl { pub fn open(dir: &Path, secrets: Arc) -> Result { let identity = PlayerIdentity::load_or_create(secrets.as_ref())?; Ok(Self { identity, secrets, store: Mutex::new(ControlStore::open(dir)?), }) } pub fn secret_store_kind(&self) -> &'static str { self.secrets.kind() } fn store(&self) -> R> { self.store .lock() .map_err(|_| ControlFail::Local("the control database is busy".into())) } /// The credentials the realm has confirmed (a password still waiting for the realm's confirmation is not one). pub fn credentials(&self, realm: &RealmId) -> Result> { Ok(self .raw_credentials(realm)? .filter(|c| !c.username.is_empty())) } fn raw_credentials(&self, realm: &RealmId) -> Result> { let Some(bytes) = self.secrets.get(&secret_name(realm))? else { return Ok(None); }; serde_json::from_slice(&bytes) .map(Some) .map_err(|_| Error::Invalid("the saved credentials for this server are damaged".into())) } fn save_credentials(&self, realm: &RealmId, c: &Credentials) -> Result<()> { self.secrets .put(&secret_name(realm), &serde_json::to_vec(c)?) } /// Forget the account on a realm (the saved password and the name). The account itself stays on the realm. pub fn forget(&self, realm: &RealmId) -> R<()> { self.secrets.delete(&secret_name(realm))?; self.store()?.player_realm_remove(&realm.to_string())?; Ok(()) } pub fn known_account(&self, realm: &RealmId) -> R> { Ok(self .store()? .player_realm(&realm.to_string())? .map(|r| (r.username, r.kind))) } /// Open a verified channel to the realm's Host. The realm's key is pinned the first time: the Registry says which key a realm id has, and a Registry (or anything between) that later /// names another key for the same id is refused here, before anything is sent. pub fn connect(&self, target: &RealmTarget) -> R { let id = target.realm_id.to_string(); let key = coord::encode_public_key(&target.key); match self.store()?.realm_pin(&id)? { Some(pinned) if pinned != key => { return Err(ControlFail::Link(LinkError::Auth( "this realm's key is not the one it had when you first joined it".into(), ))) } _ => {} } let channel = PlayerChannel::connect( &target.coordinator, &target.realm_id, &target.key, &self.identity, &clock, )?; self.store()?.realm_pin_set(&id, &key)?; Ok(channel) } pub fn welcome(&self, ch: &mut PlayerChannel) -> R<(bool, bool, Option)> { let r = ch.request(&Request::Hello { protocol: coa_control_proto::CONTROL_PROTOCOL_VERSION, client: "coa-manager".into(), })?; expect(r, |r| match r { Response::Welcome { automatic, existing_only, route, .. } => Ok((automatic, existing_only, route)), other => Err(other), }) } /// The account on this realm: reused when the player has one, created otherwise (on realms that create accounts). The generated password is saved *before* it is /// sent, so a crash between the Host creating the account and the player learning of it leaves a password that the next call sets again. pub fn ensure_account( &self, ch: &mut PlayerChannel, realm: &RealmId, preferred: Option<&str>, ) -> R { let saved = self.raw_credentials(realm)?; // saved credentials with no account name are a password that was made but never confirmed by the realm: it is sent again, as a new one let have = saved.as_ref().is_some_and(|c| !c.username.is_empty()); let password = saved .as_ref() .map(|c| c.password.clone()) .unwrap_or_else(app::generate_password); if saved.is_none() { self.save_credentials( realm, &Credentials { username: String::new(), password: password.clone(), }, )?; } let r = ch.request(&Request::Provision { desired: preferred.map(str::to_string), password: password.clone(), have_credentials: have, })?; let (username, created, reset) = expect(r, |r| match r { Response::Provisioned { username, created, reset, } => Ok((username, created, reset)), other => Err(other), }) .inspect_err(|e| { // a refusal means the pending password will never be used; a lost connection keeps it for the next try if !have && matches!(e, ControlFail::App { .. }) { let _ = self.secrets.delete(&secret_name(realm)); } })?; self.save_credentials( realm, &Credentials { username: username.clone(), password, }, )?; // an account the player linked stays a linked one when the realm confirms it again let kind = match self.store()?.player_realm(&realm.to_string())? { Some(known) if known.username == username => known.kind, _ => AccountKind::Generated, }; self.store()? .player_realm_set(&realm.to_string(), &username, kind)?; Ok(AccountOutcome { username, created, password_reset: reset, }) } /// One-time link of an account the realm already has. pub fn link_existing( &self, ch: &mut PlayerChannel, realm: &RealmId, login: &str, password: &str, ) -> R { let r = ch.request(&Request::Link { login: login.to_string(), password: password.to_string(), })?; let username = expect(r, |r| match r { Response::Linked { username } => Ok(username), other => Err(other), })?; self.save_credentials( realm, &Credentials { username: username.clone(), password: password.to_string(), }, )?; self.store()? .player_realm_set(&realm.to_string(), &username, AccountKind::Linked)?; Ok(username) } pub fn list_characters(&self, ch: &mut PlayerChannel) -> R> { let r = ch.request(&Request::ListCharacters)?; expect(r, |r| match r { Response::Characters { characters } => Ok(characters), other => Err(other), }) } pub fn claim(&self, ch: &mut PlayerChannel, token: u32) -> R { let r = ch.request(&Request::Claim { token })?; let (character_id, ruleset, sha256, payload, collections) = expect(r, |r| match r { Response::Claimed { character_id, ruleset, sha256, payload, collections, } => Ok((character_id, ruleset, sha256, payload, collections)), other => Err(other), })?; let payload = base64::engine::general_purpose::STANDARD .decode(payload) .map_err(|_| { ControlFail::Link(LinkError::Protocol( "the character data is not valid".into(), )) })?; let hash: [u8; 32] = hex::decode(&sha256) .ok() .and_then(|b| b.try_into().ok()) .ok_or_else(|| { ControlFail::Link(LinkError::Protocol( "the character hash is not valid".into(), )) })?; Ok(Claimed { character_id, ruleset, payload, sha256: hash, collections, }) } /// Tell the Host the character is safely stored here; only then is the claim final. pub fn acknowledge( &self, ch: &mut PlayerChannel, character_id: Uuid, realm: &RealmId, name: &str, ) -> R<()> { self.store()? .player_claim_add(&realm.to_string(), &character_id, name)?; let r = ch.request(&Request::ClaimAck { character_id })?; expect(r, |r| match r { Response::Done => Ok(()), other => Err(other), }) } pub fn route(&self, ch: &mut PlayerChannel) -> R> { let r = ch.request(&Request::Route)?; expect(r, |r| match r { Response::RouteInfo { address } => Ok(address), other => Err(other), }) } pub fn claimed_here(&self, realm: &RealmId) -> R> { Ok(self.store()?.player_claims(&realm.to_string())?) } /// Transfer a portable character to a remote realm over the verified control channel (Phase 12.1). fn transfer_with_id( &self, ch: &mut PlayerChannel, transfer_id: Uuid, owned_session: bool, character_id: Uuid, ruleset: &str, canonical_revision: u64, payload: &[u8], content_hash: [u8; 32], collections: BTreeMap>, ) -> R { let content_hash_str = hex::encode(content_hash); let offer = if owned_session { Request::OwnedTransferOffer { transfer_id, character_id, ruleset: ruleset.to_string(), canonical_revision, content_hash: content_hash_str.clone(), total_size: payload.len(), collections, } } else { Request::TransferOffer { transfer_id, character_id, ruleset: ruleset.to_string(), canonical_revision, content_hash: content_hash_str.clone(), total_size: payload.len(), collections, } }; let r = ch.request(&offer)?; let mut offset = match r { Response::TransferReady { received_offset, .. } => received_offset, Response::TransferCommitted { local_guid, session_id, projected_level, notes, .. } => { let _ = ch.request(&Request::TransferAck { transfer_id, character_id, }); return Ok(RemoteTransferOutcome { local_guid, session_id, projected_level, notes, }); } Response::Error { code, message } => { if owned_session && matches!( code, AppError::Incompatible | AppError::NotYours | AppError::AlreadyClaimed | AppError::Invalid ) { self.store()? .player_remote_session_remove(character_id, transfer_id)?; } return Err(ControlFail::App { code, message }); } _ => { return Err(ControlFail::Link(LinkError::Protocol( "unexpected response to transfer offer".into(), ))) } }; const CHUNK_SIZE: usize = 128 * 1024; while offset < payload.len() { let end = (offset + CHUNK_SIZE).min(payload.len()); let chunk_data = base64::engine::general_purpose::STANDARD.encode(&payload[offset..end]); let chunk_req = Request::TransferChunk { transfer_id, offset, data: chunk_data, }; let cr = ch.request(&chunk_req)?; match cr { Response::TransferChunkAck { received_offset, .. } => { offset = received_offset; } Response::Error { code, message } => { return Err(ControlFail::App { code, message }) } _ => { return Err(ControlFail::Link(LinkError::Protocol( "unexpected response to transfer chunk".into(), ))) } } } let commit_req = Request::TransferCommit { transfer_id }; let commit_resp = ch.request(&commit_req)?; let outcome = expect(commit_resp, |r| match r { Response::TransferCommitted { local_guid, session_id, projected_level, notes, .. } => Ok(RemoteTransferOutcome { local_guid, session_id, projected_level, notes, }), other => Err(other), })?; let _ = ch.request(&Request::TransferAck { transfer_id, character_id, }); Ok(outcome) } /// Request a short-lived Game Relay allocation for a relayed JOIN (Phase 13). pub fn allocate_relay( &self, ch: &mut PlayerChannel, ) -> R { let req = Request::AllocateRelay { player_id: self.identity.player_id, }; let resp = ch.request(&req)?; expect(resp, |r| match r { Response::RelayAllocated { relay_host, auth_port, world_port, token, expires_at, } => Ok(crate::control::relay_link::RelayAllocationInfo { relay_host, auth_port, world_port, token, expires_at, }), other => Err(other), }) } } #[derive(Debug, Clone, PartialEq, Eq)] pub struct RemoteTransferOutcome { pub local_guid: u32, pub session_id: Uuid, pub projected_level: Option, pub notes: Vec, }