@bom0792/herdgate 0.9.36 → 0.9.38

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.
@@ -83,3 +83,103 @@ Nếu có Python 3.11+ và file `herdr_pi.py` đi kèm **trong thư mục của
83
83
 
84
84
  Cấm: `agent prompt --wait`/`--timeout` để chờ nhiệm vụ (đó là chờ đồng bộ trên controller), vòng lặp `agent get`/`agent read`, `sleep`, polling pane. `agent start --timeout` chỉ chờ readiness khi khởi tạo agent — vẫn hợp lệ. `agent prompt` trả ok chứng nhận input đã xếp, không phải agent đã nhận việc hay hoàn thành. Khi báo cáo về: `replied` chứng minh có reply cuối đúng request (kèm usage), không khẳng định task nghiệp vụ thành công; `observe`/`agent read` chỉ để đối chiếu bổ sung sau khi báo cáo đến, hoặc khi người dùng yêu cầu tra cứu. Nếu chưa có watch/forwarder nào: ghi rõ "đã submit, báo cáo sẽ tự về" và kết thúc lượt, không chuyển sang chờ.
85
85
  5. Báo tên agent, pane, cùng kết quả hoặc trạng thái chưa xác minh; dừng đúng giới hạn. Không tự đóng pane có việc đang chạy hay pane người dùng; không dọn tài nguyên nếu chưa được yêu cầu. Worktree là checkout riêng, **không phải OS sandbox**.
