@sleep2agi/commhub-server 0.9.0-preview.7 → 0.9.0-preview.70

package/src/network-name-http.test.ts

@@ -0,0 +1,75 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-network-name-http-"));
+let server: any;
+let base = "";
+let userToken = "";
+let nodeToken = "";
+let networkId = "";
+let username = "";
+
+// 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(async () => {
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || join(PRIVATE_DB_DIR, "hub.db");
+  username = `network_name_${Date.now()}_${process.pid}`;
+  const registered = register(username, "NetworkName123!", undefined, "seed");
+  expect(registered.ok).toBe(true);
+  userToken = registered.token!;
+  networkId = registered.network_id!;
+  const userId = db.get<{ user_id: string }>(
+    "SELECT user_id FROM users WHERE username = ?1",
+    [username],
+  )!.user_id;
+  const minted = createNetworkTokenForNode(userId, networkId, "network-name-node");
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+async function networks(token: string): Promise<any[]> {
+  const response = await fetch(`${base}/api/networks`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  const body = await response.json() as any;
+  expect(body.ok).toBe(true);
+  return body.networks;
+}
+
+describe("GET /api/networks name compatibility (#449)", () => {
+  test("utok rows expose equal non-null name and network_name", async () => {
+    const rows = await networks(userToken);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].network_id).toBe(networkId);
+    // #449 is about `name` and `network_name` agreeing and being non-null.
+    // Pin them to the registered username rather than the literal "default":
+    // the auto-created network is named after its owner, so hardcoding the
+    // old literal would test the naming scheme instead of the compat shim.
+    expect(rows[0].network_name).toBe(username);
+    expect(rows[0].name).toBe(username);
+  });
+
+  test("network-bound ntok rows expose the same alias", async () => {
+    const rows = await networks(nodeToken);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].network_id).toBe(networkId);
+    expect(rows[0].network_name).toBe(username);
+    expect(rows[0].name).toBe(rows[0].network_name);
+    expect(rows[0].name).not.toBeNull();
+  });
+});

package/src/network-scope.ts

