@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.
- package/README.md +167 -2
- package/app-mod/herdgate/main.js +395 -0
- package/app-mod/herdgate/mod.json +5 -0
- package/bin/herdgate.mjs +91 -0
- package/dist-readme.md +48 -0
- package/package.json +36 -3
- package/plugin/herdr-plugin.toml +36 -0
- package/plugin/server/common.mjs +79 -0
- package/plugin/server/e2e.d.mts +43 -0
- package/plugin/server/e2e.mjs +268 -0
- package/plugin/server/index.mjs +454 -0
- package/plugin/server/ssh.mjs +241 -0
- package/scripts/build-host-bundle.sh +12 -0
- package/scripts/deploy-vps.sh +74 -0
- package/scripts/patch-ssh2.mjs +32 -0
- package/src/agent/adapter.ts +23 -0
- package/src/agent/index.ts +183 -0
- package/src/cloud/gateway.ts +946 -0
- package/src/cloud/main.ts +88 -0
- package/src/cloud/pairing.ts +81 -0
- package/src/cloud/ssh-bridge.ts +212 -0
- package/src/cloud/sshd.ts +412 -0
- package/src/cloud/static.ts +142 -0
- package/src/cloud/stores.ts +180 -0
- package/src/cloud/util.ts +47 -0
- package/src/cloud/vapid.ts +105 -0
- package/src/dev/edge-sim.ts +99 -0
- package/src/dev/main.ts +33 -0
- package/src/host/herdr.ts +316 -0
- package/src/host/main.ts +105 -0
- package/src/host/ssh.ts +317 -0
- package/src/index.ts +5 -0
- package/src/protocol/agent.ts +84 -0
- package/src/protocol/device.ts +90 -0
- package/src/protocol/envelope.ts +58 -0
- package/src/protocol/index.ts +3 -0
- package/src/web/app.css +312 -0
- package/src/web/app.js +835 -0
- package/src/web/app.webmanifest +15 -0
- package/src/web/e2e.js +268 -0
- package/src/web/herdgate-host.zip +0 -0
- package/src/web/icons/icon-192.png +0 -0
- package/src/web/icons/icon-512.png +0 -0
- package/src/web/icons/icon.svg +6 -0
- package/src/web/index.html +99 -0
- package/src/web/sw.js +98 -0
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Đóng gói bộ cài host (mod + publisher) và đặt vào web root của gate để tải về.
|
|
3
|
+
set -euo pipefail
|
|
4
|
+
DIR=$(cd "$(dirname "$0")/.." && pwd)
|
|
5
|
+
OUT=$(mktemp -d)
|
|
6
|
+
trap 'rm -rf "$OUT"' EXIT
|
|
7
|
+
mkdir -p "$OUT/herdgate-host/mod"
|
|
8
|
+
cp -r "$DIR/app-mod/herdgate" "$OUT/herdgate-host/mod/"
|
|
9
|
+
cp -r "$DIR/plugin" "$OUT/herdgate-host/"
|
|
10
|
+
cp "$DIR/dist-readme.md" "$OUT/herdgate-host/README.md"
|
|
11
|
+
( cd "$OUT/herdgate-host" && zip -qr "$DIR/src/web/herdgate-host.zip" mod plugin README.md )
|
|
12
|
+
echo "src/web/herdgate-host.zip: $(stat -c%s "$DIR/src/web/herdgate-host.zip") bytes"
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# herdgate → VPS: dựng gateway trực tiếp trên VPS (không Cloudflare tunnel).
|
|
3
|
+
# Dùng: bash scripts/deploy-vps.sh root@<VPS-IP>
|
|
4
|
+
# Yêu cầu bên VPS : Ubuntu/Debian, root (qua key herdgate_deploy), port 80/443/2299 mở.
|
|
5
|
+
# Yêu cầu bên DNS : gate. + ssh. trỏ A → VPS (mây xám) — làm TRƯỚC khi chạy để Caddy xin cert được.
|
|
6
|
+
set -euo pipefail
|
|
7
|
+
TARGET="${1:?dùng: deploy-vps.sh root@<vps-ip>}"
|
|
8
|
+
KEY="$HOME/.ssh/herdgate_deploy"
|
|
9
|
+
DIR=$(cd "$(dirname "$0")/.." && pwd)
|
|
10
|
+
|
|
11
|
+
echo "==> 1/5 sync source + node_modules + state"
|
|
12
|
+
rsync -az --delete -e "ssh -i $KEY" \
|
|
13
|
+
--exclude .git --exclude test --exclude app-mod --exclude plugin/herdr-plugin.toml \
|
|
14
|
+
"$DIR/src" "$DIR/package.json" "$DIR/tsconfig.json" "$DIR/node_modules" "$TARGET:/opt/herdgate/"
|
|
15
|
+
rsync -az -e "ssh -i $KEY" "$HOME/.local/state/herdgate/" "$TARGET:/opt/herdgate-state/"
|
|
16
|
+
|
|
17
|
+
echo "==> 2/5 node 22 (nvm, per-root) + systemd herdgate"
|
|
18
|
+
ssh -i "$KEY" "$TARGET" 'set -e
|
|
19
|
+
if ! command -v node >/dev/null || [ "$(node -v | cut -c2- | cut -d. -f1)" -lt 22 ]; then
|
|
20
|
+
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash >/dev/null
|
|
21
|
+
. ~/.nvm/nvm.sh
|
|
22
|
+
nvm install 22 --silent
|
|
23
|
+
fi
|
|
24
|
+
NODE=$(command -v node)
|
|
25
|
+
mkdir -p ~/.config/systemd/user 2>/dev/null || true
|
|
26
|
+
cat > /etc/systemd/system/herdgate.service <<EOF2
|
|
27
|
+
[Unit]
|
|
28
|
+
Description=herdgate gateway (cloud relay hub)
|
|
29
|
+
After=network-online.target
|
|
30
|
+
Wants=network-online.target
|
|
31
|
+
|
|
32
|
+
[Service]
|
|
33
|
+
ExecStart=$NODE /opt/herdgate/src/cloud/main.ts
|
|
34
|
+
Environment=HERDGATE_BIND=127.0.0.1
|
|
35
|
+
Environment=HERDGATE_PORT=8833
|
|
36
|
+
Environment=HERDGATE_STATE=/opt/herdgate-state/state.json
|
|
37
|
+
Environment=HERDGATE_SSH_PORT=2299
|
|
38
|
+
Environment=HERDGATE_SSH_BIND=0.0.0.0
|
|
39
|
+
Environment=HERDGATE_ACCOUNT_TOKEN=__TOKEN__
|
|
40
|
+
WorkingDirectory=/opt/herdgate
|
|
41
|
+
Restart=always
|
|
42
|
+
RestartSec=3
|
|
43
|
+
|
|
44
|
+
[Install]
|
|
45
|
+
WantedBy=multi-user.target
|
|
46
|
+
EOF2
|
|
47
|
+
'
|
|
48
|
+
|
|
49
|
+
echo "==> 3/5 chèn account token từ unit nhà (base64 qua đường, khỏi sợ ký tự đặc biệt)"
|
|
50
|
+
TOKEN=$(grep -oP 'HERDGATE_ACCOUNT_TOKEN=\K.*' ~/.config/systemd/user/herdgate.service | tr -d '"')
|
|
51
|
+
TOKEN_B64=$(printf %s "$TOKEN" | base64 -w0)
|
|
52
|
+
ssh -i "$KEY" "$TARGET" "python3 -c \"import base64; tok=base64.b64decode('$TOKEN_B64').decode(); p=open('/etc/systemd/system/herdgate.service').read().replace('__TOKEN__',tok); open('/etc/systemd/system/herdgate.service','w').write(p)\""
|
|
53
|
+
|
|
54
|
+
echo "==> 4/5 caddy (TLS tự động) + firewall"
|
|
55
|
+
ssh -i "$KEY" "$TARGET" 'set -e
|
|
56
|
+
if ! command -v caddy >/dev/null; then
|
|
57
|
+
apt-get update -qq && apt-get install -y -qq debian-keyring debian-archive-keyring apt-transport-https curl >/dev/null
|
|
58
|
+
curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/gpg.key | gpg --batch --yes --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
|
|
59
|
+
curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt | tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null
|
|
60
|
+
apt-get update -qq && apt-get install -y -qq caddy >/dev/null
|
|
61
|
+
fi
|
|
62
|
+
cat > /etc/caddy/Caddyfile <<EOF2
|
|
63
|
+
gate.phuongnb.io.vn {
|
|
64
|
+
reverse_proxy 127.0.0.1:8833
|
|
65
|
+
}
|
|
66
|
+
EOF2
|
|
67
|
+
systemctl enable --now caddy >/dev/null 2>&1 || systemctl restart caddy
|
|
68
|
+
command -v ufw >/dev/null && ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 2299/tcp comment herdgate-ssh || true
|
|
69
|
+
'
|
|
70
|
+
|
|
71
|
+
echo "==> 5/5 start herdgate"
|
|
72
|
+
ssh -i "$KEY" "$TARGET" 'systemctl daemon-reload && systemctl enable --now herdgate && sleep 3 && systemctl is-active herdgate'
|
|
73
|
+
|
|
74
|
+
echo "OK — kiểm tra: curl https://gate.phuongnb.io.vn/healthz (sau khi DNS đã trỏ)"
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* ssh2 1.17.0 ships a malformed `server-sig-algs` EXT_INFO: two string literals
|
|
4
|
+
* concatenated without the comma (`…nistp521` + `rsa-sha2-512…`). OpenSSH clients
|
|
5
|
+
* parse that garbled list, conclude Ed25519 signing is not allowed, and silently
|
|
6
|
+
* give up after USERAUTH_PK_OK — publickey auth can never complete against ssh2
|
|
7
|
+
* servers. This fixes the literal in place, idempotently, until an upstream
|
|
8
|
+
* release carries the fix.
|
|
9
|
+
*/
|
|
10
|
+
import { readFileSync, writeFileSync } from "node:fs";
|
|
11
|
+
import { createRequire } from "node:module";
|
|
12
|
+
|
|
13
|
+
const require = createRequire(import.meta.url);
|
|
14
|
+
let path;
|
|
15
|
+
try {
|
|
16
|
+
path = require.resolve("ssh2/lib/protocol/Protocol.js");
|
|
17
|
+
} catch {
|
|
18
|
+
console.error("patch-ssh2: ssh2 not installed, nothing to do");
|
|
19
|
+
process.exit(0);
|
|
20
|
+
}
|
|
21
|
+
let src = readFileSync(path, "utf8");
|
|
22
|
+
const broken = /ecdsa-sha2-nistp521'\s*\+\s*'rsa-sha2-512/;
|
|
23
|
+
if (broken.test(src)) {
|
|
24
|
+
src = src.replace(broken, "ecdsa-sha2-nistp521'\n + ',rsa-sha2-512");
|
|
25
|
+
writeFileSync(path, src);
|
|
26
|
+
console.error(`patch-ssh2: fixed server-sig-algs in ${path}`);
|
|
27
|
+
} else if (src.includes("nistp521'\n + ',rsa-sha2-512") || /nistp521,\s*'?\+?\s*'?rsa-sha2-512/.test(src)) {
|
|
28
|
+
console.error("patch-ssh2: already patched");
|
|
29
|
+
} else {
|
|
30
|
+
// A warning, never a failure: this must not break anyone's `npm install`.
|
|
31
|
+
console.error("patch-ssh2: ssh2 source not recognised (fixed upstream, or a different build) — skipping");
|
|
32
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a local host adapter implements to sit behind herdgate. The first
|
|
3
|
+
* integration target is official Herdr (herdr.dev). The SDK owns the connection and envelope;
|
|
4
|
+
* the adapter owns everything the cloud cannot see.
|
|
5
|
+
*/
|
|
6
|
+
import type { DeviceView } from "../protocol/agent.ts";
|
|
7
|
+
|
|
8
|
+
export interface PairAsk {
|
|
9
|
+
requestId: string;
|
|
10
|
+
device: { name: string };
|
|
11
|
+
scope: "read" | "act";
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export interface AgentAdapter {
|
|
15
|
+
/** Reported in `hello`; the account's devices see `name`. */
|
|
16
|
+
info(): { name: string; version: string; capabilities?: string[] };
|
|
17
|
+
/** An opaque payload from one paired device (its scope is in `devices`). */
|
|
18
|
+
onFrame(device: string, payload: unknown): void;
|
|
19
|
+
/** The paired-device list changed (pair, revoke, connect state). */
|
|
20
|
+
onDevices(devices: DeviceView[]): void;
|
|
21
|
+
/** A device asked for `act`; returning true pairs it. May prompt a human. */
|
|
22
|
+
onPairAsk(ask: PairAsk): boolean | Promise<boolean>;
|
|
23
|
+
}
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HerdGateAgent: one outbound WebSocket from the host to the cloud, with
|
|
3
|
+
* hello-first auth, exponential backoff + jitter on reconnect, and app-level
|
|
4
|
+
* ping/pong. The old connection is superseded server-side when a new one hellos
|
|
5
|
+
* with the same room token.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { encode } from "../protocol/envelope.ts";
|
|
9
|
+
import type { AgentToCloud, CloudToAgent, DeviceView } from "../protocol/agent.ts";
|
|
10
|
+
import { type AgentAdapter, type PairAsk } from "./adapter.ts";
|
|
11
|
+
import WebSocket from "ws";
|
|
12
|
+
|
|
13
|
+
export interface AgentOptions {
|
|
14
|
+
endpoint: string; // wss://host/v1/agent/ws
|
|
15
|
+
roomToken: string;
|
|
16
|
+
adapter: AgentAdapter;
|
|
17
|
+
log?: (line: string) => void;
|
|
18
|
+
/** Reconnect bounds (ms). Defaults: 1s..30s, doubling, +0..500ms jitter. */
|
|
19
|
+
backoff?: { minMs?: number; maxMs?: number };
|
|
20
|
+
/** Passed to the underlying WebSocket (e.g. `rejectUnauthorized` for dev certs). */
|
|
21
|
+
wsOptions?: Record<string, unknown>;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export class HerdGateAgent {
|
|
25
|
+
readonly #o: AgentOptions;
|
|
26
|
+
readonly #log: (line: string) => void;
|
|
27
|
+
#ws: WebSocket | null = null;
|
|
28
|
+
#stop = false;
|
|
29
|
+
#attempt = 0;
|
|
30
|
+
#devices: DeviceView[] = [];
|
|
31
|
+
#firstHello!: () => void;
|
|
32
|
+
/** Resolves after the cloud's first `hello`; rejects on stop before that. */
|
|
33
|
+
readonly firstHello: Promise<void>;
|
|
34
|
+
|
|
35
|
+
constructor(o: AgentOptions) {
|
|
36
|
+
this.#o = o;
|
|
37
|
+
this.#log = o.log ?? (() => {});
|
|
38
|
+
this.firstHello = new Promise((res, rej) => {
|
|
39
|
+
this.#firstHello = res;
|
|
40
|
+
o.adapter.info; // touch: adapter is required at runtime by callers
|
|
41
|
+
this.#stopPromiseCatch = rej;
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
#stopPromiseCatch: (e: Error) => void = () => {};
|
|
45
|
+
|
|
46
|
+
start(): void {
|
|
47
|
+
this.#stop = false;
|
|
48
|
+
this.#connect();
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
stop(): void {
|
|
52
|
+
this.#stop = true;
|
|
53
|
+
this.#stopPromiseCatch(new Error("agent stopped"));
|
|
54
|
+
this.#ws?.close(1000, "stopped");
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Opaque payload to one device. */
|
|
58
|
+
send(device: string, payload: unknown): void {
|
|
59
|
+
this.#send({ t: "frame", device, payload } satisfies AgentToCloud);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Ask the cloud to push-wake a device that is not connected (silent, no payload). */
|
|
63
|
+
wake(device: string): void {
|
|
64
|
+
this.#send({ t: "wake", device } satisfies AgentToCloud);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
presence(online: boolean, detail?: string): void {
|
|
68
|
+
this.#send({ t: "presence", online, detail } satisfies AgentToCloud);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Answer a `pair.request`. */
|
|
72
|
+
respond(requestId: string, ok: boolean): void {
|
|
73
|
+
this.#send({ t: "pair.response", requestId, ok } satisfies AgentToCloud);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
get devices(): readonly DeviceView[] {
|
|
77
|
+
return this.#devices;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
scopeOf(device: string): "read" | "act" | null {
|
|
81
|
+
return this.#devices.find((d) => d.id === device)?.scope ?? null;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
#send(msg: AgentToCloud): void {
|
|
85
|
+
if (this.#ws?.readyState === WebSocket.OPEN) this.#ws.send(encode(msg as unknown as Record<string, unknown>));
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
#connect(): void {
|
|
89
|
+
if (this.#stop) return;
|
|
90
|
+
const ws = new WebSocket(this.#o.endpoint, { maxPayload: 256 * 1024, ...this.#o.wsOptions });
|
|
91
|
+
this.#ws = ws;
|
|
92
|
+
let helloed = false;
|
|
93
|
+
|
|
94
|
+
ws.on("open", () => {
|
|
95
|
+
const info = this.#o.adapter.info();
|
|
96
|
+
ws.send(encode({ t: "hello", roomToken: this.#o.roomToken, info }));
|
|
97
|
+
});
|
|
98
|
+
ws.on("message", (data) => {
|
|
99
|
+
let m: CloudToAgent;
|
|
100
|
+
try {
|
|
101
|
+
m = JSON.parse(String(data)) as CloudToAgent;
|
|
102
|
+
} catch {
|
|
103
|
+
return;
|
|
104
|
+
}
|
|
105
|
+
if (!helloed && m.t === "hello") {
|
|
106
|
+
helloed = true;
|
|
107
|
+
this.#attempt = 0;
|
|
108
|
+
this.#devices = m.devices ?? [];
|
|
109
|
+
this.#log(`cloud hello: room ${m.roomId} (${m.roomName}), ${this.#devices.length} device(s)`);
|
|
110
|
+
this.#o.adapter.onDevices(this.#devices);
|
|
111
|
+
this.#firstHello();
|
|
112
|
+
return;
|
|
113
|
+
}
|
|
114
|
+
switch (m.t) {
|
|
115
|
+
case "room.update":
|
|
116
|
+
this.#devices = m.devices ?? [];
|
|
117
|
+
this.#o.adapter.onDevices(this.#devices);
|
|
118
|
+
return;
|
|
119
|
+
case "frame":
|
|
120
|
+
void this.#o.adapter.onFrame(m.device, m.payload);
|
|
121
|
+
return;
|
|
122
|
+
case "pair.request": {
|
|
123
|
+
const ask: PairAsk = { requestId: m.requestId, device: m.device, scope: m.scope };
|
|
124
|
+
void Promise.resolve(this.#o.adapter.onPairAsk(ask)).then((ok) => this.respond(ask.requestId, ok));
|
|
125
|
+
return;
|
|
126
|
+
}
|
|
127
|
+
default:
|
|
128
|
+
return;
|
|
129
|
+
}
|
|
130
|
+
});
|
|
131
|
+
ws.on("error", (e) => this.#log(`ws error: ${e.message}`));
|
|
132
|
+
ws.on("close", () => {
|
|
133
|
+
if (this.#stop) return;
|
|
134
|
+
const min = this.#o.backoff?.minMs ?? 1_000;
|
|
135
|
+
const max = this.#o.backoff?.maxMs ?? 30_000;
|
|
136
|
+
const wait = Math.min(max, min * 2 ** this.#attempt) + Math.random() * 500;
|
|
137
|
+
this.#attempt += 1;
|
|
138
|
+
this.#log(`disconnected; retry in ${Math.round(wait)}ms`);
|
|
139
|
+
setTimeout(() => this.#connect(), wait);
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
// App-level keepalive (unref: a timer alone must not hold the process).
|
|
143
|
+
const iv = setInterval(() => {
|
|
144
|
+
if (ws.readyState === WebSocket.OPEN) this.#send({ t: "ping", n: Date.now() } as unknown as AgentToCloud);
|
|
145
|
+
else clearInterval(iv);
|
|
146
|
+
}, 25_000);
|
|
147
|
+
iv.unref?.();
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Host provisioning (device flow): mint a code, surface it to the human, poll
|
|
153
|
+
* until an account approves it, return the room token. Store that token — it is
|
|
154
|
+
* the host's long-lived credential (revoke = re-provision).
|
|
155
|
+
*/
|
|
156
|
+
export async function provision(o: {
|
|
157
|
+
baseUrl: string; // http(s)://host[:port]
|
|
158
|
+
name: string;
|
|
159
|
+
onCode?: (url: string | { code: string }) => void;
|
|
160
|
+
pollMs?: number;
|
|
161
|
+
timeoutMs?: number;
|
|
162
|
+
}): Promise<{ roomToken: string; roomId: string }> {
|
|
163
|
+
const res = await fetch(`${o.baseUrl.replace(/\/$/, "")}/v1/agent/code`, {
|
|
164
|
+
method: "POST",
|
|
165
|
+
headers: { "content-type": "application/json" },
|
|
166
|
+
body: JSON.stringify({ name: o.name }),
|
|
167
|
+
});
|
|
168
|
+
if (!res.ok) throw new Error(`agent/code: ${res.status}`);
|
|
169
|
+
const minted = (await res.json()) as { code: string; url: string };
|
|
170
|
+
(o.onCode ?? ((u) => console.log(`pair this host: ${u}`)))(minted.url);
|
|
171
|
+
const deadline = Date.now() + (o.timeoutMs ?? 11 * 60_000);
|
|
172
|
+
while (Date.now() < deadline) {
|
|
173
|
+
await new Promise((r) => setTimeout(r, o.pollMs ?? 3_000));
|
|
174
|
+
const st = (await (await fetch(`${o.baseUrl.replace(/\/$/, "")}/v1/agent/code/${minted.code}/status`)).json()) as {
|
|
175
|
+
status: string;
|
|
176
|
+
roomToken?: string;
|
|
177
|
+
roomId?: string;
|
|
178
|
+
};
|
|
179
|
+
if (st.status === "approved" && st.roomToken) return { roomToken: st.roomToken, roomId: st.roomId! };
|
|
180
|
+
if (st.status === "unknown") throw new Error("pairing code expired or unknown");
|
|
181
|
+
}
|
|
182
|
+
throw new Error("pairing timed out");
|
|
183
|
+
}
|