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

package/src/node-attrs-validate.ts

@@ -0,0 +1,88 @@
+// Boundary validation for node DISPLAY attributes (display_name / team /
+// tags). Mirrors `avatar-validate.ts` in spirit: this is the only place
+// that decides what a client is allowed to store, and it trusts nothing.
+//
+// Two different postures on purpose:
+//
+//   display_name / team — SCALAR fields the user typed. A wrong TYPE here
+//     is a client bug, so it is REJECTED (400) rather than coerced: silently
+//     turning `{}` into "[object Object]" would persist garbage the user
+//     never typed and can't explain.
+//
+//   tags — a LIST. Same reasoning as the `channels` patch in tools.ts: the
+//     wire contract wants junk dropped instead of failing the whole request,
+//     so one fat-fingered entry from a dashboard doesn't 400 the save. Each
+//     element is narrowed independently (typeof → trim → length cap →
+//     dedup), so nothing non-string can reach the database.
+
+/** Max stored length of display_name / team. */
+export const MAX_ATTR_LEN = 120;
+/** Max stored length of a single tag. */
+export const MAX_TAG_LEN = 64;
+/** Max number of tags kept per node. */
+export const MAX_TAGS = 16;
+
+export type ScalarAttrResult =
+  | { ok: true; value: string | null }
+  | { ok: false; reason: string };
+
+/**
+ * Narrow an optional scalar display attribute.
+ *   undefined      → not part of this patch (caller leaves the column alone)
+ *   null / ""      → explicit clear
+ *   non-string     → rejected (never coerced)
+ *   over-long      → rejected (the user should see it, not silently lose text)
+ */
+export function validateScalarAttr(raw: unknown, field: string): ScalarAttrResult {
+  if (raw === undefined) return { ok: true, value: null };
+  if (raw === null) return { ok: true, value: null };
+  if (typeof raw !== "string") {
+    return { ok: false, reason: `${field} must be a string or null` };
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { ok: true, value: null };
+  if (trimmed.length > MAX_ATTR_LEN) {
+    return { ok: false, reason: `${field} exceeds ${MAX_ATTR_LEN} characters` };
+  }
+  // Control characters would corrupt any log line / table cell that renders
+  // the value; strip rather than reject (they are almost always a paste
+  // artefact, not user intent).
+  // eslint-disable-next-line no-control-regex
+  const clean = trimmed.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+  return { ok: true, value: clean.length > 0 ? clean : null };
+}
+
+/**
+ * Narrow an untrusted tags array. NEVER throws, never rejects the request:
+ * unusable entries are dropped. Returns the canonical list to store.
+ */
+export function narrowTags(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== "string") continue; // numbers/objects/arrays/null
+    // eslint-disable-next-line no-control-regex
+    const t = item.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+    if (t.length === 0) continue;
+    if (t.length > MAX_TAG_LEN) continue; // absurd entry — drop, don't truncate
+    const key = t.toLowerCase(); // case-fold for dedup, keep first spelling
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+    if (out.length >= MAX_TAGS) break;
+  }
+  return out;
+}
+
+/** Parse the stored tags column back into an array. Storage is JSON text;
+ *  anything unparseable (hand-edited DB, older format) reads as empty so a
+ *  dashboard can always `.map()` without a guard. */
+export function parseStoredTags(stored: unknown): string[] {
+  if (typeof stored !== "string" || stored.length === 0) return [];
+  try {
+    return narrowTags(JSON.parse(stored));
+  } catch {
+    return [];
+  }
+}

package/src/node-attrs.test.ts

