@sleep2agi/commhub-server 0.9.0-preview.0 → 0.9.0-preview.12

package/src/retention.ts

@@ -0,0 +1,269 @@
+// Round-2/4 review ② — retention sweep + incremental VACUUM.
+//
+// Background maintenance for the commhub database. Multi-tenant
+// public-facing hubs (e.g. <hub-domain>) write to high-frequency tables
+// on every heartbeat (agent_telemetry, task_events, completions) — left
+// unswept these grow unbounded, slow down indexed scans, and bloat the
+// on-disk footprint. SQLite never reclaims freed pages without VACUUM,
+// so a row delete by itself doesn't shrink the file.
+//
+// This module exposes:
+//   - sweepRetention(cfg): one-shot sweep across high-growth tables
+//   - startRetentionSweeper(): wires a 1-hour setInterval, fires once
+//     at startup with an immediate (non-blocking) sweep
+//
+// Defaults are conservative — long-tail debugging traces survive a
+// week. Operators can override per env (COMMHUB_RETENTION_*_DAYS) for
+// hot hubs.
+//
+// Run isolated tests against retention.test.ts:
+//   COMMHUB_DB=/tmp/test-retention.db bun test src/retention.test.ts
+
+import { db } from "./db.js";
+
+export type RetentionConfig = {
+  // High-frequency telemetry; default = 7 days.
+  // Heartbeat is ~30s → 50 agents × 86400 s/day ÷ 30 s = 144000 rows/day.
+  // At 7d that's ~1M rows. Indexed scans stay fast; raw disk = a few MB.
+  telemetryDays: number;
+  // Task state-change audit; default = 30 days.
+  // One row per status transition. Useful for incident forensics.
+  taskEventsDays: number;
+  // Acked inbox; default = 7 days post-ack.
+  // Once acked the row is no longer hot — keep a week for debugging.
+  // Unacked rows are NEVER swept (could be in-flight delivery).
+  ackedInboxDays: number;
+  // Completed/cancelled/failed tasks; default = 30 days.
+  // Active tasks (created/delivered/acked/running/replied less than
+  // 30 days old) are NEVER swept.
+  terminalTasksDays: number;
+  // Audit log; default = 90 days.
+  // Longer retention because audit_log is a security artifact.
+  auditLogDays: number;
+};
+
+export type SweepResult = {
+  startedAt: string;
+  durationMs: number;
+  deletes: {
+    agent_telemetry: number;
+    task_events: number;
+    inbox: number;
+    tasks: number;
+    audit_log: number;
+  };
+  vacuum: {
+    walCheckpointPagesMoved: number | null;
+    incrementalFreedPages: number | null;
+    errored: boolean;
+  };
+};
+
+const DEFAULTS: RetentionConfig = {
+  telemetryDays: 7,
+  taskEventsDays: 30,
+  ackedInboxDays: 7,
+  terminalTasksDays: 30,
+  auditLogDays: 90,
+};
+
+function readEnvDays(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  const n = Number(raw);
+  // Negative = disable that table's sweep entirely (operator opt-out).
+  // NaN / non-finite falls back to default — guard against fat-fingered env.
+  if (!Number.isFinite(n)) return fallback;
+  return n;
+}
+
+export function readRetentionConfig(): RetentionConfig {
+  return {
+    telemetryDays: readEnvDays("COMMHUB_RETENTION_TELEMETRY_DAYS", DEFAULTS.telemetryDays),
+    taskEventsDays: readEnvDays("COMMHUB_RETENTION_TASK_EVENTS_DAYS", DEFAULTS.taskEventsDays),
+    ackedInboxDays: readEnvDays("COMMHUB_RETENTION_INBOX_ACKED_DAYS", DEFAULTS.ackedInboxDays),
+    terminalTasksDays: readEnvDays("COMMHUB_RETENTION_TASKS_TERMINAL_DAYS", DEFAULTS.terminalTasksDays),
+    auditLogDays: readEnvDays("COMMHUB_RETENTION_AUDIT_DAYS", DEFAULTS.auditLogDays),
+  };
+}
+
+function sweepOne(
+  sql: string,
+  params: (string | number)[],
+  days: number,
+): number {
+  // days < 0 → operator opt-out for this table; skip the DELETE.
+  // days === 0 is a legitimate "sweep everything older than now"
+  // (effectively a TRUNCATE); we honour it.
+  if (days < 0) return 0;
+  try {
+    const res = db.run(sql, params);
+    return res.changes ?? 0;
+  } catch (e: any) {
+    console.log(`[commhub retention] sweep failed: ${e?.message ?? e}`);
+    return 0;
+  }
+}
+
+export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): SweepResult {
+  const startedAt = new Date().toISOString();
+  const t0 = Date.now();
+
+  const telemetry = sweepOne(
+    `DELETE FROM agent_telemetry WHERE created_at < datetime('now', ?1)`,
+    [`-${cfg.telemetryDays} days`],
+    cfg.telemetryDays,
+  );
+  const taskEvents = sweepOne(
+    `DELETE FROM task_events WHERE created_at < datetime('now', ?1)`,
+    [`-${cfg.taskEventsDays} days`],
+    cfg.taskEventsDays,
+  );
+  // Only sweep ACKED inbox rows — unacked may be in-flight delivery
+  // for an agent that's offline but coming back. Acked rows have
+  // served their purpose and exist only for debugging.
+  const inbox = sweepOne(
+    `DELETE FROM inbox WHERE acked = 1 AND created_at < datetime('now', ?1)`,
+    [`-${cfg.ackedInboxDays} days`],
+    cfg.ackedInboxDays,
+  );
+  // Terminal-task sweep — split into two DELETEs:
+  //
+  // (a) "safe terminals": cancelled / failed / expired / (theoretical)
+  //     completed have no chain-ancestor risk and are safe to reap
+  //     unconditionally past the horizon. NOTE: as of this writing
+  //     'completed' is dead code — no code path sets it (every reply
+  //     uses 'replied'/'failed'/'cancelled' via send_reply or
+  //     chainReplyToParent). Kept in the IN-list as a forward guard:
+  //     if someone introduces a 'completed' write later, the sweep
+  //     picks it up without code changes.
+  //
+  // (b) "replied" — was excluded entirely in the original PR, which
+  //     missed the goal: every fulfilled task lives at 'replied'
+  //     status, so the tasks table's MAIN GROWTH SOURCE would never
+  //     be reclaimed. Reviewer caught this. Fix: child-ref-aware
+  //     delete — reap an old replied row ONLY IF no other task
+  //     references it as parent_task_id. A row with no children is
+  //     not a chain ancestor and is safe to drop.
+  //
+  // **Time field** (both DELETEs): use COALESCE(completed_at, created_at).
+  // Terminal status means the server set `completed_at` at the
+  // reply/fail/cancel moment. Sweeping on `created_at` alone would
+  // reap a task created 60d ago but completed today the instant it
+  // entered terminal state — zero post-terminal retention. The
+  // COALESCE falls back to created_at for legacy rows that pre-date
+  // the completed_at column (back-compat).
+  const tasksSafeTerminal = sweepOne(
+    `DELETE FROM tasks
+     WHERE status IN ('completed', 'cancelled', 'failed', 'expired')
+       AND COALESCE(completed_at, created_at) < datetime('now', ?1)`,
+    [`-${cfg.terminalTasksDays} days`],
+    cfg.terminalTasksDays,
+  );
+  const tasksRepliedChildSafe = sweepOne(
+    `DELETE FROM tasks
+     WHERE status = 'replied'
+       AND COALESCE(completed_at, created_at) < datetime('now', ?1)
+       AND NOT EXISTS (
+         SELECT 1 FROM tasks AS child
+         WHERE child.parent_task_id = tasks.task_id
+       )`,
+    [`-${cfg.terminalTasksDays} days`],
+    cfg.terminalTasksDays,
+  );
+  const tasks = tasksSafeTerminal + tasksRepliedChildSafe;
+  const auditLog = sweepOne(
+    `DELETE FROM audit_log WHERE created_at < datetime('now', ?1)`,
+    [`-${cfg.auditLogDays} days`],
+    cfg.auditLogDays,
+  );
+
+  // VACUUM:
+  //   - wal_checkpoint(TRUNCATE): trims the WAL file. Works on every
+  //     SQLite DB regardless of auto_vacuum setting. Useful after
+  //     big DELETEs so the WAL doesn't stay bloated until the next
+  //     natural checkpoint.
+  //   - incremental_vacuum: ONLY reclaims main-DB pages on databases
+  //     created with `PRAGMA auto_vacuum = INCREMENTAL`. On legacy
+  //     DBs (the default mode 0) this is a no-op and the main file
+  //     does NOT shrink — freed pages stay in the freelist for
+  //     future inserts. Operators who want disk reclamation on old
+  //     DBs must run a one-time blocking `VACUUM` themselves (out of
+  //     scope for the sweeper, which deliberately stays non-
+  //     blocking).
+  let walCheckpointPagesMoved: number | null = null;
+  let incrementalFreedPages: number | null = null;
+  let errored = false;
+  try {
+    // wal_checkpoint(TRUNCATE) returns a row { busy, log, checkpointed }.
+    // We expose `log` (page count moved into the main DB) for ops visibility.
+    const checkpoint = db.get<{ busy: number; log: number; checkpointed: number }>(
+      "PRAGMA wal_checkpoint(TRUNCATE)",
+    );
+    walCheckpointPagesMoved = checkpoint?.log ?? null;
+  } catch (e: any) {
+    console.log(`[commhub retention] wal_checkpoint failed: ${e?.message ?? e}`);
+    errored = true;
+  }
+  try {
+    // incremental_vacuum is a no-op on databases not created with
+    // PRAGMA auto_vacuum = INCREMENTAL. For existing prod DBs that
+    // weren't, the operator would have to run a full one-time VACUUM
+    // to migrate — out of scope for the sweeper.
+    const freelistBefore = db.get<{ freelist_count: number }>("PRAGMA freelist_count");
+    db.exec("PRAGMA incremental_vacuum");
+    const freelistAfter = db.get<{ freelist_count: number }>("PRAGMA freelist_count");
+    incrementalFreedPages =
+      (freelistBefore?.freelist_count ?? 0) - (freelistAfter?.freelist_count ?? 0);
+  } catch (e: any) {
+    console.log(`[commhub retention] incremental_vacuum failed: ${e?.message ?? e}`);
+    errored = true;
+  }
+
+  return {
+    startedAt,
+    durationMs: Date.now() - t0,
+    deletes: {
+      agent_telemetry: telemetry,
+      task_events: taskEvents,
+      inbox,
+      tasks,
+      audit_log: auditLog,
+    },
+    vacuum: { walCheckpointPagesMoved, incrementalFreedPages, errored },
+  };
+}
+
+// Used by index.ts to wire the periodic sweeper. Returns the timer so
+// callers can stop it in tests / shutdown.
+export function startRetentionSweeper(
+  intervalMs = 60 * 60 * 1000, // 1 hour
+  cfg?: RetentionConfig,
+): ReturnType<typeof setInterval> {
+  const sweep = () => {
+    try {
+      const r = sweepRetention(cfg);
+      const totalDeletes =
+        r.deletes.agent_telemetry +
+        r.deletes.task_events +
+        r.deletes.inbox +
+        r.deletes.tasks +
+        r.deletes.audit_log;
+      if (totalDeletes > 0 || r.vacuum.errored) {
+        console.log(
+          `[commhub retention] swept in ${r.durationMs}ms — ` +
+            `telemetry=${r.deletes.agent_telemetry} events=${r.deletes.task_events} ` +
+            `inbox=${r.deletes.inbox} tasks=${r.deletes.tasks} audit=${r.deletes.audit_log} ` +
+            `walPages=${r.vacuum.walCheckpointPagesMoved} freedPages=${r.vacuum.incrementalFreedPages}`,
+        );
+      }
+    } catch (e: any) {
+      console.log(`[commhub retention] sweep top-level failed: ${e?.message ?? e}`);
+    }
+  };
+  // Fire once on startup so a long-running hub eventually catches up
+  // even if it's restarted just after the previous sweep. setImmediate
+  // (vs synchronous) keeps server startup from blocking on the sweep.
+  setImmediate(sweep);
+  return setInterval(sweep, intervalMs);
+}

package/src/shared/probe-host-allowlist-drift.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  VENDOR_HOST_ALLOWLIST as HUB_ALLOW,
+  FORBIDDEN_IPV4_RE as HUB_V4,
+  FORBIDDEN_IPV6_RE as HUB_V6,
+} from "./probe-host-allowlist.js";
+
+// RFC-028 P1 fold-in #1 — hub-and-daemon probe-host-allowlist drift
+// guard. Mirrors the G9 reserved-env drift test (RFC-026 §4.4.7).
+// Two enforcement modes:
+//   1. byte-identical source files
+//   2. runtime set-equality of the imported constants (vendor regex
+//      source strings + private-IP regex source strings)
+// If a future contributor edits one side without the other, this test
+// breaks the merge — the daemon-side compromised-hub defense depends
+// on the two lists being identical.
+
+const HUB_PATH = join(import.meta.dir, "probe-host-allowlist.ts");
+const DAEMON_PATH = join(
+  import.meta.dir,
+  "..", "..", "..", "agent-node", "src", "shared", "probe-host-allowlist.ts",
+);
+
+describe("RFC-028 P1 — hub/daemon probe-host-allowlist drift guard", () => {
+  test("byte-identical source files", () => {
+    const hub = readFileSync(HUB_PATH, "utf-8");
+    const daemon = readFileSync(DAEMON_PATH, "utf-8");
+    expect(daemon).toBe(hub);
+  });
+
+  test("VENDOR_HOST_ALLOWLIST regex sources equal at runtime", async () => {
+    const daemonMod = await import(DAEMON_PATH);
+    const daemonAllow = daemonMod.VENDOR_HOST_ALLOWLIST as Record<string, ReadonlyArray<RegExp>>;
+    // vendor set equality
+    expect(new Set(Object.keys(daemonAllow))).toEqual(new Set(Object.keys(HUB_ALLOW)));
+    // per-vendor regex source array equality (order matters — both should
+    // be authored in identical order to keep diffs minimal)
+    for (const vendor of Object.keys(HUB_ALLOW)) {
+      const hubSources = HUB_ALLOW[vendor].map(r => r.source);
+      const daemonSources = daemonAllow[vendor].map(r => r.source);
+      expect(daemonSources).toEqual(hubSources);
+    }
+  });
+
+  test("FORBIDDEN_IPV4_RE + FORBIDDEN_IPV6_RE sources equal at runtime", async () => {
+    const daemonMod = await import(DAEMON_PATH);
+    const daemonV4 = (daemonMod.FORBIDDEN_IPV4_RE as ReadonlyArray<RegExp>).map(r => r.source);
+    const daemonV6 = (daemonMod.FORBIDDEN_IPV6_RE as ReadonlyArray<RegExp>).map(r => r.source);
+    expect(daemonV4).toEqual(HUB_V4.map(r => r.source));
+    expect(daemonV6).toEqual(HUB_V6.map(r => r.source));
+  });
+});

