docs(link): add the Protocol 3.0 design #63

wtclaude · 2026-07-28T14:29:52Z

wtclaude commented

2026-07-28 14:29:52 +00:00

What & why

A survey of the live ServUO tree against everything the bridge already surfaces found that the bridge covers live activity well and covers shard content and standings almost not at all — every leaderboard, every ruleset fact, every "where do I find X", and the entire player economy outside a player's own vendors are absent.

This adds link/v3.md, the canonical Protocol 3.0 design. It records the full 17-item gap list (so the items not scoped now aren't re-derived later) and specs the four features that are.

Three scope areas:

A — the visibility framework. Admin-configurable, per-feature and per-field audience control over all ten shard-derived surfaces (the four new ones plus the six that already ship), on an anonymous → logged_in → player → staff → admin ladder. Every default reproduces today's behavior, so the retrofit is a no-op until an admin changes something. Two rules an admin cannot override: acct/webId are admin-only always, and an unmapped event kind is never broadcast below admin (fail closed).
B — three new wire streams: world.ruleset, points.board, vendor.listing/vendor.listing.remove.
C — the spawn atlas, built from static ServUO data files with no wire involvement at all.

Two things worth reviewer attention:

A verified leak this fixes. BridgeJson.Actor() writes acct and webId; shardState.model.js:346 shapeGuild() returns the payload verbatim; GET /api/v1/public/shard/guilds is anonymous. A guild leader's game account name and website user id are readable by anyone today. Same path for /public/shard/governors, and Actor also feeds three kinds on the anonymous SSE stream. Part A ships first and alone because of this.
shardBroadcast.js becomes the highest-risk file in 3.0. It moves from a static PUBLIC_KINDS allowlist to per-connection audience filtering — the security boundary moves with it.

Visibility lives entirely on the website. The sidecar stays a dumb forwarder: it accepts frames, persists them, forwards them verbatim, and serves store-backed reads. It defines no access parameters and advertises no capabilities.

Rollout. PROTOCOL_VERSION goes 2 → 3 exactly once, at the end. Each repo gets an edge branch cut from main; every part PRs into edge; the coordinated edge → main merge is the cutover. A schema migration moves uo_link_config.protocol (row and column default) so the bump doesn't strand the integration on a manual admin edit.

Also resolves an open question from PROTOCOL_2.md §10.4, which deferred VvV pending "which PvP system does this shard run?" — VvV.cfg Enabled=True and Factions.cfg is off. Recorded as unblocked, not scoped for 3.0.

Docs-only; no code changes. Targets edge, not main.

How it was tested

N/A — documentation. Every file path, line reference, config value and API signature cited in the design was read directly from the live ServUO tree and from the four repos; the leak in §3.1 was traced end to end (BridgeJson.cs:85-117 → shardState.model.js:346 → shard.controller.js:131) rather than inferred.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why A survey of the live ServUO tree against everything the bridge already surfaces found that **the bridge covers live *activity* well and covers shard *content and standings* almost not at all** — every leaderboard, every ruleset fact, every "where do I find X", and the entire player economy outside a player's own vendors are absent. This adds `link/v3.md`, the canonical Protocol 3.0 design. It records the full 17-item gap list (so the items *not* scoped now aren't re-derived later) and specs the four features that are. **Three scope areas:** - **A — the visibility framework.** Admin-configurable, per-feature and per-field audience control over all ten shard-derived surfaces (the four new ones plus the six that already ship), on an `anonymous → logged_in → player → staff → admin` ladder. Every default reproduces today's behavior, so the retrofit is a no-op until an admin changes something. Two rules an admin cannot override: `acct`/`webId` are admin-only always, and an unmapped event kind is never broadcast below `admin` (fail closed). - **B — three new wire streams:** `world.ruleset`, `points.board`, `vendor.listing`/`vendor.listing.remove`. - **C — the spawn atlas**, built from static ServUO data files with no wire involvement at all. **Two things worth reviewer attention:** 1. **A verified leak this fixes.** `BridgeJson.Actor()` writes `acct` and `webId`; `shardState.model.js:346 shapeGuild()` returns the payload verbatim; `GET /api/v1/public/shard/guilds` is anonymous. A guild leader's game account name and website user id are readable by anyone today. Same path for `/public/shard/governors`, and `Actor` also feeds three kinds on the anonymous SSE stream. Part A ships first and alone because of this. 2. **`shardBroadcast.js` becomes the highest-risk file in 3.0.** It moves from a static `PUBLIC_KINDS` allowlist to per-connection audience filtering — the security boundary moves with it. Visibility lives entirely on the website. The sidecar stays a dumb forwarder: it accepts frames, persists them, forwards them verbatim, and serves store-backed reads. It defines no access parameters and advertises no capabilities. **Rollout.** `PROTOCOL_VERSION` goes 2 → 3 exactly once, at the end. Each repo gets an `edge` branch cut from `main`; every part PRs into `edge`; the coordinated `edge` → `main` merge is the cutover. A schema migration moves `uo_link_config.protocol` (row and column default) so the bump doesn't strand the integration on a manual admin edit. Also resolves an open question from `PROTOCOL_2.md` §10.4, which deferred VvV pending "which PvP system does this shard run?" — `VvV.cfg Enabled=True` and `Factions.cfg` is off. Recorded as unblocked, not scoped for 3.0. Docs-only; no code changes. Targets `edge`, not `main`. ## How it was tested N/A — documentation. Every file path, line reference, config value and API signature cited in the design was read directly from the live ServUO tree and from the four repos; the leak in §3.1 was traced end to end (`BridgeJson.cs:85-117` → `shardState.model.js:346` → `shard.controller.js:131`) rather than inferred. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally.  - [x] I have added or updated tests/docs where it makes sense.  - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-07-28 14:29:53 +00:00

