Module-Rust/server/catalogue.js

// ── What the bridge can say, and who may hear it ──────────────────────────
//
// One file, because these two questions have to be answered together or the
// second one rots: which frame kinds exist, and which of them a member of the
// public may see.
//
// ── The boundary ──────────────────────────────────────────────────────────
//
// Protocol 2's catalogue includes frames carrying **IP addresses** (a login
// attempt, an approval, a ban) and **one player's complaint about another** (a
// report), and one — a destroyed structure — that names where somebody lives.
// They are stored, because an operator chasing ban evasion needs them and
// because the sidecar persists what it is told. They must never reach a public
// page.
//
// **The boundary is enforced HERE, on the side that serves, and not on the wire.**
// The plugin could have stamped a `class` on every frame and saved this file the
// trouble; it deliberately does not (PROTOCOL.md §8.5). A boundary declared by
// the sender is a boundary a compromised — or merely out-of-date — game host can
// widen. Core's own shard fan-out works the same way: a public stream with an
// allowlist of kinds, and an admin stream that adds the rest.
//
// ── Default deny, and why it is not paranoia ──────────────────────────────
//
// `isPublic` answers `false` for a kind it has never heard of. That matters
// because of the shape of the mistake it prevents: the next protocol version
// adds a kind, this module ingests it happily (`rust_events` stores what it is
// given), and a page that filtered by a DENY list would publish it the day it
// first arrived — before anybody had decided whether it should be public. With
// an allowlist the new kind is invisible until somebody adds it here, which is
// the same moment they think about it.
//
// The test holds this list against `docs/rust-link/PROTOCOL.md` §8.4's table, so
// adding a kind to the spec without classifying it fails a build rather than
// shipping an address to a public page.

/**
 * Kinds a public, signed-out visitor may see.
 *
 * Each entry is a decision. `player.chat` is here because a shard's chat is
 * public by the same logic that makes a killfeed public — it happened in front
 * of everyone who was on the server — and an operator who disagrees turns the
 * feature off rather than relying on this list being wrong.
 */
const PUBLIC_KINDS = Object.freeze([
  'player.connected',
  'player.disconnected',
  'player.respawned',
  'player.death',
  'player.chat',
  'player.tally',
  'server.wipe',
  'server.initialized',
  'server.shutdown',
  // RunicNPC bosses (runicnpc stage 6, D277, D286). The game says a boss's spawn
  // and death to everyone on the server, so the feed may too: the death names the
  // killer by in-game name and counts the players who fought it, and names no
  // Steam id but the killer's, as the killfeed does. Its phases are told only to
  // the players near it (D286), so `npc.boss.phase` is staff's, below.
  'npc.boss.spawned',
  'npc.boss.died',
  // Protocol 14: Rust's own world events (PLAN_REDESIGNS §14.3.1, D353, D376).
  // Public as a KIND, and filtered per `event` inside it by `worldEvents.js`:
  // an event type this build does not know is staff's alone, a player's name
  // shows only to the presence audience, a Steam id only to staff, and a
  // position to nobody. So it is not a presence kind — the event names nobody
  // once `worldEvents.shapeFor` has read it for a viewer below that audience.
  'world.event',
  // Protocol 14: Dynamic PVP opened a PvP zone (PLAN_REDESIGNS §14.3.3). It
  // names nobody, and `dynamicPvp.shapeFor` keeps its position for staff and an
  // operator's own event names off public pages.
  'pvp.zone.created',
  // Protocol 14: a Dangerous Treasures event opened, and was won
  // (PLAN_REDESIGNS §14.3.4). Public as kinds, read per viewer by
  // `dangerousTreasures.shapeFor` as a world event is: the winner's name only
  // for the presence audience, Steam ids and the position only for staff.
  'dt.started',
  'dt.won',
  // Protocol 14: a guarded crate landed, and was cleared (PLAN_REDESIGNS
  // §14.3.5). Public as kinds, read per viewer by `guardedCrate.shapeFor` as a
  // treasure is: the clearer's name only for the presence audience, the Steam id
  // and the position only for staff.
  'gc.started',
  'gc.ended',
  // Protocol 14: a RaidableBases base appeared, was raided, was bought, or was
  // locked to a player by an admin (PLAN_REDESIGNS §11.4, D390). Public as
  // kinds, read per viewer by `raidableBases.shapeFor`: the raiders' and a
  // buyer's names only for the presence audience, Steam ids, the position and a
  // run's key only for staff.
  'raid.started',
  'raid.completed',
  'raid.purchased',
  'raid.locked',
])

/**
 * Kinds an admin may see and nobody else.
 *
 * Listed rather than implied by absence, so that "we know about this kind and it
 * is restricted" is distinguishable from "nobody has classified this kind" — the
 * second is a finding, and a bare allowlist cannot tell you which you are
 * looking at.
 */