package/src/shared/probe-host-allowlist.ts

@@ -0,0 +1,128 @@
+// RFC-028 P1 §4.4 — shared probe SSRF guards.
+// Host allowlist + private IP block + validateBaseUrl.
+//
+// MUST be byte-identical between hub (server/src/shared/) and daemon
+// (agent-node/src/shared/). Enforced by probe-host-allowlist-drift.test.ts
+// (same pattern as reserved-env.ts G9 drift guard, RFC-026 §4.4.7).
+//
+// Why mirror not symlink: hub and daemon are separate npm packages
+// installed independently on different machines. A drift-checked source
+// copy survives `npm pack` + global install; a symlink does not.
+//
+// Threat model the daemon re-check defends against:
+//   - Compromised hub records a malicious base_url in providers/spec
+//   - Hub bypassed validateBaseUrl (regression / different code path)
+//   - On-wire injection between hub→daemon SSE
+// Daemon trusts process.execPath + this file's content, NOT what
+// `get_probe_request` claims. If hub-side check is identical, daemon
+// re-check is a no-op; if hub-side ever loosens, daemon stays strict.
+
+export class ProbeValidationError extends Error {
+  constructor(public code: string, public detail?: Record<string, unknown>) {
+    super(`${code}${detail ? ` ${JSON.stringify(detail)}` : ""}`);
+    this.name = "ProbeValidationError";
+  }
+}
+
+// ── §4.4.1 per-vendor host allowlist ──────────────────────────────
+// `anthropic` vendor accepts Anthropic + curated 3rd-party Anthropic-
+// compatible endpoints that Vincent / N站马 ship live providers
+// against (DeepSeek + MiniMax both expose `/v1/messages` with the
+// Anthropic protocol surface). Whitelist semantics preserved — NOT
+// allow-any. New entries land here via PR with security review
+// (network-admin-configurable allowlist is backlog: needs strong
+// IP-range / shape guard before admins can edit).
+//
+// Per 通信龙 (RFC-028 P1.5+): the host whitelist is defense layer 1;
+// layer 2 is the DNS-resolved IP block (FORBIDDEN_IPV{4,6}_RE below),
+// applied AFTER allowlist passes. Any new host gets BOTH layers
+// automatically — host in allowlist + DNS resolves to private/metadata
+// IP still surfaces `probe_resolve_unsafe_ip`.
+//
+// P2 will add vendors (openai/zai/openrouter/qwen) as separate keys.
+export const VENDOR_HOST_ALLOWLIST: Record<string, ReadonlyArray<RegExp>> = {
+  anthropic:  [
+    /^api\.anthropic\.com$/,
+    /^api\.deepseek\.com$/,     // Anthropic-compatible /v1/messages
+    /^api\.minimax\.chat$/,     // MiniMax legacy domain
+    /^api\.minimax\.io$/,       // MiniMax new domain (Vincent live use)
+  ],
+  // P2:
+  // openai:     [/^api\.openai\.com$/],
+  // zai:        [/^api\.z\.ai$/, /^open\.bigmodel\.cn$/],
+  // openrouter: [/^openrouter\.ai$/],
+  // qwen:       [/^dashscope(-intl)?\.aliyuncs\.com$/],
+};
+export const SUPPORTED_VENDORS = Object.keys(VENDOR_HOST_ALLOWLIST);
+
+// ── §4.4.2 private/reserved IP block (anti SSRF) ──────────────────
+export const FORBIDDEN_IPV4_RE: ReadonlyArray<RegExp> = [
+  /^10\./,
+  /^127\./,
+  /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+  /^192\.168\./,
+  /^169\.254\./,           // link-local + 169.254.169.254 cloud metadata
+  /^100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\./,  // CGNAT
+  /^0\./,
+  /^22[4-9]\./, /^23[0-9]\./,  // multicast
+  /^24[0-9]\./, /^25[0-5]\./,  // experimental
+];
+export const FORBIDDEN_IPV6_RE: ReadonlyArray<RegExp> = [
+  /^::1$/,
+  /^::$/,
+  /^fe80:/i, /^fc00:/i, /^fd00:/i,
+];
+
+export function isLoopbackHost(host: string): boolean {
+  return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+
+export function isForbiddenIp(ip: string): boolean {
+  // IPv4-mapped IPv6: ::ffff:10.0.0.1 — recurse on inner v4
+  if (ip.toLowerCase().startsWith("::ffff:")) {
+    return isForbiddenIp(ip.slice(7));
+  }
+  // Simple v4/v6 distinction by presence of '.' / ':'
+  if (ip.includes(":") && !ip.includes(".")) {
+    return FORBIDDEN_IPV6_RE.some(re => re.test(ip));
+  }
+  return FORBIDDEN_IPV4_RE.some(re => re.test(ip));
+}
+
+// ── §4.4.3 validateBaseUrl — boot/pre-fetch URL+host+vendor check ─
+/** Pure, no I/O. Called by hub (upsert_provider write path) AND
+ *  daemon (handleProbeDoorbell re-check after get_probe_request).
+ *  allowLoopback: dev-only opt-in honoring http://localhost / 127.0.0.1.
+ *  Production daemon MUST NOT set allowLoopback=true. */
+export function validateBaseUrl(
+  vendor: string,
+  baseUrl: string,
+  opts: { allowLoopback?: boolean } = {},
+): void {
+  let u: URL;
+  try { u = new URL(baseUrl); }
+  catch {
+    throw new ProbeValidationError("probe_base_url_invalid", {
+      reason: "not a valid URL", baseUrl: baseUrl.slice(0, 100),
+    });
+  }
+
+  if (u.protocol !== "https:") {
+    if (!opts.allowLoopback || !isLoopbackHost(u.hostname) || u.protocol !== "http:") {
+      throw new ProbeValidationError("probe_base_url_invalid", {
+        reason: "must be https (or http+loopback with dev opt-in)",
+      });
+    }
+  }
+  const allowed = VENDOR_HOST_ALLOWLIST[vendor];
+  if (!allowed) {
+    throw new ProbeValidationError("vendor_not_supported", {
+      vendor, supported: SUPPORTED_VENDORS,
+    });
+  }
+  if (!allowed.some(re => re.test(u.hostname))) {
+    throw new ProbeValidationError("probe_target_forbidden", {
+      vendor, host: u.hostname, allowed: allowed.map(r => r.source),
+    });
+  }
+}

package/src/shared/reserved-env-drift.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  RESERVED_ENV_KEYS_EXACT as HUB_EXACT,
+  RESERVED_ENV_PREFIXES as HUB_PREFIXES,
+} from "./reserved-env.js";
+
+// RFC-026 v4 §4.4.7 G9 drift guard — denylist MUST be hub-and-daemon
+// identical, or attacker walks the looser layer. Two enforcement modes:
+//
+//   1. byte-identical source files (this test)
+//   2. runtime set-equality of the imported constants
+//
+// We assert both. If a future contributor edits one side without the
+// other, this test breaks the merge.
+
+const HUB_PATH = join(import.meta.dir, "reserved-env.ts");
+const DAEMON_PATH = join(import.meta.dir, "..", "..", "..", "agent-node", "src", "shared", "reserved-env.ts");
+
+describe("RFC-026 v4 §4.4.7 G9 — hub/daemon reserved-env drift guard", () => {
+  test("byte-identical source files", () => {
+    const hub = readFileSync(HUB_PATH, "utf-8");
+    const daemon = readFileSync(DAEMON_PATH, "utf-8");
+    expect(daemon).toBe(hub);
+  });
+
+  test("imported constants are set-equal at runtime", async () => {
+    // Use a dynamic file import path so this test breaks if the file
+    // moves but still references the daemon copy.
+    const daemonMod = await import(DAEMON_PATH);
+    const daemonExact = daemonMod.RESERVED_ENV_KEYS_EXACT as Set<string>;
+    const daemonPrefixes = daemonMod.RESERVED_ENV_PREFIXES as ReadonlyArray<string>;
+
+    // EXACT set equality
+    expect(daemonExact.size).toBe(HUB_EXACT.size);
+    for (const k of HUB_EXACT) expect(daemonExact.has(k)).toBe(true);
+    for (const k of daemonExact) expect(HUB_EXACT.has(k)).toBe(true);
+
+    // PREFIX array order-independent equality
+    expect(new Set(daemonPrefixes)).toEqual(new Set(HUB_PREFIXES));
+  });
+});