docs(link): add the Protocol 3.0 design 6622afe4bd

Surveys the live ServUO tree against everything the bridge already
surfaces and records the full gap list (17 items), then specs the four
features scoped for 3.0.

3.0 has three scope areas:

- A: the visibility framework. Admin-configurable, per-feature and
  per-field audience control over all ten shard-derived surfaces (the
  four new ones plus the six that already ship), on an
  anonymous -> logged_in -> player -> staff -> admin ladder. Every
  default reproduces today's behavior, so the retrofit is a no-op until
  an admin changes something. Two rules an admin cannot override: acct
  and webId are admin-only always, and an unmapped event kind is never
  broadcast below admin. This also fixes a verified leak - guild leader
  acct/webId are readable today on the anonymous /public/shard/guilds.
- B: three new wire streams - world.ruleset, points.board, and
  vendor.listing/vendor.listing.remove.
- C: the spawn atlas, built from static ServUO data files with no wire
  involvement.

Visibility lives entirely on the website; the sidecar stays a dumb
forwarder that defines no access parameters and advertises no
capabilities.

PROTOCOL_VERSION goes 2 -> 3 once, at the end: every part PRs into an
edge branch per repo, and the coordinated edge -> main merge is the
cutover. A schema migration moves uo_link_config.protocol so operators
don't have to.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-07-28 14:41:21 +00:00

whitlocktech merged commit 7e8cbe1916 into edge

2026-07-28 14:41:28 +00:00

whitlocktech referenced this issue from a commit

2026-07-28 14:41:29 +00:00

Merge pull request 'docs(link): add the Protocol 3.0 design' (#63) from docs/link-v3-plan into edge

whitlocktech deleted branch docs/link-v3-plan

2026-07-28 14:41:29 +00:00

wtclaude referenced this pull request

2026-07-28 15:06:05 +00:00

docs(website): record the shard visibility framework #64

Sign in to join this conversation.