@sleep2agi/commhub-server 0.9.0-preview.2 → 0.9.0-preview.21

package/src/probe-validate.test.ts

@@ -0,0 +1,221 @@
+// RFC-028 P1 §4.4 probe-validate tests — pure unit, no I/O.
+
+import { describe, expect, test } from "bun:test";
+import {
+  validateBaseUrl, isForbiddenIp, isLoopbackHost, assertSecureTlsEnv,
+  ProbeAckPayloadSchema, deriveErrorLabel, rejectIfSecretLeaked,
+  VENDOR_HOST_ALLOWLIST, SUPPORTED_VENDORS, ProbeValidationError,
+} from "./probe-validate.js";
+
+describe("validateBaseUrl (§4.4.1 vendor host allowlist)", () => {
+  test("anthropic + api.anthropic.com → ok", () => {
+    expect(() => validateBaseUrl("anthropic", "https://api.anthropic.com/v1")).not.toThrow();
+  });
+  test("anthropic + api.openai.com → probe_target_forbidden", () => {
+    expect(() => validateBaseUrl("anthropic", "https://api.openai.com/v1")).toThrow(/probe_target_forbidden/);
+  });
+  test("anthropic + 169.254.169.254 (metadata) → probe_target_forbidden (host不在 allowlist)", () => {
+    expect(() => validateBaseUrl("anthropic", "https://169.254.169.254/v1")).toThrow(/probe_target_forbidden/);
+  });
+  test("unsupported vendor → vendor_not_supported", () => {
+    expect(() => validateBaseUrl("openai", "https://api.openai.com/v1")).toThrow(/vendor_not_supported/);
+  });
+  test("non-https → probe_base_url_invalid", () => {
+    expect(() => validateBaseUrl("anthropic", "http://api.anthropic.com/v1")).toThrow(/probe_base_url_invalid/);
+  });
+  test("http+loopback OK with allowLoopback opt-in", () => {
+    expect(() => validateBaseUrl("anthropic", "http://localhost:8080/v1", { allowLoopback: true }))
+      .toThrow(/probe_target_forbidden/);   // 但 host 还是不在 allowlist, allowLoopback 只放过 protocol
+  });
+  test("malformed URL → probe_base_url_invalid", () => {
+    expect(() => validateBaseUrl("anthropic", "not a url")).toThrow(/probe_base_url_invalid/);
+  });
+  test("P1 SUPPORTED_VENDORS only contains anthropic", () => {
+    expect(SUPPORTED_VENDORS).toEqual(["anthropic"]);
+  });
+
+  // ── RFC-028 P1.5+ — Anthropic-compatible 3rd-party hosts on `anthropic` vendor.
+  // Whitelist semantics preserved; new entries require PR + security review.
+  // Host allowlist passes here; IP-level guard still fires at fetch time
+  // (covered by safelyFetchProbe + docker scenarios qa-rfc028 F + M.ssrf).
+  test("anthropic + api.deepseek.com → ok (Anthropic-compatible /v1/messages)", () => {
+    expect(() => validateBaseUrl("anthropic", "https://api.deepseek.com/v1")).not.toThrow();
+  });
+  test("anthropic + api.minimax.chat → ok (MiniMax legacy domain)", () => {
+    expect(() => validateBaseUrl("anthropic", "https://api.minimax.chat/v1")).not.toThrow();
+  });
+  test("anthropic + api.minimax.io → ok (MiniMax new domain, Vincent live)", () => {
+    expect(() => validateBaseUrl("anthropic", "https://api.minimax.io/v1")).not.toThrow();
+  });
+  test("subdomain of allowed host NOT accepted (regex anchored)", () => {
+    expect(() => validateBaseUrl("anthropic", "https://attacker.api.deepseek.com/v1")).toThrow(/probe_target_forbidden/);
+    expect(() => validateBaseUrl("anthropic", "https://api.minimax.io.attacker.example/v1")).toThrow(/probe_target_forbidden/);
+  });
+  test("homograph / look-alike host rejected (regex anchored)", () => {
+    expect(() => validateBaseUrl("anthropic", "https://api.deepseek.com.attacker/v1")).toThrow(/probe_target_forbidden/);
+    expect(() => validateBaseUrl("anthropic", "https://api-deepseek.com/v1")).toThrow(/probe_target_forbidden/);
+  });
+  test("VENDOR_HOST_ALLOWLIST.anthropic curated list = exactly 4 entries", () => {
+    // Lock the curated set — adding a 5th host MUST go through a PR
+    // bump this assertion (forces conscious security review).
+    expect(VENDOR_HOST_ALLOWLIST.anthropic.length).toBe(4);
+    const sources = VENDOR_HOST_ALLOWLIST.anthropic.map(r => r.source).sort();
+    expect(sources).toEqual([
+      "^api\\.anthropic\\.com$",
+      "^api\\.deepseek\\.com$",
+      "^api\\.minimax\\.chat$",
+      "^api\\.minimax\\.io$",
+    ]);
+  });
+});
+
+describe("isForbiddenIp (§4.4.2 private/reserved IP block — anti SSRF)", () => {
+  test("blocks IPv4 private + metadata + CGNAT", () => {
+    for (const ip of [
+      "10.0.0.1", "10.255.255.255",
+      "172.16.0.1", "172.31.255.255",
+      "192.168.1.1",
+      "127.0.0.1", "127.255.255.255",
+      "169.254.169.254",      // cloud metadata
+      "169.254.0.0",
+      "100.64.0.1", "100.127.255.254",   // CGNAT
+      "0.0.0.0",
+      "224.0.0.1",            // multicast
+      "240.0.0.1", "255.255.255.255",   // experimental/broadcast
+    ]) {
+      expect(isForbiddenIp(ip)).toBe(true);
+    }
+  });
+  test("allows public IPv4", () => {
+    for (const ip of ["1.1.1.1", "8.8.8.8", "104.16.0.1", "172.32.0.1", "172.15.255.254"]) {
+      expect(isForbiddenIp(ip)).toBe(false);
+    }
+  });
+  test("blocks IPv6 loopback + link-local + ULA", () => {
+    for (const ip of ["::1", "::", "fe80::1", "fc00::1", "fd00::1"]) {
+      expect(isForbiddenIp(ip)).toBe(true);
+    }
+  });
+  test("blocks IPv4-mapped IPv6 (anti绕)", () => {
+    expect(isForbiddenIp("::ffff:10.0.0.1")).toBe(true);
+    expect(isForbiddenIp("::ffff:169.254.169.254")).toBe(true);
+    expect(isForbiddenIp("::FFFF:127.0.0.1")).toBe(true);
+  });
+  test("allows public IPv6", () => {
+    expect(isForbiddenIp("2606:4700:4700::1111")).toBe(false);
+    expect(isForbiddenIp("2001:4860:4860::8888")).toBe(false);
+  });
+});
+
+describe("isLoopbackHost", () => {
+  test("recognizes localhost/127.0.0.1/::1", () => {
+    expect(isLoopbackHost("localhost")).toBe(true);
+    expect(isLoopbackHost("127.0.0.1")).toBe(true);
+    expect(isLoopbackHost("::1")).toBe(true);
+    expect(isLoopbackHost("api.example.com")).toBe(false);
+  });
+});
+
+describe("assertSecureTlsEnv (§4.4 boot guard)", () => {
+  test("clean env passes", () => {
+    expect(() => assertSecureTlsEnv({})).not.toThrow();
+  });
+  test("NODE_TLS_REJECT_UNAUTHORIZED=0 throws probe_tls_insecure_disabled", () => {
+    expect(() => assertSecureTlsEnv({ NODE_TLS_REJECT_UNAUTHORIZED: "0" }))
+      .toThrow(/probe_tls_insecure_disabled/);
+  });
+  test("NODE_TLS_REJECT_UNAUTHORIZED=1 passes (default safe)", () => {
+    expect(() => assertSecureTlsEnv({ NODE_TLS_REJECT_UNAUTHORIZED: "1" })).not.toThrow();
+  });
+});
+
+describe("ProbeAckPayloadSchema (§4.4.4 v3 R3 strict whitelist)", () => {
+  test("minimal valid payload parses", () => {
+    const ok = { probe_id: "p_1", status: "ok", latency_ms: 180 };
+    expect(ProbeAckPayloadSchema.parse(ok)).toEqual(ok);
+  });
+  test("with raw_status_code parses", () => {
+    const r = ProbeAckPayloadSchema.parse({ probe_id: "p_2", status: "auth_fail", raw_status_code: 401, latency_ms: 50 });
+    expect(r.raw_status_code).toBe(401);
+  });
+  test("REJECTS extra error_message field (zod .strict, v3 R3 attacker daemon catch)", () => {
+    expect(() => ProbeAckPayloadSchema.parse({
+      probe_id: "p_3", status: "auth_fail", latency_ms: 50,
+      error_message: "Invalid API key: sk-ant-abc",   // ← attacker smuggling
+    })).toThrow();
+  });
+  test("REJECTS extra response_body / response_headers / url / vendor_text", () => {
+    for (const extra of [
+      { response_body: "..." },
+      { response_headers: { foo: "bar" } },
+      { url: "https://leak" },
+      { vendor_text: "leak" },
+      { error: "leak" },
+      { detail: "leak" },
+    ]) {
+      expect(() => ProbeAckPayloadSchema.parse({
+        probe_id: "p", status: "ok", latency_ms: 1,
+        ...extra,
+      })).toThrow();
+    }
+  });
+  test("REJECTS bad enum status", () => {
+    expect(() => ProbeAckPayloadSchema.parse({ probe_id: "p", status: "bogus", latency_ms: 1 })).toThrow();
+  });
+  test("REJECTS latency_ms > 60_000 or negative", () => {
+    expect(() => ProbeAckPayloadSchema.parse({ probe_id: "p", status: "ok", latency_ms: 60_001 })).toThrow();
+    expect(() => ProbeAckPayloadSchema.parse({ probe_id: "p", status: "ok", latency_ms: -1 })).toThrow();
+  });
+});
+
+describe("deriveErrorLabel (hub-only, daemon CANNOT submit)", () => {
+  test("ok → null", () => {
+    expect(deriveErrorLabel({ probe_id: "p", status: "ok", latency_ms: 10 })).toBeNull();
+  });
+  test("auth_fail with code → label includes HTTP code", () => {
+    expect(deriveErrorLabel({ probe_id: "p", status: "auth_fail", raw_status_code: 401, latency_ms: 10 }))
+      .toContain("401");
+  });
+  test("every enum has a label or null", () => {
+    for (const status of ["ok", "auth_fail", "quota", "rate_limit", "network_error", "timeout", "redirect_forbidden", "vendor_5xx", "other_4xx", "tls_error"] as const) {
+      const r = deriveErrorLabel({ probe_id: "p", status, latency_ms: 1 });
+      expect(typeof r === "string" || r === null).toBe(true);
+    }
+  });
+});
+
+describe("rejectIfSecretLeaked (§4.4.4 belt-and-suspenders)", () => {
+  test("clean ack passes", () => {
+    expect(() => rejectIfSecretLeaked(
+      JSON.stringify({ probe_id: "p", status: "ok" }),
+      ["sk-very-long-secret-1234567890"],
+    )).not.toThrow();
+  });
+  test("ack containing raw secret → ack_secret_leak (plain)", () => {
+    expect(() => rejectIfSecretLeaked(
+      JSON.stringify({ probe_id: "p", status: "fail", x: "sk-very-long-secret-1234567890" }),
+      ["sk-very-long-secret-1234567890"],
+    )).toThrow(/ack_secret_leak/);
+  });
+  test("ack containing URL-encoded secret → ack_secret_leak (url_encoded)", () => {
+    const secret = "sk/with+special=chars/here-long-enough";
+    const enc = encodeURIComponent(secret);
+    expect(() => rejectIfSecretLeaked(
+      JSON.stringify({ probe_id: "p", url: `https://x/?key=${enc}` }),
+      [secret],
+    )).toThrow(/ack_secret_leak/);
+  });
+  test("ack containing 12-char substring of long secret → ack_secret_leak (substring_12)", () => {
+    const secret = "sk-ant-api03-very-long-key-1234567890-abcdef";
+    expect(() => rejectIfSecretLeaked(
+      JSON.stringify({ probe_id: "p", x: "leak prefix sk-ant-api03 here" }),
+      [secret],
+    )).toThrow(/ack_secret_leak/);
+  });
+  test("short secret (<8) not checked (avoid false positive on tiny tokens)", () => {
+    expect(() => rejectIfSecretLeaked(
+      JSON.stringify({ probe_id: "p", x: "test" }),
+      ["test"],
+    )).not.toThrow();
+  });
+});