@@ -0,0 +1,224 @@
+// Network-scope resolution shared by BOTH transports.
+//
+// #517: REST (server.ts) and MCP (tools.ts) each carried their own copy of
+// the "which network does this caller write to" rule. REST grew a
+// single-network fallback (POST /api/task); MCP never did — so a utok_
+// caller could read everything but write nothing, with a misleading
+// permission_denied. Extracted here (same pattern as lifecycle-guard.ts)
+// so the rule has exactly ONE implementation. If you change write-scope
+// semantics, this module is the only place — do NOT re-inline a copy in
+// server.ts or tools.ts.
+
+import { db } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { isAgentRestricted, restrictedNetworkIds, usernameIsAgentAlias, visibleAgents } from "./agent-access.js";
+
+export type RestNetworkScope = {
+  networkId: string | null;
+  networkIds: string[] | null;
+  denied?: string;
+  // 多用户 Agent 权限:scope 里哪些网络对这个调用者是「只看授权 Agent」的。
+  // addNetworkScope 对这些网络 fail-closed(整网不返回);要按授权放行的路径
+  // 显式改用 addAgentNetworkScope / addOwnTrafficScope,人类数据用 addHumanNetworkScope。
+  agentRestriction?: { userId: string; username: string; networkIds: string[] };
+};
+
+type ScopeAuthCtx = { userId: string; networkId: string | null; username?: string | null };
+
+function usernameOf(userId: string, known?: string | null): string {
+  if (known) return known;
+  return db.get<{ username: string }>("SELECT username FROM users WHERE user_id = ?1", userId)?.username ?? "";
+}
+
+function withAgentRestriction(scope: RestNetworkScope, authCtx: ScopeAuthCtx): RestNetworkScope {
+  const inScope = scope.networkId ? [scope.networkId] : (scope.networkIds ?? []);
+  if (inScope.length === 0) return scope;
+  const restricted = restrictedNetworkIds(authCtx.userId).filter((id) => inScope.includes(id));
+  if (restricted.length === 0) return scope;
+  return { ...scope, agentRestriction: { userId: authCtx.userId, username: usernameOf(authCtx.userId, authCtx.username), networkIds: restricted } };
+}
+
+export function getUserNetworkIds(userId: string): string[] {
+  // JOIN networks: deleteNetwork historically left network_members rows
+  // behind (fixed alongside PR #519, but legacy DBs still carry strays).
+  // A ghost membership must neither make a single-network user look
+  // ambiguous nor let the write fallback resolve INTO a deleted network.
+  return db.all<{ network_id: string }>(
+    `SELECT m.network_id FROM network_members m
+     JOIN networks n ON n.network_id = m.network_id
+     WHERE m.user_id = ?1`,
+    userId
+  ).map((row) => row.network_id);
+}
+
+export function resolveRestNetworkScope(requested: string | null, authCtx: ScopeAuthCtx | null, isAdmin: boolean): RestNetworkScope {
+  // Legacy global token or open dev mode keeps the old global behavior.
+  if (!authCtx) return { networkId: requested || null, networkIds: null };
+
+  // Network tokens are forcibly scoped to their bound network.
+  if (authCtx.networkId) return { networkId: authCtx.networkId, networkIds: null };
+
+  // System admins may intentionally inspect all networks.
+  if (isAdmin) return { networkId: requested || null, networkIds: null };
+
+  if (requested) {
+    const role = getUserNetworkRole(authCtx.userId, requested);
+    if (!role) return { networkId: null, networkIds: [], denied: "access denied to requested network" };
+    return withAgentRestriction({ networkId: requested, networkIds: null }, authCtx);
+  }
+
+  return withAgentRestriction({ networkId: null, networkIds: getUserNetworkIds(authCtx.userId) }, authCtx);
+}
+
+function unrestrictedNetworks(scope: RestNetworkScope): string[] | null {
+  const excluded = scope.agentRestriction?.networkIds ?? [];
+  if (scope.networkId) return excluded.includes(scope.networkId) ? [] : [scope.networkId];
+  if (scope.networkIds) return scope.networkIds.filter((id) => !excluded.includes(id));
+  return null;
+}
+
+function placeholders(params: any[], values: string[]): string {
+  const start = params.length;
+  params.push(...values);
+  return values.map((_, i) => `?${start + i + 1}`).join(", ");
+}
+
+/**
+ * 默认的网络作用域 —— 对受限成员的受限网络 **fail-closed**:整网不返回。
+ * 没被逐条审过、不知道按授权怎么放行的查询,默认走这里,受限成员什么都看不到。
+ */
+export function addNetworkScope(sql: string, params: any[], scope: RestNetworkScope, column = "network_id"): string {
+  if (!scope.agentRestriction) return addHumanNetworkScope(sql, params, scope, column);
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length === 0) return `${sql} AND 1=0`;
+  return `${sql} AND ${column} IN (${placeholders(params, allowed)})`;
+}
+
+/**
+ * 人类数据(自己的私信收件箱、需求看板、项目、网络成员)的作用域:受限成员照常看得到
+ * 自己所在网络。只给已确认不含 Agent 内容的查询用。
+ */
+export function addHumanNetworkScope(sql: string, params: any[], scope: RestNetworkScope, column = "network_id"): string {
+  if (scope.networkId) {
+    sql += ` AND ${column} = ?${params.length + 1}`;
+    params.push(scope.networkId);
+  } else if (scope.networkIds) {
+    if (scope.networkIds.length === 0) {
+      sql += " AND 1=0";
+    } else {
+      const placeholders = scope.networkIds.map((_, i) => `?${params.length + i + 1}`).join(", ");
+      sql += ` AND ${column} IN (${placeholders})`;
+      params.push(...scope.networkIds);
+    }
+  }
+  return sql;
+}
+
+type AgentColumns = { network?: string; alias: string; nodeId?: string };
+
+/**
+ * Agent 行(sessions / nodes)的作用域:不受限的网络整网放行;受限网络只放行授权的 Agent。
+ * mode="message" 时只放行 can_message 的授权。
+ */
+export function addAgentNetworkScope(sql: string, params: any[], scope: RestNetworkScope, cols: AgentColumns, mode: "see" | "message" = "see"): string {
+  const restriction = scope.agentRestriction;
+  if (!restriction) return addHumanNetworkScope(sql, params, scope, cols.network ?? "network_id");
+  const net = cols.network ?? "network_id";
+  const parts: string[] = [];
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length) parts.push(`${net} IN (${placeholders(params, allowed)})`);
+  for (const networkId of restriction.networkIds) {
+    const visible = visibleAgents(restriction.userId, networkId);
+    const aliases = mode === "message" ? visible.messageAliases : visible.aliases;
+    const nodeIds = mode === "message" ? visible.messageNodeIds : visible.nodeIds;
+    const conds: string[] = [];
+    if (aliases.length) conds.push(`${cols.alias} IN (${placeholders(params, aliases)})`);
+    if (cols.nodeId && nodeIds.length) conds.push(`${cols.nodeId} IN (${placeholders(params, nodeIds)})`);
+    if (conds.length === 0) continue;
+    parts.push(`(${net} = ${placeholders(params, [networkId])} AND (${conds.join(" OR ")}))`);
+  }
+  return parts.length ? `${sql} AND (${parts.join(" OR ")})` : `${sql} AND 1=0`;
+}
+
+type TrafficColumns = { network?: string; from: string; to: string; fromNodeId?: string; toNodeId?: string };
+
+/**
+ * 任务 / inbox 这类「谁发给谁」的行:受限网络里只放行**自己**与**授权 Agent**之间的往来
+ * (from=自己 且 to=授权 Agent,或反过来)。别人(包括 owner)和同一个 Agent 的对话看不到。
+ */
+export function addOwnTrafficScope(sql: string, params: any[], scope: RestNetworkScope, cols: TrafficColumns): string {
+  const restriction = scope.agentRestriction;
+  if (!restriction) return addHumanNetworkScope(sql, params, scope, cols.network ?? "network_id");
+  const net = cols.network ?? "network_id";
+  const parts: string[] = [];
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length) parts.push(`${net} IN (${placeholders(params, allowed)})`);
+  if (restriction.username) {
+    for (const networkId of restriction.networkIds) {
+      // 用户名与本网络某个 Agent 的 alias 撞名时(入网时拦过,但 Agent 之后注册的 alias 拦不住),
+      // 「发给我的」无法和「发给那个 Agent 的」区分开 —— 这个网络的往来一律不放行。
+      if (usernameIsAgentAlias(networkId, restriction.username)) continue;
+      const visible = visibleAgents(restriction.userId, networkId);
+      // 先判空再生成占位符:side() 会往 params 里推值,推了又丢弃会让参数个数对不上。
+      const useNodeIds = !!(cols.fromNodeId && cols.toNodeId) && visible.nodeIds.length > 0;
+      if (visible.aliases.length === 0 && !useNodeIds) continue;
+      const side = (aliasCol: string, nodeCol?: string): string | null => {
+        const conds: string[] = [];
+        if (visible.aliases.length) conds.push(`${aliasCol} IN (${placeholders(params, visible.aliases)})`);
+        if (nodeCol && useNodeIds) conds.push(`${nodeCol} IN (${placeholders(params, visible.nodeIds)})`);
+        return conds.length ? `(${conds.join(" OR ")})` : null;
+      };
+      const toAgent = side(cols.to, cols.toNodeId)!;
+      const fromAgent = side(cols.from, cols.fromNodeId)!;
+      const me = placeholders(params, [restriction.username]);
+      parts.push(`(${net} = ${placeholders(params, [networkId])} AND ((${cols.from} = ${me} AND ${toAgent}) OR (${cols.to} = ${me} AND ${fromAgent})))`);
+    }
+  }
+  return parts.length ? `${sql} AND (${parts.join(" OR ")})` : `${sql} AND 1=0`;
+}
+
+export function singleNetworkId(scope: RestNetworkScope): string | null {
+  if (scope.networkId) return scope.networkId;
+  if (scope.networkIds?.length === 1) return scope.networkIds[0];
+  return null;
+}
+
+/**
+ * Resolve one unambiguous network for a REST write.
+ *
+ * Admin read scope is intentionally global (`networkIds=null`), so it cannot
+ * by itself express that an admin happens to have exactly one membership.
+ * Writes must not inherit that ambiguity: use the sole real membership when
+ * one exists, and keep requiring an explicit network for zero or 2+.
+ */
+export function resolveRestWriteNetworkId(
+  scope: RestNetworkScope,
+  authCtx: { userId: string; networkId: string | null } | null,
+  isAdmin: boolean,
+): string | null {
+  const scoped = singleNetworkId(scope);
+  if (scoped) return scoped;
+  if (!authCtx || !isAdmin) return null;
+  const memberships = getUserNetworkIds(authCtx.userId);
+  return memberships.length === 1 ? memberships[0] : null;
+}
+
+/**
+ * 能不能往这个网络写**面向 Agent 的东西**(派任务、改节点、排程……)。
+ * 受限成员在受限网络里恒为 false(fail-closed);给授权 Agent 发任务的路径另用
+ * canMessageAgent 单独放行,人类侧的写入(私信、需求、上传)用 canRestWriteNetworkAsHuman。
+ */
+export function canRestWriteNetwork(authCtx: { userId: string; networkId: string | null } | null, networkId: string | null, isAdmin: boolean): boolean {
+  if (!canRestWriteNetworkAsHuman(authCtx, networkId, isAdmin)) return false;
+  if (!authCtx || isAdmin || !networkId) return true;
+  return !isAgentRestricted(authCtx.userId, networkId);
+}
+
+/** 旧的「成员且不是 viewer」判据,不看 Agent 授权。只给人类侧写入用。 */
+export function canRestWriteNetworkAsHuman(authCtx: { userId: string; networkId: string | null } | null, networkId: string | null, isAdmin: boolean): boolean {
+  if (!authCtx) return true; // legacy global token or open dev mode
+  if (isAdmin) return true;
+  if (!networkId) return false;
+  const role = getUserNetworkRole(authCtx.userId, networkId);
+  return !!role && role !== "viewer";
+}

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,217 @@
+// 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;
+
+// 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(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));
+}, 30_000);
+
+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);
+  });
+});