10 KiB
Multi-Ruleset Realms & Portable Characters: Architectural Audit
This audit evaluates the released CoA Server Manager v0.7.0/v0.7.1 architecture to support three independent, strictly isolated gameplay rulesets:
- Conquest of Azeroth (
coa) - Wildcard (
wildcard) - Warcraft Reborn (
reborn)
Date: October 2026
Status: Pre-Implementation Audit Baseline
1. Executive Summary & Existing Representation
Current codebase inspection reveals that while realms::Mode already defines Coa, Wildcard, and Reborn for local realm profiles and database switching, the Portable Characters and Public Realm Registry subsystems were designed almost entirely around coa, with experimental/preliminary partial awareness of wildcard, and an explicit blocking error for reborn (ruleset_of: "Portable characters are not supported on Warcraft Reborn realms yet").
Furthermore, several critical isolation gaps exist across the stack:
- Registry & Host Identity Conflation: Local realm publication keys by
srv-<installation_id>rather than by(installation_id, ruleset). A host running multiple modes (or switching modes) risks mutating or conflating public realm identity. - Collection Bucket Shared per Profile: Canonical collection storage (
collectiontable) is keyed by(profile_id, kind)with fixed strings likecoa:appearanceandcoa:vanity. Wildcard and Reborn collections cannot safely share these keys or numeric id sets without risking collision and cross-ruleset leakage. - Store Schema Constraints: SQLite
charactertable and PostgreSQL Registryrealmtable enforceCHECK (ruleset IN ('coa', 'wildcard')), which rejectsreborn. - Remote Control & Session Protocols:
TransferOffer,PortableSessionStarted,PortableCheckpoint, andOwnerAckmessages do not bindrulesetin their envelopes, relying solely on character snapshot payload validation or local mapping lookups. - Capability Profiles:
RealmCapabilitiesreports and negotiation hardcode expectations aroundcoa, blocking other rulesets.
2. Inventory of Current Subsystem Locations & Representation
2.1 Realm Profiles & Databases (crates/coa-core/src/realms.rs, db.rs)
| Ruleset / Mode | Realm ID | Character Database | World Database | Auth Database | Configuration Profile |
|---|---|---|---|---|---|
| CoA | 1 |
acore_characters |
acore_world |
acore_auth |
Settings/realm-profiles/coa.json |
| Wildcard | 2 |
acore_characters_wildcard |
acore_world_wildcard |
acore_auth |
Settings/realm-profiles/wildcard.json |
| Warcraft Reborn | 3 |
acore_characters_reborn |
acore_world_reborn |
acore_auth |
Settings/realm-profiles/reborn.json |
- Simultaneous Startup Policy:
- CoA + Wildcard simultaneous is supported via
secondary_world_portandsecondary_ra_port(CoA on primary world port 8085, Wildcard on secondary e.g. 8086). - Warcraft Reborn simultaneous startup is strictly unsupported (
s.simultaneous && s.active == Mode::RebornreturnsError::Invalid("Simultaneous startup supports CoA and Wildcard only.")).
- CoA + Wildcard simultaneous is supported via
- Worldserver Capability Detection:
- Executable inspected directly (
Core/worldserver.exeon Windows repack,Core/worldserveron Linux Docker). - Wildcard detected by byte pattern:
b"Wildcard synergy settings". - Reborn detected by byte pattern:
b"Warcraft Reborn class spells are unavailable".
- Executable inspected directly (
2.2 Ruleset Enumeration & Protocols
crates/coa-core/src/realms.rs:enum Mode { Coa, Wildcard, Reborn }crates/coa-core/src/portable/model.rs:enum Ruleset { Coa, Wildcard }(LacksReborn)crates/coa-registry-proto/src/caps.rs:enum Ruleset { Coa, Wildcard }(LacksReborn)services/coa-registry/src/pg.rs:ruleset: match ruleset.as_str() { "coa" => Ruleset::Coa, "wildcard" => Ruleset::Wildcard }(LacksReborn)src/lib/browse.ts:export type Ruleset = "coa" | "wildcard";(Lacksreborn)
2.3 Public Registry Model & Publication
crates/coa-core/src/realm_registry/settings.rs:RegistrySettings.realmsis aBTreeMap<String, PublishConfig>.src/screens/PublishCard.tsx: UseslocalId = 'srv-' + serverId.- Host vs Published Realm Identity Issue:
One installation (
InstallMeta.id) hosting multiple rulesets currently shareslocalId = srv-<id>. If the host switches active realm from CoA to Wildcard, or publishes both under simultaneous mode,srv-<id>cannot represent both published realms distinctly. Each published realm must possess its own distinct local realm identity (srv-<id>-<ruleset>orsrv-<id>:<ruleset>), uniqueRealmId(UUIDv7), and independent Ed25519 signing key inKeyStore.
2.4 Canonical Portable Storage (crates/coa-core/src/portable/store.rs)
- SQLite schema (
%LOCALAPPDATA%\CoAServerManager\portable\portable.db):character:ruleset TEXT NOT NULL CHECK (ruleset IN ('coa', 'wildcard'))-> Must be updated to allow'reborn'.collection:PRIMARY KEY (profile_id, kind)-> Unpartitioned by ruleset! Must become(profile_id, ruleset, kind).character_server_mapping:PRIMARY KEY (character_id, server_id), UNIQUE (server_id, local_guid).item_mapping:PRIMARY KEY (character_id, server_id, portable_item_id).pet_mapping:PRIMARY KEY (character_id, server_id, portable_pet_id).owner_session:character_id,server_id,c0_revision,b0_hash.host_session:character_id,server_id,local_guid.
2.5 Remote Transfer & Control Protocol (crates/coa-control-proto/src/app.rs)
Request::TransferOffer:{ transfer_id, character_id, canonical_revision, content_hash, total_size, collections }-> Missingruleset. An offer must bindruleset: Rulesetso the host can reject before chunk transport or preflight if target realm mismatch occurs.Request::TransferCommit: Currently relies on cached transfer metadata.Response::TransferCommitted: Returns session parameters.
2.6 Runtime Sessions & Checkpoints (crates/coa-core/src/portable/session/protocol.rs)
PortableSessionStarted:{ protocol_version, session_id, character_id, server_id, base_canonical_revision, baseline_generation, b0, content_hash, progression }-> Missingruleset.PortableCheckpoint:{ protocol_version, session_id, character_id, server_id, base_canonical_revision, sequence, final_checkpoint, realm_snapshot, content_hash, pin }-> Missingruleset.OwnerAck:{ protocol_version, session_id, sequence, outcome, canonical_revision, canonical_hash, owned_items, owned_pets, canonical, next_session, pin }-> Must verify ruleset match in owner session state before applying 3-way merge.
2.7 Direct & Relay Routing
- Direct Ingress Proxy (
crates/coa-core/src/control/direct_ingress.rs): Listens on direct auth and world ports, interceptsCMD_REALM_LISTfrom the Auth server, and rewrites the realm entry address to the public direct world IP and port. When multiple realms are active (simultaneous CoA + Wildcard), each published realm must target its respective local world port (ports.worldvss.secondary_world_port). - Relay Hub & Allocations (
services/coa-relay/,crates/coa-core/src/control/relay_link.rs): Relay allocation requests are authenticated by Ed25519 realm key. Allocations bind a short-lived token to an isolated auth/world stream pair.
3. Strict Isolation Invariants
The fundamental architectural invariant is:
\text{portable\_character.ruleset} == \text{target\_realm.ruleset}
On mismatch:
- Zero DB Mutation: No rows written to
acore_characters*,item_instance, or modules. - Zero Session Creation: No
host_sessionorowner_sessionrecord opened or armed. - Zero Mapping Creation: No entry in
character_server_mapping,item_mapping, or pet mapping. - Zero Collection Merge: No union into collections of a different ruleset.
- Zero Canonical Revision Change: Canonical revision remains unchanged; reject with explicit mismatch error.
- No Implicit Conversion: Never attempt conversion, level projection across rulesets, or guessing missing rulesets.
4. Execution Plan & Phasing
- Authoritative RulesetId Abstraction (Section 3):
- Normalize
RulesetId/ unified enum acrosscoa-core,coa-registry-proto,coa-control-proto, and TypeScript models. - Values:
coa,wildcard,reborn.
- Normalize
- Partitioning Collections & Canonical Storage (Sections 8, 11):
- Add SQLite migration
009_multiruleset_collections.sqlpartitioning collections by(profile_id, ruleset, kind)and expandingcharactertable ruleset constraint to allow'reborn'. - Update
StoreAPIs to acceptruleset: Ruleseton character operations and collection operations.
- Add SQLite migration
- Registry & Multi-Realm Publication on One Host (Sections 5, 6, 26):
- Partition published realm keys:
srv-<serverId>:<ruleset>. - Each published realm receives its own
RealmId, Ed25519 key, heartbeat, status, and capabilities. - Registry PostgreSQL migration for
rebornruleset check.
- Partition published realm keys:
- Remote Transfer Envelope & Session Binding (Sections 14, 22):
- Add
rulesettoTransferOffer,PortableSessionStarted,PortableCheckpoint. - Enforce 4-way equality: envelope ruleset == payload ruleset == published realm ruleset == host target DB ruleset.
- Add
- Wildcard Vertical Slice (Section 15):
- End-to-end testing of Wildcard claiming, transfer, session, checkpoint, and collection partitioning.
- Verify negative cross-ruleset attack scenarios.
- Warcraft Reborn Audit & Vertical Slice (Sections 18, 19):
- Complete
docs/REBORN_PORTABLE_AUDIT.md. - Wire Reborn adapter into the unified engine and verify vertical slice.
- Complete
- UI Multi-Ruleset Filtering (Sections 7, 27):
- Server browser ruleset tabs/filters (
All,Conquest of Azeroth,Wildcard,Warcraft Reborn). - Portable character picker filtered by target realm ruleset.
- Server browser ruleset tabs/filters (
- Regression & Cross-Ruleset Attack Test Suite (Section 29):
- Comprehensive unit and integration attack tests ensuring strict isolation.