dsh-remote-control-plugin 0.0.0-stage → 0.3.0

package/INSTALL.md

@@ -0,0 +1,35 @@
+# Install on another desktop
+
+Published as `dsh-remote-control-plugin`. The package is self-contained — no dependencies, no
+build step, no postinstall script.
+
+## 1. Install it
+
+Open DSH on the other desktop, start a session, and send:
+
+> Install the DSH plugin bundle `dsh-remote-control-plugin@0.3.0` with plugin_manager, then tell me when it is applied.
+
+Then restart DSH. A **Devices** icon appears in the sidebar.
+
+`dsh plugin add` does not work for this: it forwards to `pnpm`, which is not on `PATH` outside
+the app. The agent route uses the bundled pnpm and also registers the bundle in the profile,
+which a bare `pnpm add` would not do.
+
+## 2. Connect the two machines
+
+Pick the machine with a reachable address (same LAN, VPN, or a forwarded port):
+
+1. On that machine: **Devices → Relay → Create relay here**, then **Copy** the invite.
+2. On the other machine: **Devices → Relay**, paste the invite into the URL field, **Connect**.
+3. Either machine: **Request** next to the peer, then **Allow** on the target.
+
+No reachable machine? Run a relay anywhere both can reach (`PORT=8787 node relay/server.js`) and
+paste `http://<host>:8787 <workspace key>` into both panels.
+
+## Notes
+
+- The account label is cosmetic; trust comes from the one-time **Allow** on the target device.
+- Approvals persist in `$DSH_HOME/remote-control-peers.json`; deleting it revokes every peer.
+- The relay and the control API share one port (default `57330`), so one forwarded port is enough.
+- Device trusts are per install: the published plugin and a locally built copy share the protocol
+  but keep separate approval stores.

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# dsh-remote-control-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Control other DSH desktops from the one you are using.
+
+Two surfaces share one Host plugin:
+
+- **Devices panel** (Web GUI) — discovers other DSH desktops on the same network, asks the
+  target for access once, then lists that device's sessions and lets you read the live
+  transcript, send prompts, and stop a turn.
+- **Browser page** (phone / any browser) — the same control surface as a small standalone
+  page, unlocked with a pairing code. Useful when the other end is a phone rather than a DSH
+  desktop.
+
+Both drive `ctx.sessionController` in-process, so neither depends on the GUI's boot payload.
+
+## How device trust works
+
+1. Each Host announces itself on UDP `discoveryPort` with its device id, display name, and
+   account id (when signed in).
+2. To control a peer, this Host sends `POST /peer/hello`. The **target** shows a pending
+   request in its own Devices panel; nothing is granted until a person there presses **Allow**.
+3. On approval the target issues a random per-peer secret. Every later call is signed
+   `HMAC-SHA256(secret, deviceId + method + path + timestamp + body)`, valid for 5 minutes of
+   clock skew.
+4. Approvals persist in `$DSH_HOME/remote-control-peers.json`. Deleting that file revokes
+   every device.
+
+There is deliberately no "same account implies trust" shortcut: two devices holding grants for
+the same account share no secret, so account id alone cannot authenticate a peer. The panel
+shows the account id of each candidate and flags a different account, but a person approves.
+
+## Across networks (relay)
+
+LAN discovery only reaches one subnet. Devices on different networks meet through a relay, and
+there are two ways to get one.
+
+**Create it on a device.** In **Devices → Relay**, press **Create relay here**. That Host serves
+the relay on its own listener and shows a ready-to-paste invite — one line holding the URL and
+the workspace key. Paste it into the other device's Relay panel.
+
+This only reaches other networks if that device is reachable there: the same LAN, a forwarded
+port, a VPN address, or a configured `publicUrl`. The invite carries the address the panel can
+see, so forward that port (or set `publicUrl`) before sharing it.
+
+**Or run a relay on a machine that is always reachable:**
+
+```sh
+PORT=8787 node relay/server.js
+```
+
+Host it on a VPS, NAS, or any always-on machine, put it behind TLS or a VPN, and paste
+`http://host:8787 <workspace key>` into every device.
+
+Either way the workspace key never leaves the devices: the relay only receives its SHA-256 as a
+group id. It forwards opaque `/peer/*` calls that stay signed end to end, so a compromised relay
+can drop or delay traffic but cannot forge a control command. Group membership alone grants
+nothing — the target still requires the one-time approval before any session call is accepted.
+Treat the relay as private: whoever holds the group id can join the group and *request* access.
+
+## Configuration
+
+Defaults work on a LAN. Override the row in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`:
+
+```yaml
+- id: remote-control
+  name: 'dsh-remote-control-plugin'
+  config:
+    host: 0.0.0.0            # any interface (default); use one LAN IP to narrow exposure
+    port: 57330              # browser page + peer API
+    discovery: true
+    discoveryPort: 57331     # UDP discovery
+    relayUrl: ''             # e.g. https://relay.example.com for cross-network control
+    relayKey: ''             # shared workspace key; required when relayUrl is set
+    deviceName: Desk PC      # defaults to the OS hostname
+    publicUrl: ''            # e.g. https://dsh.example.com for a tunnel/proxy
+    trustedHosts: []         # extra accepted authorities for the browser page
+    code: ''                 # fixed pairing code; empty = generated and persisted
+    cookieDays: 30
+    defaultCwd: ''
+    tls: { certFile: '', keyFile: '' }
+```
+
+The browser page and the peer API share the listener. When `host` is a wildcard, any IP literal
+is accepted and domain-name Hosts are refused unless they appear in `publicUrl` or
+`trustedHosts`; this blocks DNS-rebinding. Requests without a same-origin `Sec-Fetch-Site` must
+come from loopback.
+
+## Threat model / limits
+
+- Approval is manual on purpose. A peer on the LAN can prompt for access; it cannot grant it.
+- Prompts sent from a peer run with this Host's tools and permissions. Approve devices you
+  control.
+- Peer transport is plain HTTP. The peer secret crosses the LAN once, at approval time. Use a
+  private network or VPN, or set `tls` and front the port with a proxy.
+- The pairing code protects the browser page only; it is printed at activation and stored in
+  `$DSH_HOME/remote-control.json`.
+- Approvals that arrive while no Devices panel is open stay pending for up to 10 minutes.