86
+
87
+ ## Spawn subagent và mở lại session (Herdgate helper)
88
+
89
+ Pane chết không mất session — nhưng tra cứu tay thì phiến nghiệp. Dùng helper Herdgate
90
+ (`experiments/pi-spawn/spawn.mjs`): **một UUID làm cả request id lẫn `pi --session-id`**,
91
+ biết session ngay lúc spawn, quan hệ cha-con (session controller → session con) ghi bền
92
+ vào `spawns.jsonl` cạnh journal receipt:
93
+
94
+ ```bash
95
+ node experiments/pi-spawn/spawn.mjs spawn reviewer --cwd /home/bom/source # trả {id, paneId, bound:true}
96
+ # ... arm/watch/gửi việc theo id đó như quy trình trên ...
97
+ node experiments/pi-spawn/spawn.mjs list # cây con + pane còn sống không
98
+ node experiments/pi-spawn/spawn.mjs restore reviewer # mở lại ĐÚNG session, một lệnh
99
+ ```
100
+
101
+ Helper dùng `pi --session-id <id>` (mở session có id đó, không có thì tạo — idempotent);
102
+ chạy bên trong pane Herdr thì tự nhận parent session. Không lưu prompt/answer trong registry.
103
+
104
+ Thủ công (fallback khi không có helper):
105
+
106
+
107
+ Pane chết không mất session — Pi session là file. Khôi phục đúng quy trình (khác với quy tắc
108
+ "không resume cho agent mới": đây là trả lại đúng session cũ của pane đó):
109
+
110
+ ```bash
111
+ PANE=$("$H" pane split --current --direction right --no-focus --cwd /home/bom/source | jq -r .result.pane.pane_id)
112
+ "$H" agent start <tên> --kind pi --pane "$PANE" --timeout 45000 -- --session <session-id|đường-dẫn-file>
113
+ "$H" pane list # xác minh agent_session trỏ đúng file session cũ
114
+ ```
115
+
116
+ Cờ sau `--` truyền thẳng cho Pi; **dùng `--session <id|path>`** — `--resume` không nhận id,
117
+ nó mở menu chọn tương tác và agent sẽ không ràng buộc session. **Không dùng `pane run 'pi …'`
118
+ để khởi chạy/khôi phục agent**: phản hồi của `pane run` chỉ là "input đã xếp", không chờ readiness,
119
+ không ràng buộc agent — agent sẽ hiện không có session và controller không quản lý được.
120
+ Muốn đóng agent: `/quit` trong pane đó, đợi shell prompt; đóng pane phải do người dùng quyết định.
121
+
122
+ ## Wake protocol — khi nhận `[herdgate-wake …]`
123
+
124
+ Publisher bắn wake-frame vào pane cha khi receipt của agent con settle. Frame tự mang
125
+ chỉ thị, nhưng ghi nhớ bền ở đây (sống sót qua context compaction):
126
+
127
+ **Nhận `[herdgate-wake child=<tên> id=<uuid> status=…]` → làm TRỌN trong đúng turn đó.**
128
+ **Reply PHẢI mở đầu bằng banner 1 dòng**: `🔔 WAKE — agent <tên> <status>: <kết quả trong 1 câu>`
129
+ (id receipt nằm ở dòng sau). Turn wake nhanh và dễ bị người dùng bỏ qua — mở đầu bằng id
130
+ hoặc văn thường là như không báo (đã xảy ra: user nhìn thẳng pane vẫn nghĩ chưa có gì đến):
131
+ 1. Chạy test mục tiêu của phần việc con vừa làm (`node --test test/<file>.test.ts`).
132
+ 2. Review diff (`git diff` + `git status`) — đúng whitelist file đã giao.
133
+ 3. Commit nếu đạt (thông điệp ghi rõ agent nào, spawn id).
134
+ 4. Báo user ngắn gọn ngay trong reply (agent nào xong, commit gì, test bao nhiêu pass).
135
+ 5. Cần report đầy đủ: `node experiments/pi-receipt/query.mjs --gate <gate> --device <d> --secret <s> --id <uuid> --body`.
136
+
137
+ KHÔNG chỉ ack rồi kết thúc turn — mỗi lần ack suông là một phần việc chết chờ user nhắc
138
+ (đã xảy ra: 3 wake đến, 0 được xử lý trọn). Cây agent: `node experiments/pi-spawn/dag.mjs`.
139
+
140
+ ## Giao việc cho subagent — MỘT lệnh
141
+
142
+ ```bash
143
+ node experiments/pi-spawn/task.mjs start <tên> <taskfile> [--cwd DIR] [--tab] # spawn+arm+prompt, marker tự đúng định dạng
144
+ node experiments/pi-spawn/task.mjs continue <tên> <taskfile|text> # re-prompt con đang sống
145
+ node experiments/pi-spawn/task.mjs status [tên] # recent-first, kèm receipt
146
+ node experiments/pi-spawn/task.mjs close <tên> # delegate spawn.mjs close
147
+ ```
148
+ Lệnh gốc spawn.mjs giữ cho edge case. Không tự ghép spawn+arm+prompt tay nữa —
149
+ marker sai định dạng từng làm cả đợt agent mù observation.
150
+
151
+ ## Vòng đời con — dọn ngay, không tích tụ
152
+
153
+ Parent là chủ vòng đời con mình. Sau khi wake đã xử lý (test/commit xong), nếu KHÔNG còn
154
+ việc kế tiếp đã lên kế hoạch cho con đó → **đóng ngay trong cùng turn**:
155
+
156
+ ```bash
157
+ node experiments/pi-spawn/spawn.mjs close <tên> # đóng tab/pane con; từ chối nếu đang working
158
+ ```
159
+
160
+ Record spawn vẫn còn nên cần lại chỉ là `spawn.mjs restore <tên>` (đúng session one-id).
161
+ Sau reboot/machine restart: node experiments/pi-spawn/spawn.mjs revive (dry-run trước nếu muốn xem kế hoạch).
162
+ Chỉ giữ con sống khi còn job tiếp theo cho nó. Pane/tab của NGƯỜI DÙNG không bao giờ tự đóng.
163
+
164
+ ## Nhánh chính hay worktree? — tránh xung đột trước khi spawn
165
+
166
+ **Làm trực tiếp nhánh chính (checkout đang mở)** khi thỏa CẢ HAI:
167
+ - Chỉ MỘT người viết tại một thời điểm (controller đơn mình, hoặc các agent có
168
+ whitelist file RỜI nhau hoàn toàn — ghi rõ whitelist trong prompt giao việc), VÀ
169
+ - Việc nhỏ/vừa, user đang theo dõi và cần commit ngay.
170
+
171
+ **BẮT BUỘC worktree riêng** khi:
172
+ - ≥2 subagent song song đụng CÙNG module/file (whitelist không tách nổi), HOẶC
173
+ - Việc dài/lớn trong lúc user có thể tự gõ lên repo chính, HOẶC thử nghiệm chưa chắc giữ.
174
+
175
+ ```bash
176
+ herdr worktree create --cwd <repo> --branch hg-<task> # tạo + mở workspace worktree
177
+ node experiments/pi-spawn/spawn.mjs spawn <tên> --cwd <repo>/../<worktree-dir> --tab
178
+ # con làm + test TRONG worktree (receipt scope theo cwd nên tự tách khỏi journal chính)
179
+ # wake về → controller verify trong worktree → về repo chính: git merge, rồi:
180
+ herdr worktree remove # dọn worktree sau khi merge
181
+ ```
182
+
183
+ Nguyên tắc: whitelist file là lớp 1; worktree là lớp 2 khi lớp 1 không đủ. Không bao giờ
184
+ để hai agent cùng ghi một file ở hai nơi rồi tự hòa giải — merge là việc của controller,
185
+ trên repo chính, sau khi từng con đã settle.
package/DESIGN.md CHANGED
@@ -219,3 +219,31 @@ bridge-side. herdgate: the cloud in the middle, own identity, host renders, clou
219
219
  ideas kept: hello-first auth, hashed tokens, scope-aware routing, single-use artifacts, rate limits everywhere.
220
220
  The parts dropped: mod sandboxing (the host is trusted code on its own machine), tree recording (the host owns
221
221
  its UI), Tailscale (public via cloudflared).
