mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-19 19:25:56 +00:00
feat(portable): MR2 Wildcard portable character vertical slice
- 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.
This commit is contained in:
1 parent
9d135765cd
commit
5343020bed
27 files changed
+1251
-159
No files matched your search
@@ -6,7 +6,7 @@ type into the game.
|
||||
|
||||
Code: `crates/coa-control-proto` (the protocol: pure, no I/O), `services/coa-coordinator` (the Coordinator), `crates/coa-core/src/control` (Host and Player sides),
|
||||
`src-tauri/src/control_cmds.rs` and `src/screens/JoinPanel.tsx` (the interface). End-to-end tests: `services/coa-control-e2e`. Deployment: [REGISTRY_DEPLOYMENT.md](REGISTRY_DEPLOYMENT.md).
|
||||
`CONTROL_PROTOCOL_VERSION = 1`; it is independent of the Registry protocol (2) and of the portable formats.
|
||||
`CONTROL_PROTOCOL_VERSION = 2` (bumped in MR1.1/MR2 to require explicit `ruleset` fields in transfer and claim negotiations); it is independent of the Registry protocol (2) and of the portable formats.
|
||||
|
||||
## 1. Shape
|
||||
|
||||
@@ -148,8 +148,8 @@ its profile, and only then sends `claim_ack`; the Host marks the binding `Portab
|
||||
When a player selects a portable character that exists in their Player Manager but does not yet exist on the remote realm, the Player Manager performs an automated, transactional transfer over the encrypted Noise channel:
|
||||
|
||||
1. **Preflight Compatibility Check**: The Player Manager checks the canonical character against the target realm's advertised capabilities (Phase 7/8). If incompatible, the transfer is refused immediately before any network mutation.
|
||||
2. **Transfer Offer (`TransferOffer`)**: Inside the end-to-end encrypted Noise channel, the Player Manager sends `transfer_offer{transfer_id, character_id, canonical_revision, content_hash, total_size, collections}`.
|
||||
- The Host validates the PlayerIdentity, character ownership, format revision, hash format, size limit (≤ 4 MiB, `MAX_TRANSFER_REQUEST_BYTES`), and collection counts (≤ 100,000 items).
|
||||
2. **Transfer Offer (`TransferOffer`)**: Inside the end-to-end encrypted Noise channel, the Player Manager sends `transfer_offer{transfer_id, character_id, canonical_revision, content_hash, total_size, collections, ruleset}`.
|
||||
- The Host validates the PlayerIdentity, character ownership, format revision, hash format, size limit (≤ 4 MiB, `MAX_TRANSFER_REQUEST_BYTES`), collection counts (≤ 100,000 items), and ruleset matching target realm.
|
||||
- If the exact revision was already committed or an active transfer session exists, the Host responds with `transfer_ready{transfer_id, accepted_offset}`.
|
||||
3. **Payload Transfer & Chunking (`TransferChunk` / `TransferStatus`)**:
|
||||
- The Player sends the payload in bounded chunks via `transfer_chunk{transfer_id, offset, data}`.
|
||||
@@ -157,7 +157,8 @@ When a player selects a portable character that exists in their Player Manager b
|
||||
- If a connection is interrupted, the Player can query progress via `transfer_status{transfer_id}` and resume from `accepted_offset`.
|
||||
4. **Validation & Atomic Commit (`TransferCommit`)**:
|
||||
- Once all chunks arrive, the Player sends `transfer_commit{transfer_id}`.
|
||||
- The Host verifies the SHA-256 content hash of the assembled payload against the offer.
|
||||
- The Host verifies the SHA-256 content hash of the canonical JSON against the offer.
|
||||
- The Host decodes the payload and verifies that `decoded.character_id == transfer.character_id`, `decoded.ruleset == transfer.ruleset`, and `transfer.ruleset == destination_realm.ruleset`.
|
||||
- The Host runs the level projection engine (e.g. projecting level 80 down to realm cap 60 via Phase-8 oracle).
|
||||
- The Host imports the character into the realm's characters database, updates/creates the working copy mapping, and arms the session.
|
||||
- The Host returns `transferred{character_id, local_guid, session_id}`.
|
||||
|
||||
@@ -6,7 +6,7 @@ This audit evaluates the architecture to support three independent, strictly iso
|
||||
3. **Warcraft Reborn (`reborn`)**
|
||||
|
||||
Date: October 2026
|
||||
Status: Updated for MR1.1 Gate (Post-Foundation Fixes)
|
||||
Status: Updated for MR2 Gate (Wildcard Vertical Slice Completed)
|
||||
|
||||
---
|
||||
|
||||
@@ -21,19 +21,33 @@ Status: Updated for MR1.1 Gate (Post-Foundation Fixes)
|
||||
- Collection validation used unsafe prefix checks (`kind.starts_with(ruleset)`), permitting prefix confusion attacks.
|
||||
- `Ruleset::schema(kind)` contained a fallback `_ => "acore_characters"`, routing unknown database kinds to CoA.
|
||||
|
||||
### 1.2 Implemented in 58a99f0+ and MR1.1
|
||||
### 1.2 Implemented in MR1, MR1.1, and MR2
|
||||
- **Authoritative Ruleset Enum:** `Ruleset` (`Coa`, `Wildcard`, `Reborn`) unified across `coa-core`, `coa-registry-proto`, `coa-control-proto`, and frontend models.
|
||||
- **Transactional SQLite Migration 009:** Migrates released v0.7.x databases by recreating both `collection` (composite key `profile_id, ruleset, kind`) and `character` (CHECK constraint allowing `'coa', 'wildcard', 'reborn'`) with FK toggles ensuring zero child row loss.
|
||||
- **Protocol Versioning & Negotiation:**
|
||||
- Control protocol bumped to `CONTROL_PROTOCOL_VERSION = 2`. `Request::TransferOffer` requires `ruleset: String` (no default).
|
||||
- Session protocol bumped to `SESSION_PROTOCOL_VERSION = 3`. `SessionOffer`, `PortableSessionStarted`, `PortableCheckpoint`, and `OwnerAck` require explicit `ruleset` (no serde defaults). Old v2 messages require explicit legacy translation.
|
||||
- Collection protocol set to `COLLECTION_PROTOCOL_VERSION = 2`. `CollectionObserved`, `CollectionState`, and `CollectionAck` require explicit `ruleset`.
|
||||
- **Schema Safety:** Unsafe fallback in `Ruleset::schema(kind)` removed; unknown database kinds return a hard error.
|
||||
- **Exact Collection Namespace Validation:** `carried_kind_for(kind, ruleset)` strictly validates allowed collection kinds; prefix confusion attacks (`coax:appearance`, etc.) are rejected with zero mutation.
|
||||
- **Multi-Realm Local Key Resolution:** `find_access` resolves composite keys `srv-<install_id>:<ruleset>` while retaining `srv-<install_id>` for existing single-realm publication until MR4.
|
||||
- **Fail-Closed Realm Backend:** Removed unsafe `unwrap_or(Ruleset::Coa)` in `LocalBackend::info()`. Unreadable, unknown, or broken realms fail closed immediately with error rather than falling back to CoA.
|
||||
- **Control Protocol 2 & Strict Envelopes:**
|
||||
- `CONTROL_PROTOCOL_VERSION = 2`.
|
||||
- `Request::TransferOffer` requires explicit `ruleset: String`.
|
||||
- `Response::Claimed` returns explicit `ruleset: String`.
|
||||
- Claiming and commit verify that the claimed envelope ruleset matches the decoded payload ruleset and matches target realm ruleset.
|
||||
- `HostTransfer` stores `ruleset` in SQLite; `transfer_commit` verifies that canonical JSON hash and ruleset match the offer and destination realm before writing to disk.
|
||||
- **Session Protocol 3 & Ruleset Enforcement:**
|
||||
- `SESSION_PROTOCOL_VERSION = 3` and `COLLECTION_PROTOCOL_VERSION = 2`.
|
||||
- `SessionOffer`, `PortableSessionStarted`, `PortableCheckpoint`, and `OwnerAck` require explicit `ruleset`.
|
||||
- Any mismatch between character ruleset, offer ruleset, session ruleset, or checkpoint ruleset rejects immediately with zero DB mutation and zero canonical revision advance.
|
||||
- **Wildcard Collections Isolation:**
|
||||
- `wildcard:appearance` and `wildcard:vanity` isolated from `coa:appearance` and `coa:vanity`.
|
||||
- Cross-ruleset collection merges strictly rejected by `carried_kind_for(kind, ruleset)`.
|
||||
- **Database Routing & Three-Space Isolation:**
|
||||
- Canonical SQL routes through `Db::query()` and `realm_schema` to `acore_characters_wildcard` and `acore_world_wildcard`.
|
||||
- Multiple characters sharing local GUIDs on distinct server IDs (`srv-1:coa`, `srv-1:wildcard`, `srv-1:reborn`) coexist with zero collision in character mappings and item mappings.
|
||||
- Mutating Wildcard character state, revisions, or collections leaves CoA and Reborn states 100% byte-for-byte untouched.
|
||||
- **Direct & Relay Routing for Wildcard:**
|
||||
- `world_port_for_mode` dynamically determines active world port (8085 for primary CoA, 8086 for secondary Wildcard in simultaneous mode).
|
||||
- Direct Ingress proxy and Relay link dynamically route to the correct realm world port.
|
||||
- Direct Ingress Auth rewrite replaces internal realm list address with external mapped Wildcard port (e.g. 48086) and never advertises CoA port 8085.
|
||||
|
||||
### 1.3 Still Planned (Subsequent Milestones)
|
||||
- **MR2 (Wildcard Vertical Slice):** Full end-to-end import/export, session runtime, and live verification of Wildcard gameplay.
|
||||
- **MR3 (Warcraft Reborn Vertical Slice):** Unlocking `ruleset_of` for Reborn, import/export adapters, and live verification.
|
||||
- **MR4 (Multi-Realm Publication UI & Registry):** Simultaneous publication of multiple RealmIds from a single Manager host under distinct identities and keypairs.
|
||||
|
||||
|
||||
@@ -2,7 +2,16 @@
|
||||
|
||||
**Portable characters are experimental.** The feature is in active development and may contain bugs.
|
||||
|
||||
Portable characters let you keep a saved character in the Manager and play it on compatible CoA realms.
|
||||
Portable characters let you keep a saved character in the Manager and play it on compatible realms (Conquest of Azeroth and Wildcard).
|
||||
|
||||
## Multi-Ruleset Isolation Invariant
|
||||
|
||||
Portable characters are strictly isolated by gameplay ruleset (`coa`, `wildcard`, `reborn`):
|
||||
- A character created or claimed on a **Conquest of Azeroth** realm is a CoA character and can only ever be played on CoA realms.
|
||||
- A character created or claimed on a **Wildcard** realm is a Wildcard character and can only ever be played on Wildcard realms.
|
||||
- A character created or claimed on a **Warcraft Reborn** realm can only ever be played on Reborn realms.
|
||||
|
||||
Cross-ruleset transfers, imports, joins, sessions, and collection merges are impossible: the Manager strictly rejects any mismatched request at every protocol, session, and database boundary with zero mutation to your characters or servers.
|
||||
|
||||
## Make your first character portable
|
||||
|
||||
|
||||
@@ -77,7 +77,8 @@ one place, no duplicate ids). Extension payloads must match their recorded hash.
|
||||
* `rollback_to` creates a **new** revision whose state equals an old one; revision numbers never decrease.
|
||||
* The newest `history_keep` revisions are kept (default 20, 1..=1000, configurable). The current revision is never
|
||||
pruned.
|
||||
* A character's `ruleset` (`coa` | `wildcard`) can never change.
|
||||
* A character's `ruleset` (`coa` | `wildcard` | `reborn`) can never change.
|
||||
* The character's `content_namespace` aligns strictly with `ruleset` (`coa`, `wildcard`, or `reborn`).
|
||||
|
||||
## Extensions
|
||||
|
||||
@@ -87,8 +88,9 @@ that does not support an extension simply does not receive it; the canonical cop
|
||||
|
||||
## Collections
|
||||
|
||||
Account-wide sets of numeric ids (`coa:wardrobe`, `coa:vanity`, ...), stored per profile and kind:
|
||||
Account-wide sets of numeric ids (`coa:appearance`, `wildcard:appearance`, `reborn:appearance`, etc.), stored per `(profile_id, ruleset, kind)`:
|
||||
|
||||
* partitioned strictly by ruleset: collections of different rulesets never intersect or merge;
|
||||
* union only: `stored = stored U incoming`; nothing is ever removed because a realm did not return it;
|
||||
* if the union equals what is stored, **no revision is created** and the hash is unchanged;
|
||||
* encoding: `[format version][count][first id][gap]...`, unsigned LEB128 varints, strictly ascending ids, 1-2 bytes per
|
||||
@@ -98,17 +100,17 @@ Account-wide sets of numeric ids (`coa:wardrobe`, `coa:vanity`, ...), stored per
|
||||
## Store (`%LOCALAPPDATA%\CoAServerManager\portable\portable.db`)
|
||||
|
||||
SQLite, WAL, `synchronous=FULL`, `foreign_keys=ON`, `application_id = 0x434F4150`, forward-only migrations tracked in
|
||||
`PRAGMA user_version` (currently 3). A database from a newer Manager, or a foreign SQLite file, is refused and left untouched.
|
||||
`PRAGMA user_version` (migration 009 adds multi-ruleset collection partitioning and reborn character support). A database from a newer Manager, or a foreign SQLite file, is refused and left untouched.
|
||||
|
||||
| Table | Purpose |
|
||||
|---|---|
|
||||
| `profile` | the owner |
|
||||
| `character` | summary row + canonical revision |
|
||||
| `character` | summary row + canonical revision (`ruleset IN ('coa', 'wildcard', 'reborn')`) |
|
||||
| `snapshot` | `(character_id, revision)` -> compressed canonical payload + hash |
|
||||
| `character_server_mapping` | `(character_id, server_id)` -> local guid; `UNIQUE(server_id, local_guid)` |
|
||||
| `item_mapping` | one row per mapping with a lifecycle (schema 2, see below) |
|
||||
| `import_journal` | schema 3: one row per import into a realm (`prepared` / `committed` / `aborted` / `needs_attention`) with the nonce/marker and the plan; see `PORTABLE_IMPORT.md` |
|
||||
| `collection` | per profile and kind: revision, hash, encoded set |
|
||||
| `collection` | per profile, ruleset, and kind: revision, hash, encoded set |
|
||||
| `setting` | `history_keep` |
|
||||
|
||||
## Item mapping lifecycle (schema 2)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Runtime portable sessions (Phase 5): design and audit
|
||||
|
||||
Code: core `src/server/coa/CoAPortableSession*.{h,cpp}` and `CoAPortableImport*.{h,cpp}` (branch `feat/portable-session-bridge` of the
|
||||
core fork), Manager `crates/coa-core/src/portable/session/`. CoA only; Wildcard portable transfer stays disabled.
|
||||
core fork), Manager `crates/coa-core/src/portable/session/`. Supports Conquest of Azeroth and Wildcard (MR2) with strict multi-ruleset isolation.
|
||||
|
||||
Phase 4 proved the offline model with a real client. Its one fragile rule is that the baseline `B0` must be captured *after*
|
||||
the realm's own normalisation and *before* the character is played. Phase 5 makes that rule a property of the running
|
||||
@@ -130,16 +130,18 @@ Messages wait in the outbox until acknowledged; redelivery is harmless (section
|
||||
|
||||
## 5. Messages (transport-neutral, versioned, JSON)
|
||||
|
||||
`protocol_version = 1`; each message is canonical JSON with unknown fields refused. Snapshots travel in the existing
|
||||
snapshot envelope (zstd of canonical JSON, SHA-256 of the canonical JSON).
|
||||
`protocol_version = 3` (Session Protocol Version 3; Collection Protocol Version 2); each message is canonical JSON with unknown fields refused. Snapshots travel in the existing
|
||||
snapshot envelope (zstd of canonical JSON, SHA-256 of the canonical JSON). Every session message carries an explicit `ruleset` (`coa`, `wildcard`, or `reborn`):
|
||||
|
||||
```text
|
||||
PortableSessionStarted { protocol_version, session_id, character_id, server_id, base_canonical_revision,
|
||||
baseline_generation, b0: envelope, content_hash }
|
||||
PortableCheckpoint { protocol_version, session_id, character_id, server_id, base_canonical_revision,
|
||||
sequence, final_checkpoint, realm_snapshot: envelope, content_hash }
|
||||
OwnerAck { protocol_version, session_id, sequence, outcome, canonical_revision, canonical_hash,
|
||||
[final: canonical snapshot envelope] }
|
||||
SessionOffer { protocol_version, ruleset, session_id, character_id, server_id,
|
||||
canonical_revision, snapshot: envelope }
|
||||
PortableSessionStarted { protocol_version, ruleset, session_id, character_id, server_id, base_canonical_revision,
|
||||
baseline_generation, b0: envelope, content_hash, progression }
|
||||
PortableCheckpoint { protocol_version, ruleset, session_id, character_id, server_id, base_canonical_revision,
|
||||
sequence, final_checkpoint, realm_snapshot: envelope, content_hash, pin }
|
||||
OwnerAck { protocol_version, ruleset, session_id, sequence, outcome, canonical_revision, canonical_hash,
|
||||
owned_items, owned_pets, [final: canonical snapshot envelope], next_session, pin }
|
||||
```
|
||||
|
||||
`outcome` is `applied`, `duplicate` (same sequence and hash, already applied), `stale_sequence`, `stale_session`
|
||||
|
||||
@@ -19,6 +19,15 @@ Recovery points identify their active realm; select that realm before restoring
|
||||
both realms, with auth applied once. The server updater can replace its launcher: the Manager reapplies the realm
|
||||
adapter before the next start.
|
||||
|
||||
## Portable Characters on Wildcard
|
||||
|
||||
As of v0.7.1 (MR2), Wildcard realms fully participate in the Portable Characters subsystem with strict multi-ruleset isolation:
|
||||
- **Canonical Model:** Wildcard portable characters carry `ruleset: "wildcard"` and `content_namespace: "wildcard"`.
|
||||
- **Claim & Export:** Real characters played on a Wildcard realm (`acore_characters_wildcard`) can be claimed and exported into canonical portable snapshots. Wildcard character builds—including spells, talents, skills, action bars, settings, inventory, pets, and currencies—are fully captured.
|
||||
- **Import & Session Runtime:** A Wildcard portable character can be transferred to a remote Wildcard host, imported into its `acore_characters_wildcard` database, armed in a runtime session (Session Protocol 3), and played live with automatic checkpoints and logout synchronization.
|
||||
- **Collections:** Wildcard collections (`wildcard:appearance` and `wildcard:vanity`) are partitioned separately from CoA collections. Unlocks on a Wildcard realm union into the profile's Wildcard collections and never touch CoA collections.
|
||||
- **Fail-Closed Protection:** Any attempt to transfer or import a CoA character into a Wildcard realm, or vice versa, is rejected at the protocol and database boundaries with zero mutation.
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
Reference in new issue
Block a user