herdr-remote-relay 0.2.0 → 0.2.2

package/README.md

@@ -1,27 +1,21 @@
 # herdr-remote-relay
 
-Standalone relay server for [Herdr Remote](https://www.npmjs.com/package/herdr-remote):
-it serves the mobile web terminal and brokers browser ↔ workstation sessions.
+*[English](README.md) · [简体中文](README.zh-CN.md)*
 
-Its only runtime dependency is `ws`, so the machine running it needs no
-compiler, no Herdr and no plugin. It never runs a shell and never touches your
-Herdr socket — only the host connector on your own workstation does that.
+Standalone relay server and WebUI for [Herdr Remote](https://www.npmjs.com/package/herdr-remote).
 
-**You usually do not need to install this yourself.** `herdr-remote` starts a
-relay locally unless you point it at one you host. Install this package only
-when you want to reach your workstation from outside your own network.
+Brokers WebSocket connections between browsers and workstation host connectors. Runtime dependency is `ws` only; requires no compilers or Herdr binaries.
+
+> **Note**: `herdr-remote` runs a local relay automatically. Install this package only when deploying a dedicated relay server.
+
+## Installation
 
 ```bash
 npm install -g herdr-remote-relay
-herdr-remote-relay --public-url https://herdr.example.com \
-  --password your-password --admin-token your-long-random-admin-token \
-  --trust-proxy
+herdr-remote-relay --public-url https://herdr.example.com --password <password>
 ```
 
-Requirements: Node.js 22+, a domain name, and TLS. Terminate TLS in a reverse
-proxy in front of the relay — nginx, Caddy, Traefik and Cloudflare Tunnel all
-work. Example configs for nginx, Cloudflare Tunnel, systemd and Docker Compose
-ship in `deploy/` inside this package.
+Requirements: Node.js 22+, TLS reverse proxy (nginx, Caddy, Cloudflare Tunnel).
 
 ## Docker
 
@@ -32,7 +26,7 @@ docker run -d --name herdr-relay --restart unless-stopped \
   -e RELAY_BIND=0.0.0.0 \
   -e RELAY_PUBLIC_URL=https://herdr.example.com \
   -e RELAY_PASSWORD=your-password \
-  -e RELAY_ADMIN_TOKEN=your-long-random-admin-token \
+  -e RELAY_ADMIN_TOKEN=your-admin-token \
   -e RELAY_TRUST_PROXY=1 \
   -e RELAY_AUTH_STATE_FILE=/data/relay-auth.json \
   node:22-alpine npx -y herdr-remote-relay
@@ -40,63 +34,33 @@ docker run -d --name herdr-relay --restart unless-stopped \
 
 ## Options
 
-Every setting has a flag, an environment variable and a JSON config file key
-(`--config`, or `HERDR_RELAY_CONFIG`). Precedence runs defaults → file →
-environment → flags.
-
-| Variable | Default | |
-|---|---|---|
-| `RELAY_PUBLIC_URL` | `http://127.0.0.1:8787` | URL browsers open |
-| `RELAY_PASSWORD` | *(none)* | Password a workstation must present. **Empty = public relay** |
-| `RELAY_ADMIN_TOKEN` | *(none)* | Operator token for the relay dashboard at `/admin` |
-| `RELAY_BIND` | `127.0.0.1` | Listen address (`0.0.0.0` in Docker) |
-| `RELAY_PORT` | `8787` | Listen port |
-| `RELAY_TRUST_PROXY` | `0` | Set to `1` behind a reverse proxy |
-| `RELAY_AUTH_STATE_FILE` | `~/.local/state/herdr-remote-relay/relay-auth.json` | Device records |
-| `RELAY_ALLOWED_ORIGINS` | *(same-origin)* | Extra browser origins, comma separated |
-| `RELAY_MAX_CLIENTS_PER_HOST` | `16` | Browsers per workstation |
-| `RELAY_DEPLOYMENT_MODE` | `remote` | `local` is reserved for the workstation-managed relay |
-
-Whatever proxy you put in front must forward WebSocket upgrades and must not
-time out idle connections — a terminal is idle between keystrokes.
-
-## Public relays
-
-Leaving `RELAY_PASSWORD` empty makes the relay public: anyone may connect a
-workstation to it. That is safe to share, because each workstation is reachable
-only through its own host token — generated on that machine, never handed out
-by the relay. Nobody else can pair a device to your terminal.
-
-What a public relay does give away is bandwidth and the fact that your
-workstation is online. Set a password if that matters.
-
-## Connect a workstation
-
-On the workstation, run `herdr-remote`, open the **Relay** tab and set the
-access mode to **Self-hosted relay**, the relay URL to
-`wss://herdr.example.com`, and the relay password to the same `RELAY_PASSWORD`.
-Then check:
-
+| Option | Env Var | Default | Description |
+|---|---|---|---|
+| `--public-url` | `RELAY_PUBLIC_URL` | `http://127.0.0.1:8787` | Public URL for browsers |
+| `--password` | `RELAY_PASSWORD` | *(empty)* | Workstation join password (empty = public) |
+| `--admin-token` | `RELAY_ADMIN_TOKEN` | *(empty)* | Operator token for `/admin` |
+| `--bind` | `RELAY_BIND` | `127.0.0.1` | Listen address |
+| `--port` | `RELAY_PORT` | `8787` | Listen port |
+| `--trust-proxy` | `RELAY_TRUST_PROXY` | `0` | Trust `X-Forwarded-For` header (`1` behind proxy) |
+| `--state-file` | `RELAY_AUTH_STATE_FILE` | `~/.local/state/herdr-remote-relay/relay-auth.json` | Auth state file path |
+| `--allowed-origins` | `RELAY_ALLOWED_ORIGINS` | *(same-origin)* | Allowed CORS origins, comma-separated |
+| `--max-clients` | `RELAY_MAX_CLIENTS_PER_HOST` | `16` | Maximum browser clients per host |
+| `--config` | `HERDR_RELAY_CONFIG` | *(none)* | JSON configuration file path |
+
+Reverse proxies must pass WebSocket `Upgrade` headers and maintain long idle timeouts. Deployment examples for nginx, systemd, and Docker Compose are in `deploy/`.
+
+## Connecting a Workstation
+
+In `herdr-remote` TUI under **Relay** tab:
+- Set mode to **Self-hosted relay**
+- Set Relay URL to `wss://herdr.example.com`
+- Set Relay Password to matching `RELAY_PASSWORD`
+
+Check connection status:
 ```bash
-curl https://herdr.example.com/healthz    # hosts should be 1
+curl https://herdr.example.com/healthz
 ```
 
-| Symptom | Cause |
-|---|---|
-| `hosts: 0` | Workstation not connected — check `herdr-remote status` |
-| `relay_password_required` | Password differs between the two sides |
-| Page loads, terminal never opens | Proxy is not forwarding `Upgrade` headers |
-| Drops after ~60s idle | Proxy read timeout too short |
-
-## Security
-
-- Tokens are stored as SHA-256 hashes, never in clear text. Terminal content is
-  never written to disk.
-- Pairing codes are single-use, expire in ten minutes, and are rate limited.
-- The `/admin` operator credential is separate from the workstation join
-  password and from paired device tokens.
-- Losing the state file just means re-pairing your devices.
-
 ## License
 
 MIT

package/README.zh-CN.md

@@ -0,0 +1,66 @@
+# herdr-remote-relay
+
+*[English](README.md) · [简体中文](README.zh-CN.md)*
+
+[Herdr Remote](https://www.npmjs.com/package/herdr-remote) 的独立 Relay 服务端与 WebUI。
+
+负责在浏览器与工作站主机连接器之间转发 WebSocket 连接。运行时仅依赖 `ws`，无需编译环境或 Herdr 二进制文件。
+
+> **提示**：`herdr-remote` 默认在本地自动运行 relay。仅在需要部署独立中继服务器时安装本包。
+
+## 安装
+
+```bash
+npm install -g herdr-remote-relay
+herdr-remote-relay --public-url https://herdr.example.com --password <密码>
+```
+
+前置要求：Node.js 22+、TLS 反向代理（nginx、Caddy、Cloudflare Tunnel 等）。
+
+## Docker 运行
+
+```bash
+docker run -d --name herdr-relay --restart unless-stopped \
+  -p 127.0.0.1:8787:8787 \
+  -v herdr-relay:/data \
+  -e RELAY_BIND=0.0.0.0 \
+  -e RELAY_PUBLIC_URL=https://herdr.example.com \
+  -e RELAY_PASSWORD=你的密码 \
+  -e RELAY_ADMIN_TOKEN=你的管理令牌 \
+  -e RELAY_TRUST_PROXY=1 \
+  -e RELAY_AUTH_STATE_FILE=/data/relay-auth.json \
+  node:22-alpine npx -y herdr-remote-relay
+```
+
+## 配置参数
+
+| 参数 | 环境变量 | 默认值 | 说明 |
+|---|---|---|---|
+| `--public-url` | `RELAY_PUBLIC_URL` | `http://127.0.0.1:8787` | 浏览器访问的公开地址 |
+| `--password` | `RELAY_PASSWORD` | *(空)* | 工作站接入密码（留空为公用 Relay） |
+| `--admin-token` | `RELAY_ADMIN_TOKEN` | *(空)* | `/admin` 管理后台操作员令牌 |
+| `--bind` | `RELAY_BIND` | `127.0.0.1` | 监听地址 |
+| `--port` | `RELAY_PORT` | `8787` | 监听端口 |
+| `--trust-proxy` | `RELAY_TRUST_PROXY` | `0` | 信任 `X-Forwarded-For` 头（反代后设为 `1`） |
+| `--state-file` | `RELAY_AUTH_STATE_FILE` | `~/.local/state/herdr-remote-relay/relay-auth.json` | 认证状态文件路径 |
+| `--allowed-origins` | `RELAY_ALLOWED_ORIGINS` | *(同源)* | 允许的跨域源，逗号分隔 |
+| `--max-clients` | `RELAY_MAX_CLIENTS_PER_HOST` | `16` | 每台工作站最大客户端连接数 |
+| `--config` | `HERDR_RELAY_CONFIG` | *(无)* | JSON 配置文件路径 |
+
+反向代理必须转发 WebSocket `Upgrade` 头，并设置较长空闲超时时间。`deploy/` 目录下提供 nginx、systemd 与 Docker Compose 示例。
+
+## 工作站连接
+
+在工作站的 `herdr-remote` TUI 中进入 **Relay** 页面：
+- 访问方式选择 **自建 relay**
+- Relay 地址填写 `wss://herdr.example.com`
+- Relay 密码填写对应的 `RELAY_PASSWORD`
+
+验证连接状态：
+```bash
+curl https://herdr.example.com/healthz
+```
+
+## 开源协议
+
+MIT

package/bin/herdr-remote-relay.js

@@ -17,22 +17,21 @@ const USAGE = `herdr-remote-relay ${VERSION} — standalone relay for Herdr Remo
 Usage: herdr-remote-relay [options]
 
 Options:
-  --password <password>      Password a workstation must present (RELAY_PASSWORD).
-                             Leave unset for a public relay.
-  --admin-token <token>      Operator token for the relay dashboard (RELAY_ADMIN_TOKEN).
-  --deployment-mode <mode>   WebUI deployment mode: local or remote (default remote).
-  --public-url <url>         Public URL browsers use (RELAY_PUBLIC_URL)
+  --password <password>      Workstation password (RELAY_PASSWORD, empty for public)
+  --admin-token <token>      Admin dashboard token (RELAY_ADMIN_TOKEN)
+  --deployment-mode <mode>   Deployment mode: local or remote (default remote)
+  --public-url <url>         Public URL for browsers (RELAY_PUBLIC_URL)
   --bind <address>           Listen address (default 127.0.0.1, RELAY_BIND)
   --port <number>            Listen port (default 8787, RELAY_PORT)
-  --trust-proxy              Read X-Forwarded-For for rate limiting (RELAY_TRUST_PROXY)
-  --state-file <file>        Where device/host records are stored (RELAY_AUTH_STATE_FILE)
-  --allowed-origins <list>   Extra comma-separated browser origins (RELAY_ALLOWED_ORIGINS)
-  --max-clients <number>     Max browsers per workstation (RELAY_MAX_CLIENTS_PER_HOST)
-  --config <file>            JSON config file (also HERDR_RELAY_CONFIG)
-  -h, --help                 Show this help
-  -v, --version              Show the version
+  --trust-proxy              Trust X-Forwarded-For headers (RELAY_TRUST_PROXY)
+  --state-file <file>        Auth state file path (RELAY_AUTH_STATE_FILE)
+  --allowed-origins <list>   Allowed browser origins, comma-separated
+  --max-clients <number>     Max clients per workstation (default 16)
+  --config <file>            JSON config file (HERDR_RELAY_CONFIG)
+  -h, --help                 Show help
+  -v, --version              Show version
 
-See docs/self-hosted-relay.md.
+Guide: docs/self-hosted-relay.md
 `;
 
 function webUiBuilt() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "herdr-remote-relay",
-  "version": "0.2.0",
-  "description": "Standalone relay server for Herdr Remote: serves the mobile web terminal and brokers browser <-> workstation sessions",
+  "version": "0.2.2",
+  "description": "Standalone relay server and web terminal for Herdr Remote",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -37,7 +37,8 @@
     "src",
     "web/dist",
     "deploy",
-    "config.example.json"
+    "config.example.json",
+    "README.zh-CN.md"
   ],
   "scripts": {
     "build": "npm --prefix web run build",

package/src/auth-store.js

@@ -142,6 +142,69 @@ class AuthStore {
     return { deviceId, hostId: pairing.hostId, token, expiresAt, expiresAtIso: nowIso(expiresAt), publicUrl: pairing.publicUrl };
   }
 
+  /**
+   * Record how a device presented itself, so an operator revoking a device can
+   * tell which phone or laptop they are about to cut off. Only the coarse
+   * user agent string and the address are kept — never terminal content.
+   */
+  noteDeviceSeen(deviceId, { userAgent, ip } = {}, now = Date.now()) {
+    const device = this.state.devices[deviceId];
+    if (!device) return null;
+    let changed = false;
+    if (userAgent && device.userAgent !== userAgent) {
+      device.userAgent = String(userAgent).slice(0, 256);
+      changed = true;
+    }
+    if (ip && device.lastIp !== ip) {
+      device.lastIp = String(ip).slice(0, 64);
+      changed = true;
+    }
+    device.lastSeenAt = nowIso(now);
+    if (changed) this.save();
+    return { ...device };
+  }
+
+  /**
+   * Devices an operator may act on, newest first. Token hashes are never
+   * included: the dashboard has no use for them and they must not leave the
+   * process.
+   */
+  listDevices(now = Date.now()) {
+    return Object.values(this.state.devices)
+      .filter((device) => device && device.expiresAt > now)
+      .map((device) => ({
+        deviceId: device.deviceId,
+        hostId: device.hostId,
+        createdAt: device.createdAt,
+        lastSeenAt: device.lastSeenAt,
+        expiresAt: device.expiresAt,
+        expiresAtIso: nowIso(device.expiresAt),
+        userAgent: device.userAgent || null,
+        lastIp: device.lastIp || null,
+      }))
+      .sort((a, b) => String(b.lastSeenAt || '').localeCompare(String(a.lastSeenAt || '')));
+  }
+
+  /**
+   * Permanently invalidate a paired device. The stored hash is dropped, so the
+   * token it was derived from can never authenticate again. Returns the removed
+   * record so the caller can also close whatever sockets it still holds.
+   */
+  revokeDevice(deviceId) {
+    if (typeof deviceId !== 'string' || !deviceId) return null;
+    const device = this.state.devices[deviceId];
+    if (!device) return null;
+    delete this.state.devices[deviceId];
+    this.lastDeviceSaveAt.delete(deviceId);
+    this.save();
+    return {
+      deviceId: device.deviceId,
+      hostId: device.hostId,
+      userAgent: device.userAgent || null,
+      lastIp: device.lastIp || null,
+    };
+  }
+
   authenticateDevice(token, now = Date.now()) {
     if (typeof token !== 'string' || token.length < 16) return null;
     const tokenHash = hash(token);

package/src/metrics.js

@@ -92,15 +92,19 @@ class RelayMetrics {
     }
     const memory = process.memoryUsage();
     const load = os.loadavg();
-    const controller = clients.find((client) => client.role === 'controller');
+    // Every attached window has full input, so there is no "active controller"
+    // to name: reporting the first of them as one had an operator reading a
+    // distinction that does not exist. The host is still worth naming, and any
+    // client knows which workstation it is on.
+    const anyClient = clients[0];
     return {
       version: this.version,
       protocolVersion: this.protocolVersion,
       uptimeSeconds: Math.floor((now - this.startedAt) / 1000),
       startTime: new Date(this.startedAt).toISOString(),
       serverTime: new Date(now).toISOString(),
-      activeControllerId: controller?.id || null,
-      activeHostId: controller?.hostId || hosts[0]?.id || null,
+      activeControllerId: null,
+      activeHostId: anyClient?.hostId || hosts[0]?.id || null,
       clients,
       hosts,
       ptys,