gen1recomp/docs/link-security.md

# Link play: threat model and what the code actually guarantees

Link play is the only part of this game that reads bytes written by
somebody else. This is what it defends against, what it does not, and
where each guarantee lives.

## The boundary

Everything a peer or the relay sends arrives as one JSON object per line.
There is exactly one place it becomes a message:

    src/link/Net.lua        reads bytes, frames lines, decodes JSON
    src/link/Wire.lua       rebuilds each line as a typed message
    src/link/Session.lua    the only path from a transport into a mode

`Session:update` runs `Wire.sanitize` on every message before anything
else sees it. A schema returns a **new** table holding only the fields it
names, at the Lua types it names, so the rest of `src/link/` can read
`msg.slot`, `msg.parts.actives` or `msg.mons[i].dvs.hp` directly and be
right by construction. A message with no schema (a mod's, or a future
build's) keeps a bounded, scalar-only copy of its payload instead of
being dropped.

A message that fails its schema is **dropped and logged**, never fatal.
Latching a terminal failure would hand a hostile peer a cheaper
disconnect than sending nothing at all.

### Why the bounds are loose

Wire's numeric bounds are deliberately wider than the game's own clamps in
`Protocol.unpackMon`. Both peers run identical clamps over identical
packets; a bound that bit an honest value would change one side's copy of
a mon and desync the lockstep. Wire's job is types and sizes. Rules are
`Protocol`'s job, and it keeps its own clamps for the callers that reach
it without a Session (the mod API, `tests/`).

### Containment behind it

Assume something still gets through:

- `Game:step` pcalls the link pump, and pcalls `stack:update` **only
  while a link session is active**. On a throw, `Game:breakLink` closes
  the connection, unwinds to the overworld and says "The link was
  broken." Outside link play the stack is unguarded on purpose: a blanket
  pcall would swallow real engine bugs and leave the game silently wrong
  instead of loudly broken.
- `Net` caps `rxBuf` at 256KB and its per-frame read at 512KB, so a peer
  that never sends a newline ends as a clean disconnect.
- `Json.decode` refuses documents nested past 64 levels, and takes an
  optional length cap that the link path passes and the mod-manifest path
  does not.

## The relay (`../pokeserver`)

- A line that is not a JSON **object** with a string `type` is dropped
  before any handler runs, and `onLine` is wrapped in try/catch.
  `server.js` installs `uncaughtException`/`unhandledRejection` handlers:
  one bad packet must never take every live match down with the process.
- Line buffers are capped, lines per second are capped, connections per
  IP and in total are capped, and an unbound connection that never hosts
  or joins is swept after 30s.
- `SERVER_ONLY` is the set of message types the server is the only
  legitimate author of (`peer_gone`, `bracket_update`, `match_start`,
  `tournament_over`, `spectate`, ...). A peer that sends one has them
  dropped rather than forwarded, so a bracket opponent cannot forge a
  tournament result or fake "your opponent left".
- Trainer names are reduced to a printable subset and capped at the same
  10 characters the game enforces, on the way in, because they are
  rendered by the dashboard and broadcast to every participant.

`pokeserver/test/hostile.js` is the regression net for all of that.

## What is NOT defended

**Party legality is trust-the-client.** Online play meets strangers, and
`Handshake.onlineAllowed` is a Lua function in the same VM the mods load
into. It cannot be made tamper-proof in-process, and pretending otherwise
would only cost honest mod authors. What lockstep and
`Protocol.unpackMon`'s recompute-from-species-data *do* guarantee is that
a cheater cannot invent stats, moves, or a shiny: every derived value is
rebuilt locally from real species data. They can send a legal party they
farmed or edited. That is the honest boundary.

What the relay does instead is **observe and record**. It already sees
every `hello`, so it keeps each connection's self-reported
`engineVersion`, `fingerprint` and `linkModified`, compares the two sides
of a room or a live tournament match, and logs and surfaces a
`modded` / `fingerprint_mismatch` / `version_skew` flag on the dashboard.
A patched client can still lie; what it cannot do is lie without the
tournament organizer having a record of it.

Client-side attestation is deliberately not built. This is an
open-source Lua game: it would be theater, and it would break honest
mods.

**The relay has no TLS.** Port 7778 is plaintext, so party contents,
trades and trainer names are visible to anyone on the network path. There
is nothing secret in a Pokemon party, but it is a real property of the
system and not an oversight. Fixing it means a TLS terminator in front of
the relay and a client that speaks it, which is a version break for every
shipped build.

**The dashboard has no default password.** `DASHBOARD_PASSWORD` is
required; with it unset the relay runs and the dashboard simply does not
start. It is still Basic Auth over plain HTTP, so it belongs behind an
IP restriction or an SSH tunnel (`pokeserver/DEPLOY.md`).

## Tests

    luajit tests/link_hostile.lua        every message type x every wrong type
    luajit tests/link_desync_fuzz.lua    lockstep fuzz, plus a mutation mode
    luajit tests/run_link_tests.lua      both of the above, plus the rest
    cd ../pokeserver && npm test         relay smoke, 16-player bracket, hostile

`tests/link_hostile.lua` builds its corpus from a template per message
type, replaces each field (and several nested ones) with every wrong Lua
type, and drives the survivors through the real trade session, a real
lockstep battle, a real spectator battle, and the tournament screen
**including its draw** -- because the two nastiest payloads are
delayed-fuse ones that crash on render rather than on receipt.