keyrelay/README.md

keyrelay — a WiFi-remote USB keyboard and mouse on the M5Stack AtomS3 Lite

Type on your laptop; the keystrokes land on a different machine, over the air, as genuine USB HID input — including Enter and Ctrl+Alt+Del. Capture the pointer and your mouse moves the other machine's cursor. The board enumerates on the target as a boot-protocol keyboard with a relative mouse on the same HID interface, so the target needs no software, no driver and no network. The controller is a web page served by the board itself, over TLS, with a certificate the board made on its own first boot.

   your laptop                          target machine
   ┌──────────────────┐                ┌──────────────────┐
   │ browser tab      │   WiFi         │                  │
   │  keydown/keyup   ├──wss://(TLS)──►│  AtomS3 Lite     │
   │  mousemove       │   (token)      │  keyrelay        │
   │  (Pointer Lock)  │                │                  │
   └──────────────────┘                └────────┬─────────┘
                                                │ USB HID: boot keyboard
                                                │          + relative mouse
                                                ▼
                                       whatever has keyboard focus:
                                       a login prompt, a BIOS setup,
                                       a VT, a text editor

disarmed   LED dark      nothing you type or move goes anywhere
armed      LED solid red every keystroke in the tab goes to the target

The mouse is opt-in twice over: the bridge has to be armed and the page has to be handed the pointer, which the browser only does when you click. Esc gives it back — that one is the browser's own guarantee, not something this firmware has to honour.

