@bom0792/herdgate 0.9.40 → 0.9.41

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bom0792/herdgate",
3
- "version": "0.9.40",
3
+ "version": "0.9.41",
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": {
@@ -58,10 +58,15 @@ export function scrubEnv() {
58
58
 
59
59
  /** Args must be short printable words: refs, hashes, paths, allowed flags. */
60
60
  const ARG_RE = /^[A-Za-z0-9._/::~^-]{1,128}$/;
61
- /** Flags a read may carry. Anything else option-looking is refused. */
62
- const ALLOWED_FLAGS = new Set(["-C", "--no-color", "--stat", "--patch", "--no-ext-diff", "--no-textconv"]);
61
+ /** Flags a read may carry. Anything else option-looking is refused.
62
+ * `--porcelain` is `status`'s machine-readable mode — read-only output shaping,
63
+ * the same trust class as `--stat`; `--` is the path separator (`ls-files -- <path>`). */
64
+ const ALLOWED_FLAGS = new Set(["-C", "--no-color", "--stat", "--patch", "--numstat", "--no-ext-diff", "--no-textconv", "--porcelain", "--verify", "--"]);
63
65
  /** Subcommands that produce diffs — the only ones that take --no-ext-diff/--no-textconv. */
64
66
  const DIFF_COMMANDS = new Set(["diff", "show", "log", "whatchanged", "format-patch", "range-diff"]);
67
+ /** Read-only subcommands gitRead will run at all. Anything else is refused before
68
+ * argv is even built — the allowlist is the whole attack surface for this seam. */
69
+ const ALLOWED_COMMANDS = new Set(["show", "log", "diff", "ls-files", "status", "rev-parse", "config"]);
65
70
 
66
71
  function refuse(code, message) {
67
72
  const err = new Error(message);
@@ -113,6 +118,20 @@ function buildArgv(args) {
113
118
  */
114
119
  export async function gitRead(args, cwd = diffRepoDir(), timeoutMs = 10_000, maxBuffer = 8 * 1024 * 1024) {
115
120
  validateArgs(args);
121
+ // The subcommand itself must be on the read allowlist — flags alone were never
122
+ // the whole surface (`config`, `clone`, … are all flagless). The command is the
123
+ // first arg that is not an option, skipping any leading `-C <dir>` pair.
124
+ let i = 0;
125
+ while (i < args.length && args[i].startsWith("-")) i += args[i] === "-C" ? 2 : 1;
126
+ const command = args[i] ?? "";
127
+ if (!ALLOWED_COMMANDS.has(command)) {
128
+ throw refuse("GIT_SAFE_ARG", `gitRead refuses command ${JSON.stringify(command)}: not a read command`);
129
+ }
130
+ // `config` is readable but writable too (`git config key value` has no flag!) —
131
+ // admit ONLY the two-arg read form, never a value or --add/--global.
132
+ if (command === "config" && args.length !== i + 2) {
133
+ throw refuse("GIT_SAFE_ARG", "gitRead refuses config: only the two-arg read form `config <name>`");
134
+ }
116
135
  const allowed = new Set([PLUGIN_DIR]);
117
136
  if (process.env.HERDGATE_DIFF_REPO_DIR) allowed.add(resolve(process.env.HERDGATE_DIFF_REPO_DIR));
118
137
  const startDir = resolve(cwd);
@@ -9,7 +9,7 @@
9
9
  import { execFile as execFileCb, spawn } from "node:child_process";
10
10
  import { randomUUID } from "node:crypto";
11
11
  import { promisify } from "node:util";
12
- import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
12
+ import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, statSync, realpathSync } from "node:fs";
13
13
  import { join, dirname } from "node:path";
14
14
  import { hostname, homedir } from "node:os";
15
15
  import { fileURLToPath } from "node:url";
@@ -33,6 +33,10 @@ const D = dirs();
33
33
  const execFile = promisify(execFileCb);
34
34
  /** diff.get ships at most 128 KiB of `git show` output, marked truncated beyond. */
35
35
  const MAX_DIFF_BYTES = 128 * 1024;
36
+ const MAX_FILE_ENTRIES = 5000; // file.tree cap — the fuzzy finder ranks within this
37
+ const MAX_FILE_BYTES = 128 * 1024; // file.read cap — same class as diffs, and well under the gate's 256KiB frame limit
38
+ const MAX_REVIEW_FILES = 5000; // review.files entries cap (one screen's worth of scrolling)
39
+ const MAX_REVIEW_COMMENTS = 50; // review.send comments per batch — a review, not a prompt
36
40
  const NAME = process.env.HERDGATE_HOST_NAME || hostname();
37
41
  const log = (line) => console.error(`herdgate: ${line}`);
38
42
  /** The panel's settings file (app home herdgate dir) — the owner's switches live
@@ -439,7 +443,29 @@ async function publisherLoop() {
439
443
  }
440
444
  if (replayed) log(`receipts: replayed ${replayed} unacknowledged push(es) to ${device}`);
441
445
  };
446
+ /** Settle-anchored git heads — the `turn` review scope without a ref write
447
+ * (reviewr keeps its baseline in refs/reviewr/*; herdgate journals settle
448
+ * heads BESIDE the repo instead). Receipts carry no hashes, so this journal
449
+ * is the honest baseline: every settle records HEAD; `turn` diffs the two
450
+ * newest anchors = exactly the last settled agent turn. */
451
+ const gitAnchorsFile = () => (D.statePath ? join(D.statePath, "..", "git-anchors.json") : "");
452
+ const recordGitAnchor = async (reason) => {
453
+ const file = gitAnchorsFile();
454
+ if (!file) return;
455
+ try {
456
+ const { stdout } = await gitRead(["rev-parse", "HEAD"], diffRepoDir(), 5_000);
457
+ const head = String(stdout).trim();
458
+ if (!/^[0-9a-f]{7,40}$/.test(head)) return;
459
+ const prior = readState(file);
460
+ const anchors = Array.isArray(prior.anchors) ? prior.anchors : [];
461
+ if (anchors[anchors.length - 1]?.head === head) return; // no new commits since
462
+ anchors.push({ head, at: Date.now(), reason });
463
+ writeState(file, { v: 1, anchors: anchors.slice(-8) });
464
+ log(`review: anchor ${head.slice(0, 8)} (${reason})`);
465
+ } catch { /* not a repo — `turn` will say so honestly */ }
466
+ };
442
467
  const pushReceipt = (entry) => {
468
+ void recordGitAnchor("settle"); // journal the turn boundary first — subscriber fan-out is separate
443
469
  const store = watches();
444
470
  if (!store) return;
445
471
  store.sweep();
@@ -453,21 +479,22 @@ async function publisherLoop() {
453
479
  const known = devices.find(d => d.id === sub.device);
454
480
  if (known && known.connected !== false) continue;
455
481
  log(`receipts: wake ${sub.device} (settle while offline)`);
456
- wakeAway(true);
482
+ wakeAway(true, { kind: "settle", agent: entry.title ?? undefined });
457
483
  }
458
484
  };
459
485
 
460
486
  /** Wake phones that are away when something actually changed (throttled per device). */
461
487
  const lastWake = new Map(); // deviceId → epoch ms
462
- const wakeAway = (changed) => {
488
+ const wakeAway = (changed, note = { kind: "activity" }) => {
463
489
  if (!changed) return;
490
+ if (note?.kind === "settle") void recordGitAnchor("settle"); // event-hook settles journal too
464
491
  const now = Date.now();
465
492
  for (const d of devices) {
466
493
  if (d.connected !== false) continue;
467
494
  const at = lastWake.get(d.id) ?? 0;
468
495
  if (now - at < 5 * 60_000) continue;
469
496
  lastWake.set(d.id, now);
470
- if (wsRef && wsRef.readyState === 1) wsRef.send(JSON.stringify({ v: 1, t: "wake", device: d.id }));
497
+ if (wsRef && wsRef.readyState === 1) wsRef.send(JSON.stringify({ v: 1, t: "wake", device: d.id, note }));
471
498
  }
472
499
  };
473
500
 
@@ -523,6 +550,7 @@ async function publisherLoop() {
523
550
  if (timer) clearInterval(timer);
524
551
  timer = setInterval(() => void publish(ws), PUBLISH_MS);
525
552
  timer.unref?.();
553
+ void recordGitAnchor("boot"); // seed the first boundary so turn 1 is diffable
526
554
  return;
527
555
  }
528
556
  if (m.t === "room.update") {
@@ -905,6 +933,217 @@ async function publisherLoop() {
905
933
  : stderr.split("\n")[0] || err.message });
906
934
  }
907
935
  }
936
+ if (op === "file.tree") {
937
+ // READ-ONLY file index (filev pattern): tracked files from `git ls-files`
938
+ // (already .gitignore-aware) with `git status --porcelain` markers overlaid.
939
+ // Same hardened gitRead as diff.get — no payload-chosen cwd, scrubbed env.
940
+ // Untracked files are invisible by design: only what git tracks can be read.
941
+ const repoDir = diffRepoDir();
942
+ try {
943
+ const [files, status] = await Promise.all([
944
+ gitRead(["ls-files"], repoDir, 10_000),
945
+ gitRead(["status", "--porcelain"], repoDir, 10_000),
946
+ ]);
947
+ // XY status + path; rename lines take the "-> " target. Quoted paths
948
+ // (git quotes specials) are unquoted minimally — markers are advisory.
949
+ const markers = new Map();
950
+ for (const line of String(status.stdout).split("\n")) {
951
+ const m = /^([ MARDRCU?!]{1,2})\s+(.+)$/.exec(line);
952
+ if (!m || !m[1].trim()) continue; // "??" and blank lead chars alike
953
+ let target = m[2].split(" -> ").pop() ?? m[2];
954
+ if (target.startsWith('"') && target.endsWith('"')) target = target.slice(1, -1);
955
+ markers.set(target, m[1].trim());
956
+ }
957
+ const all = String(files.stdout).split("\n").filter(Boolean);
958
+ const capped = all.length > MAX_FILE_ENTRIES;
959
+ const entries = (capped ? all.slice(0, MAX_FILE_ENTRIES) : all)
960
+ .map((path) => ({ path, status: markers.get(path) ?? null }))
961
+ .sort((a, b) => a.path.localeCompare(b.path));
962
+ return void replyTo({ op: "file.tree.result", files: entries, capped, total: all.length });
963
+ } catch (e) {
964
+ const err = e instanceof Error ? e : new Error(String(e));
965
+ const stderr = String(e?.stderr ?? "");
966
+ const noRepo = /not a git repository/i.test(`${err.message}\n${stderr}`);
967
+ log(`files: ${m.device} tree refused: ${err.message}`);
968
+ return void replyTo({ op: "error", code: noRepo ? "diff.repo" : "files.tree",
969
+ message: noRepo ? "the plugin directory is not a git repository"
970
+ : stderr.split("\n")[0] || err.message });
971
+ }
972
+ }
973
+ if (op === "file.read") {
974
+ // READ-ONE-FILE with filev's hardening rules: git-tracked paths only (the
975
+ // tree above is the whitelist), no leading /, no .., no NUL, ≤ 255 chars,
976
+ // realpath must stay under the repo (a symlink planted inside must not
977
+ // read outside), size capped — and the bytes go back as text, nothing else.
978
+ const path = typeof payload.path === "string" ? payload.path : "";
979
+ if (!/^[^/\0][^\0]{0,254}$/.test(path) || path.split("/").includes("..")) {
980
+ return void replyTo({ op: "error", code: "bad-path", message: "file.read needs a root-relative path without .." });
981
+ }
982
+ const repoDir = diffRepoDir();
983
+ try {
984
+ const repoReal = realpathSync(repoDir);
985
+ const full = join(repoDir, path);
986
+ let st;
987
+ try { st = statSync(full); } catch { st = null; }
988
+ if (!st || !st.isFile()) {
989
+ return void replyTo({ op: "error", code: "no-file", message: "no such file in the repo" });
990
+ }
991
+ if (!realpathSync(full).startsWith(repoReal + "/")) {
992
+ return void replyTo({ op: "error", code: "bad-path", message: "path escapes the repo" });
993
+ }
994
+ const tracked = await gitRead(["ls-files", "--", path], repoDir, 10_000);
995
+ if (!String(tracked.stdout).trim()) {
996
+ return void replyTo({ op: "error", code: "no-file", message: "not a tracked file" });
997
+ }
998
+ const truncated = st.size > MAX_FILE_BYTES;
999
+ const buf = readFileSync(full);
1000
+ let text = truncated ? buf.subarray(0, MAX_FILE_BYTES).toString("utf8") : buf.toString("utf8");
1001
+ // JSON escaping can inflate a hostile file several-fold (\u0000 = 6x);
1002
+ // shrink until the ENVELOPE fits the gate's 256KiB frame cap — a reply
1003
+ // that kills the publisher's own socket is worse than a shorter view.
1004
+ while (Buffer.byteLength(JSON.stringify({ t: "frame", payload: { op: "file.read.result", path, text } })) > 240 * 1024 && text.length > 0) {
1005
+ text = text.slice(0, Math.floor(text.length * 0.8));
1006
+ }
1007
+ const lines = text.length ? text.split("\n").length : 0;
1008
+ return void replyTo({ op: "file.read.result", path, text, lines, bytes: st.size, truncated: truncated || Buffer.byteLength(text) < Math.min(st.size, MAX_FILE_BYTES) });
1009
+ } catch (e) {
1010
+ const err = e instanceof Error ? e : new Error(String(e));
1011
+ log(`files: ${m.device} read ${path} refused: ${err.message}`);
1012
+ return void replyTo({ op: "error", code: "files.read", message: err.message });
1013
+ }
1014
+ }
1015
+ if (op === "review.files" || op === "review.diff") {
1016
+ // READ-ONLY review scopes — the reviewr pattern, mobile: `uncommitted`,
1017
+ // `branch` (three-dot vs upstream/main — merge-base for free), `turn`
1018
+ // (diff of the last settled agent turn, anchored by the git-anchors
1019
+ // journal — no ref writes). All git flows through the hardened gitRead.
1020
+ const scope = typeof payload.scope === "string" ? payload.scope : "";
1021
+ if (!["uncommitted", "branch", "turn"].includes(scope)) {
1022
+ return void replyTo({ op: "error", code: "bad-scope", message: "review.* needs scope uncommitted | branch | turn" });
1023
+ }
1024
+ const repoDir = diffRepoDir();
1025
+ try {
1026
+ let range;
1027
+ let base = null;
1028
+ if (scope === "uncommitted") {
1029
+ range = ["HEAD"];
1030
+ } else if (scope === "branch") {
1031
+ // Candidates avoid ref-expression braces (@{upstream}, ^{commit}) —
1032
+ // gitRead's arg grammar keeps them out, so plain names only.
1033
+ for (const cand of ["origin/main", "origin/master", "main", "master"]) {
1034
+ try {
1035
+ const { stdout } = await gitRead(["rev-parse", "--verify", cand], repoDir, 5_000);
1036
+ const sha = String(stdout).trim();
1037
+ if (/^[0-9a-f]{7,40}$/.test(sha)) { base = sha; break; }
1038
+ } catch { /* try the next candidate */ }
1039
+ }
1040
+ if (!base) {
1041
+ return void replyTo({ op: "error", code: "no-base", message: "không thấy upstream/main — không định vị được scope branch" });
1042
+ }
1043
+ range = [`${base}...HEAD`];
1044
+ } else {
1045
+ const anchors = readState(gitAnchorsFile()).anchors;
1046
+ if (!Array.isArray(anchors) || anchors.length < 2) {
1047
+ return void replyTo({ op: "error", code: "no-anchor", message: "chưa đủ 2 mốc settle — chờ agent settle thêm một lượt để có diff lượt cuối" });
1048
+ }
1049
+ const from = anchors[anchors.length - 2].head;
1050
+ const to = anchors[anchors.length - 1].head;
1051
+ range = [`${from}..${to}`];
1052
+ base = from;
1053
+ }
1054
+ if (op === "review.files") {
1055
+ const numstat = await gitRead(["diff", "--no-color", "--numstat", ...range], repoDir, 10_000);
1056
+ const files = [];
1057
+ for (const line of String(numstat.stdout).split("\n")) {
1058
+ const nm = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line);
1059
+ if (!nm) continue;
1060
+ let path = nm[3].split(" -> ").pop() ?? nm[3];
1061
+ if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
1062
+ files.push({ path, plus: nm[1] === "-" ? null : Number(nm[1]), minus: nm[2] === "-" ? null : Number(nm[2]) });
1063
+ }
1064
+ let untracked = 0;
1065
+ if (scope === "uncommitted") {
1066
+ // `git diff` never sees untracked files; the porcelain overlay adds
1067
+ // them as zero-stat rows so the review list matches reality.
1068
+ const status = await gitRead(["status", "--porcelain"], repoDir, 10_000);
1069
+ for (const line of String(status.stdout).split("\n")) {
1070
+ const sm = /^\?\?\s+(.+)$/.exec(line);
1071
+ if (!sm) continue;
1072
+ let path = sm[1].split(" -> ").pop() ?? sm[1];
1073
+ if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
1074
+ if (files.some((f) => f.path === path)) continue;
1075
+ files.push({ path, plus: null, minus: null, status: "??" });
1076
+ untracked++;
1077
+ }
1078
+ }
1079
+ files.sort((a, b) => a.path.localeCompare(b.path));
1080
+ const capped = files.length > MAX_REVIEW_FILES;
1081
+ log(`review: ${m.device} files ${scope}${base ? ` @${String(base).slice(0, 8)}` : ""} -> ${files.length} file${untracked ? ` (${untracked} chưa track)` : ""}`);
1082
+ return void replyTo({ op: "review.files.result", scope, base, files: capped ? files.slice(0, MAX_REVIEW_FILES) : files, capped });
1083
+ }
1084
+ const path = typeof payload.path === "string" ? payload.path : "";
1085
+ if (!/^[^/\0][^\0]{0,254}$/.test(path) || path.split("/").includes("..")) {
1086
+ return void replyTo({ op: "error", code: "bad-path", message: "review.diff needs a root-relative path without .." });
1087
+ }
1088
+ const { stdout } = await gitRead(["diff", "--no-color", "--patch", ...range, "--", path], repoDir, 10_000);
1089
+ const bytes = Buffer.byteLength(stdout, "utf8");
1090
+ const truncated = bytes > MAX_DIFF_BYTES;
1091
+ const text = truncated ? Buffer.from(stdout, "utf8").subarray(0, MAX_DIFF_BYTES).toString("utf8") : stdout;
1092
+ log(`review: ${m.device} diff ${scope} ${path} -> ${bytes}B${truncated ? " (capped at 128KiB)" : ""}`);
1093
+ return void replyTo({ op: "review.diff.result", scope, path, base, text, bytes, truncated });
1094
+ } catch (e) {
1095
+ const err = e instanceof Error ? e : new Error(String(e));
1096
+ const stderr = String(e?.stderr ?? "");
1097
+ const noRepo = /not a git repository/i.test(`${err.message}\n${stderr}`);
1098
+ log(`review: ${m.device} ${op} ${scope} refused: ${err.message}`);
1099
+ return void replyTo({ op: "error", code: noRepo ? "diff.repo" : "review",
1100
+ message: noRepo ? "the plugin directory is not a git repository" : stderr.split("\n")[0] || err.message });
1101
+ }
1102
+ }
1103
+ if (op === "review.send") {
1104
+ // ACT — ship the phone's line comments to the agent. The Pi worker queue
1105
+ // is the one delivery leg that already exists (receipts, wake-on-settle);
1106
+ // the comments ride as a <file-comments> block the agent reads structurally.
1107
+ if (process.env.HERDGATE_PI_WORKER !== "1") {
1108
+ return void replyTo({ op: "error", code: "pi_worker_disabled", message: "host chưa bật Pi worker — review.send cần HERDGATE_PI_WORKER=1" });
1109
+ }
1110
+ if (devices.find((d) => d.id === m.device)?.scope !== "act") {
1111
+ return void replyTo({ op: "error", code: "requires-act", message: "review.send needs an act device" });
1112
+ }
1113
+ const comments = Array.isArray(payload.comments) ? payload.comments : [];
1114
+ if (!comments.length || comments.length > MAX_REVIEW_COMMENTS) {
1115
+ return void replyTo({ op: "error", code: "bad-comments", message: `review.send needs 1..${MAX_REVIEW_COMMENTS} comments` });
1116
+ }
1117
+ for (const c of comments) {
1118
+ const okPath = typeof c?.path === "string" && /^[^/\0][^\0]{0,254}$/.test(c.path) && !c.path.split("/").includes("..");
1119
+ const okLine = Number.isInteger(c?.line) && c.line >= 1 && c.line <= 1e6;
1120
+ const okEnd = c?.endLine === undefined || (Number.isInteger(c.endLine) && c.endLine >= c.line && c.endLine <= 1e6);
1121
+ const okText = typeof c?.text === "string" && c.text.trim().length > 0 && c.text.length <= 500;
1122
+ if (!okPath || !okLine || !okEnd || !okText) {
1123
+ return void replyTo({ op: "error", code: "bad-comment", message: "comment needs { path, line 1..1e6, endLine?, text 1..500 }" });
1124
+ }
1125
+ }
1126
+ const body = comments.map((c) => `${c.path}:${c.line}${c.endLine ? `-${c.endLine}` : ""} — ${c.text}`).join("\n");
1127
+ const prompt = `Xử lý review comments trên diff từ mobile:\n\n<file-comments>\n${body}\n</file-comments>\n\nTừng comment: xem chỗ chỉ dẫn, sửa nếu đúng, chạy test liên quan, commit nếu đạt. Báo lại ngắn gọn từng dòng đã xử lý thế nào.`;
1128
+ const file = jobsFile(workerBase());
1129
+ let jobs;
1130
+ try { jobs = readJobs(file); }
1131
+ catch (e) {
1132
+ return void replyTo({ op: "error", code: "worker-queue", message: `queue unreadable: ${e instanceof Error ? e.message : String(e)}` });
1133
+ }
1134
+ const pending = [...jobs.values()].filter((j) => j.state === "queued" || j.state === "running").length;
1135
+ if (pending >= MAX_PENDING) {
1136
+ return void replyTo({ op: "error", code: "queue-full", message: `worker queue is full (${MAX_PENDING} pending)` });
1137
+ }
1138
+ const jobId = randomUUID();
1139
+ try {
1140
+ appendJob(file, { v: 1, id: jobId, prompt, ts: Date.now(), state: "queued", principal: `device:${m.device}`, kind: "review" });
1141
+ } catch (e) {
1142
+ return void replyTo({ op: "error", code: "worker-queue", message: `queue append failed: ${e instanceof Error ? e.message : String(e)}` });
1143
+ }
1144
+ log(`review: ${m.device} sent ${comments.length} comment(s) as job ${jobId}`);
1145
+ return void replyTo({ op: "review.sent", id: jobId, state: "queued", count: comments.length });
1146
+ }
908
1147
  if (op === "pane.focus") {
909
1148
  // Focus a pane on the host's Herdr. Fire-and-forget spawn, never awaited:
910
1149
  // a phone must not hang on a TUI command. argv comes from the --help probe.
@@ -21,7 +21,7 @@ CLOUD="$STAGE/$NAME"
21
21
  mkdir -p "$CLOUD/runtime/web/icons" "$CLOUD/scripts"
22
22
 
23
23
  npm run build:cloud -- --outDir "$CLOUD/runtime"
24
- cp src/web/{index.html,app.js,app.css,app.webmanifest,sw.js,e2e.js} "$CLOUD/runtime/web/"
24
+ cp src/web/{index.html,app.js,app.css,app.webmanifest,sw.js,e2e.js,push-decision.js} "$CLOUD/runtime/web/"
25
25
  cp src/web/icons/{icon.svg,icon-192.png,icon-512.png} "$CLOUD/runtime/web/icons/"
26
26
  cp templates/cloud/{Dockerfile,compose.yml,compose.env.example,.dockerignore,herdgate-cloud.service,herdgate-cloud-edge.service,Caddyfile.example,README.md} "$CLOUD/"
27
27
  cp templates/cloud/gitignore.example "$CLOUD/.gitignore"
@@ -38,8 +38,27 @@ import { type Account, type DeviceRecord, type RoomRecord, State } from "./store
38
38
  import { pruneBudget, readJsonBody, randomId, sameSecret, sha256Hex } from "./util.ts";
39
39
  import { serveStatic } from "./static.ts";
40
40
  import { startSshd, type SshHandle, type SshConfig } from "./sshd.ts";
41
- import { pushEndpoint, sendWake } from "./push.ts";
41
+ import { pushEndpoint, sendPush, encryptPayload, canPayload, type PushKeys } from "./push.ts";
42
42
  import { type VapidKeys } from "./vapid.ts";
43
+ import { readFileSync } from "node:fs";
44
+ import { dirname, join } from "node:path";
45
+ import { fileURLToPath } from "node:url";
46
+
47
+ /** The gate's own build id (npm package version) — served on /healthz so a PWA can
48
+ * detect that the bundle it is running is older than the gate and offer a reload. */
49
+ const BUILD_ID: string = (() => {
50
+ try {
51
+ return String(JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8")).version ?? "");
52
+ } catch {
53
+ return "";
54
+ }
55
+ })();
56
+
57
+ /** What changed on the host, for the encrypted push payload (Vietnamese copy is PWA-side). */
58
+ export interface WakeNote {
59
+ kind: "settle" | "died" | "needs-you" | "activity";
60
+ agent?: string;
61
+ }
43
62
 
44
63
  export interface CloudConfig {
45
64
  accounts: { id: string; name: string; token: string }[];
@@ -178,13 +197,27 @@ export function startCloud(cfg: CloudConfig): Promise<Cloud> {
178
197
  return s;
179
198
  };
180
199
  const pendingWakes = new Set<string>();
181
- const wakeDevice = (deviceId: string): void => {
200
+ /** Push a wake to an away device. `note` (from the host) upgrades the ping to an
201
+ * encrypted payload when the subscription captured its p256dh/auth keys — the
202
+ * provider still sees only ciphertext; keyless subscriptions keep the silent ping. */
203
+ const wakeDevice = (deviceId: string, note?: WakeNote): void => {
182
204
  const push = cfg.push;
183
- const endpoint = pushEndpoint(state.deviceById(deviceId)?.push?.endpoint ?? "");
205
+ const rec = state.deviceById(deviceId);
206
+ const endpoint = pushEndpoint(rec?.push?.endpoint ?? "");
184
207
  if (!push || !endpoint || pendingWakes.has(deviceId) || pendingWakes.size >= 8) return;
185
208
  pendingWakes.add(deviceId);
186
- void sendWake(endpoint, push.keys, push.sub).catch(() => log("push: wake failed"))
187
- .finally(() => pendingWakes.delete(deviceId));
209
+ const send = async (): Promise<void> => {
210
+ const keys = rec?.push;
211
+ if (note && keys && canPayload(keys)) {
212
+ const payload = Buffer.from(JSON.stringify({
213
+ v: 1, kind: note.kind, room: rec!.roomId, ...(note.agent ? { agent: note.agent } : {}),
214
+ }), "utf8");
215
+ const body = encryptPayload(payload, keys.p256dh!, keys.auth!);
216
+ return sendPush(endpoint, push.keys, push.sub, body, note.kind === "needs-you" || note.kind === "died" ? "high" : "normal");
217
+ }
218
+ return sendPush(endpoint, push.keys, push.sub, null, "normal");
219
+ };
220
+ void send().catch(() => log("push: wake failed")).finally(() => pendingWakes.delete(deviceId));
188
221
  };
189
222
 
190
223
  const streamEmit = (roomId: string, msg: Record<string, unknown>, device?: string): void => {
@@ -420,14 +453,26 @@ export function startCloud(cfg: CloudConfig): Promise<Cloud> {
420
453
  }
421
454
  case "wake": {
422
455
  // The host asks for a phone to be woken: deliver a silent push only if the
423
- // device is not connected right now (a connected one is already live).
456
+ // device is not connected right now (a connected one is already live). A
457
+ // `note` upgrades the ping to an encrypted payload (settle / died / needs-you)
458
+ // when the subscription carries its RFC 8291 keys.
424
459
  if (!cfg.push) return fail(ws, "no-push", "push is not configured");
425
460
  const deviceId = typeof m.device === "string" ? m.device : null;
426
461
  if (!deviceId) return fail(ws, "bad-message", "wake.device");
427
462
  const rec = state.deviceById(deviceId);
428
463
  if (!rec || rec.roomId !== room.id) return fail(ws, "no-such-device", "not one of this room's devices");
464
+ const rawNote = m.note;
465
+ let note: WakeNote | undefined;
466
+ if (rawNote && typeof rawNote === "object") {
467
+ const kind = (rawNote as { kind?: unknown }).kind;
468
+ const agent = (rawNote as { agent?: unknown }).agent;
469
+ if (kind !== "settle" && kind !== "died" && kind !== "needs-you" && kind !== "activity") {
470
+ return fail(ws, "bad-message", "wake.note.kind");
471
+ }
472
+ note = { kind, ...(typeof agent === "string" && agent.length <= 64 ? { agent: agent.slice(0, 64) } : {}) };
473
+ }
429
474
  if ([...deviceConns].some((c) => c.device?.id === deviceId)) return;
430
- wakeDevice(deviceId);
475
+ wakeDevice(deviceId, note);
431
476
  return;
432
477
  }
433
478
  case "ping":
@@ -816,7 +861,7 @@ export function startCloud(cfg: CloudConfig): Promise<Cloud> {
816
861
  const path = url.pathname;
817
862
 
818
863
  if (req.method === "GET" && path === "/healthz") {
819
- res.writeHead(200);
864
+ res.writeHead(200, BUILD_ID ? { "x-hg-build": BUILD_ID } : undefined);
820
865
  return res.end("ok");
821
866
  }
822
867
 
@@ -897,7 +942,15 @@ export function startCloud(cfg: CloudConfig): Promise<Cloud> {
897
942
  if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
898
943
  const validated = pushEndpoint(endpoint);
899
944
  if (!validated) return json(res, 400, { error: "unsupported push endpoint" });
900
- state.setDevicePush(device.id, validated.href);
945
+ // Optional RFC 8291 keys: validate the shapes once here, then store verbatim.
946
+ // A subscription without them keeps working as a silent wake ping.
947
+ const p256dh = typeof body?.p256dh === "string" ? body.p256dh : "";
948
+ const auth = typeof body?.auth === "string" ? body.auth : "";
949
+ if ((p256dh || auth) && !canPayload({ p256dh, auth })) {
950
+ return json(res, 400, { error: "bad push keys" });
951
+ }
952
+ const keys: PushKeys | undefined = p256dh && auth ? { p256dh, auth } : undefined;
953
+ state.setDevicePush(device.id, validated.href, keys);
901
954
  return json(res, 200, { ok: true });
902
955
  });
903
956
  }
@@ -917,7 +970,7 @@ export function startCloud(cfg: CloudConfig): Promise<Cloud> {
917
970
  return json(res, 200, {
918
971
  devices: state.devices
919
972
  .filter((d) => d.roomId === room.id)
920
- .map((d) => ({ id: d.id, name: d.name, scope: d.scope, connected: live.has(d.id), keys: (d.sshKeys ?? []).length, created: d.created })),
973
+ .map((d) => ({ id: d.id, name: d.name, scope: d.scope, connected: live.has(d.id), keys: (d.sshKeys ?? []).length, created: d.created, push: !!d.push, payload: canPayload(d.push) })),
921
974
  });
922
975
  }
923
976
  if (path === "/v1/device/revoke") {
package/src/cloud/push.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { lookup } from "node:dns/promises";
2
2
  import { request } from "node:https";
3
3
  import { BlockList, isIPv4 } from "node:net";
4
+ import { createCipheriv, createECDH, generateKeyPairSync, hkdfSync, randomBytes } from "node:crypto";
4
5
  import { vapidHeader, type VapidKeys } from "./vapid.ts";
5
6
 
6
7
  const providers = new Set(["fcm.googleapis.com", "updates.push.services.mozilla.com", "web.push.apple.com"]);
@@ -28,6 +29,93 @@ export function publicPushAddress(address: string): boolean {
28
29
  }
29
30
 
30
31
  export async function sendWake(endpoint: URL, keys: VapidKeys, sub: string): Promise<void> {
32
+ return sendPush(endpoint, keys, sub, null, "normal");
33
+ }
34
+
35
+ /** The user-agent half of a web-push subscription (RFC 8291 §2): the P-256 public
36
+ * point the browser generated (65-byte uncompressed, base64url) and the 16-byte
37
+ * auth secret. Both arrive via /v1/device/push alongside the endpoint. */
38
+ export interface PushKeys {
39
+ p256dh: string;
40
+ auth: string;
41
+ }
42
+
43
+ export interface EncryptSeams {
44
+ /** Fixed 16-byte salt and ephemeral keypair — test seams for deterministic vectors. */
45
+ salt?: Buffer;
46
+ asKeys?: { privateKey: Buffer; publicKey: Buffer };
47
+ }
48
+
49
+ /** Web-push payload encryption (RFC 8291) in the aes128gcm content coding (RFC 8188).
50
+ *
51
+ * body = salt(16) ‖ rs(4, BE, 4096) ‖ idlen(1, 65) ‖ asPublic(65) ‖ AES-128-GCM(plaintext ‖ 0x02 ‖ pad)
52
+ *
53
+ * The ephemeral server public key rides in the keyid field — that is how the agent
54
+ * derives the same IKM without any extra header (the aesgcm "dh=" header is dead).
55
+ * IKM = HKDF(salt=auth, ecdh(asPriv, uaPublic), info="WebPush: info"‖ua‖as, 32)
56
+ * CEK = HKDF(salt=rand, IKM, info="Content-Encoding: aes128gcm", 16)
57
+ * NONCE= HKDF(salt=rand, IKM, info="Content-Encoding: nonce", 12)
58
+ * Plaintext must fit one record: ≤ 4096 − 1 (delimiter) − 16 (GCM tag) − 65… the
59
+ * record size covers plaintext+delimiter+padding+tag, so payloads stay tiny by design. */
60
+ export function encryptPayload(
61
+ plaintext: Buffer,
62
+ uaPublicB64u: string,
63
+ authB64u: string,
64
+ seams: EncryptSeams = {},
65
+ ): Buffer {
66
+ const uaPublic = Buffer.from(uaPublicB64u, "base64url");
67
+ const auth = Buffer.from(authB64u, "base64url");
68
+ if (uaPublic.length !== 65 || uaPublic[0] !== 0x04) throw new Error("p256dh must be a 65-byte uncompressed point");
69
+ if (auth.length !== 16) throw new Error("auth secret must be 16 bytes");
70
+ if (plaintext.length === 0 || plaintext.length > 3000) throw new Error("payload must be 1..3000 bytes");
71
+
72
+ const as = seams.asKeys ?? (() => {
73
+ const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
74
+ const jwk = publicKey.export({ format: "jwk" }) as { x: string; y: string };
75
+ const d = privateKey.export({ format: "jwk" }) as { d: string };
76
+ return {
77
+ privateKey: Buffer.from(d.d, "base64url"),
78
+ publicKey: Buffer.concat([Buffer.from([0x04]), Buffer.from(jwk.x, "base64url"), Buffer.from(jwk.y, "base64url")]),
79
+ };
80
+ })();
81
+ const ecdh = createECDH("prime256v1");
82
+ ecdh.setPrivateKey(as.privateKey);
83
+ const secret = ecdh.computeSecret(uaPublic);
84
+
85
+ const salt = seams.salt ?? randomBytes(16);
86
+ const info = Buffer.concat([Buffer.from("WebPush: info"), uaPublic, as.publicKey]);
87
+ const ikm = Buffer.from(hkdfSync("sha256", secret, auth, info, 32));
88
+ const cek = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: aes128gcm"), 16));
89
+ const nonce = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: nonce"), 12));
90
+
91
+ // One record: plaintext ‖ 0x02 delimiter ‖ zero padding, then GCM over the whole thing.
92
+ const rs = 4096;
93
+ const padded = Buffer.concat([plaintext, Buffer.from([0x02]), Buffer.alloc(0)]);
94
+ if (padded.length + 16 > rs) throw new Error("payload does not fit one aes128gcm record");
95
+ const cipher = createCipheriv("aes-128-gcm", cek, nonce);
96
+ const ciphertext = Buffer.concat([cipher.update(padded), cipher.final(), cipher.getAuthTag()]);
97
+
98
+ const idLen = Buffer.from([as.publicKey.length]); // 65
99
+ const rsBuf = Buffer.alloc(4);
100
+ rsBuf.writeUInt32BE(rs);
101
+ return Buffer.concat([salt, rsBuf, idLen, as.publicKey, ciphertext]);
102
+ }
103
+
104
+ /** True when a stored subscription can receive payloads (keys captured at subscribe time). */
105
+ export function canPayload(k: { p256dh?: string; auth?: string } | undefined): boolean {
106
+ return typeof k?.p256dh === "string" && typeof k?.auth === "string" &&
107
+ Buffer.from(k.p256dh, "base64url").length === 65 && Buffer.from(k.auth, "base64url").length === 16;
108
+ }
109
+
110
+ /** POST to the push service: a silent ping (no body) or an encrypted payload.
111
+ * `urgent` (needs-you / died) maps to Urgency: high so the platform budgets battery. */
112
+ export async function sendPush(
113
+ endpoint: URL,
114
+ keys: VapidKeys,
115
+ sub: string,
116
+ body: Buffer | null,
117
+ urgency: "normal" | "high" = "normal",
118
+ ): Promise<void> {
31
119
  const { hostname, pathname, search, href } = endpoint;
32
120
  // Keep the DNS lookup part of the in-flight quota even if it is slow.
33
121
  const signal = AbortSignal.timeout(5000);
@@ -39,7 +127,14 @@ export async function sendWake(endpoint: URL, keys: VapidKeys, sub: string): Pro
39
127
  hostname: address, servername: hostname, path: pathname + search,
40
128
  method: "POST", agent: false, rejectUnauthorized: true, signal,
41
129
  headers: {
42
- Host: hostname, TTL: "60", Urgency: "normal", "content-length": "0",
130
+ Host: hostname, TTL: "60", Urgency: urgency,
131
+ ...(body
132
+ ? {
133
+ "Content-Encoding": "aes128gcm",
134
+ "Content-Type": "application/octet-stream",
135
+ "Content-Length": String(body.length),
136
+ }
137
+ : { "content-length": "0" }),
43
138
  Authorization: vapidHeader(href, keys, sub),
44
139
  },
45
140
  }, (res) => {
@@ -49,6 +144,6 @@ export async function sendWake(endpoint: URL, keys: VapidKeys, sub: string): Pro
49
144
  else reject(new Error("push provider rejected wake"));
50
145
  });
51
146
  req.once("error", reject);
52
- req.end();
147
+ req.end(body ?? undefined);
53
148
  });
54
149
  }
@@ -36,8 +36,10 @@ export interface DeviceRecord {
36
36
  created: string;
37
37
  /** sha256 of the device's own secret; the plaintext exists only at pair time. */
38
38
  secretHash?: string;
39
- /** The device's web-push subscription endpoint for silent wake pings (VAPID). */
40
- push?: { endpoint: string; at: string };
39
+ /** The device's web-push subscription: endpoint for silent wake pings (VAPID) plus
40
+ * the user-agent half for encrypted payloads (RFC 8291) — p256dh (65-byte point,
41
+ * base64url) and auth (16 bytes). Old subscriptions carry the endpoint only. */
42
+ push?: { endpoint: string; at: string; p256dh?: string; auth?: string };
41
43
  /** SSH public keys this device may log in with (authorized_keys lines, parsed). */
42
44
  sshKeys?: { algo: string; b64: string; comment?: string; at: string }[];
43
45
  }
@@ -117,11 +119,13 @@ export class State {
117
119
  return this.devices.find((d) => d.id === id) ?? null;
118
120
  }
119
121
 
120
- /** Remember (or forget, with a null endpoint) where to wake a device. */
121
- setDevicePush(id: string, endpoint: string | null): boolean {
122
+ /** Remember (or forget, with a null endpoint) where to wake a device. `keys` is
123
+ * the subscription's p256dh/auth pair (validated by the caller) — present only
124
+ * on subscriptions made by the current PWA; absent keeps the legacy silent ping. */
125
+ setDevicePush(id: string, endpoint: string | null, keys?: { p256dh: string; auth: string }): boolean {
122
126
  const d = this.deviceById(id);
123
127
  if (!d) return false;
124
- d.push = endpoint ? { endpoint, at: new Date().toISOString() } : undefined;
128
+ d.push = endpoint ? { endpoint, at: new Date().toISOString(), ...keys } : undefined;
125
129
  if (!endpoint) delete d.push;
126
130
  this.#save();
127
131
  return true;