Files

wtclaude bf41105ec0 docs(website): record the shard visibility framework

Protocol 3.0 Part A. Admin-configurable, per-feature and per-field
audience control over every shard-derived surface, replacing the static
PUBLIC_KINDS allowlist that used to be the whole boundary.

- SHARD_VISIBILITY.md (new): the admin-facing guide - the ladder, what
  each of the ten features exposes, the defaults, the two rules that are
  code rather than configuration, and worked examples.
- BACKEND_DESIGN.md 6.5 (new): the same thing as a security contract -
  the ladder and how viewerLevel resolves it, the locked acct/webId rule,
  the fail-closed kind map, the asymmetric ladder fallbacks, and the
  three enforcement points. Plus the shard_feature_visibility schema, the
  /public/shard/features route, and the adminOnly tier on
  /admin/shard/visibility.

Defaults reproduce pre-3.0 behavior everywhere, with one deliberate
exception which is the leak Part A was written to close: guilds and
governors previously returned the raw stored payload, whose leader and
governor actors carry acct and webId, to anonymous callers.

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

2026-07-28 10:04:29 -05:00

6.6 KiB

Raw Blame History

Shard visibility — who sees which shard data

Status: Built (Protocol 3.0 Part A). Admin → Shard Visibility. Audience: shard owners and admins. Companion to ../link/v3.md §3 (the design) and BACKEND_DESIGN.md §6 (the security contract).

The website surfaces a lot of live shard data. What your players, your staff and the anonymous internet may each see is yours to decide, per feature, from Admin → Shard Visibility.

Nothing changes until you change it: every setting ships at the value that reproduces how the site behaved before this panel existed.

1. The audience ladder

Five rungs. Each one includes everyone below it.

Rung	In the UI	Who that is
`anonymous`	Everyone	Anyone at all, signed in or not.
`logged_in`	Signed in	Any registered account, whether or not they've linked a game account.
`player`	Linked players	Accounts with a linked in-game account. Staff always qualify, linked or not.
`staff`	Staff	Admins and moderators.
`admin`	Admins only	Admins.

Two notes that surprise people:

editor is a content role, not a shard role. Editors write news and wiki pages; they get no shard privilege from that. An editor is treated by link status like any other member. This matches the rest of the site, where shard staff powers are admin-or-moderator.
Staff satisfy player without linking. Otherwise an admin would be locked out of surfaces they'd gated to players, which is how the /player/* routes already behave.

2. What you can set per feature

Enabled. Off means gone. The feature's pages return “not found”, not “forbidden” — a disabled feature doesn't advertise that it exists.

Who can see it. The minimum rung, from the ladder above.

Live updates. Whether this feature pushes changes to open pages in real time. Turning it off doesn't break the page; it just refreshes on load instead of updating in place.

Sensitive fields. Some features expose a field that deserves its own rung — you can publish the board while holding back one column. See the table in §3.

3. The features, and their defaults

Feature	What it exposes	Default	Sensitive fields
Shard status	Connection state, online count, gold-supply series	Everyone	—
Activity feed	Deaths, kills, skill gains, quests, logins	Everyone	—
Champion spawns	The live champion / mini-champ / sea-boss board	Everyone	—
Guilds	Guild rosters, alliances, leaders	Everyone	—
Town governors	City Loyalty governors, elections, term history	Everyone	—
Houses / IDOC	Houses in danger	Everyone	House owner → Staff · House price → Staff
Players online	Population aggregate, staff-online widget	Everyone	In-game location → Staff
Shard rules	Skill/stat caps, house limits, vet rewards, the ruleset	Everyone	Connect address → Everyone
Spawn atlas	Bestiary and spawn locations (static content)	Everyone	—
Leaderboards	Point and loyalty standings	Everyone	Character names → Everyone
Marketplace	The shard-wide player-vendor index	Everyone, live updates off	Vendor owner name → Everyone · Location → Everyone

Why the marketplace ships with live updates off. A live feed of every vendor's full inventory would be the single largest thing the site sends. No page needs it — the marketplace is a search over stored data with a “prices last refreshed N minutes ago” stamp. Turn it on only if you want it.

Why house owner/price default to Staff. The public Houses page has always been a "where are the falling houses" board — location only. Owner and price are the staff view. That split is preserved.

4. What you cannot change

Two rules are enforced in code and are not settings. Attempting to set them returns an error rather than silently ignoring you.

1. Game account names and website user ids are admin-only, always. acct and webId never appear below the admin rung on any surface. A character name is visible in game to anyone standing next to them; the account behind it is not, and neither is the website user it's linked to. Publishing those would disclose something the shard itself doesn't, and would tie a player's in-game identity to their forum identity without their consent.

2. Unknown event kinds are never broadcast below admin. The live stream maps each event kind to a feature. A kind with no mapping — a new event from a shard plugin the site doesn't know yet, say — goes to admins only. It fails closed. This is what keeps the stream safe by default when the shard starts sending something new: the worst case is that staff see it and players don't, never the reverse.

5. How it's enforced

Three places, one config:

Page and API requests are checked before the handler runs, and the response is then stripped of any field above the caller's rung.
The live stream resolves a viewer's rung once, when they connect, and freezes it for that connection — a long-open page can't gain privilege because something changed underneath it. Each event is then gated and stripped per viewer, so two people watching the same page can legitimately receive different versions of the same event, or one of them nothing.
Navigation hides links a viewer can't follow, so they don't hit a wall. This is presentation only — the gate is server-side either way.

Changes take effect within about five seconds, including on streams that are already open. You don't need to restart anything.

If the database is briefly unreachable, the site falls back to the built-in defaults — the pre-v3 behavior — rather than to "everything is public".

6. Worked examples

"I want a private shard — nothing public until people register." Set every feature to Signed in. Anonymous visitors still get the site itself; the shard data disappears from the nav.

"Publish the market, but don't tie vendors to players." Marketplace → Everyone, with Vendor owner name → Staff. Prices, items and locations stay public; who owns each vendor doesn't.

"Leaderboards for members only." Leaderboards → Linked players. Anyone who's linked a game account sees the standings; drive-by visitors don't.

"Let players see house owners." Houses → Everyone, House owner → Linked players. Note this is a real disclosure: house ownership is visible in game, but the website makes it searchable in a way the game doesn't.

6.6 KiB Raw Blame History