@bom0792/herdgate 0.0.0-stage → 0.9.6

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.
Files changed (46) hide show
  1. package/README.md +167 -2
  2. package/app-mod/herdgate/main.js +395 -0
  3. package/app-mod/herdgate/mod.json +5 -0
  4. package/bin/herdgate.mjs +91 -0
  5. package/dist-readme.md +48 -0
  6. package/package.json +36 -3
  7. package/plugin/herdr-plugin.toml +36 -0
  8. package/plugin/server/common.mjs +79 -0
  9. package/plugin/server/e2e.d.mts +43 -0
  10. package/plugin/server/e2e.mjs +268 -0
  11. package/plugin/server/index.mjs +454 -0
  12. package/plugin/server/ssh.mjs +241 -0
  13. package/scripts/build-host-bundle.sh +12 -0
  14. package/scripts/deploy-vps.sh +74 -0
  15. package/scripts/patch-ssh2.mjs +32 -0
  16. package/src/agent/adapter.ts +23 -0
  17. package/src/agent/index.ts +183 -0
  18. package/src/cloud/gateway.ts +946 -0
  19. package/src/cloud/main.ts +88 -0
  20. package/src/cloud/pairing.ts +81 -0
  21. package/src/cloud/ssh-bridge.ts +212 -0
  22. package/src/cloud/sshd.ts +412 -0
  23. package/src/cloud/static.ts +142 -0
  24. package/src/cloud/stores.ts +180 -0
  25. package/src/cloud/util.ts +47 -0
  26. package/src/cloud/vapid.ts +105 -0
  27. package/src/dev/edge-sim.ts +99 -0
  28. package/src/dev/main.ts +33 -0
  29. package/src/host/herdr.ts +316 -0
  30. package/src/host/main.ts +105 -0
  31. package/src/host/ssh.ts +317 -0
  32. package/src/index.ts +5 -0
  33. package/src/protocol/agent.ts +84 -0
  34. package/src/protocol/device.ts +90 -0
  35. package/src/protocol/envelope.ts +58 -0
  36. package/src/protocol/index.ts +3 -0
  37. package/src/web/app.css +312 -0
  38. package/src/web/app.js +835 -0
  39. package/src/web/app.webmanifest +15 -0
  40. package/src/web/e2e.js +268 -0
  41. package/src/web/herdgate-host.zip +0 -0
  42. package/src/web/icons/icon-192.png +0 -0
  43. package/src/web/icons/icon-512.png +0 -0
  44. package/src/web/icons/icon.svg +6 -0
  45. package/src/web/index.html +99 -0
  46. package/src/web/sw.js +98 -0