package/src/shared/reserved-env.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { RESERVED_ENV_KEYS_EXACT, RESERVED_ENV_PREFIXES, isReservedEnvKey } from "./reserved-env.js";
+
+describe("RFC-026 v4 §4.4.7 reserved env denylist (B1)", () => {
+  test("exact PATH/HOME/LANG/NODE_OPTIONS blocked", () => {
+    for (const k of ["PATH", "HOME", "LANG", "LC_ALL", "SHELL", "USER", "LOGNAME", "NODE_OPTIONS", "IFS", "TMPDIR"]) {
+      expect(isReservedEnvKey(k)).toBe(true);
+    }
+  });
+  test("LD_ prefix family blocked (Linux dynamic loader)", () => {
+    for (const k of ["LD_PRELOAD", "LD_LIBRARY_PATH", "LD_AUDIT", "LD_"]) {
+      expect(isReservedEnvKey(k)).toBe(true);
+    }
+  });
+  test("DYLD_ prefix blocked (macOS)", () => {
+    expect(isReservedEnvKey("DYLD_INSERT_LIBRARIES")).toBe(true);
+    expect(isReservedEnvKey("DYLD_LIBRARY_PATH")).toBe(true);
+  });
+  test("BUN_/NPM_/NPM_CONFIG_/NODE_ prefix blocked", () => {
+    expect(isReservedEnvKey("BUN_INSTALL")).toBe(true);
+    expect(isReservedEnvKey("NPM_TOKEN")).toBe(true);
+    expect(isReservedEnvKey("NPM_CONFIG_REGISTRY")).toBe(true);
+    expect(isReservedEnvKey("NODE_PATH")).toBe(true);
+    expect(isReservedEnvKey("NODE_TLS_REJECT_UNAUTHORIZED")).toBe(true);
+  });
+  test("legitimate API key style is NOT blocked", () => {
+    for (const k of ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "TELEGRAM_BOT_TOKEN", "DEEPSEEK_API_KEY", "MY_APP_CONFIG"]) {
+      expect(isReservedEnvKey(k)).toBe(false);
+    }
+  });
+  test("set shape sanity — both EXACT and PREFIX non-empty + frozen-ish", () => {
+    expect(RESERVED_ENV_KEYS_EXACT.size).toBeGreaterThan(10);
+    expect(RESERVED_ENV_PREFIXES.length).toBeGreaterThan(3);
+  });
+});

