@bom0792/herdgate 0.9.27 → 0.9.29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DEPLOY.md +314 -0
- package/DESIGN.md +216 -0
- package/README.md +100 -52
- package/bin/herdgate.mjs +17 -1
- package/dist-readme.md +22 -6
- package/package.json +3 -1
- package/windows/install-cli.mjs +70 -14
- package/windows/node-runtime.mjs +26 -0
- package/windows/setup-tui.mjs +18 -2
package/DEPLOY.md
ADDED
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
# Deploying herdgate publicly (cloudflared, this machine)
|
|
2
|
+
|
|
3
|
+
The cloud binds `127.0.0.1` and is published through a Cloudflare tunnel. Two shapes:
|
|
4
|
+
|
|
5
|
+
## A. Quick tunnel (no DNS setup, throwaway URL)
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
# terminal 1 — the cloud
|
|
9
|
+
cd /home/bom/source/herdgate
|
|
10
|
+
export HERDGATE_ACCOUNT_TOKEN=$(openssl rand -base64 32)
|
|
11
|
+
export HERDGATE_STATE=$HOME/.herdgate/state.json
|
|
12
|
+
npm start
|
|
13
|
+
|
|
14
|
+
# terminal 2 — a trycloudflare URL (random, changes every run)
|
|
15
|
+
cloudflared tunnel --url http://127.0.0.1:8787
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Use the printed `https://<random>.trycloudflare.com` as the public URL. Nothing to configure; fine for testing.
|
|
19
|
+
|
|
20
|
+
## B. Named tunnel + your domain (stable hostname)
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
cloudflared tunnel login # once, picks a zone
|
|
24
|
+
cloudflared tunnel create herdgate
|
|
25
|
+
cloudflared tunnel route dns herdgate herd.example.com
|
|
26
|
+
|
|
27
|
+
cat > ~/.cloudflared/herdgate.yml <<'YML'
|
|
28
|
+
tunnel: herdgate
|
|
29
|
+
credentials-file: /home/bom/.cloudflared/<TUNNEL-ID>.json
|
|
30
|
+
ingress:
|
|
31
|
+
- hostname: herd.example.com
|
|
32
|
+
service: http://127.0.0.1:8787
|
|
33
|
+
- service: http_status:404
|
|
34
|
+
YML
|
|
35
|
+
|
|
36
|
+
cloudflared tunnel run --config ~/.cloudflared/herdgate.yml
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Then start the cloud with the hostname pinned:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
export HERDGATE_ACCOUNT_TOKEN=$(openssl rand -base64 32)
|
|
43
|
+
export HERDGATE_STATE=$HOME/.herdgate/state.json
|
|
44
|
+
export HERDGATE_PUBLIC_HOST=herd.example.com
|
|
45
|
+
export HERDGATE_PUBLIC_URL=https://herd.example.com
|
|
46
|
+
npm start
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`HERDGATE_PUBLIC_HOST` makes the gateway answer **only** that Host (421 otherwise); `HERDGATE_PUBLIC_URL` builds
|
|
50
|
+
the pairing links shown to hosts.
|
|
51
|
+
|
|
52
|
+
### Funnel vs Tunnel
|
|
53
|
+
|
|
54
|
+
- **Tunnel** (above): the hostname resolves for everyone, but traffic only flows for this tunnel — which is
|
|
55
|
+
what we want, because herdgate authenticates every request and socket itself (hello-first tokens). Use this.
|
|
56
|
+
- **Funnel** (`cloudflared tunnel --url … --hello-world` variants / funnel ingress) would additionally let
|
|
57
|
+
arbitrary internet clients terminate at your origin without a CF account — herdgate's gate is the only
|
|
58
|
+
protection then. It works with the same code (the gate never trusts CF headers), but adds no value and more
|
|
59
|
+
exposure. Not recommended.
|
|
60
|
+
|
|
61
|
+
## Rehearse before going live (edge-sim)
|
|
62
|
+
|
|
63
|
+
`npm run edge` runs a local Cloudflare-edge simulator: TLS termination + `Host` rewrite +
|
|
64
|
+
WebSocket Upgrade splice — byte-for-byte the origin-side job cloudflared does. It lets you
|
|
65
|
+
exercise the public contract (`expectedHost` pinning → 421 on wrong host, the PWA over
|
|
66
|
+
TLS, both wss legs) on this machine, with a throwaway dev cert:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
|
|
70
|
+
-keyout /tmp/edge-key.pem -out /tmp/edge-cert.pem -days 2 -nodes -subj "/CN=127.0.0.1"
|
|
71
|
+
|
|
72
|
+
HERDGATE_PUBLIC_HOST=gate.local HERDGATE_SSH_PORT=0 npm start # terminal 1
|
|
73
|
+
HERDGATE_TARGET_PORT=8787 HERDGATE_PINNED_HOST=gate.local \
|
|
74
|
+
HERDGATE_EDGE_CERT=/tmp/edge-cert.pem HERDGATE_EDGE_KEY=/tmp/edge-key.pem \
|
|
75
|
+
npm run edge # terminal 2
|
|
76
|
+
# → https://127.0.0.1:<port> (trust the cert or pass --ignore-certificate-errors)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Verified by `test/edge.test.ts` and a full headless-Chrome run: sign in → `online` →
|
|
80
|
+
machine online → pair read → live Herdr view + SSH hint, all over TLS with both wss legs
|
|
81
|
+
through the splice.
|
|
82
|
+
|
|
83
|
+
### A note on `trycloudflare.com` quick tunnels
|
|
84
|
+
|
|
85
|
+
On this machine, quick tunnels **register** but the edge answers **404** for the
|
|
86
|
+
trycloudflare hostname from both IPv4 and IPv6 — the free-for-all hostname space is
|
|
87
|
+
blocked somewhere between this machine and Cloudflare. **Named tunnels on your own zone
|
|
88
|
+
do not have this problem**: `gate.phuongnb.io.vn` (tunnel `herdgate`, id `dfc578ef`) is
|
|
89
|
+
live — PWA + CSP through the edge, owner + host wss legs through the edge, pairing and
|
|
90
|
+
the live Herdr view all verified in headless Chrome with the real Cloudflare cert (no
|
|
91
|
+
`--ignore-certificate-errors`). The live recipe on this machine:
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
cloudflared tunnel create herdgate
|
|
95
|
+
cloudflared tunnel route dns -f <tunnel-uuid> gate.phuongnb.io.vn # -f overwrites; the
|
|
96
|
+
# bare form once logged the WRONG tunnel id (fell back to config.yml) — always pass
|
|
97
|
+
# the UUID and check the log line says your tunnel id
|
|
98
|
+
# ~/.cloudflared/herdgate.yml → ingress gate.phuongnb.io.vn → http://127.0.0.1:8833
|
|
99
|
+
HERDGATE_PUBLIC_HOST=gate.phuongnb.io.vn HERDGATE_PORT=8833 HERDGATE_SSH_PORT=2299 npm start
|
|
100
|
+
cloudflared --config ~/.cloudflared/herdgate.yml tunnel run herdgate
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Gotchas hit along the way: port 8787 was already taken by the hermes webui (the old
|
|
104
|
+
`config.yml` routes `hermes.phuongnb.io.vn` there — an ingress clash would silently serve
|
|
105
|
+
the wrong app through our hostname), and running the gateway script without `&` in a
|
|
106
|
+
shell helper blocks forever. Local `curl http://127.0.0.1:8833/` returns **421** by
|
|
107
|
+
design — the gateway pins `Host: gate.phuongnb.io.vn`; that is the pinning contract
|
|
108
|
+
working, not a bug.
|
|
109
|
+
|
|
110
|
+
### The SSH leg — passwordless logins (publickey)
|
|
111
|
+
|
|
112
|
+
`hc machine add` shells out to the system `ssh`, which prefers keys and the agent and
|
|
113
|
+
refuses to answer prompts when it has no terminal. A device whose machine should add
|
|
114
|
+
it non-interactively registers that machine's public key first:
|
|
115
|
+
|
|
116
|
+
1. In the PWA, open the host's room → **SSH for the Herdr app**, select the exact device ID,
|
|
117
|
+
and add the controlling machine's public key. For Herdr Mobile, add the phone's public key to
|
|
118
|
+
its device ID instead. Do not edit the publisher's `authorized_keys` or copy a private key.
|
|
119
|
+
2. Confirm the fingerprint presented by the client matches the Gate's known SSH host fingerprint.
|
|
120
|
+
Pin that key; the TCP edge does not present the VPS admin SSH key.
|
|
121
|
+
3. Use the room's device ID as the SSH username. For example, a Core client can run
|
|
122
|
+
`hc machine add d_device@ssh.example.com:2299`. On Mobile, use the reachable TCP edge
|
|
123
|
+
hostname or IPv4 address and port in the machine settings. Password auth with the paired
|
|
124
|
+
device secret also works.
|
|
125
|
+
|
|
126
|
+
The REST surface (same two identities as `/v1/device/push`: the device's own secret,
|
|
127
|
+
or the account token): `GET/POST/DELETE /v1/device/sshkey`. Ed25519, RSA and ECDSA
|
|
128
|
+
(nistp256/384/521) keys are accepted; signatures are verified per RFC 4252 §7.
|
|
129
|
+
|
|
130
|
+
## The SSH leg is not a Cloudflare-TCP leg — three ways in
|
|
131
|
+
|
|
132
|
+
Phones speak plain SSH to `host:port`; Cloudflare Tunnel only carries TCP for clients
|
|
133
|
+
running `cloudflared access`, which the phone does not. Reachability options, in order
|
|
134
|
+
of setup cost:
|
|
135
|
+
|
|
136
|
+
1. **LAN / same network** — `HERDGATE_SSH_BIND=0.0.0.0`, phones dial the machine.
|
|
137
|
+
2. **IPv6 AAAA** (this machine's setup) — a DNS-only `AAAA` record to the gate
|
|
138
|
+
machine's global IPv6; `~/.local/bin/herdgate-ssh-ddns` + the `herdgate-ddns`
|
|
139
|
+
timer keep it current (needs a Cloudflare API token + `ufw allow`).
|
|
140
|
+
3. **Tokenless TCP edge (recommended for a VPS)** — one TCP connection from Herdr
|
|
141
|
+
Mobile maps to one WSS connection to the public gate. The edge never terminates
|
|
142
|
+
SSH. Use the existing Herdgate SSH host key on the phone, not the VPS admin key.
|
|
143
|
+
|
|
144
|
+
### Deploy the tokenless TCP edge on a VPS
|
|
145
|
+
|
|
146
|
+
Use a public IPv4 VPS with Node 22+ installed system-wide. Build the standalone
|
|
147
|
+
JavaScript on a machine with TypeScript-enabled Node 22.18+ before copying it to
|
|
148
|
+
the VPS (Ubuntu's packaged Node may not support running `.ts` directly):
|
|
149
|
+
|
|
150
|
+
```sh
|
|
151
|
+
node --input-type=module -e 'import { readFileSync } from "node:fs"; import { stripTypeScriptTypes } from "node:module"; process.stdout.write(stripTypeScriptTypes(readFileSync("src/cloud/ssh-tcp-edge.ts", "utf8")))' > /tmp/ssh-tcp-edge.mjs
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Copy the output to `/opt/herdgate-tcp-edge/ssh-tcp-edge.mjs` and install only the
|
|
155
|
+
locked `ws` version there (`npm install --save-exact --omit=dev --ignore-scripts --prefix /opt/herdgate-tcp-edge ws@8.23.0`).
|
|
156
|
+
Install `templates/herdgate-tcp-edge.service` into `/etc/systemd/system/` (adjust
|
|
157
|
+
`ExecStart` if Node is not at `/usr/bin/node`), and put this in
|
|
158
|
+
`/etc/herdgate-tcp-edge.env`:
|
|
159
|
+
|
|
160
|
+
```dotenv
|
|
161
|
+
HERDGATE_URL=https://gate.phuongnb.io.vn
|
|
162
|
+
HERDGATE_TCP_EDGE_BIND=0.0.0.0
|
|
163
|
+
HERDGATE_TCP_EDGE_PORT=2299
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Do **not** copy any Herdgate credential or SSH host key to the VPS. Enable the unit
|
|
167
|
+
with `sudo systemctl enable --now herdgate-tcp-edge` and allow TCP 2299 in the VPS
|
|
168
|
+
provider and OS firewalls. Restrict the VPS's separate admin SSH access. The edge
|
|
169
|
+
caps concurrent sessions at 3 per IP and 6 total by default; the gate's own tunnel
|
|
170
|
+
caps still apply, and the gate may see several clients as one source behind a proxy.
|
|
171
|
+
|
|
172
|
+
Test `VPS_IP:2299` with the existing mobile username and key over cellular before
|
|
173
|
+
changing DNS. Confirm the host key matches the gate's pinned fingerprint. To switch
|
|
174
|
+
`ssh.phuongnb.io.vn`, add a DNS-only `A` record for the VPS and remove the old `AAAA`
|
|
175
|
+
unless it also points to a verified edge. Disable the old home AAAA DDNS timer if
|
|
176
|
+
using that hostname for the VPS. Keep the HTTPS hostname unchanged.
|
|
177
|
+
|
|
178
|
+
### Legacy authenticated SSH bridge
|
|
179
|
+
|
|
180
|
+
The older SSH bridge is also available, but requires an account owner token on
|
|
181
|
+
its VPS and shares one upstream connection:
|
|
182
|
+
|
|
183
|
+
```sh
|
|
184
|
+
# on the VPS (Node ≥ 22, one file, no dependencies):
|
|
185
|
+
node ssh-bridge.ts # env: HERDGATE_URL, HERDGATE_BRIDGE_TOKEN (the account token),
|
|
186
|
+
# HERDGATE_BRIDGE_BIND/PORT (default 0.0.0.0:2299),
|
|
187
|
+
# HERDGATE_BRIDGE_PUBLIC_HOST/PORT — advertise what phones dial
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The bridge dials the cloud over an OUTBOUND WebSocket and pipes raw SSH bytes both
|
|
191
|
+
ways; the cloud feeds them into its sshd through ssh2's `injectSocket`. Device-key
|
|
192
|
+
auth, act-scope enforcement, the read-only allowlist and brute-force strikes all stay
|
|
193
|
+
in the cloud. The legacy bridge credential is the account (owner) token. While a bridge with an advertised address is connected, the
|
|
194
|
+
device hello's `ssh {host, port}` points phones at it; disconnect it and the hello
|
|
195
|
+
falls back to the gate's own address. Verified end to end through the real Cloudflare
|
|
196
|
+
tunnel: pair over wss → SSH the bridge → `hello` (32 methods), `server.status`, and
|
|
197
|
+
`terminal.send` refused with the act-scope error.
|
|
198
|
+
|
|
199
|
+
The public HTTP/WSS surface continues to go through the tunnel.
|
|
200
|
+
|
|
201
|
+
### When the publisher and gateway run on the same machine
|
|
202
|
+
|
|
203
|
+
Set `HERDGATE_AGENT_LOOPBACK_PORT=8833` in the publisher's `herdgate.env`
|
|
204
|
+
(use the gateway's actual port). Keep `HERDGATE_URL` set to the canonical public
|
|
205
|
+
URL. The publisher dials `127.0.0.1` with the public `Host` header, so gateway host
|
|
206
|
+
validation and room-token authentication still apply. This opt-in mode uses the
|
|
207
|
+
existing `ws` dependency from the npm installation; the standalone plugin uses
|
|
208
|
+
Node's native WebSocket by default. Restart only the publisher. Remove the line
|
|
209
|
+
to restore the public transport. No client SSH configuration changes are needed.
|
|
210
|
+
|
|
211
|
+
## Keep it running
|
|
212
|
+
|
|
213
|
+
On this machine (Linux + systemd) a user unit keeps the gate up; the tunnel is a second unit:
|
|
214
|
+
|
|
215
|
+
```sh
|
|
216
|
+
mkdir -p ~/.config/systemd/user
|
|
217
|
+
cat > ~/.config/systemd/user/herdgate.service <<'UNIT'
|
|
218
|
+
[Unit]
|
|
219
|
+
Description=herdgate cloud relay hub
|
|
220
|
+
After=network-online.target
|
|
221
|
+
|
|
222
|
+
[Service]
|
|
223
|
+
ExecStart=/home/bom/.nvm/versions/node/v22.23.1/bin/node /home/bom/source/herdgate/src/cloud/main.ts
|
|
224
|
+
Environment=HERDGATE_ACCOUNT_TOKEN=change-me
|
|
225
|
+
Environment=HERDGATE_PUBLIC_HOST=gate.phuongnb.io.vn
|
|
226
|
+
Environment=HERDGATE_PORT=8833
|
|
227
|
+
Environment=HERDGATE_STATE=/home/bom/.local/state/herdgate/state.json
|
|
228
|
+
WorkingDirectory=/home/bom/source/herdgate
|
|
229
|
+
Restart=always
|
|
230
|
+
RestartSec=3
|
|
231
|
+
|
|
232
|
+
[Install]
|
|
233
|
+
WantedBy=default.target
|
|
234
|
+
UNIT
|
|
235
|
+
systemctl --user daemon-reload && systemctl --user enable --now herdgate
|
|
236
|
+
# tunnel: cloudflared --config ~/.cloudflared/herdgate.yml tunnel run herdgate
|
|
237
|
+
# (a second unit wrapping that line, same shape)
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Other platforms:
|
|
241
|
+
|
|
242
|
+
```sh
|
|
243
|
+
# launchd agent sketch (adjust paths); or use tmux/systemd-in-wsl as you prefer
|
|
244
|
+
cat > ~/Library/LaunchAgents/dev.herdgate.cloud.plist <<'PLIST'
|
|
245
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
246
|
+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
247
|
+
<plist version="1.0"><dict>
|
|
248
|
+
<key>Label</key><string>dev.herdgate.cloud</string>
|
|
249
|
+
<key>ProgramArguments</key><array>
|
|
250
|
+
<string>/Users/bom/.nvm/versions/node/v22.23.1/bin/node</string>
|
|
251
|
+
<string>/home/bom/source/herdgate/src/cloud/main.ts</string>
|
|
252
|
+
</array>
|
|
253
|
+
<key>RunAtLoad</key><true/>
|
|
254
|
+
<key>KeepAlive</key><true/>
|
|
255
|
+
<key>EnvironmentVariables</key><dict>
|
|
256
|
+
<key>HERDGATE_ACCOUNT_TOKEN</key><string>…</string>
|
|
257
|
+
<key>HERDGATE_STATE</key><string>/Users/bom/.herdgate/state.json</string>
|
|
258
|
+
<key>HERDGATE_PUBLIC_HOST</key><string>herd.example.com</string>
|
|
259
|
+
<key>HERDGATE_PUBLIC_URL</key><string>https://herd.example.com</string>
|
|
260
|
+
</dict>
|
|
261
|
+
</dict></plist>
|
|
262
|
+
PLIST
|
|
263
|
+
launchctl load ~/Library/LaunchAgents/dev.herdgate.cloud.plist
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
(The plist above is a sketch — fill the token, keep `node` on your PATH or use the absolute binary.)
|
|
267
|
+
|
|
268
|
+
## Migrate the Linux TUI publisher
|
|
269
|
+
|
|
270
|
+
On the host, use Node 22+ and run as the user who owns the running Herdr TUI
|
|
271
|
+
and the systemd user unit. Verify publisher/remote access before starting and
|
|
272
|
+
pick a window when a short remote disconnection is acceptable:
|
|
273
|
+
|
|
274
|
+
```sh
|
|
275
|
+
systemctl --user is-active herdgate-home-tui.service
|
|
276
|
+
herdr status server --json
|
|
277
|
+
npx --yes @bom0792/herdgate@latest migrate
|
|
278
|
+
npx --yes @bom0792/herdgate@latest status
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
For a new host with no previous publisher unit, use `herdgate setup` after
|
|
282
|
+
pairing instead. Migration only adopts the known legacy Herdgate home unit.
|
|
283
|
+
It stages the publisher under `${XDG_DATA_HOME:-$HOME/.local/share}/herdgate/home-tui/releases`,
|
|
284
|
+
reuses the existing room config, and checks for a Gate hello from the new
|
|
285
|
+
systemd invocation. If the new publisher cannot connect, it attempts to
|
|
286
|
+
restore the previous service. It does not stop or update the Herdr server.
|
|
287
|
+
If Herdr's executable or socket is not at the default path, pass
|
|
288
|
+
`HERDR_BIN_PATH` and/or `HERDR_SOCKET_PATH` when running setup or update.
|
|
289
|
+
|
|
290
|
+
After success, reconnect from the remote Herdr TUI and confirm the existing
|
|
291
|
+
session is reachable. If migration fails, check
|
|
292
|
+
`journalctl --user -u herdgate-home-tui.service` locally; do not re-pair or
|
|
293
|
+
share tokens or keys. Use `herdgate update` for later main-publisher updates.
|
|
294
|
+
|
|
295
|
+
### Upgrade boundaries
|
|
296
|
+
|
|
297
|
+
- The publisher CLI updates the main TUI service only. It does not deploy
|
|
298
|
+
the Gate, web/PWA, Cloudflare tunnel, VPS TCP edge, or independent Mobile
|
|
299
|
+
read/control services. Maintain and verify those separately.
|
|
300
|
+
- Herdr Mobile Core, Mobile TUI read and Mobile TUI control are different
|
|
301
|
+
targets. Preserve the room, SSH key and scope of each entry. Do not turn a
|
|
302
|
+
read device into an interactive device just to resolve a connection issue.
|
|
303
|
+
- If several phone entries use the same public IP and a new one cannot
|
|
304
|
+
connect, close unused entries and retry. Check the TCP edge logs before
|
|
305
|
+
attributing the failure to the connection limits.
|
|
306
|
+
|
|
307
|
+
## Operational notes
|
|
308
|
+
|
|
309
|
+
- Preserve the Gate state and SSH host key in protected backups. Deleting
|
|
310
|
+
state loses room/device registrations; replacing the host key invalidates
|
|
311
|
+
clients' pins.
|
|
312
|
+
- **Rotate the account token** by restarting with a new `HERDGATE_ACCOUNT_TOKEN` (devices must update it).
|
|
313
|
+
- **Logs** go to stderr (agent connect/pair events). Payloads are never logged — keep it that way.
|
|
314
|
+
- **Watch the exposure**: `curl -s https://host/healthz` public; everything else needs tokens.
|
package/DESIGN.md
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# herdgate — design
|
|
2
|
+
|
|
3
|
+
Architecture and trust boundaries. For installation and upgrade commands, see [README.md](README.md) and
|
|
4
|
+
[DEPLOY.md](DEPLOY.md).
|
|
5
|
+
|
|
6
|
+
## 1. What herdgate is
|
|
7
|
+
|
|
8
|
+
A relay hub between **host apps** and **devices** (browsers, PWAs). The first host target is official
|
|
9
|
+
[Herdr](https://herdr.dev). A herdgate-owned local adapter will use a verified upstream interface; the adapter
|
|
10
|
+
runs on the host and the agent connects outbound to the gateway. No fork, third-party plugin, or relay project
|
|
11
|
+
is required. The hub handles identity, routing, and presence; content and policy stay in the host adapter. Payloads crossing the cloud are **opaque by rule**: the cloud never parses, logs or
|
|
12
|
+
persists them.
|
|
13
|
+
|
|
14
|
+
Three deployment properties:
|
|
15
|
+
|
|
16
|
+
1. Hosts and devices both connect **outbound**; only the cloud is publicly reachable (via cloudflared on the
|
|
17
|
+
machine that runs it).
|
|
18
|
+
2. The cloud is the **identity provider**. No Cloudflare Access in front, no trusted proxy headers. If
|
|
19
|
+
`HERDGATE_PUBLIC_HOST` is set, the Host header is enforced (anti host-confusion) but nothing else about the
|
|
20
|
+
edge is trusted.
|
|
21
|
+
3. Single-owner v0: accounts come from config (env tokens). Multi-account signup is roadmap, not code.
|
|
22
|
+
|
|
23
|
+
## 2. Identity: accounts, rooms, devices
|
|
24
|
+
|
|
25
|
+
| Layer | Who | Credential | Minted by |
|
|
26
|
+
|---|---|---|---|
|
|
27
|
+
| account | a person | config token (v0) | operator (env) |
|
|
28
|
+
| room | one host app | room token (random 32B, stored **hashed**) | device-flow approval |
|
|
29
|
+
| device | one room-scoped browser or SSH client | device ID + device secret, or registered SSH public key for SSH auth | `pair.begin` and key registration |
|
|
30
|
+
|
|
31
|
+
- **Host provisioning (device flow).** The host mints a code (`POST /v1/agent/code`), a human approves it from a
|
|
32
|
+
logged-in device (`POST /v1/agent/approve`), the host polls `GET /v1/agent/code/:code/status` and receives the
|
|
33
|
+
room token exactly once. The host stores it; re-provisioning rotates it.
|
|
34
|
+
- **Device pairing.** A device hellos with its account token, then `pair.begin {roomId, name, scope}`.
|
|
35
|
+
`read` pairs immediately. `act` triggers `pair.request` **down to the host** — the human approves on the host
|
|
36
|
+
(approve-on-host), the cloud grants on `pair.response`. Timeout 60s → denied.
|
|
37
|
+
- **Scopes.** `read` = view; `act` = may cause effects. The cloud knows scopes and reports them
|
|
38
|
+
(`room.update`, `hello.devices`), but **enforcement of what an `act` payload may do is host-side** — the cloud
|
|
39
|
+
cannot see payloads. This split is deliberate (see §5).
|
|
40
|
+
|
|
41
|
+
## 3. Wire protocol (v1)
|
|
42
|
+
|
|
43
|
+
One JSON object per WS text frame: `{v:1, t:"…", …}`. Unknown `v` → close. Legs:
|
|
44
|
+
|
|
45
|
+
- `GET /v1/agent/ws` — host leg. `hello {roomToken, info}` first (10s deadline, else close 4001). Then
|
|
46
|
+
`frame {device, payload}` ⇄, `presence`, `pair.request`/`pair.response`, `ping`/`pong`, `room.update`.
|
|
47
|
+
One live agent per room: a second connection supersedes the first (4000).
|
|
48
|
+
- `GET /v1/device/ws` — device leg. `hello {accountToken | device+deviceSecret, resume?}` first. Then `frame {payload}`
|
|
49
|
+
(routed to the paired room's host), `pair.begin` → `pair.granted`/`pair.denied`, `presence`, `ping`/`pong`.
|
|
50
|
+
|
|
51
|
+
### Room streams and resume (v0.6.0)
|
|
52
|
+
|
|
53
|
+
Every host→device message that matters while a phone is away (frames, presence) carries a
|
|
54
|
+
room-scoped `seq` and is buffered briefly (last 256 KiB / 120 s per room). Device hello
|
|
55
|
+
responses carry a `stream {gen, seq}` header; a reconnecting device adds
|
|
56
|
+
`resume {room, gen, seq}` to its hello and receives `resumed:true` plus the buffered tail
|
|
57
|
+
in order. `gen` changes on every gateway process start, so stale bookkeeping from a
|
|
58
|
+
previous life invalidates in one comparison — the device gets a fresh hello (`resumed:false`)
|
|
59
|
+
and re-requests state. A resume from before what was kept answers `stream.gap:true`
|
|
60
|
+
(replay what survived; the device re-requests its view). Frames with an `ssh.*` op are
|
|
61
|
+
**ephemeral**: sent raw, unstamped, never buffered — they belong to an SSH channel that
|
|
62
|
+
died with the drop, and replaying them into a new SSH session would corrupt its wire
|
|
63
|
+
protocol. `pair.granted` (carries the one-time device secret) is likewise never replayed.
|
|
64
|
+
|
|
65
|
+
HTTP: `GET /healthz`, `POST /v1/agent/code`, `POST /v1/agent/approve` (bearer account token),
|
|
66
|
+
`GET /v1/agent/code/:code/status`.
|
|
67
|
+
|
|
68
|
+
Limits: frames 256 KiB (`maxPayload`), 60 msg/s per socket (token bucket), hello within 10s, failed-hello
|
|
69
|
+
strikes per IP (5/min → 60s block), and WebSocket heartbeat pings (8s by default) with termination on silence.
|
|
70
|
+
|
|
71
|
+
## 4. State
|
|
72
|
+
|
|
73
|
+
`state.json` (atomic tmp+rename, 0600): rooms (token hashed) + devices. In-memory pending pairing codes never
|
|
74
|
+
touch disk. v0 loses open sockets on restart; the room stream resumes devices after a drop (§3), and the `gen`
|
|
75
|
+
header makes a restart a clean re-sync rather than a wrong replay.
|
|
76
|
+
|
|
77
|
+
## 5. Threat model — what the cloud promises
|
|
78
|
+
|
|
79
|
+
| Threat | Mitigation (v0) |
|
|
80
|
+
|---|---|
|
|
81
|
+
| Guessing a room token / account token | 256-bit random, hashed at rest, constant-time compare, failed-hello strikes |
|
|
82
|
+
| Brute-forcing pairing codes | 8-char no-lookalike alphabet, 10-min TTL, single retrieval, rate-limited mint per IP |
|
|
83
|
+
| A stolen `act` device | approve-on-host at pair time; host re-confirmation of dangerous ops is host policy |
|
|
84
|
+
| Hostile room claiming | codes bound to the approving account; rooms never cross accounts |
|
|
85
|
+
| DoS | per-IP blocks, per-socket rate, frame caps, supersede rule, unbounded fan-out is a bug |
|
|
86
|
+
| Cloud reading content | Gate routes application frames without interpreting them; only a negotiated Noise session protects that payload from the Gate. SSH terminates at the Gate. |
|
|
87
|
+
| Host confusion via cloudflared | optional `expectedHost` pin; nothing else about the edge is trusted |
|
|
88
|
+
|
|
89
|
+
Per-device secrets and Noise_XX payload sessions now exist. Noise applies to its own application payload
|
|
90
|
+
channel, not to SSH, which terminates at the Gate. Do not infer that all payloads use Noise or that the
|
|
91
|
+
single-owner deployment model provides multi-tenant isolation.
|
|
92
|
+
|
|
93
|
+
## 6. Roadmap
|
|
94
|
+
|
|
95
|
+
1. ~~**Per-device secrets**~~ — **done (v0.5.0)**: `pair.granted` returns a device secret once; hello uses it;
|
|
96
|
+
the account token stays in the dashboard only (and is never an SSH credential).
|
|
97
|
+
2. ~~**Resume**~~ — **done (v0.6.0)**: room streams with `seq`/`gen`, a bounded replay buffer, gap declaration;
|
|
98
|
+
see §3. Ciphertext-friendly by construction (the buffer stores opaque envelopes).
|
|
99
|
+
3. ~~**E2E payloads**~~ — **done (v0.7.0)**: Noise_XX (P-256/SHA-256/AES-256-GCM, WebCrypto-only so the
|
|
100
|
+
plugin and the PWA run one identical module) over the payload channel; the device initiates after
|
|
101
|
+
pairing, the host acks with `e2e.ready` (nothing encrypts before the ack — a frame racing the
|
|
102
|
+
handshake's last step would desync the counters forever), and a decrypt failure drops the session for
|
|
103
|
+
renegotiation. Host static key is TOFU: the device pins its fingerprint and screams if it changes.
|
|
104
|
+
See DESIGN §3 and `plugin/server/e2e.mjs`.
|
|
105
|
+
4. ~~**Official Herdr adapter**~~ — **done (v0.1.0)**, read-only. `src/host/herdr.ts` runs
|
|
106
|
+
`herdr api snapshot` (verified on Herdr 0.9.5, protocol 22) and maps `workspaces[]`, `tabs[]`, `panes[]`,
|
|
107
|
+
`agents[]` and the focused ids into a versioned view. Device ops are `view` and `ping`; every other op is
|
|
108
|
+
refused on the host with `read-only`. Next in this line: an `act` op set once per-op policy and audit exist.
|
|
109
|
+
5. **Device PWA** — shipped: pairing, multi-room dashboard, per-device SSH key management and read-only pane views.
|
|
110
|
+
5b. **SSH through the Gate** — shipped: per-device public keys, TUI bridge, real Core and the scoped Mobile
|
|
111
|
+
TUI adapter (see §8).
|
|
112
|
+
5c. **SSH without inbound publisher ports** — shipped: SSH over WSS for desktop clients and a tokenless
|
|
113
|
+
TCP edge for Mobile. The old owner-token SSH bridge is a separate legacy deployment.
|
|
114
|
+
6. ~~**Push wake**~~ — **done (v0.8.0)**: VAPID keys beside the state file; a paired device stores its web-push
|
|
115
|
+
subscription (`/v1/device/push`); the host sends `wake {device}` and the cloud delivers a silent,
|
|
116
|
+
payload-less push — but only when the device is not connected (a connected one is already live). The
|
|
117
|
+
PWA's service worker raises a notification only when no window is open.
|
|
118
|
+
7. Multi-account signup, quotas, Postgres state, audit log.
|
|
119
|
+
|
|
120
|
+
## 7. Host payload contract (herdgate.herdr.v1)
|
|
121
|
+
|
|
122
|
+
The cloud routes `payload` blind, so the host and its devices own their own schema. Current ops:
|
|
123
|
+
|
|
124
|
+
| Direction | Message | Reply |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| device → host | `{op:"view"}` | `{op:"view", view}` (lazy read if none yet) |
|
|
127
|
+
| device → host | `{op:"ping", n?}` | `{op:"pong", n, at}` |
|
|
128
|
+
| host → device | `{op:"view", view}` | pushed when the view changes, and to a newly paired device |
|
|
129
|
+
| host → device | `{op:"error", code, message}` | `read-only` for any other op; `host-unavailable` when Herdr cannot be read |
|
|
130
|
+
|
|
131
|
+
`view` = `{v:1, source:"herdr", herdrVersion, protocol, takenAt, focused{workspaceId,tabId,paneId},
|
|
132
|
+
workspaces[{id,label,number,tabs,panes,agentStatus,focused}], agents[{name,kind,status,workspaceId,tabId,paneId,cwd,title}]}`.
|
|
133
|
+
A new Herdr version that adds keys keeps working (every field is read defensively); a missing key degrades to an
|
|
134
|
+
empty/honest value rather than throwing.
|
|
135
|
+
|
|
136
|
+
The table describes the standalone metadata adapter. The TUI publisher also exposes read-only
|
|
137
|
+
`term.list` and `term.read` for the PWA. Browser payload operations do not grant terminal input;
|
|
138
|
+
SSH access is a separate channel with its own authorization.
|
|
139
|
+
|
|
140
|
+
## 8. How herdgate attaches to Herdr (official surface only)
|
|
141
|
+
|
|
142
|
+
Herdr is not forked, patched, or re-implemented. herdgate is a **Herdr plugin**: a directory with
|
|
143
|
+
`herdr-plugin.toml` whose commands Herdr validates, launches, and logs — the surface Herdr documents for
|
|
144
|
+
extensions (`docs/plugins.mdx`) and lists in the marketplace (`herdr-plugin` GitHub topic, `/tui/plugins/`).
|
|
145
|
+
|
|
146
|
+
| Manifest entry | Command | Why |
|
|
147
|
+
|---|---|---|
|
|
148
|
+
| `[[startup]]` | `node server/index.mjs serve` | Herdr runs it once after the socket API is ready; it spawns the long-lived publisher and exits, so a failed publisher cannot fail the Herdr server |
|
|
149
|
+
| `[[actions]]` | `pair`, `status`, `stop` | the human-facing operations, invoked as `herdr plugin action invoke dev.herdgate.host.pair` |
|
|
150
|
+
| `[[panes]]` | `node server/index.mjs pane` | a `split` pane inside Herdr showing honest publish state (light 10s poll) |
|
|
151
|
+
|
|
152
|
+
Two official surfaces are used, one per program: the **plugin** (§ above, `herdr-plugin.toml`) for the TUI, and
|
|
153
|
+
the **app mod** (§ below, `mods/<name>/`) for the desktop app.
|
|
154
|
+
|
|
155
|
+
The plugin uses Herdr's CLI for metadata and pane reads, and fixed Herdr bridge commands for remote TUI
|
|
156
|
+
connections. The interactive Mobile adapter additionally uses Herdr's native terminal session control.
|
|
157
|
+
These integrations use the running TUI server's configured executable and socket, not a second Herdr
|
|
158
|
+
server. Nothing patches Herdr.
|
|
159
|
+
|
|
160
|
+
Credentials go in `HERDR_PLUGIN_CONFIG_DIR`, not the managed plugin checkout; runtime state goes in
|
|
161
|
+
`HERDR_PLUGIN_STATE_DIR`. The standalone plugin uses Node's native `WebSocket`; the opt-in Linux Gate
|
|
162
|
+
loopback transport uses the bundled `ws` dependency.
|
|
163
|
+
|
|
164
|
+
Note on Herdr's moving parts: the **TUI** (`herdr`) exposes workspaces/tabs/panes/agents; **herdr-core** (`hc`)
|
|
165
|
+
is the separate runtime under the Herdr app and its iPhone/iPad/Android app, with a JSON-RPC API of its own.
|
|
166
|
+
The plugin attaches to the TUI's documented CLI.
|
|
167
|
+
|
|
168
|
+
### The Herdr app mod (`app-mod/herdgate/`)
|
|
169
|
+
|
|
170
|
+
The desktop app extends through **mods**, a different official surface (`docs/mods.md`,
|
|
171
|
+
`defaults/AGENTS.md`): `mods/<name>/` with `mod.json` + `main.js`, written in gpui-kit. A mod is trusted code
|
|
172
|
+
with `fetch`, `exec`, and unrestricted network — but **no Node globals** (`process`, `require`, `setTimeout`
|
|
173
|
+
are absent). Verified in a real window: `herdr-app check` passes, `mod.open` reports `overlays:["herdgate"]`
|
|
174
|
+
with `errors: []`, and a probe mod reached a live herdgate cloud with `fetch` (HTTP 200).
|
|
175
|
+
|
|
176
|
+
The mod and the TUI plugin share one publisher: the mod owns the pairing conversation (mint a code, poll,
|
|
177
|
+
write the token 0600) and shells out to `plugin/server/index.mjs serve` for the long-lived connection. One
|
|
178
|
+
implementation, two surfaces.
|
|
179
|
+
|
|
180
|
+
### SSH clients: TUI, real Core and the Mobile TUI adapter
|
|
181
|
+
|
|
182
|
+
The Gate (`src/cloud/sshd.ts`) terminates SSH and authenticates the device ID with its registered public
|
|
183
|
+
key or device secret, never with the owner token. Each exec is an ephemeral channel bound to the
|
|
184
|
+
authenticated device and room. The publisher dispatches supported commands to fixed argv, not a shell.
|
|
185
|
+
A VPS TCP edge, when used, carries raw SSH over WSS and holds no Gate credentials; the client verifies
|
|
186
|
+
and pins the Gate's SSH host key. SSH channels are not replayed or resumed after a disconnect.
|
|
187
|
+
|
|
188
|
+
| Target | Host scope enforcement |
|
|
189
|
+
|---|---|
|
|
190
|
+
| Existing Herdr TUI via the desktop TUI bridge | `act` only; the native two-way bridge is not a read filter. |
|
|
191
|
+
| Real `herdr-core` | A `read` device gets filtered plain JSON-RPC; framed hello is downgraded. Approved `act` gets byte-transparent Core RPC. |
|
|
192
|
+
| Existing TUI panes via the Mobile adapter | Read/observe attaches show a text snapshot; no input or resize. An explicitly configured device with matching `act` scope can use Send, keys, Interrupt and native attach with ANSI, input and resize. |
|
|
193
|
+
|
|
194
|
+
The Mobile adapter speaks the Core protocol subset needed for those operations and rejects unsupported
|
|
195
|
+
RPCs. It does not implement Core task lifecycle, templates or file operations. See
|
|
196
|
+
`plugin/server/mobile-tui-core.mjs` and `plugin/server/mobile-tui-stream.mjs`.
|
|
197
|
+
|
|
198
|
+
### Publisher releases and migration
|
|
199
|
+
|
|
200
|
+
The platform-specific publisher runtime is installed outside npm's cache. On Windows `herdgate install`
|
|
201
|
+
installs a per-user, Node-pinned command from npm. First setup also provisions it. Its `command` junction
|
|
202
|
+
is separate from the publisher's `current` junction, so publisher rollback does not remove the command.
|
|
203
|
+
User PATH registration is optional and never changes the machine-wide PATH. Migration stages and validates
|
|
204
|
+
first, then saves the existing device mode only after the new publisher connects; failure triggers a
|
|
205
|
+
rollback attempt. On Linux the CLI installs a user systemd unit, recognizes only the known legacy home
|
|
206
|
+
unit for adoption, and checks the new invocation's Gate hello. Both preserve the room config and the
|
|
207
|
+
running Herdr server. The Gate, TCP edge, and standalone Linux Mobile publishers have independent
|
|
208
|
+
lifecycles.
|
|
209
|
+
|
|
210
|
+
## 9. Herdr-relay comparison (why a new project)
|
|
211
|
+
|
|
212
|
+
herdr-relay: Mac-local bridge, Tailscale identity, renders Herdr's mods in sandboxed processes, diffs trees
|
|
213
|
+
bridge-side. herdgate: the cloud in the middle, own identity, host renders, cloud routes opaque frames. The
|
|
214
|
+
ideas kept: hello-first auth, hashed tokens, scope-aware routing, single-use artifacts, rate limits everywhere.
|
|
215
|
+
The parts dropped: mod sandboxing (the host is trusted code on its own machine), tree recording (the host owns
|
|
216
|
+
its UI), Tailscale (public via cloudflared).
|
package/README.md
CHANGED
|
@@ -11,27 +11,24 @@ Both remote connections are outbound; the cloud gateway binds loopback.
|
|
|
11
11
|
|
|
12
12
|
- **One gate, three identities** — accounts (people), rooms (hosts), devices (browsers). Hosts pair by a
|
|
13
13
|
GitHub-style device flow; devices pair into a room; `act` scope needs the host's own approval.
|
|
14
|
-
- **
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
identity provider (no Cloudflare Access needed, none of its headers trusted).
|
|
14
|
+
- **Separate payload and SSH channels** — the relay routes application frames without interpreting their
|
|
15
|
+
contents, and the payload channel supports Noise_XX between device and host. SSH terminates at the Gate;
|
|
16
|
+
it is not client-to-publisher Noise E2E.
|
|
17
|
+
- **No inbound ports on publishers** — they dial out over WSS. Use a public HTTPS Gate for desktop TUI
|
|
18
|
+
connections. For Herdr Mobile on cellular, a [tokenless TCP edge](DEPLOY.md#deploy-the-tokenless-tcp-edge-on-a-vps)
|
|
19
|
+
can forward SSH to the Gate without VPN, without storing room or owner credentials on the VPS.
|
|
21
20
|
|
|
22
21
|
## Status
|
|
23
22
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
of it verified live through a real Cloudflare Tunnel (gate.phuongnb.io.vn), push subscription and all, and systemd user units (gateway, tunnel, publisher) keeping it alive.
|
|
23
|
+
| Client | What it connects to | What it can do |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| Browser/PWA | Herdgate publisher over HTTPS/WSS | View Herdr metadata and read pane snapshots; no terminal input |
|
|
26
|
+
| Herdr TUI | An existing Herdr TUI session over SSH/WSS | Connect and control it with an approved `act` device and its own SSH key |
|
|
27
|
+
| Herdr Mobile (Core) | A real `herdr-core` runtime over SSH | Core terminals and the Core API, subject to the device scope |
|
|
28
|
+
| Herdr Mobile (TUI adapter) | Existing Herdr TUI panes over SSH | Read-only snapshots, or opt-in Send, keys, Interrupt and native attach/resize for one approved `act` device; not the full Core API |
|
|
31
29
|
|
|
32
|
-
The
|
|
33
|
-
|
|
34
|
-
slice, by design. No third-party plugin or relay is a dependency — only Herdr's own CLI.
|
|
30
|
+
The Gateway also supports bounded room-stream resume and VAPID push wake. Pairing, publisher updates and
|
|
31
|
+
Mobile authorization are separate: changing the publisher release does not move a room or grant a new scope.
|
|
35
32
|
|
|
36
33
|
## Layout
|
|
37
34
|
|
|
@@ -108,8 +105,9 @@ Devices pair into the room and ask for `{op:"view"}`; the host answers with the
|
|
|
108
105
|
|
|
109
106
|
## The SSH leg (the Herdr phone app)
|
|
110
107
|
|
|
111
|
-
The phone app adds machines over SSH
|
|
112
|
-
|
|
108
|
+
The phone app adds machines over SSH. Herdgate terminates SSH at the Gate; use the Gate's reachable SSH
|
|
109
|
+
address or the TCP edge's address. Each entry uses the device ID and key for that room. A Core entry lands
|
|
110
|
+
on the host's real `herdr-core`; the opt-in TUI adapter described below lands on existing TUI panes instead:
|
|
113
111
|
|
|
114
112
|
```sh
|
|
115
113
|
ssh -p 2222 d_xxxxxxxx@your-gate # password = the device key shown once at pair time
|
|
@@ -121,11 +119,12 @@ ssh -p 2222 d_xxxxxxxx@your-gate # password = the device key shown once a
|
|
|
121
119
|
prompts without a terminal. Register the adding machine's `~/.ssh/id_ed25519.pub` in the PWA (SSH →
|
|
122
120
|
*Public keys*, or `POST /v1/device/sshkey`) and the add is passwordless — Ed25519/RSA/ECDSA, signatures
|
|
123
121
|
verified per RFC 4252 §7.
|
|
124
|
-
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
-
|
|
128
|
-
|
|
122
|
+
- For real Core, the host rejects mutating calls from `read` devices and downgrades their framed hello.
|
|
123
|
+
An approved `act` device gets byte-transparent Core RPC. The separate TUI adapter enforces its own
|
|
124
|
+
read-only and interactive allowlists.
|
|
125
|
+
- Herdgate only starts supported Core exec commands or fixed Herdr bridge commands. It does not offer
|
|
126
|
+
a generic SSH shell, SFTP or SSH port forwarding.
|
|
127
|
+
- Real Core mode requires `herdr-core` (`hc`); the TUI adapter does not.
|
|
129
128
|
|
|
130
129
|
**Note:** ssh2 1.17.0 has a malformed `server-sig-algs` EXT_INFO (a missing comma garbles the
|
|
131
130
|
algorithm list) that makes real OpenSSH clients silently abandon publickey auth right after
|
|
@@ -180,7 +179,18 @@ client-to-publisher Noise E2E. No third-party relay or inbound client port is ne
|
|
|
180
179
|
|
|
181
180
|
### Manage a paired publisher from one CLI
|
|
182
181
|
|
|
183
|
-
Install the command once
|
|
182
|
+
Install the command once (Node 22+). On Linux, use `npm install -g @bom0792/herdgate`.
|
|
183
|
+
On Windows, use the npm bootstrap instead; it installs the persistent command
|
|
184
|
+
without requiring admin rights, a separate global npm install, or a running publisher:
|
|
185
|
+
|
|
186
|
+
```powershell
|
|
187
|
+
npx --yes @bom0792/herdgate@latest install
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Open a new PowerShell after installation. In a shell with the old PATH, or if
|
|
191
|
+
User PATH registration is blocked, call
|
|
192
|
+
`& "$env:LOCALAPPDATA\Herdgate\cli\bin\herdgate.cmd"` with the same arguments.
|
|
193
|
+
Use `install --no-path` to create only that shim, without modifying User PATH.
|
|
184
194
|
Use your own cloud URL; there is no built-in Gate address.
|
|
185
195
|
|
|
186
196
|
```sh
|
|
@@ -211,15 +221,18 @@ rooms or upgrade the VPS.
|
|
|
211
221
|
### Windows as a TUI host
|
|
212
222
|
|
|
213
223
|
Use this only where remote control is approved by the machine's owner/IT.
|
|
214
|
-
With Node 22+ on Windows and an existing Gate pairing,
|
|
215
|
-
|
|
224
|
+
With Node 22+ on Windows and an existing Gate pairing, install and start the
|
|
225
|
+
TUI publisher (add the relevant Mobile flag if enabled):
|
|
216
226
|
|
|
217
227
|
```powershell
|
|
218
|
-
npx --yes @bom0792/herdgate@latest
|
|
219
|
-
npx --yes @bom0792/herdgate@latest
|
|
228
|
+
npx --yes @bom0792/herdgate@latest setup --mobile-act d_device
|
|
229
|
+
npx --yes @bom0792/herdgate@latest status
|
|
220
230
|
```
|
|
221
231
|
|
|
222
|
-
Omit `--mobile-
|
|
232
|
+
Omit `--mobile-act d_device` for a new TUI-only setup. Since `0.9.29`, Windows
|
|
233
|
+
`setup` and `migrate` from npm also install the durable `herdgate` command on
|
|
234
|
+
first success, even when invoked from `npx`. Use `--no-path` on the first
|
|
235
|
+
setup or migration if you do not want the User PATH entry. The first setup or
|
|
223
236
|
migration from a manual install needs the desired mode once; it is saved
|
|
224
237
|
locally only after the publisher connects. For subsequent updates:
|
|
225
238
|
|
|
@@ -230,17 +243,56 @@ herdgate update
|
|
|
230
243
|
The update validates the new release before touching the old publisher. It
|
|
231
244
|
preserves the device ID and mode, restarts only the publisher if needed, and
|
|
232
245
|
tries to restore the old release if the new worker cannot connect. Pairing
|
|
233
|
-
and SSH keys are not rewritten.
|
|
246
|
+
and SSH keys are not rewritten. Before opening a new shell, or if Windows policy
|
|
247
|
+
blocks User PATH registration, use the full path to the Node-pinned shim:
|
|
248
|
+
|
|
249
|
+
```powershell
|
|
250
|
+
& "$env:LOCALAPPDATA\Herdgate\cli\bin\herdgate.cmd" update
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Use `install-tui` for install without starting.
|
|
254
|
+
|
|
255
|
+
#### Windows: `npx` resolves the wrong Node
|
|
256
|
+
|
|
257
|
+
Check the runtime using its full path (adjust it if installed elsewhere):
|
|
234
258
|
|
|
235
|
-
|
|
259
|
+
```powershell
|
|
260
|
+
$node = 'C:\Program Files\nodejs\node.exe'
|
|
261
|
+
& $node --version
|
|
262
|
+
& $node -p 'typeof(WebSocket)'
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Expect Node 22+ and `function`. Starting with `0.9.28`, the main Windows CLI can
|
|
266
|
+
relaunch publisher-management commands using Node under `Program Files` if npm
|
|
267
|
+
started it with an older Node. It does not change `PATH` or override options
|
|
268
|
+
that disable WebSocket. If the fallback cannot find your installation, bypass the
|
|
269
|
+
`npm` and `npx` shims entirely. Example for an existing Mobile Act publisher:
|
|
270
|
+
|
|
271
|
+
```powershell
|
|
272
|
+
$npm = Join-Path (Split-Path $node) 'node_modules\npm\bin\npm-cli.js'
|
|
273
|
+
$dir = Join-Path $env:TEMP ('herdgate-' + [guid]::NewGuid())
|
|
274
|
+
& $node $npm install --prefix $dir --no-save --ignore-scripts --no-audit --no-fund @bom0792/herdgate@0.9.29
|
|
275
|
+
if ($LASTEXITCODE -ne 0) { throw 'Herdgate installation failed' }
|
|
276
|
+
& $node "$dir\node_modules\@bom0792\herdgate\bin\herdgate.mjs" migrate --mobile-act d_device
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Replace `d_device` with the existing approved device ID, or use your actual
|
|
280
|
+
saved/legacy mode. Do not stop the publisher first. The **migration's own**
|
|
281
|
+
`"state":"connected"` output means it finished and saved the mode; `status`
|
|
282
|
+
can still report the old publisher after a failed migration. Verify both TUI
|
|
283
|
+
and Mobile before cleaning up the temporary npm directory.
|
|
284
|
+
|
|
285
|
+
The ZIP remains an alternative: extract it and run `& $node .\windows\install-cli.mjs`.
|
|
236
286
|
|
|
237
287
|
The installer stores each build under `%LOCALAPPDATA%\Herdgate\cli\releases`.
|
|
238
288
|
The directory junction `current` selects the build used by the stable
|
|
239
289
|
`bin\herdgate-tui.cmd` shim. Rerun `npx --yes @bom0792/herdgate@latest install-tui`
|
|
240
290
|
to switch builds. The `tui` subcommand forwards to the installed build; use
|
|
241
291
|
`tui versions` and `tui use <release-id>` to list/select existing builds.
|
|
242
|
-
|
|
243
|
-
`
|
|
292
|
+
The legacy `install-tui` and ZIP installer do not change PATH. The npm
|
|
293
|
+
`install` and first npm `setup`/`migrate` can register the directory in User PATH.
|
|
294
|
+
The main command is stored independently of the publisher selection: rolling
|
|
295
|
+
back the publisher does not remove `herdgate` or tie it to the npm cache.
|
|
244
296
|
|
|
245
297
|
After pairing the laptop and starting its default session with the official
|
|
246
298
|
Herdr Windows 0.9.5 package, run `herdgate-tui start <path-to-herdr.exe>`.
|
|
@@ -256,24 +308,23 @@ in to Herdr Mobile support with the installed Core executable:
|
|
|
256
308
|
```powershell
|
|
257
309
|
$hc = (Get-Command herdr-core.exe -ErrorAction Stop).Source
|
|
258
310
|
& $hc server status --json
|
|
259
|
-
herdgate
|
|
260
|
-
herdgate-tui start --hc "$hc"
|
|
311
|
+
herdgate setup --hc "$hc"
|
|
261
312
|
```
|
|
262
313
|
|
|
263
314
|
If Core is not running, start it locally with `& $hc server start`. The `--hc`
|
|
264
315
|
flag keeps the TUI bridge enabled and adds Core access for `act` devices only.
|
|
265
316
|
The publisher restart interrupts remote connections, not the local TUI server.
|
|
266
317
|
In `--hc` mode, Herdr Mobile sees Core terminals, not TUI panes.
|
|
267
|
-
To expose TUI panes directly instead, use `herdgate
|
|
268
|
-
with the ID of a paired `read` device in this laptop
|
|
318
|
+
To expose TUI panes directly instead, use `herdgate setup --mobile-read d_device`
|
|
319
|
+
with the ID of a paired `read` device in this laptop's room. This opt-in mode
|
|
269
320
|
serves only that device with a read-only Core protocol adapter, needs no `hc`
|
|
270
321
|
binary, and leaves the normal TUI bridge and its existing `act` devices intact.
|
|
271
322
|
Opening an individual pane in Herdr Mobile shows a periodically refreshed
|
|
272
323
|
text snapshot of its visible screen. The adapter does not forward keystrokes,
|
|
273
324
|
resize the pane, or reproduce its full ANSI rendering or scrollback.
|
|
274
325
|
|
|
275
|
-
For a phone explicitly approved to control this laptop,
|
|
276
|
-
|
|
326
|
+
For a phone explicitly approved to control this laptop, use
|
|
327
|
+
`herdgate setup --mobile-act d_device` instead. The device must already have `act`
|
|
277
328
|
scope, and the setting only enables the Core adapter for that device ID.
|
|
278
329
|
Non-observe attach uses Herdr's native terminal session to forward ANSI output,
|
|
279
330
|
keys and viewport resize. Resize changes the pane's real terminal size while
|
|
@@ -282,17 +333,14 @@ also mapped to TUI actions. The adapter does not implement Core-only features
|
|
|
282
333
|
such as templates, task lifecycle or file operations. Enable this mode only
|
|
283
334
|
where executing commands in existing panes from the phone is authorized.
|
|
284
335
|
|
|
285
|
-
|
|
336
|
+
### Linux as a TUI host
|
|
286
337
|
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
338
|
+
Run these commands as the user who owns the running Herdr server. For a newly
|
|
339
|
+
paired host use `herdgate setup`. For the previous Herdgate home service, use
|
|
340
|
+
`herdgate migrate` instead. Both install a durable systemd user service and
|
|
341
|
+
reuse the pairing and TUI socket. See the [migration checklist](DEPLOY.md#migrate-the-linux-tui-publisher).
|
|
291
342
|
|
|
292
|
-
|
|
293
|
-
Herdgate; other custom units are not overwritten. The command installs a
|
|
294
|
-
persistent systemd user service, reuses the existing room and TUI socket,
|
|
295
|
-
and does not restart Herdr. Repeat `setup` to update the publisher.
|
|
343
|
+
### Linux: standalone Mobile TUI publishers
|
|
296
344
|
|
|
297
345
|
On Linux, use `npm run mobile-tui` (or `node src/host/mobile-tui.ts`) as the
|
|
298
346
|
user running Herdr, with
|
|
@@ -312,10 +360,10 @@ view the host publishes.
|
|
|
312
360
|
HERDGATE_ACCOUNT_TOKEN=… npm start # → http://127.0.0.1:8787/ is the app
|
|
313
361
|
```
|
|
314
362
|
|
|
315
|
-
|
|
363
|
+
PWA safeguards (see `test/web.test.ts` and `test/web-pairing.test.ts`):
|
|
316
364
|
|
|
317
|
-
- **no HTML from the wire** —
|
|
318
|
-
- **
|
|
365
|
+
- **no HTML from the wire** — incoming strings are shown as text, not injected as HTML;
|
|
366
|
+
- **read-only publisher operations** — the PWA can request `view`, `term.list` and `term.read`, but cannot type into a pane;
|
|
319
367
|
- **a locked-down CSP** — `default-src 'self'`, no inline script or style, `frame-ancestors 'none'`;
|
|
320
368
|
- **static can't escape** — `realpath`-pinned root, dotfiles and traversal refused (including `%2e%2e`);
|
|
321
369
|
- **API precedence** — `/v1/*` and `/healthz` are routed before static, so no file can shadow them.
|
package/bin/herdgate.mjs
CHANGED
|
@@ -13,12 +13,14 @@ import { fileURLToPath } from "node:url";
|
|
|
13
13
|
import { manageCloud, resolveCloud } from "./cloud-config.mjs";
|
|
14
14
|
import { readConfig } from "../plugin/server/common.mjs";
|
|
15
15
|
import { withLatest } from "../windows/npm-update.mjs";
|
|
16
|
+
import { windowsNode } from "../windows/node-runtime.mjs";
|
|
16
17
|
|
|
17
18
|
const HERE = dirname(fileURLToPath(import.meta.url)); // <pkg>/bin
|
|
18
19
|
const ROOT = dirname(HERE); // <pkg>
|
|
19
20
|
|
|
20
21
|
const help = `herdgate — every machine, one herd
|
|
21
22
|
|
|
23
|
+
herdgate install [--no-path] Install the persistent Windows command (no publisher restart).
|
|
22
24
|
herdgate cloud add <name> <https-url>
|
|
23
25
|
herdgate cloud list
|
|
24
26
|
herdgate pair --cloud <name> Pair this machine with owner approval.
|
|
@@ -348,8 +350,22 @@ try {
|
|
|
348
350
|
if (cmd === "setup-host") setupHost();
|
|
349
351
|
else if (cmd === "cloud") manageCloud(args);
|
|
350
352
|
else if (cmd === "pair") pairHost(args);
|
|
351
|
-
else if (
|
|
353
|
+
else if (process.platform === "win32" && (
|
|
354
|
+
["install", "setup", "migrate", "start", "update", "install-tui"].includes(cmd) ||
|
|
355
|
+
(cmd === "tui" && ["setup", "migrate", "start", "update"].includes(args[0]))
|
|
356
|
+
) && (Number(process.versions.node.split(".")[0]) < 22 || typeof globalThis.WebSocket !== "function")) {
|
|
357
|
+
const node = windowsNode();
|
|
358
|
+
const r = spawnSync(node, [fileURLToPath(import.meta.url), cmd, ...args], { stdio: "inherit", shell: false, windowsHide: true });
|
|
359
|
+
if (r.error) throw r.error;
|
|
360
|
+
process.exitCode = r.status ?? 1;
|
|
361
|
+
} else if (["setup", "migrate", "start", "stop", "status", "update"].includes(cmd)) managePublisher(cmd, args);
|
|
352
362
|
else if (cmd === "home-tui") runNode(join(HERE, "home-tui.mjs"), args);
|
|
363
|
+
else if (cmd === "install") {
|
|
364
|
+
if (args.length && !(args.length === 1 && args[0] === "--no-path") && !(args.length === 2 && args[0] === "--root" && args[1])) {
|
|
365
|
+
throw new Error("usage: herdgate install [--no-path | --root <dir>]");
|
|
366
|
+
}
|
|
367
|
+
runNode(join(ROOT, "windows", "install-cli.mjs"), ["--command", ...args]);
|
|
368
|
+
}
|
|
353
369
|
else if (cmd === "install-tui") runNode(join(ROOT, "windows", "install-cli.mjs"), args);
|
|
354
370
|
else if (cmd === "tui") {
|
|
355
371
|
if (["setup", "migrate", "update"].includes(args[0])) runNode(join(ROOT, "windows", "setup-tui.mjs"), args);
|
package/dist-readme.md
CHANGED
|
@@ -7,7 +7,7 @@ phone/PWA của bạn.
|
|
|
7
7
|
## Yêu cầu
|
|
8
8
|
|
|
9
9
|
- herdr desktop app (per-user, không cần admin) hoặc herdr TUI
|
|
10
|
-
-
|
|
10
|
+
- Node 22+ có WebSocket (kiểm tra: `node -v` và `node -p 'typeof(WebSocket)'`, kết quả sau phải là `function`)
|
|
11
11
|
- Nút **Publish** trong panel yêu cầu Linux/macOS. Với Windows, dùng thử publisher TUI chạy nền bên dưới.
|
|
12
12
|
|
|
13
13
|
## Cài (Linux / macOS)
|
|
@@ -39,11 +39,20 @@ Máy giờ hiện trong PWA; phone pair thiết bị riêng để xem terminal.
|
|
|
39
39
|
## Thử Windows làm host TUI (không cần sshd)
|
|
40
40
|
|
|
41
41
|
Chỉ bật nếu chính sách của máy cho phép điều khiển từ xa. Laptop phải đã pair
|
|
42
|
-
trong Herdgate.
|
|
43
|
-
|
|
42
|
+
trong Herdgate. Với npm trên Windows, chạy `npx --yes @bom0792/herdgate@latest install`
|
|
43
|
+
để cài lệnh `herdgate` cho user (không cần admin), rồi dùng `herdgate setup`
|
|
44
|
+
khi cài mới hoặc `herdgate migrate`
|
|
45
|
+
để tiếp quản publisher cũ. Nếu bản cũ chưa lưu mode, khai đúng chế độ đang dùng:
|
|
46
|
+
`--mobile-act d_device`, `--mobile-read d_device`, `--hc <path>` hoặc `--plain`.
|
|
47
|
+
Không dừng publisher hay pair lại trước. `herdgate update` giữ mode đã lưu.
|
|
48
|
+
|
|
49
|
+
Nếu dùng ZIP, mở PowerShell ở thư mục vừa giải nén. Trỏ thẳng đến Node 22 nếu
|
|
50
|
+
máy có nhiều bản Node (sửa đường dẫn nếu cần):
|
|
44
51
|
|
|
45
52
|
```powershell
|
|
46
|
-
node
|
|
53
|
+
$node = 'C:\Program Files\nodejs\node.exe'
|
|
54
|
+
& $node -p 'typeof(WebSocket)'
|
|
55
|
+
& $node .\windows\install-cli.mjs
|
|
47
56
|
$bin = Join-Path $env:LOCALAPPDATA 'Herdgate\cli\bin'
|
|
48
57
|
$env:Path = "$bin;$env:Path"
|
|
49
58
|
herdgate-tui status
|
|
@@ -60,14 +69,21 @@ Nếu không cài `herdr.exe` trong `%LOCALAPPDATA%\HerdrPilot\v0.9.5`, truyền
|
|
|
60
69
|
dẫn đầy đủ sau `start`. Khi `status` báo `connected`, có thể đóng PowerShell.
|
|
61
70
|
`herdgate-tui stop` chỉ dừng publisher. Không tự khởi động khi đăng nhập.
|
|
62
71
|
Máy điều khiển vẫn cần quyền `act` và SSH key riêng cho room của laptop.
|
|
63
|
-
|
|
72
|
+
Mặc định publisher chỉ mở cầu nối TUI, không dùng desktop app hay `hc`.
|
|
73
|
+
Mobile là opt-in: `--hc <path>` dùng Core thật; `--mobile-tui d_device`
|
|
74
|
+
chỉ đọc pane; `--mobile-tui-act d_device` cho phép nhập và resize đối với
|
|
75
|
+
đúng thiết bị đã được duyệt `act`. Adapter TUI không phải bản thay thế đầy đủ
|
|
76
|
+
cho Core. Cài ZIP không tự migrate hay nâng cấp máy nhà, Gate hoặc VPS.
|
|
64
77
|
|
|
65
78
|
## Bộ gồm
|
|
66
79
|
|
|
67
80
|
mod/herdgate/ → copy vào mods/ của herdr-app
|
|
68
81
|
plugin/server/*.mjs → publisher (mod tự spawn bằng node)
|
|
69
82
|
plugin/herdr-plugin.toml → nếu bạn dùng herdr TUI thay vì app
|
|
83
|
+
windows/ → bộ cài và CLI publisher Windows
|
|
70
84
|
|
|
71
85
|
## Gỡ
|
|
72
86
|
|
|
73
|
-
|
|
87
|
+
Dừng publisher trước. Để chỉ gỡ mod, xóa thư mục
|
|
88
|
+
`~/.config/herdr-app/mods/herdgate` (hoặc thư mục mod tương ứng trên hệ điều hành).
|
|
89
|
+
Giữ `~/.config/herdr-app/herdgate` nếu muốn dùng lại pairing đã có.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bom0792/herdgate",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.29",
|
|
4
4
|
"description": "Cloud relay hub for herdr-core: every machine dials out, phones and browsers follow (PWA + SSH leg, E2E payloads).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
@@ -36,6 +36,8 @@
|
|
|
36
36
|
"app-mod",
|
|
37
37
|
"plugin",
|
|
38
38
|
"scripts",
|
|
39
|
+
"DEPLOY.md",
|
|
40
|
+
"DESIGN.md",
|
|
39
41
|
"dist-readme.md",
|
|
40
42
|
"templates",
|
|
41
43
|
"windows"
|
package/windows/install-cli.mjs
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// Per-user installation. On Windows, directory junctions do not need admin or Developer Mode.
|
|
2
|
+
import { spawnSync } from "node:child_process";
|
|
2
3
|
import { createHash, randomUUID } from "node:crypto";
|
|
3
4
|
import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
|
|
4
|
-
import { basename, dirname, join, resolve } from "node:path";
|
|
5
|
+
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
5
6
|
import { fileURLToPath } from "node:url";
|
|
6
7
|
|
|
7
8
|
const source = fileURLToPath(new URL("../", import.meta.url));
|
|
@@ -16,9 +17,16 @@ function directory(path) {
|
|
|
16
17
|
}
|
|
17
18
|
|
|
18
19
|
function inputs() {
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
20
|
+
function files(dir) {
|
|
21
|
+
return readdirSync(join(source, dir), { withFileTypes: true }).flatMap((file) => {
|
|
22
|
+
const name = `${dir}/${file.name}`;
|
|
23
|
+
return file.isDirectory() ? files(name) : file.isFile() ? [name] : [];
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
const runtime = ["plugin", "windows"];
|
|
27
|
+
// ZIPs built before the standalone command do not contain these npm assets.
|
|
28
|
+
for (const dir of ["bin", "app-mod", "templates"]) if (stat(join(source, dir))?.isDirectory()) runtime.push(dir);
|
|
29
|
+
return runtime.flatMap(files).sort();
|
|
22
30
|
}
|
|
23
31
|
|
|
24
32
|
function installRelease(releases) {
|
|
@@ -47,13 +55,13 @@ function installRelease(releases) {
|
|
|
47
55
|
return id;
|
|
48
56
|
}
|
|
49
57
|
|
|
50
|
-
function selectRelease(root, releases, id) {
|
|
58
|
+
function selectRelease(root, releases, id, link = "current") {
|
|
51
59
|
if (!releasePattern.test(id)) throw new Error("invalid release ID");
|
|
52
60
|
const dest = join(releases, id);
|
|
53
61
|
if (!stat(dest)?.isDirectory() || readFileSync(join(dest, "release.txt"), "utf8").trim() !== id) {
|
|
54
62
|
throw new Error(`release not installed: ${id}`);
|
|
55
63
|
}
|
|
56
|
-
const current = join(root,
|
|
64
|
+
const current = join(root, link);
|
|
57
65
|
const old = stat(current);
|
|
58
66
|
if (old) {
|
|
59
67
|
if (!old.isSymbolicLink()) throw new Error(`refusing to replace a real file or directory: ${current}`);
|
|
@@ -79,17 +87,17 @@ function selectRelease(root, releases, id) {
|
|
|
79
87
|
}
|
|
80
88
|
}
|
|
81
89
|
|
|
82
|
-
function installShim(root) {
|
|
90
|
+
function installShim(root, name, target, marker) {
|
|
83
91
|
const bin = join(root, "bin");
|
|
84
92
|
directory(bin);
|
|
85
|
-
const shim = join(bin,
|
|
93
|
+
const shim = join(bin, name);
|
|
86
94
|
const previous = stat(shim);
|
|
87
|
-
if (previous && (!previous.isFile() || !readFileSync(shim, "utf8").startsWith(
|
|
95
|
+
if (previous && (!previous.isFile() || !readFileSync(shim, "utf8").startsWith(marker + "\r\n"))) {
|
|
88
96
|
throw new Error(`refusing to overwrite an unmanaged shim: ${shim}`);
|
|
89
97
|
}
|
|
90
98
|
// Match the Node used for install, not a node.exe from the caller's cwd.
|
|
91
99
|
const node = process.execPath.replaceAll("%", "%%");
|
|
92
|
-
const content =
|
|
100
|
+
const content = `${marker}\r\n@echo off\r\nsetlocal DisableDelayedExpansion\r\n"${node}" "%~dp0..\\${target}" %*\r\nexit /b %errorlevel%\r\n`;
|
|
93
101
|
// Self-update is running from this batch file; never rewrite an unchanged shim.
|
|
94
102
|
if (previous && readFileSync(shim, "utf8") === content) return;
|
|
95
103
|
const staged = `${shim}.${randomUUID()}`;
|
|
@@ -101,22 +109,59 @@ function installShim(root) {
|
|
|
101
109
|
}
|
|
102
110
|
}
|
|
103
111
|
|
|
112
|
+
function registerUserPath(root) {
|
|
113
|
+
const system = process.env.SystemRoot;
|
|
114
|
+
if (!isAbsolute(system ?? "")) return false;
|
|
115
|
+
const powershell = join(system, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
|
|
116
|
+
const script = `
|
|
117
|
+
$ErrorActionPreference = 'Stop'
|
|
118
|
+
$bin = $env:HERDGATE_INSTALL_BIN
|
|
119
|
+
if (!$bin -or $bin.Contains(';')) { exit 1 }
|
|
120
|
+
$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
|
|
121
|
+
try {
|
|
122
|
+
$old = $key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
|
|
123
|
+
if ($old -isnot [string]) { exit 1 }
|
|
124
|
+
foreach ($entry in $old.Split(';')) {
|
|
125
|
+
$expanded = [Environment]::ExpandEnvironmentVariables($entry.Trim().Trim([char]34))
|
|
126
|
+
if ($expanded.TrimEnd([char[]]@(92, 47)) -ieq $bin) { exit 0 }
|
|
127
|
+
}
|
|
128
|
+
$new = if ($old -and !$old.EndsWith(';')) { $old + ';' + $bin } else { $old + $bin }
|
|
129
|
+
if ($key.GetValueNames() -contains 'Path' -and $key.GetValueKind('Path') -eq 'ExpandString') {
|
|
130
|
+
if ($bin.Contains('%')) { exit 1 }
|
|
131
|
+
$key.SetValue('Path', $new, [Microsoft.Win32.RegistryValueKind]::ExpandString)
|
|
132
|
+
} else {
|
|
133
|
+
[Environment]::SetEnvironmentVariable('Path', $new, [EnvironmentVariableTarget]::User)
|
|
134
|
+
}
|
|
135
|
+
} finally { $key.Dispose() }
|
|
136
|
+
exit 0`;
|
|
137
|
+
const result = spawnSync(powershell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script], {
|
|
138
|
+
env: { ...process.env, HERDGATE_INSTALL_BIN: join(root, "bin") }, shell: false, windowsHide: true,
|
|
139
|
+
timeout: 15_000, encoding: "utf8",
|
|
140
|
+
});
|
|
141
|
+
return result.status === 0;
|
|
142
|
+
}
|
|
143
|
+
|
|
104
144
|
try {
|
|
105
145
|
if (process.platform === "win32" && typeof globalThis.WebSocket !== "function") throw new Error("run this installer with Node 22+ with WebSocket enabled");
|
|
106
146
|
const args = process.argv.slice(2);
|
|
107
|
-
|
|
147
|
+
const defaultRoot = process.platform === "win32" && process.env.LOCALAPPDATA ? resolve(process.env.LOCALAPPDATA, "Herdgate", "cli") : null;
|
|
148
|
+
let root = defaultRoot;
|
|
108
149
|
let use = null;
|
|
109
150
|
let stage = false;
|
|
151
|
+
let command = false;
|
|
152
|
+
let userPath = true;
|
|
110
153
|
while (args.length) {
|
|
111
154
|
const flag = args.shift();
|
|
112
155
|
if (flag === "--stage") { stage = true; continue; }
|
|
156
|
+
if (flag === "--command") { command = true; continue; }
|
|
157
|
+
if (flag === "--no-path") { userPath = false; continue; }
|
|
113
158
|
const value = args.shift();
|
|
114
159
|
if (flag === "--root" && value) root = resolve(value);
|
|
115
160
|
else if (flag === "--use" && value) use = value;
|
|
116
|
-
else throw new Error("usage: node windows/install-cli.mjs [--root <dir>] [--stage | --use <release-id>]");
|
|
161
|
+
else throw new Error("usage: node windows/install-cli.mjs [--root <dir>] [--stage | --use <release-id>] [--command [--no-path]]");
|
|
117
162
|
}
|
|
118
163
|
if (!root) throw new Error("this installer defaults to %LOCALAPPDATA% on Windows");
|
|
119
|
-
if (stage && use) throw new Error("
|
|
164
|
+
if ((stage && (use || command)) || (!command && !userPath)) throw new Error("invalid installer option combination");
|
|
120
165
|
directory(root);
|
|
121
166
|
const releases = join(root, "releases");
|
|
122
167
|
directory(releases);
|
|
@@ -126,9 +171,20 @@ try {
|
|
|
126
171
|
const id = use ?? installRelease(releases);
|
|
127
172
|
if (stage) {
|
|
128
173
|
console.log(id);
|
|
174
|
+
} else if (command) {
|
|
175
|
+
if (!releasePattern.test(id) || !stat(join(releases, id, "bin", "herdgate.mjs"))?.isFile()) {
|
|
176
|
+
throw new Error("the standalone command requires the Herdgate npm package");
|
|
177
|
+
}
|
|
178
|
+
installShim(root, "herdgate.cmd", "command\\bin\\herdgate.mjs", "@rem Herdgate CLI");
|
|
179
|
+
selectRelease(root, releases, id, "command");
|
|
180
|
+
const shim = join(root, "bin", "herdgate.cmd");
|
|
181
|
+
if (userPath && defaultRoot && samePath(root, defaultRoot)) {
|
|
182
|
+
if (registerUserPath(root)) console.log(`Herdgate CLI: ${shim}\nOpen a new terminal for User PATH; in the current shell, use the full path above.`);
|
|
183
|
+
else console.log(`Herdgate CLI: ${shim}\nCould not register User PATH; invoke the shim by full path.`);
|
|
184
|
+
} else console.log(`Herdgate CLI: ${shim}`);
|
|
129
185
|
} else {
|
|
130
186
|
selectRelease(root, releases, id);
|
|
131
|
-
installShim(root);
|
|
187
|
+
installShim(root, "herdgate-tui.cmd", "current\\windows\\cli.mjs", "@rem Herdgate TUI CLI");
|
|
132
188
|
console.log(`Herdgate TUI CLI: ${id}\nShim: ${join(root, "bin", "herdgate-tui.cmd")}`);
|
|
133
189
|
}
|
|
134
190
|
} finally {
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
// An npm-launched CLI can be running under a different Node from npm itself.
|
|
2
|
+
import { spawnSync } from 'node:child_process';
|
|
3
|
+
import { isAbsolute, join } from 'node:path';
|
|
4
|
+
|
|
5
|
+
const major = (version) => Number(/^v?(\d+)\./.exec(version)?.[1] || 0);
|
|
6
|
+
const working = (version, webSocket) => major(version) >= 22 && webSocket;
|
|
7
|
+
|
|
8
|
+
/** Return an absolute alternate runtime, or null when the current runtime is usable. */
|
|
9
|
+
export function windowsNode({ version = process.version, webSocket = typeof globalThis.WebSocket === 'function', env = process.env } = {}) {
|
|
10
|
+
if (working(version, webSocket)) return null;
|
|
11
|
+
// Do not work around flags disabling WebSocket on an already compatible Node installation.
|
|
12
|
+
if (major(version) >= 22) throw new Error(`WebSocket is disabled or unavailable in Node ${version}; check NODE_OPTIONS and the Node installation`);
|
|
13
|
+
for (const base of new Set([env.ProgramW6432, env.ProgramFiles])) {
|
|
14
|
+
if (!base || !isAbsolute(base)) continue;
|
|
15
|
+
const candidate = join(base, 'nodejs', 'node.exe');
|
|
16
|
+
const result = spawnSync(candidate, ['-p', 'JSON.stringify([process.version,typeof(WebSocket)])'], {
|
|
17
|
+
cwd: join(base, 'nodejs'), env, encoding: 'utf8', windowsHide: true, shell: false, timeout: 3000,
|
|
18
|
+
});
|
|
19
|
+
if (result.status !== 0) continue;
|
|
20
|
+
try {
|
|
21
|
+
const [found, ws] = JSON.parse(result.stdout);
|
|
22
|
+
if (working(found, ws === 'function')) return candidate;
|
|
23
|
+
} catch { /* not a usable Node runtime */ }
|
|
24
|
+
}
|
|
25
|
+
throw new Error(`Herdgate was launched with Node ${String(version).replace(/^v/, '')}; install Node 22+ with WebSocket enabled or run the CLI directly with that Node`);
|
|
26
|
+
}
|
package/windows/setup-tui.mjs
CHANGED
|
@@ -31,8 +31,10 @@ function writeProfile(path, args) {
|
|
|
31
31
|
}
|
|
32
32
|
|
|
33
33
|
async function setup() {
|
|
34
|
-
const [cmd, ...
|
|
35
|
-
|
|
34
|
+
const [cmd, ...options] = process.argv.slice(2);
|
|
35
|
+
const requested = options.filter(flag => flag !== "--no-path");
|
|
36
|
+
const noPath = requested.length !== options.length;
|
|
37
|
+
if (cmd === "update" && options.length) throw new Error("use herdgate setup to change publisher options");
|
|
36
38
|
if (!["setup", "migrate", "update"].includes(cmd)) throw new Error("expected setup, migrate, or update");
|
|
37
39
|
const plain = requested.includes("--plain");
|
|
38
40
|
if (plain && requested.length !== 1) throw new Error("--plain cannot be combined with other publisher options");
|
|
@@ -81,10 +83,23 @@ async function setup() {
|
|
|
81
83
|
const next = install("--stage");
|
|
82
84
|
if (!releaseId.test(next)) throw new Error("installer did not return a release ID");
|
|
83
85
|
cli(next, "check", ...args); // validate executable, pairing and Herdr before disrupting the old worker
|
|
86
|
+
const refreshCommand = () => {
|
|
87
|
+
// Older standalone bundles do not have the top-level npm CLI. Keep their compatibility shim usable.
|
|
88
|
+
if (!existsSync(join(releases, next, "bin", "herdgate.mjs"))) return;
|
|
89
|
+
const first = !existsSync(join(root, "bin", "herdgate.cmd"));
|
|
90
|
+
try {
|
|
91
|
+
const output = install("--command", "--use", next, ...(!first || noPath ? ["--no-path"] : []));
|
|
92
|
+
if (first) console.error(output);
|
|
93
|
+
} catch (error) {
|
|
94
|
+
// Command registration isn't part of the publisher transaction.
|
|
95
|
+
console.error(`herdgate tui: could not install the persistent command: ${errorText(error)}`);
|
|
96
|
+
}
|
|
97
|
+
};
|
|
84
98
|
const oldStatus = status(prior ?? next);
|
|
85
99
|
const running = !["stopped", "stale"].includes(oldStatus.state);
|
|
86
100
|
if (prior === next && profile && JSON.stringify(args) === JSON.stringify(profile) && oldStatus.state === "connected") {
|
|
87
101
|
install("--use", next); // refresh pinned Node shim, no worker restart
|
|
102
|
+
refreshCommand();
|
|
88
103
|
console.log(JSON.stringify({ release: next, ...oldStatus }));
|
|
89
104
|
return;
|
|
90
105
|
}
|
|
@@ -95,6 +110,7 @@ async function setup() {
|
|
|
95
110
|
triedStart = true;
|
|
96
111
|
const result = await start(next, args);
|
|
97
112
|
writeProfile(profilePath, args);
|
|
113
|
+
refreshCommand();
|
|
98
114
|
console.log(JSON.stringify({ release: next, ...result }));
|
|
99
115
|
} catch (cause) {
|
|
100
116
|
try {
|