@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 CHANGED
@@ -1,15 +1,65 @@
1
- # Deploying herdgate publicly (cloudflared, this machine)
1
+ # Deploying Herdgate
2
2
 
3
- The cloud binds `127.0.0.1` and is published through a Cloudflare tunnel. Two shapes:
3
+ ## Deploying a clean Gate
4
4
 
5
- ## A. Quick tunnel (no DNS setup, throwaway URL)
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
- 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
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
- ## B. Named tunnel + your domain (stable hostname)
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: /home/bom/.cloudflared/<TUNNEL-ID>.json
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 tunnel run --config ~/.cloudflared/herdgate.yml
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
- export HERDGATE_ACCOUNT_TOKEN=$(openssl rand -base64 32)
43
- export HERDGATE_STATE=$HOME/.herdgate/state.json
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
- HERDGATE_PUBLIC_HOST=gate.local HERDGATE_SSH_PORT=0 npm start # terminal 1
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
- ### 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.
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. 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
+ 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 it running
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
- (The plist above is a sketch — fill the token, keep `node` on your PATH or use the absolute binary.)
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 restarting with a new `HERDGATE_ACCOUNT_TOKEN` (devices must update it).
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). Frames with an `ssh.*` op are
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. 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
+ 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). Verified against real herdr-core 0.1.21.
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") manageCloud(args);
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.31",
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
- "app-mod",
40
- "plugin",
41
- "scripts",
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
- "windows"
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
  }
@@ -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 }>;
@@ -47,11 +47,15 @@ export function concat(...parts) {
47
47
  return out;
48
48
  }
49
49
 
50
- /** Short human-checkable fingerprint of a static public key (8 bytes, url-safe). */
51
- export function fingerprint(pub) {
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) — n stays below 2^32 for our lifetimes.
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, this.n);
104
+ new DataView(iv.buffer).setUint32(8, n);
100
105
  return iv;
101
106
  }
102
- async encrypt(ad, plaintext) {
103
- if (this.n >= 0xffffffff) throw new Error("e2e: nonce exhausted");
104
- const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["encrypt"]);
105
- const ct = new Uint8Array(
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
- async decrypt(ad, ciphertext) {
112
- const key = await subtle.importKey("raw", this.k, "AES-GCM", false, ["decrypt"]);
113
- const pt = new Uint8Array(
114
- await subtle.decrypt({ name: "AES-GCM", iv: this.nonce(), additionalData: ad, tagLength: 128 }, key, ciphertext),
115
- );
116
- this.n += 1;
117
- return pt;
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
- this.hostFingerprint = fingerprint(sHost);
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: this.sendCs.n - 1, c: b64e(ct) };
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
- const pt = await this.recvCs.decrypt(this.#hs.h, b64d(msg.c));
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: this.sendCs.n - 1, c: b64e(ct) };
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
- const pt = await this.recvCs.decrypt(this.#hs.h, b64d(msg.c));
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
+ }