feat(control): one control key and a Noise handshake on every control connection

[fylorn]

Phase P1 of the remote-core plan: one control key, and a Noise handshake in front of every control-plane connection. The remote TCP listener (P4) is not in this PR; the APIs are shaped so it drops into the same hand_off path.

Protocol

Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s (the snow crate, only X25519 / ChaChaPoly / BLAKE2s enabled). The PSK is the 32-byte listen.control.key from config.yaml; prologue ThinkWatch control channel 1.

app  → core   [u16 BE len][e, encrypted ClientHello { proto, app }]
core → app    [u16 BE len][e, ee, encrypted ServerHello { proto, core, accept }]
              or a single plaintext 0xFF (REJECT) and close — message 1 did not decrypt (wrong key)
then          [u16 BE len][ciphertext]…   ≤ 65535 bytes incl. the 16-byte tag; larger writes are split

• proto is CONTROL_API_VERSION (bumped to 18). On a mismatch core answers accept: false and closes; the client gets VersionMismatch { ours, theirs, peer_version } with core's CalVer before any HTTP.
• Handshake timeout 5 s on both sides. Plain HTTP (e.g. curl) gets the reject byte.
• After the handshake SecureStream<S> is a plain AsyncRead + AsyncWrite; hyper HTTP/1.1 and the SSE event stream run over it unchanged.
• The server reads the key per handshake from the config in effect. When a reload changes the key, connections made with the previous key are closed.

What changed

• New crate tw-link (deps: snow, tokio, serde/serde_json, thiserror, tw-api, tw-yaml): connect, connect_with_timeout, Acceptor, Accepted, SecureStream, LinkError (Unreachable / Closed / WrongKey / VersionMismatch / Timeout / Io), ClientHello / ServerHello, read_key(path) / key_in_config(text).
• tw-api: control::ControlKey (64-hex parse/format, redacted Debug), KEY_PATH, KEY_HEX_LEN, KEY_MASK, CONFIG_FILE, config_file(). Removed TOKEN_FILE, TOKEN_ENV, token_file.
• tw-config: listen.control.key (ControlListen, with a marked spot for remote), validated — missing → config.control_key_missing, not 64 hex → config.control_key_invalid. generate_initial() carries a fresh key; generate_control_key(). New control_key module: ensure / ensure_file (adds only that field, minimal YAML edit), rotate / rotate_file, mask, unmask, raw_in. History snapshots store the key masked (the version is still hashed from the real text); history::rollback puts the current key back.
• twcore: serve writes the key before the control plane listens (new config, or one added field in an existing config). New twcore control-key [--rotate] and twcore call [-X METHOD] [-d JSON] [--out FILE] <path>, which replaces curl for scripts and debugging. check validates the way serve will (a missing key is noted, not an error). init uses the same generator.
• tw-control: token.rs is gone; serve(state, at) takes no token; gate.rs does the handshake in hand_off for every transport. GET /config masks the key; PUT / PATCH / rollback through the control plane keep it when the mask comes back and refuse any change or removal (403 control.control_key_locked). The diagnostic bundle and config-error excerpts mask it completely.
• scripts/smoke.sh and the Windows CI step use twcore call; they also check that plain HTTP is refused, a wrong key is refused, only the key lines are added to an old config, /config is masked, and --rotate takes effect.

Message codes: new config.control_key_missing, config.control_key_invalid, control.control_key_locked; removed control.unauthorized.

What the desktop app must change (P2)

• Depend on tw-link (same tag as tw-api). Remove token.rs, the TW_CONTROL_TOKEN env on spawn, and every Authorization: Bearer header.
• Local key: tw_link::read_key(&tw_api::control::config_file(&tw_api::data::dir())). KeyReadError::Io (NotFound) / Missing means core is not ready yet; retry as for a missing socket.
• ControlClient::connect: after opening the unix socket or loopback TCP stream, tw_link::connect(stream, &key, app_version) and run hyper's HTTP/1.1 client on the returned SecureStream. call::<E>() and the event stream are otherwise unchanged.
• Map LinkError to UI states. After WrongKey or a dropped connection, re-read the key once (rotation closes old connections).
• GET /config text now carries KEY_MASK where the key is; send it back unchanged. Add translations for the three new codes and drop control.unauthorized.
• CONTROL_API_VERSION is 18; regenerate the TS types.

For P4 (remote listener)

• Put remote in ControlListen (marked in tw-config/src/lib.rs); the key stays the same field.
• Accept on the remote port and hand the stream to the same hand_off(stream, app, gate) in tw-control/src/lib.rs. allow_from rejection happens before it (close, no bytes; the client sees Closed); the 5 s handshake timeout is already in Acceptor.
• Remote restrictions (/shutdown, listen.control writes, diagnostics) need to know which transport a request came from; hand_off is the place to add that per-connection marker.

Checks

cargo fmt --all, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace, and scripts/smoke.sh pass locally (macOS).

🤖 Generated with Claude Code