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

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

@@ -1,5 +1,6 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { db } from "./db.js";
+import { parseStoredTags } from "./node-attrs-validate.js";
 
 // Regression test for SELECT * fragility on GET /api/nodes.
 //
@@ -41,7 +42,12 @@ function mapRow(r: Record<string, unknown>): Record<string, unknown> {
     catch { /* malformed */ }
   }
   const { config_snapshot, ...rest } = r;
-  return { ...rest, role };
+  return {
+    ...rest,
+    tags: parseStoredTags(r.tags),
+    attrs_revision: Number(r.attrs_revision ?? 0),
+    role,
+  };
 }
 
 describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", () => {
@@ -66,7 +72,7 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
       `SELECT node_id, node_name, alias, runtime, model,
               config_path, channels, server, hostname,
               network_id, created_at, updated_at,
-              config_snapshot
+              config_snapshot, display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     );
@@ -85,11 +91,17 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     expect(row).not.toHaveProperty("config_snapshot");
     // 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
+    // Belt: the key set is exactly the dashboard-facing contract.
+    // NOTE: this file MIRRORS the handler's SQL rather than calling it, so
+    // it can drift — it already lagged behind `lifecycle_state` /
+    // `avatar_url`, which the handler selects but this mirror does not.
+    // Treat a diff here as "re-read the handler", not as proof of the wire
+    // shape; node-attrs.test.ts asserts the real HTTP response.
     expect(Object.keys(row).sort()).toEqual([
-      "alias", "channels", "config_path", "created_at", "hostname",
-      "model", "network_id", "node_id", "node_name", "role", "runtime",
-      "server", "updated_at",
+      "alias", "attrs_revision", "channels", "config_path", "created_at",
+      "display_name", "hostname", "model", "network_id", "node_id",
+      "node_name", "role", "runtime", "server", "tags", "team",
+      "updated_at",
     ]);
   });
 
@@ -102,7 +114,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     );
     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
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     )!);
@@ -113,7 +126,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     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
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     )!);
@@ -124,7 +138,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
            [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
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     )!);
@@ -141,7 +156,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     );
     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
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE network_id = ?1`,
       TEST_NETWORK,
     ).map(mapRow);

package/src/auth-validate.test.ts