package/src/shared/reserved-env.ts

@@ -0,0 +1,31 @@
+// RFC-026 v4 §4.4.7 B1 — reserved env-key denylist (single source of
+// truth for hub + daemon).
+//
+// Scope: env_refs naming a system/process-model sensitive key (PATH /
+// LD_PRELOAD / NODE_OPTIONS / BUN_* / NPM_* / ...) MUST be rejected
+// before the secret value ever reaches fork(), because such a key in
+// the child env is effectively arbitrary code execution.
+//
+// G9 (drift guard): this module is the ONE source. Daemon-side runtime
+// imports the same constants. A divergence between hub and daemon would
+// let attacker target the looser layer; CI test asserts set equality.
+
+export const RESERVED_ENV_KEYS_EXACT = new Set<string>([
+  "PATH", "HOME", "LANG", "LC_ALL", "SHELL", "USER", "LOGNAME",
+  "NODE_OPTIONS", "IFS", "PS1", "PS4", "ENV", "BASH_ENV",
+  "CDPATH", "PROMPT_COMMAND", "TMPDIR",
+]);
+
+// Prefix-match denied. Order matters only for clarity (LD_ catches
+// LD_PRELOAD / LD_LIBRARY_PATH / LD_AUDIT; DYLD_ catches DYLD_INSERT_
+// LIBRARIES; BUN_ / NPM_ / NPM_CONFIG_ / NODE_ catch ecosystem-level
+// runtime config).
+export const RESERVED_ENV_PREFIXES: ReadonlyArray<string> = [
+  "LD_", "DYLD_", "BUN_", "NPM_", "NPM_CONFIG_", "NODE_",
+];
+
+export function isReservedEnvKey(k: string): boolean {
+  if (RESERVED_ENV_KEYS_EXACT.has(k)) return true;
+  for (const p of RESERVED_ENV_PREFIXES) if (k.startsWith(p)) return true;
+  return false;
+}