const STAFF_KINDS = Object.freeze([
  'entity.destroyed',
  'player.reported',
  'player.banned',
  'player.unbanned',
  'player.login.attempt',
  'player.approved',
  // Protocol 3's two account frames. Neither carries a code — the code travels
  // through the player, which is what makes typing it proof — but both name a
  // Steam id ALONGSIDE a website account's activity, which is exactly the join a
  // public page must not be able to make: "this player is that person" is a fact
  // about somebody's identity, not about what happened on the server.
  'account.link.requested',
  'account.unlinked',
  // Protocol 4. Who holds which privilege in game, and the fact that somebody
  // changed it by hand — a question about a person's standing and about an
  // operator's own console, neither of which is a public page's business.
  'perm.drift',
  // Protocol 13. How a configuration save's reload ended — and, when it failed,
  // the tail of the game server's own log, which is an operator's console and
  // can hold anything a plugin chose to print.
  'config.outcome',
  // Protocol 13 (F8, D184). Which plugins a server runs, and which permissions
  // each one registers: an operator's inventory, and the map of what can be
  // granted there — not a public page's business.
  'plugin.loaded',
  'plugin.unloaded',
  // The world an event borrowed or made, ending on its own deadline:
  // `lease.expired` since protocol 8 and `world.expired` since protocol 9 — the
  // latter recognisable only from protocol 13 (F13). Neither was ever classified
  // (default deny kept both off public pages); both are an event's machinery,
  // and the public learns what an event did from core's own announcements.
  'lease.expired',
  'world.expired',
  // Protocol 6. Clan membership, which the org lead made members-only (D49):
  // who joined which clan, and who threw whom out, is the clan's business. It
  // reaches a clan's own members through core's Team feed, where core resolves
  // who is a member, and it reaches the server's public feed not at all.
  'clan.created',
  'clan.disbanded',
  'clan.member.added',
  'clan.member.left',
  'clan.member.kicked',
  // RunicNPC (runicnpc stage 4). `npc.died` names the player who killed it and
  // everyone who hurt it, so it is a roll call like `player.tally`: staff until
  // an operator says otherwise. What the public sees of a kill is the tally's
  // per-profile count on the leaderboard (D250).
  'npc.died',
  'npc.health',
  'npc.placement.changed',
  // Runicnpc stage 6: a boss's phase is said in game only to the players near it (D286).
  'npc.boss.phase',
  // Protocol 14 (§14.3.3): a Dynamic PVP zone closed. The plan keeps its close
  // a staff line: the public learns a zone opened, and the map shows it going.
  'pvp.zone.deleted',
  // Protocol 14 (§14.3.4): a Dangerous Treasures event ended, won or not. The
  // plan keeps it staff's; the map shows the chest go.
  'dt.ended',
  // Protocol 14 (§14.3.5): a guarded crate timed out with guards still standing.
  // The plan keeps it staff's; the map shows the crate go.
  'gc.failed',
  // Protocol 14 (§11.4): a RaidableBases base despawned. Staff's; the map shows
  // the base go.
  'raid.ended',
])

/**
 * The public kinds that say a NAMED player was on the server at a given moment.
 *
 * A subset of `PUBLIC_KINDS`, not a third list: these are public-page material
 * whose audience an operator chooses (`model/visibility`), where the rest of
 * `PUBLIC_KINDS` is public by construction. The org lead's rule, settled
 * 2026-09-22: **nothing tells who is online by default** — the narrowest
 * audience (staff) unless an operator widens it, and a count is never a name.
 *
 * `player.death` and `player.chat` are here, and that was decided rather than
 * overlooked. They are the killfeed and the chat — the content a feed exists
 * for — and each one says "this person was on at 12:03" as plainly as a connect
 * frame does. `player.tally` is a per-minute flush that is only ever sent for a
 * player who is playing, which makes it a roll call with extra steps.
 *
 * What is left in the public set once these are removed is the server's own
 * story — a wipe, a start, a shutdown — which names nobody.
 */
const PRESENCE_KINDS = Object.freeze([
  'player.connected',
  'player.disconnected',
  'player.respawned',
  'player.death',
  'player.chat',
  'player.tally',
  // Runicnpc stage 6: a boss's death names its killer, which says that player was on.
  'npc.boss.died',
])

/** Every event kind the protocol defines, through protocol 14. */
const ALL_KINDS = Object.freeze([...PUBLIC_KINDS, ...STAFF_KINDS])

const PUBLIC = new Set(PUBLIC_KINDS)
const STAFF = new Set(STAFF_KINDS)
const PRESENCE = new Set(PRESENCE_KINDS)

/**
 * May a signed-out visitor see this kind?
 *
 * Default deny: an unknown kind is not public. Callers pass whatever arrived on
 * the wire, including a kind from a newer protocol this build has never seen.
 */
function isPublic(kind) {
  return PUBLIC.has(kind)
}

/** Is this a kind this build knows about at all? */
function isKnown(kind) {
  return PUBLIC.has(kind) || STAFF.has(kind)
}

/** Does this kind name a player who was on the server at the time? */
function isPresence(kind) {
  return PRESENCE.has(kind)
}

/**
 * Narrows a list of requested kinds to the ones a viewer may have.
 *
 * Returning the allowlist itself when nothing was requested is what makes the
 * public route safe by construction rather than by remembering to filter: there
 * is no code path where "no filter" means "everything".
 *
 * `presence` defaults to `false` for the same reason `admin` does: a caller that
 * forgets to say what the viewer may see gets the narrowest answer. The route
 * resolves it from the operator's setting (`model/visibility`); nothing else
 * should be passing `true`.
 */
function kindsFor({ admin = false, presence = false, requested = null } = {}) {
  const permitted = admin
    ? ALL_KINDS
    : PUBLIC_KINDS.filter((k) => presence || !PRESENCE.has(k))

  if (!requested || requested.length === 0) return [...permitted]

  const allowed = new Set(permitted)
  return requested.filter((k) => allowed.has(k))
}

module.exports = {
  PUBLIC_KINDS,
  STAFF_KINDS,
  PRESENCE_KINDS,
  ALL_KINDS,
  isPublic,
  isKnown,
  isPresence,
  kindsFor,
}