package/src/probe-validate.ts

@@ -0,0 +1,104 @@
+// RFC-028 P1 §4.4 — probe path validators (pure, no I/O).
+// Host allowlist + IP block + validateBaseUrl extracted into
+// shared/probe-host-allowlist.ts (mirror of agent-node/src/shared/, G9
+// drift guard enforces byte-identical). This module re-exports them so
+// existing hub call sites keep working, and adds hub-only bits:
+// PROBE_STATUS_ENUM + ProbeAckPayloadSchema + deriveErrorLabel +
+// rejectIfSecretLeaked + assertSecureTlsEnv.
+
+import { z } from "zod/v4";
+export {
+  VENDOR_HOST_ALLOWLIST,
+  SUPPORTED_VENDORS,
+  ProbeValidationError,
+  validateBaseUrl,
+  isLoopbackHost,
+  isForbiddenIp,
+} from "./shared/probe-host-allowlist.js";
+import { ProbeValidationError } from "./shared/probe-host-allowlist.js";
+
+// ── §4.4.5 boot-time TLS env guard (assert before any probe runs) ──
+
+export function assertSecureTlsEnv(env: NodeJS.ProcessEnv = process.env): void {
+  if (env.NODE_TLS_REJECT_UNAUTHORIZED === "0") {
+    throw new ProbeValidationError("probe_tls_insecure_disabled", {
+      reason: "NODE_TLS_REJECT_UNAUTHORIZED=0 forbidden — TLS cert validation must be ON for SSRF defense",
+    });
+  }
+}
+
+// ── §4.4.4 ProbeAckPayload — STRICT whitelist (v3 R3) ─────────────
+// Daemon ack returns ONLY these fields. Any extra string is dropped
+// at the zod parse boundary. Hub additionally runs rejectIfSecretLeaked
+// (defense in depth).
+
+export const PROBE_STATUS_ENUM = [
+  "ok",
+  "auth_fail",
+  "quota",
+  "rate_limit",
+  "network_error",
+  "timeout",
+  "redirect_forbidden",
+  "vendor_5xx",
+  "other_4xx",
+  "tls_error",
+  // SSRF guards surface their own statuses so dashboard can show the
+  // exact reason; deriveErrorLabel maps to UI text.
+  "probe_resolve_unsafe_ip",
+  "probe_target_forbidden",
+] as const;
+export type ProbeStatus = typeof PROBE_STATUS_ENUM[number];
+
+export const ProbeAckPayloadSchema = z.object({
+  probe_id: z.string().min(1).max(200),
+  status: z.enum(PROBE_STATUS_ENUM),
+  raw_status_code: z.number().int().min(100).max(599).optional(),
+  latency_ms: z.number().int().min(0).max(60_000),
+}).strict();   // .strict() rejects ANY extra field — error_message / response_body / etc smuggled by attacker daemon
+export type ProbeAckPayload = z.infer<typeof ProbeAckPayloadSchema>;
+
+/** Hub-side: map (status, raw_status_code) → human label.
+ *  daemon NEVER submits this; hub computes from enum + numeric. */
+export function deriveErrorLabel(ack: ProbeAckPayload): string | null {
+  switch (ack.status) {
+    case "ok":                   return null;
+    case "auth_fail":            return `API key 校验失败 (HTTP ${ack.raw_status_code ?? "?"})`;
+    case "quota":                return "API 额度用尽 (429)";
+    case "rate_limit":           return "我方 rate limit (60req/min/provider) 触发";
+    case "network_error":        return "网络不可达 (connect/DNS fail)";
+    case "timeout":              return "连通性测试超时 (>30s)";
+    case "redirect_forbidden":   return "vendor 返回 30x redirect, P1 一律拒";
+    case "vendor_5xx":           return `vendor 服务端错 (HTTP ${ack.raw_status_code ?? "5xx"})`;
+    case "other_4xx":            return `vendor 客户端错 (HTTP ${ack.raw_status_code ?? "4xx"})`;
+    case "tls_error":            return "TLS 证书校验失败";
+    case "probe_resolve_unsafe_ip": return "SSRF 拒: base_url 解析到禁用 IP 段 (私网/metadata)";
+    case "probe_target_forbidden":  return "SSRF 拒: base_url host 不在 vendor allowlist";
+  }
+}
+
+// ── §4.4.4 hub-side belt: reject if daemon ack contains a secret ──
+// Even though daemon ack schema (zod .strict()) blocks string fields,
+// this guard catches a daemon impl bug that smuggles secrets via
+// some other means (e.g. probe_id stuffed with key value).
+// Checks plaintext + URL-encoded + 12-char sliding window substring.
+
+export function rejectIfSecretLeaked(ackJson: string, knownSecrets: ReadonlyArray<string>): void {
+  for (const s of knownSecrets) {
+    if (!s || s.length < 8) continue;  // avoid false positive on tiny tokens
+    if (ackJson.includes(s)) {
+      throw new ProbeValidationError("ack_secret_leak", { reason: "plain", len: s.length });
+    }
+    const enc = encodeURIComponent(s);
+    if (enc !== s && ackJson.includes(enc)) {
+      throw new ProbeValidationError("ack_secret_leak", { reason: "url_encoded", len: s.length });
+    }
+    if (s.length >= 16) {
+      for (let i = 0; i <= s.length - 12; i++) {
+        if (ackJson.includes(s.slice(i, i + 12))) {
+          throw new ProbeValidationError("ack_secret_leak", { reason: "substring_12", offset: i });
+        }
+      }
+    }
+  }
+}

