Skip to content

feat: pair each remote client for a session of its own - #175

Open
sanchitrk wants to merge 1 commit into
feat/door-followupsfrom
feat/pairing
Open

sanchitrk wants to merge 1 commit into
feat/door-followupsfrom
feat/pairing

Conversation

@sanchitrk

@sanchitrk sanchitrk commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on the CLI error fixes, which are stacked on #173.

Why

A remote client stored a copy of the machine's token: one long-lived secret for every client of a home, with no way to cut off one device. Now each client pairs once and holds its own session.

How it works

  1. Pair. codework service pair prints a one-time code (XXXXX-XXXXX, 10 minutes).
  2. Exchange. POST /pair with { code, label } answers { id, token }. The machine stores a hash of the token in <home>/devices.json (mode 0600).
  3. Ticket. POST /ticket with Authorization: Bearer <token> answers a ticket: single use, 60 seconds. A session unused for 30 days is refused.
  4. Socket. The client offers the ticket where the home token goes for a local caller.
  5. Manage. codework service devices lists devices. codework service revoke <id> removes one and closes its open sockets.

What else changes

  • Home token. Made per server start again and accepted from a loopback peer only. <home>/token is gone.
  • Device rights. A device may call everything a local caller may, except pairing and device management, which answer Server.Forbidden.
  • App server. Adding a remote server takes { url, code }. Every connection takes a fresh ticket. A lost pairing shows as paired: false, separate from unreachable, and is not retried. The session token never reaches the renderer.
  • CLI. --server defaults to the home's server instead of port 7433. A server bound to every address answers to this computer's loopback names.

Breaking

  • A remote server row saved before this change is not paired and needs a code.
  • A server bound to one specific non-loopback address cannot be reached by its own CLI. Binding to 0.0.0.0 works.

Verified

Check Result
vp check, vp run typecheck, knip exports pass
packages/codework tests, in parallel, three runs 153 passed, 28 skipped each
apps/server non-live suite 42 passed
Live sync, recovery and usage suites, four OrbStack machines 23 passed

Also driven by hand in the Electron app with the CLI and three OrbStack machines: a real prompt locally; a server restart and recovery; pairing all three machines; a wrong code; sessions from each machine reaching the app; a follow-up sent to a machine from the app; a machine restart and reconnect; a revoke, and pairing again.

Known gaps

  • The code and session token travel in clear over ws:// to a non-loopback host.
  • The desktop app has no screen for adding a remote server yet; the run above added them over the app server's RPC.
  • metrics.simulation.live.test.ts was updated for pairing but not run.
  • Live runs add devices to each test machine's devices.json, which the fixture keeps.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

A remote client no longer stores a copy of the machine's token. It pairs
once with a code a person reads from `codework service pair`, and gets a
session only it holds.

- `POST /pair` exchanges a one-time code (10 minutes) for a session token.
  The machine keeps a hash of it in <home>/devices.json.
- `POST /ticket` takes the session token in Authorization and answers a
  ticket that opens one socket within 60 seconds. A session unused for
  30 days is refused.
- `codework service devices` lists devices; `codework service revoke`
  removes one and closes its open sockets.
- The home's token is made per server start again and is accepted from
  loopback only. <home>/token is gone.
- A device may call everything a local caller may, except pairing and
  device management.
- The app server adds a remote server with a pairing code, takes a ticket
  for every connection, and reports a lost pairing as `paired: false`.
- `--server` now defaults to the home's server, and a server bound to
  every address answers to this computer's loopback names.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant