@bom0792/herdgate 0.9.31 → 0.9.34
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 +85 -126
- package/DESIGN.md +9 -4
- package/README.md +12 -2
- package/bin/herdgate.mjs +6 -1
- package/dist-readme.md +3 -1
- package/package.json +34 -8
- package/plugin/server/e2e.d.mts +2 -2
- package/plugin/server/e2e.mjs +51 -32
- package/plugin/server/index.mjs +128 -32
- package/plugin/server/pi-receipts.d.mts +28 -0
- package/plugin/server/pi-receipts.mjs +77 -0
- package/plugin/server/pi-worker.d.mts +47 -0
- package/plugin/server/pi-worker.mjs +127 -0
- package/scripts/build-host-bundle.sh +14 -8
- package/scripts/build-release.sh +47 -0
- package/scripts/deploy-vps.sh +5 -78
- package/src/cloud/gateway.ts +163 -134
- package/src/cloud/main.ts +72 -15
- package/src/cloud/pairing.ts +7 -2
- package/src/cloud/push.ts +54 -0
- package/src/cloud/sshd.ts +76 -38
- package/src/cloud/util.ts +5 -5
- package/src/web/app.js +88 -61
- package/src/web/e2e.js +51 -32
- package/src/web/sw.js +1 -1
- package/templates/cloud/.dockerignore +7 -0
- package/templates/cloud/Caddyfile.example +3 -0
- package/templates/cloud/Dockerfile +10 -0
- package/templates/cloud/README.md +74 -0
- package/templates/cloud/compose.env.example +18 -0
- package/templates/cloud/compose.yml +41 -0
- package/templates/cloud/gitignore.example +4 -0
- package/templates/cloud/herdgate-cloud-edge.service +18 -0
- package/templates/cloud/herdgate-cloud.service +26 -0
- package/tsconfig.cloud.json +11 -0
- package/tsconfig.json +18 -0
- package/src/web/herdgate-host.zip +0 -0
package/DEPLOY.md
CHANGED
|
@@ -1,15 +1,65 @@
|
|
|
1
|
-
# Deploying
|
|
1
|
+
# Deploying Herdgate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Deploying a clean Gate
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
From a checkout with Node 22+, npm, Bash, `tar`, `zip` and `sha256sum`:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm ci --ignore-scripts
|
|
9
|
+
npm run build:release
|
|
10
|
+
# Or stage into a new directory without changing the PWA currently being served:
|
|
11
|
+
npm run build:release -- /path/to/new-output
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The default `dist/<version>/` contains `herdgate-cloud-<version>.tar.gz`,
|
|
15
|
+
`herdgate-host-<version>.zip`, the npm tarball and `SHA256SUMS`. Verify the set
|
|
16
|
+
with `sha256sum -c SHA256SUMS`. The Cloud archive contains compiled JS, the PWA
|
|
17
|
+
with the matching host ZIP, a dependency lockfile, and Compose/systemd examples.
|
|
18
|
+
The standalone npm command `herdgate cloud serve` is also available from a full
|
|
19
|
+
npm installation on Node with TypeScript stripping, like `npm start`.
|
|
20
|
+
|
|
21
|
+
Extract the Cloud archive and follow its [README](templates/cloud/README.md)
|
|
22
|
+
to deploy via Docker Compose or systemd. Create credentials on the destination:
|
|
23
|
+
no build step copies state, tokens, SSH or VAPID keys, or modifies a running Gate.
|
|
24
|
+
The old `scripts/deploy-vps.sh` is retired and does not connect to the target.
|
|
25
|
+
For an existing Gate, back up and migrate explicitly, keeping the public origin,
|
|
26
|
+
owner token, state, SSH key and any VAPID keys. A clean Gate starts with no rooms.
|
|
27
|
+
|
|
28
|
+
From v0.9.33, Push wake is off by default. If you need it, set `HERDGATE_ENABLE_PUSH=1`
|
|
29
|
+
(and optionally `HERDGATE_PUSH_SUB` to a VAPID contact URI); `HERDGATE_NO_PUSH=1`
|
|
30
|
+
takes precedence. Existing VAPID keys are untouched while wake is off.
|
|
31
|
+
|
|
32
|
+
A PWA room with a Noise host pin no longer accepts plaintext pane data or a different
|
|
33
|
+
host key.
|
|
34
|
+
|
|
35
|
+
### Client addresses behind a proxy (v0.9.34)
|
|
36
|
+
|
|
37
|
+
Abuse limits (failed-hello strikes, pairing-code minting, SSH-over-WSS caps) key on
|
|
38
|
+
the client address. Connections arriving over loopback — a same-host proxy such as
|
|
39
|
+
cloudflared — automatically get a **per-connection** budget, so one abusive client
|
|
40
|
+
cannot lock everyone behind the proxy out, and the Gate admits SSH tunnels up to its
|
|
41
|
+
global total rather than a collapsed per-address cap. If your edge forwards a real
|
|
42
|
+
client IP header, set `HERDGATE_TRUSTED_PROXY=1` (and optionally
|
|
43
|
+
`HERDGATE_REAL_IP_HEADER`, default `CF-Connecting-IP`) to restore per-client budgets;
|
|
44
|
+
a raw TCP edge cannot convey real addresses, so size the shared budget with
|
|
45
|
+
`HERDGATE_SSH_TUNNELS_PER_IP` and `HERDGATE_SSH_TUNNELS_TOTAL`. Pairing-code minting
|
|
46
|
+
is bounded per client (10 per 10 minutes) and globally (256 pending). Matching legacy pins are upgraded without re-pairing. Keep the publisher’s
|
|
47
|
+
`e2e-host.json` in backups; on a key-change warning verify the identity with the host
|
|
48
|
+
admin rather than clearing browser data. Noise does not cover the separate SSH leg.
|
|
49
|
+
|
|
50
|
+
## Source checkout behind cloudflared
|
|
51
|
+
|
|
52
|
+
If you are developing or already run from the checkout, bind the cloud to
|
|
53
|
+
`127.0.0.1` and publish it through a Cloudflare tunnel. Two shapes:
|
|
54
|
+
|
|
55
|
+
### A. Quick tunnel (no DNS setup, throwaway URL)
|
|
6
56
|
|
|
7
57
|
```sh
|
|
8
58
|
# terminal 1 — the cloud
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
npm start
|
|
59
|
+
# From the checkout; use a disposable private directory.
|
|
60
|
+
trial=$(mktemp -d)
|
|
61
|
+
(umask 077; openssl rand -base64 32 > "$trial/owner-token")
|
|
62
|
+
HERDGATE_ACCOUNT_TOKEN_FILE="$trial/owner-token" HERDGATE_STATE="$trial/state.json" npm start
|
|
13
63
|
|
|
14
64
|
# terminal 2 — a trycloudflare URL (random, changes every run)
|
|
15
65
|
cloudflared tunnel --url http://127.0.0.1:8787
|
|
@@ -17,7 +67,7 @@ cloudflared tunnel --url http://127.0.0.1:8787
|
|
|
17
67
|
|
|
18
68
|
Use the printed `https://<random>.trycloudflare.com` as the public URL. Nothing to configure; fine for testing.
|
|
19
69
|
|
|
20
|
-
|
|
70
|
+
### B. Named tunnel + your domain (stable hostname)
|
|
21
71
|
|
|
22
72
|
```sh
|
|
23
73
|
cloudflared tunnel login # once, picks a zone
|
|
@@ -26,21 +76,24 @@ cloudflared tunnel route dns herdgate herd.example.com
|
|
|
26
76
|
|
|
27
77
|
cat > ~/.cloudflared/herdgate.yml <<'YML'
|
|
28
78
|
tunnel: herdgate
|
|
29
|
-
credentials-file: /
|
|
79
|
+
credentials-file: /absolute/path/to/.cloudflared/<TUNNEL-ID>.json
|
|
30
80
|
ingress:
|
|
31
81
|
- hostname: herd.example.com
|
|
32
82
|
service: http://127.0.0.1:8787
|
|
33
83
|
- service: http_status:404
|
|
34
84
|
YML
|
|
35
85
|
|
|
36
|
-
cloudflared
|
|
86
|
+
cloudflared --config ~/.cloudflared/herdgate.yml tunnel run
|
|
37
87
|
```
|
|
38
88
|
|
|
39
89
|
Then start the cloud with the hostname pinned:
|
|
40
90
|
|
|
41
91
|
```sh
|
|
42
|
-
|
|
43
|
-
|
|
92
|
+
install -d -m 700 "$HOME/.herdgate"
|
|
93
|
+
# First install only; preserve the token file on upgrades.
|
|
94
|
+
(umask 077; set -C; openssl rand -base64 32 > "$HOME/.herdgate/owner-token")
|
|
95
|
+
export HERDGATE_ACCOUNT_TOKEN_FILE="$HOME/.herdgate/owner-token"
|
|
96
|
+
export HERDGATE_STATE="$HOME/.herdgate/state.json"
|
|
44
97
|
export HERDGATE_PUBLIC_HOST=herd.example.com
|
|
45
98
|
export HERDGATE_PUBLIC_URL=https://herd.example.com
|
|
46
99
|
npm start
|
|
@@ -69,7 +122,9 @@ TLS, both wss legs) on this machine, with a throwaway dev cert:
|
|
|
69
122
|
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
|
|
70
123
|
-keyout /tmp/edge-key.pem -out /tmp/edge-cert.pem -days 2 -nodes -subj "/CN=127.0.0.1"
|
|
71
124
|
|
|
72
|
-
|
|
125
|
+
# terminal 1, reuse a local test token file
|
|
126
|
+
HERDGATE_ACCOUNT_TOKEN_FILE=/path/to/test-token \
|
|
127
|
+
HERDGATE_PUBLIC_HOST=gate.local HERDGATE_NO_SSH=1 npm start
|
|
73
128
|
HERDGATE_TARGET_PORT=8787 HERDGATE_PINNED_HOST=gate.local \
|
|
74
129
|
HERDGATE_EDGE_CERT=/tmp/edge-cert.pem HERDGATE_EDGE_KEY=/tmp/edge-key.pem \
|
|
75
130
|
npm run edge # terminal 2
|
|
@@ -80,32 +135,8 @@ Verified by `test/edge.test.ts` and a full headless-Chrome run: sign in → `onl
|
|
|
80
135
|
machine online → pair read → live Herdr view + SSH hint, all over TLS with both wss legs
|
|
81
136
|
through the splice.
|
|
82
137
|
|
|
83
|
-
|
|
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.
|
|
138
|
+
For a permanent deployment, prefer a named tunnel on a domain you control. If a quick tunnel
|
|
139
|
+
registers but returns 404, check the active tunnel and ingress settings before changing DNS.
|
|
109
140
|
|
|
110
141
|
### The SSH leg — passwordless logins (publickey)
|
|
111
142
|
|
|
@@ -143,37 +174,15 @@ of setup cost:
|
|
|
143
174
|
|
|
144
175
|
### Deploy the tokenless TCP edge on a VPS
|
|
145
176
|
|
|
146
|
-
Use a public IPv4 VPS with Node 22+ installed system-wide.
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
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
|
+
Use a public IPv4 VPS with Node 22+ installed system-wide. The Cloud release
|
|
178
|
+
includes the compiled TCP edge and a separate systemd unit. See the
|
|
179
|
+
[Cloud README](templates/cloud/README.md#optional-native-herdr-mobile-on-cellular).
|
|
180
|
+
For an existing standalone deployment, its old unit and config still work.
|
|
181
|
+
The edge caps concurrent sessions at 3 per IP and 6 total by default; the
|
|
182
|
+
Gate's tunnel caps still apply, and it may see several clients as one source
|
|
183
|
+
behind a proxy. Test the edge directly from Mobile over cellular and verify
|
|
184
|
+
the pinned Gate SSH key before switching any DNS-only records. Keep the HTTPS
|
|
185
|
+
Gate hostname unchanged.
|
|
177
186
|
|
|
178
187
|
### Legacy authenticated SSH bridge
|
|
179
188
|
|
|
@@ -235,62 +244,12 @@ input. This does not include cellular RTT or the official app's rendering.
|
|
|
235
244
|
An observe/read-only TUI attachment instead polls every 1.25 seconds; its
|
|
236
245
|
refresh interval is not comparable to the native interactive stream.
|
|
237
246
|
|
|
238
|
-
## Keep
|
|
239
|
-
|
|
240
|
-
On this machine (Linux + systemd) a user unit keeps the gate up; the tunnel is a second unit:
|
|
241
|
-
|
|
242
|
-
```sh
|
|
243
|
-
mkdir -p ~/.config/systemd/user
|
|
244
|
-
cat > ~/.config/systemd/user/herdgate.service <<'UNIT'
|
|
245
|
-
[Unit]
|
|
246
|
-
Description=herdgate cloud relay hub
|
|
247
|
-
After=network-online.target
|
|
248
|
-
|
|
249
|
-
[Service]
|
|
250
|
-
ExecStart=/home/bom/.nvm/versions/node/v22.23.1/bin/node /home/bom/source/herdgate/src/cloud/main.ts
|
|
251
|
-
Environment=HERDGATE_ACCOUNT_TOKEN=change-me
|
|
252
|
-
Environment=HERDGATE_PUBLIC_HOST=gate.phuongnb.io.vn
|
|
253
|
-
Environment=HERDGATE_PORT=8833
|
|
254
|
-
Environment=HERDGATE_STATE=/home/bom/.local/state/herdgate/state.json
|
|
255
|
-
WorkingDirectory=/home/bom/source/herdgate
|
|
256
|
-
Restart=always
|
|
257
|
-
RestartSec=3
|
|
258
|
-
|
|
259
|
-
[Install]
|
|
260
|
-
WantedBy=default.target
|
|
261
|
-
UNIT
|
|
262
|
-
systemctl --user daemon-reload && systemctl --user enable --now herdgate
|
|
263
|
-
# tunnel: cloudflared --config ~/.cloudflared/herdgate.yml tunnel run herdgate
|
|
264
|
-
# (a second unit wrapping that line, same shape)
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
Other platforms:
|
|
268
|
-
|
|
269
|
-
```sh
|
|
270
|
-
# launchd agent sketch (adjust paths); or use tmux/systemd-in-wsl as you prefer
|
|
271
|
-
cat > ~/Library/LaunchAgents/dev.herdgate.cloud.plist <<'PLIST'
|
|
272
|
-
<?xml version="1.0" encoding="UTF-8"?>
|
|
273
|
-
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
274
|
-
<plist version="1.0"><dict>
|
|
275
|
-
<key>Label</key><string>dev.herdgate.cloud</string>
|
|
276
|
-
<key>ProgramArguments</key><array>
|
|
277
|
-
<string>/Users/bom/.nvm/versions/node/v22.23.1/bin/node</string>
|
|
278
|
-
<string>/home/bom/source/herdgate/src/cloud/main.ts</string>
|
|
279
|
-
</array>
|
|
280
|
-
<key>RunAtLoad</key><true/>
|
|
281
|
-
<key>KeepAlive</key><true/>
|
|
282
|
-
<key>EnvironmentVariables</key><dict>
|
|
283
|
-
<key>HERDGATE_ACCOUNT_TOKEN</key><string>…</string>
|
|
284
|
-
<key>HERDGATE_STATE</key><string>/Users/bom/.herdgate/state.json</string>
|
|
285
|
-
<key>HERDGATE_PUBLIC_HOST</key><string>herd.example.com</string>
|
|
286
|
-
<key>HERDGATE_PUBLIC_URL</key><string>https://herd.example.com</string>
|
|
287
|
-
</dict>
|
|
288
|
-
</dict></plist>
|
|
289
|
-
PLIST
|
|
290
|
-
launchctl load ~/Library/LaunchAgents/dev.herdgate.cloud.plist
|
|
291
|
-
```
|
|
247
|
+
## Keep the Gate running
|
|
292
248
|
|
|
293
|
-
|
|
249
|
+
Use the packaged [systemd unit or Compose](templates/cloud/README.md) on Linux.
|
|
250
|
+
For a foreground source/npm install, set a persistent state file and use
|
|
251
|
+
`HERDGATE_ACCOUNT_TOKEN_FILE` instead of storing the token in a unit, plist, or
|
|
252
|
+
shell history. Run the reverse proxy or tunnel separately.
|
|
294
253
|
|
|
295
254
|
## Migrate the Linux TUI publisher
|
|
296
255
|
|
|
@@ -336,6 +295,6 @@ share tokens or keys. Use `herdgate update` for later main-publisher updates.
|
|
|
336
295
|
- Preserve the Gate state and SSH host key in protected backups. Deleting
|
|
337
296
|
state loses room/device registrations; replacing the host key invalidates
|
|
338
297
|
clients' pins.
|
|
339
|
-
- **Rotate the account token** by
|
|
298
|
+
- **Rotate the account token** by replacing the private token file (or old token environment value) and restarting the Gate. Update browsers that use the owner token.
|
|
340
299
|
- **Logs** go to stderr (agent connect/pair events). Payloads are never logged — keep it that way.
|
|
341
300
|
- **Watch the exposure**: `curl -s https://host/healthz` public; everything else needs tokens.
|
package/DESIGN.md
CHANGED
|
@@ -57,7 +57,9 @@ responses carry a `stream {gen, seq}` header; a reconnecting device adds
|
|
|
57
57
|
in order. `gen` changes on every gateway process start, so stale bookkeeping from a
|
|
58
58
|
previous life invalidates in one comparison — the device gets a fresh hello (`resumed:false`)
|
|
59
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).
|
|
60
|
+
(replay what survived; the device re-requests its view). Device-targeted frames are
|
|
61
|
+
visible only to their destination device, live and in replay; sequence gaps between
|
|
62
|
+
its frames are normal because the cursor is room-wide. Frames with an `ssh.*` op are
|
|
61
63
|
**ephemeral**: sent raw, unstamped, never buffered — they belong to an SSH channel that
|
|
62
64
|
died with the drop, and replaying them into a new SSH session would corrupt its wire
|
|
63
65
|
protocol. `pair.granted` (carries the one-time device secret) is likewise never replayed.
|
|
@@ -100,8 +102,9 @@ single-owner deployment model provides multi-tenant isolation.
|
|
|
100
102
|
plugin and the PWA run one identical module) over the payload channel; the device initiates after
|
|
101
103
|
pairing, the host acks with `e2e.ready` (nothing encrypts before the ack — a frame racing the
|
|
102
104
|
handshake's last step would desync the counters forever), and a decrypt failure drops the session for
|
|
103
|
-
renegotiation.
|
|
104
|
-
|
|
105
|
+
renegotiation. Cipher operations are serialized per direction. Host identity is TOFU: the PWA uses
|
|
106
|
+
a full SHA-256 pin, upgrades a matching legacy pin and refuses changed keys or plaintext pane data
|
|
107
|
+
on a pinned room. See `plugin/server/e2e.mjs`.
|
|
105
108
|
4. ~~**Official Herdr adapter**~~ — **done (v0.1.0)**, read-only. `src/host/herdr.ts` runs
|
|
106
109
|
`herdr api snapshot` (verified on Herdr 0.9.5, protocol 22) and maps `workspaces[]`, `tabs[]`, `panes[]`,
|
|
107
110
|
`agents[]` and the focused ids into a versioned view. Device ops are `view` and `ping`; every other op is
|
|
@@ -114,7 +117,9 @@ single-owner deployment model provides multi-tenant isolation.
|
|
|
114
117
|
6. ~~**Push wake**~~ — **done (v0.8.0)**: VAPID keys beside the state file; a paired device stores its web-push
|
|
115
118
|
subscription (`/v1/device/push`); the host sends `wake {device}` and the cloud delivers a silent,
|
|
116
119
|
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.
|
|
120
|
+
PWA's service worker raises a notification only when no window is open. Off by default since v0.9.33;
|
|
121
|
+
opt-in wake uses a fixed HTTPS provider list and connects only to an approved public IPv4 DNS result,
|
|
122
|
+
retaining TLS verification for the provider name and never following redirects.
|
|
118
123
|
7. Multi-account signup, quotas, Postgres state, audit log.
|
|
119
124
|
|
|
120
125
|
## 7. Host payload contract (herdgate.herdr.v1)
|
package/README.md
CHANGED
|
@@ -27,7 +27,7 @@ Both remote connections are outbound; the cloud gateway binds loopback.
|
|
|
27
27
|
| Herdr Mobile (Core) | A real `herdr-core` runtime over SSH | Core terminals and the Core API, subject to the device scope |
|
|
28
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 |
|
|
29
29
|
|
|
30
|
-
The Gateway also supports bounded room-stream resume and VAPID push wake. Pairing, publisher updates and
|
|
30
|
+
The Gateway also supports bounded room-stream resume and opt-in VAPID push wake (off by default). Pairing, publisher updates and
|
|
31
31
|
Mobile authorization are separate: changing the publisher release does not move a room or grant a new scope.
|
|
32
32
|
|
|
33
33
|
## Layout
|
|
@@ -43,6 +43,15 @@ src/web/ the PWA a device opens — served by the cloud, same origin as t
|
|
|
43
43
|
test/ e2e relay, the adapter, and the plugin's own commands
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
+
## Self-hosted release
|
|
47
|
+
|
|
48
|
+
Herdgate ships as one versioned release set. Build it from the checkout with
|
|
49
|
+
`npm ci --ignore-scripts` and `npm run build:release`. The output under `dist/<version>/`
|
|
50
|
+
contains a clean **Cloud** archive (Gate, PWA, optional Mobile TCP edge), a **host** ZIP,
|
|
51
|
+
the **npm** package (CLI, publisher, plugin/mod and Pi skills), and `SHA256SUMS`.
|
|
52
|
+
See [Deploying a clean Gate](DEPLOY.md#deploying-a-clean-gate) for Docker Compose
|
|
53
|
+
or systemd. No credentials, keys, or live state are copied into the Cloud archive.
|
|
54
|
+
|
|
46
55
|
## Quickstart
|
|
47
56
|
|
|
48
57
|
```sh
|
|
@@ -132,7 +141,8 @@ algorithm list) that makes real OpenSSH clients silently abandon publickey auth
|
|
|
132
141
|
an upstream release carries the fix; the system-ssh test below guards the regression.
|
|
133
142
|
|
|
134
143
|
Gateway flags: `HERDGATE_SSH_PORT` (default 2222, `0` disables), `HERDGATE_SSH_BIND` (loopback; `0.0.0.0` for
|
|
135
|
-
LAN phones), `HERDGATE_SSH_KEY` (host key file).
|
|
144
|
+
LAN phones), `HERDGATE_SSH_KEY` (host key file). Set `HERDGATE_SSH_PUBLIC_PORT` if an external TCP edge
|
|
145
|
+
advertises a different port. Verified against real herdr-core 0.1.21.
|
|
136
146
|
Anything that is not `view`/`ping` is refused **on the host** with `read-only` — the cloud cannot see payloads,
|
|
137
147
|
so the host is the last trusted decision point. `act` scope is denied unless `HERDGATE_ALLOW_ACT=1`.
|
|
138
148
|
|
package/bin/herdgate.mjs
CHANGED
|
@@ -25,6 +25,7 @@ const help = `herdgate — every machine, one herd
|
|
|
25
25
|
herdgate pi-skills Sync the bundled skills into your Pi profile.
|
|
26
26
|
herdgate cloud add <name> <https-url>
|
|
27
27
|
herdgate cloud list
|
|
28
|
+
herdgate cloud serve Run a self-hosted Gate from the full npm package (uses HERDGATE_* env).
|
|
28
29
|
herdgate pair --cloud <name> Pair this machine with owner approval.
|
|
29
30
|
herdgate setup [--cloud <name>] [--mobile-act <device-id>]
|
|
30
31
|
Install/configure the publisher for this OS.
|
|
@@ -353,7 +354,11 @@ try {
|
|
|
353
354
|
setupHost();
|
|
354
355
|
trySyncPiSkills();
|
|
355
356
|
} else if (cmd === "pi-skills" && !args.length) trySyncPiSkills();
|
|
356
|
-
else if (cmd === "cloud"
|
|
357
|
+
else if (cmd === "cloud" && args.length === 1 && args[0] === "serve") {
|
|
358
|
+
const entry = join(ROOT, "src", "cloud", "main.ts");
|
|
359
|
+
if (!existsSync(entry)) throw new Error("cloud serve requires the full npm package; use the Cloud archive for Docker or systemd");
|
|
360
|
+
runNode(entry, []);
|
|
361
|
+
} else if (cmd === "cloud") manageCloud(args);
|
|
357
362
|
else if (cmd === "pair") pairHost(args);
|
|
358
363
|
else if (process.platform === "win32" && (
|
|
359
364
|
["install", "setup", "migrate", "start", "update", "install-tui"].includes(cmd) ||
|
package/dist-readme.md
CHANGED
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Bộ này dùng cho máy đã cài **herdr** (app desktop hoặc TUI): cài mod + publisher,
|
|
4
4
|
máy sẽ tự kết nối **out** tới gate (không mở port, không VPN) và xuất hiện trên
|
|
5
|
-
phone/PWA của bạn.
|
|
5
|
+
phone/PWA của bạn. ZIP này không chạy Gate; để tự host Gate mới, dùng
|
|
6
|
+
`herdgate-cloud-<version>.tar.gz` trong cùng bộ phát hành.
|
|
6
7
|
|
|
7
8
|
## Yêu cầu
|
|
8
9
|
|
|
@@ -86,6 +87,7 @@ Cài ZIP không tự migrate hay nâng cấp máy nhà, Gate hoặc VPS.
|
|
|
86
87
|
plugin/server/*.mjs → publisher (mod tự spawn bằng node)
|
|
87
88
|
plugin/herdr-plugin.toml → nếu bạn dùng herdr TUI thay vì app
|
|
88
89
|
windows/ → bộ cài và CLI publisher Windows
|
|
90
|
+
templates/herdgate-via.mjs → cầu SSH qua WSS/443
|
|
89
91
|
|
|
90
92
|
## Gỡ
|
|
91
93
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bom0792/herdgate",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.34",
|
|
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": {
|
|
@@ -12,6 +12,8 @@
|
|
|
12
12
|
"edge": "node src/dev/main.ts",
|
|
13
13
|
"test": "node --test test/*.test.ts",
|
|
14
14
|
"check": "tsc -p tsconfig.json",
|
|
15
|
+
"build:cloud": "tsc -p tsconfig.cloud.json",
|
|
16
|
+
"build:release": "bash scripts/build-release.sh",
|
|
15
17
|
"ssh-bridge": "node src/cloud/ssh-bridge.ts",
|
|
16
18
|
"ssh-tcp-edge": "node src/cloud/ssh-tcp-edge.ts",
|
|
17
19
|
"mobile-tui": "node src/host/mobile-tui.ts",
|
|
@@ -31,18 +33,42 @@
|
|
|
31
33
|
"herdgate": "bin/herdgate.mjs"
|
|
32
34
|
},
|
|
33
35
|
"files": [
|
|
34
|
-
"bin",
|
|
36
|
+
"bin/*.mjs",
|
|
35
37
|
".agents/skills/herdr*/SKILL.md",
|
|
36
38
|
".agents/skills/herdr/herdr_pi.py",
|
|
37
39
|
".agents/skills/herdr/profiles.example.toml",
|
|
38
|
-
"src",
|
|
39
|
-
"
|
|
40
|
-
"
|
|
41
|
-
"
|
|
40
|
+
"src/**/*.ts",
|
|
41
|
+
"src/host/*.mjs",
|
|
42
|
+
"src/web/index.html",
|
|
43
|
+
"src/web/*.css",
|
|
44
|
+
"src/web/*.js",
|
|
45
|
+
"src/web/app.webmanifest",
|
|
46
|
+
"src/web/icons/icon.svg",
|
|
47
|
+
"src/web/icons/icon-192.png",
|
|
48
|
+
"src/web/icons/icon-512.png",
|
|
49
|
+
"app-mod/herdgate/main.js",
|
|
50
|
+
"app-mod/herdgate/mod.json",
|
|
51
|
+
"app-mod/herdgate/herdgate.svg",
|
|
52
|
+
"plugin/herdr-plugin.toml",
|
|
53
|
+
"plugin/server/*.mjs",
|
|
54
|
+
"plugin/server/*.d.mts",
|
|
55
|
+
"scripts/*.mjs",
|
|
56
|
+
"scripts/*.sh",
|
|
42
57
|
"DEPLOY.md",
|
|
43
58
|
"DESIGN.md",
|
|
44
59
|
"dist-readme.md",
|
|
45
|
-
"templates",
|
|
46
|
-
"
|
|
60
|
+
"templates/herdgate-via.mjs",
|
|
61
|
+
"templates/herdgate-tcp-edge.service",
|
|
62
|
+
"templates/cloud/Caddyfile.example",
|
|
63
|
+
"templates/cloud/Dockerfile",
|
|
64
|
+
"templates/cloud/.dockerignore",
|
|
65
|
+
"templates/cloud/gitignore.example",
|
|
66
|
+
"templates/cloud/README.md",
|
|
67
|
+
"templates/cloud/compose.env.example",
|
|
68
|
+
"templates/cloud/compose.yml",
|
|
69
|
+
"templates/cloud/*.service",
|
|
70
|
+
"tsconfig.json",
|
|
71
|
+
"tsconfig.cloud.json",
|
|
72
|
+
"windows/*.mjs"
|
|
47
73
|
]
|
|
48
74
|
}
|
package/plugin/server/e2e.d.mts
CHANGED
|
@@ -12,7 +12,7 @@ export declare function b64d(s: string): Uint8Array;
|
|
|
12
12
|
export declare function utf8e(s: string): Uint8Array;
|
|
13
13
|
export declare function utf8d(u8: Uint8Array): string;
|
|
14
14
|
export declare function concat(...parts: Uint8Array[]): Uint8Array;
|
|
15
|
-
export declare function fingerprint(pub: Uint8Array): string
|
|
15
|
+
export declare function fingerprint(pub: Uint8Array): Promise<string>;
|
|
16
16
|
export declare function generateKeyPair(): Promise<{ jwk: JsonWebKey; pub: Uint8Array }>;
|
|
17
17
|
|
|
18
18
|
export interface NoiseWire {
|
|
@@ -25,7 +25,7 @@ export interface NoiseWire {
|
|
|
25
25
|
export declare class DeviceChannel {
|
|
26
26
|
constructor(self: { jwk: JsonWebKey; pub: Uint8Array });
|
|
27
27
|
begin(): Promise<{ e: string }>;
|
|
28
|
-
acceptReply(msg: { e: string; c: string }): Promise<{ c: string }>;
|
|
28
|
+
acceptReply(msg: { e: string; c: string }, expectedHost?: string | null): Promise<{ c: string }>;
|
|
29
29
|
ready(): boolean;
|
|
30
30
|
hostFingerprint: string | null;
|
|
31
31
|
send(obj: unknown): Promise<{ op: string; n: number; c: string }>;
|
package/plugin/server/e2e.mjs
CHANGED
|
@@ -47,11 +47,15 @@ export function concat(...parts) {
|
|
|
47
47
|
return out;
|
|
48
48
|
}
|
|
49
49
|
|
|
50
|
-
/**
|
|
51
|
-
|
|
50
|
+
/** Legacy pin matching is used only to upgrade existing browser pins. */
|
|
51
|
+
function legacyFingerprint(pub) {
|
|
52
52
|
return b64e(pub.slice(0, 8)).replace(/[^A-Za-z0-9]/g, "").toLowerCase().slice(0, 12);
|
|
53
53
|
}
|
|
54
54
|
|
|
55
|
+
export async function fingerprint(pub) {
|
|
56
|
+
return "SHA256:" + b64e(await sha256(pub)).replace(/=+$/, "");
|
|
57
|
+
}
|
|
58
|
+
|
|
55
59
|
// ---- WebCrypto plumbing ----------------------------------------------------
|
|
56
60
|
|
|
57
61
|
const subtle = globalThis.crypto.subtle;
|
|
@@ -90,31 +94,38 @@ export async function generateKeyPair() {
|
|
|
90
94
|
class CipherState {
|
|
91
95
|
k = null;
|
|
92
96
|
n = 0;
|
|
97
|
+
#tail = Promise.resolve();
|
|
93
98
|
setKey(k) {
|
|
94
99
|
this.k = k;
|
|
95
100
|
}
|
|
96
|
-
nonce() {
|
|
97
|
-
// 96-bit: 4 zero bytes ‖ BE64(n)
|
|
101
|
+
nonce(n) {
|
|
102
|
+
// 96-bit: 4 zero bytes ‖ BE64(n); sessions are bounded below 2^32.
|
|
98
103
|
const iv = new Uint8Array(12);
|
|
99
|
-
new DataView(iv.buffer).setUint32(8,
|
|
104
|
+
new DataView(iv.buffer).setUint32(8, n);
|
|
100
105
|
return iv;
|
|
101
106
|
}
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
await subtle.encrypt({ name: "AES-GCM", iv: this.nonce(), additionalData: ad, tagLength: 128 }, key, plaintext),
|
|
107
|
-
);
|
|
108
|
-
this.n += 1;
|
|
109
|
-
return ct;
|
|
107
|
+
#enqueue(operation) {
|
|
108
|
+
const result = this.#tail.then(operation);
|
|
109
|
+
this.#tail = result.catch(() => {});
|
|
110
|
+
return result;
|
|
110
111
|
}
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
112
|
+
encrypt(ad, plaintext) {
|
|
113
|
+
return this.#enqueue(async () => {
|
|
114
|
+
if (this.n >= 0xffffffff) throw new Error("e2e: nonce exhausted");
|
|
115
|
+
const n = this.n++;
|
|
116
|
+
const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["encrypt"]);
|
|
117
|
+
const ct = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: this.nonce(n), additionalData: ad, tagLength: 128 }, key, plaintext));
|
|
118
|
+
return { ct, n };
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
decrypt(ad, ciphertext, n) {
|
|
122
|
+
return this.#enqueue(async () => {
|
|
123
|
+
if (this.n >= 0xffffffff || (n !== undefined && n !== this.n)) throw new Error("e2e: invalid nonce counter");
|
|
124
|
+
const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["decrypt"]);
|
|
125
|
+
const pt = new Uint8Array(await subtle.decrypt({ name: "AES-GCM", iv: this.nonce(this.n), additionalData: ad, tagLength: 128 }, key, ciphertext));
|
|
126
|
+
this.n += 1;
|
|
127
|
+
return pt;
|
|
128
|
+
});
|
|
118
129
|
}
|
|
119
130
|
}
|
|
120
131
|
|
|
@@ -151,7 +162,7 @@ class Handshake {
|
|
|
151
162
|
}
|
|
152
163
|
/** The `s` token: transport under the current key, else in the clear (ENC0). */
|
|
153
164
|
async writeTokenStatic(pubRaw) {
|
|
154
|
-
const out = this.cs.k ? await this.cs.encrypt(this.h, pubRaw) : pubRaw;
|
|
165
|
+
const out = this.cs.k ? (await this.cs.encrypt(this.h, pubRaw)).ct : pubRaw;
|
|
155
166
|
await this.mixHash(out);
|
|
156
167
|
return out;
|
|
157
168
|
}
|
|
@@ -189,14 +200,18 @@ export class DeviceChannel {
|
|
|
189
200
|
return { e: b64e(this.#e.pub) };
|
|
190
201
|
}
|
|
191
202
|
/** Feed the host's `{op:"e2e.reply", e, c}`; returns the msg3 payload. */
|
|
192
|
-
async acceptReply(msg) {
|
|
203
|
+
async acceptReply(msg, expectedHost = null) {
|
|
193
204
|
const eHost = b64d(msg.e);
|
|
194
205
|
if (eHost.length !== PUB_LEN) throw new Error("e2e: bad host ephemeral");
|
|
195
206
|
await this.#hs.mixHash(eHost);
|
|
196
207
|
await this.#hs.mixKey(await dh(this.#e.jwk, eHost)); // ee
|
|
197
208
|
const sHost = await this.#hs.readTokenStatic(b64d(msg.c)); // s
|
|
198
209
|
if (sHost.length !== PUB_LEN) throw new Error("e2e: bad host static");
|
|
199
|
-
|
|
210
|
+
const fp = await fingerprint(sHost);
|
|
211
|
+
if (expectedHost && expectedHost !== fp && (expectedHost.startsWith("SHA256:") || expectedHost !== legacyFingerprint(sHost))) {
|
|
212
|
+
throw Object.assign(new Error("e2e: host key changed"), { code: "host-key-changed" });
|
|
213
|
+
}
|
|
214
|
+
this.hostFingerprint = fp;
|
|
200
215
|
await this.#hs.mixKey(await dh(this.#e.jwk, sHost)); // es (e_dev × s_host)
|
|
201
216
|
const c = await this.#hs.writeTokenStatic(this.#self.pub); // s_dev
|
|
202
217
|
await this.#hs.mixKey(await dh(this.#self.jwk, eHost)); // se (e_host × s_dev)
|
|
@@ -210,12 +225,11 @@ export class DeviceChannel {
|
|
|
210
225
|
return Boolean(this.sendCs && this.recvCs);
|
|
211
226
|
}
|
|
212
227
|
async send(obj) {
|
|
213
|
-
const ct = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
|
|
214
|
-
return { op: "e2e", n
|
|
228
|
+
const { ct, n } = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
|
|
229
|
+
return { op: "e2e", n, c: b64e(ct) };
|
|
215
230
|
}
|
|
216
231
|
async recv(msg) {
|
|
217
|
-
|
|
218
|
-
return JSON.parse(utf8d(pt));
|
|
232
|
+
return receive(this.recvCs, this.#hs.h, msg);
|
|
219
233
|
}
|
|
220
234
|
}
|
|
221
235
|
|
|
@@ -247,7 +261,7 @@ export class HostChannel {
|
|
|
247
261
|
async acceptFinish(msg) {
|
|
248
262
|
const sDev = await this.#hs.readTokenStatic(b64d(msg.c)); // s_dev
|
|
249
263
|
if (sDev.length !== PUB_LEN) throw new Error("e2e: bad device static");
|
|
250
|
-
this.deviceFingerprint = fingerprint(sDev);
|
|
264
|
+
this.deviceFingerprint = await fingerprint(sDev);
|
|
251
265
|
await this.#hs.mixKey(await dh(this.#e.jwk, sDev)); // se (e_host × s_dev)
|
|
252
266
|
const [c1, c2] = await this.#hs.split();
|
|
253
267
|
this.recvCs = c1; // device → host (c1 encrypts initiator→responder)
|
|
@@ -258,11 +272,16 @@ export class HostChannel {
|
|
|
258
272
|
return Boolean(this.sendCs && this.recvCs);
|
|
259
273
|
}
|
|
260
274
|
async send(obj) {
|
|
261
|
-
const ct = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
|
|
262
|
-
return { op: "e2e", n
|
|
275
|
+
const { ct, n } = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
|
|
276
|
+
return { op: "e2e", n, c: b64e(ct) };
|
|
263
277
|
}
|
|
264
278
|
async recv(msg) {
|
|
265
|
-
|
|
266
|
-
return JSON.parse(utf8d(pt));
|
|
279
|
+
return receive(this.recvCs, this.#hs.h, msg);
|
|
267
280
|
}
|
|
268
281
|
}
|
|
282
|
+
|
|
283
|
+
async function receive(cipher, handshakeHash, msg) {
|
|
284
|
+
if (!Number.isInteger(msg.n) || msg.n < 0 || msg.n >= 0xffffffff) throw new Error("e2e: invalid nonce counter");
|
|
285
|
+
const plaintext = await cipher.decrypt(handshakeHash, b64d(msg.c), msg.n);
|
|
286
|
+
return JSON.parse(utf8d(plaintext));
|
|
287
|
+
}
|