@@ -10,13 +10,17 @@ import { register } from "./auth.js";
 
 // First user gets RELAXED rules (admin bootstrap allows 4-char "anethub" etc.)
 // To test full-strength rules, seed a dummy admin first.
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
 beforeAll(() => {
   // Idempotent: if DB file already has users (from a previous run on the
   // same temp path), this errors with "username already taken" → that's
   // fine, the goal is just "ensure at least one user exists so subsequent
   // registers hit the strict path".
   register("_seed_admin", "BootstrapPw1", undefined, "seed");
-});
+}, 30_000);
 
 describe("register — username rules", () => {
   it("rejects empty username", () => {

package/src/auth.ts

@@ -3,6 +3,7 @@
  */
 import { db, generateId, hashPassword, verifyPassword, hashToken, generateToken, generateUserToken, generateNetworkToken, uuidv4 } from "./db.js";
 import { WEAK_PASSWORDS } from "./password-dict.js";
+import { NETWORK_REST_COLUMNS, NETWORK_REST_SELECT, sqlColumns } from "./rest-projections.js";
 
 // Round-6 A1 hardening — dummy hash for username-enumeration timing
 // close. We compute ONE scrypt hash of a throwaway password and reuse
@@ -87,11 +88,32 @@ export function register(username: string, password: string, email?: string, dis
     [userId, username, pwHash, email || null, displayName || username, isFirstUser ? "admin" : "user"]
   );
 
-  // Auto-create default network + add as owner member
+  // Auto-create the user's own network + add as owner member.
+  //
+  // Name it after the user rather than the literal "default". Every
+  // registration used to mint a network called "default", so a hub with N
+  // users showed N identical "default" rows in the Dashboard sidebar with
+  // no way to tell them apart (23 of them on the live hub, 22 empty).
+  // Three CLI call sites (bin/cli.ts debate / demo-social / pr-review) resolve
+  // a network as:
+  //     me.user.default_network_id
+  //       || networks.find(n => n.network_name === "default")
+  //       || networks[0]
+  // Checked against the live hub: GET /api/auth/me returns
+  // {user_id, username, display_name, email, role} — there is no
+  // default_network_id field, and nothing in server/ ever writes one. So the
+  // first term is always undefined and the name lookup is the operative path,
+  // not a fallback.
+  //
+  // After this change that lookup misses for new users and they land on
+  // networks[0]. That still resolves to this network because listNetworks()
+  // is `ORDER BY created_at` ascending (auth.ts:296) and this row is the
+  // user's oldest. Reordering that query would silently point those three
+  // commands at the wrong network.
   const networkId = generateId("net");
   db.run(
     "INSERT INTO networks (network_id, network_name, owner_id, description) VALUES (?1, ?2, ?3, ?4)",
-    [networkId, "default", userId, "Auto-created default network"]
+    [networkId, username, userId, `Auto-created network for ${username}`]
   );
   db.run(
     "INSERT INTO network_members (network_id, user_id, role) VALUES (?1, ?2, 'owner')",
@@ -191,18 +213,67 @@ export function login(username: string, password: string): AuthResult {
   };
 }
 
-/** Create a network-scoped token (ntok_) for a specific node */
-export function createNetworkTokenForNode(userId: string, networkId: string, nodeName: string): { ok: boolean; token?: string; error?: string } {
+/**
+ * Create a network-scoped token (ntok_) for a specific node.
+ *
+ * RFC-036: callers that provide nodeId atomically establish the immutable
+ * node-owner binding before the plaintext token is returned. The 3-argument
+ * legacy form remains available for old clients, but its token has no bound
+ * node id and therefore cannot consume external-schedule edit intents.
+ */
+export function createNetworkTokenForNode(userId: string, networkId: string, nodeName: string, nodeId?: string): { ok: boolean; token?: string; token_id?: string; node_id?: string; error?: string } {
   // Verify user is a member of this network with write access
   const role = getUserNetworkRole(userId, networkId);
   if (!role || role === "viewer") return { ok: false, error: "no write access to this network" };
+  if (!nodeName || nodeName.length > 200) return { ok: false, error: "invalid_node_name" };
+  if (nodeId !== undefined && (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(nodeId))) {
+    return { ok: false, error: "invalid_node_id" };
+  }
   const token = generateNetworkToken();
   const tokenId = generateId("tok");
-  db.run(
-    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-    [tokenId, hashToken(token), userId, networkId, `node:${nodeName}`, "network"]
-  );
-  return { ok: true, token };
+  try {
+    db.transaction(() => {
+      if (nodeId) {
+        const existing = db.get<{ network_id: string | null; owner_user_id: string | null }>(
+          "SELECT network_id, owner_user_id FROM nodes WHERE node_id = ?1",
+          nodeId,
+        );
+        if (existing?.network_id && existing.network_id !== networkId) throw new Error("cross_network_node");
+        // Existing pre-RFC-036 rows have no trustworthy owner anchor. A token
+        // refresh must not turn knowledge of a legacy node_id into ownership.
+        // They remain read-only until a separately authorized migration.
+        if (existing && !existing.owner_user_id) throw new Error("node_owner_unclaimed");
+        if (existing?.owner_user_id && existing.owner_user_id !== userId) throw new Error("node_owner_mismatch");
+        db.run(
+          `INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, updated_at)
+           VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'))
+           ON CONFLICT(node_id) DO UPDATE SET
+             node_name = COALESCE(nodes.node_name, ?2),
+             alias = COALESCE(nodes.alias, ?2),
+             network_id = COALESCE(nodes.network_id, ?3),
+             owner_user_id = COALESCE(nodes.owner_user_id, ?4),
+             updated_at = datetime('now')`,
+          [nodeId, nodeName, networkId, userId],
+        );
+        if (!existing) {
+          db.run(
+            `INSERT INTO audit_log (user_id, action, target_type, target_id, detail, network_id)
+             VALUES (?1, 'external_schedule.owner_claimed', 'node', ?2, ?3, ?4)`,
+            [userId, nodeId, JSON.stringify({ node_id: nodeId, network_id: networkId }), networkId],
+          );
+        }
+      }
+      db.run(
+        "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, bound_node_id) VALUES (?1, ?2, ?3, ?4, ?5, 'network', ?6)",
+        [tokenId, hashToken(token), userId, networkId, `node:${nodeName}`, nodeId ?? null],
+      );
+    });
+  } catch (error: any) {
+    const code = String(error?.message || "node_token_create_failed");
+    if (code === "cross_network_node" || code === "node_owner_unclaimed" || code === "node_owner_mismatch") return { ok: false, error: code };
+    throw error;
+  }
+  return { ok: true, token, token_id: tokenId, ...(nodeId ? { node_id: nodeId } : {}) };
 }
 
 export function resolveToken(token: string): { user: AuthUser; networkId: string | null; tokenName: string | null; tokenId: string | null } | null {
@@ -235,7 +306,7 @@ export function resolveToken(token: string): { user: AuthUser; networkId: string
 
 export function getUserNetworks(userId: string) {
   return db.all<any>(
-    "SELECT * FROM networks WHERE owner_id = ?1 ORDER BY created_at",
+    `SELECT ${NETWORK_REST_SELECT} FROM networks WHERE owner_id = ?1 ORDER BY created_at`,
     userId);
 }
 
@@ -280,7 +351,7 @@ export function listTokens(userId: string) {
 }
 
 export function renameNetwork(userId: string, networkId: string, newName: string): { ok: boolean; error?: string } {
-  const net = db.get<any>("SELECT * FROM networks WHERE network_id = ?1", networkId);
+  const net = db.get<any>("SELECT owner_id FROM networks WHERE network_id = ?1", networkId);
   if (!net) return { ok: false, error: "network not found" };
   if (net.owner_id !== userId) return { ok: false, error: "not your network" };
   const dup = db.get<any>("SELECT network_id FROM networks WHERE owner_id = ?1 AND network_name = ?2", userId, newName);
@@ -290,13 +361,18 @@ export function renameNetwork(userId: string, networkId: string, newName: string
 }
 
 export function deleteNetwork(userId: string, networkId: string): { ok: boolean; error?: string } {
-  const net = db.get<any>("SELECT * FROM networks WHERE network_id = ?1", networkId);
+  const net = db.get<any>("SELECT owner_id FROM networks WHERE network_id = ?1", networkId);
   if (!net) return { ok: false, error: "network not found" };
   if (net.owner_id !== userId) return { ok: false, error: "not your network" };
   // Check if any sessions/tasks still reference this network
   const sessions = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM sessions WHERE network_id = ?1", networkId);
   if (sessions && sessions.cnt > 0) return { ok: false, error: `network has ${sessions.cnt} active session(s) — stop them first` };
   db.run("DELETE FROM networks WHERE network_id = ?1 AND owner_id = ?2", [networkId, userId]);
+  // PR #519 codex catch: leaving membership rows behind made deleted
+  // networks count toward getUserNetworkIds — a stale row could flip a
+  // single-network user to "ambiguous" or auto-resolve writes INTO the
+  // deleted network. Remove memberships with the network.
+  db.run("DELETE FROM network_members WHERE network_id = ?1", [networkId]);
   return { ok: true };
 }
 
@@ -444,7 +520,10 @@ export function createInvite(networkId: string, createdBy: string, role: string
 }
 
 export function joinByInvite(inviteCode: string, userId: string): { ok: boolean; network_id?: string; role?: string; error?: string } {
-  const invite = db.get<any>("SELECT * FROM network_invites WHERE invite_code = ?1", inviteCode);
+  const invite = db.get<any>(
+    "SELECT invite_code, network_id, role, created_by, max_uses, used_count, expires_at, created_at FROM network_invites WHERE invite_code = ?1",
+    inviteCode,
+  );
   if (!invite) return { ok: false, error: "invalid invite code" };
   if (invite.max_uses > 0 && invite.used_count >= invite.max_uses) return { ok: false, error: "invite code fully used" };
   if (invite.expires_at) {
@@ -469,7 +548,7 @@ export function joinByInvite(inviteCode: string, userId: string): { ok: boolean;
 /** Get all networks a user is a member of (replaces owner-only query) */
 export function getUserAllNetworks(userId: string) {
   return db.all<any>(
-    `SELECT n.*, nm.role as member_role
+    `SELECT ${sqlColumns(NETWORK_REST_COLUMNS, "n")}, nm.role as member_role
      FROM networks n JOIN network_members nm ON n.network_id = nm.network_id
      WHERE nm.user_id = ?1 ORDER BY nm.role = 'owner' DESC, n.created_at`,
     userId);

package/src/avatar-validate.test.ts

@@ -0,0 +1,163 @@
+// #462 — unit tests for the avatar_url XSS boundary (avatar-validate.ts).
+//
+// The validator's whole job is to keep hostile values out of a dashboard
+// <img src>; every rejection case here is a concrete injection shape.
+// Live-gate check: replace validateAvatarUrl with `return { ok: true,
+// value: String(raw) }` and the javascript:/data:/control-char tests go
+// red.
+
+import { describe, expect, test } from "bun:test";
+import { MAX_AVATAR_URL_LENGTH, validateAvatarUrl } from "./avatar-validate";
+
+describe("#462 validateAvatarUrl", () => {
+  test("accepts plain https URL", () => {
+    const r = validateAvatarUrl("https://cdn.example.com/a/b.png");
+    expect(r).toEqual({ ok: true, value: "https://cdn.example.com/a/b.png" });
+  });
+
+  test("accepts http URL and trims surrounding whitespace", () => {
+    const r = validateAvatarUrl("  http://example.com/x.jpg  ");
+    expect(r).toEqual({ ok: true, value: "http://example.com/x.jpg" });
+  });
+
+  test("accepts URL with query string", () => {
+    const r = validateAvatarUrl("https://example.com/img?size=64&v=2");
+    expect(r.ok).toBe(true);
+  });
+
+  test("null / undefined / empty / whitespace-only → clear (value null)", () => {
+    expect(validateAvatarUrl(null)).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl(undefined)).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl("")).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl("   ")).toEqual({ ok: true, value: null });
+  });
+
+  test("rejects non-string types", () => {
+    expect(validateAvatarUrl(42).ok).toBe(false);
+    expect(validateAvatarUrl({ url: "https://x" }).ok).toBe(false);
+    expect(validateAvatarUrl(["https://x"]).ok).toBe(false);
+    expect(validateAvatarUrl(true).ok).toBe(false);
+  });
+
+  test("rejects javascript: pseudo-protocol", () => {
+    expect(validateAvatarUrl("javascript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("JavaScript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("JAVASCRIPT:alert(document.cookie)").ok).toBe(false);
+  });
+
+  test("rejects javascript: smuggled via embedded tab/newline (URL() would strip them)", () => {
+    expect(validateAvatarUrl("java\tscript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("java\nscript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("java\rscript:alert(1)").ok).toBe(false);
+  });
+
+  test("rejects data: / vbscript: / file: / blob: and other non-http protocols", () => {
+    expect(validateAvatarUrl("data:text/html,<script>alert(1)</script>").ok).toBe(false);
+    expect(validateAvatarUrl("data:image/png;base64,iVBORw0KGgo=").ok).toBe(false);
+    expect(validateAvatarUrl("vbscript:msgbox(1)").ok).toBe(false);
+    expect(validateAvatarUrl("file:///etc/passwd").ok).toBe(false);
+    expect(validateAvatarUrl("blob:https://example.com/uuid").ok).toBe(false);
+    expect(validateAvatarUrl("ftp://example.com/a.png").ok).toBe(false);
+  });
+
+  test("rejects protocol-relative / non-URL / schemeless strings", () => {
+    // SPEC CHANGE (通信龙 裁定, avatar 接线单): same-origin pool paths
+    // (/avatars/<name>.<ext>) are now ACCEPTED — that case moved to the
+    // dedicated relative-branch suite below. Everything here stays rejected.
+    expect(validateAvatarUrl("//cdn.example.com/1.png").ok).toBe(false);
+    expect(validateAvatarUrl("not a url").ok).toBe(false);
+    expect(validateAvatarUrl("example.com/x.png").ok).toBe(false);
+  });
+
+  test("rejects embedded whitespace and control characters", () => {
+    expect(validateAvatarUrl("https://example.com/a b.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://example.com/a\u0000.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://example.com/a\u009f.png").ok).toBe(false);
+  });
+
+  test("normalizes to parsed.href: markup-hostile chars come out percent-encoded (finding 3)", () => {
+    const r1 = validateAvatarUrl('https://example.com/a"b.png');
+    expect(r1).toEqual({ ok: true, value: "https://example.com/a%22b.png" });
+    const r2 = validateAvatarUrl("https://example.com/</script><script>.png");
+    expect(r2.ok).toBe(true);
+    if (r2.ok) {
+      expect(r2.value).not.toContain("<");
+      expect(r2.value).not.toContain(">");
+    }
+    const r3 = validateAvatarUrl("https://example.com/a`b.png");
+    expect(r3.ok).toBe(true);
+    if (r3.ok) expect(r3.value).not.toContain("`");
+  });
+
+  test("rejects values whose href still carries attribute-breaking chars (single quote)", () => {
+    // WHATWG URL leaves ' un-encoded in the PATH component — href alone
+    // doesn't neutralize it there, so the validator must refuse.
+    expect(validateAvatarUrl("https://example.com/a'b.png").ok).toBe(false);
+    // In the QUERY component ' IS percent-encoded by href → accepted,
+    // but the stored value must carry no raw quote.
+    const q = validateAvatarUrl("https://example.com/x.png?a='1'");
+    expect(q.ok).toBe(true);
+    if (q.ok) expect(q.value).not.toContain("'");
+  });
+
+  test("rejects URLs with embedded credentials (userinfo)", () => {
+    expect(validateAvatarUrl("https://user:pass@example.com/a.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://user@example.com/a.png").ok).toBe(false);
+    expect(validateAvatarUrl("http://:secret@example.com/a.png").ok).toBe(false);
+  });
+
+  test("enforces the length cap", () => {
+    const base = "https://example.com/";
+    const ok = base + "a".repeat(MAX_AVATAR_URL_LENGTH - base.length);
+    expect(validateAvatarUrl(ok).ok).toBe(true);
+    expect(validateAvatarUrl(ok + "a").ok).toBe(false);
+  });
+});
+
+// ── Same-origin relative branch (通信龙 裁定: relax to portable pool paths;
+//    absolute URLs would weld one hostname into the DB across multi-origin
+//    entry points). Each direction is its OWN test so any single guard
+//    being deleted turns its OWN assertion red (no merged catch-all).
+describe("validateAvatarUrl — same-origin relative pool paths", () => {
+  test("accepts a pool path: /avatars/avatar-09.webp", () => {
+    const r = validateAvatarUrl("/avatars/avatar-09.webp");
+    expect(r).toEqual({ ok: true, value: "/avatars/avatar-09.webp" });
+  });
+
+  test("accepts png and svg pool files", () => {
+    expect(validateAvatarUrl("/avatars/intern_avatar.png")).toEqual({ ok: true, value: "/avatars/intern_avatar.png" });
+    expect(validateAvatarUrl("/avatars/team-logo.svg")).toEqual({ ok: true, value: "/avatars/team-logo.svg" });
+  });
+
+  test("rejects protocol-relative //host (classic same-origin bypass)", () => {
+    const r = validateAvatarUrl("//evil.com/x.png");
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toContain("protocol-relative");
+  });
+
+  test("rejects javascript: scheme (still, after the relax)", () => {
+    expect(validateAvatarUrl("javascript:alert(1)").ok).toBe(false);
+  });
+
+  test("rejects non-/avatars/ absolute paths (/etc/passwd)", () => {
+    expect(validateAvatarUrl("/etc/passwd").ok).toBe(false);
+  });
+
+  test("rejects non-whitelisted extensions under /avatars/", () => {
+    expect(validateAvatarUrl("/avatars/payload.html").ok).toBe(false);
+  });
+
+  test("rejects nested/traversal paths (charset forbids further slashes)", () => {
+    expect(validateAvatarUrl("/avatars/../secrets.webp").ok).toBe(false);
+    expect(validateAvatarUrl("/avatars/sub/x.webp").ok).toBe(false);
+  });
+
+  test("rejects percent-encoding inside the filename (no encoded surprises)", () => {
+    expect(validateAvatarUrl("/avatars/a%2f..%2fx.webp").ok).toBe(false);
+  });
+
+  test("absolute http(s) branch is UNTOUCHED by the relax (positive control)", () => {
+    const r = validateAvatarUrl("https://example.com/pic.png");
+    expect(r.ok).toBe(true);
+  });
+});

package/src/avatar-validate.ts

@@ -0,0 +1,103 @@
+// #462 — validator for the user-set custom avatar URL (nodes.avatar_url).
+//
+// The value ends up in an <img src> on every dashboard client, so this is
+// an XSS trust boundary: protocol MUST be http/https (rejects javascript:,
+// data:, vbscript:, file:, blob:, …), no whitespace/control characters,
+// bounded length. Pure function, unit-tested in avatar-validate.test.ts.
+
+export const MAX_AVATAR_URL_LENGTH = 2048;
+
+export type AvatarValidation =
+  | { ok: true; value: string | null }
+  | { ok: false; reason: string };
+
+/**
+ * Normalize + validate an untrusted avatar_url patch value.
+ *
+ *   null / undefined / "" / whitespace-only  → { ok, value: null }  (clear)
+ *   same-origin pool path /avatars/<name>.<ext>  → { ok, value: trimmed }
+ *   valid absolute http(s) URL               → { ok, value: normalized }
+ *   anything else                            → { ok: false, reason }
+ *
+ * Relative branch rationale (通信龙 裁定, avatar 接线单): the hub is
+ * reached through several origins (localhost dev, public domains) — an
+ * absolute URL would weld ONE hostname into the DB and break the image
+ * for every other entry point; a same-origin relative path is portable.
+ * 🔴 Trap this branch must block: "starts with /" ≠ "same-origin" —
+ * "//evil.com/x.png" ALSO starts with "/" but is a protocol-relative URL
+ * the browser resolves to evil.com. Hence: single leading slash with the
+ * SECOND char not "/", then an exact value-set match (the /avatars/ pool
+ * prefix + extension whitelist), not a shape match.
+ */
+
+// Exact allowed set for same-origin values: the dashboard's designed pool
+// under /avatars/. Filename charset excludes "/" (no traversal, no nested
+// paths) and "%" (no encoded surprises); extensions mirror the actual
+// pool contents. Widen ONLY by extending this list deliberately.
+const SAME_ORIGIN_AVATAR_RE = /^\/avatars\/[A-Za-z0-9._-]+\.(webp|png|svg)$/;
+export function validateAvatarUrl(raw: unknown): AvatarValidation {
+  if (raw === null || raw === undefined) return { ok: true, value: null };
+  if (typeof raw !== "string") {
+    return { ok: false, reason: "avatar_url must be a string or null" };
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { ok: true, value: null };
+  if (trimmed.length > MAX_AVATAR_URL_LENGTH) {
+    return { ok: false, reason: `avatar_url must be ≤ ${MAX_AVATAR_URL_LENGTH} chars` };
+  }
+  // Reject embedded whitespace + C0/C1 control chars outright. URL()
+  // silently strips some of these (e.g. tabs/newlines), which would let
+  // "java\tscript:" style payloads normalize into a hostile protocol —
+  // so this check must run BEFORE parsing, on the raw trimmed string.
+  if (/[\u0000-\u001f\u007f-\u009f\s]/.test(trimmed)) {
+    return { ok: false, reason: "avatar_url must not contain whitespace or control characters" };
+  }
+  // Same-origin relative branch (runs AFTER the whitespace/control gate
+  // above — that check protects this branch too). Order of the two tests
+  // matters for the reason string, not for safety: the exact-set regex
+  // alone already rejects "//…" (second char is "/", first segment must
+  // literally be "avatars"), the explicit double-slash check just names
+  // the classic bypass in its own words.
+  if (trimmed.startsWith("/")) {
+    if (trimmed.startsWith("//")) {
+      return { ok: false, reason: "avatar_url must not be protocol-relative (//host/…)" };
+    }
+    if (!SAME_ORIGIN_AVATAR_RE.test(trimmed)) {
+      return { ok: false, reason: "relative avatar_url must match /avatars/<name>.(webp|png|svg)" };
+    }
+    return { ok: true, value: trimmed };
+  }
+  // Absolute http(s) branch — unchanged from #462 (do not touch while
+  // relaxing: 通信龙 裁定 condition 3).
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, reason: "avatar_url must be an absolute URL" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { ok: false, reason: "avatar_url protocol must be http or https" };
+  }
+  // Embedded credentials (https://user:pass@host/…) would be persisted,
+  // leaked to the avatar host on every render, and can spoof the visible
+  // origin in UIs. Reject outright rather than silently stripping — the
+  // caller should know their input carried secrets (通信龙 review round-2
+  // follow-up).
+  if (parsed.username || parsed.password) {
+    return { ok: false, reason: "avatar_url must not contain credentials (userinfo)" };
+  }
+  // Persist the NORMALIZED href, not the raw input: href percent-encodes
+  // markup-hostile characters (" < > ` → %22 %3C %3E %60), so what lands
+  // in the DB is already safe to interpolate into an <img src> attribute.
+  // The dashboard renderer lives in a different package this repo cannot
+  // audit — the server must not bet on it escaping (审查修复 per 通信龙
+  // #461/#462 review, finding 3).
+  const normalized = parsed.href;
+  // Belt-and-braces: reject anything href does NOT encode that could
+  // still break out of an attribute context (WHATWG URL leaves ' and \
+  // untouched in some positions).
+  if (/["'<>\\`]/.test(normalized)) {
+    return { ok: false, reason: "avatar_url contains characters not allowed in a URL" };
+  }
+  return { ok: true, value: normalized };
+}