222
+
223
+
224
+ ## Wake by herdr event (2026-11-22)
225
+
226
+ Settles and pane deaths are **herdr's observations**, not the child's. The plugin manifest
227
+ hooks `pane.agent_status_changed`, `pane.exited`, `pane.closed` into
228
+ `plugin/server/wake-event.mjs` — a short-lived process per event:
229
+
230
+ ```
231
+ herdr event ─▶ wake-event.mjs ─▶ registry lookup (spawn children only)
232
+ ├─ settle (idle|done, revision-stable) ─▶ 🔔 frame → parent pane
233
+ └─ death (no final receipt, not closedBy parent) ─▶ DIED frame (once)
234
+ ```
235
+
236
+ Discipline layered from live incidents and the herdr-pings/sidebar/cats deep research:
237
+ flock try_lock per event (burst dedup) · heartbeat liveness (>20s stale revision =
238
+ corpse echo, dropped) · generation tokens on every frame (`gen=<revision>`) ·
239
+ stamp-and-byte-verify sidecar writes · parent quiet-wait before typing (pane run,
240
+ never the RPC channel) · `parentPaneId` recorded at spawn beats session-file lookup.
241
+ The publisher keeps receipts purely as evidence (device push); it no longer wakes.
242
+
243
+ ## State discipline (2026-11-22)
244
+
245
+ Spawn registry and receipt-adjacent state follow herdr-portfwd's rules: a damaged file
246
+ throws WITH ITS NAME (never reads as empty), writes are O_EXCL temp + rename with a
247
+ stable sort (byte-stable files), and a state directory writable by group/other is
248
+ refused outright. `startCloud` resolves only after the sshd has bound (a Cloud whose
249
+ `.ssh.port` is still zero made ssh2 silently dial :22 — a live flake).
package/README.md CHANGED
@@ -38,9 +38,16 @@ src/cloud/ the gateway: stores, pairing, routing, HTTP/WS, CLI (main.ts)
38
38
  src/agent/ HerdGateAgent SDK + AgentAdapter (what a host app implements)
39
39
  src/host/ standalone host CLI (no Herdr needed) + the `herdr api snapshot` adapter
40
40
  plugin/ the Herdr TUI plugin: herdr-plugin.toml + server/ (what `herdr plugin link` loads)
41
+ — op table, wake-event hooks, receipts/observers/attachments modules
42
+ experiments/ host-local CLIs + SDK pieces the controller drives by hand:
43
+ pi-spawn (task.mjs lifecycle, registry, pipeline, dag),
44
+ pi-receipt (observer that runs INSIDE children, query/search/usage/gc),
45
+ pi-worker (run-jobs, scheduler, MCP, durable probes)
46
+ docs/research/ two-tier deep research on 12 herdr plugins (2,426 lines, file:line-sourced)
41
47
  app-mod/ the Herdr app mod: mods/herdgate/ (what `herdr-app check` validates)
42
48
  src/web/ the PWA a device opens — served by the cloud, same origin as the WS legs