package/src/probe.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test, beforeEach } from "bun:test";
+import {
+  putPendingProbeSecret,
+  takePendingProbeSecret,
+  peekPendingProbeSecret,
+  evictExpiredProbeSecrets,
+  stopBackgroundProbeTimersForTest,
+  type PendingProbeSecret,
+} from "./probe.js";
+
+// RFC-028 P1 fold-in #4 — takePendingProbeSecret 4-case unit. Mirrors
+// RFC-026 §4.4 takePendingEnvBlob unit pattern. This is the C2 cross-
+// daemon guard for probes: a daemon-X that intercepts a probe_id minted
+// for daemon-Y must NOT be able to consume it. Wrong-caller branch must
+// NOT evict (so the right daemon can still consume in TTL).
+
+function mkSecret(over: Partial<PendingProbeSecret> = {}): Omit<PendingProbeSecret, "expires_at"> {
+  return {
+    probe_id: over.probe_id ?? "pr_test_1",
+    daemon_node_id: over.daemon_node_id ?? "node_daemon_alpha",
+    provider_id: over.provider_id ?? "prov_1",
+    vendor: over.vendor ?? "anthropic",
+    base_url: over.base_url ?? "https://api.anthropic.com",
+    model_name: over.model_name ?? "claude-opus-test",
+    api_key: over.api_key ?? "sk-secret-not-leaked",
+    network_id: over.network_id ?? "net_1",
+  };
+}
+
+describe("RFC-028 P1 — takePendingProbeSecret 4-case", () => {
+  beforeEach(() => stopBackgroundProbeTimersForTest());
+
+  test("case 1: happy path — right daemon, within TTL → returns + evicts", () => {
+    putPendingProbeSecret(mkSecret({ probe_id: "pr_happy" }));
+    expect(peekPendingProbeSecret("pr_happy")).not.toBeNull();
+    const out = takePendingProbeSecret("pr_happy", "node_daemon_alpha");
+    expect(out).not.toBeNull();
+    expect(out!.api_key).toBe("sk-secret-not-leaked");
+    // Evicted on success → second take returns null
+    expect(takePendingProbeSecret("pr_happy", "node_daemon_alpha")).toBeNull();
+    expect(peekPendingProbeSecret("pr_happy")).toBeNull();
+  });
+
+  test("case 2: wrong daemon → returns null AND does NOT evict (right daemon can still consume)", () => {
+    putPendingProbeSecret(mkSecret({ probe_id: "pr_wrongcaller", daemon_node_id: "node_daemon_alpha" }));
+    // attacker daemon tries to consume
+    const wrong = takePendingProbeSecret("pr_wrongcaller", "node_daemon_attacker");
+    expect(wrong).toBeNull();
+    // entry MUST still be there — peek confirms (this is the C2 invariant:
+    // a wrong-caller probe cannot DoS the legitimate one by triggering eviction)
+    const peeked = peekPendingProbeSecret("pr_wrongcaller");
+    expect(peeked).not.toBeNull();
+    expect(peeked!.daemon_node_id).toBe("node_daemon_alpha");
+    // right daemon STILL gets it
+    const right = takePendingProbeSecret("pr_wrongcaller", "node_daemon_alpha");
+    expect(right).not.toBeNull();
+    expect(right!.api_key).toBe("sk-secret-not-leaked");
+  });
+
+  test("case 3: not found → returns null (no side-effect)", () => {
+    const out = takePendingProbeSecret("pr_nonexistent", "node_daemon_alpha");
+    expect(out).toBeNull();
+    // also confirm peek is null
+    expect(peekPendingProbeSecret("pr_nonexistent")).toBeNull();
+  });
+
+  test("case 4: expired → returns null + evicts (so memory doesn't accumulate)", async () => {
+    // Use evictExpiredProbeSecrets's now-arg surrogate: put a fresh entry then
+    // ask take with a time-shifted view by mutating the map. Since the public
+    // API doesn't expose expires_at directly, we use the sweeper to verify
+    // expired entries get cleaned, then assert take returns null.
+    putPendingProbeSecret(mkSecret({ probe_id: "pr_expired" }));
+    // Sweep with a forced "now" 120s in the future → past TTL_MS (60s)
+    const n = evictExpiredProbeSecrets(Date.now() + 120_000);
+    expect(n).toBeGreaterThanOrEqual(1);
+    // Now any take must return null + the entry is gone
+    expect(takePendingProbeSecret("pr_expired", "node_daemon_alpha")).toBeNull();
+    expect(peekPendingProbeSecret("pr_expired")).toBeNull();
+  });
+});

package/src/probe.ts

@@ -0,0 +1,200 @@
+// RFC-028 P1 §2.5 — hub-side probe state (pendingProbeSecrets Map +
+// orphan revoke sweeper + finalize helper). MCP tools register in
+// tools.ts (calls into here).
+//
+// Mirrors RFC-026 §4.4 mint-stream-evict pattern:
+//  - hub creates probe row (metadata only) + stashes decrypted secret
+//    + child fetcher params in in-memory Map (TTL 60s)
+//  - daemon get_probe_request takes (one-shot consume + evict)
+//  - daemon ack_probe_request → hub deriveErrorLabel + final row write
+//  - sweeper revokes orphan rows + tokens (P2 not needed since probe
+//    doesn't mint long-lived tokens — short-window only)
+
+import { db, uuidv4 } from "./db.js";
+import { vaultGet, VaultError } from "./vault.js";
+import {
+  validateBaseUrl, deriveErrorLabel, rejectIfSecretLeaked,
+  ProbeAckPayloadSchema, type ProbeAckPayload,
+  ProbeValidationError,
+} from "./probe-validate.js";
+
+// ── Probe ephemeral state Map (F1 mint-stream-evict, RFC-028 §2.5) ──
+
+export interface PendingProbeSecret {
+  probe_id: string;
+  daemon_node_id: string;          // C2 cross-daemon guard
+  provider_id: string;
+  vendor: string;
+  base_url: string;
+  model_name: string;
+  api_key: string;                  // plaintext, ephemeral, never persisted
+  network_id: string;
+  expires_at: number;
+}
+
+const TTL_MS = 60_000;
+const SWEEPER_INTERVAL_MS = 30_000;
+const REAPER_TTL_MS = 60_000;
+
+const pendingProbeSecrets = new Map<string, PendingProbeSecret>();
+let _gcTimer: ReturnType<typeof setInterval> | null = null;
+let _sweeperTimer: ReturnType<typeof setInterval> | null = null;
+
+export function putPendingProbeSecret(b: Omit<PendingProbeSecret, "expires_at">): void {
+  pendingProbeSecrets.set(b.probe_id, { ...b, expires_at: Date.now() + TTL_MS });
+}
+
+/** Caller-bound one-shot consume. Returns null if not found, wrong
+ *  daemon, or expired; entry deleted on success. */
+export function takePendingProbeSecret(probe_id: string, callerDaemonNodeId: string): PendingProbeSecret | null {
+  const b = pendingProbeSecrets.get(probe_id);
+  if (!b) return null;
+  if (b.daemon_node_id !== callerDaemonNodeId) return null;   // wrong-caller probe: DON'T evict
+  if (Date.now() > b.expires_at) { pendingProbeSecrets.delete(probe_id); return null; }
+  pendingProbeSecrets.delete(probe_id);
+  return b;
+}
+
+export function peekPendingProbeSecret(probe_id: string): PendingProbeSecret | null {
+  return pendingProbeSecrets.get(probe_id) || null;
+}
+
+export function evictExpiredProbeSecrets(now = Date.now()): number {
+  let n = 0;
+  for (const [k, v] of pendingProbeSecrets) {
+    if (now > v.expires_at) { pendingProbeSecrets.delete(k); n++; }
+  }
+  return n;
+}
+
+export function startPendingProbeGcTimer(): void {
+  if (_gcTimer) return;
+  _gcTimer = setInterval(() => {
+    const n = evictExpiredProbeSecrets();
+    if (n > 0) console.log(`[probe] GC: evicted ${n} expired probe secret(s)`);
+  }, 5_000);
+  (_gcTimer as any).unref?.();
+}
+
+export function stopBackgroundProbeTimersForTest(): void {
+  if (_gcTimer) { clearInterval(_gcTimer); _gcTimer = null; }
+  if (_sweeperTimer) { clearInterval(_sweeperTimer); _sweeperTimer = null; }
+  pendingProbeSecrets.clear();
+}
+
+// ── Sweeper: terminal-transition probe_results rows that never got ack ──
+// Mirrors RFC-026 §4.4.8 — probe rows older than REAPER_TTL_MS that
+// are still status='pending' get marked timeout + error_label set.
+
+export function runOrphanProbeSweepOnce(now = Date.now()): { swept: number } {
+  const cutoffMs = now - REAPER_TTL_MS;
+  const stale = db.all<{ probe_id: string }>(
+    `SELECT probe_id FROM probe_results WHERE status = 'pending' AND probed_at < ?1`,
+    cutoffMs,
+  );
+  if (stale.length === 0) return { swept: 0 };
+
+  let swept = 0;
+  try {
+    db.exec("BEGIN");
+    for (const row of stale) {
+      db.run(
+        `UPDATE probe_results SET status = ?1, error_label = ?2 WHERE probe_id = ?3 AND status = 'pending'`,
+        ["timeout", "连通性测试超时 (sweeper: 60s 无 daemon ack)", row.probe_id],
+      );
+      pendingProbeSecrets.delete(row.probe_id);
+      swept++;
+    }
+    db.exec("COMMIT");
+  } catch (e: any) {
+    try { db.exec("ROLLBACK"); } catch { /* ok */ }
+    console.warn(`[probe] sweeper failed: ${e?.message || e}`);
+    return { swept: 0 };
+  }
+  if (swept > 0) console.log(`[commhub] ✓ probe sweeper: swept ${swept} stale probe(s)`);
+  return { swept };
+}
+
+export function startProbeSweeperTimer(): void {
+  if (_sweeperTimer) return;
+  try { runOrphanProbeSweepOnce(); }
+  catch (e: any) { console.warn(`[probe] boot sweeper failed: ${e?.message || e}`); }
+  _sweeperTimer = setInterval(() => {
+    try { runOrphanProbeSweepOnce(); }
+    catch (e: any) { console.warn(`[probe] periodic sweeper failed: ${e?.message || e}`); }
+  }, SWEEPER_INTERVAL_MS);
+  (_sweeperTimer as any).unref?.();
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+export function newProbeId(): string {
+  return `pr_${uuidv4()}`;
+}
+
+/** Hub-side: receive daemon ack, validate, redact, derive label, write
+ *  final row. Returns the persisted row OR throws ProbeValidationError. */
+export function finalizeProbeAck(
+  rawAck: unknown,
+  caller: { network_id: string; daemon_node_id: string },
+): { ok: boolean; error_label: string | null; status: string } {
+  // 1. Schema parse — rejects extra fields via .strict()
+  const ack = ProbeAckPayloadSchema.parse(rawAck);
+  // 2. Pull the row (existence + caller binding)
+  const row = db.get<{ probe_id: string; daemon_node_id: string; provider_id: string; status: string }>(
+    `SELECT probe_id, daemon_node_id, provider_id, status FROM probe_results WHERE probe_id = ?1`,
+    ack.probe_id,
+  );
+  if (!row) throw new ProbeValidationError("probe_not_found", { probe_id: ack.probe_id });
+  if (row.daemon_node_id !== caller.daemon_node_id) {
+    throw new ProbeValidationError("not_your_probe", { probe_id: ack.probe_id });
+  }
+  if (row.status !== "pending") {
+    throw new ProbeValidationError("probe_not_pending", { current_status: row.status });
+  }
+  // 3. Belt-and-suspenders secret-leak guard on full ack JSON
+  //    (catches daemon impl bug stuffing secret into probe_id etc.)
+  try {
+    const providerRow = db.get<{ secret_key_ref: string }>(
+      `SELECT secret_key_ref FROM providers WHERE provider_id = ?1 AND network_id = ?2`,
+      row.provider_id, caller.network_id,
+    );
+    if (providerRow) {
+      const secretVal = vaultGet(caller.network_id, providerRow.secret_key_ref);
+      if (secretVal) {
+        rejectIfSecretLeaked(JSON.stringify(ack), [secretVal]);
+      }
+    }
+  } catch (e) {
+    if (e instanceof ProbeValidationError && e.code === "ack_secret_leak") {
+      // audit-log this serious event (impl pattern below in tools.ts)
+      console.warn(`[probe] ack_secret_leak: daemon=${caller.daemon_node_id} probe=${ack.probe_id} reason=${JSON.stringify(e.detail)}`);
+      // mark row as failed for safety
+      db.run(
+        `UPDATE probe_results SET status = 'tls_error', error_label = ?1 WHERE probe_id = ?2 AND status = 'pending'`,
+        ["内部安全异常: daemon ack 含 secret 值, 已拒并 audit", ack.probe_id],
+      );
+      throw e;
+    }
+    // VaultError (missing key etc.) — non-fatal, skip leak guard but log
+    if (e instanceof VaultError) {
+      console.warn(`[probe] leak-guard skipped (vault read failed): ${e.message}`);
+    } else {
+      throw e;
+    }
+  }
+
+  // 4. Derive error_label from enum + raw_status_code
+  const label = deriveErrorLabel(ack);
+  // 5. Final write
+  db.run(
+    `UPDATE probe_results
+       SET status = ?1, latency_ms = ?2, raw_status_code = ?3, error_label = ?4
+     WHERE probe_id = ?5 AND status = 'pending'`,
+    [ack.status, ack.latency_ms, ack.raw_status_code ?? null, label, ack.probe_id],
+  );
+  return { ok: true, status: ack.status, error_label: label };
+}
+
+// Re-export validate funcs for tools.ts convenience
+export { validateBaseUrl, ProbeValidationError };

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));
+  });
+});