@sleep2agi/commhub-server 0.9.0-preview.4 → 0.9.0-preview.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.4",
+  "version": "0.9.0-preview.6",
   "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/api-nodes-shape.test.ts

@@ -29,8 +29,23 @@ afterAll(() => {
   try { db.run("DELETE FROM nodes WHERE node_id = ?1", [TEST_NODE]); } catch {}
 });
 
+// Helper: mirror handler's role-extraction pass to mimic the production
+// response shape exactly. Keeps the test the source of truth for the
+// contract; if the handler changes, the assertions still lock what
+// the dashboard / external clients see.
+function mapRow(r: Record<string, unknown>): Record<string, unknown> {
+  let role: string | null = null;
+  const snap = r.config_snapshot;
+  if (snap) {
+    try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
+    catch { /* malformed */ }
+  }
+  const { config_snapshot, ...rest } = r;
+  return { ...rest, role };
+}
+
 describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", () => {
-  test("explicit columns: internal config_revision/config_snapshot NOT in response", () => {
+  test("explicit columns + role extracted: config_snapshot NOT in response, role IS", () => {
     // Insert a row with the leak-prone columns populated. Use INSERT OR
     // REPLACE so concurrent test runs don't trip on PRIMARY KEY.
     db.run(
@@ -43,38 +58,101 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
        )`,
       [TEST_NODE, "test-shape", "test-shape", "claude-agent-sdk", "claude-opus",
        "/tmp/cfg.json", "[]", "localhost", "test-host", TEST_NETWORK,
-       7, JSON.stringify({ model: "claude-opus", flags: { x: true } })],
+       7, JSON.stringify({ model: "claude-opus", flags: { x: true }, role: "host_supervisor" })],
     );
 
-    // Run the same SQL the handler runs (mirror; if handler changes, this
-    // assertion still locks the shape).
-    const rows = db.all<Record<string, unknown>>(
+    // Mirror handler SQL + mapping
+    const raw = db.all<Record<string, unknown>>(
       `SELECT node_id, node_name, alias, runtime, model,
               config_path, channels, server, hostname,
-              network_id, created_at, updated_at
+              network_id, created_at, updated_at,
+              config_snapshot
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     );
+    const rows = raw.map(mapRow);
 
     expect(rows).toHaveLength(1);
     const row = rows[0]!;
-    // Expected fields present
+    // Expected fields present (13 = 12 contract + new role)
     for (const k of ["node_id", "node_name", "alias", "runtime", "model",
                      "config_path", "channels", "server", "hostname",
-                     "network_id", "created_at", "updated_at"]) {
+                     "network_id", "created_at", "updated_at", "role"]) {
       expect(row).toHaveProperty(k);
     }
-    // Internal fields NOT present (these are the leak the test guards against)
+    // Internal fields NOT present
     expect(row).not.toHaveProperty("config_revision");
     expect(row).not.toHaveProperty("config_snapshot");
-    // Belt: full key set is exactly the 12 contract fields
+    // role is EXTRACTED from config_snapshot JSON, not the raw blob
+    expect(row.role).toBe("host_supervisor");
+    // Belt: full key set is exactly the 13 contract fields
     expect(Object.keys(row).sort()).toEqual([
       "alias", "channels", "config_path", "created_at", "hostname",
-      "model", "network_id", "node_id", "node_name", "runtime",
+      "model", "network_id", "node_id", "node_name", "role", "runtime",
       "server", "updated_at",
     ]);
   });
 
