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:
Дмитрий committed 2026-10-22 17:24:15 +05:00
1 parent 9d135765cd
commit 5343020bed
27 files changed
+1251 -159

No files matched your search

+5 -4
View File
@@ -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}`.
+24 -10
View File
@@ -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.
+10 -1
View File
@@ -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
+7 -5
View File
@@ -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)
+11 -9
View File
@@ -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`
+9
View File
@@ -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.
![Wildcard overview](screenshots/wildcard-demo/overview.jpg)
![Module compatibility](screenshots/wildcard-demo/modules.jpg)