RunicGateway/website
3
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Activity

feat(shard): admin-configurable visibility for every shard surface

Browse Source 
Protocol 3.0 Part A. Replaces the static PUBLIC_KINDS allowlist - which
was the entire public/admin boundary - with per-feature, per-field
audience control an admin owns from Admin -> Shard Visibility.

Closes a live leak. BridgeJson.Actor() writes acct and webId;
shapeGuild() returned the stored payload verbatim; GET
/api/v1/public/shard/guilds is anonymous. Guild leaders' game account
names and website user ids were readable by anyone, and the same path
existed for governors. Both are now projected.

The ladder is anonymous < logged_in < player < staff < admin, each rung
implying the ones below. Staff satisfy `player` without a linked account
(as /player/* already does); `editor` is a content role and gets no
shard privilege, since mapping it to staff would silently widen what
editors see.

Two invariants are code, not configuration, and both reject rather than
silently ignore:

  1. acct/webId are admin-only always - not configurable, discarded on
     read as well as rejected on write.
  2. A kind absent from KIND_FEATURE never reaches anyone below admin.
     Fail closed, so a shard emitting a new event degrades to staff-only
     rather than to public.

Enforcement is three points over one config: requireFeature() on routes
(404 disabled, 403 out-of-rung) plus field projection; per-connection
filtering on SSE, where a subscriber's rung is resolved once at subscribe
time and frozen so a long-open stream cannot gain privilege; and
/public/shard/features so the SPA hides links it cannot follow.

PUBLIC_KINDS still exists and is still exported (/feed filtering,
notificationStreams) but is now derived from the kind map, so the two
can no longer drift. Defaults reproduce pre-3.0 behavior exactly - a
test pins the derived set against the old allowlist.

Also fixes an SSE resource leak found while testing: a client dropped
because its write threw was removed from the bucket but its keepalive
interval was never cleared, firing forever on a dead socket. Both paths
now go through one drop().

Tests: 478 server (33 new across shardVisibility + shardBroadcast),
43 client. Route manifest and OpenAPI spec regenerated.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
claude
2026-07-28 10:04:48 -05:00
parent a3407ae654
commit f3450686e0
22 changed files with 2369 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

535
server/swagger/swagger-output.json
View File

@@ -4368,6 +4368,98 @@
]
}
},
"/api/v1/admin/shard/visibility": {
"get": {
"tags": [
"Admin · Shard"
],
"summary": "Get per-feature shard visibility config (admin only)",
"description": "The effective config (compiled defaults merged with stored overrides) plus the vocabulary the admin UI renders from: the audience ladder and the always-locked fields. Defaults reproduce pre-v3 behavior.",
"responses": {
"200": {
"description": "Visibility config",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShardVisibilityConfig"
}
}
}
},
"403": {
"description": "Admin role required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal Server Error"
}
},
"security": [
{
"cookieAuth": []
},
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Admin · Shard"
],
"summary": "Update per-feature shard visibility config (admin only)",
"description": "Patch one or more features. Unknown feature names, unknown rungs, and any attempt to configure a locked field (acct / webId — admin-only always) are rejected with 400 rather than silently dropped.",
"responses": {
"200": {
"description": "Updated config",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShardVisibilityConfig"
}
}
}
},
"400": {
"description": "Unknown feature, rung, or a locked field",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal Server Error"
}
},
"security": [
{
"cookieAuth": []
},
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShardVisibilityUpdate"
}
}
}
}
}
},
"/api/v1/admin/site-mode": {
"put": {
"tags": [
@@ -10849,6 +10941,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -10890,6 +10988,36 @@
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/api/v1/public/shard/features": {
"get": {
"tags": [
"Public · Shard"
],
"summary": "Shard features visible to the caller (drives client nav)",
"description": "The caller\\'s audience rung plus the shard features they may reach, so a client can hide nav entries instead of rendering links that 403. Reports only what the caller can see — the list itself does not disclose gated features.",
"responses": {
"200": {
"description": "Visible features",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShardFeatures"
}
}
}
},
"500": {
"description": "Internal Server Error"
}
@@ -10940,6 +11068,12 @@
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -10968,6 +11102,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11019,6 +11159,12 @@
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11047,6 +11193,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11074,6 +11226,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11101,6 +11259,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11128,6 +11292,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11153,6 +11323,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11177,6 +11353,12 @@
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
@@ -11188,8 +11370,8 @@
"tags": [
"Public · Shard"
],
"summary": "Live shard event stream (Server-Sent Events, public/safe kinds)",
"description": "text/event-stream of curated live events. Sensitive kinds (staff audit, cheat detection, login attempts, IPs) are NOT sent on this channel.",
"summary": "Live shard event stream (Server-Sent Events, filtered by audience)",
"description": "text/event-stream of live events. The caller\\'s audience rung is resolved once at subscribe time and frozen for the connection; each frame is then gated on its feature and field-projected, so sensitive kinds and fields (staff audit, cheat detection, login attempts, IPs, acct/webId) never reach a caller below their configured rung.",
"responses": {
"200": {
"description": "An SSE stream (Content-Type: text/event-stream)."
@@ -17416,6 +17598,355 @@
}
}
},
"ShardFeatures": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"description": {
"type": "string",
"example": "The shard features the caller may reach, plus the audience rung they resolved to. Drives client nav so it never renders a link that would 403."
},
"properties": {
"type": "object",
"properties": {
"level": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "string"
},
"enum": {
"type": "array",
"example": [
"anonymous",
"logged_in",
"player",
"staff",
"admin"
],
"items": {
"type": "string"
}
},
"example": {
"type": "string",
"example": "anonymous"
}
}
},
"features": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "array"
},
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "string"
}
}
},
"example": {
"type": "array",
"example": [
"status",
"activity",
"champs",
"guilds",
"governors",
"houses",
"presence"
],
"items": {
"type": "string"
}
}
}
}
}
}
}
},
"ShardFeatureVisibility": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"description": {
"type": "string",
"example": "Visibility settings for one shard feature."
},
"properties": {
"type": "object",
"properties": {
"enabled": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "boolean"
},
"example": {
"type": "boolean",
"example": true
}
}
},
"audience": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "string"
},
"enum": {
"type": "array",
"example": [
"anonymous",
"logged_in",
"player",
"staff",
"admin"
],
"items": {
"type": "string"
}
},
"description": {
"type": "string",
"example": "Minimum rung that may reach this feature. Each rung implies the ones below it."
},
"example": {
"type": "string",
"example": "anonymous"
}
}
},
"stream": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "boolean"
},
"description": {
"type": "string",
"example": "Whether this feature's event kinds fan out over SSE at all."
},
"example": {
"type": "boolean",
"example": true
}
}
},
"fieldRules": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"additionalProperties": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "string"
}
}
},
"description": {
"type": "string",
"example": "Per-field rung overrides for the sensitive fields this feature exposes. acct / webId are admin-only always and are rejected here."
},
"example": {
"type": "object",
"properties": {
"location": {
"type": "string",
"example": "staff"
}
}
}
}
}
}
}
}
},
"ShardVisibilityConfig": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"properties": {
"type": "object",
"properties": {
"ladder": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "array"
},
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "string"
}
}
},
"example": {
"type": "array",
"example": [
"anonymous",
"logged_in",
"player",
"staff",
"admin"
],
"items": {
"type": "string"
}
}
}
},
"lockedFields": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "array"
},
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "string"
}
}
},
"example": {
"type": "array",
"example": [
"acct",
"webId"
],
"items": {
"type": "string"
}
}
}
},
"defaults": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"additionalProperties": {
"$ref": "#/components/schemas/ShardFeatureVisibility"
}
}
},
"features": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"additionalProperties": {
"$ref": "#/components/schemas/ShardFeatureVisibility"
}
}
}
}
}
}
},
"ShardVisibilityUpdate": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"required": {
"type": "array",
"example": [
"features"
],
"items": {
"type": "string"
}
},
"properties": {
"type": "object",
"properties": {
"features": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "object"
},
"additionalProperties": {
"$ref": "#/components/schemas/ShardFeatureVisibility"
},
"example": {
"type": "object",
"properties": {
"market": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"example": true
},
"audience": {
"type": "string",
"example": "player"
},
"stream": {
"type": "boolean",
"example": false
},
"fieldRules": {
"type": "object",
"properties": {
"ownerName": {
"type": "string",
"example": "player"
}
}
}
}
}
}
}
}
}
}
}
}
},
"ShardLinkRequest": {
"type": "object",
"properties": {

72
server/swagger/swagger.js
View File

@@ -881,6 +881,78 @@ const doc = {
updatedAt: { type: 'string', format: 'date-time' },
},
},
ShardFeatures: {
type: 'object',
description:
"The shard features the caller may reach, plus the audience rung they resolved to. Drives client nav so it never renders a link that would 403.",
properties: {
level: {
type: 'string',
enum: ['anonymous', 'logged_in', 'player', 'staff', 'admin'],
example: 'anonymous',
},
features: {
type: 'array',
items: { type: 'string' },
example: ['status', 'activity', 'champs', 'guilds', 'governors', 'houses', 'presence'],
},
},
},
ShardFeatureVisibility: {
type: 'object',
description: 'Visibility settings for one shard feature.',
properties: {
enabled: { type: 'boolean', example: true },
audience: {
type: 'string',
enum: ['anonymous', 'logged_in', 'player', 'staff', 'admin'],
description: 'Minimum rung that may reach this feature. Each rung implies the ones below it.',
example: 'anonymous',
},
stream: {
type: 'boolean',
description: "Whether this feature's event kinds fan out over SSE at all.",
example: true,
},
fieldRules: {
type: 'object',
additionalProperties: { type: 'string' },
description:
'Per-field rung overrides for the sensitive fields this feature exposes. acct / webId are admin-only always and are rejected here.',
example: { location: 'staff' },
},
},
},
ShardVisibilityConfig: {
type: 'object',
properties: {
ladder: {
type: 'array',
items: { type: 'string' },
example: ['anonymous', 'logged_in', 'player', 'staff', 'admin'],
},
lockedFields: { type: 'array', items: { type: 'string' }, example: ['acct', 'webId'] },
defaults: {
type: 'object',
additionalProperties: { $ref: '#/components/schemas/ShardFeatureVisibility' },
},
features: {
type: 'object',
additionalProperties: { $ref: '#/components/schemas/ShardFeatureVisibility' },
},
},
},
ShardVisibilityUpdate: {
type: 'object',
required: ['features'],
properties: {
features: {
type: 'object',
additionalProperties: { $ref: '#/components/schemas/ShardFeatureVisibility' },
example: { market: { enabled: true, audience: 'player', stream: false, fieldRules: { ownerName: 'player' } } },
},
},
},
ShardLinkRequest: {
type: 'object',
required: ['code'],