+  test("role is null when config_snapshot is empty / missing / malformed", () => {
+    // Empty snapshot → null
+    db.run(
+      `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+       VALUES (?1, ?2, ?3, ?4, NULL)`,
+      [TEST_NODE, "test-shape", "test-shape", TEST_NETWORK],
+    );
+    let row = mapRow(db.get<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
+              server, hostname, network_id, created_at, updated_at, config_snapshot
+       FROM nodes WHERE node_id = ?1`,
+      TEST_NODE,
+    )!);
+    expect(row.role).toBeNull();
+    expect(row).not.toHaveProperty("config_snapshot");
+
+    // Malformed JSON → null (handler doesn't throw, just leaves role null)
+    db.run(`UPDATE nodes SET config_snapshot = ?1 WHERE node_id = ?2`, ["not-json{", TEST_NODE]);
+    row = mapRow(db.get<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
+              server, hostname, network_id, created_at, updated_at, config_snapshot
+       FROM nodes WHERE node_id = ?1`,
+      TEST_NODE,
+    )!);
+    expect(row.role).toBeNull();
+
+    // Snapshot without role key → null
+    db.run(`UPDATE nodes SET config_snapshot = ?1 WHERE node_id = ?2`,
+           [JSON.stringify({ model: "x", flags: {} }), TEST_NODE]);
+    row = mapRow(db.get<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
+              server, hostname, network_id, created_at, updated_at, config_snapshot
+       FROM nodes WHERE node_id = ?1`,
+      TEST_NODE,
+    )!);
+    expect(row.role).toBeNull();
+  });
+
+  test("daemon discovery use-case: dashboard finds role=host_supervisor without prefix heuristic", () => {
+    // Daemon registered with arbitrary node_id (NO `node_daemon_` prefix)
+    db.run(
+      `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+       VALUES (?1, ?2, ?3, ?4, ?5)`,
+      [TEST_NODE, "my-daemon", "my-daemon", TEST_NETWORK,
+       JSON.stringify({ role: "host_supervisor", runtime: "claude-agent-sdk" })],
+    );
+    const rows = db.all<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
+              server, hostname, network_id, created_at, updated_at, config_snapshot
+       FROM nodes WHERE network_id = ?1`,
+      TEST_NETWORK,
+    ).map(mapRow);
+    // Dashboard's lookup: find first node with role==='host_supervisor'
+    const daemon = rows.find(r => r.role === "host_supervisor");
+    expect(daemon).toBeTruthy();
+    expect(daemon!.node_id).toBe(TEST_NODE);
+    // Even though node_id does NOT start with `node_daemon_` (the prior heuristic)
+    expect(String(daemon!.node_id).startsWith("node_daemon_")).toBe(false);
+  });
+
   test("internal columns are still readable via dedicated query (config snapshot endpoint path)", () => {
     db.run(
       `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id,

package/src/db.ts

@@ -436,6 +436,76 @@ try {
   console.warn(`[commhub] partial unique index uniq_ncr_inflight skipped: ${e?.message || e}`);
 }
 
+// RFC-028 P1 v4 §2.2 — providers + provider_models + network_secrets +
+// probe_results. All 4 tables idempotent CREATE TABLE IF NOT EXISTS. F2
+// lazy gate: tables created on hub boot regardless; vault master key
+// (ANET_HUB_SECRET_VAULT_KEY env) only required when these tables get
+// their first non-empty row (lazy in vault.ts). Empty tables = hub
+// boots fine without env (critical for existing prod hub升级 不 brick).
+db.exec(`
+  CREATE TABLE IF NOT EXISTS providers (
+    provider_id     TEXT PRIMARY KEY,
+    network_id      TEXT NOT NULL,
+    name            TEXT NOT NULL,
+    vendor          TEXT NOT NULL,
+    base_url        TEXT NOT NULL,
+    secret_key_ref  TEXT NOT NULL,
+    created_at      INTEGER NOT NULL,
+    created_by      TEXT NOT NULL,
+    enabled         INTEGER NOT NULL DEFAULT 1,
+    UNIQUE(network_id, name)
+  );
+  CREATE INDEX IF NOT EXISTS idx_providers_network ON providers(network_id);
+`);
+db.exec(`
+  CREATE TABLE IF NOT EXISTS provider_models (
+    model_id        TEXT PRIMARY KEY,
+    provider_id     TEXT NOT NULL,
+    model_name      TEXT NOT NULL,
+    display_name    TEXT,
+    context_window  INTEGER,
+    supports_vision INTEGER NOT NULL DEFAULT 0,
+    enabled         INTEGER NOT NULL DEFAULT 1,
+    created_at      INTEGER NOT NULL,
+    UNIQUE(provider_id, model_name)
+  );
+  CREATE INDEX IF NOT EXISTS idx_models_provider ON provider_models(provider_id);
+`);
+// network_secrets — encrypted-at-rest vault. ciphertext + iv + tag are
+// AES-GCM output; plaintext NEVER touches this table. master key from
+// ANET_HUB_SECRET_VAULT_KEY env (lazy gate in vault.ts).
+db.exec(`
+  CREATE TABLE IF NOT EXISTS network_secrets (
+    network_id   TEXT NOT NULL,
+    key          TEXT NOT NULL,
+    ciphertext   BLOB NOT NULL,
+    iv           BLOB NOT NULL,
+    tag          BLOB NOT NULL,
+    created_at   INTEGER NOT NULL,
+    updated_at   INTEGER NOT NULL,
+    PRIMARY KEY (network_id, key)
+  );
+`);
+// probe_results — connectivity matrix history. v3 R3 lock: error_label
+// is HUB-DERIVED ONLY from (status, raw_status_code) — daemon CANNOT
+// submit arbitrary error string. status enum mirrors ProbeAckPayload.
+db.exec(`
+  CREATE TABLE IF NOT EXISTS probe_results (
+    probe_id        TEXT PRIMARY KEY,
+    provider_id     TEXT NOT NULL,
+    model_name      TEXT NOT NULL,
+    daemon_node_id  TEXT NOT NULL,
+    network_id      TEXT NOT NULL,
+    status          TEXT NOT NULL,
+    latency_ms      INTEGER,
+    error_label     TEXT,
+    probed_at       INTEGER NOT NULL,
+    probed_by_user  TEXT,
+    raw_status_code INTEGER
+  );
+  CREATE INDEX IF NOT EXISTS idx_probe_matrix ON probe_results(network_id, provider_id, model_name, daemon_node_id, probed_at DESC);
+`);
+
 // ── V3: audit_log table ──
 db.exec(`
   CREATE TABLE IF NOT EXISTS audit_log (

package/src/index.ts

@@ -1965,16 +1965,37 @@ Bun.serve({
     if (url.pathname === "/api/nodes") {
       const nodeId = url.searchParams.get("node_id");
       const alias = url.searchParams.get("alias");
+      // `config_snapshot` SELECTed ONLY to extract the daemon `role` field
+      // for dashboard discovery — full snapshot is NOT broadcast (would
+      // re-introduce the #312 SELECT * fragility). Mapping step pulls
+      // `role` out then drops `config_snapshot` from the response row.
       let sql = `SELECT node_id, node_name, alias, runtime, model,
                         config_path, channels, server, hostname,
-                        network_id, created_at, updated_at
+                        network_id, created_at, updated_at,
+                        config_snapshot
                  FROM nodes WHERE 1=1`;
       const params: any[] = [];
       sql = addNetworkScope(sql, params, restScope);
       if (nodeId) { sql += ` AND node_id = ?${params.length + 1}`; params.push(nodeId); }
       if (alias) { sql += ` AND alias = ?${params.length + 1}`; params.push(alias); }
       sql += " ORDER BY updated_at DESC";
-      const rows = db.all(sql, ...params);
+      const rawRows = db.all<Record<string, any>>(sql, ...params);
+      // Add a single new field `role: string | null` per row, extracted from
+      // config_snapshot JSON. Daemon nodes that posted role='host_supervisor'
+      // via report_status surface here; dashboard uses this for daemon
+      // discovery (replacing the prior `node_daemon_` prefix heuristic).
+      // RFC-026 P1 P2 §9 will supersede this REST proxy with the
+      // `list_host_supervisors` MCP tool.
+      const rows = rawRows.map(r => {
+        let role: string | null = null;
+        const snap = r.config_snapshot;
+        if (snap) {
+          try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
+          catch { /* malformed snapshot — leave role null */ }
+        }
+        const { config_snapshot, ...rest } = r;
+        return { ...rest, role };
+      });
       return withCors(req, Response.json({ ok: true, nodes: rows, count: rows.length }));
     }
 
@@ -2185,3 +2206,22 @@ console.log(`
 ║   Health: http://${HOST}:${PORT}/health               ║
 ╚══════════════════════════════════════════════════╝
 `);
+
+// RFC-028 P1 boot banner — vault key configuration status.
+// F2 invariant: hub MUST boot regardless of vault state. This is
+// banner-only (informational); errors are raised lazily at vault op
+// time. needsKeyToOp=true means the operator should set
+// ANET_HUB_SECRET_VAULT_KEY before vault/provider features will work.
+try {
+  const { vaultStatusForBoot } = await import("./vault.js");
+  const s = vaultStatusForBoot();
+  if (s.needsKeyToOp) {
+    console.warn("[rfc-028 vault] ⚠️  network_secrets/providers have data BUT ANET_HUB_SECRET_VAULT_KEY is unset — vault ops will throw vault_master_key_missing until you set the env. Generate one: `openssl rand -hex 32` (must match the key used at write time).");
+  } else if (s.configured) {
+    console.log(`[rfc-028 vault] master key configured (tables_have_data=${s.tablesHaveData})`);
+  } else {
+    console.log("[rfc-028 vault] master key not set + no vault rows — vault gating is lazy; boot OK. Set ANET_HUB_SECRET_VAULT_KEY when enabling provider/secret features.");
+  }
+} catch (e: any) {
+  console.warn(`[rfc-028 vault] boot banner skipped (${e?.message || e})`);
+}

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