• Nothing types until you arm it. Boot, reload, reconnect, focus loss, socket loss and 8 s of silence all disarm, and disarming sends "all keys up" and "all mouse buttons up" — to the target, as reports, not just to the board's own bookkeeping.
• Arming needs a passphrase (or a thumb on the board's button). The LED is readable from across the room, so the state is not a secret between you and the screen.
• Nothing that matters crosses the network in the clear. The board serves the page, the WebSocket and /status over TLS on :443 with an ECDSA keypair and self-signed certificate it generated on its first boot and keeps in NVS, so the passphrase, the keystrokes, the pasted text and the pointer deltas are encrypted or they are not sent. Port :80 answers nothing but the way to :443 — a 301, and a 426 Upgrade Required to a plaintext /ws upgrade or to a request carrying ?token=. The certificate's SHA-256 fingerprint is printed once at first boot and reprinted by the serial cert command; checking it against the board's own console is the one link in this chain that a human has to close, because encryption you have not identified is encryption you have assumed.
• The mouse is captured, not grabbed. The page asks the browser for Pointer Lock — the same thing a web game asks for — so the cursor cannot escape the tab while it is being forwarded, and Esc always returns it. Losing the lock, the tab or the link releases every button. Movement is relative: the board says how far, never where, so there is no position for the two machines to disagree about.
• The keystrokes are not stored, logged or replayable. The board keeps counters and the live key and button state, and nothing else — no sequence storage, no macro, no script, nothing it can type later, no gesture it can replay. Pasted text is typed from RAM and forgotten; the serial console has no command that types or clicks anything at all. It is a keyboard and a mouse, not a payload dropper.
• 5104 checks cover the key-state machine, the mouse state, the report queues and the release funnel, the wire protocol, the text→keystroke map, SHA-1/base64, the WebSocket codec, the TLS identity's PEM armour, name table and fingerprint renderings, the TLS session's policy layer (handshake deadline, slot admission, library-return table, refusal record and frame ring), the transport view's response head, :80 answer table, redirect builder and page send cursor, the pending takeover claim's whitelist and clocks (which frames a claim may send at all — arming is not one of them), the status frame's fields (including busy/tkov, which say a bridge is held without ever saying by whom) and the buffer they have to fit in, the controller page's own script (its refusal to type a passphrase from a page that arrived in the clear, and the take-over gesture that stays down until one deliberate click), the CLI's frames and its TLS trust decisions (no trust argument → refuse; wrong fingerprint → nothing sent) and its --take-over ordering, and the target-side verifier itself — all before anything is flashed.

---

Contents

• Is this the right tool
• Quick start
• The one USB port, and why the control path is WiFi
• Safety model
• Security model and trust boundaries
• Linux notes (the target and the laptop)
• Layout caveats
• Controller page
• Wire protocol
• Serial console
• Architecture
• Tests
• End-to-end verification
• Measured behaviour
• Troubleshooting
• Design decisions
• Backlog
• Restoring the sibling firmware

---

Is this the right tool

Good fits

• Driving a machine that has no keyboard and should not get one: a headless box, a rack server at a console, a kiosk, an instrument, a second machine mid-install.
• Working on a machine you are allowed to touch but not sit at — BIOS/UEFI setup, bootloader and recovery screens, a login prompt, a full-screen game on a laptop whose keyboard you would rather not wear out.
• Keeping an agent session live on a machine you are not typing into (that is the sibling project ../jiggler, which is a simpler build of the same board).
• Pointing at something on a machine you cannot reach — a BIOS menu item, a dialog in a installer, a button in a kiosk app — with the cursor you can already see on that machine's own monitor.
• Anything where a KVM-over-IP would be right and you do not need video or audio, and you have 8 dollars and a USB port to spare.

Bad fits — use something else

• You need the screen. There is no video path. You steer the target's cursor without being able to see it, which is fine for a monitor you are looking at and hopeless for one you are not. PiKVM or TinyPilot do video + keyboard + mouse.
• You need to know where the cursor is. Movement is relative — see Layout caveats. There is no absolute pointer, so "click the OK button" is not a thing this can express, deliberately: an absolute pointer would give the board a position to be wrong about.
• You want unattended automation. Deliberately impossible here (see above). If you want scripted input on a machine you own, xdotool/ydotool/uinput on that machine is the honest tool, and a Rubber Ducky is what this design is not.
• A machine you are not authorised to input to. Physical access is the whole security model of every USB HID tool, and "I could plug it in" is not authorisation. Use it on your own hardware or where you have explicit permission.

What this deliberately is not

There is no macro store, no auto-arm at boot, no stored or scheduled sequence, no replay, and no key logging — in firmware or in the tools. Not because it is hard (it is about ten lines of Keyboard.print()), but because the difference between "a remote keyboard" and "an unattended injection device" is exactly whether a human is deciding, live, with the arming light on.

Where the line sits. Text you have just pasted and then deliberately sent is a keyboard doing its job, so there is a command for it: the page's Send text box, or wl-paste | relayctl paste --yes. It is gated like everything else — armed, a target attached, one deliberate press of a button that says how many characters it will type — and it cannot outlive that decision. The characters sit in RAM until they have gone out and then they are gone: nothing is stored, nothing is scheduled, and release-all, disarm, focus loss, a silent controller or a detached target cancels the rest of a run mid-word. What stays absent is the part that would change what this device is — something the board remembers, assembles on its own, or fires without a human in the loop.

The mouse is the same line, drawn in the same place. There is no auto-click, no double-click macro, no drag recorded and replayed, no "move to (x, y)", no idle wiggle that keeps a screen unlocked, and nothing that moves the pointer because a timer said so. relayctl mouse click and mouse drag exist because verifying that the button bits arrive is a thing the operator has to be able to do, and each needs --yes; a movement (mouse move) does not, because moving a cursor is reversible by definition. If nobody is moving a mouse, nothing moves. The pointer is captured with the browser's own Pointer Lock, so Esc — which the browser keeps for itself and never forwards — is an escape hatch that does not depend on the firmware, the network or this page being correct.

Two consequences hold either way. The CLI's ordinary commands still press one key per invocation, which is all verification needs; scripting 30 of them is possible and would still be 30 deliberate actions with the LED on. And a captured board is a keyboard, not a recording — pull it out and there is nothing in it to find.

---

Quick start

Needs PlatformIO and the board's source on this machine. The board is an ESP32-S3 with no USB-UART bridge, so all flashing is over the USB-C connector it already uses.

cd keyrelay
tests/run_tests.sh                    # 5104 checks, no hardware needed
pio run -e bridge                     # ~1.2 MB image, ~40% of the 3 MB app slot (TLS on)
python3 tools/to_bootloader.py        # 1200-baud touch -> ROM download mode
pio run -e bridge -t upload           # flash

Build console as well as bridge before flashing: it compiles with ARDUINO_USB_MODE=1, which is the only thing that checks the no-HID #else branches. And if pio on this machine is a broken launcher rather than a working command (ModuleNotFoundError: platformio), python3 -m platformio from an interpreter that has the package works instead — see AGENTS.md, which lists this and the other environment traps.

Then, with the board plugged into the target:

python3 tools/console.py wifi "My SSID" "the wifi passphrase"    # optional: join a LAN
python3 tools/console.py token "a-long-passphrase-you-pick"      # do this one, always
python3 tools/console.py status

A board with nothing in NVS makes its TLS identity on that first boot — an ECDSA secp256r1 keypair and a self-signed certificate, kept in NVS — and prints the certificate's SHA-256 fingerprint once, wrapped over two lines so the serial console cannot drop half of it:

[tls] identity generated -- pin this certificate:
       ba:78:16:bf:8f:01:cf:ea:41:41:40:de:5d:ae:22:23
       b0:03:61:a3:96:17:7a:9c:b4:10:ff:61:f2:00:15:ad

(Two 47-character lines, never one 95-character line. The bytes above are the SHA-256 of abc, so nobody reads them as their own board's.)

That is the only time the board prints it. python3 tools/console.py cert prints it again, on demand, with the certificate's validity window and the names it is issued for — and never the key, in either direction: there is no command that writes an identity and none that dumps one. The fingerprint survives reflashing (NVS does) and changes only when NVS is erased (nvs erase, or the factory reset): the board then generates a new identity and says so loudly, because a fingerprint that changed quietly is a pinned value that stopped meaning anything. The first https:// connection will ask the browser to accept the certificate once per browser — that acceptance is per device and per browser profile, and a second prompt after a pinning is the same signal as a changed fingerprint. https:// is how the page is reached: port 80 answers a 301 to the encrypted port and a 426 Upgrade Required to anything it must not answer in plaintext (a /ws upgrade, a request carrying ?token=), and serves no content of its own.

Now, on the laptop:

the board is on	open in a browser	because
your WiFi network	https://keyrelay.local (or the ip= from status)	mDNS, then direct IP
its own access point	https://192.168.4.1 after joining keyrelay-ctl	no infrastructure needed

Enter the passphrase, press connect, press arm — the LED goes solid red — and type in that tab. Enter goes. Ctrl+Alt+Del is the button (twice), because your laptop's own OS swallows the real combination before a browser can see it.

The Connection card then shows the board's certificate fingerprint — certificate SHA-256 aabbccdd… — confirm it against the cert command on the board's serial console — and a header pill reads tls. Confirm those digits against python3 tools/console.py cert; a mismatch means the board regenerated its identity or somebody else is answering keyrelay.local, which is exactly the thing the fingerprint is for. The browser's own certificate warning is accepted once per browser, or you skip it for the terminal and pin instead:

python3 tools/console.py cert                       # the fingerprint, printed on demand
export KEYRELAY_TLS_FP='<the 64 hex digits cert printed>'      # 2:2 colon form works too
curl -sk 'https://keyrelay.local/status?token=a-long-passphrase-you-pick'
python3 tools/relayctl.py --host keyrelay.local status          # pins via $KEYRELAY_TLS_FP

relayctl.py requires exactly one trust argument — --fingerprint (also honoured as $KEYRELAY_TLS_FP), --ca <pem>, or --insecure (which warns on stderr every single run) — and refuses to connect without one, because a tool that quietly downgrades is the component that makes all of this pointless. A pinned run hashes the peer certificate before sending its first frame and aborts on mismatch, so a wrong pin never even leaks the passphrase attempt. --plain selects the plaintext ws:// on :80 — the -D KR_TLS=0 rollback board is the only thing that answers it, explicit opt-in, scriptable like everything else. A board held by another controller is a refusal, never a fallback: the tool says so and names --take-over, which is the same one deliberate X the page's TAKE OVER button sends — the incumbent is told (E12), every key and every mouse button is released through the release funnel, and the session continues disarmed. Against a free board --take-over is a stated no-op; neither path can arm.

To send text instead of pressing keys, paste it into Send text and press its button: it says how many characters it will type, the board types them as keystrokes at a pace the board keeps, and stop typing abandons the rest. From a terminal it is wl-paste | relayctl.py paste --yes (or xclip -o -selection clipboard, pbpaste).

The rollback — building it, and what it costs

If TLS itself is the thing that broke — a provisioning change you cannot undo from the network, a client that will not do TLS, a board you have to reach now — the way back is one reflash, and it is a build rather than a setting on purpose. A board that has lost its way over TLS should not also have to be trusted with the switch that would let it be reached in the clear; the same reasoning makes mouse off a reboot. Turning TLS out saves about 6 kB of RAM and 99 kB of flash, and the image fits the 3 MB app slot either way, so the way back is never a question of space:

pio run -e rollback                   # env:bridge with -DKR_TLS=0, i.e. the pre-phase-02 build
python3 tools/to_bootloader.py        # 1200-baud touch -> ROM download mode
pio run -e rollback -t upload         # if pio here is a broken launcher (ModuleNotFoundError),
                                      # use: python3 -m platformio run -e rollback -t upload

[env:rollback] in platformio.ini is env:bridge with the default -DKR_TLS=1 unflagged and -DKR_TLS=0 in its place. Unflagged, not overridden: two -D flags for one macro is a redefinition whose winner depends on flag order, and this PlatformIO's run has no --build-flags option to argue with, so the environment is the documented command. .agents/validate.sh builds all three environments on every run for the same reason — a way back that stopped compiling is not a way back, and the phase that added the encryption is not the phase that gets to decide it cannot be reversed.

What you get is the pre-phase-02 device: page and socket on :80 in plaintext, no :443, no identity generated and no NVS records for one, a boot line that says [tls] TLS compiled out (KR_TLS=0) -- plaintext control channel so nobody has to guess which board is answering, and a page carrying var KR_TLS_BUILD=0; so it connects over the plaintext socket instead of refusing an http: origin it was legitimately served. What you give up is the whole Security model: the passphrase and every keystroke are readable on the network again. Nothing about arming, the release funnel or the LED moves with the flag — it changes which port carries bytes, never who may type them. The rollback's ws:// is the only plaintext socket this README calls a normal way to reach a board, one reflash away.

To put the sibling project back on the board: cd ../jiggler && python3 .../to_bootloader.py && pio run -t upload.

---

The one USB port, and why the control path is WiFi

The AtomS3 Lite's USB-C is wired straight to the ESP32-S3's native USB pads (GPIO19/20), and those pads belong to exactly one peripheral and exactly one host at a time. A board that is a keyboard to machine A therefore cannot simultaneously be a serial modem to your laptop. That single hardware fact decides the architecture:

option	works?	why this project chose as it did
control over USB, HID to the same laptop	yes, pointless	the target is the laptop; that is the jiggler use case
second USB port / USB host shield	no	the board has one connector, and ESP32-S3 USB-host + device at once is not a thing
USB gadget on a Linux SBC (PiKVM-style)	yes	real answer for video + mouse; needs a Pi, a PoE HAT, and 10× the cost
WiFi control, USB HID out	yes	one connector stays free for the target, no host software at all

The consequence worth stating plainly: the board draws its power and its USB identity from the target, and its instructions from your network. Pulling it out stops everything immediately — that is a feature.

---

Safety model

Enforced in this order, each independent of the others:

1. Disarmed is the only default. Boot, page reload, WebSocket reconnect and page load all begin disarmed. armed is a state the board holds, not something the page assumes — the page's own arming only becomes visible when the board confirms it. A takeover lands disarmed too: when a second authenticated socket takes the bridge — X, or --take-over in the terminal — the handover runs through releaseEverything() before the newcomer is adopted, so every key and every mouse button the incumbent held comes up, and the handover itself cannot arm — nothing reachable from X calls arm(); only an ordinary authenticated A1 (rule 2), the board's button, or the console arms the session that now holds it. The displaced incumbent sees E12 and mirrors the same gesture locally: disarm, release the mouse, end the typing run, and stay down until a human clicks again.

2. Arming requires authority: the passphrase over the network, the button on the board, or the serial console. Nothing else can arm it, and nothing at all reaches the target while disarmed — not one key, not one chord, not even a "hello".

3. Armed is displayed on the device. Solid red LED while armed and attached. If the target is not attached the LED blinks red instead, because "armed" without a target means keystrokes are being dropped, and that deserves to look wrong.

4. Silence disarms. No inbound frame for kNoClientTimeoutMs (8 s) → all keys up and all buttons up, disarmed. Covers the laptop sleeping, the browser being killed, the WiFi dying, the network going down — every way a controller can vanish without saying goodbye. The browser sends a keepalive every 2 s and answers the board's own 15 s WebSocket pings, so a live tab holds it open indefinitely; relayctl does the same while it types. This is checked in loop(), and it is checked before the typewriter is driven: it is the one rule that stops a run of pasted text when the controller dies without a parting packet.

   What counts as silence, and what does not. The clock is moved only by the authenticated controller: by its authentication, and by bytes on its WebSocket. An accepted TCP connection is not a live operator, and neither is anything reading the board — a monitoring script, a health check, a second tab pointed at /status, or relayctl listen used to hold this timer at zero and keep the bridge armed indefinitely with the last key still pressed (bug 10). A board armed by its own button with no controller at all is deliberately left running: it has no controller to go quiet. This backstop is not gated on the link still existing, and must never be — see Fourteen bugs.

5. Focus loss releases every key. The tab blurring or being hidden sends "all keys up" and disarms (unless you tick stay armed if this tab loses focus, which still releases the keys — you cannot keep a held Ctrl alive by tabbing away).

6. The target taking the bus away disarms. USB detach or host suspend clears the report queue, releases the keys and disarms; ARDUINO_USB_* events drive it.

7. A full queue is a stop, not a drop. 48 queued key states or 32 queued mouse reports without a drain means something is outrunning the USB path, so the bridge releases everything, reports E7 and disarms rather than typing out of step with what the operator sees. The queue is not a buffer to absorb loss: 255 queued reports once sat through a disconnect, which is ~2 s of keystrokes delivered after the operator had stopped asking.

8. State, not events. The controller restates the whole key state on every event (see Wire protocol), so a lost frame cannot leave a modifier stuck on the target. This is the single most important design decision in the project: every "stuck Ctrl" horror story in HID injection tooling is an event-protocol bug. Mouse buttons follow the same rule — every M= frame carries the complete button byte — and movement is the one thing that is not state because a delta has no state to lose: a dropped movement frame moves the cursor slightly less, never leaves anything stuck.

9. A paste cancels; it never pauses. R means "stop typing", not "hold on". The run is dropped on release-all, disarm, target detach or suspend, queue overflow, focus loss and silence — every fail-safe above routes through the same releaseEverything() that clears the queue, raises the keys, lets go of the mouse buttons and discards what was still to type. The board never holds a run that outlives the decision to send it.

10. Losing the pointer releases the pointer. Pointer Lock going away, the tab blurring, the tab being hidden, disarm, R, silence and target detach all send an all-buttons-up mouse report. stay armed if this tab loses focus exempts the keyboard only — a held mouse button is never something to keep across a tab switch. The page stops capturing rather than queueing movement to send later.

TLS is transport, not an arming input. Every rule above reads the same on :443 as it read on :80, because nothing in the arming path consults the transport: a TLS session that is authenticated and not armed types nothing, and a TLS session that drops is a lost link, which runs releaseEverything() and disarms exactly as a dropped plaintext socket did. The -D KR_TLS=0 rollback changes which port carries the bytes, never who may type them — which is why it is a way back rather than a second security model (see Design decisions).

The physical kill switch is the button: press it and the keys come up and the buttons come up, no network, no passphrase, no software required. Esc is a second one for the pointer specifically, and it is the browser's, not ours.

One release funnel, and it has to actually send. Every item above ends in releaseEverything(), which now queues an all-keys-up and an all-buttons-up report to the target rather than only clearing the board's own idea of what is down. That is the fixed ninth bug: a held key stayed held on the target after silence-disarm, target loss or a reload, because the report that would have released it was never queued (see Measured behaviour).

---

Security model and trust boundaries

actor	can	cannot
Anyone on the target (its own OS)	see a Logitech G815 keyboard and a pointer in its device list; read the CDC console; type on itself	arm or drive the bridge remotely, detect that a second controller exists
Anyone on the board's network	fetch the page over https://; open a socket; learn that a keyrelay exists and read the public names on its certificate	arm, send a key, send a chord, type a run of text, move the pointer, click, read /status — all need the passphrase, and all but /status need the bridge armed. They no longer get to hear any of it: the passphrase and the keystrokes are inside a TLS record, and :80 hands out a redirect and two 426s and nothing else
Anyone who can see the traffic — a café access point, a mirror port, a hostile neighbour	learn that this address answers TLS, when, and how many bytes; read the certificate's own public names (keyrelay.local, keyrelay, 192.168.4.1)	read a passphrase, a keystroke, one pasted character or one pointer delta; get a plaintext page or a plaintext socket out of this board. One honest exception: an attacker who can see the traffic and is first to answer keyrelay.local is a certificate authority of one for any connection nobody pinned — the browser warning, or the fingerprint you compared against cert, is what closes that window, and nothing in the firmware can close it for you
Anyone with a copy of this firmware (or of this repository)	build their own keyrelay; read every byte of the protocol and of this README	impersonate your board or decrypt a session to it. The keypair is generated on your device, lives only in its NVS, and is not in the image, the tree, a log or a URL; every board's fingerprint is different, which is the only reason pinning means anything
Whoever holds the laptop's mouse	the browser tab's pointer, only after a click on Capture pointer, and only while armed	move the target's pointer without the LED being red, or keep moving it after Esc — Pointer Lock is revoked by the browser and cannot be retaken without another click
Someone guessing the passphrase	5 attempts before a 30 s lockout during which the token is not evaluated at all	learn anything from the failure: same error, same close, no timing oracle (constant-time compare)
Someone holding the passphrase, arriving on a second socket — a second tab, another laptop, a colleague	stand in the one pending-claim slot, keep itself warm, and take the bridge with one deliberate X (or --take-over from the terminal)	arm it by doing so — someone with the passphrase can take the bridge over, and cannot arm it by taking it: the handover runs through the release funnel and lands disarmed, and only an ordinary authenticated A1 arms. And they cannot learn who holds or held it: the status frame says busy and counts takeovers — a boolean and a counter, never addresses, user agents or identities
The owner of the WiFi	join the network, learn that a keyrelay is there, watch the size and timing of a session	read or forge what a controller sends, or arm anything. The perimeter used to be the network alone; now it is the network and whether the certificate was checked — see below
You, holding the board	arm/disarm (button), reconfigure or reflash (console), stop everything (unplug)	—
The target's user	notice a red LED next to their monitor, and pull it out	—

What the passphrase does and does not do. It authenticates the control channel; confidentiality is a separate layer, and that layer now carries everything: the board serves the page, the WebSocket and /status over TLS on :443 (https://, wss://) with the identity it generated on first boot (src/tls.h, src/tls_session.h), and :80 answers nothing but the way to :443 — a 301 for a page request, and a 426 Upgrade Required for a plaintext /ws upgrade or for a request carrying ?token= (src/conn.h, plaintextRoute()). So the passphrase, the keystrokes, the pasted text and the pointer now cross the network encrypted or not at all, and a page loaded over http:// — which an on-path attacker could rewrite, at which point it is their page asking for your keystrokes — is not a page this board serves. A plaintext /ws upgrade is refused rather than accepted: the weaker option is never taken quietly, and the refusal says wss:// in the body so the operator knows what to reconnect as. The controller slot stays shared between the two listeners, so a controller on either transport holds the keyboard — but never two at once, encrypted or not. The only build that carries keystrokes in plaintext is the -D KR_TLS=0 rollback, which is a reflash and a decision, not a mode a running board can fall into; see The rollback.

What TLS does not buy. Encryption is not identity until you look at the certificate. It is self-signed, so the first connection to a board you have never pinned is a decision-you-have-not-made-yet window, and closing it costs one comparison: 64 hex digits from cert, read on the board's own serial console, where nobody on a network can follow you. Ticking "accept the risk" in a browser is the same decision made without looking at anything, once per browser profile — and a second prompt for a board you already accepted is the same alarm as a fingerprint that moved. Encryption buys nothing for the things outside this channel, and they are worth naming in the same breath: the target sees every keystroke you send it and can log all of it, and that machine is not in this threat model at all; the laptop keeps the passphrase in sessionStorage and keeps --token in your shell history if you use it, so a controller someone else has touched is a controller you must re-passphrase; whatever you type while armed goes to the target whether or not you meant it to, which is what the LED and the focus-loss rule are for; and the board you walked away from is stopped by disarming and unplugging, not by crypto.

Why ?token= gets 426 instead of a redirect: a Location: that echoes the query exposes the passphrase twice on the wire the redirect is escaping, and it trains operators to type the secret into a http:// bar. The body of that answer names the fix without repeating the value — verified on the device, where the 426 body contains no token.

Practical rule: the certificate you did not check is the one thing to check. Everything else on this device is automated, reviewable and testable; comparing 64 hex digits against cert on the serial console is not, and it is the one step an on-path attacker can defeat merely by being there first. Next to it, still worth doing for a different reason: use it on a network you trust, or on the board's own access point whose WPA2 passphrase is a separate secret (kr::kApPass, change it in src/config.h) — the AP means you never have to put the board on someone else's LAN, which is a smaller blast radius even when the traffic is encrypted.

Single controller, by design. A second WebSocket upgrade cannot drive the keyboard. It is accepted into the board's one spare slot as a pending claim: it completes the same handshake, authenticates against the same passphrase and the same lockout counters, and may then send nothing but K to keep itself warm and one deliberate frame — X, take this bridge over. Arm, key state, chords including Ctrl+Alt+Del, pasted text, mouse frames and even R are each refused by one whitelist (src/claim.h, host-tested) with E6, and the claim is dropped: no frame from a claim reaches the target, disturbs the incumbent, or moves the arming line, and no claim frame is ever handed to the command dispatcher at all. X is the one act the door exists for — the operator locked out by somebody's forgotten tab (usually their own) — and it moves the bridge through the release funnel, never around it: the incumbent is told (E12), every key and every mouse button is released, and the handover lands disarmed. A takeover can never produce an armed board — nothing reachable from X calls arm(); the newcomer arms with an ordinary authenticated A1, exactly like a controller that connected cold, or it never arms (the ordering is pinned by source checks in tests/test_relayctl.py). A claim that goes quiet is dropped (kClaimTimeoutMs, 15 s) and its session freed, so a parked claim cannot hold one of the board's two TLS sessions hostage. Two controllers typing into one machine is precisely the ambiguity a keyboard must not have, and "who owns this bridge" should never be a tie. What the locked-out operator can see is busy and tkov in the status frame — a link state and a count of events — which is why the page can say "held by another controller" and the CLI can refuse by name without either ever saying who holds it, or from where. The refusal is one slot wide: the board holds at most kTlsMaxSessions (2) live connections — the controller's, and one spare (read-only viewer or the one pending claim, never both) — and a third connection is refused outright (a TLS alert record on :443, a close on :80, both counted), never queued and never half-opened, because a TLS session's I/O buffers are ~32 KB each and "accept first, find no memory later" is not an option on a board with no PSRAM.

What is exclusive is the keyboard, not the board: GET / and /status?token= are served even while a controller holds the bridge, so a page can be reloaded, a second window can watch the counters, and curl keeps working mid-session. Read-only access is still gated by what it reveals — /status needs the passphrase, the page needs it before it can arm or type. If that ever goes too far, the ap off/network config is the blunt instrument; there is no per-client ACL.

The mouse widens what a compromised controller can do, so it is gated the same twice over. Arm plus Pointer Lock. It is also the reason there is a mouse off switch: the composite descriptor is fixed when USB starts, so turning the pointer interface off is a reboot, not a setting change — and a board that advertises no pointer cannot be made to move one. When a target selects HID boot protocol (some BIOS setups, some KVMs) the mouse is switched off by itself, because a 5-byte mouse report on a boot-protocol interface would be parsed as keyboard data: the keyboard keeps working, the pointer stops, and E11 says why rather than the command silently doing nothing.

Identity. The board reports itself as 046d:c33f "Logitech Gaming Keyboard G815", matching the sibling jiggler firmware so the two are indistinguishable from the host side and /dev/input/by-id names stay stable across reflashes. This makes the device unremarkable in lsusb; it does not hide it from anyone who looks for a keyboard that appeared at 14:32. It is your hardware and a real Logitech id, so: personal use only. To make it honest instead, change the five kUsb* constants in src/main.cpp — nothing else depends on them.

What is never stored: keystrokes, characters, key names, SSIDs beyond the configured one, client addresses, or anything else about what was typed. Counters only (keys, chords, dropped, and typed/typing for the paste path), which is what the status display needs to be useful. A run of pasted text exists in RAM from the moment a frame is accepted until the last character is typed or the run is cancelled, and nothing about it survives that — no queue across a disconnect, no place to write it. The board has no clock it trusts and no filesystem it writes to. Turning this into a logger would be a fork, not a feature flag.

---

Linux notes (the target and the laptop)

Ctrl+Alt+Del on a Linux target can reboot it. On the graphical session it is usually inert; on a virtual terminal systemd maps it to ctrl-alt-del.target, which by default reboots the machine (seven CAD presses in two seconds force it). This is why the combination is a button with a two-press confirm and a 3-second window, never a forwarded keypress, and why relayctl cad refuses to run without --yes.

Ctrl+Alt+F1…F7 works — which is a bigger deal than CAD: it switches the target's virtual terminal, and a getty on an unused VT with autologin enabled will hand you a shell as that user. This project puts the VT switches on the special-keys pad so they are deliberate clicks rather than a chord you can fat-finger.

Alt+SysRq+b etc. are reachable too (the magic SysRq key is off by default on most distros). The pad does not offer them; the keyboard table can produce them, which is what a keyboard is.

Keys the laptop's OS steals (this is the laptop side, and it is the browser-capture limitation, not a bug): Ctrl+Alt+Del, Ctrl+Alt+F1…F7, Alt+Tab, Super, PrintScreen, and on GNOME/KDE a growing list of media and tiling shortcuts are grabbed by the compositor and never reach the page. Three answers, in order of preference:

1. the special-keys pad on the page — each of those is one deliberate click, and the board synthesises the chord so the laptop never sees it;
2. run the laptop's compositor in a mode with fewer grabs while you work;
3. the OS-wide capture client (see Backlog) — an evdev reader on the laptop that forwards everything before the compositor gets it. The protocol is already designed for it; it is a client-side addition, not a firmware change.

While armed, the page swallows everything with preventDefault(), so Ctrl+W will not close the tab, Ctrl+R will not reload it and F11 will not fullscreen it. It also means you cannot type into the page's own fields while armed — disarm first.

While the pointer is captured, Esc belongs to the browser. That is the point: it revokes Pointer Lock, the page sees pointerlockchange, and every button goes up. What it cannot do is disarm the bridge — the keyboard is still armed and still typing, so the status line says so and you can press R or the board's button. Nothing else the laptop's compositor grabs takes the pointer away: Super and Alt+Tab are inert while locked, which is another reason capture is the design and a plain mousemove relay would not be.

The laptop's own pointer settings apply to what gets forwarded. Acceleration, libinput Accel Speed and a high pointer speed on the laptop mean the same hand movement sends different deltas going out, and the target then accelerates them again. Set the laptop's pointer speed to the middle and disable acceleration while steering something you cannot see the response curve of; the target's speed is what it is.

---

Layout caveats

KeyboardEvent.code names a physical position on a US-ANSI keyboard, and those positions are what travel as HID usage ids. If the target is set to a non-US layout, KeyQ still means "the key left of A" and the target maps it to whatever its layout says. This is identical to what a physical KVM does, and the fixes are the same:

• set the target's layout to English (US) — the one-line fix;
• or remap CODE_TO_USAGE in src/web_page.h for your laptop's board (it is one object literal; tools/relayctl.py carries the same table and tests/test_relayctl.py fails if the two drift).

The pointer is relative, on purpose. The board reports a boot mouse: buttons, ±127 per axis per report, wheel and horizontal pan. It does not know where the target's cursor is, and the target will not say, so there is no "move to" and no way to desynchronise — the same property that makes S= the right model for keys. Two consequences to know before you depend on it:

• Acceleration is applied twice, once by the laptop's driver before the page sees the movement and once by the target's driver after the board sends it. The deltas that leave the page are the laptop's, not your hand's, and the cursor moves by the target's idea of those. Fine for steering; not fine for a pixel-exact drag.
• The target clamps at its screen edges, and the board cannot see that happen. Moving 5000 px right from the far right of the screen does nothing, and the board has no way to know. This is why mouse move exists as a verifiable primitive and no macro of movements is ever stored: relative motion is only meaningful while a human is watching the screen it lands on.

ISO keyboards: IntlBackslash (0x32) is the extra key next to Left Shift on ISO and Backslash (0x31) is the ANSI one; both are in the table. AltRight is AltGr and travels as its own modifier bit, which is what layout engines on the target expect.

Pasted text goes through a third table, strokeFor() in src/text.h: character → modifier + usage, US-ANSI, and deliberately not position-based, because what is being pasted is characters. Same caveat, same fix — the target must be on a US layout. A character with no entry is refused (E9) rather than approximated, and test_text walks the entire printable range so an omission cannot hide, while test_relayctl proves the tool's validator and the board's map accept exactly the same 128 codes.

---

Controller page

Served by the board from flash (src/web_page.h, 59 262 bytes — the exact count .agents/validate.sh prints on every run, and the device-side measurement is curl -sk https://keyrelay.local/ | wc -c against that number: on a board flashed from this tree the two must be equal, and a mismatch means the flash is stale (the last runs and the open device leg are recorded in .agents/HW_VERIFICATION.md); no CDN, no fonts, no framework, nothing external — a keyboard bridge must work on an airplane and on a network that is down). Its script is executed by tests/test_page.js, because a C++ raw string is invisible to every compiler and a typo there fails in a browser, with a target live. The page carries exactly one byte-of-build-identity: a 19-character #if KR_TLS marker (var KR_TLS_BUILD=1; / …=0;, equal lengths, so the served page is the same size in either build) that lets the TLS build's page refuse an http:// origin before any socket exists — refusing to type a passphrase into a page that arrived in the clear, while the rollback build keeps its ws://.

The layout works for a laptop and a phone held in one hand over a target you are standing at: one breakpoint (max-width:720px) forces a single column with tighter padding and turns the ARM bar sticky — main switches to a flex column there, because position:sticky on a grid item is pinned inside its own grid area and would never actually stick. A pointer:coarse query puts every press target on a 44 px thumb floor (chord buttons and checkboxes get the matching width floor, and so does a <summary>) and leaves the dense laptop page untouched. That last one was a bug, not a detail: the fold's summary is the only route to five of the page's safety sentences and it rendered 17 px tall, while every byte-level layout assertion stayed green — see bug 14. A floor asserted in the served bytes can still miss a control nobody named, so the thumb floor is measured in a real browser at 360 px as well as pinned in tests/test_page.js (the run is recorded in .agents/HW_VERIFICATION.md); inputs never render below 16 px because iOS Safari zooms the page on focusing a smaller field and never zooms back out; the log caps its own height (max-height + overscroll-behavior:contain, so scrolling the log cannot scroll the page out from under the ARM bar); and viewport-fit=cover plus env(safe-area-inset-bottom) padding keeps the last card clear of the home indicator. At the breakpoint the State card's counters stop stacking into eight rows and wrap into a couple of lines instead — they stay visible, because they are the "is it typing" evidence — and the Log card's option row tightens so that card is two lines: the options, then the log. Pinch zoom stays enabled — the viewport never sets maximum-scale or user-scalable=no; a thumb floor must not be paid for with zoom. Every one of these claims is asserted by tests/test_page.js against the served bytes: a missing breakpoint fails silently in the browser — it just renders the laptop layout onto a phone — so the byte-level check is where it can be seen without one.

Most of the reading is behind a tap, and that is all that moved. Each long paragraph is now a one-line summary plus a <details> — the chord/"why are these buttons here" reason, the passphrase paragraph, the forwarded-mouse paragraph, the paste paragraph, and the footer's shortcut list. <details> rather than a help modal or a tour: zero script, keyboard accessible, printable, works with JS off, and it degrades to visible text in a browser that ignores it, which is the safe direction for a safety note. The arming banner is the one paragraph never folded — a warning you have to tap to see is a warning you can arm without, and tests/test_page.js asserts the banner sits before every <details> in the page. Every safety sentence is pinned there too, matched as text read out of the served bytes (tags stripped, entities decoded, whitespace collapsed, so a rewrap cannot break a check and neither can moving the sentence into a fold): that arming forwards every key including Enter to the machine the board is plugged into; that nothing is forwarded while disarmed and that reload, focus loss and socket loss restore that; that Esc frees the cursor and lets go of every button, and that Esc never reaches the target; that restating the button byte is what stops a lost frame sticking one; that stop typing abandons the rest of a run; that characters are positions so the target must be on a US layout; that no history and nothing is saved and nothing scheduled — with the default-passphrase shout pinned as what the board drives (dflt:1, rendered onto the arming banner) rather than as static text, and with the Ctrl+Alt+Del reboot warning pinned where it is actually said. These assertions passed on the page before the fold (proving the sentences were there) and after it (proving the fold kept them), and each one was demonstrated to fail when its sentence was deleted. That is the whole point of pinning them: a page that reads as a wall of text invites the edit that removes a warning — and this page has just been shortened, so the tests, not a reviewer's memory of what a sentence was for, are what say no to the next one. Cutting the multi-sentence title tooltips (which restated the same manual, and which are a tooltip rather than a manual) is why the served page got smaller even though every pinned safety sentence survived word for word.

element	why it is there
big ARM/DISARM bar	the state must be unmissable; it only changes when the board confirms. On a phone it is sticky — pinned to the top of the scroll — because armed-or-disarmed is the one fact that must survive scrolling; a state you have to scroll up to read is a state you press blind
red page border + red LED while armed	two independent indicators of the same fact
status pills: network / target / link / armed / caps-num / mouse / tls	"will my keystrokes land, and where", whether the pointer is yours right now, and whether the channel is encrypted (tls vs plaintext, from the status frame — not from what the page hopes). The link pill has three honest states: linked, link down, and held by another controller — from the status frame's busy, never from a guess, and never saying who
certificate line in the Connection card	the board's own fp from the status frame, verbatim, plus where to confirm it (cert on the serial console). Rendered only when the frame carries TLS and a fingerprint; the page invents nothing
"This page arrived in the clear" banner	a TLS build's page on an http:// origin — bytes no TLS board ever served on :80 — disables the passphrase box and the connect button outright and says why, rather than collecting a secret it cannot protect
take over (beside the passphrase field, visible only when the board says it is held)	the accident this is for: a session left connected somewhere else. The button appears only after the board said so — un-adopted claim, busy status frame, or the E12 that says this session was displaced — and one click sends T then X and nothing else. The incumbent is told, the release funnel runs, the board lands disarmed, and the page that lost the bridge stops reconnecting until a human clicks again: auto-reclaim is how two tabs become a fight
Ctrl+Alt+Del with two-press confirm	the OS eats the real one; on Linux it reboots
VT1–VT7, Alt+Tab, Win, PrtSc, Menu	the chords the laptop's compositor steals
⇦ snap left / snap right ⇨ / ⛶ fullscreen	Super+Left, Super+Right, Super+PageUp — KDE window management, sent by the board so your laptop does not answer it with its own windows
Release keys and Ctrl+Alt+Esc	panic: every key up, disarm
stay armed if this tab loses focus	off by default; for the one workflow that needs it
Send text box, its button and its stop typing	paste something and have it typed as keystrokes; the button says how many characters, refuses to be armed-into accidentally, and is the only path text takes
drop characters I cannot type	off by default: a paste that quietly loses a character is worse than one that refuses
capture the pointer and the mouse pad	the pointer half of the bridge. Capture asks the browser for Pointer Lock, so the cursor cannot escape the tab while forwarded; the one line under the pad says movement is relative and Esc frees it, and how a forwarded mouse behaves is the <details> under it
the folded <details> notes (Special keys, Connection, Mouse, Send text, footer)	one line where you act, the reasoning one tap away — and every safety sentence inside them is asserted against the served bytes by tests/test_page.js, so folding is not the same as losing
Release buttons under the pad	panic for the pointer, separate from the keyboard's because the two fail independently — held-button-then-lost-link is the mouse's stuck-key, and it is the same one release funnel
held-keys readout and the mouse line under it, keys/chords/text/chords/mouse counters	so "it is typing" and "it is moving" are facts you can see; the mouse line names the buttons held and the button byte, because "left is down" and "the target has 0x01" are different claims and only the second one is on the wire
log, log each key sent, clear	the board's errors verbatim plus one line per key pressed — never one per release, never a blank line, and a repeating line is counted rather than stacked

The caps/num indicators are read from the target (its HID output reports drive them), not guessed — a caps-lock desync between controller and target is a real failure mode of remote keyboards and this design cannot have it. The mouse counters are read from the board for the same reason: mframes counts the reports the board accepted, which is the number watch_target.py on the target can be compared against.

What capture does and does not do. The pointer is captured only while the bridge is armed, and only after a click; Esc, blur, a hidden tab, disarm, R and the board reporting it cannot do mouse reports (boot protocol, or mouse off) all end it, each releasing the buttons. The page never accumulates movement to send later: if the link is down, movement is dropped, because a queue of pointer motion delivered after you stopped moving is the pointer version of a stuck key. mouse frames 0 in the status line while you are moving means the frames are not getting there — that is a fault to look at, not noise, so it is shown rather than smoothed.

---

Wire protocol

One WebSocket text frame = one command. ASCII, no JSON inbound, trivially hand-typed, and impossible for one malformed field to desynchronise what follows it.

dir	message	meaning
c → d	T<token>	authenticate; must be first (kAuthTimeoutMs = 5 s)
c → d	H	hello: status now
c → d	A1 / A0	arm / disarm
c → d	S=<mods>:<u>,<u>…	the complete key state
c → d	C	Ctrl+Alt+Del (fixed in firmware, not read off the wire)
c → d	Y=<mods>:<u>,<u>…	one synthetic chord, kChordHoldMs (40 ms)
c → d	P=<ms>:<hex>	type pasted text, <ms> ms per character (0 = board default)
c → d	M=<btn>:<dx>:<dy>:<wheel>:<pan>	the complete mouse button state plus this report's relative movement
c → d	R	release every key and every mouse button, stay armed — and drop a text run in progress
c → d	K	keepalive
c → d	X	claim this bridge for myself — honoured only on an authenticated pending claim: the incumbent is told (E12), the release funnel runs, the board lands disarmed, then the claimant is adopted. From the incumbent controller it is a no-op answered OK (you already hold it)
d → c	OK	accepted
d → c	E<code>:<text>	error (codes below)
d → c	S{json}	status, 1 Hz and on every change, incl. typing = characters of the run still to type, busy = a controller holds the keyboard (to a /status poller, someone else; to the adopted controller, itself — a link state, never an identity), tkov = completed bridge handovers (a count of events, never who or from-where), tls = the board holds a working TLS identity, fp = the first 8 bytes of its SHA-256 in hex

The transport is wss:// on :443, and that is the only thing TLS changed about this table. Every frame above is the same bytes in the same order — the phase that encrypted the channel deliberately did not touch the protocol, so a controller written before it still parses and every host test still means what it meant. What is different is that T<token> no longer crosses the network in the clear: on a TLS board the first thing anybody else can read about a controller is that a session exists. A plaintext socket is refused rather than accepted: the rollback build is the only thing that will ever take a ws:// upgrade on :80, and here that upgrade is answered 426 Upgrade Required before a frame is read. So a session that is typing has never been plaintext by accident, in either direction.

The status frame is rendered by src/status.h — a pure module, so the whole frame including the kStatusJsonCap arithmetic is measured on a host (test_proto) instead of discovered on a device: a frame that would not fit renders as nothing rather than as half a status, and fp is cut at the first non-hex byte so a stored value cannot forge a field.

<mods> is the modifier byte as two hex digits, <u> a HID usage id as two hex digits. Both are strict: exactly two hex digits, no spaces, no trailing comma, usage 00 is not a key, and a rejected message leaves the previous state in force — the safe outcome.

S= carries state, not events. S=00: means "nothing is pressed". A press and its release are two frames and therefore two HID reports, so a fast tap cannot vanish; identical consecutive reports collapse, which is what keeps the queue short. A single message resynchronises the target completely, which is why no key can get stuck.

M= restates the buttons and carries one report's movement. <btn> is the button byte as two hex digits — 01 left, 02 right, 04 middle, 08 back, 10 forward, and any combination — and is the whole button state every time, exactly like S=. A frame that lifts one button restates the ones still held; there is no button-up event to lose, so no button can get stuck on the target. The four signed decimal fields are this report's movement, each ±127 (kMouseDeltaMax, the boot-mouse byte), and all five fields are required — M=01 is E6, not "left, no movement", because a controller that forgot three fields is a controller whose next frame is also wrong. Movement is the one field that is not state: losing a frame moves the cursor slightly less and leaves nothing behind.

The page chunks movement to 127 per axis and keeps the diagonal shape (a 200×200 move leaves as 127,127 then 73,73, never as two axis-parallel legs), so a fast flick cannot turn into a silently clamped one, and it flushes the pending movement under the old button state before restating a new one — that ordering is what makes a drag a drag.

P= is text, typed by the board. <hex> is the bytes to type, so one frame carries at most kTextFrameMax (120) characters and a longer paste is several frames; <ms> is the pace asked for, and the board keeps it — expansion and timing live on the USB side because a controller's clock, arriving over WiFi in whatever order the network delivers it, is not a keyboard timing source. Each character is pressed and released on top of whatever the operator is physically holding, and released back to it, so a paste can neither let go of a held key nor strand one. The board answers E9 for a character the US-ANSI map cannot express and types none of the frame, rather than sending a paste that quietly lost one; E8 means it already holds kTextJobCap (2048) characters. A controller sends the next frame when the status says typing: 0 — the board's own count, not a guess at timing.

Error codes: 1 not authenticated · 2 locked out · 3 another controller holds the bridge (your claim found no room) · 4 not armed · 5 no USB host attached · 6 bad message · 7 queue overflow (released and disarmed) · 8 text buffer full · 9 a character with no US-ANSI keystroke · 10 the mouse interface is off on this board · 11 the target chose HID boot protocol, so no mouse report can be sent safely · 12 your session was taken over by another controller — you were dropped, which is a different sentence from 3's "refused": one of them should be alarming on your screen and the other should not.

10, 11 and 12 are two digits, which changed the encoder: formatError used to emit E + code % 10 and would have rendered both of them as E0: — a refusal that names nothing. Codes now render in full, every single-digit code byte-identical to before, and clients read the code up to the first : rather than assuming one character — the controller page's single-character read turned E10/E11 into a bogus "E1: no passphrase" and would have hidden E12's reason inside the same misread; the page now parses to the colon, like the protocol says.

The refusals that are not E<code> live at the HTTP layer, because they happen before a WebSocket exists: 401 for /status without the passphrase; 503 (and E3, for a client that maps status codes to them) on a /ws upgrade that cannot be accepted as the board's one pending claim — a malformed upgrade, or a second claimant when the one claim slot is already filled. The first claimant's upgrade now succeeds (101) and authenticates, and what it may then do is wait, keep itself warm with K, or send the one deliberate X -- never anything that arms, types, or disturbs the incumbent (Security model); 404 on an unknown path on :443. And on the plaintext port, 301 for a page request — a Location pointing at https:// the same address and nothing else — plus 426 Upgrade Required for a /ws upgrade or for any request carrying ?token=, which is refused rather than redirected precisely so the passphrase is not echoed a second time on the wire the redirect is escaping. All of it is src/conn.h's plaintextRoute(), one table, consulted in one place, and compiled away by the rollback. See Security model.

The same protocol is what a future OS-wide capture client would speak — see Backlog — which is why it lives in src/proto.h instead of inside the server.

---

Serial console

/dev/ttyACM0 is the CDC half of the same composite USB device, so the console appears on whatever machine the board is plugged into:

python3 tools/console.py                      # interactive, Ctrl-] to quit
python3 tools/console.py /dev/ttyACM0 status  # one command, print the reply

command	effect
status	the same JSON the controller gets, plus link, queue and text-run state (text N chars typed, M still to go)
wifi <ssid> [passphrase]	station network to join (stored in NVS, reconnects)
wifi clear	forget it; the access point becomes the only way back
ap auto|force|off	AP policy: when the station is down / always / never
token <passphrase>	control passphrase, 6–32 chars, never echoed back
cert	the TLS certificate: SHA-256 fingerprint, validity window, and the names it carries — and a warning when the stored certificate does not actually contain that extension, so the list is this build's table rather than the certificate's. Never the key, never the PEM body — there is no argument form that writes an identity and no subcommand that reads one out
arm / disarm	same as the button
mouse on|off	whether the bridge enumerates a pointer interface at all. Stored, and it needs a reboot: the composite descriptor is fixed when USB starts, so this cannot change under a live target. Off means the pointer cannot be moved by anything, ever, until it is turned back on
reboot, help

status also says which of the two the running bridge is, and why: a line like mouse interface=present target=report protocol buttons=0x00 41 reports, 0 queued, where target=BOOT protocol (refused) means the target asked for boot protocol and the pointer is disabled by itself until it re-selects report protocol, and interface=off is the mouse off switch. The queue line reads queue 0 keys pending, 0 held, ok.

There is deliberately no command that types or clicks anything — the console is configuration, not an input path. That is why mouse on|off is the only mouse command and it changes a capability rather than performing an action. Replies are printed with a blocking write (the global serial timeout is 0 so logging into a port nobody reads can never stall loop()); without that, multi-line replies truncate at the 128-byte CDC TX ring, which is exactly what happened on the first build and is why pollConsole() bumps the timeout around each reply.

---

Architecture

src/
  config.h            defaults: network, timeouts, caps, buffers   (NVS overrides)
  keystate.h    pure   modifier byte + pressed-set -> 8-byte HID report, rollover
  mouse.h       pure   button byte + signed deltas -> 5-byte relative report; the
                       buttons are restated, not evented, exactly like keystate
  text.h        pure   pasted text -> US-ANSI keystrokes, paced; run buffer and cancel
  output.h      pure   the one place keystrokes, pasted runs, chords and mouse reports
                       become two ordered queues, and the one place anything is released
  proto.h       pure   the wire protocol: parse/render commands, constant-time compare
  status.h      pure   the status frame: StatusSnapshot and its renderer, the tls/fp
                       identity fields, and the SSID's JSON-boundary sanitising -- host
                       measured against kStatusJsonCap, which is why it is not in the server
  sha1.h        pure   SHA-1 + base64 for the WebSocket handshake
  ws_codec.h    pure   handshake request parsing + RFC 6455 frame codec
  claim.h       pure   the pending takeover claim (phase 03): the spare slot's role, the
                       ONE whitelist of frames a pending claim may have honoured (T, K,
                       and the deliberate X; arm/state/text/mouse/release refused by
                       name -- X only after authentication), and
                       its two-clock deadline arithmetic, as data a host suite walks
  tls_pem.h     pure   the TLS identity as strings: PEM armour in both directions, the
                       fingerprint's hex and the two shapes the console and the status frame
                       need (colon pairs, short label), the ONE table of names the certificate
                       is issued for, that table's SAN extension in DER *and the OID that
                       labels it* (sanOidDer -- DER content bytes, because that is what the
                       writer takes; the dotted string writes a well-formed certificate with
                       no SAN), the whole Extension SEQUENCE as it goes on the wire
                       (sanExtensionFullDer), derContains() and derCarriesSan() for checking a
                       claim against the certificate itself, and the validity-window arithmetic
                       over __DATE__ with its human-readable rendering
  tls.{h,cpp}          the mbed TLS half of the identity: secp256r1 keypair, self-signed
                       certificate, reparse-and-match check, fingerprint and validity of a
                       stored certificate, all behind KR_TLS (config.h; 1 is the default, 0
                       builds the plaintext rollback). main.cpp generates it on first boot,
                       keeps it in NVS and prints the fingerprint once
  tls_session.{h,cpp}  the TLS session: a raw-mbedTLS server session over an accepted fd,
                       handshake driven one call per tick with a kTlsHandshakeMs deadline,
                       non-blocking read/write with a strict same-buffer resume contract,
                       and an explicit slot-cap refusal (alert record, no context built).
                       Its POLICY half (deadline test, accept table, library-return table,
                       alert record, write queue, frame ring) is pure and host-tested; the
                       library half is compiled only where mbed TLS exists (KR_TLS &&
                       ESP_PLATFORM), which is what keeps the suite compiling without it
  conn.h        pure*  the transport view the routing sits on: one byte pipe with two
                       implementations (a WiFiClient, or a tls::Session) so serveHttp() and
                       serveViewer() do not know which they are talking to. Queued outbound
                       bytes (whole frame or nothing), a resumable pump capped per write and
                       per tick, and a flash body streamed through a bounded RAM chunk --
                       which is what lets a ~58 KB page leave across ticks on either
                       transport instead of in one call that can wait (the plaintext write
                       helper retries a blocking select ten times at one second each). Its
                       pure half also holds the HTTP response head, the `:80` answer table
                       (serve / 301 / 426), the redirect builder that turns a client `Host:`
                       into a `Location:` only when it is a name this board is reached at,
                       and the page send cursor (sent/total). `kr::Conn` itself is
                       ESP-only, like tls::Session; the tables are host-tested
  control_server.{h,cpp}  sockets: two listeners (:80, and :443 when an identity exists)
                       feeding ONE controller slot, ONE routing table and ONE transport view;
                       HTTP routes, WebSocket lifecycle, auth, heartbeat; `serveReadonly()`
                       is the only HTTP answer for either listener and either port, so the
                       encrypted and plaintext paths cannot disagree about what is served --
                       they differ only in that :80's answer is a redirect or a 426
  web_page.h           the controller page, in PROGMEM (59 262 bytes, with Pointer Lock,
                       the pinning banner and the take-over affordance; one #if KR_TLS
                       build marker, equal-length branches, assembled and size-pinned by
                       three separate test readers)
  main.cpp             glue: USB identity/HID composite, WiFi, chords, text run, the TLS
                       identity's NVS records, LED, button, watchdogs, serial console
tools/
  to_bootloader.py  1200-baud touch into ROM download mode (stdlib termios)
  console.py        serial console, one command or interactive (stdlib)
  relayctl.py       controller from a terminal: status/arm/disarm/release/cad/key/keys/
                    chord/listen/paste/mouse; pinned TLS by default (--fingerprint /
                    --ca / --insecure, refused without one), --plain for -D KR_TLS=0
                    rollback boards
  watch_target.py   on the target: decode the board's evdev events (keyboard *and*
                    mouse), prove delivery
  hw_probe.sh       what device context exists right now (serial nodes by stat only, mDNS,
                    http/https, uv, node, target evdev); informs, never gates, always 0
tests/
  run_tests.sh      builds and runs everything (host g++ or a local container)
  test_keystate.cpp test_mouse.cpp test_output.cpp test_proto.cpp test_text.cpp
  test_ws_codec.cpp test_tls_pem.cpp test_tls_session.cpp test_conn.cpp test_claim.cpp
  test_relayctl.py  test_page.js (node, skipped when absent)
.agents/
  PLAN.md           the roadmap and the decisions a phase may not move
  validate.sh       the gate the pipeline stops on: both suite runs, all three firmware
                    builds (bridge, console, the KR_TLS=0 rollback), the page byte count, the
                    numbers README/AGENTS quote, repo hygiene — no device, no upload, no network
  HW_VERIFICATION.md  the device half: every claim only hardware can settle, the command
                    that settles it, and the outcome someone actually observed
AGENTS.md           operating manual for whoever edits this next: the invariants, the tables
                    that must agree, the build traps, the verification standard
TODO.md             open items, kept with their root cause rather than deleted

If you are an agent or a new contributor, read AGENTS.md before changing anything: several rules here are invisible to a compiler and to the test suite at the same time.

The ten modules marked pure — plus conn.h, marked pure* because only its tables are — have no Arduino and no ESP-IDF include, so the identical code compiles and runs on a host under -fsanitize=address,undefined. That is not convenience for its own sake: the sanitiser caught five real defects in the frame decoder before the first flash (a reset() that left the reader latched on the previous frame, an unsequenced _buf[_got++] = b ^ _mask[_got & 3], a missing FIN check that silently accepted fragmentation, a mask key skipped on zero-length frames, and a "sec-websocket-key:" prefix compared at the wrong length so the accept hash was computed from "ey: …").

The keystroke path, end to end:

keydown/keyup -> full state S=.. -> Reader (RFC6455) -> proto::parse -> auth gate
  -> KeyboardState::apply (dirty only if the report changed)
  -> ReportQueue (dedupe identical, overflow = release + disarm)
  -> drainReports: tud_hid_n_ready(0) ? USBHIDKeyboard::sendReport : keep queued
  -> HID interrupt endpoint, boot protocol, 8-byte report -> target

pointer move  -> M=btn:dx:dy:wheel:pan  -> same gate (armed + attached + mouse allowed)
  -> MouseState::apply (button byte restated; idle frames produce no report at all)
  -> a second ReportQueue, same dedupe and the same overflow rule
  -> drainReports, after the keyboard queue -> report #2 on the *same* HID interface

fail-safe (any of: disarm, R, blur, silence, detach, suspend, overflow)
  -> releaseEverything() -> OutputStage::releaseAll()
       clears both queues, both trackers, the chord and the text run, THEN queues
       all-keys-up and (if the target can take it) all-buttons-up

USBHID::SendReport in the core is synchronous (it waits on a semaphore for the transfer to complete, up to 100 ms), so drainReports() takes at most kMaxReportsPerLoop = 8 reports per pass across both devices — bounded time in the USB path, and the control plane never waits on it.

Both devices live on one HID interface, which is a constraint with three consequences. The keyboard's USBHIDKeyboard is the first HID instance, so it claims the boot keyboard subclass; the mouse is added as the second report on that same instance, which is why mouseDev is created after kbd and never before. Because the descriptor is written when USB.begin() runs, mouse off cannot take effect until a reboot. And because a boot-protocol host parses every report on that interface as an 8-byte keyboard report, a target that selects boot protocol gets the pointer switched off under it (E11) rather than sending 5-byte mouse reports that would arrive as garbage keystrokes. Chords (Ctrl+Alt+Del, VT switches) are synthetic: the press is pushed, and after the hold the tracked state is pushed back, so keys that were genuinely held before a chord survive it and the tracker is never corrupted by something the operator did not type.

The USB interface is confirmed boot-protocol on real hardware, which is the precondition for Windows accepting Ctrl+Alt+Del as the secure attention sequence:

$ for i in /sys/bus/usb/devices/*:1.*/; do echo "$(basename $i) class=$(cat $i/bInterfaceClass) sub=$(cat $i/bInterfaceSubClass) proto=$(cat $i/bInterfaceProtocol)"; done
7-1:1.0 class=03 sub=01 proto=01        <- HID, boot subclass, keyboard protocol
7-1:1.1 class=02 sub=02 proto=00        <- CDC-ACM control
7-1:1.2 class=0a sub=00 proto=00        <- CDC-ACM data

Three build environments, one flag apart. bridge is the real thing (USB-OTG + TinyUSB, TLS on). console is ARDUINO_USB_MODE=1: no HID, so it cannot type, but WiFi/page/WebSocket/ LED/button all live — for separating "the network side is broken" from "the HID side is broken" without rebuilding; arming refuses with E5 there, on purpose. rollback is bridge with -DKR_TLS=0: the plaintext pre-phase-02 control channel, kept buildable by the gate because it is the documented way back from a TLS problem and not a mode a live board can choose (src/config.h, README The rollback).

---

Tests

tests/run_tests.sh              # uses g++ if present, else a local container image
SANITIZE=1 tests/run_tests.sh   # + ASan/UBSan  (recommended, and what found 5 bugs)
bash .agents/validate.sh        # the gate: both runs above + all three firmware builds
                                # (bridge, console, the KR_TLS=0 rollback) + the page's byte
                                # count + the numbers README/AGENTS quote + repo hygiene,
                                # and never a device, an upload or a network fetch

suite	checks	what it pins down
test_keystate	40	idempotence, transition preservation (a fast tap is two reports), 6-key limit, ErrorRollOver and recovery from it, dedupe, clear(), the exact Ctrl+Alt+Del bytes 05 00 4c 00 00 00 00 00
test_mouse	48	the 5-byte report layout, every button bit where the HID spec says it is, idle frames producing no report, a button change with no movement still producing one, the button byte being restated rather than evented, releaseAll being idempotent, and that no frame can put a value outside one signed byte on the wire
test_output	153	the release funnel. Queues hold their order and collapse duplicates; releasing with keys held queues an all-keys-up report when there is a target to receive it; releasing drops a press that was queued but never sent; releasing with a mouse button held queues all-buttons-up; boot protocol or mouse off means no mouse report is queued but the key release still is; a pasted run and an in-flight chord are both cancelled; and overflow is detected on both queues. Regression-proven: reinstating the old releaseEverything() fails 23 of these
test_proto	2379	every command form including X (the takeover: parsed alone, Bad with any trailing bytes, and the exact claimant-side frame run through the firmware's own parser), strict rejection of malformed state specs, bounds (cap on keys, token length and text frames), render/parse round-trip, error framing (including all three two-digit codes -- E12 renders at full width so the dropped incumbent reads "taken over", never a truncated E1), constant-time compare, every chord button's bytes matched against the label printed on it, the page's text constants pinned to config.h, every M= frame rendered from every button bit against the full signed-byte movement range parsed back to the report it claims, and the status frame: tls/fp rendering, the busy/tkov pair that says a bridge is held without ever saying by whom (a link boolean and a counter; the fields carry no address, agent or peer, and walking them is what makes the next "just add the client IP" a deliberate edit rather than a quiet one), fp empty whenever tls is 0 however the snapshot was filled, a non-hex fp cut at the first non-hex byte so it cannot forge a field, SSID sanitising, and the longest frame the board can legally send (349 bytes, busy set and tkov at UINT32_MAX) asserted to fit kStatusJsonCap with a field's worth of headroom -- and to render as nothing one byte short of what it needs
test_text	459	the whole printable-ASCII map walked (nothing may be unmapped, nothing may claim a key it has no glyph for), shifted glyphs and the digit row, what is refused rather than guessed at, all-or-nothing frame acceptance, pace arithmetic and clamping, the exact press/release report sequence for two characters, overlay on the operator's held keys, ErrorRollOver propagation, cancel, buffer-full, P= render/parse round-trip including the largest legal frame, and one end-to-end case that takes the exact frame the page sends and asserts the HID report sequence the target ends up seeing
test_ws_codec	135	SHA-1 against published vectors including the million-a case, base64 against RFC 4648, the RFC 6455 handshake example, frame encode/decode at the 125/126 and 64-bit boundaries, byte-at-a-time delivery, and rejection of unmasked, fragmented, reserved-bit, binary, over-long and oversized frames
test_tls_pem	862	the identity's strings, walked exhaustively (100 % of src/tls_pem.h): PEM armour against an RFC 4648 vector and line-by-line at 0/1/45/46/47/48/49 bytes and every 64-character boundary up to 704, the padded final group terminating its own line, a refusal (writing nothing) one byte short of cap, the armour read back through CRLF / missing-newline / stray-space shapes and torn or re-labelled blocks rejected rather than decoded, the fingerprint against the published SHA-256 of abc and refused at one byte short, the two renderings of it the board actually prints (the status frame's 16-character label, and the console's colon pairs -- rejoining the two printed lines reproduces the digest exactly, each line is short enough for the 128-byte CDC transmit ring, and a refusal writes nothing rather than half a fingerprint), derContains deciding whether a stored certificate really carries the SAN bytes this build writes (one changed byte anywhere, in the needle or in the certificate, stops matching), the name table pinned to kHostname/kApGw/kCertCommonName with the CN asserted to be kHostname + ".local", the SAN extension's 34 DER bytes (cross-checked byte-for-byte against what OpenSSL writes for the same three names), the OID that turns those bytes into a subjectAltName (06 03 55 1D 11, pinned as DER content bytes with an explicit check that no byte of the dotted text survives into what the writer is handed, and the whole 43-byte SEQUENCE { OID, OCTET STRING } pinned against the certificate OpenSSL issues for the same three names), and derCarriesSan answering no to the exact extension a live board produced before that was fixed -- the right value bytes under a mislabelled OID, which derContains still calls a match and no client does -- plus one mutated OID byte, value-without-OID, OID-without-value, and a haystack cut one byte short of carrying it, strict dotted-quad parsing, __DATE__ with its padded day, the leap-day + 10 years clamp, utcTime refusing every component UTCTime cannot carry, and dateTimeText rendering a validity bound for cert -- same component checks, deliberately without UTCTime's 1950..2049 window because reading a date is not the permission to write one
test_tls_session	118	the TLS session's policy layer, walked without mbed TLS (100 % of the pure half of src/tls_session.h): the handshake/stall deadline in its wrap-safe int32_t(now - start) > limit form including the 49.7-day millis() rollover and the exact-boundary case, the slot-admission table (controller, spare, refused) with the cap checked before the free slot and no transport parameter to consult -- the third connection is refused the same way whichever listener it knocked on -- kTlsMaxSessions pinned to the 2 the RAM arithmetic in config.h is written against, the library-return table that decides Bytes / Want / Closed / Error (a WANT misread as fatal drops working controllers on slow WiFi; a fatal misread as WANT spins the loop; the three error-code literals it branches on are pinned against the real mbed TLS by static_assert inside tls_session.cpp, so neither half can drift silently), the 7-byte fatal-alert record byte-for-byte against RFC 5246 -- including the description byte drafted once as 0x40 because forty, which is the entire reason a wire format gets its own test, never confidence -- and the frame ring's whole-frame-or-nothing push, wrap-span arithmetic and stable head (which is what makes re-handing identical bytes after a refused write possible at all), its default-constructed / unseated state -- cap coerced to 1, nothing accepted, no modulo by zero on the first tick before any socket exists -- and reseat(), because kr::Conn binds to a different transport between sockets and a byte left behind would be delivered to the new occupant. Task 04 deleted its WriteQueue (and with it the queue checks): the transport view queues head and body through the ring plus kr::FlashSend instead, so a second streaming cursor here would be exactly the second path this phase exists to remove
test_conn	280	the transport view's deciding half, walked without Arduino or sockets (100 % of the pure half of src/conn.h): the one HTTP response head -- exact bytes, Content-Length agreeing with the body, an extra header landing before Connection, a buffer too small refused with nothing written rather than a truncated block, and the widest legal response (a full dotted-quad authority plus /index.html) fitting kHttpResponseHeadCap with margin asserted rather than hoped for; the :80 answer table for both builds, including that -D KR_TLS=0 serves everything (the rollback criterion, expressed as a row) and that an upgrade carrying a token is answered as an upgrade; token= in a query detected at a key boundary and nowhere else (mytoken= is not the passphrase, &token= is) and never with the value copied; the redirect authority -- keyrelay.local, keyrelay and a private dotted quad survive and are canonicalised, while evil.com, keyrelay.local@evil.com (the shape of a real open-redirect URL), a public IP, evil.local, ::1, 300.1.1.1 and a 300-byte Host all fall back to the certificate's name; the redirect target carrying only / and /index.html and refusing a path containing a CR or LF that would inject a header into this board's own response; and the page send cursor -- 59 262 bytes drained at kPageChunkBytes per write and kPageBytesPerTick per tick, every byte of every piece checked against the source, the piece and tick caps asserted, and the resulting 41 chunks / 11 ticks pinned to config.h. Two defects in this code were caught by the sanitised run rather than by its assertions (a 6-byte key memcmped past the end of "a=1", and an octet counter that let "192.168.1.1.1" write octets[4]); both are pinned by the case that triggered them
test_claim	102	the pending takeover claim's predicates (src/claim.h), walked as a matrix: every proto::Cmd against both authentication states and both spare-slot roles -- unauthenticated a claim may send only T (the explicit cell that an X before the passphrase is refused: no promotion path without _claimAuthed), authenticated only T, K and the deliberate X (allowed exactly there, and named as the one act that handover runs through the funnel and cannot arm), with the refusals named one by one (arm, disarm, key state, Ctrl+Alt+Del, chords, pasted text, mouse, R, H) because that list is the reason "a pending claim can arm nothing" is checkable rather than believed -- one claim at a time; both clocks (the controller's kAuthTimeoutMs before authentication, kClaimTimeoutMs after) at the exact boundary and across the 49.7-day millis() rollover; and the claim's 64-byte frame budget measured through the real codec: the widest legal T<token> parses with room to spare, a frame at the cap completes, and one byte over it is an Err::TooLong refusal -- never a truncation, never an allocation
test_relayctl	308	the Python client's codec, that its key table has not drifted from the page's, that its text validator agrees with the firmware's character map on all 128 ASCII codes, CRLF normalisation, TEXT_FRAME_MAX/MAX_PASTE_CHARS pinned to config.h, the mouse frame builder refusing a sixth button and any movement that does not fit one report, movement splitting that reproduces the original displacement exactly, click/drag/wheel frame ordering, every generated frame parseable by the firmware's own parser, and the button bits and frame pace agreeing between page, tool and config.h. Its structural sections add handshake_refusal() -- so "the board wants TLS" (426) and "wrong passphrase" (401) are never the same sentence to an operator -- the bridge handover pins (the release funnel runs before the claimant is adopted; no arm/setArmed/armed = true is reachable from the X handler or from the controller-side no-op; claim::honours(_claimAuthed) is consulted before the Takeover branch and X lives in claim.h's authenticated branch only, so no promotion without the passphrase; E12 is the named code the incumbent is told with, distinct from E3), the one routing path, two transports pins described below, and the client side of pinning: select_transport() refusing no-trust-argument and mixed arguments and naming the way forward, the port table (TLS 443, --plain 80, explicit --port wins), fingerprints normalised from bare/colon/upper-case forms and refused at any other length or alphabet; and a fake board socket that records every byte this side sends, proving a wrong fingerprint aborts with nothing at all on the wire (not the upgrade, certainly not T<token>), that the right one puts the authentication frame first on the encrypted session, that --ca builds create_default_context with hostname checking ON and the chain REQUIRED while pinning shares the deliberate post-handshake DER hash, that --insecure warns on stderr every run, that --plain builds no TLS context and is the only path to :80, that $KEYRELAY_TLS_FP satisfies main()'s gate without a reachable board and the refusal never prints a credential, the busy board and --take-over (the fake board answers T as a controller -- OK plus the adoption status -- or parks the client as a pending claim: OK and the silence that means busy; so the default refusal names the flag and puts no X on the wire and frees the slot, the flag sends T then X in that order and nothing else, a free board gets a stated no-op with no X wasted on it, and through main() the whole gesture is T, X, then H -- claim, handover, status -- with the terminal told the board came back DISARMED and no credential printed), and that the token pre-flight and the paste --yes gate still run before any connection at all, and that every failure on the way to an authenticated session is named -- TLS handshake failure (with the wrong-port hint, never an invitation to use it), --ca verification failure (identity-rotation or wrong-device, the two real causes), a peer that shows no certificate, a wrong Sec-WebSocket-Accept, a header block that never ends, a board that hangs up mid-handshake. The page-bytes pin also assembles both builds' pages from the #if KR_TLS marker chunks and asserts the two marker branches are equal length -- three readers of that layout (here, test_page.js, validate.sh), so no build can serve a page nobody tested
test_page	220	the page's script, executed: blank and whitespace-only log lines never render and a repeating line is counted not stacked, character validation, CRLF, hex encoding, one frame for a short paste and exactly the right bytes, a busy board holding the next frame back, a 300-character paste reassembling to the text that went in, refusal of untypeable text and the opt-in drop, cancellation by stop/disarm, the mouse: capture requires the bridge armed, movement becomes exactly one M= per report with nothing sent when idle, a 400×300 flick split so no frame exceeds one signed byte while the diagonal shape survives, the click ordering that makes a drag a drag, wheel pixels quantised to notches with the remainder carried, Esc/blur/disarm each releasing the buttons, stay armed on blur exempting the keyboard only, a board that reports mouse:0 refusing capture and dropping one in progress — and every mouse frame the page emits parsed by the firmware's own parser, plus every element id the script reaches for checked against the markup, and the connect path: an https: origin builds wss://host/ws (an https: page opening ws:// is blocked as mixed content and looks exactly like a dead board), a TLS build's page on an http: origin opens no socket and sends not one frame and says "this page arrived in the clear; reload over https", boot() on that origin disables the passphrase box and the connect button and raises the banner, the rollback marker (KR_TLS_BUILD=0) still builds ws:// because that is the documented way back, no credential rides in the connect URL, exactly one new WebSocket( exists in the whole page, and the served bytes contain exactly one plaintext ws:// -- the rollback's path, reachable only from an origin a TLS board never hands out; and the channel pill and certificate line: tls/plaintext rendered from the status frame with the alarming colour on the alarming state, the line showing exactly the fp the frame carried and naming the serial cert command, rendering nothing when tls:0 (even if the frame carried an fp anyway) or when tls:1 brings no fp -- the page displays the board's bytes or nothing**; and the busy board and the take-over: busy drives the link pill's third state (held by another controller) while the adopted controller still reads its own busy as linked; an un-adopted claim close shows the take-over button and sends nothing on its own, with the reconnect loop off -- no retry fight; one click sends T then X in that order and nothing else, and the first status after it is logged as the DISARMED start it is; E12 disarms, releases the mouse, ends a typing run mid-frame, marks the pill taken over and stays down through the close (coming back is one deliberate click, never zero); and E3 keeps its separate meaning -- it disarms the ask, logs "no room for a claim", and does not claim anyone was displaced**; and the responsive layout: the viewport meta carries viewport-fit=cover (without it env(safe-area-inset-*) is always 0) and never disables pinch zoom; the one 720 px breakpoint forces one column and makes main a flex column -- the switch that makes the sticky ARM bar sticky for real, since a sticky grid item is pinned inside its own grid area; the 16 px input floor against the iOS focus-zoom; the log's max-height cap; the 44 px pointer:coarse thumb floors for buttons, pills and inputs (width floor on chord buttons and checkboxes); overscroll-behavior:contain on the log, touch-action:manipulation and user-select:none on the controls, calc(14px + env(safe-area-inset-bottom)) on main, the ARM bar still the first element in main, and the folded notes' <summary> on the 44 px thumb floor too -- it is the only route to five of the pinned safety sentences and it rendered 17 px tall while every other byte-level assertion stayed green, which is the clearest case in this file for measuring a control rather than naming it, plus the folded-at-the-breakpoint counters (kv wraps, the Log card's option row tightens) so the counters stay visible instead of stacking eight rows on a phone**; and the safety statements that must never be tidied away, matched as text out of the served markup (tags stripped, entities decoded, whitespace and case folded) so they survive a rewrap and survive moving inside a <details> but fail the moment one is deleted: the arming banner says every key, including Enter, going to the machine the board is plugged into, with the permission rule, and sits before every <details> on the page (a warning about arming is never one tap away from being unseen); nothing is forwarded while disarmed and reload/focus loss/socket loss are named as what restores it; Esc frees the cursor and lets go of every button, never reaching the target, and the restated button byte cannot leave one held down; stop typing/Ctrl+Alt+Esc abandons the rest of a run; characters are positions so the target must be on a US layout; no history / nothing is saved / nothing scheduled; that a takeover cannot arm it by doing so because every handover lands disarmed; the clear-loaded-page warning and the fix it names; the Ctrl+Alt+Del reboots a Linux VT warning where it is actually said; and the default-passphrase shout as something driven by the board's dflt flag onto the arming banner, with no static default-passphrase sentence in the markup at all. TEXT_FRAME_MAX/TEXT_JOB_MAX are re-pinned against config.h here as well (three readers of that arithmetic, none trusting the page's own copy); and arming and the state frames on the wire -- the half of invariants 1 and 2 that a markup restructure could move without a single word changing: an ARM click before authentication asks for nothing; the click sends A1 alone and A0+R (in that order) on the way out, and the page flips its own state only when the board's status frame says so, while a board-side arm is mirrored without any click; while disarmed a whole press forwards not even a restatement; every keystroke while armed restates the WHOLE state -- S=00: travels, keys-up is a state and not an absence of event -- autorepeat is not a state change, usages arrive in press order, a keystroke inside the page's own text box stays there but a modifier released above it is still let go, and Ctrl+Alt+Esc sends R then A0; every state frame the section emitted is the wire form test_proto parses; the folded notes are checked structurally too -- exactly five <details>, each with a summary that names what is behind the tap and real sentences inside it, so deleting or hollowing a fold fails the suite (folded is not deleted); and the id-coverage check proves it bites: an id handed to the shim that is not in the markup must be named by the very same comparison, so a broken matcher cannot read as green

The verifier is verified too, because twice now it was the verifier that was wrong: node classification (EV_REL means a pointing device — not the device's name, not the order the glob found them in), movement coalescing one report into one line, net displacement arithmetic, hi-res wheel events not counted as extra notches, and a stuck button being called out in those words.

A second pinned section, one routing path, two transports, does for the transport split what the fail-safe pins do for the release funnel: it asserts sentences no host test can execute and no compiler can see -- that readSome() stamps the controller-silence clock only for _phase == WebSocket && _authed (so a TLS handshake, a /status poll and a viewer refresh cannot hold a dead controller's armed state open), that the read-only slot never goes through readSome() at all, that exactly one formatter in src/ writes an HTTP status line, that serveReadonly() is reached from both slots and defined once, that the :80 table is consulted in exactly one place, and that the page's wss://-or-rollback-ws:// choice exists exactly once. It also pins the served page's byte count against the constant test_conn.cpp drains through the chunk arithmetic -- the same test the table, not your confidence in it rule as the mouse bits and the evdev codes.

Five checks in test_relayctl's the fail-safe wiring section are source pins, and the suite says so out loud: they assert that loop()'s silence disarm runs off controllerSeen() rather than linked() (and that nothing else gates it on the link still being there), that acceptNew() never stamps the controller clock, and that closeLink() stamps it only for a link that reached the WebSocket phase. They cannot execute — that code needs a socket and a board — but each one is a sentence a later edit can undo with no compiler error and no behavioural test failing on the host, which is exactly how bug 10 survived. Measured, not asserted: reinstating the linked() gate fails 2 of them, stamping in acceptNew() fails 1, reinstating the bug as it was fails 3.

Gaps, stated plainly: nothing here exercises real sockets, real WiFi associations, or real USB transactions — those are the end-to-end procedure below. control_server.cpp is still the least-executed part of the project, deliberately the thinnest layer, and task 04 narrowed what that means: the transport decision, the :80 answer table, the redirect construction, the response head and the page send cursor used to be lines in front of WiFi.h that only a device could prove, and they now live in conn.h where test_conn walks them — what remains untestable there is the socket plumbing itself and the auth lifecycle (the ordering of accept → handshake → upgrade → T= → close), which is why the sentences around it are pinned as source assertions. What it used to render is: the status frame moved to src/status.h so that test_proto can build one and measure it, which it could not do while the code sat behind #include <WiFi.h> — the frame's field list, its sanitising and its buffer arithmetic were previously verifiable only on a device. src/tls.cpp and the session half of src/tls_session.cpp are the same kind of gap on purpose: they are sequences of mbed TLS calls whose failure mode is an error code, so they are proven by the two firmware builds (the symbols resolve, both environments link) and by the device checks in .agents/HW_VERIFICATION.md, not by a host suite that would have to fake the library to run -- which is also exactly why every decision those calls make (deadlines, admission, return-code meaning, buffer-resume bookkeeping) was pushed out of them into pure, host-tested helpers in tls_pem.h and tls_session.h. The one thing a host build cannot establish — that a section nothing yet calls still has every mbed TLS reference it needs — was settled by a throwaway link with -Wl,-u, forcing those three functions to survive garbage collection.

The gate also checks two things in the other direction, because a build that succeeds proves nothing about a build that is supposed to disappear: -e rollback has to link (-D KR_TLS=0 is the documented way back, so it is built on every run), and the image it produces carries no mbedtls_ssl_* symbol at all — 0 against 115 in bridge, by nm, quoted under Measured behaviour. And since this README is the source of truth for behaviour, the gate compares the numbers it quotes against the commands that produce them: the check count in this table, the page's byte count, a Backlog numbered 1..N with nothing closed left inside it, and the rule that any line naming a plaintext ws:// must name the rollback build on that very line, so no sentence can be read as if plaintext were the default.

---

End-to-end verification

Three machines' worth of roles on two boxes: the laptop is the controller, the board is the bridge, and any Linux box (including the laptop itself) is the target.

# 1. on the target: what actually arrived, decoded from evdev, focus-independent
python3 tools/watch_target.py --seconds 60

# 2. on the laptop: drive it from the terminal
export KEYRELAY_TOKEN='the-passphrase-you-set'
export KEYRELAY_TLS_FP='<the 64 hex digits `cert` printed>'   # the pin; --fingerprint works too
python3 tools/relayctl.py --host keyrelay.local status
python3 tools/relayctl.py --host keyrelay.local arm
python3 tools/relayctl.py --host keyrelay.local key Enter
python3 tools/relayctl.py --host keyrelay.local chord 04 2b      # Alt+Tab, by hand
python3 tools/relayctl.py --host keyrelay.local cad --yes
printf 'Hello from keyrelay\n' | \
  python3 tools/relayctl.py --host keyrelay.local paste --yes    # 19 characters
python3 tools/relayctl.py --host keyrelay.local listen 20      # heartbeats, live
python3 tools/relayctl.py --host keyrelay.local disarm
python3 tools/relayctl.py --host keyrelay.local --take-over status  # take a bridge a forgotten tab still holds (lands disarmed)

# 3. the mouse, same two terminals
python3 tools/relayctl.py --host keyrelay.local mouse move 120 -40
python3 tools/relayctl.py --host keyrelay.local mouse click --yes
python3 tools/relayctl.py --host keyrelay.local mouse wheel -3
python3 tools/relayctl.py --host keyrelay.local mouse drag 200 0 --button right --yes
python3 tools/relayctl.py --host keyrelay.local mouse release

.agents/HW_VERIFICATION.md is where the outcome of each device claim gets recorded, with the command that was run; bash tools/hw_probe.sh says, cheaply and before you try, whether a board is reachable at all. Both obey one rule: a device step is attempted once, capped with timeout, and the outcome is written down — ok, skipped (no device) or failed: …. Nothing here loops on a port, reflashes to see if it works, or belongs in .agents/validate.sh, which stays device-free so a gate never fails on the schedule of whoever is not holding a board.

And in the browser, which is where the pointer is actually usable: open the page, arm it, press capture the pointer, move the mouse (the target's cursor moves, the laptop's is hidden), hold left and move for a drag, press Esc. Then arm it, capture, hold a button, and close the tab — the target must stop clicking within 8 s of the silence timeout.

And the bridge handover — the one claim that needs two controllers, and the only ordering claim in this file: the incumbent's key must come up before the newcomer's first key reaches the target. Terminal A watches the target; terminal B holds the bridge with a key pressed and held; a third controller — a phone page, or a second terminal holding the same passphrase — takes it:

# A. on the target, left running: what actually arrived
python3 tools/watch_target.py --seconds 120

# B. on the laptop: hold the bridge and press-and-hold a key long enough to act against
python3 tools/relayctl.py --host keyrelay.local arm
python3 tools/relayctl.py --host keyrelay.local key KeyA --hold 30000

# C. while B still holds it: the deliberate act. On the phone, open the page and press
# TAKE OVER once the pill says "held by another controller"; from a terminal:
python3 tools/relayctl.py --host keyrelay.local --take-over status

What must appear, in this order: A shows A press (B's held key), then A release caused by the handover — and nothing from C before it, because C's session starts disarmed and types nothing until it arms on purpose. C's own output says the bridge was taken and the board came back DISARMED; the status it prints reads armed: 0, busy: 1, tkov: 1. B is dropped with E12 mid-hold; a browser tab in B's seat marks its pill taken over, logs "another controller took over", releases its mouse, and stops reconnecting. If A release ever appears after C's first key, or C is armed without having sent its own A1, the funnel moved after the adoption — on the host that same ordering is pinned by the bridge handover section of tests/test_relayctl.py.

What a correct run proves, and how to tell:

claim	evidence
HID reaches the host	watch_target.py prints every press/release with a timestamp
text is correct	its typed line, with case from the shift state
Enter works	Enter press/release and <Enter> in the typed text
Ctrl+Alt+Del works as a combination	>>> Ctrl+Alt+Del <<<, one line, not three
no stuck keys	still held is absent at the end of the run
pasted text is keystrokes, not a shortcut	the run's typed line reproduces the text, and the press count is roughly twice the character count — a paste that arrived as nothing, or as a single odd chord, means the character map or the pace, not the target
Alt+Tab is Alt+Tab	LAlt press then Tab press — and not LCtrl. This combination was Ctrl+Alt+A on the wire until it was caught by the label-vs-bytes test; watch_target.py is what settles any doubt about which keys the board actually sent
a paste stops	start a long one, press stop typing (or blur the tab, or press the board's button): the typed text stops mid-sentence and nothing further appears
target LEDs are read back	LED CapsLock on on the target, caps indicator on the page
silence disarms	arm it, close the tab, wait 8 s, status says armed: 0
auth is real	relayctl with a wrong token fails; the board logs authfails=1; 5 tries → E2
a takeover releases before it adopts	in watch_target.py, the incumbent's A release appears before anything from the new session — the newcomer starts disarmed and types nothing until its own A1; the taker's status says armed: 0, busy: 1, tkov: 1; the displaced page's pill says taken over, its log says "another controller took over", and it does not reconnect
movement reaches the target as movement	watch_target.py prints a movement dx … dy … line per report and the summary's net position matches the direction and rough distance you moved — the keyboard half of the watcher cannot show this, which is why the mouse node is watched separately
the button bits are the buttons they claim to be	mouse click --yes gives BTN Left press/release; --button right gives BTN Right. A button that arrives as the wrong one is a bit-order bug and looks identical from the page
a drag is down, move, up in that order	BTN Left press, then movement lines, then BTN Left release — any other order is a drag that clicks at the start and drags nothing
no stuck buttons	still held absent from the mouse summary at the end. Check it the hard way: hold a button and close the tab
the wheel is notches, not pixels	mouse wheel -3 produces REL_WHEEL -3 three times, and hi-res events do not inflate the count
boot protocol refuses the pointer, not the keyboard	on a BIOS/KVM that selects boot protocol, keys keep working and M= answers E11; console.py status says target=BOOT protocol (refused)
mouse off really removes the capability	console.py mouse off + reboot → lsusb/evdev show no pointing device, watch_target.py notes the missing interface, the page's Capture button is disabled, and keys still work

watch_target.py finds the board by USB id, not device name, so it keeps working on a different port or a renamed input node, and it accepts both the Logitech identity and the Espressif default so it works on older builds.

A pasted run prints one line per press and release, so a few hundred characters is a lot of scrolling: watch the key presses and typed summary lines at the end rather than the stream, and give --seconds enough room for the pace (2048 characters at the default 12 ms is about 25 s of typing, plus the run's own margins).

---

Measured behaviour

On real hardware: AtomS3 Lite → this laptop (Linux, US layout), board on the same WiFi, firmware 1.0.0, bridge environment. Fill in / re-run after any change to the keystroke path; the numbers below are the shape a correct run has. (Those frames predate the TLS identity: a status frame from a phase-02 board carries tls and fp as well, and a phase-03 board adds busy and tkov — the link state and the handover count, and never an identity — while its serial link line ends with taken=. cert exists and has been confirmed against the live handshake — the pinning rows below — but the status fields themselves and the keystroke path over a pinned session need an authenticated controller, and the board's passphrase is the operator's, not this repo's.)

$ python3 tools/console.py status
status  {"v":"1.0.0","up":7,"usb":1,"armed":0,"net":"ap","ssid":"keyrelay-ctl",
         "ip":"192.168.4.1","keys":0,"chords":0,"drop":0,"roll":0,"leds":0,
         "dflt":1,"ap":0,"typed":0,"typing":0,"mouse":1,"mbtn":0,"mframes":0}
link    controller=no rejected=0 authfails=0
queue   0 keys pending, 0 held, ok

$ python3 tools/relayctl.py --host <ip> status        # armed, typing, then disarmed
  armed      YES -- keystrokes are being forwarded
  counters   keys=… chords=0 dropped=0

$ python3 tools/watch_target.py --seconds 30          # on the same laptop
  t=  0.42s  A press
  t=  0.48s  A release
  ...
  key presses     …
  typed           '...'

Confirmed on hardware

AtomS3 Lite → Linux laptop (US layout), board joined the LAN, firmware 1.0.0.

what	result
flash	1 134 768 bytes written (706 661 compressed) in 8.1 s at 1 116 kbit/s, hash verified — measured on the pre-TLS image; the image this tree builds is 1 257 901 B (see the footprint row below), so the same math applies to a body ~11 % larger
footprint	bridge with TLS on: RAM 30.4 % (99 744 / 327 680); Flash 40.0 % (1 257 901 / 3 145 728) of the 3 MB app slot, console 20.6 % (67 352 B) / 37.5 % (1 178 141 B) — the pairs .agents/validate.sh prints on every run, re-measured at the phase-04 final pass on 2026-11-09: RAM unmoved from the phase-03 close, and flash 32 B higher than the task-02 measurement because the page grew by 39 bytes (the summary thumb-floor rule; the page lives in .rodata, so page bytes are flash bytes). The page is still 24 bytes smaller than phase 04 opened at — the prose fold paid for the fix and then some. Phase 03 — the claim slot, its whitelist, busy/tkov, the handover and the take-over affordance — is +128 B of RAM and +11 788 B of flash over the phase-02 final pass (RAM 30.4 % / 99 616 B, Flash 39.6 % / 1 246 145 B), most of the flash the page. Against the phase-01 baseline (RAM 26.7 % / 87 592 B, Flash 36.1 % / 1 135 293 B) the whole of phases 02 and 03 cost +12 152 B of RAM and +122 640 B of flash, 3.9 % more of the app slot. The RAM figure has barely moved since phase 02 task 06 even though both phases added code: kSanOidTlv is 5 bytes of flash, the rest of bug 11 is instructions, and what phase 03 adds per slot is one 64-byte buffer, one frame decoder and four small counters
what TLS itself costs	the same tree at -D KR_TLS=0 (pio run -e rollback): RAM 28.6 % (93 568 B) / Flash 36.8 % (1 157 593 B) — unchanged in kind by bug 11, which lives entirely inside #if KR_TLS. So the encrypted channel is +6 176 B of RAM and +100 308 B of flash on top of everything else the phase added, and the gate builds that image every run so the way back cannot rot. Proof the flag took, rather than a build that merely ran: xtensa-esp-elf-nm .pio/build/rollback/firmware.elf | grep -c mbedtls_ssl_ → 0 against 115 in the bridge image; the same for mbedtls_x509write → 0 vs 15; strings … | grep -c "pin this certificate" → 0 vs 1. Measured 2026-11-09
TLS handshake time	curl -sk -o /dev/null -w '%{time_appconnect} %{time_total}\n' https://keyrelay.local/ and …/status, one capped run each, 2026-11-09: seven warm connections handshake 0.349–0.423 s, the whole 51 626-byte page of that build (36 chunks over 9 loop() ticks of that build; the page grows -- the count .agents/validate.sh prints is the current truth, and the served-bytes half of this check is a row in .agents/HW_VERIFICATION.md) in 0.53–0.62 s, /status in 0.38–0.43 s. The first connection after ~10 minutes of quiet took 3.94 s of handshake — worth knowing because from a browser that looks like a timeout and is a cold start
TLS session heap	the board's own [tls] sessions=N heap=… serial lines: boot [tls] https :443 listening heap=187936 → 1 session ≈ 145.5 k → 2 sessions ≈ 107.9 k; the task-04 run with the transport view on both ports read 140 092 → 109 228 → close one 144 836 → close all 182 256. A second session is ~31–38 kB (two 16 kB mbed TLS record buffers plus the context), the memory comes back, and 20 connect/disconnect cycles showed no downward drift. This is why kTlsMaxSessions is 2 and why a third connection is refused outright rather than queued
enumeration	class=03 sub=01 proto=01 — boot-protocol keyboard, the Windows secure-attention precondition
reflashing	1200-baud touch into ROM download mode works with this firmware running, so no button and no GPIO0
page delivery	GET / over TLS → 200 and 51 626 bytes, sha256 equal to the locally assembled page from src/web_page.h (raw-string chunks + the 19-byte KR_TLS=1 marker; dd16e195…f04e9) — re-measured 2026-11-09 after the pinning-banner page change, i.e. of that build: the page has grown since and this tree assembles to 59 262 B, so the two numbers differ because the live board has not been reflashed, not because the send is lossy (every leg, and the byte-for-byte equality that held at that build, are in .agents/HW_VERIFICATION.md) — so the resumable, chunked flash send (1460 B per write, 5840 B per tick) delivers the page intact across many loop() iterations; the served bytes carry var KR_TLS_BUILD=1; and the new certFp/pTls/clearWarn elements; zero external references; 404 on unknown paths; 401 on /status without the passphrase
pinning from the terminal	relayctl.py --fingerprint 00…00 aborts with certificate fingerprint mismatch … Nothing was sent — the presented digest (61:54:19:30:ed:df:…, same identity the serial cert printed, across reflashes) and zero wire bytes; the real fingerprint passes the pin and stops only at authentication (E1, operator's passphrase — typing over a pinned session is the operator's confirmation to make); --ca <self-signed exported via openssl> verifies with hostname checking on; --insecure prints its warning on every run; no trust argument → the four-option refusal, exit 2, no socket; --plain reads the board's 426 as "board refuses plaintext", never as a passphrase problem — measured 2026-11-09, one capped run each
:80 is redirect-only	GET / → 301 with Location: https://<the address used>/; /index.html → 301 to the same path over https://; /nope → 301 to / (an unknown target is a 404 on the encrypted port, and the redirect does not echo an arbitrary request target); GET /status?token=… → 426 with Upgrade: TLS/1.2, HTTP/1.1 and no Location, body free of the token (grep -c of the value in the body: 0); /ws upgrade → 426, refused rather than downgraded — measured 2026-11-09, one capped curl each
controller over wss://	upgrade → 101 with the correct Sec-WebSocket-Accept, TLSv1.2 / ECDHE-ECDSA-AES256-GCM-SHA384; a wrong passphrase over that session → E1:wrong passphrase then close, never a silent pass; while that slot was open a second TLS connection fetched the page (200) and /status (401) — measured 2026-11-09
arming from the browser	the page armed the board on first try (observed as controller=yes armed=1); pre-TLS runs used ws://, phase 02+ runs use wss://
keystroke delivery	6/6 inert keys arrived on the target with matched press and release: F13, F15, F17, ScrollLock, CapsLock ×2
chord path	chords=1 counted and delivered (Shift+F15)
LED read-back	LED CapsLock on then off, coming from the target's HID output reports
silence disarms	controller process killed → armed:0 within 11 s, keys released. Worth knowing: that run passed before the silence timer existed — killing a process closes the socket, and the socket-close path disarmed. The FIN-less death (laptop slept, network vanished) is what the timer covers, and it is wired now. A check that passes for the wrong reason is still a check that passes, which is exactly the problem
single controller	a second client got E3 / 503 and the board logged rejected=1 — no takeover (observed pre-phase-03; a second client is a pending claim now — the takeover claims are rows in .agents/HW_VERIFICATION.md)
mouse enumeration	the target created two input devices from one HID interface — keyboard=/dev/input/event19, mouse=/dev/input/event20 — with caps rel: 1943, i.e. REL_X, REL_Y, REL_WHEEL, REL_HWHEEL and both hi-res axes
mouse movement	mouse move 120 -40 → movement dx +120 dy -40 on the target, exact, one report
mouse buttons	click → BTN Left press + BTN Left release; --button right → BTN Right. The bit order the page claims is the bit order the target sees
the wheel	mouse wheel -3 → REL_WHEEL -3. It took a wrong axis table in the verifier to prove this worked — see the note under Tests
drag ordering	drag 200 0 --button right → BTN Right press, movement dx +127, movement dx +73, BTN Right release. Both halves of the property at once: the ordering is down-then-move-then-up, and the 200 px left as two reports that stay inside one signed byte
keyboard and mouse together	keys, chords, a 14-character paste and mouse reports in one session, drop=0 roll=0, keys=3 and mframes advancing independently
a controller that dies holding a button	BTN Left press → client os._exit() (no close, no disarm) → BTN Left release 9.4 s later, and a live controller holding the same link with keepalives stayed armed for the 24 s it was tested. This is bug 10, and it is the property the whole release funnel exists to provide
lockout	5 wrong passphrases → E2, for 30 s, from the page's own retry loop
queues	drop=0 roll=0 throughout; queue 0 keys pending, 0 held, ok at rest

Fourteen bugs this verification caught (all fixed)

Worth listing, because each one is a class of bug that HID-over-network tools ship with:

1. CDC replies truncated at 128 bytes — setTxTimeoutMs(0) meant "drop what does not fit", and serial status came back cut mid-JSON. Replies now temporarily switch to a blocking write and flush. A diagnostic tool that lies about state is worse than none.

2. The CLI lowercased the whole handshake header block — base64 is case-sensitive, so every Sec-WebSocket-Accept compared wrong and the board looked broken while answering correctly. Header names are case-insensitive; values are not.

3. The CLI reported stale status — the board heartbeats at 1 Hz and the key helpers do not read while typing, so disarm printed armed YES from a heartbeat sent before the command. arm/disarm now drain, then poll until the board actually reports the state asked for — confirm, don't assume.

4. The target-side verifier mislabelled every LED — its table was copied from the HID bit numbering, but Linux EV_LED indices are zero-based (LED_CAPSL is 1, not 2). Verified against real events.

5. Unnamed key codes looked like lost keystrokes — F13–F24 had no names in the verifier's table, so a perfectly delivered run appeared to drop its first three keys. Now named, and unknown codes are counted rather than silently skipped.

6. The single-controller gate was applied at accept(), before the request was even read — so while a controller was connected, anything else that touched the board got a 503: curl of the page, a second browser, and worst of all pressing reload on the page that already held the bridge, since the board could still be holding the slot the instant the new request arrives. The fix moves the gate to what it actually protects: a second /ws upgrade was still refused then (that is a controller claim — phase 03 turned that refusal into the one pending claim, so a 503 now answers a second claim or a malformed upgrade), while read-only HTTP is served on a separate short-lived socket through the same routing code (serveReadonly) so the two paths cannot drift. Verified live: with your browser holding the bridge, the page returns 200 and /status returns 401 without the token, 200 with it, and a second upgrade still gets 503 while the incumbent stays controller=yes and healthy. (That last sentence is the pre-phase-03 observation, kept because it is what the fix was measured against at the time; the read-only half of it is unchanged, and what a second upgrade gets now is in Security model.*)

7. The Alt+Tab button sent Ctrl+Alt+A. Its data-chord was 05:04 — LCtrl|LAlt with usage 0x04, which is the A key. It parsed cleanly, it was correctly gated by arming, it arrived intact and it was the wrong combination: Alt+Tab is 04:2b. Reported by a user who could not work out why the Pi ignored it, and provable because the page stores the chord bytes on the button instead of a name to look up — so nothing on the browser side could ever disagree with a label. Every labelled chord is now pinned to the combination its label promises, by modifier byte and usage id.

8. relayctl's drain called two methods that do not exist (_send_frame, _check_error) while answering a ping, so any session outliving the board's 15 s ping died on an AttributeError instead of reading its next frame. Only reachable on long sessions, which is exactly what typing text is; it answered pings the way _poll does and raises on error frames now.

9. "Silence disarms" was documented and not implemented. kNoClientTimeoutMs existed, ControlServer::lastInboundMs() existed, and nothing ever compared them. Harmless while the only input was a human keystroke (a vanished controller sends no more keystrokes), and not harmless once a run can type for twenty seconds on its own: a laptop that slept mid-paste, with a link that never got a FIN, would keep typing into the target. loop() now checks it, before driving the typewriter, and clients keep-alive while they type. The lesson is the one the whole project keeps relearning: a safety property that is only written down is not a safety property.

10. A held mouse button stayed held, forever, and anything on the network could keep it that way. Found while verifying the mouse, with the mouse innocent: releaseEverything() queued the release reports (bug 9's fix), and they still did not go out.

    Three things stacked up. closeLink() ran the release callback only if (linked()), and linked() is _phase == WebSocket && _authed — so any path that cleared _authed on its way to closing the socket closed it with the keys down and nothing downstream able to notice. The board then sat armed=1 mbtn=01 with phase=none. And the backstop that should have caught it, loop()'s silence timer, was gated on control.linked() — a controller that has gone away is precisely the case in which linked() is false, so the fail-safe designed for a vanished controller could only ever run while the controller was there. Measured: BTN Left press, controller killed, target still holding the button 26 s later, and the armed state never expired.

    The second half was worse. acceptNew() stamped _lastInboundMs for any incoming TCP connection, so a read-only GET /status — which is served by design while a controller holds the bridge — reset the silence clock. Any authenticated monitor, second tab or health probe kept a dead controller's armed state open indefinitely. The first fix traded that for stamping in closeLink(), which moved the reset from accept to every close and changed nothing observable; wasLinked is the honest test, because it is true exactly when the thing being closed can leave key state behind.

    Fixed as: wasLinked = (_phase == Phase::WebSocket); the silence clock moved only by an authenticated controller's own traffic or by that link closing; controllerSeen() distinguishes "no controller since boot" (button-armed, leave it alone) from "one came and went" (never stay armed on its strength). Verified on hardware with the monitor running the whole time: BTN Left press → BTN Left release at 9.4 s, armed 0 and staying 0 for 37 s of continued polling, while a live controller holding the link with keepalives stayed armed through the same test.

    What to take from it: never gate a fail-safe on the absence of the thing its condition detects. And a backstop needs its own test, because this one passed every keyboard suite for exactly the reason bug 9 did — the socket-close path happened to cover the case being checked. tests/test_relayctl.py now pins all three sentences in source — five checks — and reinstating the linked() gate fails 2 of them, the accept-time stamp fails 1, the bug as it stood fails 3.

11. The certificate carried its names under the wrong OID, so no client could read them. mbedtls_x509write_crt_set_extension() takes an extension OID as the content bytes of the DER OBJECT IDENTIFIER, and this tree handed it the dotted string "2.5.29.17". The library said nothing, because nine bytes of ASCII are a well-formed OID — 1.10.46.53.46.50.57.46.49.55 — so the board issued a certificate with the correct 34-byte GeneralNames under a label nobody recognises. That is not a broken certificate: the key is fine, the handshake completes, the page is served, the fingerprint pins. It is a certificate with no subjectAltName, and browsers stopped matching hostnames on the CN years ago, so the name check fails with a message about the name while every part of the board insists the names are correct.

    It was found by reading the certificate the live board was serving instead of the code that writes it: openssl x509 -text on the peer certificate printed 1.10.46.53.46.50.57.46.49.55 where X509v3 Subject Alternative Name belongs, -ext subjectAltName answered no extensions, and a hex dump showed 06 09 32 2e 35 2e 32 39 2e 31 37 — the literal text — where 06 03 55 1d 11 should have been. The host suite could not have caught it as written, because every check in it walked the value and the name table, never the label. Same shape as the verifier's LED table (bug 4) and its REL_WHEEL axis code: a table cross-checked against itself, green the whole time — which is why AGENTS.md says to test the table, not your confidence in it.

    Fixed where the other DER lives, so it is host-tested: kSanOidTlv / sanOidDer() are the bytes the writer takes, sanExtensionFullDer() is the whole SEQUENCE { OID, OCTET STRING } pinned to the 43 bytes OpenSSL writes for the same three names, and derCarriesSan() asks the certificate the question a client asks — so cert now refuses to claim names a stored certificate does not carry. The regression test embeds the pre-fix extension byte for byte: derContains says the value is there and derCarriesSan says the extension is not, which is the difference between those two functions and the reason both exist.

    A board reflashed with the fix keeps its old certificate — NVS survives reflashing and rotating an identity is the operator's decision, not the build's — so cert prints a warning and the remedy is nvs erase, which reissues it, prints the new fingerprint once, and also forgets the passphrase and the network. Two rules out of it: an API that accepts a wrong-but-parseable argument is undocumented until it has bitten you, and a wire format has to be checked against somebody else's implementation, not against your own encoder.

12. The page read the error code as one character, so every two-digit code arrived as E1. The controller page parsed E<code>:<text> with raw[1] — fine while every code was one digit, wrong ever since E10 (mouse interface off) and E11 (target chose boot protocol) existed: the board's "the pointer is gone" or "boot protocol, no mouse" reached a fully authenticated page as the wrong-passphrase message, clearing authed and painting "no passphrase" on a session that was working. Phase 03 found it by writing the test for the code it was adding: E12 — the one sentence a dropped operator most needs read back verbatim ("your session was taken over") — would have arrived as the same bogus E1, hiding the takeover inside the misread. Fixed by parsing the code up to the first :, which is what the wire format always was; test_page.js now walks E12 end to end (disarm, mouse released, typing run ended, pill taken over, no auto-reclaim) with E3's separate "no room for a claim" sentence pinned beside it, and test_proto pins the two-digit codes' full-width rendering so the board cannot send a truncated one. The lesson is the mouse codes' lesson again: a client that assumes a field's width has stopped parsing the protocol and started guessing it.

13. relayctl's _poll returned from inside the read loop, abandoning the rest of the batch. A status frame riding in behind the reply the call was waiting for was lost with the abandoned generator — invisible while every caller asked for one thing at a time, and fatal for the phase-03 adoption probe, which reads what follows the OK: a controller gets OK then status back to back (auth answers them in one write), a pending claim gets OK and silence, and a drain that dropped the status would report a free board as busy — inviting --take-over against a bridge nobody held. Found by writing the suite's fake board the way the real one writes; fixed by draining the whole batch, parking an un-wanted status in _pending_status, and returning only once the socket is quiet. test_relayctl.py pins both probe answers — the fake puts T's OK and the adoption status on one write — so an early-return regression makes the free board look held and fails the stated no-op row instead of passing quietly.

14. The fold's tap target was 17 px tall — a safety note no thumb could open. Phase 04 moved five pinned safety sentences behind <details>, so the <summary> became the only route to them on a phone. It inherited no thumb floor, because the floor rule names its controls — button.k, .pill, input — rather than the property, and <summary> was written after the rule was set. Every byte-level layout assertion stayed green: they check that the named selectors carry min-height:44px in the served bytes, which is true, and says nothing about a control nobody named. Found only by measuring the assembled page in a real browser at 360 px — the pass this phase's final verification added — where it renders 17 px while the CSS comment two lines above it says "every press target is 44 px tall". Fixed by putting summary on the floor (page 59 223 → 59 262 B, re-pinned in config.h, test_conn.cpp and here), asserted in tests/test_page.js and measured in .agents/HW_VERIFICATION.md; deleting the rule fails both, which is the only reason to believe either. What to take from it: an assertion list built by naming things can only ever catch the things it names. Where the property is what matters — a tap target's height, a column count, sideways overflow — measure the property, or accept that the next control added is untested by construction. Same lesson as bug 4 and bug 11 in a different costume: a table cross-checked against itself stays green forever.

The hazard nobody warns you about

When the target is the machine you are working on, your keystrokes land on your own focused window. The first live test sent Escape, and the target was the laptop running this agent — so the keystroke interrupted the very session that sent it. That is not a bug in the bridge; it is exactly the transparency the thing is designed for, pointed the wrong way. So:

• verify with keys that nothing reacts to — F13–F24 and the Lock keys are inert almost everywhere, and they exercise the same code path as Enter;
• before arming against your own machine, decide what has focus; a terminal will execute what you send;
• the page releases keys and disarms when its tab loses focus, which is also how you get control back: click anything else, then click back.

---

Troubleshooting

symptom	cause, and what to do
the page does not have a feature the README describes	the page is served from the board's flash, so the image you built is not the image on the device. curl -sk https://keyrelay.local/ | wc -c and compare with the page in src/web_page.h; if they differ, reflash (to_bootloader.py then upload) and reload the tab — one already open still holds the old page in memory, passphrase notwithstanding
pio run -t upload sits at Connecting…	the app owns the USB pads. python3 tools/to_bootloader.py, or hold the button 3 s while powering up (LED solid red)
page will not connect	wrong address: console.py status for the real ip=; net:"ap" means you must join keyrelay-ctl
the browser says SSL_ERROR_…, curl says certificate verify failed, or relayctl.py says certificate fingerprint mismatch	the board regenerated its identity (nvs erase — the boot log prints the new fingerprint once, loudly) or you are on the wrong network and a different device is answering. That is exactly the attack the fingerprint is for, in those words: re-read cert on the board's own serial console — where nobody on a network can fake it — before typing the passphrase anywhere again. A browser that shows a second acceptance prompt after you already trusted it is the same signal
TLS itself is the thing that is broken and you need the board now	the way back is a reflash, not a repair: pio run -e rollback and upload it (that is [env:bridge] with -DKR_TLS=0), which is the pre-phase-02 build — page and socket on :80 in plaintext, no :443, booting with [tls] TLS compiled out (KR_TLS=0) -- plaintext control channel so there is no doubt which board is answering. relayctl.py needs --plain to talk to one. Everything in Security model is off while you run it; nothing about arming changes. Details and the measured cost: The rollback
the page says "this page arrived in the clear; reload over https" and will not take a passphrase	you loaded http://…. A TLS board answers :80 with a redirect and never serves the page there, so those bytes came from a cache, a downgrade attempt, or somebody else's server. Open https://keyrelay.local (or https://<ip>) and confirm the fingerprint the Connection card shows
keyrelay.local does not resolve	mDNS is queried per-process with no cache on glibc (mdns4_minimal [NOTFOUND=return]), so a cold probe that misses returns "not known" immediately — just retry, or use the IP. Across VLANs/VPN it is often blocked outright
arm does nothing, LED blinks red	no USB host attached (usb:0); the board is not plugged into the target, or the target suspended the bus
typing does nothing, armed says yes	the tab lost focus: click into the page. Or the target's focus moved — that is the target's answer, not a bug
E4 not armed	it is not armed. arm first; chords and states are never free passes
E3 another controller	another tab/machine holds it and the one pending-claim slot was already filled — your claim found no room. Close the other tab, or wait for its claim to expire (kClaimTimeoutMs, 15 s) and claim again; a takeover lands the board disarmed
the page's link pill says held by another controller	the board said so — an authenticated socket it declined to adopt, a busy status frame, or the E12 that says this session was displaced. It never says who: a link state, not an identity. The take-over button beside the passphrase field is one deliberate click (T then X, nothing else); the page that lost the bridge stays down until someone presses it — auto-reclaim is two tabs fighting over a keyboard
E2 locked out	5 wrong passphrases; wait 30 s
keys arrive out of order or missing	check dropped (queue overflow) and that the laptop's signal is good; WiFi.setSleep(false) is already set. If a verifier says keys are missing, check it names the codes — see the hazard nobody warns you about
the CLI says another controller holds this bridge	your browser page has it, and that is the rule working. Close the tab — or re-run with --take-over, which is the same one deliberate X the page's TAKE OVER button sends: the incumbent is told (E12), every key and every mouse button is released through the release funnel, and the board comes back disarmed so the new session arms on purpose. Against a free board --take-over is a stated no-op
pasted text arrives as different characters	the target is not on a US layout — characters travel as positions, exactly like the live keys. Or the run was sent with drop characters I cannot type / --strip, which reported how many it removed
a paste stops before the end	something cancelled it, on purpose: the tab lost focus, the bridge disarmed, the target suspended the bus, E7/E8, or 8 s with nothing inbound from the controller. The page's log says which, and how far it got
a chord button does something other than its label	the bytes on the button are wrong — the page carries the wire form itself, so nothing browser-side can catch it. curl the page and read data-chord; this was the case for Alt+Tab (05:04, Ctrl+Alt+A) until the label-vs-bytes test was written
a key is stuck on the target	R / Release keys / the button. Then check whether the tab lost focus without the page noticing (a hidden tab still gets blur on most browsers)
the boot log printed !! THE STORED TLS IDENTITY IS UNUSABLE, or cert says there is none	NVS holds a record that does not check out: a write lost to a power cut, an nvs erase, a key from one generation beside a certificate from another. The board regenerates and says so, once, before printing the new fingerprint -- that is the moment to re-pin. Nothing about arming changed either way: keystrokes are gated on arming, never on TLS
cert warns that the stored certificate does not carry the name list it prints	the certificate in NVS was issued by a different build than the one running now: the names come from the one table in src/tls_pem.h (sanEntries), and cert searches the certificate's own bytes for that extension, OID included. The usual reason is an identity generated before bug 11 was fixed — that certificate has the names in it under an OID no client reads, so encryption and pinning work and the hostname check cannot, and a browser complains about the name rather than about the extension. It is not dangerous and it is not a rotation: the fingerprint above that line still identifies the board. nvs erase reissues it (new fingerprint — re-pin — and it also forgets the token and the Wi-Fi credentials), which is the operator's call, not the board's
the fingerprint changes on every boot	NVS is refusing or losing the identity records. The boot log says IDENTITY NOT STORED when it happened; check the partition table (huge_app.csv: NVS is 20 KB and already holds the SSID, the passphrase and the token)
Ctrl+Alt+Del does nothing on the target	on Linux this is normal on a graphical session and fatal on a VT; on Windows the interface must be boot protocol (confirmed above)
target keeps suspending the bus	the target suspends, which disarms by design; disable suspend or plug into a port that stays powered

---

Design decisions

Why a web page and not a host daemon. Because "install something on the laptop" is the difference between a tool you can use in ten minutes on a machine you are borrowing and a project you set up once at your own desk. The page is served by the board, so the only software that has to exist is the browser you already opened.

Why full state instead of key events. Covered under Safety model point 8, and it is the decision that makes every other guarantee here cheap: a lost message is corrected by the next one, so there is no resynchronisation protocol, no sequence numbers, no stuck-key reconciliation timer.

Why the board expands and paces text, not the browser. It is tempting to turn a paste into existing S= frames client-side and change no firmware at all. Timing is the reason not to: a controller reaches the board over WiFi, in frames, with whatever gaps the network inserts, and a character is a press and a release with a hold either side of it on a target that samples every millisecond. A browser tab that stalls for a second would produce either a burst of keys or a run that outran the 48-deep report queue and tripped the overflow-disarm. Expanding on the board also means the page and the CLI cannot disagree about what a character types, which is the same argument that put the protocol in proto.h. Cost: the character map exists twice — positions in web_page.h/relayctl.py, characters in text.h — and a test pins all three together.

Why a paste refuses rather than sanitises. Curly quotes, em dashes and accented characters have no key on a US-ANSI keyboard. Dropping them quietly would send a passphrase, a rm line or a config value that is nearly what was pasted, which is the failure mode no one notices until it has landed. So the board answers E9 naming the code point and types none of the frame, the page says the same before it sends anything, and dropping is an explicit, per-paste opt-in that says how many characters it removed. Fail-closed, and loud.

Why no WebSocket library. The control channel needs text frames, ping/pong and close. A library buys fragmentation, extensions, TLS plumbing and many-client handling — attack surface and heap, none of it wanted. The hand-rolled codec is ~200 lines of pure logic with 135 host checks behind it, and every deviation from the subset is a hard close.

Why TLS rather than a challenge–response over the passphrase. The original ask was "doesn't need to be proper x509, but something", and the cheapest something is a nonce and an HMAC: the passphrase never appears on the wire, and there is no certificate, no warning screen, no fingerprint, no NVS record. It was rejected because hiding the secret is not the same as protecting the session. Under a challenge–response the keystrokes, the pasted text and the pointer deltas stay readable, and the page that collects them is still served in the clear — which anybody on the path can rewrite, at which point the attacker does not need the passphrase at all, only one keystroke from a page they wrote in a browser that already believes this is the keyboard bridge. Encrypting the channel is the option that closes that, and the only one that makes the trust-boundary table in Security model true rather than aspirational. The cost is stated rather than hidden: about 99 kB of flash and 6 kB of RAM, a handshake measured at ~0.35 s per new connection, and a certificate every browser complains about until you look at it once.

Why the identity is generated on the board rather than shipped as a PEM. Three reasons, in order of how much they matter. A key in this repository is one key for every board ever built, so reading the repo would buy a position between every deployment — and a per-user key generated by a build script makes the first pio run fail for anyone who has not run the script. Second, a private key is where this project's "never in a file, a log or a URL" rule gets teeth, and .agents/validate.sh refuses tracked *.pem, *.key and *.crt for exactly that reason; a key that exists only in NVS cannot be committed by accident, printed by a diagnostic, or shipped in a release. Third, per-board keys are what make pinning mean something: with a shared key any other board answers for yours and the fingerprint you checked identifies a model, not the device in your hand. So the board makes one on first boot, stores it in NVS (tlscrt, tlskey, tlscrtfp), keeps it across reflashing because NVS does, and regenerates it only when NVS is erased — printing the new fingerprint, loudly, because a rotated identity that stays quiet is a pinned value that stopped meaning anything. Where it lives is a separate decision, below.

Why raw mbed TLS rather than esp_tls. esp_tls.h was read before choosing, and its server entry point esp_tls_server_session_create() is documented to create the context and perform the handshake inside the call; the asynchronous pair (esp_tls_server_session_init + _continue_async) still takes ownership of the session and its teardown, layers its own error-code translation over mbed TLS's, and keeps its own fd bookkeeping. loop() needs the opposite on all three counts: one library call per tick, an fd whose lifetime is exactly the Session object's so it is closed on every path including open()'s failures, and WANT_READ distinguished from a real failure by the same table the read and write paths use (misread a WANT as fatal and slow WiFi drops working controllers; misread a fatal as WANT and the loop spins). esp_tls remains the right tool for a client; for a server that must not block a keyboard it is a wrapper whose convenience is the obstacle. The reasoning is in src/tls_session.h, not in a diff, so nobody "simplifies" it back.

Why a token-carrying request on :80 is refused with 426 instead of redirected. Because the obvious redirect is the leak: a 301 whose Location: echoes ?token=… puts the passphrase on the plaintext wire twice — once in the request the attacker already sees, once in the header written for their benefit — and it trains everyone who reads a curl -v to type the secret into an http:// address bar. So a plaintext /ws upgrade and any request carrying ?token= get 426 Upgrade Required with a one-line body that names https:// and contains no value (checked on the device: grep -c of the token in that body is 0), and everything else on that port gets the 301 it can safely have. AGENTS.md keeps the token a query parameter on /status because curl is the point of that endpoint — this is what makes that acceptable without the plaintext path becoming leakier than the encrypted one.

Why the rollback is a build, not a setting. A runtime switch for "accept keystrokes in plaintext" is a value the board could be talked into, and one that a future operator would leave on because turning it off costs a reboot. So the way back is -D KR_TLS=0 — pio run -e rollback, a reflash, same standing as mouse off, and built by the gate on every run so the reversal cannot rot. Nothing about arming moves with the flag: it decides which port carries bytes, never who may type them.

Why NVS for configuration. So the passphrase and network live in the board rather than in a header you recompile, and survive reflashing — and so a passphrase never has to enter a shell history, a git diff or a build log. The token command deliberately does not echo it back. The TLS identity lives in the same namespace (tlscrt, tlskey, tlscrtfp) for the same reason: reflashing must not change which certificate the operator pinned. Storing the fingerprint alongside it, rather than rehashing the certificate at every boot, is a trivial cost on a device with no PSRAM and no clock, and the value is public — the thing that is secret is the key, and the only outputs that touch it are mbedtls_pk_write_key_pem into NVS and the listener that will read it back. Nothing in src/ prints it, and the serial console has no command that could ask it to.

Why the sibling project's USB identity. Two firmwares on one board that are indistinguishable from the host side, and stable /dev/input/by-id names for the tools. Cost: it is a borrowed VID/PID, so it is documented as personal-use and one edit away from being honest.

---

Backlog

Ordered by what would make the biggest difference first.

1. OS-wide capture client (tools/keyrelay-capture.py, laptop side): grab the keyboard with evdev, forward full state over the same protocol, uinput a shadow if needed. Solves every compositor-stolen key and is the missing piece for "transparently drive another machine". Firmware unchanged — the protocol was designed for it. Needs root or input group + a udev rule; documented as opt-in because it swallows the laptop's keyboard while running.
2. A second, independent key path for the panic release: a GPIO or button double-click that force-releases without waiting for the loop's disarm path, so the panic release does not depend on the code that just failed.
3. Per-connection rate limiting — a token bucket on state messages, so a wedged or hostile client cannot pump the queue into the overflow-disarm path as a nuisance attack (currently it disarms: safe, but noisy), and a cap on page fetches now that the page is served even while a controller is live (each is ~58 KB, and no-store means a determined client will ask for it again and again).
4. mDNS also on the AP interface, verified on each chipset — some builds answer only on the station interface, which is why the docs say "IP if the name fails".
5. WPA3/PMF on the SoftAP and a per-board AP passphrase printed once at first boot, instead of one shared constant in config.h.
6. Report-rate telemetry: measure the achieved report interval against the host's poll rate, so the queue-depth choice is measured rather than reasoned.
7. Pastes longer than one run. kTextJobCap is 2048 characters and a controller that wants to send more has to split the job itself. The flow-control hook already exists — typing in the status frame is the board's own remaining count — so what is missing is only a client policy that refills as the board drains, plus the E8 retry that goes with it. Deliberately not done yet: unbounded buffering on a keyboard bridge buys nothing and enlarges the window in which text sits in RAM waiting to be typed.
8. A paste map that is not US-ANSI. strokeFor() in src/text.h is the single table for characters; positions live in web_page.h/relayctl.py. A second layout means a second character table and a second CODE_TO_USAGE, with the existing refusal semantics intact (no entry → E9, never a guess). Until then the answer is "set the target to US", which is one line on the target and zero bytes on the board.
9. A certificate a browser already trusts. The channel is encrypted, the fingerprint is pinnable and relayctl.py proves the pin; what is still manual is the trust itself — one warning accepted per browser profile, or 64 hex digits compared against the board's serial cert. The candidates are a per-board CA whose root the operator installs once (real chain validation, and a file to carry onto every controller that will ever connect) or ACME against a real hostname when the board has one (no warning at all, and it needs DNS this project does not control). Deliberately absent: a shared CA shipped in this repository — one key for every board ever built, which is the thing phase 02 moved generation onto the device to avoid. So are session tickets and resumption, on the blunter grounds that a board with no PSRAM and one controller is not paying a handshake cost worth optimising (measured: ~0.35 s per new connection, see Measured behaviour).

---

Restoring the sibling firmware

cd ../jiggler && pio run -t upload          # after tools/to_bootloader.py, if needed

The jiggler source is untouched by this project; they are separate PlatformIO projects for one board, and switching is one flash each way.