Repository navigation
feat(remote): pair two machines over SSH, and report partial pairings - #98
Merged
Merged
Conversation
ADR 0035: `localify machines pair B --over-ssh <destination>` starts the accepting side over SSH and compares both codes in Localify's own code, so the relay-in-the-middle check holds without a person; `--for-ssh` only answers its parent process. The MCP server still has no pairing tool, and removing a machine stays a person's decision.
Mandatory host key trust, one quoted remote command with no shell on A, a ready event binding B's one-shot acceptor to the expected account, initiator and attempt, versioned JSON lines, deadlines from B's ready, the usual limits counted on ready, and an honest partial result after confirmations started (which every pairing can hit).
…n id, and deadline origins
An agent a person gave SSH access to both machines can now pair them without a person at either screen (ADR 0035): `localify machines pair <B> --over-ssh <destination>` runs `ssh` itself with the contract's fixed options, starts `localify machines pair --accept --for-ssh` on B, reads both codes over the line protocol, and confirms both sides only when they match. The daemon gets a one-shot acceptor bound to the account and the initiating machine id (`remote_pair_accept`), counted against the hour's 5 attempts when it is registered, with B's 2 minutes starting there. `remote_pair` takes an `attempt` it echoes, and `remote_status` gives the machine id and account both sides check. A pairing cut after a `pair.confirm` used to say "Nothing was saved" while one side could hold a pin. Each side now reports its own pin as the disk has it and the peer's as it said (`partial`, exit 4): a side that wrote its pin ends with `bye` `done` and waits for the peer's, and one that accepted without saving ends with `error`. A pin with another key is never replaced by a pairing. The app and the interactive CLI show partial results too.
…ng over SSH A 1.7.0 peer ends a pairing with `bye` `done` even when its pin write failed or its 2 minutes ran out, so reading that `bye` as "saved" reported `paired` with only one pin. Session protocol 3 adds `pair.saved`, sent only once the pin is durably written. A 1.7.0 peer speaks 1 to 2, so it never receives it: with such a peer, a side ends as soon as it wrote its own pin, as 1.7.0 does, and reports the peer `unknown` with reason `unconfirmed`. The app and the CLI then say to check that machine or update it, since pairing again would end the same way. The desktop's checks for protocol 2 now accept later versions. The pin write now checks the existing pin's key under the pins' lock, so two pairings in flight for one machine id never overwrite each other's key: the second ends with `key_mismatch`. The `--for-ssh` helper bounds its daemon's first answer to 15 s and watches stdin during registration, so it never blocks before `ready`. On the initiator, a line that breaks the protocol marks B's stdout invalid for good: later lines, an earlier `result` included, are ignored, B is never reported pinned, and the report keeps the break as its reason. `--over-ssh` checks `ssh -V` for OpenSSH 8.7 or later first, and fails with exit 2 instead of letting ssh reject StdinNull and ForkAfterAuthentication. The tests play a 1.7.0 target in the fake relay, byte for byte on the wire, to check a timeout and a failed pin write against it, and that nothing a new peer sends is unknown to 1.7.0.
Brings in --machine for the CLI and MCP (#97). - docs/remote-machines.md: keeps #97's CLI output and MCP snapshot text and #98's pairing over SSH exceptions. - src/cli/machines.rs: machines() now takes the management client, so the SSH pairing passes ctx.mgmt_client. - The CLI's --machine end-to-end test holds a session between A and B and checks that both agree on the latest protocol (3, pair.saved, or later) for the whole run. The CLI and MCP code from #97 never checks the session version, so nothing else needed to change.
…re pair.saved, and exit 2 or 4 from interactive pairing - A line B writes after its result is still checked, so a protocol break after a claimed success undoes it instead of being ignored. - A pin is synced to disk, and so is its folder after the rename, before pair.saved says it was saved. - `machines pair` and `pair --accept` exit 2 when nothing was saved and 4 when only one side is known pinned, as the contract says, instead of 1.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements pairing over SSH (ADR 0035) and the partial results of "Pairing" in
docs/remote-machines.md. The contract commits fromdocs/remote-cli-and-agent-pairing(up to bb7dca1) are cherry-picked first, so this PR carries the contract with the code.What changes
Daemon
remote_pair_accept {machineId, account}(streaming) registers a one-shot acceptor bound to the account and the initiating machine id. Only a pairing request from that machine consumes it; any other request is declinedbusy. Registration follows the one-active-pairing rule and counts against the 5-per-hour limit right away, just beforeready. B's 2 minutes start at registration, on the monotonic clock.remote_pair {machineId, attempt?}echoesattempton every event.remote_statusaddsmachineIdandaccountwhile connected, which both sides check.--accept: a pairing session now endspaired,cancelledorpartial {local, peer}. "Nothing was saved" is said only when nothing could have been written: this side wrote no pin, and it either never sentaccept: trueor got the peer'saccept: false. To tell when the peer saved, session protocol 3 addspair.saved: a side sends it only once its pin is durably written, then waits up to 30 s for the peer's. Nothing else,byedoneincluded, counts as saved.pair.saved. With such a peer, a side ends as soon as it wrote its own pin, as 1.7.0 does, and reports the peerunknownwith reasonunconfirmed(exit 4). The app and the CLI then say to check that machine or update it, since pairing again would end the same way.pair_partialcarries thatreason.key_mismatch, and the pin write checks again under the pins' lock, so two pairings in flight for one machine id never overwrite each other.CLI
localify machines pair --accept --for-ssh --from <id> --account <userId>(hidden flags). It refuses a terminal on stdin or stdout. Its daemon checks the account and that--fromis not this machine. stdout carries only versioned JSON lines (ready,code,result) and diagnostics go to stderr. It confirms only on an exact code match, cancels on a closed stdin, a cancel line or a malformed line, and writes nothing to stdout when it fails beforeready.localify machines pair <B> --over-ssh <destination> [--remote-localify <path>]:sshdirectly with exactly the contract's option set and--.-, plus empty values, whitespace and control characters. Each word of the remote command is quoted for a POSIX shell.--remote-localifymust be one absolute path with no newline or NUL.ready(machine id and account), starts its own pairing with the attempt, compares the codes, then confirms or cancels both sides. It keeps B's stdin open until B'sresult, then reapsssh.ready(15 s connect plus 15 s), then 2 minutes. The helper bounds its daemon's first answer to 15 s and watches stdin while it registers.resultincluded, are ignored, B is never reported pinned, and the report keeps the break as its reason (exit 2 or 4).ssh -Vfor OpenSSH 8.7 or later first (StdinNull,ForkAfterAuthentication), and fails with exit 2 and the version needed otherwise.pairand--acceptshow partial results.Desktop app: handles the new
partialandpair_partialevents, so it no longer says "Nothing was saved" after a partial pairing. Its checks for session protocol 2 accept later versions.Docs: the contract's Daemon table and "Partial results", the user guide (
docs/README.md), andchanges/pair-over-ssh.md.Tested
Everything ran in this process against the fake relay, with temporary data directories and homes. Nothing ran against real machines, real pairings, or any machine's real remote state.
cargo fmt --check,cargo clippy -- -D warnings, andcargo test: lib 967, bin 1306, and all integration tests pass.tests/app_bridge.rsfailed once under the full run's load and passed on three reruns; it doesn't touch pairing.--all-targetsclippy shows only the existingtestkit.rsfindings.pnpm run typecheck,node --test desktop-ui/src/lib/util.remote.test.ts, oxlint and oxfmt on the changed files.partialwith each side's verified state (Anot_pinned/unknown, Bpinned/unknown), and pairing again completes it.partialrather than "Nothing was saved". Timeouts and cancels before any confirm still pin nothing.byedoneleaves Apinned/unknown,unconfirmed. Everything A sent it is a type 1.7.0 knows, and A'shellorange holds 2.pair.savedswallowed, A reports Bunknowneven though B'sbyearrives. With it, both sides are paired.key_mismatch.resultclaiming success, while A's daemon still waits: A reports Bunknown, exit 4, with the invalid line as the reason.vother than 1. Control lines are exactlyconfirmorcancel.-o…,-p, spaces, newline, NUL); quoting checked through a realshwith spaces, quotes,$and backticks; NUL and newline refused.localifybinary (--accept --for-ssh,env_clear, temporaryHOME) instead ofssh, against B's management socket.partial, exit 4, B pinned and A not. Pairing again completes it.readyfor another machine or account, and on a malformed,v: 2or foreign line.Notes
ready: that version has no--for-ssh.--machinefor the CLI and MCP landed separately in feat: act on another machine's services from the CLI and MCP #97, which is merged into this branch (see below).Merge with main (#97)
origin/mainis merged in (b7c11d0), not rebased. #97 added--machineto the CLI and MCP.docs/remote-machines.md: the conflicts are resolved by keeping both PRs' edits. That means feat: act on another machine's services from the CLI and MCP #97's CLI output rules and its MCP snapshot line, plus this PR's pairing over SSH exceptions forpairand for agents.src/cli/machines.rs: feat: act on another machine's services from the CLI and MCP #97 changedmachines()to take the management client, so the SSH pairing now passesctx.mgmt_client.src/cli/remote/,src/cli/mcp/) never reads the session version, and the daemon's version gates already compare with>=. Nothing assumed exactly version 2, so no code changed.--machineend-to-end test (daemon::remote::tests::cli) now holds a session between A and B through the fake relay. It checks that both agree on the latest protocol (3, which haspair.saved, or later) before the commands run and after the stop. Snapshot, logs, follow, a stop and a refused start then all run in that version-3 session.cargo fmt --check,cargo clippy -- -D warnings, fullcargo test(lib 967, bin 1342, all integration tests),pnpm run typecheck,pnpm desktop:test(63). In the first full run,tests/app_bridge.rsfailed once with the same flake as above; it passed 3 times alone and in a second full run.