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 |
Context
Section titled “Context”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".
Decision
Section titled “Decision”Enabling
Section titled “Enabling”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 };- Default is off.
devtools: trueenables it only whenNODE_ENV !== 'production'. - In production,
devtools: trueis ignored with a warning. Enabling there needs{ enabled: true, allowInProduction: true, token }with a token of at least 32 characters; otherwisecreateServerthrows. Production use is meant for a short, deliberate debugging session, and the startup log says devtools is live. - 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=.... - 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.
Mounting and authentication
Section titled “Mounting and authentication”- 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. - 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. - 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).
- Responses carry
Cache-Control: no-store, a strictContent-Security-Policy(default-src 'self'),X-Frame-Options: DENYandReferrer-Policy: no-referrer. - Every authenticated devtools session and every export is logged at
warnwith the remote address.
Live tables are read-only
Section titled “Live tables are read-only”- 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.
- 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”- Time travel builds a new
TableRuntimebyreplay()from the stored log up to the chosenseq(ADR 0006), reading entries throughStore.readLog(ADR 0009). It runs in an isolated sandbox: no transport, a fake clock, no store writes, and a freshMemoryWalletseeded from recorded balances (ADR 0007). The live table is never paused or touched. - Fork turns such a copy into a dev table: id prefixed
dev_, flaggeddev: true, hidden from the lobby, not persisted, always using aMemoryWallet. 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. - Export as fixture downloads JSON that
shoehive/testingreplays:
interface Fixture { shoehiveFixture: 1; game: string; version: number; entries: LogEntry[]; // includes the 'create' entry and its seed expect?: { rev: number; stateHash: string };}// shoehive/testingconst t = replayFixture(blackjack, fixture); // a test table at the last entryExport replaces player ids with `p0`, `p1`, ... and drops names and metadata. Theseed is kept, because without it the fixture cannot replay. The download dialogstates that a fixture from a production table reveals that table's cards.Implementation notes (Phase 6)
Section titled “Implementation notes (Phase 6)”shoehive.devtools.handleRequest(req, res)routes devtools paths for apps whose HTTP stack cannot be wrapped;attach()otherwise wraps the app'srequestlisteners and restores them on close.- A cross-site browser
Originis refused before authentication, so a web page can neither guess the token nor trigger the lockout. Same-host origins, and those in the server'soriginsoption, 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 noForwarded,X-Forwarded-FororX-Real-IPheader (a proxy on the same host connects from loopback on behalf of anyone), and itsHostis an IP literal,localhost, a.localhostname or the host of anoriginsentry. TheHostrule stops DNS rebinding: a page on an attacker's domain that resolves to 127.0.0.1 sends a same-hostOrigin, which the Origin check alone would accept. WithallowRemote: truenone of these checks apply, so rely on the token (and TLS) there. - The CSP is
default-src 'self'withconnect-srcalso listing the page's ownws:andwss:origin,img-srcallowingdata:, andbase-uri,form-action,frame-ancestorsandobject-srcset to'none'. Responses also sendnosniff, 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'sMemoryWalletstarts 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 top0,p0 (2)...;expectcomes from replaying the anonymized log, andreplayFixtureinshoehive/testingchecks 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.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- 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.
Negative
Section titled “Negative”- 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.
Alternatives considered
Section titled “Alternatives considered”Devtools messages on the game socket
Section titled “Devtools messages on the game socket”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.
No token in dev
Section titled “No token in dev”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.
Live state editing and action injection
Section titled “Live state editing and action injection”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.