43
- test/ e2e relay, the adapter, and the plugin's own commands
49
+ test/ 57 files / 275 tests: relay e2e, plugin ops over the device channel,
50
+ wake-event semantics, spawn lifecycle, sysmon/port fixtures, web assets
44
51
  ```
45
52
 
46
53
  ## Self-hosted release
@@ -112,6 +119,53 @@ HERDGATE_URL=https://herd.example.com HERDGATE_ROOM_TOKEN=… npm run host
112
119
 
113
120
  Devices pair into the room and ask for `{op:"view"}`; the host answers with the current Herdr metadata.
114
121
 
122
+ ## The subagent fleet (receipts · wake · observers)
123
+
124
+ Beyond relaying, the Herdr plugin runs a full **subagent observability and lifecycle stack**.
125
+ Everything below is local-first (append-only JSONL + registry under XDG state dirs), fail-closed,
126
+ and testable — 275 tests cover it.
127
+
128
+ ### Identity and evidence — receipts
129
+ Every spawned child gets a **one-id** (`spawn:<uuid>`) recorded in a bounded registry; panes and
130
+ session files are carriers, never the address. The arm→prompt handshake acknowledges via an ack
131
+ file (no sleep-and-hope). Each marked request becomes a **receipt**: status/reason, usage tokens/$,
132
+ `turns`/`lastActivityAt`, a leak-safe title, delivery state (`delivered|stalled|unverified`), a
133
+ failure **phase** (`failed_before_dispatch` vs post-dispatch), and an optional gated body archive.
134
+ Search is BM25 (diacritic-folded) over bodies+transcripts; devices see publicReceipt shapes only.
135
+ A journal GC (dry-run default) never deletes `unknown` — unresolved evidence stays.
136
+
137
+ ### Wake — herdr is the observer
138
+ Settles no longer depend on child cooperation: the plugin manifest hooks herdr's own events
139
+ (`pane.agent_status_changed`, `pane.exited`, `pane.closed`) into `server/wake-event.mjs`, a
140
+ short-lived process per event. A child's closed turn (or death without a settle) becomes a
141
+ `🔔 WAKE` frame typed into the parent pane — after revision-stability quiet-wait, deduped by
142
+ generation, guarded against event bursts (flock) and corpse echoes (heartbeats), with title/tokens
143
+ enriched from the receipt journal when present. Receipts are evidence; **herdr is the trigger**.
144
+
145
+ ### Lifecycle — one command per verb
146
+ ```sh
147
+ node experiments/pi-spawn/task.mjs start <name> <taskfile> --tab # spawn+arm+prompt, marker-safe
148
+ node experiments/pi-spawn/task.mjs continue <name> <text|file> # self-describing re-prompt
149
+ node experiments/pi-spawn/task.mjs status [name] # recent-first, receipt-aware
150
+ node experiments/pi-spawn/spawn.mjs close <id> # 3-layer retire + generation check
151
+ node experiments/pi-spawn/spawn.mjs revive [--dry-run] # after a reboot: exact sessions back
152
+ node experiments/pi-spawn/pipeline.mjs run <task.md> --fake # worktree→agent→test→retry→reviewer
153
+ ```
154
+ See `.agents/skills/herdr/SKILL.md` for the operating protocol (in-turn wake handling, the
155
+ no-accumulation close rule, worktree-vs-main-branch whitelists).
156
+
157
+ ### Device-channel ops (the PWA's vocabulary)
158
+ `view` · `receipt.query/search/body/ack` · `receipt.enrich` (model/context/usage from the transcript)
159
+ · `usage.rollup` · `diff.get` (hardened git: hooks off, env scrubbed, `~ ^` refs)
160
+ · `sysmon.snapshot` (per-agent CPU/RAM from /proc, cutime-aware) · `ports.list` (listeners attributed
161
+ by process ancestry; unattributed stay honest) · `attachment.upload/list` (magic-byte photos from
162
+ the phone to the agent's own disk, 0700/0600, uuid names) — plus the SSH/mobile leg below.
163
+
164
+ ### Mobile transport
165
+ One persistent shell with marker framing replaces exec-per-command; phone keystrokes enter a
166
+ bounded, coalescing, in-order-acked queue that resyncs instead of replaying; file polls are
167
+ checksum-stamped (`unchanged` costs one word).
168
+
115
169
  ## The SSH leg (the Herdr phone app)
116
170
 
117
171
  The phone app adds machines over SSH. Herdgate terminates SSH at the Gate; use the Gate's reachable SSH
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bom0792/herdgate",
3
- "version": "0.9.36",
3
+ "version": "0.9.38",
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": {
@@ -20,6 +20,7 @@
20
20
  "postinstall": "node scripts/patch-ssh2.mjs && node scripts/install-pi-skills.mjs"
21
21
  },
22
22
  "dependencies": {
23
+ "qrcode-terminal": "^0.12.0",
23
24
  "ssh2": "^1.17.0",
24
25
  "ws": "^8.18.0"
25
26
  },
@@ -12,6 +12,23 @@ platforms = ["linux", "macos"]
12
12
  [[startup]]
13
13
  command = ["node", "server/index.mjs", "serve"]
14
14
 
15
+ # Wake-by-event: herdr itself reports pane lifecycle and agent settles. Each
16
+ # hook is a short-lived process (server/wake-event.mjs) that resolves the spawn
17
+ # registry's parent edge and delivers one wake frame — no daemon, no polling,
18
+ # and no cooperation (arm/marker/observer) needed from the child. User panes
19
+ # are not in the registry, so their events exit silently.
20
+ [[events]]
21
+ on = "pane.agent_status_changed"
22
+ command = ["node", "server/wake-event.mjs"]
23
+
24
+ [[events]]
25
+ on = "pane.exited"
26
+ command = ["node", "server/wake-event.mjs"]
27
+
28
+ [[events]]
29
+ on = "pane.closed"
30
+ command = ["node", "server/wake-event.mjs"]
31
+
15
32
  [[actions]]
16
33
  id = "status"
17
34
  title = "herdgate: show pairing status"
@@ -0,0 +1,184 @@
1
+ // Photo/file attachments uploaded from the PWA composer (Wave C3).
2
+ //
3
+ // The herdcats lesson (docs/research/2026-11-21-marketplace/deep/cats.md,
4
+ // resolver.rs / runtime.mjs endpoint hygiene): files arriving from a device
5
+ // land ON THE AGENT MACHINE under a private directory the plugin owns —
6
+ // * every directory level is mkdir'd then chmod'd 0700 one by one, and a
7
+ // level that already exists as a symlink is refused ('symlink'),
8
+ // * the client-supplied name is NEVER trusted for the stored filename —
9
+ // names are <uuid>.<ext>, and <ext> comes from sniffing magic bytes,
10
+ // not from the name or the declared mime type,
11
+ // * the file itself is written O_CREAT|O_EXCL mode 0600.
12
+ // The reply then carries a path hint so the Pi agent opens the file with its
13
+ // own read tool — image bytes never ride the prompt text.
14
+ //
15
+ // Pure exports, no sockets: the device ops in index.mjs call these.
16
+
17
+ import { randomUUID } from 'node:crypto';
18
+ import {
19
+ chmodSync, closeSync, constants, lstatSync, mkdirSync, openSync, readdirSync, rmSync, statSync, writeSync,
20
+ } from 'node:fs';
21
+ import { dirname, join, resolve, sep } from 'node:path';
22
+
23
+ export const MAX_ATTACHMENT_BYTES = 4 * 1024 * 1024; // 4 MiB hard cap, device and host agree
24
+ export const ATTACHMENTS_DIR = 'attachments';
25
+ const MONTH_DIR = /^\d{4}-(0[1-9]|1[0-2])$/;
26
+ /** Stored filenames only: <uuid>.<ext> with ext from the magic-byte whitelist. */
27
+ const STORED = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(png|jpe?g|webp|gif)$/;
28
+ const DAY_MS = 86400e3;
29
+
30
+ /** Sniff the image type from magic bytes — the name and mime are never trusted.
31
+ * PNG \x89PNG\r\n\x1a\n · JPEG \xFF\xD8\xFF · GIF "GIF8" · WEBP "RIFF"…."WEBP". */
32
+ export function sniffType(bytes) {
33
+ if (!Buffer.isBuffer(bytes)) return null;
34
+ const has = (offset, hex) => {
35
+ if (bytes.length < offset + hex.length) return false;
36
+ return hex.every((byte, i) => bytes[offset + i] === byte);
37
+ };
38
+ if (has(0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'png';
39
+ if (has(0, [0xff, 0xd8, 0xff])) return 'jpg';
40
+ if (has(0, [0x47, 0x49, 0x46, 0x38])) return 'gif'; // "GIF8" (GIF87a/GIF89a)
41
+ if (has(0, [0x52, 0x49, 0x46, 0x46]) && has(8, [0x57, 0x45, 0x42, 0x50])) return 'webp'; // RIFF<u32>WEBP
42
+ return null;
43
+ }
44
+
45
+ /** Create base/attachments/<yyyy-mm> one level at a time. Ancestors above base
46
+ * are only created when missing (never chmod'd — /tmp and friends are not
47
+ * ours; on macOS /tmp is even a system symlink). From base down — the
48
+ * plugin's own territory — every level is mkdir'd (0700) then chmod'd 0700,
49
+ * created or not, and a level that exists as a symlink is refused. Returns
50
+ * the month directory path. */
51
+ function ensureMonthDir(base, now = new Date()) {
52
+ const month = `${now.getUTCFullYear()}-` + String(now.getUTCMonth() + 1).padStart(2, '0');
53
+ const dir = join(base, ATTACHMENTS_DIR, month);
54
+ const abs = resolve(base);
55
+ const segments = abs.split(sep).filter(Boolean);
56
+ const prefix = abs.startsWith(sep) ? sep : '';
57
+ // 1. bring base into existence (each missing ancestor mkdir'd 0700, no chmod)
58
+ let walk = prefix;
59
+ for (const part of segments) {
60
+ walk = walk === prefix ? join(prefix, part) : join(walk, part);
61
+ try { lstatSync(walk); continue; }
62
+ catch (error) { if (error.code !== 'ENOENT') throw error; }
63
+ mkdirSync(walk, { mode: 0o700 });
64
+ chmodSync(walk, 0o700);
65
+ }
66
+ // 2. base/attachments/<month>: 0700 each level, refuse planted symlinks
67
+ let level = abs;
68
+ for (const part of [ATTACHMENTS_DIR, month]) {
69
+ level = join(level, part);
70
+ let st = null;
71
+ try { st = lstatSync(level); }
72
+ catch (error) { if (error.code !== 'ENOENT') throw error; }
73
+ if (st) {
74
+ if (st.isSymbolicLink()) throw new Error('symlink'); // planted path — refuse, never write through it
75
+ if (!st.isDirectory()) throw new Error('not_a_directory');
76
+ } else {
77
+ mkdirSync(level, { mode: 0o700 });
78
+ }
79
+ chmodSync(level, 0o700); // every traversed level ends 0700, created or pre-existing
80
+ st = lstatSync(level); // post-create check: what we made must be a real dir
81
+ if (!st || st.isSymbolicLink() || !st.isDirectory()) throw new Error('symlink');
82
+ }
83
+ return dir;
84
+ }
85
+
86
+ /**
87
+ * Save one uploaded image: validate, sniff the type, store under
88
+ * base/attachments/<yyyy-mm>/<uuid>.<ext> (O_EXCL|O_CREAT, mode 0600).
89
+ * `name` is client metadata only — it never reaches the stored path.
90
+ * Returns { id, path }. Throws 'bad_bytes' | 'empty' | 'too_large' |
91
+ * 'bad_type' | 'symlink' — callers translate to a clear error op.
92
+ */
93
+ export function saveAttachment(base, { name, bytes }) {
94
+ if (!Buffer.isBuffer(bytes)) throw new Error('bad_bytes');
95
+ if (bytes.length === 0) throw new Error('empty');
96
+ if (bytes.length > MAX_ATTACHMENT_BYTES) throw new Error('too_large');
97
+ const type = sniffType(bytes);
98
+ if (!type) throw new Error('bad_type');
99
+ if (name !== undefined && (typeof name !== 'string' || name.length < 1 || name.length > 255)) {
100
+ throw new Error('bad_name');
101
+ }
102
+ const dir = ensureMonthDir(base);
103
+ const id = randomUUID(); // stored names are uuids — a client name is never trusted
104
+ const path = join(dir, `${id}.${type}`);
105
+ const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
106
+ try {
107
+ writeSync(fd, bytes);
108
+ } finally {
109
+ closeSync(fd);
110
+ }
111
+ chmodSync(path, 0o600); // explicit: survive any umask
112
+ return { id, path };
113
+ }
114
+
115
+ /**
116
+ * Metadata for every stored attachment (id, path, size, at) newest first.
117
+ * Never reads file contents; a missing base answers [].
118
+ */
119
+ export function listAttachments(base) {
120
+ const out = [];
121
+ const root = join(base, ATTACHMENTS_DIR);
122
+ let months = [];
123
+ try { months = readdirSync(root); }
124
+ catch { return out; }
125
+ for (const month of months.sort()) {
126
+ if (!MONTH_DIR.test(month)) continue;
127
+ let names = [];
128
+ try { names = readdirSync(join(root, month)); }
129
+ catch { continue; }
130
+ for (const name of names) {
131
+ const match = STORED.test(name);
132
+ if (!match) continue;
133
+ const path = join(root, month, name);
134
+ try {
135
+ const st = statSync(path);
136
+ if (!st.isFile()) continue;
137
+ out.push({ id: name.slice(0, 36), path, size: st.size, at: st.mtimeMs });
138
+ } catch { /* vanished mid-list: skip, never throw */ }
139
+ }
140
+ }
141
+ return out.sort((a, b) => b.at - a.at);
142
+ }
143
+
144
+ /**
145
+ * TTL sweep for stored attachments, dry-run by default (the gcJournal
146
+ * philosophy): report what `days` would reclaim, touch nothing unless
147
+ * apply: true. `at` (mtime) is the age clock; unreadable entries land in
148
+ * errors and are never deleted.
149
+ */
150
+ export function gcAttachments(base, { days = 14, apply = false, now = Date.now() } = {}) {
151
+ const at = Number.isFinite(now) ? now : Date.now();
152
+ const span = Number.isFinite(days) ? Math.max(0, Math.floor(days)) : 14;
153
+ const cutoff = at - span * DAY_MS;
154
+ const report = { attachments: 0, candidates: [], bytesReclaimable: 0, errors: [], applied: false, deleted: 0, bytesFreed: 0 };
155
+ const keep = [];
156
+ const months = new Set();
157
+ for (const entry of listAttachments(base)) {
158
+ report.attachments++;
159
+ months.add(dirname(entry.path));
160
+ if (entry.at < cutoff) {
161
+ report.candidates.push({ id: entry.id, path: entry.path, bytes: entry.size, at: entry.at });
162
+ report.bytesReclaimable += entry.size;
163
+ } else {
164
+ keep.push(entry.path);
165
+ }
166
+ }
167
+ if (!apply) return report;
168
+ report.applied = true;
169
+ for (const candidate of report.candidates) {
170
+ try {
171
+ rmSync(candidate.path, { force: false });
172
+ report.deleted++;
173
+ report.bytesFreed += candidate.bytes;
174
+ } catch (error) {
175
+ report.errors.push({ path: candidate.path, code: error.code ?? 'unlink_failed' });
176
+ }
177
+ }
178
+ // A month dir left empty by the sweep goes away too (best effort, never recursive).
179
+ for (const dir of months) {
180
+ try { rmSync(dir, { recursive: false }); }
181
+ catch { /* not empty or vanished — fine */ }
182
+ }
183
+ return report;
184
+ }
@@ -22,6 +22,21 @@ export const NOISE_NAME = "Noise_XX_P256_AESGCM_SHA256";
22
22
  export const KEY_LEN = 32;
23
23
  export const PUB_LEN = 65; // uncompressed P-256 point: 0x04 ‖ X ‖ Y
24
24
 
25
+ /** Session lifetime (Paseo lesson: handshake lifetime). A transport key that lives
26
+ * forever erodes forward secrecy — compromising it exposes the WHOLE session since
27
+ * the handshake. Rotation fences exposure to the slice since the last handshake.
28
+ * Bounds: messages per direction (far under nonce exhaustion at 2^32) or wall time,
29
+ * whichever comes first. The device initiates; the host's `e2e.init` handler swaps
30
+ * the session in place, so rotation is just a fresh handshake. */
31
+ export const REKEY_AFTER_MESSAGES = 2 ** 24;
32
+ export const REKEY_AFTER_MS = 24 * 60 * 60 * 1000;
33
+
34
+ /** True when a READY channel has reached either lifetime bound. */
35
+ export function needsRekey(ch, now = Date.now()) {
36
+ if (!ch?.ready()) return false;
37
+ return ch.usage() >= REKEY_AFTER_MESSAGES || now - ch.handshakeAt >= REKEY_AFTER_MS;
38
+ }
39
+
25
40
  // ---- byte helpers (kept dependency-free; typed arrays only) ----------------
26
41
 
27
42
  export function b64e(u8) {
@@ -189,6 +204,7 @@ export class DeviceChannel {
189
204
  sendCs = null;
190
205
  recvCs = null;
191
206
  hostFingerprint = null;
207
+ handshakeAt = 0; // set when Split() runs — the rotation clock starts at ready
192
208
  constructor(self) {
193
209
  this.#self = self;
194
210
  }
@@ -218,12 +234,17 @@ export class DeviceChannel {
218
234
  const [c1, c2] = await this.#hs.split();
219
235
  this.sendCs = c1; // device → host
220
236
  this.recvCs = c2; // host → device
237
+ this.handshakeAt = Date.now();
221
238
  this.#e = null;
222
239
  return { c: b64e(c) };
223
240
  }
224
241
  ready() {
225
242
  return Boolean(this.sendCs && this.recvCs);
226
243
  }
244
+ /** Messages carried under the current keys (max of both directions). */
245
+ usage() {
246
+ return Math.max(this.sendCs?.n ?? 0, this.recvCs?.n ?? 0);
247
+ }
227
248
  async send(obj) {
228
249
  const { ct, n } = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
229
250
  return { op: "e2e", n, c: b64e(ct) };
@@ -241,6 +262,7 @@ export class HostChannel {
241
262
  sendCs = null;
242
263
  recvCs = null;
243
264
  deviceFingerprint = null;
265
+ handshakeAt = 0; // set when Split() runs — the rotation clock starts at ready
244
266
  constructor(self) {
245
267
  this.#self = self;
246
268
  }
@@ -266,11 +288,16 @@ export class HostChannel {
266
288
  const [c1, c2] = await this.#hs.split();
267
289
  this.recvCs = c1; // device → host (c1 encrypts initiator→responder)
268
290
  this.sendCs = c2; // host → device
291
+ this.handshakeAt = Date.now();
269
292
  this.#e = null;
270
293
  }
271
294
  ready() {
272
295
  return Boolean(this.sendCs && this.recvCs);
273
296
  }
297
+ /** Messages carried under the current keys (max of both directions). */
298
+ usage() {
299
+ return Math.max(this.sendCs?.n ?? 0, this.recvCs?.n ?? 0);
300
+ }
274
301
  async send(obj) {
275
302
  const { ct, n } = await this.sendCs.encrypt(this.#hs.h, utf8e(JSON.stringify(obj)));
276
303
  return { op: "e2e", n, c: b64e(ct) };
@@ -0,0 +1,126 @@
1
+ /**
2
+ * Hardened read-only git for the plugin — every `git` invocation that answers a
3
+ * device payload funnels through gitRead (the herdr-file-viewer git.rs lesson).
4
+ *
5
+ * Fail-closed by construction:
6
+ * - argv: each arg must match [A-Za-z0-9._/:-] (no space, `;`, `$()`, newline,
7
+ * unicode …), and any arg that looks like a flag must be on a tiny read-flag
8
+ * allowlist — `--upload-pack`-style option injection is refused before git
9
+ * is ever spawned (execFile never shells out, this is defense in depth).
10
+ * - cwd: never payload-chosen. Only the plugin dir itself, or the
11
+ * HERDGATE_DIFF_REPO_DIR test override. Anything else refuses.
12
+ * - env: scrubbed to PATH/HOME/LANG + GIT_OPTIONAL_LOCKS=0 (the herdr-sidebar
13
+ * lesson: a read must not take the index lock). GIT_DIR, GIT_WORK_TREE and
14
+ * every other GIT_* from the publisher's environment never cross the
15
+ * boundary, so no env can redirect which repository is read.
16
+ * - hardening flags on every run: `-c core.fsmonitor=false` and
17
+ * `-c core.hooksPath=` go before the subcommand (real global options), and
18
+ * `--no-ext-diff --no-textconv` right after a diff-family subcommand — the
19
+ * only positions git accepts them — so hostile repo config (an evil
20
+ * textconv/diff.external driver, an fsmonitor daemon, a hooks dir) can never
21
+ * execute through a read.
22
+ *
23
+ * Reads only: callers that need writes keep their own spawn, but reuse
24
+ * scrubEnv() so the write path is equally deaf to GIT_* injection.
25
+ */
26
+
27
+ import { execFile as execFileCb } from "node:child_process";
28
+ import { dirname, resolve } from "node:path";
29
+ import { fileURLToPath } from "node:url";
30
+ import { promisify } from "node:util";
31
+
32
+ const execFile = promisify(execFileCb);
33
+
34
+ /** The plugin's own directory — one of the two cwds git may ever run in. */
35
+ export const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
36
+
37
+ /** The only cwd a git read may target: the plugin dir, or the test override. */
38
+ export function diffRepoDir() {
39
+ const override = process.env.HERDGATE_DIFF_REPO_DIR;
40
+ return override ? resolve(override) : PLUGIN_DIR;
41
+ }
42
+
43
+ /**
44
+ * Child env for every git run. PATH/HOME/LANG survive (git needs them to be
45
+ * findable and to read ~/.gitconfig); GIT_OPTIONAL_LOCKS=0 is added so a read
46
+ * never touches index.lock. Everything else — GIT_DIR, GIT_WORK_TREE,
47
+ * GIT_CONFIG_COUNT, GIT_* of any kind — is dropped.
48
+ */
49
+ export function scrubEnv() {
50
+ const env = {
51
+ PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
52
+ GIT_OPTIONAL_LOCKS: "0",
53
+ };
54
+ if (process.env.HOME !== undefined) env.HOME = process.env.HOME;
55
+ if (process.env.LANG !== undefined) env.LANG = process.env.LANG;
56
+ return env;
57
+ }
58
+
59
+ /** Args must be short printable words: refs, hashes, paths, allowed flags. */
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"]);
63
+ /** Subcommands that produce diffs — the only ones that take --no-ext-diff/--no-textconv. */
64
+ const DIFF_COMMANDS = new Set(["diff", "show", "log", "whatchanged", "format-patch", "range-diff"]);
65
+
66
+ function refuse(code, message) {
67
+ const err = new Error(message);
68
+ err.code = code;
69
+ return err;
70
+ }
71
+
72
+ function validateArgs(args) {
73
+ if (!Array.isArray(args) || args.length === 0) {
74
+ throw refuse("GIT_SAFE_ARG", "gitRead refuses: args must be a non-empty array");
75
+ }
76
+ for (const arg of args) {
77
+ if (typeof arg !== "string" || !ARG_RE.test(arg)) {
78
+ throw refuse("GIT_SAFE_ARG", `gitRead refuses arg ${JSON.stringify(arg)}: only [A-Za-z0-9._/:-], 1..128 chars`);
79
+ }
80
+ if (arg.startsWith("-") && !ALLOWED_FLAGS.has(arg)) {
81
+ throw refuse("GIT_SAFE_ARG", `gitRead refuses flag ${arg}: not on the read allowlist`);
82
+ }
83
+ }
84
+ }
85
+
86
+ /** The full argv handed to git: config overrides first (they are global), the
87
+ * diff hardening flags immediately after the diff subcommand (git rejects them
88
+ * in any other position). */
89
+ function buildArgv(args) {
90
+ let i = 0;
91
+ while (i < args.length && args[i].startsWith("-")) i += args[i] === "-C" ? 2 : 1;
92
+ const argv = ["-c", "core.fsmonitor=false", "-c", "core.hooksPath="];
93
+ if (DIFF_COMMANDS.has(args[i])) {
94
+ argv.push(...args.slice(0, i + 1), "--no-ext-diff", "--no-textconv", ...args.slice(i + 1));
95
+ } else {
96
+ argv.push(...args);
97
+ }
98
+ return argv;
99
+ }
100
+
101
+ /**
102
+ * Run one hardened read-only git command.
103
+ *
104
+ * @param {string[]} args git argv tail, e.g. ["show", "--no-color", "--stat", "--patch", ref]
105
+ * or ["-C", worktree, "diff", "--stat"] (git is pinned to a safe start cwd and
106
+ * re-pointed with -C — the filev pattern: git除外 vì dùng -C).
107
+ * @param {string} [cwd] where git starts; must be the plugin dir or the
108
+ * HERDGATE_DIFF_REPO_DIR override, otherwise the call refuses.
109
+ * @param {number} [timeoutMs] kill git after this long (default 10s).
110
+ * @param {number} [maxBuffer] output cap (default 8 MiB).
111
+ * @returns {Promise<{stdout: string, stderr: string}>} execFile's result, so
112
+ * callers keep their existing error mapping (e.stderr, exit codes).
113
+ */
114
+ export async function gitRead(args, cwd = diffRepoDir(), timeoutMs = 10_000, maxBuffer = 8 * 1024 * 1024) {
115
+ validateArgs(args);
116
+ const allowed = new Set([PLUGIN_DIR]);
117
+ if (process.env.HERDGATE_DIFF_REPO_DIR) allowed.add(resolve(process.env.HERDGATE_DIFF_REPO_DIR));
118
+ const startDir = resolve(cwd);
119
+ if (!allowed.has(startDir)) {
120
+ throw refuse(
121
+ "GIT_SAFE_CWD",
122
+ `gitRead refuses cwd ${cwd}: git reads run only in the plugin dir or HERDGATE_DIFF_REPO_DIR`,
123
+ );
124
+ }
125
+ return execFile("git", buildArgv(args), { cwd: startDir, timeout: timeoutMs, maxBuffer, env: scrubEnv() });
126
+ }