Skip to content

ADR 0011: Devtools security model

Status Accepted, 2026-11-14
Related RFC 0001 sections 5.3, 7 (Devtools), 11 (Devtools), 12 (Phase 6), 13; ADRs 0006, 0007, 0009, 0010

shoehive/devtools is a full inspector: live tables, raw state, every seat's view side by side, the action log with timings and rejections, sessions and connections, and replay, time travel, fork and export-as-fixture. That is exactly the information a cheater wants: raw state contains every hole card, and the create entry contains the RNG seed, which predicts every future card (ADR 0006). RFC 0001 section 13 lists "devtools exposed in production" as a risk. Phase 6 exits only if devtools are "off and unreachable in production mode".

type DevtoolsOption =
| boolean
| {
enabled: boolean;
token?: string; // required in production; generated in dev if omitted
path?: string; // default '/__shoehive'
allowRemote?: boolean; // default false: loopback clients only
allowInProduction?: boolean; // default false
};
  1. Default is off. devtools: true enables it only when NODE_ENV !== 'production'.
  2. In production, devtools: true is ignored with a warning. Enabling there needs { enabled: true, allowInProduction: true, token } with a token of at least 32 characters; otherwise createServer throws. Production use is meant for a short, deliberate debugging session, and the startup log says devtools is live.
  3. A token is required whenever devtools is enabled. In dev, if none is given, the server generates 32 random bytes and logs the full inspector URL once at startup, for example http://localhost:3000/__shoehive/#token=....
  4. In dev, requests from non-loopback addresses get 404 unless allowRemote: true. This keeps devtools off the LAN at hackathons and in shared Docker networks.
  1. Devtools is served on its own HTTP path (/__shoehive, static UI) and its own WebSocket path (/__shoehive/ws). It is never on the game socket path. The game protocol (RFC 0001 section 6) has no devtools messages, and a game connection cannot be upgraded into a devtools connection.
  2. The UI reads the token from the URL fragment (never sent to the server in a request line, so it does not land in access logs), then sends it as the first message on the devtools socket. HTTP endpoints take Authorization: Bearer. Comparison is constant time. Five failed attempts from one address in a minute lock that address out for a minute.
  3. When devtools is disabled, nothing is mounted: its paths return the server's normal 404 and the devtools module is not even imported (dynamic import on enable).
  4. Responses carry Cache-Control: no-store, a strict Content-Security-Policy (default-src 'self'), X-Frame-Options: DENY and Referrer-Policy: no-referrer.
  5. Every authenticated devtools session and every export is logged at warn with the remote address.
  1. Against live tables, devtools can only read: state, engine state, per-viewer views, log entries, the rejection ring buffer (ADR 0006), sessions and connection stats. There is no endpoint to act, edit state, move seats, fire timers or kick players. Operator actions stay in the typed server admin API.
  2. The view-as-viewer panel calls view() on the committed state, exactly as sync does (ADR 0003), so what devtools shows per seat is what that seat receives.

Replay, time travel and fork work on copies

Section titled “Replay, time travel and fork work on copies”
  1. Time travel builds a new TableRuntime by replay() from the stored log up to the chosen seq (ADR 0006), reading entries through Store.readLog (ADR 0009). It runs in an isolated sandbox: no transport, a fake clock, no store writes, and a fresh MemoryWallet seeded from recorded balances (ADR 0007). The live table is never paused or touched.
  2. Fork turns such a copy into a dev table: id prefixed dev_, flagged dev: true, hidden from the lobby, not persisted, always using a MemoryWallet. A developer can join it from the normal client and play on from that point. Forks are refused in production even when devtools is enabled there.
  3. Export as fixture downloads JSON that shoehive/testing replays:
interface Fixture {
shoehiveFixture: 1;
game: string;
version: number;
entries: LogEntry[]; // includes the 'create' entry and its seed
expect?: { rev: number; stateHash: string };
}
// shoehive/testing
const t = replayFixture(blackjack, fixture); // a test table at the last entry
Export replaces player ids with `p0`, `p1`, ... and drops names and metadata. The
seed is kept, because without it the fixture cannot replay. The download dialog
states that a fixture from a production table reveals that table's cards.
  • shoehive.devtools.handleRequest(req, res) routes devtools paths for apps whose HTTP stack cannot be wrapped; attach() otherwise wraps the app's request listeners and restores them on close.
  • A cross-site browser Origin is refused before authentication, so a web page can neither guess the token nor trigger the lockout. Same-host origins, and those in the server's origins option, are allowed.
  • Rule 4 in detail (Phase 8 security review, findings P-02 and P-03): without allowRemote, a request is served only if its TCP peer is loopback, it carries no Forwarded, X-Forwarded-For or X-Real-IP header (a proxy on the same host connects from loopback on behalf of anyone), and its Host is an IP literal, localhost, a .localhost name or the host of an origins entry. The Host rule stops DNS rebinding: a page on an attacker's domain that resolves to 127.0.0.1 sends a same-host Origin, which the Origin check alone would accept. With allowRemote: true none of these checks apply, so rely on the token (and TLS) there.
  • The CSP is default-src 'self' with connect-src also listing the page's own ws: and wss: origin, img-src allowing data:, and base-uri, form-action, frame-ancestors and object-src set to 'none'. Responses also send nosniff, COOP and CORP headers.
  • The UI removes the token from the address bar after reading it and keeps it in the tab's history.state, so a reload of the same tab reconnects; it never goes to a query string or to storage.
  • Copies (time travel and forks) replay with resendWalletOps: false. A fork's MemoryWallet starts from each player's last recorded balance and pre-holds the reservations open at the fork point at amount 0, so later commits succeed; the money those reservations held is not modelled.
  • Export maps player ids to p0, p1... in order of first appearance across entries, wallet ops and reservation keys, and each distinct name to p0, p0 (2)...; expect comes from replaying the anonymized log, and replayFixture in shoehive/testing checks it. The Playwright suite exports a fixture from every example and replays it.
  • Export also replaces strings equal to a known player id inside action and timer inputs and the table options. If the log does not replay that way (a game that inspects the shape of an id), those values are kept and the export warning says so. Kept in every fixture, besides the seed: free text in inputs (chat, for example), the table id, entry timestamps and the wallet balances the game read. A player id embedded in a longer string is not recognised.
  • Developers get the full inspector with zero setup in dev, behind a token they never have to type (the logged URL).
  • Production is safe by default: devtools is not mounted, not imported, unreachable.
  • Read-only live access plus copy-based time travel means debugging can never corrupt a running game or move money.
  • Exported fixtures turn bug reports into regression tests directly.
  • A loopback-only default surprises people running the server in a container or on a remote dev box. The 404 is logged with a hint to set allowRemote: true.
  • Fixtures from production contain the seed and are secrets. We warn; we cannot enforce.
  • No live editing means "what if" questions need a fork first. That is deliberate.

One connection for the UI. Rejected: it puts privileged messages on the most exposed endpoint, and one protocol bug would leak raw state to players.

Less friction. Rejected: browsers let any website open a WebSocket to localhost, so an unauthenticated local inspector is readable by any page the developer visits.

Handy for debugging. Rejected: it breaks "state only changes through actions, hooks or timers" and makes the log no longer the source of truth. Forks cover the use case.