@@ -0,0 +1,946 @@
1
+ /**
2
+ * The herdgate gateway (v0): HTTP + two WebSocket legs behind one gate.
3
+ *
4
+ * GET /healthz liveness (public)
5
+ * POST /v1/agent/code mint a host pairing code (rate-limited, no auth)
6
+ * POST /v1/agent/approve approve a code (account token)
7
+ * GET /v1/agent/code/:code/status the host polls for its room token
8
+ * GET /v1/agent/ws host-agent leg (hello-first, room token)
9
+ * GET /v1/device/ws device leg (hello-first, account token)
10
+ *
11
+ * Deployment: bind 127.0.0.1, publish through `cloudflared` (DEPLOY.md). The
12
+ * cloud is the identity provider — no Cloudflare Access in front is required,
13
+ * and none of its headers are trusted. If `expectedHost` is set, every request
14
+ * must carry that Host (the public hostname), else 421.
15
+ *
16
+ * Payload rule: `frame.payload` is routed, never parsed (see protocol/envelope.ts).
17
+ */
18
+
19
+ import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
20
+ import { request as httpRequest } from "node:http";
21
+ import { request as httpsRequest } from "node:https";
22
+ import { Duplex, type Stream } from "node:stream";
23
+ import { WebSocketServer, type WebSocket } from "ws";
24
+ import {
25
+ decode,
26
+ encode,
27
+ HELLO_TIMEOUT_MS,
28
+ isScope,
29
+ MAX_FRAME_BYTES,
30
+ PAIR_ANSWER_MS,
31
+ RATE_BURST,
32
+ RATE_MSG_PER_S,
33
+ type DeviceView,
34
+ type Envelope,
35
+ } from "../protocol/index.ts";
36
+ import { AgentCodes } from "./pairing.ts";
37
+ import { parseAuthorizedKey, sshKeyFingerprint } from "./sshd.ts";
38
+ import { type Account, type DeviceRecord, type RoomRecord, State } from "./stores.ts";
39
+ import { readJsonBody, randomId, sameSecret, sha256Hex } from "./util.ts";
40
+ import { serveStatic } from "./static.ts";
41
+ import { startSshd, type SshHandle, type SshConfig } from "./sshd.ts";
42
+ import { endpointTag, vapidHeader, type VapidKeys } from "./vapid.ts";
43
+
44
+ export interface CloudConfig {
45
+ accounts: { id: string; name: string; token: string }[];
46
+ bind?: string;
47
+ port?: number;
48
+ /** JSON state file (rooms + devices); omit for in-memory. */
49
+ statePath?: string;
50
+ /** The public hostname cloudflared serves; enforced as `Host` when set. */
51
+ expectedHost?: string;
52
+ /** Shown in pairing-code responses; e.g. `https://herd.example.com`. */
53
+ publicUrl?: string | null;
54
+ /** Directory of the PWA (src/web). Served on `/`; omit to serve no UI. */
55
+ webRoot?: string;
56
+ /** The SSH leg phones dial. `port: 0` disables. */
57
+ ssh?: SshConfig;
58
+ /** The hostname phones should dial for the SSH leg (e.g. an AAAA/DNS-only name). */
59
+ sshHost?: string;
60
+ /** VAPID keys for silent wake pushes; omit to disable the push endpoints. */
61
+ push?: { keys: VapidKeys; /** mailto contact required by the VAPID spec. */ sub: string } | null;
62
+ log?: (line: string) => void;
63
+ }
64
+
65
+ interface AgentConn {
66
+ ws: WebSocket;
67
+ room: RoomRecord;
68
+ alive: boolean;
69
+ }
70
+ interface DeviceConn {
71
+ ws: WebSocket;
72
+ account: Account;
73
+ device: DeviceRecord | null;
74
+ alive: boolean;
75
+ /** True when this socket authenticated with a device secret, not the account token. */
76
+ viaDeviceSecret: boolean;
77
+ }
78
+
79
+ export interface Cloud {
80
+ server: Server;
81
+ port: number;
82
+ /** The SSH leg, when enabled. */
83
+ ssh: SshHandle | null;
84
+ close(): Promise<void>;
85
+ }
86
+
87
+ export function startCloud(cfg: CloudConfig): Promise<Cloud> {
88
+ const log = cfg.log ?? (() => {});
89
+ const state = new State(cfg.accounts, cfg.statePath);
90
+ const codes = new AgentCodes(Date.now, cfg.publicUrl ?? null);
91
+ let sshd: SshHandle | null = null;
92
+
93
+ const agentByRoom = new Map<string, AgentConn>(); // roomId → conn
94
+ const deviceConns = new Set<DeviceConn>();
95
+ const pendingPairs = new Map<string, (ok: boolean) => void>(); // requestId → resolve
96
+
97
+ // ---- SSH bridges: a reachable front door for the SSH leg --------------------
98
+ // A bridge runs on any host with an open port (e.g. a tiny VPS), dials the cloud
99
+ // over wss (outbound only) and pipes raw SSH bytes both ways. Device auth, scopes
100
+ // and the read-only allowlist all live in the sshd behind the gate — the bridge
101
+ // carries no secrets, so the account token (owner-level) is its credential.
102
+ interface BridgeConn {
103
+ ws: WebSocket;
104
+ account: Account;
105
+ /** What phones should dial ({host, port}); when set, the device hello prefers it. */
106
+ advertise: { host: string; port: number } | null;
107
+ }
108
+ const bridges = new Set<BridgeConn>();
109
+
110
+ /** A virtual SSH client socket: bytes arrive from / leave to a bridged wss frame. */
111
+ class VirtualSshSocket extends Duplex {
112
+ readonly remoteAddress = "bridge"; // the sshd's strike map sees one source — documented
113
+ readonly remoteFamily = "IPv4";
114
+ readonly remotePort = 0;
115
+ constructor() {
116
+ super({ allowHalfOpen: false });
117
+ }
118
+ // ssh2 (isWritable) also reads these — Duplex provides writable/_readableState.
119
+ _write(chunk: Buffer, _enc: string, cb: (err?: Error | null) => void): void {
120
+ this.emit("tobytes", chunk);
121
+ cb(null);
122
+ }
123
+ _read(): void {
124
+ /* pushed from the bridge leg */
125
+ }
126
+ }
127
+
128
+ // ---- room streams (resume support) ----
129
+ // Messages a phone must not lose while it is away (host frames, presence) are
130
+ // stamped with a room-scoped `seq` and buffered briefly. A reconnecting device
131
+ // says how far it read (`resume: { room, gen, seq }`) and gets the tail back;
132
+ // `gen` changes whenever the gateway process is (re)started, which invalidates
133
+ // stale bookkeeping in one comparison. `ssh.*` frames are ephemeral by
134
+ // contract — they belong to an SSH channel that died with the drop — so they
135
+ // are sent raw and never buffered or replayed.
136
+ const STREAM_KEEP_MS = 120_000;
137
+ const STREAM_MAX_BYTES = 256 * 1024;
138
+ interface StreamMsg {
139
+ seq: number;
140
+ msg: Record<string, unknown>;
141
+ bytes: number;
142
+ at: number;
143
+ }
144
+ interface RoomStream {
145
+ gen: string;
146
+ seq: number;
147
+ buf: StreamMsg[];
148
+ bytes: number;
149
+ /** Everything at or below this was evicted: resuming from earlier = gap. */
150
+ evictedUpTo: number;
151
+ }
152
+ const streams = new Map<string, RoomStream>();
153
+ const streamOf = (roomId: string): RoomStream => {
154
+ let s = streams.get(roomId);
155
+ if (!s) {
156
+ s = { gen: randomId("g"), seq: 0, buf: [], bytes: 0, evictedUpTo: 0 };
157
+ streams.set(roomId, s);
158
+ }
159
+ return s;
160
+ };
161
+ /** Silent wake push to a device's stored endpoint (VAPID, no payload). */
162
+ const wakeDevice = (deviceId: string): void => {
163
+ const push = cfg.push;
164
+ const endpoint = state.deviceById(deviceId)?.push?.endpoint;
165
+ if (!push || !endpoint) return;
166
+ try {
167
+ const u = new URL(endpoint);
168
+ const send = u.protocol === "https:" ? httpsRequest : httpRequest;
169
+ const req = send(
170
+ {
171
+ protocol: u.protocol,
172
+ hostname: u.hostname,
173
+ port: u.port || (u.protocol === "https:" ? 443 : 80),
174
+ path: `${u.pathname}${u.search}`,
175
+ method: "POST",
176
+ headers: {
177
+ TTL: "60",
178
+ Urgency: "normal",
179
+ "content-length": "0",
180
+ Authorization: vapidHeader(endpoint, push.keys, push.sub),
181
+ },
182
+ },
183
+ (res) => {
184
+ res.resume();
185
+ if (res.statusCode && res.statusCode >= 400) log(`push: wake ${endpointTag(endpoint)} answered ${res.statusCode}`);
186
+ },
187
+ );
188
+ req.on("error", (e) => log(`push: wake ${endpointTag(endpoint)} failed (${e instanceof Error ? e.message : String(e)})`));
189
+ req.end();
190
+ } catch (e) {
191
+ // A bad endpoint must never take the gateway down.
192
+ log(`push: wake ${endpointTag(endpoint)} failed (${e instanceof Error ? e.message : String(e)})`);
193
+ }
194
+ };
195
+
196
+ const streamEmit = (roomId: string, msg: Record<string, unknown>): void => {
197
+ const s = streamOf(roomId);
198
+ s.seq += 1;
199
+ const stamped = { ...msg, seq: s.seq };
200
+ const text = encode(stamped);
201
+ const bytes = Buffer.byteLength(text);
202
+ const at = Date.now();
203
+ const evict = (): void => {
204
+ const old = s.buf.shift();
205
+ if (!old) return;
206
+ s.bytes -= old.bytes;
207
+ if (old.seq > s.evictedUpTo) s.evictedUpTo = old.seq;
208
+ };
209
+ while (s.buf.length && s.buf[0].at < at - STREAM_KEEP_MS) evict();
210
+ if (bytes > STREAM_MAX_BYTES) {
211
+ // Too big to ever keep: a hole for anyone not connected right now.
212
+ if (s.seq > s.evictedUpTo) s.evictedUpTo = s.seq;
213
+ } else {
214
+ while (s.bytes + bytes > STREAM_MAX_BYTES) evict();
215
+ s.buf.push({ seq: s.seq, msg: stamped, bytes, at });
216
+ s.bytes += bytes;
217
+ }
218
+ for (const c of deviceConns) {
219
+ if (c.device?.roomId !== roomId) continue;
220
+ try {
221
+ c.ws.send(text);
222
+ } catch {
223
+ /* closing */
224
+ }
225
+ }
226
+ };
227
+
228
+ // ---- rate limiting: failed hellos per IP ----
229
+ const fails = new Map<string, { n: number; until: number }>();
230
+ const ipOf = (req: IncomingMessage): string => req.socket.remoteAddress ?? "?";
231
+ const strike = (ip: string): void => {
232
+ const f = fails.get(ip) ?? { n: 0, until: 0 };
233
+ f.n += 1;
234
+ if (f.n >= 5) {
235
+ f.until = Date.now() + 60_000;
236
+ f.n = 0;
237
+ }
238
+ fails.set(ip, f);
239
+ };
240
+ const blocked = (ip: string): boolean => {
241
+ const f = fails.get(ip);
242
+ return !!f && f.until > Date.now();
243
+ };
244
+
245
+ const send = (ws: WebSocket, msg: Record<string, unknown>): void => {
246
+ if (ws.readyState === ws.OPEN) {
247
+ try {
248
+ ws.send(encode(msg));
249
+ } catch {
250
+ /* closing */
251
+ }
252
+ }
253
+ };
254
+ const fail = (ws: WebSocket, code: string, message: string): void => send(ws, { t: "error", code, message });
255
+
256
+ // ---- registry helpers ----
257
+ const deviceViews = (roomId: string): DeviceView[] =>
258
+ state.devicesOfRoom(roomId).map((d) => ({
259
+ id: d.id,
260
+ name: d.name,
261
+ scope: d.scope,
262
+ connected: [...deviceConns].some((c) => c.device?.id === d.id),
263
+ }));
264
+
265
+ const pushRoomUpdate = (roomId: string): void => {
266
+ const a = agentByRoom.get(roomId);
267
+ if (a) send(a.ws, { t: "room.update", devices: deviceViews(roomId) });
268
+ };
269
+
270
+ const pushPresence = (roomId: string, online: boolean): void => {
271
+ streamEmit(roomId, { t: "presence", roomId, online });
272
+ };
273
+
274
+ const agentViews = (accountId: string) =>
275
+ state.roomsOfAccount(accountId).map((r) => ({
276
+ roomId: r.id,
277
+ name: r.name,
278
+ online: agentByRoom.has(r.id),
279
+ }));
280
+
281
+ // ---- WebSocket plumbing ----
282
+ const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES });
283
+
284
+ const keepAlive = (getAlive: () => boolean, ws: WebSocket): NodeJS.Timeout => {
285
+ const iv = setInterval(() => {
286
+ if (!getAlive()) {
287
+ ws.terminate();
288
+ return;
289
+ }
290
+ ws.ping();
291
+ }, 30_000);
292
+ iv.unref?.();
293
+ return iv;
294
+ };
295
+
296
+ /** Token bucket: returns false when over the rate (the caller closes 1008). */
297
+ const bucket = (perSec = RATE_MSG_PER_S, burst = RATE_BURST) => {
298
+ let tokens = burst;
299
+ let last = Date.now();
300
+ return (): boolean => {
301
+ const now = Date.now();
302
+ tokens = Math.min(burst, tokens + ((now - last) / 1000) * perSec);
303
+ last = now;
304
+ if (tokens < 1) return false;
305
+ tokens -= 1;
306
+ return true;
307
+ };
308
+ };
309
+
310
+ const upgrade = (req: IncomingMessage, socket: import("node:stream").Duplex, head: Buffer, leg: "agent" | "device" | "bridge"): void => {
311
+ const ip = ipOf(req);
312
+ if (blocked(ip)) {
313
+ socket.write("HTTP/1.1 429 Too Many Requests\r\n\r\n");
314
+ socket.destroy();
315
+ return;
316
+ }
317
+ wss.handleUpgrade(req, socket, head, (ws) => {
318
+ if (leg === "agent") attachAgent(ws, ip);
319
+ else if (leg === "bridge") attachBridge(ws, ip);
320
+ else attachDevice(ws, ip);
321
+ });
322
+ };
323
+
324
+ const attachAgent = (ws: WebSocket, ip: string): void => {
325
+ let conn: AgentConn | null = null;
326
+ let done = false;
327
+ const take = bucket();
328
+ const helloTimer = setTimeout(() => {
329
+ if (!done) ws.close(4001, "hello timeout");
330
+ }, HELLO_TIMEOUT_MS);
331
+ const iv = keepAlive(() => conn?.alive ?? true, ws);
332
+
333
+ ws.on("pong", () => {
334
+ if (conn) conn.alive = true;
335
+ });
336
+ ws.on("message", (data, isBinary) => {
337
+ if (isBinary) return ws.close(1003, "text only");
338
+ // Size is enforced by `maxPayload` on the server; decode still guards shape.
339
+ if (conn && !take()) return ws.close(1008, "rate");
340
+ const m = decode(String(data));
341
+ if (!m) return fail(ws, "bad-message", "not a v1 envelope");
342
+
343
+ if (!conn) {
344
+ if (m.t !== "hello" || typeof m.roomToken !== "string") {
345
+ strike(ip);
346
+ return ws.close(4001, "bad hello");
347
+ }
348
+ const room = state.roomByTokenHash(sha256Hex(m.roomToken));
349
+ if (!room) {
350
+ strike(ip);
351
+ return ws.close(4001, "unknown room token");
352
+ }
353
+ done = true;
354
+ clearTimeout(helloTimer);
355
+ const old = agentByRoom.get(room.id);
356
+ if (old) {
357
+ send(old.ws, { t: "error", code: "superseded", message: "another connection took this room" });
358
+ old.ws.close(4000, "superseded");
359
+ }
360
+ conn = { ws, room, alive: true };
361
+ agentByRoom.set(room.id, conn);
362
+ log(`agent ${room.id} (${room.name}) connected`);
363
+ send(ws, { t: "hello", roomId: room.id, roomName: room.name, devices: deviceViews(room.id), resumed: false });
364
+ pushPresence(room.id, true);
365
+ return;
366
+ }
367
+
368
+ const room = conn.room;
369
+ switch (m.t) {
370
+ case "frame": {
371
+ const device = typeof m.device === "string" ? m.device : null;
372
+ if (!device) return fail(ws, "bad-message", "frame.device");
373
+ const payload = m.payload;
374
+ const isSsh = typeof payload === "object" && payload !== null && typeof (payload as { op?: unknown }).op === "string" && String((payload as { op: string }).op).startsWith("ssh.");
375
+ // Host→device ssh.* frames also feed the sshd, which writes them into the
376
+ // phone's SSH channel; the payload stays opaque to this layer either way.
377
+ if (isSsh) {
378
+ sshd?.onHostFrame(device, payload as Record<string, unknown>);
379
+ // Ephemeral: raw, unstamped, never buffered (see room streams above).
380
+ const text = encode({ t: "frame", payload });
381
+ for (const c of deviceConns) {
382
+ if (c.device?.id !== device) continue;
383
+ try {
384
+ c.ws.send(text);
385
+ } catch {
386
+ /* closing */
387
+ }
388
+ }
389
+ return;
390
+ }
391
+ streamEmit(room.id, { t: "frame", payload });
392
+ return;
393
+ }
394
+ case "presence": {
395
+ pushPresence(room.id, m.online === true);
396
+ return;
397
+ }
398
+ case "pair.response": {
399
+ const requestId = typeof m.requestId === "string" ? m.requestId : null;
400
+ const resolve = requestId ? pendingPairs.get(requestId) : null;
401
+ if (!requestId || !resolve) return fail(ws, "bad-message", "unknown requestId");
402
+ pendingPairs.delete(requestId);
403
+ resolve(m.ok === true);
404
+ return;
405
+ }
406
+ case "wake": {
407
+ // The host asks for a phone to be woken: deliver a silent push only if the
408
+ // device is not connected right now (a connected one is already live).
409
+ if (!cfg.push) return fail(ws, "no-push", "push is not configured");
410
+ const deviceId = typeof m.device === "string" ? m.device : null;
411
+ if (!deviceId) return fail(ws, "bad-message", "wake.device");
412
+ const rec = state.deviceById(deviceId);
413
+ if (!rec || rec.roomId !== room.id) return fail(ws, "no-such-device", "not one of this room's devices");
414
+ if ([...deviceConns].some((c) => c.device?.id === deviceId)) return;
415
+ wakeDevice(deviceId);
416
+ return;
417
+ }
418
+ case "ping":
419
+ return send(ws, { t: "pong", n: m.n ?? 0 });
420
+ default:
421
+ return fail(ws, "unknown", `agent leg has no ${m.t}`);
422
+ }
423
+ });
424
+ ws.on("close", () => {
425
+ clearTimeout(helloTimer);
426
+ clearInterval(iv);
427
+ if (conn && agentByRoom.get(conn.room.id)?.ws === ws) {
428
+ agentByRoom.delete(conn.room.id);
429
+ log(`agent ${conn.room.id} disconnected`);
430
+ pushPresence(conn.room.id, false);
431
+ pushRoomUpdate(conn.room.id);
432
+ }
433
+ });
434
+ };
435
+
436
+ /**
437
+ * The bridge leg (`/v1/bridge/ws`): owner-token hello, then `bridge.open/data/close`
438
+ * frames carrying one phone's raw SSH bytes each. Bytes land in the sshd through a
439
+ * virtual socket — auth, scopes and the allowlist are unchanged, inside SSH.
440
+ */
441
+ const attachBridge = (ws: WebSocket, ip: string): void => {
442
+ let conn: BridgeConn | null = null;
443
+ let done = false;
444
+ const sessions = new Map<string, VirtualSshSocket>();
445
+ const take = bucket(600, 1200); // SSH chunks: higher ceiling than interactive legs
446
+ const helloTimer = setTimeout(() => {
447
+ if (!done) ws.close(4001, "hello timeout");
448
+ }, HELLO_TIMEOUT_MS);
449
+ const iv = keepAlive(() => conn !== null, ws);
450
+ ws.on("pong", () => {
451
+ /* conn presence is the liveness marker for bridges */
452
+ });
453
+
454
+ ws.on("message", (data, isBinary) => {
455
+ if (isBinary) return ws.close(1003, "text only");
456
+ const m = decode(String(data));
457
+ if (!m) return fail(ws, "bad-message", "not a v1 envelope");
458
+ if (conn && !take()) return ws.close(1008, "rate");
459
+
460
+ if (!conn) {
461
+ if (m.t !== "hello" || typeof m.bridgeToken !== "string") {
462
+ strike(ip);
463
+ return ws.close(4001, "bad hello");
464
+ }
465
+ const bridgeToken = m.bridgeToken;
466
+ const account = typeof bridgeToken === "string" ? (cfg.accounts.find((a) => sameSecret(a.token, bridgeToken)) ?? null) : null;
467
+ if (!account) {
468
+ strike(ip);
469
+ return ws.close(4001, "unknown bridge token");
470
+ }
471
+ if (!sshd) {
472
+ return ws.close(4001, "ssh leg disabled on this cloud");
473
+ }
474
+ const ad = m.advertise;
475
+ const advertise =
476
+ ad && typeof ad === "object" && typeof (ad as { host?: unknown }).host === "string" && typeof (ad as { port?: unknown }).port === "number" && Number.isSafeInteger((ad as { port: number }).port) && (ad as { port: number }).port > 0 && (ad as { port: number }).port < 65536
477
+ ? { host: String((ad as { host: string }).host).slice(0, 255), port: (ad as { port: number }).port }
478
+ : null;
479
+ done = true;
480
+ clearTimeout(helloTimer);
481
+ conn = { ws, account, advertise };
482
+ bridges.add(conn);
483
+ log(`bridge (${account.name}) connected${advertise ? ` — phones dial ${advertise.host}:${advertise.port}` : ""}`);
484
+ send(ws, { t: "hello", ok: true });
485
+ return;
486
+ }
487
+
488
+ switch (m.t) {
489
+ case "bridge.open": {
490
+ const sid = typeof m.sid === "string" ? m.sid : "";
491
+ if (!sid || sessions.has(sid)) return fail(ws, "bad-message", "bridge.open.sid");
492
+ if (!sshd) return fail(ws, "no-ssh", "ssh leg disabled");
493
+ const sock = new VirtualSshSocket();
494
+ sessions.set(sid, sock);
495
+ sock.on("tobytes", (chunk: Buffer) => send(ws, { t: "bridge.data", sid, b64: chunk.toString("base64") }));
496
+ sock.on("close", () => {
497
+ sessions.delete(sid);
498
+ send(ws, { t: "bridge.close", sid });
499
+ });
500
+ sshd.inject(sock as unknown as import("node:net").Socket);
501
+ return;
502
+ }
503
+ case "bridge.data": {
504
+ const sid = typeof m.sid === "string" ? m.sid : "";
505
+ const sock = sessions.get(sid);
506
+ if (!sock || typeof m.b64 !== "string") return fail(ws, "bad-message", "bridge.data");
507
+ sock.push(Buffer.from(m.b64, "base64"));
508
+ return;
509
+ }
510
+ case "bridge.close": {
511
+ const sid = typeof m.sid === "string" ? m.sid : "";
512
+ const sock = sessions.get(sid);
513
+ if (sock) {
514
+ sock.push(null); // EOF into the sshd
515
+ sock.destroy();
516
+ }
517
+ return;
518
+ }
519
+ case "ping":
520
+ return send(ws, { t: "pong", n: m.n ?? 0 });
521
+ default:
522
+ return fail(ws, "unknown", `bridge leg has no ${m.t}`);
523
+ }
524
+ });
525
+
526
+ ws.on("close", () => {
527
+ clearTimeout(helloTimer);
528
+ clearInterval(iv);
529
+ for (const sock of sessions.values()) sock.destroy();
530
+ sessions.clear();
531
+ if (conn && bridges.has(conn)) {
532
+ bridges.delete(conn);
533
+ log(`bridge (${conn.account.name}) disconnected`);
534
+ }
535
+ });
536
+ };
537
+
538
+ const attachDevice = (ws: WebSocket, ip: string): void => {
539
+ let conn: DeviceConn | null = null;
540
+ let done = false;
541
+ const take = bucket();
542
+ const helloTimer = setTimeout(() => {
543
+ if (!done) ws.close(4001, "hello timeout");
544
+ }, HELLO_TIMEOUT_MS);
545
+ const iv = keepAlive(() => conn?.alive ?? true, ws);
546
+
547
+ ws.on("pong", () => {
548
+ if (conn) conn.alive = true;
549
+ });
550
+ ws.on("message", (data, isBinary) => {
551
+ if (isBinary) return ws.close(1003, "text only");
552
+ // Size is enforced by `maxPayload` on the server; decode still guards shape.
553
+ if (conn && !take()) return ws.close(1008, "rate");
554
+ const m = decode(String(data));
555
+ if (!m) return fail(ws, "bad-message", "not a v1 envelope");
556
+
557
+ if (!conn) {
558
+ if (m.t !== "hello") {
559
+ strike(ip);
560
+ return ws.close(4001, "bad hello");
561
+ }
562
+ // Two identities: the owner (account token) or a paired device (id + its own secret).
563
+ const wantsDevice = typeof m.device === "string" && typeof m.deviceSecret === "string";
564
+ if (!wantsDevice && typeof m.accountToken !== "string") {
565
+ strike(ip);
566
+ return ws.close(4001, "bad hello");
567
+ }
568
+ let account: Account | null = null;
569
+ let device: DeviceRecord | null = null;
570
+ let viaDeviceSecret = false;
571
+ if (wantsDevice) {
572
+ device = state.deviceByCredentials(m.device as string, m.deviceSecret as string);
573
+ if (!device) {
574
+ strike(ip);
575
+ return ws.close(4001, "unknown device credentials");
576
+ }
577
+ account = state.accountById(device.accountId);
578
+ viaDeviceSecret = true;
579
+ } else {
580
+ account = state.accountByToken(m.accountToken as string);
581
+ if (!account) {
582
+ strike(ip);
583
+ return ws.close(4001, "unknown account token");
584
+ }
585
+ if (typeof m.device === "string" && m.device) {
586
+ const d = state.deviceById(m.device);
587
+ device = d && d.accountId === account.id ? d : null;
588
+ if (!device) return fail(ws, "unknown-device", "device id does not belong to this account");
589
+ }
590
+ }
591
+ done = true;
592
+ clearTimeout(helloTimer);
593
+ conn = { ws, account: account!, device, alive: true, viaDeviceSecret };
594
+ deviceConns.add(conn);
595
+ log(`device ${device ? device.id : "?"} (${account!.name}${viaDeviceSecret ? ", device key" : ""}) connected`);
596
+ const agents = state.roomsOfAccount(account!.id).map((r) => {
597
+ const mine = device && device.roomId === r.id ? device.scope : null;
598
+ return { roomId: r.id, name: r.name, online: agentByRoom.has(r.id), scope: mine };
599
+ });
600
+ const helloMsg: Record<string, unknown> = {
601
+ t: "hello",
602
+ session: randomId("s"),
603
+ device: device ? { id: device.id, name: device.name, scope: device.scope, roomId: device.roomId } : null,
604
+ agents,
605
+ };
606
+
607
+ // Resume: a returning device replays what it missed (bounded, best effort).
608
+ // No match (no resume, wrong room, stale gen, seq from another life) falls
609
+ // through to a fresh hello — the device re-requests state on its own.
610
+ const wantResume = ((): { room: string; gen: string; seq: number } | null => {
611
+ if (!device) return null;
612
+ const r = m.resume;
613
+ if (typeof r !== "object" || r === null) return null;
614
+ const room = (r as { room?: unknown }).room;
615
+ const gen = (r as { gen?: unknown }).gen;
616
+ const seq = (r as { seq?: unknown }).seq;
617
+ if (room !== device.roomId || typeof gen !== "string") return null;
618
+ if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0) return null;
619
+ return { room, gen, seq };
620
+ })();
621
+ const resuming = ((): { replay: StreamMsg[]; gap: boolean } | null => {
622
+ if (!wantResume) return null;
623
+ const s = streams.get(wantResume.room);
624
+ if (!s || s.gen !== wantResume.gen || wantResume.seq > s.seq) return null;
625
+ const replay = s.buf.filter((b) => b.seq > wantResume.seq);
626
+ // Missed more than we kept: say so, the device re-syncs its state.
627
+ const gap = replay.length < s.seq - wantResume.seq;
628
+ return { replay, gap };
629
+ })();
630
+
631
+ if (resuming && device) {
632
+ const s = streamOf(device.roomId);
633
+ send(ws, {
634
+ ...helloMsg,
635
+ resumed: true,
636
+ stream: { gen: s.gen, seq: s.seq, gap: resuming.gap },
637
+ });
638
+ for (const b of resuming.replay) {
639
+ try {
640
+ ws.send(encode(b.msg));
641
+ } catch {
642
+ /* closing */
643
+ }
644
+ }
645
+ if (resuming.gap) log(`device ${device.id} resumed with a gap (re-requests state)`);
646
+ } else {
647
+ const s = device ? streamOf(device.roomId) : null;
648
+ send(ws, {
649
+ ...helloMsg,
650
+ resumed: false,
651
+ ...(s ? { stream: { gen: s.gen, seq: s.seq } } : {}),
652
+ ...((): Record<string, unknown> => {
653
+ // A live bridge with an advertised address wins: phones reach the bridge,
654
+ // not the gate machine (which may sit behind NAT with no IPv6).
655
+ if (!cfg.ssh) return {};
656
+ for (const b of bridges) if (b.advertise) return { ssh: { ...b.advertise } };
657
+ // The real port (the listener may be ephemeral), falling back to config.
658
+ return { ssh: { port: sshd?.port ?? cfg.ssh.port, ...(cfg.sshHost ? { host: cfg.sshHost } : {}) } };
659
+ })(),
660
+ });
661
+ }
662
+ if (device) pushRoomUpdate(device.roomId);
663
+ return;
664
+ }
665
+
666
+ switch (m.t) {
667
+ case "frame": {
668
+ const device = conn.device;
669
+ if (!device) return fail(ws, "not-paired", "pair.begin first");
670
+ const agent = agentByRoom.get(device.roomId);
671
+ if (!agent) return fail(ws, "host-offline", "the host is not connected");
672
+ send(agent.ws, { t: "frame", device: device.id, payload: m.payload });
673
+ return;
674
+ }
675
+ case "pair.begin": {
676
+ if (conn.viaDeviceSecret) return fail(ws, "owner-only", "pairing uses the account token");
677
+ const roomId = typeof m.roomId === "string" ? m.roomId : null;
678
+ const name = typeof m.name === "string" ? m.name.trim().slice(0, 64) : "";
679
+ const scope = m.scope;
680
+ const room = roomId ? state.rooms.find((r) => r.id === roomId) : null;
681
+ if (!room || room.accountId !== conn.account.id) return fail(ws, "no-such-room", "roomId is not one of yours");
682
+ if (!name) return fail(ws, "bad-message", "pair.begin.name");
683
+ if (!isScope(scope)) return fail(ws, "bad-message", "pair.begin.scope");
684
+ grantPair(conn, room, name, scope);
685
+ return;
686
+ }
687
+ case "ping":
688
+ return send(ws, { t: "pong", n: m.n ?? 0 });
689
+ default:
690
+ return fail(ws, "unknown", `device leg has no ${m.t}`);
691
+ }
692
+ });
693
+ ws.on("close", () => {
694
+ clearTimeout(helloTimer);
695
+ clearInterval(iv);
696
+ if (conn) {
697
+ deviceConns.delete(conn);
698
+ if (conn.device) pushRoomUpdate(conn.device.roomId);
699
+ }
700
+ });
701
+ };
702
+
703
+ /** `read` pairs at once; `act` needs the host's answer while this socket waits. */
704
+ const grantPair = (conn: DeviceConn, room: RoomRecord, name: string, scope: "read" | "act"): void => {
705
+ const finish = (): void => {
706
+ const { device: rec, secret } = state.addDevice(room, name, scope);
707
+ conn.device = rec;
708
+ deviceConns.add(conn);
709
+ send(conn.ws, {
710
+ t: "pair.granted",
711
+ device: { id: rec.id, name: rec.name, scope: rec.scope, roomId: rec.roomId },
712
+ // One-time: the device stores it (PWA keeps it locally) and re-attaches with it.
713
+ deviceSecret: secret,
714
+ });
715
+ pushRoomUpdate(room.id);
716
+ log(`device ${rec.id} paired to ${room.id} (${scope})`);
717
+ };
718
+ if (scope === "read") return finish();
719
+ const agent = agentByRoom.get(room.id);
720
+ if (!agent) return send(conn.ws, { t: "pair.denied", reason: "host offline" });
721
+ const requestId = randomId("pr");
722
+ const timer = setTimeout(() => {
723
+ pendingPairs.delete(requestId);
724
+ send(conn.ws, { t: "pair.denied", reason: "host did not answer" });
725
+ }, PAIR_ANSWER_MS);
726
+ pendingPairs.set(requestId, (ok) => {
727
+ clearTimeout(timer);
728
+ if (ok) finish();
729
+ else send(conn.ws, { t: "pair.denied", reason: "denied on the host" });
730
+ });
731
+ send(agent.ws, { t: "pair.request", requestId, device: { name }, scope });
732
+ };
733
+
734
+ // ---- HTTP ----
735
+ const hostOk = (req: IncomingMessage): boolean => {
736
+ if (!cfg.expectedHost) return true;
737
+ const host = (req.headers.host ?? "").toLowerCase();
738
+ return host === cfg.expectedHost || host === `${cfg.expectedHost}:443` || host === `${cfg.expectedHost}:80`;
739
+ };
740
+
741
+ const json = (res: ServerResponse, status: number, body: unknown): void => {
742
+ res.writeHead(status, { "content-type": "application/json" });
743
+ res.end(JSON.stringify(body));
744
+ };
745
+
746
+ const accountByAuth = (req: IncomingMessage): Account | null => {
747
+ const h = req.headers.authorization ?? "";
748
+ const token = h.startsWith("Bearer ") ? h.slice(7) : "";
749
+ if (!token) return null;
750
+ return cfg.accounts.find((a) => sameSecret(a.token, token)) ?? null;
751
+ };
752
+
753
+ const server = createServer((req, res) => {
754
+ if (!hostOk(req)) {
755
+ res.writeHead(421);
756
+ return res.end("wrong host");
757
+ }
758
+ const url = new URL(req.url ?? "/", "http://x");
759
+ const path = url.pathname;
760
+
761
+ if (req.method === "GET" && path === "/healthz") {
762
+ res.writeHead(200);
763
+ return res.end("ok");
764
+ }
765
+
766
+ if (req.method === "POST" && path === "/v1/agent/code") {
767
+ if (blocked(ipOf(req))) return json(res, 429, { error: "rate limited" });
768
+ return void readJsonBody(req).then((body) => {
769
+ const name = typeof body?.name === "string" && body.name.trim() ? body.name.trim().slice(0, 64) : "host";
770
+ json(res, 200, codes.mint(name));
771
+ });
772
+ }
773
+
774
+ if (req.method === "POST" && path === "/v1/agent/approve") {
775
+ const account = accountByAuth(req);
776
+ if (!account) return json(res, 401, { error: "account token required" });
777
+ return void readJsonBody(req).then(async (body) => {
778
+ const code = typeof body?.code === "string" ? body.code : "";
779
+ const st = codes.status(code);
780
+ if (st.status !== "pending") return json(res, 404, { error: "unknown or used code" });
781
+ // Re-mint the pending entry's room (fulfill binds the token to it).
782
+ const minted = state.addRoom(account.id, st.hostName ?? "host");
783
+ codes.fulfill(code, minted.token, minted.room.id);
784
+ log(`room ${minted.room.id} (${minted.room.name}) approved by ${account.name}`);
785
+ json(res, 200, { roomId: minted.room.id, name: minted.room.name });
786
+ });
787
+ }
788
+
789
+ const statusMatch = path.match(/^\/v1\/agent\/code\/([A-Za-z0-9]+)\/status$/);
790
+ if (req.method === "GET" && statusMatch) {
791
+ if (blocked(ipOf(req))) return json(res, 429, { error: "rate limited" });
792
+ const st = codes.status(statusMatch[1]);
793
+ if (st.status === "unknown") return json(res, 404, { status: st.status });
794
+ return json(res, 200, st);
795
+ }
796
+
797
+ if (cfg.push && req.method === "GET" && path === "/v1/push/key") {
798
+ return json(res, 200, { publicKey: cfg.push.keys.publicBase64Url });
799
+ }
800
+ if (cfg.push && path === "/v1/device/push") {
801
+ if (blocked(ipOf(req))) return json(res, 429, { error: "rate limited" });
802
+ // Two identities, same as the WS leg: the paired device (id + its own secret in
803
+ // the body) or the owner (account token in Authorization, device id in the body).
804
+ return void readJsonBody(req).then((body) => {
805
+ const deviceId = typeof body?.device === "string" ? body.device : "";
806
+ const deviceSecret = typeof body?.deviceSecret === "string" ? body.deviceSecret : "";
807
+ let device: DeviceRecord | null = deviceId && deviceSecret ? state.deviceByCredentials(deviceId, deviceSecret) : null;
808
+ if (!device) {
809
+ const account = accountByAuth(req);
810
+ if (!account) return json(res, 401, { error: "device credentials or account token required" });
811
+ device = deviceId ? state.deviceById(deviceId) : null;
812
+ if (!device || device.accountId !== account.id) return json(res, 403, { error: "not one of this account's devices" });
813
+ }
814
+ if (req.method === "DELETE") {
815
+ state.setDevicePush(device.id, null);
816
+ return json(res, 200, { ok: true });
817
+ }
818
+ const endpoint = typeof body?.endpoint === "string" ? body.endpoint.trim().slice(0, 2048) : "";
819
+ let u: URL;
820
+ try {
821
+ u = new URL(endpoint);
822
+ } catch {
823
+ return json(res, 400, { error: "bad endpoint" });
824
+ }
825
+ if (u.protocol !== "https:" && u.protocol !== "http:") return json(res, 400, { error: "bad endpoint" });
826
+ state.setDevicePush(device.id, endpoint);
827
+ return json(res, 200, { ok: true });
828
+ });
829
+ }
830
+
831
+ // Device SSH public keys: register the key of the machine that will `hc machine
832
+ // add` this device, so system ssh logs in without a password prompt. Same two
833
+ // identities as /v1/device/push (the device's own secret, or the owner's token).
834
+ if (path === "/v1/device/sshkey") {
835
+ if (blocked(ipOf(req))) return json(res, 429, { error: "rate limited" });
836
+ return void readJsonBody(req).then((body) => {
837
+ // GET carries no body: the device id rides the query, its secret a header
838
+ // (never a query string — those end up in proxy logs).
839
+ const q = new URL(req.url ?? "/", "http://x").searchParams;
840
+ const headerSecret = req.headers["x-herdgate-secret"];
841
+ const deviceId = typeof body?.device === "string" ? body.device : q.get("device") ?? "";
842
+ const deviceSecret = typeof body?.deviceSecret === "string" ? body.deviceSecret : typeof headerSecret === "string" ? headerSecret : "";
843
+ let device: DeviceRecord | null = deviceId && deviceSecret ? state.deviceByCredentials(deviceId, deviceSecret) : null;
844
+ if (!device) {
845
+ const account = accountByAuth(req);
846
+ if (!account) return json(res, 401, { error: "device credentials or account token required" });
847
+ device = deviceId ? state.deviceById(deviceId) : null;
848
+ if (!device || device.accountId !== account.id) return json(res, 403, { error: "not one of this account's devices" });
849
+ }
850
+ if (req.method === "GET") {
851
+ return json(res, 200, {
852
+ keys: (device.sshKeys ?? []).map((k) => ({ algo: k.algo, fp: sshKeyFingerprint(k.b64), comment: k.comment ?? "", at: k.at, b64: k.b64 })),
853
+ });
854
+ }
855
+ if (req.method === "DELETE") {
856
+ const b64 = typeof body?.b64 === "string" ? body.b64 : "";
857
+ if (!b64) return json(res, 400, { error: "b64 required" });
858
+ const removed = state.removeDeviceSshKey(device.id, b64);
859
+ return json(res, removed ? 200 : 404, { ok: removed });
860
+ }
861
+ if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
862
+ const parsed = parseAuthorizedKey(typeof body?.pubkey === "string" ? body.pubkey : "");
863
+ if (!parsed) return json(res, 400, { error: "bad pubkey (want an authorized_keys line: <algo> <base64> [comment])" });
864
+ const added = state.addDeviceSshKey(device.id, parsed.algo, parsed.b64, parsed.comment);
865
+ if (!added && !(state.deviceById(device.id)?.sshKeys ?? []).some((k) => k.algo === parsed.algo && k.b64 === parsed.b64)) {
866
+ return json(res, 422, { error: "too many keys (max 5)" });
867
+ }
868
+ return json(res, 200, { ok: true, fp: sshKeyFingerprint(parsed.b64) });
869
+ });
870
+ }
871
+
872
+ // The PWA, same-origin with the WS legs. Only GET/HEAD, and only after the API
873
+ // routes above, so `/v1/*` can never be shadowed by a file.
874
+ if ((req.method === "GET" || req.method === "HEAD") && cfg.webRoot) {
875
+ return void serveStatic(res, cfg.webRoot, path);
876
+ }
877
+
878
+ res.writeHead(404);
879
+ return res.end("not found");
880
+ });
881
+
882
+ server.on("upgrade", (req, socket, head) => {
883
+ if (!hostOk(req)) {
884
+ socket.write("HTTP/1.1 421 Misdirected Request\r\n\r\n");
885
+ return socket.destroy();
886
+ }
887
+ const path = new URL(req.url ?? "/", "http://x").pathname;
888
+ if (path === "/v1/agent/ws") return upgrade(req, socket, head, "agent");
889
+ if (path === "/v1/device/ws") return upgrade(req, socket, head, "device");
890
+ if (path === "/v1/bridge/ws") return upgrade(req, socket, head, "bridge");
891
+ socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
892
+ socket.destroy();
893
+ });
894
+
895
+ return new Promise((resolve) => {
896
+ server.listen(cfg.port ?? 0, cfg.bind ?? "127.0.0.1", () => {
897
+ const addr = server.address();
898
+ const port = typeof addr === "object" && addr ? addr.port : 0;
899
+
900
+ // The SSH leg shares this process (state + device sockets). Disabled when ssh is
901
+ // false or its port is 0.
902
+ // `ssh` unset = disabled (tests and API-only runs); main.ts turns it on by default.
903
+ // The cloud resolves only once the leg is up or has failed, so callers see the truth.
904
+ const sshPromise: Promise<SshHandle | null> = cfg.ssh
905
+ ? startSshd({
906
+ config: cfg.ssh,
907
+ state,
908
+ log,
909
+ sendAsDevice: (deviceId, payload) => {
910
+ const dev = state.deviceById(deviceId);
911
+ if (!dev) return false;
912
+ const agent = agentByRoom.get(dev.roomId);
913
+ if (!agent) return false;
914
+ send(agent.ws, { t: "frame", device: deviceId, payload });
915
+ return true;
916
+ },
917
+ deviceOnline: (deviceId) => [...deviceConns].some((c) => c.device?.id === deviceId),
918
+ }).catch((e) => {
919
+ log(`ssh: failed to start (${e instanceof Error ? e.message : String(e)})`);
920
+ return null;
921
+ })
922
+ : Promise.resolve(null);
923
+
924
+ void sshPromise.then((h) => {
925
+ sshd = h;
926
+ resolve({
927
+ server,
928
+ port,
929
+ get ssh() {
930
+ return sshd;
931
+ },
932
+ close: () =>
933
+ new Promise<void>((done) => {
934
+ for (const a of agentByRoom.values()) a.ws.close(1001, "server shutdown");
935
+ for (const d of deviceConns) d.ws.close(1001, "server shutdown");
936
+ void sshd?.close();
937
+ server.close(() => done());
938
+ }),
939
+ });
940
+ });
941
+ });
942
+ });
943
+ }
944
+
945
+ /** Silence the unused-import lint for Envelope (kept for API surface clarity). */
946
+ export type { Envelope };