# Hostbound

A single-page browser game that teaches the **SSH perspective shift** - the
fact that once you `ssh` into a machine, every command runs *there*, and which
network you're standing on decides who you can reach next. Built for intro
networking students.

Each run generates a unique network. Your job: hop through the SSH web and
find the hidden **golden machine**, using fewer hops and fewer guesses.

## Play

Open `index.html` in any browser - double-click it, no server or build step.
Also served at <https://www.its.ohio.edu/tools/hostbound/>.

You start on some host with several network interfaces. You can only reach
hosts that share one of your **directly connected** subnets (no routing -
that's the lesson). Discover the network as you go; the map fills in
only what you've found.

Typical loop:

1. `ip a` - see which networks this host is on.
2. `nmap` - scan a connected subnet for live hosts (their addresses).
3. `ssh <address>` - hop to a discovered host on a connected subnet.
4. Read each host's recon file (`ls`, then `cat <file>`) - it states how
   many ssh-hops it is from the golden machine, plus a fragment of the
   golden machine's IP. Triangulate, move closer. The golden machine has
   **no recon file** - an empty home (`ls` shows nothing) is the tell.
5. When you think you're there, `claim` (or click **This is the Golden
   Machine**).

Scoring: **hops traversed** and **claims made** - lower is better. A wrong
claim just tells you "not it" and counts against you.

### Commands

`ip a`, `ping <addr>`, `nmap [-sn|-sV] [subnet|host]`, `ssh [user@]<addr>`,
`ls` / `cat <file>` / `nano <file>` (read a host's recon file), `exit`,
`where-am-i`, `describe`, `claim`, `clear`, `help`. SSH/ping/nmap only work against a
**directly connected** network (`ip a` shows yours) - that constraint is the
whole point. Address-based; **IPv4 by default, IPv6 / dual-stack optional**
(the family is carried by the code prefix). Cybersecurity Mode adds `inv`
(your tools) and the `dw` Darkweb commands.

## Sharing a network

Every network has a code shown in the bottom About bar and stored in the URL
hash (e.g. `index.html#HB1-2DEMOFW0`). The prefix is the address family -
`HB1-` IPv4, `HB2-` IPv6, `HB3-` dual-stack - and `HB4-` is an
instructor-dialed custom-topology code. **The code is the single source of
truth for shareable state**: it carries the topology seed *and* the
difficulty, Hidden Host Mode, Firewalls, and Cybersecurity toggles, so
pasting just the code reproduces the sender's exact playable world - same
layout, addresses, golden machine, and clues - on any machine. Share one with
the footer code box (edit / copy / new) or the hamburger menu's **Copy Share
Link**, **Copy Challenge Link**, **Today's network**, or **Custom network**.

## Difficulty and modes

Five difficulty levels (**Casual → Extreme**) scale the map size and the
number of branches, loops, and routers. Optional modes layer on top, each
carried in the code:

- **Hidden Host Mode** - hide the hop-trail breadcrumb (On), or hide
  everything but the LAN squares and your current host (Hard) so you must
  navigate from the terminal.
- **Firewalls** - some hosts/subnets silently drop `ping`/`ssh` even when
  same-LAN; you read the symptom and route around it via another peer.
- **Cybersecurity Mode** - hosts grow vulnerabilities you need a matching
  tool to `ssh`; you gather tools from loot and **The Darkweb**, funded by
  selling per-host intel. With it on, recon files also point you at the
  Darkweb broker.

Full details are in the [Student Guide](docs/student.html) and
[Faculty Guide](docs/faculty.html).

## Accessibility

A high-visibility mode (larger type, higher contrast, bold) and a
Light / Dark / Auto theme toggle from the menu; both honor
`prefers-reduced-motion` and `prefers-contrast`. These two preferences -
plus, once an instructor unlocks it, the sticky Admin passphrase - are the
only things that persist across reloads (Admin ▸ *Clear Local Settings*
wipes all three). Game progress always resets: reopening a code restarts
that same network fresh.

## Project layout

- `index.html` - the entire game: embedded CSS/JS, no dependencies, no build.
  Seeded RNG → deterministic network generator → terminal engine → canvas
  map. The world is built around a guaranteed chain of LANs so the golden
  machine is always reachable and a real distance away.
- `docs/` - the HTML guides: `student.html`, `faculty.html`, and
  `maintainer.html` (plus `index.html`, the docs landing page).
- `TODO.md` - ranked feature backlog. `CLAUDE.md` - durable build notes.

## Verifying changes

There is no build. The generator's invariants (determinism, connectivity,
solvability, distance, NIC/LAN constraints) are checked by porting it to
Python and asserting over hundreds of seeds, and UI/canvas work is checked
with a headless Playwright harness kept outside the docroot - see the
Verification section of the [Maintainer Guide](docs/maintainer.html). Then
load `index.html` and play a known code end to end.