mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-19 03:25:56 +00:00
- Enforce fail-closed backend resolution in LocalBackend::info (unknown ruleset = error). - Implement strict three-space isolation (Wildcard != CoA != Reborn) across canonical store, host mappings, and collections. - Isolate collection namespaces (wildcard:appearance, wildcard:vanity) and reject cross-ruleset collections in claim and import. - Enforce Control Protocol v2 ruleset verification on TransferOffer, TransferCommit, and Claimed response. - Route Direct Ingress and Relay Link dynamically according to realm world port (8085 for CoA, 8086 for Wildcard). - Add runtime session attack rejection test suite (cross-ruleset session offers, checkpoints, owner acks, server IDs). - Verify end-to-end Wildcard session lifecycle and documentation updates.
555 lines
18 KiB
Rust
555 lines
18 KiB
Rust
//! 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};
|
|
|
|
/// 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<RealmTarget> {
|
|
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<LinkError> for ControlFail {
|
|
fn from(e: LinkError) -> Self {
|
|
ControlFail::Link(e)
|
|
}
|
|
}
|
|
|
|
impl From<Error> for ControlFail {
|
|
fn from(e: Error) -> Self {
|
|
ControlFail::Local(e.to_string())
|
|
}
|
|
}
|
|
|
|
type R<T> = std::result::Result<T, ControlFail>;
|
|
|
|
/// 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<u8>,
|
|
pub sha256: [u8; 32],
|
|
pub collections: BTreeMap<String, Vec<u32>>,
|
|
}
|
|
|
|
pub struct PlayerControl {
|
|
pub identity: PlayerIdentity,
|
|
secrets: Arc<dyn SecretStore>,
|
|
store: Mutex<ControlStore>,
|
|
}
|
|
|
|
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<T>(
|
|
response: Response,
|
|
ok: impl FnOnce(Response) -> std::result::Result<T, Response>,
|
|
) -> R<T> {
|
|
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<dyn SecretStore>) -> Result<Self> {
|
|
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<std::sync::MutexGuard<'_, ControlStore>> {
|
|
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<Option<Credentials>> {
|
|
Ok(self
|
|
.raw_credentials(realm)?
|
|
.filter(|c| !c.username.is_empty()))
|
|
}
|
|
|
|
fn raw_credentials(&self, realm: &RealmId) -> Result<Option<Credentials>> {
|
|
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<Option<(String, AccountKind)>> {
|
|
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<PlayerChannel> {
|
|
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<String>)> {
|
|
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<AccountOutcome> {
|
|
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<String> {
|
|
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<Vec<CharacterEntry>> {
|
|
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<Claimed> {
|
|
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<Option<String>> {
|
|
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<Vec<(Uuid, String)>> {
|
|
Ok(self.store()?.player_claims(&realm.to_string())?)
|
|
}
|
|
|
|
/// Transfer a portable character to a remote realm over the verified control channel (Phase 12.1).
|
|
pub fn transfer_character(
|
|
&self,
|
|
ch: &mut PlayerChannel,
|
|
character_id: Uuid,
|
|
ruleset: &str,
|
|
canonical_revision: u64,
|
|
payload: &[u8],
|
|
content_hash: [u8; 32],
|
|
collections: BTreeMap<String, Vec<u32>>,
|
|
) -> R<RemoteTransferOutcome> {
|
|
let transfer_id = Uuid::now_v7();
|
|
let content_hash_str = hex::encode(content_hash);
|
|
let offer = 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 } => 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<crate::control::relay_link::RelayAllocationInfo> {
|
|
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<u32>,
|
|
pub notes: Vec<String>,
|
|
}
|