@bom0792/herdgate 0.9.31 → 0.9.35

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,12 +141,24 @@ 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
 
139
149
  ## Herdr TUI → an existing Herdr session
140
150
 
151
+ On the controlling machine, `herdgate connect` does the whole client side in one
152
+ command: device pairing (read or act), one SSH key per cloud, and the matching
153
+ `~/.ssh/config` blocks. The owner token is asked once on a hidden prompt and is
154
+ never stored; afterwards only per-device SSH keys remain on that machine.
155
+
156
+ ```sh
157
+ herdgate connect --cloud <name> --room home --scope act
158
+ ```
159
+
160
+ The manual equivalent, kept for reference and for non-CLI clients:
161
+
141
162
  This is separate from `hc machine add` and the PWA. On the client use the official
142
163
  [Herdr v0.9.5 release](https://github.com/herdrdev/herdr/releases/tag/v0.9.5), including the native Windows ZIP if applicable. On the host run the matching Herdr server and the updated Herdgate publisher. The publisher exposes one session (`default`, or `HERDGATE_HERDR_SESSION` in its environment/config); the SSH device must have **act** scope and its own registered SSH key. `act` can type into panes and control Herdr as the host user.
143
164
 
@@ -12,8 +12,11 @@ export function cloudOrigin(raw) {
12
12
  let url;
13
13
  try { url = new URL(raw); }
14
14
  catch { throw new Error('cloud must be a credential-free HTTPS origin'); }
15
- if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
16
- throw new Error('cloud must be a credential-free HTTPS origin');
15
+ // Plain HTTP only for local development against a loopback gate (same rule as templates/herdgate-via.mjs).
16
+ const loopbackHttp = url.protocol === 'http:' && ['127.0.0.1', 'localhost', '::1'].includes(url.hostname);
17
+ if (url.username || url.password || url.pathname !== '/' || url.search || url.hash ||
18
+ (url.protocol !== 'https:' && !loopbackHttp)) {
19
+ throw new Error('cloud must be a credential-free HTTPS origin (HTTP only for local development)');
17
20
  }
18
21
  return url.origin;
19
22
  }
@@ -29,6 +32,10 @@ function load() {
29
32
  }));
30
33
  }
31
34
 
35
+ export function listClouds() {
36
+ return [...load()];
37
+ }
38
+
32
39
  export function resolveCloud(input) {
33
40
  if (validName.test(input)) {
34
41
  const origin = load().get(input);