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

package/INSTALL.md

@@ -0,0 +1,38 @@
+# 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
+
+In the Web GUI: **Plugins → Add plugin**, enter `dsh-remote-control-plugin@0.3.1`, keep the
+official npm registry selected, then **Install** and **Enable now**. Restart DSH.
+
+A **Devices** icon appears in the sidebar.
+
+From a chat, the same install works where the plugin tool is enabled (Standard or Creator
+preset — PTC disables `tool-plugin-manager`):
+
+> Install the DSH plugin bundle `dsh-remote-control-plugin@0.3.1` with plugin_manager, then tell me when it is applied.
+
+## 2. Connect 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.
+
+Two machines on the same LAN need no relay at all — LAN discovery lists them directly.
+
+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.
+- Peer traffic is signed but not encrypted. Use a private network or TLS in front of the port.
+- 0.3.1 fixes two relay bugs: peers no longer linger as `503 relay-offline` after a relay goes
+  away, and a failed Connect no longer tears down a working hosted relay.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hkrds1996
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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.