keyrelay/.agents/PLAN.md

keyrelay — Master Plan

Master design document for a phased-execution project. The phase roadmap below was derived from TODO.md on 2026-11-08; each phase overview and task file cites its source lines in that file. The LOCKED DECISIONS below are binding: no phase may introduce technology outside them without explicit user permission.

README.md remains the single source of truth for behaviour, protocol and safety. AGENTS.md remains the operating manual. This file adds what is left to build and the anchors those phases may not move. If this plan and the README disagree about arming, the wire format or the safety model, the README wins and this file is wrong.

Assumptions & Design Principles

• The safety model is not on the roadmap. Disarmed-is-the-only-default, the release funnel, state-not-events, nothing-stored, reject-never-guess, fixed Ctrl+Alt+Del, one-frame-one-command, exclusive-keyboard-not-exclusive-board: every phase adds capability inside those rules. A phase that needs one of them relaxed is wrong, not ahead of schedule.
• Every new capability has to be cancelable. Anything that can outlive a disconnect — a session, a TLS context, a touch capture, a modifier latch — is cancelled in releaseEverything() or on the link change that ends it, exactly like the paste run.
• Auth is a precondition, never a consequence. Takeover (03) and the soft keyboard (05) build on the authenticated channel (02); neither may gain the ability to arm.
• No secrets in files. Not in the repo, not in a log, not in a URL, not in shell history. This is why the TLS identity is generated on the board rather than shipped as a PEM in the tree — the pipeline's own hygiene gate refuses tracked *.pem|*.key|*.crt.
• No unit blocks on hardware. Board access is best effort: one attempt, wrapped in timeout, outcome recorded in .agents/HW_VERIFICATION.md. The gate is host-observed (test suites + both firmware builds + curl against a reachable board when one is reachable). A phase may not hang, retry forever, or leave the board in download mode waiting for a human who is not there.
• Docs move in the same change (README sections named per task; AGENTS.md only gets stale statements fixed, never expanded).

Architectural Anchors

COMPONENT	DECISION	RATIONALE	STATUS
Target hardware	M5Stack AtomS3 Lite (ESP32-S3FN8, 8 MB flash, no PSRAM), one USB port shared between USB-Serial/JTAG and TinyUSB	platformio.ini header, README "The one USB port"	LOCKED
Build	PlatformIO espressif32@8.0.0 (Arduino core 3.3.12), envs bridge (HID) and console (ARDUINO_USB_MODE=1, KR_HAVE_HID == 0)	console is the only thing that compiles the no-HID branches	LOCKED
Control plane	One browser page served from flash (src/web_page.h), one WebSocket, ASCII one-frame-one-command, no JSON inbound	invariant 7	LOCKED
Pure modules	keystate.h, proto.h, text.h, mouse.h, output.h, ws_codec.h, sha1.h include no Arduino/IDF header, so the identical code runs on a host under ASan/UBSan	tests/run_tests.sh	LOCKED
Crypto/TLS stack	mbedTLS + esp-tls exactly as shipped by the installed core — no new third-party dependency. Verified in ~/.platformio/packages/framework-arduinoespressif32-esp32s3-libs: flags/ld_libs carries -lmbedtls_2 -lmbedcrypto -lmbedx509 -lmbedtls -lesp-tls -llwip; esp_tls_server_session_create/_continue_async/_delete, esp_tls_conn_read/write, mbedtls_ssl_setup/set_bio/handshake/conf_max_frag_len, mbedtls_pk_write_key_pem, mbedtls_ecp_gen_key, mbedtls_ctr_drbg_seed, mbedtls_x509write_crt_init, mbedtls_base64_encode all resolve; sdkconfig enables MBEDTLS_ECP_C, MBEDTLS_ECDSA_C, ECP_DP_SECP256R1, KEY_EXCHANGE_ECDHE_ECDSA, SSL_ALPN	the user chose full WSS; nothing new has to be fetched, vendored or audited	LOCKED
TLS transport shape	HTTPS on 443 + wss://, one TLS context for the controller and a short-lived one per read-only request; :80 becomes redirect-only	a page loaded over http:// can be replaced on-path by an attacker who then owns the keystroke path, so half-encryption is not a smaller risk — it is a smaller apparent risk	LOCKED
TLS identity	Self-signed ECDSA secp256r1 certificate generated on first boot, PEM key+cert in NVS, SHA-256 fingerprint printed once on the serial console for pinning; regenerated only if NVS is erased	keeps the private key out of the repo (AGENTS.md), survives reflashing (NVS does), and a per-board key means stealing the repo does not buy a MITM position	LOCKED
Plaintext rollback	-D KR_TLS=0 builds the current ws://-only behaviour; documented in README as the rollback, same standing as mouse off	a device that cannot be reached over TLS after a bad provisioning change must have a way back that is a reflash, not a repair	LOCKED
Arming	Unchanged by every phase in this roadmap: TLS, takeover and mobile input are all gated on the same arming as a keystroke today	invariant 2	LOCKED
Host gate	tests/run_tests.sh (+ SANITIZE=1) and both PlatformIO builds; pio run -t upload never runs inside .agents/validate.sh	AGENTS.md: an upload in a gate is a device side effect on somebody else's schedule	LOCKED