@@ -0,0 +1,213 @@
+// Node display attributes — team / tags / display_name (Vincent 目标第 3 条).
+//
+// These are HUB-SIDE DISPLAY attributes. Following the `avatar_url` (#462)
+// precedent they are deliberately NOT part of the RFC-024 config-apply
+// pipeline: agent-node has nothing to consume, so pushing them through
+// config revision/ack would ring a doorbell for a field the node does not
+// understand and could wedge the config revision.
+//
+// They DO need concurrency protection (two dashboards editing the same
+// node), which `avatar_url` lacks. Hence a dedicated `attrs_revision` CAS
+// that is independent of `config_revision` — editing a tag must never bump
+// the node's *config* revision.
+//
+// Every test drives the REAL HTTP endpoint against a booted server, not a
+// helper: the contract under test is the wire shape + status codes.
+//
+// NOTE (test isolation): this file boots its own Bun.serve, same pattern as
+// uploads-http.test.ts / api-host-supervisors-fallback.test.ts. Those files
+// are per-file runs by design (single-process module-singleton conflict,
+// tracked in #434) — run this file on its own.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const tmpDb = join(mkdtempSync(join(tmpdir(), "anet-attrs-")), "commhub.db");
+process.env.COMMHUB_DB = tmpDb;
+const PORT = 23000 + Math.floor(Math.random() * 1500);
+process.env.PORT = String(PORT);
+process.env.HOST = "127.0.0.1";
+
+const { db } = await import("./db.js");
+const { issueUserToken } = await import("./auth.js");
+const { bootServer } = await import("./server.js");
+
+const BASE = `http://127.0.0.1:${PORT}`;
+const NET = "net_attrs";
+const USER = "u_attrs";
+/** A node row seeded the way a PRE-MIGRATION row looks: none of the new
+ *  columns are written, so they are NULL / default at read time. */
+const LEGACY_NODE = "node_attrs_legacy";
+const LEGACY_ALIAS = "attrs-legacy-node";
+
+let token = "";
+let server: { stop: (force?: boolean) => void } | null = null;
+
+beforeAll(async () => {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role) VALUES (?1, 'attrs-user', 'x', 'user')`, [USER]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id) VALUES (?1, 'attrs-net', ?2)`, [NET, USER]);
+  db.run(`INSERT INTO network_members (network_id, user_id, role) VALUES (?1, ?2, 'owner')`, [NET, USER]);
+  // Legacy row: only the columns that existed before this change.
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, runtime, model, network_id)
+     VALUES (?1, 'attrs-legacy', ?2, 'claude-agent-sdk', 'claude-sonnet-4-6', ?3)`,
+    [LEGACY_NODE, LEGACY_ALIAS, NET],
+  );
+  token = issueUserToken(USER, "attrs-test").token;
+  server = bootServer({ port: PORT, hostname: "127.0.0.1" }) as never;
+  await new Promise((r) => setTimeout(r, 120));
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch { /* already down */ }
+});
+
+async function putAttrs(ref: string, body: unknown) {
+  const res = await fetch(`${BASE}/api/nodes/${encodeURIComponent(ref)}/attrs?network_id=${NET}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, json: (await res.json()) as Record<string, unknown> };
+}
+
+async function listNodes() {
+  const res = await fetch(`${BASE}/api/nodes?network_id=${NET}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const j = (await res.json()) as { nodes?: Array<Record<string, unknown>> };
+  return j.nodes ?? [];
+}
+
+describe("node display attrs — backward compatibility with existing rows", () => {
+  test("a pre-migration node row still lists fine; new fields read as empty, not missing/throwing", async () => {
+    const rows = await listNodes();
+    const row = rows.find((r) => r.node_id === LEGACY_NODE);
+    expect(row).toBeDefined();
+    // Must not blow up and must not omit the keys — the dashboard reads
+    // them unconditionally.
+    expect(row!).toHaveProperty("display_name");
+    expect(row!).toHaveProperty("team");
+    expect(row!).toHaveProperty("tags");
+    expect(row!.display_name ?? null).toBeNull();
+    expect(row!.team ?? null).toBeNull();
+    // tags normalises to an empty array rather than null/undefined so the
+    // dashboard can `.map()` without a guard.
+    expect(row!.tags).toEqual([]);
+    expect(row!.attrs_revision).toBe(0);
+  });
+});
+
+describe("node display attrs — write then read back", () => {
+  test("PUT sets display_name/team/tags, bumps attrs_revision, and GET /api/nodes reflects it", async () => {
+    const w = await putAttrs(LEGACY_ALIAS, {
+      base_attrs_revision: 0,
+      display_name: "研发一号机",
+      team: "platform",
+      tags: ["prod", "gpu"],
+    });
+    expect(w.status).toBe(200);
+    expect(w.json.ok).toBe(true);
+    expect(w.json.attrs_revision).toBe(1);
+
+    const row = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(row.display_name).toBe("研发一号机");
+    expect(row.team).toBe("platform");
+    expect(row.tags).toEqual(["prod", "gpu"]);
+    expect(row.attrs_revision).toBe(1);
+  });
+
+  test("editing attrs does NOT touch config_revision (display vs config are separate revisions)", async () => {
+    const before = db.get<{ config_revision: number }>(
+      "SELECT config_revision FROM nodes WHERE node_id = ?1", LEGACY_NODE)!.config_revision ?? 0;
+    const w = await putAttrs(LEGACY_ALIAS, { base_attrs_revision: 1, team: "infra" });
+    expect(w.status).toBe(200);
+    const after = db.get<{ config_revision: number }>(
+      "SELECT config_revision FROM nodes WHERE node_id = ?1", LEGACY_NODE)!.config_revision ?? 0;
+    expect(after).toBe(before);
+  });
+
+  test("partial patch leaves untouched fields alone", async () => {
+    const row = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    // team was just changed to 'infra'; display_name/tags must survive.
+    expect(row.team).toBe("infra");
+    expect(row.display_name).toBe("研发一号机");
+    expect(row.tags).toEqual(["prod", "gpu"]);
+  });
+});
+
+describe("node display attrs — CAS concurrency guard", () => {
+  test("stale base_attrs_revision → 409 with the current revision, and NO write happens", async () => {
+    const before = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    const stale = await putAttrs(LEGACY_ALIAS, {
+      base_attrs_revision: 0, // deliberately stale
+      team: "should-not-land",
+    });
+    expect(stale.status).toBe(409);
+    expect(stale.json.ok).toBe(false);
+    expect(stale.json.error).toBe("attrs_revision_conflict");
+    expect(stale.json.current_attrs_revision).toBe(before.attrs_revision);
+
+    const after = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(after.team).toBe(before.team); // unchanged
+    expect(after.attrs_revision).toBe(before.attrs_revision);
+  });
+});
+
+describe("node display attrs — untrusted input is narrowed at the boundary", () => {
+  test("tags: non-strings dropped, blanks dropped, duplicates folded, count + length capped", async () => {
+    const cur = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!.attrs_revision as number;
+    const w = await putAttrs(LEGACY_ALIAS, {
+      base_attrs_revision: cur,
+      tags: [
+        "keep",
+        "keep", // duplicate
+        "  spaced  ", // trimmed
+        "",
+        "   ",
+        42,
+        null,
+        { evil: true },
+        ["nested"],
+        "x".repeat(200), // over-long → dropped or truncated, never stored raw
+      ],
+    });
+    expect(w.status).toBe(200);
+    const tags = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!.tags as string[];
+    expect(Array.isArray(tags)).toBe(true);
+    expect(tags).toContain("keep");
+    expect(tags).toContain("spaced");
+    // one "keep", no junk, nothing absurdly long
+    expect(tags.filter((t) => t === "keep")).toHaveLength(1);
+    expect(tags.every((t) => typeof t === "string" && t.length > 0 && t.length <= 64)).toBe(true);
+    expect(tags.some((t) => t.includes("evil") || t.includes("nested"))).toBe(false);
+  });
+
+  test("display_name/team: non-string values are rejected, not coerced", async () => {
+    const cur = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!.attrs_revision as number;
+    const bad = await putAttrs(LEGACY_ALIAS, { base_attrs_revision: cur, team: { not: "a string" } });
+    expect(bad.status).toBe(400);
+    expect(bad.json.ok).toBe(false);
+  });
+});
+
+describe("node display attrs — auth + scope", () => {
+  test("no token → 401, and the row is untouched", async () => {
+    const before = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    const res = await fetch(`${BASE}/api/nodes/${LEGACY_ALIAS}/attrs?network_id=${NET}`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ base_attrs_revision: before.attrs_revision, team: "hijack" }),
+    });
+    expect(res.status).toBe(401);
+    const after = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(after.team).toBe(before.team);
+  });
+
+  test("unknown node ref → 404", async () => {
+    const r = await putAttrs("no-such-node-ref", { base_attrs_revision: 0, team: "x" });
+    expect(r.status).toBe(404);
+  });
+});

package/src/observer-avatar-http.test.ts

@@ -0,0 +1,349 @@
+// #461 + #462 — HTTP integration tests against the real Bun.serve hub.
+//
+// Boots a PRIVATE server instance via the #434 seam (`bootServer({ port: 0 })`,
+// same signature as PR #438) and derives BASE from the actual bound port.
+// This keeps the suite alive in aggregate runs: `await import("./server.js")`
+// is a module-cache no-op when another file booted first, so relying on the
+// import side effect + own PORT env leaves every fetch ConnectionRefused
+// while the tests still "run" (通信龙 #461 review, finding 2). Gate:
+//   bun test src/uploads-http.test.ts src/observer-avatar-http.test.ts → 0 fail
+//
+// #461: GET /events/network/:id observer stream — membership auth incl.
+//       member-removal revocation, summary events for third-party traffic
+//       (REST dispatch + MCP send_reply), no content leakage.
+// #462: PUT /api/nodes/:ref/avatar + GET /api/nodes round trip — persistence,
+//       href normalization, XSS-shaped rejects, clear semantics, write gate.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { register, login, addNetworkMember, removeNetworkMember, createNetworkTokenForNode } from "./auth.js";
+import { registerTools } from "./tools.js";
+import { db } from "./db.js";
+
+const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-obs-avatar-db-")) + "/commhub.db";
+
+let BASE = "";
+let privateServer: any = null;
+
+let memberToken = "";
+let memberNetworkId = "";
+let memberUserId = "";
+let outsiderToken = "";
+let outsiderUserId = "";
+const TARGET_ALIAS = "obs-target-agent";
+const AVATAR_NODE_ID = "node_avatar_test_1";
+
+beforeAll(async () => {
+  // Kept for per-file runs launched without an external COMMHUB_DB (the
+  // documented contract still is to set it externally; see db-adapter.ts).
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || SERVER_DB;
+  process.env.HOST = "127.0.0.1";
+  // (#438 corrective: importing server.js is side-effect-free — no
+  // default instance, no PORT juggling; only the private bootServer
+  // instance below listens.)
+
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const pw = "BootstrapPw123Aa!";
+
+  const memberName = `obs_member_${suffix}`;
+  let r = register(memberName, pw, undefined, "seed");
+  if (!r.ok || !r.token) {
+    const lr = login(memberName, pw);
+    if (lr.token) { memberToken = lr.token; memberNetworkId = lr.network_id ?? ""; }
+  } else {
+    memberToken = r.token;
+    memberNetworkId = r.network_id ?? "";
+  }
+  expect(memberToken).toBeTruthy();
+  expect(memberNetworkId).toBeTruthy();
+  memberUserId = db.get<any>("SELECT user_id FROM users WHERE username = ?1", memberName)?.user_id ?? "";
+  expect(memberUserId).toBeTruthy();
+
+  const outsiderName = `obs_outsider_${suffix}`;
+  const r2 = register(outsiderName, pw, undefined, "seed");
+  if (r2.ok && r2.token) outsiderToken = r2.token;
+  expect(outsiderToken).toBeTruthy();
+  outsiderUserId = db.get<any>("SELECT user_id FROM users WHERE username = ?1", outsiderName)?.user_id ?? "";
+  expect(outsiderUserId).toBeTruthy();
+
+  // Target agent session in the member's network, freshly seen → online.
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'idle', ?3, datetime('now'), datetime('now'))`,
+    [`resume_${suffix}`, TARGET_ALIAS, memberNetworkId]
+  );
+
+  // Node row for the avatar round trip.
+  db.run(
+    `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, 'avatar-test-node', ?2, ?3, datetime('now'), datetime('now'))`,
+    [AVATAR_NODE_ID, TARGET_ALIAS, memberNetworkId]
+  );
+
+  // Private instance on an OS-assigned port — collision-free by
+  // construction (kernel-assigned).
+  const mod: any = await import("./server.js");
+  privateServer = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${privateServer.port}`;
+});
+
+afterAll(() => {
+  try { privateServer?.stop?.(true); } catch {}
+  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
+});
+
+function auth(token: string): Record<string, string> {
+  return { "Authorization": `Bearer ${token}` };
+}
+
+/** Read the next SSE data frame from a fetch Response, with timeout. */
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs = 3_000,
+): Promise<Record<string, any>> {
+  const decoder = new TextDecoder();
+  let buf = "";
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error(`no SSE frame within ${timeoutMs}ms`)), deadline - Date.now()),
+      ),
+    ]);
+    if (result.done) throw new Error("SSE stream ended unexpectedly");
+    buf += decoder.decode(result.value, { stream: true });
+    const sep = buf.indexOf("\n\n");
+    if (sep === -1) continue;
+    const rawFrame = buf.slice(0, sep);
+    buf = buf.slice(sep + 2);
+    const dataLine = rawFrame.split("\n").find((l) => l.startsWith("data: "));
+    if (!dataLine) continue;
+    return JSON.parse(dataLine.slice(6));
+  }
+  throw new Error(`no SSE frame within ${timeoutMs}ms`);
+}
+
+describe("#461 GET /events/network/:id — auth", () => {
+  test("anonymous → 401", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`);
+    expect(res.status).toBe(401);
+  });
+
+  test("non-member user token → 403", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(outsiderToken) });
+    expect(res.status).toBe(403);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(false);
+  });
+
+  test("member user token → SSE stream with observer connected frame", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(memberToken) });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type") || "").toContain("text/event-stream");
+    const reader = res.body!.getReader();
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.observer).toBe(true);
+    expect(connected.network_id).toBe(memberNetworkId);
+    await reader.cancel();
+  });
+
+  test("membership removal revokes observer access — ntok exploit repro (通信龙 review finding 1)", async () => {
+    // Exact repro of the review's exploit: add user C to network A, mint
+    // an ntok BOUND to A, remove C from A — the same live ntok must lose
+    // the stream. network_members IS the revocation mechanism because
+    // removeNetworkMember does not revoke the user's tokens; the old
+    // `!role && authCtx.networkId !== observedNetId` OR-form let the
+    // token's network binding bypass the membership check (utok would
+    // not catch this: its authCtx.networkId is null, so only ntok
+    // exercises the vulnerable branch — verified by stubbing the OR
+    // back in: THIS test goes red, the utok variants stay green).
+    const added = addNetworkMember(memberNetworkId, outsiderUserId, "member");
+    expect(added.ok).toBe(true);
+    const minted = createNetworkTokenForNode(outsiderUserId, memberNetworkId, "revocation-probe");
+    expect(minted.ok).toBe(true);
+    const ntok = minted.token!;
+    expect(ntok.startsWith("ntok_")).toBe(true);
+
+    const whileMember = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(ntok) });
+    expect(whileMember.status).toBe(200);
+    const reader = whileMember.body!.getReader();
+    expect((await readFrame(reader)).type).toBe("connected");
+    await reader.cancel();
+
+    const removed = removeNetworkMember(memberNetworkId, outsiderUserId);
+    expect(removed.ok).toBe(true);
+    // The review's failing probe: /events/network/A with the still-live
+    // network-bound token → must now be 403, not 200.
+    const afterRemoval = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(ntok) });
+    expect(afterRemoval.status).toBe(403);
+    // utok of the removed user is denied too.
+    const utokAfter = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(outsiderToken) });
+    expect(utokAfter.status).toBe(403);
+  });
+});
+
+describe("#461 observer receives third-party traffic summaries", () => {
+  test("REST /api/task dispatch → observer gets new_task summary, no content", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(memberToken) });
+    const reader = res.body!.getReader();
+    await readFrame(reader); // connected
+
+    const secret = `SECRET-TASK-CONTENT-${Date.now()}`;
+    const dispatch = await fetch(`${BASE}/api/task`, {
+      method: "POST",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ alias: TARGET_ALIAS, task: secret, priority: "high", from: "third-party-sender", network_id: memberNetworkId }),
+    });
+    expect([200, 202]).toContain(dispatch.status);
+    const dispatched = await dispatch.json() as any;
+    expect(dispatched.task_id).toBeTruthy();
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    expect(evt.task_id).toBe(dispatched.task_id);
+    expect(evt.from).toBe("third-party-sender");
+    expect(evt.to).toBe(TARGET_ALIAS);
+    // Online session was seeded → delivered; offline would report queued.
+    expect(evt.status).toBe("delivered");
+    expect(evt.priority).toBe("high");
+    expect(evt.network_id).toBe(memberNetworkId);
+    expect(evt.scope).toBe("network");
+    // The acceptance line: summary must NOT leak the task body.
+    expect(JSON.stringify(evt)).not.toContain(secret);
+    await reader.cancel();
+  });
+
+  test("MCP send_reply → observer gets new_reply summary, reply text NOT in frame", async () => {
+    // Drive the REAL registered MCP handler (same interception pattern as
+    // ack-create-request.test.ts) with the member's network enforced, and
+    // read the observer stream over real HTTP.
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(memberToken) });
+    const reader = res.body!.getReader();
+    await readFrame(reader); // connected
+
+    const tools: Record<string, (args: any) => Promise<any>> = {};
+    const mcp = new McpServer({ name: "test", version: "0" }) as any;
+    mcp.tool = (name: string, _desc: string, _schema: any, handler: any) => { tools[name] = handler; };
+    registerTools(mcp, undefined, memberNetworkId, memberUserId);
+    expect(typeof tools["send_reply"]).toBe("function");
+
+    const secret = `SECRET-REPLY-TEXT-${Date.now()}`;
+    const result = await tools["send_reply"]({
+      alias: TARGET_ALIAS,
+      text: secret,
+      status: "replied",
+      from_session: "reply-worker",
+    });
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.ok).toBe(true);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_reply");
+    expect(evt.from).toBe("reply-worker");
+    expect(evt.to).toBe(TARGET_ALIAS);
+    expect(evt.status).toBe("replied");
+    expect(evt.message_id).toBe(parsed.message_id);
+    expect(evt.network_id).toBe(memberNetworkId);
+    expect(JSON.stringify(evt)).not.toContain(secret);
+    await reader.cancel();
+  });
+});
+
+describe("#462 PUT /api/nodes/:ref/avatar + GET /api/nodes", () => {
+  test("set avatar → 200, GET /api/nodes returns it (cross-device persistence)", async () => {
+    const avatarUrl = "https://cdn.example.com/avatars/custom-1.png";
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: avatarUrl }),
+    });
+    expect(put.status).toBe(200);
+    const putBody = await put.json() as any;
+    expect(putBody.ok).toBe(true);
+    expect(putBody.avatar_url).toBe(avatarUrl);
+
+    const list = await fetch(`${BASE}/api/nodes?node_id=${AVATAR_NODE_ID}`, { headers: auth(memberToken) });
+    expect(list.status).toBe(200);
+    const listBody = await list.json() as any;
+    expect(listBody.ok).toBe(true);
+    const row = listBody.nodes.find((n: any) => n.node_id === AVATAR_NODE_ID);
+    expect(row).toBeTruthy();
+    expect(row.avatar_url).toBe(avatarUrl);
+    // #312 discipline still holds — internals must not leak.
+    expect("config_snapshot" in row).toBe(false);
+  });
+
+  test("markup-hostile chars are stored NORMALIZED (href), not raw (通信龙 review finding 3)", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: 'https://cdn.example.com/a"b.png' }),
+    });
+    expect(put.status).toBe(200);
+    const putBody = await put.json() as any;
+    expect(putBody.avatar_url).toBe("https://cdn.example.com/a%22b.png");
+    const row = db.get<any>("SELECT avatar_url FROM nodes WHERE node_id = ?1", AVATAR_NODE_ID);
+    expect(row.avatar_url).toBe("https://cdn.example.com/a%22b.png");
+    expect(row.avatar_url).not.toContain('"');
+  });
+
+  test("clear avatar with null → avatar_url null in list", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: null }),
+    });
+    expect(put.status).toBe(200);
+    const list = await fetch(`${BASE}/api/nodes?node_id=${AVATAR_NODE_ID}`, { headers: auth(memberToken) });
+    const listBody = await list.json() as any;
+    const row = listBody.nodes.find((n: any) => n.node_id === AVATAR_NODE_ID);
+    expect(row.avatar_url).toBeNull();
+  });
+
+  test("javascript: URL → 400 invalid_avatar_url, value NOT persisted", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "javascript:alert(1)" }),
+    });
+    expect(put.status).toBe(400);
+    const body = await put.json() as any;
+    expect(body.error).toBe("invalid_avatar_url");
+    const row = db.get<any>("SELECT avatar_url FROM nodes WHERE node_id = ?1", AVATAR_NODE_ID);
+    expect(row.avatar_url ?? null).toBeNull();
+  });
+
+  test("data: URL → 400", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "data:text/html,<script>alert(1)</script>" }),
+    });
+    expect(put.status).toBe(400);
+  });
+
+  test("anonymous → 401; non-member → 404/403 (network-scoped lookup)", async () => {
+    const anon = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "https://example.com/x.png" }),
+    });
+    expect(anon.status).toBe(401);
+
+    // Outsider's network scope can't even see the node → 404 (or 403 if
+    // visibility rules change later; both deny the write).
+    const outsider = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(outsiderToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "https://example.com/x.png" }),
+    });
+    expect([403, 404]).toContain(outsider.status);
+    const row = db.get<any>("SELECT avatar_url FROM nodes WHERE node_id = ?1", AVATAR_NODE_ID);
+    expect(row.avatar_url ?? null).toBeNull();
+  });
+});