High-Level Architecture

laptop / phone browser                      target machine
  src/web_page.h  -- https:// + wss:// --->  ┌───────────────────────────────┐
        │  CODE_TO_USAGE, Pointer Lock,      │ AtomS3 Lite (ESP32-S3)        │
        │  touch pad, soft keyboard          │  src/main.cpp   loop(), arming│
        ▼                                    │  src/control_server.{h,cpp}   │
   one ASCII frame  (T N X A S C Y P M R K)  │   ├ src/tls.{h,cpp}  mbedTLS  │  USB HID → target
   one status frame (S{json})            <---│   ├ src/ws_codec.h   SHA-1/WS │
                                             │   ├ src/proto.h → keystate,   │
   tools/relayctl.py  (terminal controller,  │   │   text, mouse, output     │
    stdlib ssl, same frames)                 │   └ serial console (no typing)│
                                             └───────────────────────────────┘

• ControlServer owns exactly one controller socket plus one read-only socket, and both read-only paths go through serveReadonly() so they cannot drift (invariant 8). Phase 02 puts a transport underneath it (plain socket vs mbedTLS session) without splitting the routing.
• main.cpp owns arming, the report queue and releaseEverything() — the single funnel that clears the queue, raises the keys, ends the chord and discards a pasted run.
• The page is one C++ raw string; tests/test_page.js executes it against a DOM shim.

Data Model

• Key state: S=<mods>:<usages> restates everything; applying the same state twice is a no-op. No events, no sequence numbers, no resynchronisation timer.
• Mouse: M=<btn>:<dx>:<dy>:<wh>:<pan>, button byte restated every frame, deltas signed-byte bounded.
• Status (statusJson() in control_server.cpp): v up usb armed net ssid ip keys chords drop roll leds dflt ap typed typing mouse mbtn mframes. typed/typing are counts, never text — that rule is not negotiable for any new field either.
• NVS (namespace in src/main.cpp, survives reflashing): sta_ssid, sta_pass, token, ap_mode, mouse. Phase 02 adds tlscrt, tlskey (PEM) and tlscrtfp.
• Persistence never holds text. No macro store, no schedule, no replay, no auto-arm.

Validation / Verification Workflow

1. Host unit/integration — tests/run_tests.sh: test_keystate, test_proto, test_text, test_mouse, test_output, test_ws_codec compiled from the same headers the board runs, plus test_relayctl.py (tool↔page↔config.h tables) and tests/test_page.js (the page script, executed). SANITIZE=1 for anything touching a buffer. Baseline at the start of this roadmap: 3406 checks, all passing.
2. Firmware builds — uv run --python 3.14 --with platformio python -m platformio run -e bridge -e console (the pio on PATH is broken; pio run -t upload reports SUCCESS on a stale binary, so build status is checked before anything is trusted). Baseline: bridge RAM 26.7% (87 592 B), Flash 36.1% (1 135 293 B); console RAM 16.8%, Flash 33.6%. Any phase that grows RAM is expected to quote the new pair.
3. Device observation — tools/watch_target.py on the target (evdev, focus independent) is the only thing that says what the target received; curl against the served page pins page claims. Best effort per the hardware rule above, logged in .agents/HW_VERIFICATION.md.
4. Gate — .agents/validate.sh runs 1 + 2 (plus repo hygiene) after every task; a phase commits only when it exits 0.

Phase Roadmap

#	Phase	TODO source	Objective (one line)
01	01_verification_gate	— (foundation)	.agents/validate.sh runs keyrelay's real gates (host suites, sanitiser run, both firmware builds) and the hardware contract is written down so no unit blocks on a board
02	02_tls_control_channel	TODO.md L3	HTTPS + wss:// with an on-board-generated self-signed EC identity, so the passphrase and the keystrokes are encrypted in transit and the board's identity can be pinned
03	03_session_takeover	TODO.md L6	An authenticated controller can deliberately take the bridge from a session left connected; the incumbent is told, the funnel runs, and the board comes back disarmed
04	04_controller_page_responsive	TODO.md L4	Less prose, tighter layout: one-screen controls on a laptop, single-column and thumb-sized on a phone, safety statements kept verbatim
05	05_mobile_controller	TODO.md L5	Arm on a phone and the soft keyboard appears, with an on-screen modifier row; press-and-hold the pad and the target's pointer moves, release and every button lets go

Excluded (already done, no phase): nothing — TODO.md held no [x] items.

Deferred, deliberately not in this roadmap (still in README Backlog): OS-wide evdev capture client, GPIO panic release path, per-connection rate limiting, mDNS on the AP interface, WPA3/PMF, report-rate telemetry, multi-run pastes, non-US paste maps.