@sleep2agi/commhub-server 0.9.0-preview.5 → 0.9.0-preview.50

package/src/rest-identity.test.ts

@@ -0,0 +1,129 @@
+// REST from_session identity binding.
+//
+// Run: COMMHUB_DB=/tmp/rest-identity-test.db bun test src/rest-identity.test.ts
+// (COMMHUB_DB must be set explicitly — unset defaults to the production DB.)
+//
+// Assertion discipline: results are compared with toEqual against the whole
+// object, so a widened accepted-set fails instead of silently passing.
+
+import { describe, expect, test } from "bun:test";
+import { nodeAliasForToken, resolveRestFromSession } from "./rest-identity.js";
+
+const NTOK = "ntok_abc123";
+const UTOK = "utok_abc123";
+
+describe("REST from_session identity binding", () => {
+  test("node token claiming another node's alias is refused", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: "通信龙",
+    })).toEqual({
+      ok: false,
+      error: "from_session_identity_mismatch",
+      message: "network token from_session does not match token-bound node alias",
+      tokenAlias: "通信IM牛",
+      requestedFromSession: "通信龙",
+    });
+  });
+
+  test("node token omitting from is bound to its own alias, not 'api'", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: undefined,
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  test("node token claiming its own alias is accepted", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: "通信IM牛",
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  test("whitespace padding does not defeat the comparison", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: "  通信IM牛  ",
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  // The Dashboard posts as its logged-in user; this path must not change.
+  test("user token keeps the previous behaviour", () => {
+    expect(resolveRestFromSession({
+      token: UTOK,
+      tokenName: "dashboard",
+      requestedFrom: "admin",
+    })).toEqual({ ok: true, fromSession: "admin" });
+  });
+
+  test("user token with no from defaults to the authenticated username", () => {
+    expect(resolveRestFromSession({
+      token: UTOK,
+      tokenName: null,
+      authenticatedUsername: "admin",
+      requestedFrom: undefined,
+    })).toEqual({ ok: true, fromSession: "admin" });
+  });
+
+  test("legacy user auth without a username still falls back to 'api'", () => {
+    expect(resolveRestFromSession({
+      token: UTOK,
+      tokenName: null,
+      requestedFrom: undefined,
+    })).toEqual({ ok: true, fromSession: "api" });
+  });
+
+  // A non-string `from` must not be coerced into an identity.
+  test("non-string from is not treated as a claim", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: { toString: () => "通信龙" },
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  // A network-bound token we cannot resolve to an alias must not be able to
+  // call itself anything. Found by independent review of this change.
+  describe("ntok_ with an unresolvable alias fails closed", () => {
+    for (const tokenName of ["node:", "node:   ", "dashboard", null, undefined]) {
+      test(`claim is refused when tokenName is ${JSON.stringify(tokenName)}`, () => {
+        expect(resolveRestFromSession({
+          token: NTOK,
+          tokenName,
+          requestedFrom: "通信龙",
+        })).toEqual({
+          ok: false,
+          error: "from_session_identity_mismatch",
+          message: "network token has no resolvable node alias and may not claim a from_session",
+          tokenAlias: "",
+          requestedFromSession: "通信龙",
+        });
+      });
+    }
+
+    test("no claim at all still resolves to 'api'", () => {
+      expect(resolveRestFromSession({
+        token: NTOK,
+        tokenName: "node:",
+        requestedFrom: undefined,
+      })).toEqual({ ok: true, fromSession: "api" });
+    });
+  });
+
+  describe("nodeAliasForToken", () => {
+    test("only ntok_ + node: prefix yields an alias", () => {
+      expect(nodeAliasForToken(NTOK, "node:X")).toBe("X");
+      // A user token whose name merely looks node-shaped must not bind.
+      expect(nodeAliasForToken(UTOK, "node:X")).toBeNull();
+      // A node token whose name is not node-scoped must not bind.
+      expect(nodeAliasForToken(NTOK, "dashboard")).toBeNull();
+      expect(nodeAliasForToken(NTOK, null)).toBeNull();
+      // `node:` with nothing after it is not an identity.
+      expect(nodeAliasForToken(NTOK, "node:   ")).toBeNull();
+    });
+  });
+});

package/src/rest-identity.ts

@@ -0,0 +1,100 @@
+// REST from_session identity binding.
+//
+// Both transports resolve the same `api_tokens` row through resolveToken, and
+// auth.ts already states the invariant:
+//
+//   "Network-bound node tokens are an identity boundary: they must not spoof
+//    another node via from_session."
+//
+// tools.ts enforced it for MCP (defaultFrom + fromIdentityMismatchReply).
+// POST /api/task did not — it took `body.from` verbatim, so any node holding
+// its own ntok_ could claim another node's alias. That value is stored on the
+// task row and, once sender labels reach the copresence TUIs, rendered to a
+// human as an attribution.
+//
+// This is the same decision expressed as a pure function so every credential
+// kind is a directly constructible test input rather than a hand-assembled
+// Request (the #503 convention in this codebase).
+
+export interface RestIdentityInput {
+  /** Raw bearer token, only its prefix matters (`ntok_` = network-bound). */
+  token: string;
+  /** `api_tokens.name`; for node tokens it is `node:<alias>`. */
+  tokenName: string | null | undefined;
+  /** Username resolved from the authenticated token. */
+  authenticatedUsername?: string | null;
+  /** Caller-supplied `body.from`. */
+  requestedFrom: unknown;
+}
+
+export type RestIdentityResult =
+  | { ok: true; fromSession: string }
+  | {
+      ok: false;
+      error: "from_session_identity_mismatch";
+      message: string;
+      tokenAlias: string;
+      requestedFromSession: string;
+    };
+
+/** Alias a token is bound to, or null when it is not node-scoped. */
+export function nodeAliasForToken(token: string, tokenName: string | null | undefined): string | null {
+  if (!token.startsWith("ntok_")) return null;
+  if (typeof tokenName !== "string" || !tokenName.startsWith("node:")) return null;
+  const alias = tokenName.slice("node:".length).trim();
+  return alias || null;
+}
+
+export function resolveRestFromSession(input: RestIdentityInput): RestIdentityResult {
+  const alias = nodeAliasForToken(input.token, input.tokenName);
+  const requested = typeof input.requestedFrom === "string" ? input.requestedFrom.trim() : "";
+
+  // A network-bound token whose name we cannot resolve to an alias (`node:`,
+  // `node:   `, or a name that was never node-scoped) is the degenerate case.
+  // We know it IS a node credential; we just cannot tell WHICH node. Letting it
+  // claim anything is the worst available option, so refuse the claim outright
+  // rather than falling through to the unbound path.
+  //
+  // Production always writes `node:${nodeName}`, so this costs nothing real —
+  // but "we couldn't identify you, so you may call yourself anything" is
+  // exactly the fail-open shape this change exists to remove.
+  if (!alias && input.token.startsWith("ntok_")) {
+    if (requested) {
+      return {
+        ok: false,
+        error: "from_session_identity_mismatch",
+        message: "network token has no resolvable node alias and may not claim a from_session",
+        tokenAlias: "",
+        requestedFromSession: requested,
+      };
+    }
+    return { ok: true, fromSession: "api" };
+  }
+
+  // A user-token client normally does not need to repeat its identity in every
+  // request. Prefer an explicit, backwards-compatible claim when present;
+  // otherwise attribute the task to the authenticated username. Falling back
+  // to the transport label `api` is reserved for legacy auth contexts where
+  // the server genuinely has no user identity.
+  if (!alias) {
+    const authenticatedUsername = typeof input.authenticatedUsername === "string"
+      ? input.authenticatedUsername.trim()
+      : "";
+    return { ok: true, fromSession: requested || authenticatedUsername || "api" };
+  }
+
+  // Node token claiming somebody else — refuse rather than silently rewrite,
+  // so a misconfigured caller is visible instead of quietly relabelled.
+  if (requested && requested !== alias) {
+    return {
+      ok: false,
+      error: "from_session_identity_mismatch",
+      message: "network token from_session does not match token-bound node alias",
+      tokenAlias: alias,
+      requestedFromSession: requested,
+    };
+  }
+
+  // Node token, no claim or a matching one: bind to the token's own alias.
+  return { ok: true, fromSession: alias };
+}

package/src/rest-projections.ts

@@ -0,0 +1,67 @@
+/**
+ * Stable REST row projections.
+ *
+ * These lists deliberately mirror the fields already exposed by the public
+ * endpoints before #311.  Keeping them in one place makes the wire contract
+ * independent from future ALTER TABLE migrations: adding a storage-only
+ * column must never silently add a REST response key.
+ */
+export const NETWORK_REST_COLUMNS = [
+  "network_id", "network_name", "owner_id", "description", "settings",
+  "created_at", "updated_at", "visibility", "max_members",
+] as const;
+
+export const SESSION_REST_COLUMNS = [
+  "resume_id", "alias", "tmux_name", "server", "ip", "hostname", "agent",
+  "project_dir", "version", "status", "task", "output", "progress", "score",
+  "cpu_load_1min", "cpu_cores", "mem_total_gb", "mem_used_gb", "mem_avail_gb",
+  "disk_total_gb", "disk_used_gb", "disk_avail_gb", "process_rss_bytes",
+  "process_rss_mb", "process_cpu_pct", "process_uptime_seconds",
+  "process_in_flight_count", "network_id", "registered_at", "updated_at",
+  "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
+  "external_schedules",
+] as const;
+
+export const AUDIT_LOG_REST_COLUMNS = [
+  "id", "user_id", "username", "action", "target_type", "target_id", "detail",
+  "ip", "network_id", "created_at",
+] as const;
+
+export const TASK_EVENT_REST_COLUMNS = [
+  "id", "task_id", "from_status", "to_status", "event_type", "actor", "detail",
+  "created_at", "network_id",
+] as const;
+
+export const TASK_REST_COLUMNS = [
+  "task_id", "from_node_id", "from_name", "to_node_id", "to_name", "priority",
+  "status", "content", "result", "in_reply_to", "requires_response", "scope",
+  "created_at", "delivered_at", "started_at", "runtime_submitted_at", "consumed_at", "completed_at", "expires_at",
+  "network_id", "parent_task_id", "meta_json", "thread_id", "turn_id",
+] as const;
+
+export const COMPLETION_REST_COLUMNS = [
+  "id", "session_name", "task", "result", "artifacts", "score",
+  "duration_minutes", "network_id", "completed_at",
+] as const;
+
+// Storage projection for scheduled-task rows. `created_by` and
+// `schedule_json` are intentionally selected for server-side auth/decoding,
+// then removed by decodeRow before the REST response is serialized.
+export const SCHEDULED_TASK_STORAGE_COLUMNS = [
+  "schedule_id", "network_id", "created_by", "name", "target_node_id",
+  "target_alias", "task_content", "priority", "schedule_type", "schedule_json",
+  "timezone", "overlap_policy", "misfire_policy", "status", "next_run_at",
+  "last_run_at", "revision", "created_at", "updated_at",
+] as const;
+
+export function sqlColumns(columns: readonly string[], qualifier?: string): string {
+  return columns.map((column) => qualifier ? `${qualifier}.${column}` : column).join(", ");
+}
+
+export const NETWORK_REST_SELECT = sqlColumns(NETWORK_REST_COLUMNS);
+export const SESSION_REST_SELECT = sqlColumns(SESSION_REST_COLUMNS);
+export const AUDIT_LOG_REST_SELECT = sqlColumns(AUDIT_LOG_REST_COLUMNS);
+export const TASK_EVENT_REST_SELECT = sqlColumns(TASK_EVENT_REST_COLUMNS);
+export const TASK_REST_SELECT = sqlColumns(TASK_REST_COLUMNS);
+export const COMPLETION_REST_SELECT = sqlColumns(COMPLETION_REST_COLUMNS);
+export const SCHEDULED_TASK_STORAGE_SELECT = sqlColumns(SCHEDULED_TASK_STORAGE_COLUMNS);

package/src/rest-write-network-resolution.test.ts

@@ -0,0 +1,133 @@
+// #819 — `resolveRestWriteNetworkId` 是 network-scope.ts 里唯一没有任何测试点名的
+// 导出函数。同文件的五个兄弟各有 1-2 个测试文件点名它们:
+//
+//   resolveRestNetworkScope  1        canRestWriteNetwork  1
+//   singleNetworkId          2        addNetworkScope      1
+//   getUserNetworkIds        1        resolveRestWriteNetworkId  🔴 0
+//
+// 而它决定的是**一次 REST 写入落到哪个网络**。它的 docstring 说明了一条不显然的
+// 规则:管理员的**读**作用域按设计是全局的(networkIds=null),所以它本身表达不了
+// 「这个管理员恰好只属于一个网络」;而**写**不能继承这个歧义 —— 只有在确实只有
+// 一个成员关系时才用它,0 个或 ≥2 个都必须显式指定网络。
+//
+// 🔴 这条规则的两半都要钉:
+//   - **放行那半**(admin + 恰好 1 个成员关系 → 用它)如果坏了,会退化成「管理员
+//     写任何东西都要显式带 network_id」——很吵,但**安全**,所以没人会急着修;
+//   - **收紧那半**(admin + 0 或 ≥2 → null)如果坏了,一次写入会**落到一个没被
+//     指定的网络里**,而调用方看到的是成功。
+//
+// 只写反向断言是不够的:一个「永远返回 null」的实现能通过所有「收紧」用例。
+// 所以每一条收紧断言都配了正控。
+//
+// Run: COMMHUB_DB=/tmp/819-rest-write-scope.db bun test src/rest-write-network-resolution.test.ts
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { resolveRestNetworkScope, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
+
+const NET_A = "net_819_a";
+const NET_B = "net_819_b";
+const U_SINGLE = "u819_single";   // 只属于 NET_A
+const U_MULTI = "u819_multi";     // 属于 NET_A + NET_B
+const U_NONE = "u819_none";       // 一个都不属于
+const ALL_USERS = [U_SINGLE, U_MULTI, U_NONE];
+
+function cleanup() {
+  try { db.run("DELETE FROM network_members WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  for (const u of ALL_USERS) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [u]); } catch {}
+  }
+}
+
+function seed() {
+  for (const u of ALL_USERS) {
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role, created_at)
+       VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+      [u, u],
+    );
+  }
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_A, U_SINGLE]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_B, U_MULTI]);
+  const member = (u: string, net: string, role: string) =>
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [u, net, role]);
+  member(U_SINGLE, NET_A, "owner");
+  member(U_MULTI, NET_A, "member");
+  member(U_MULTI, NET_B, "owner");
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterAll(() => { cleanup(); });
+
+/** 管理员的读作用域:全局(networkIds=null),这正是歧义的来源。 */
+const ADMIN_SCOPE: RestNetworkScope = { networkIds: null };
+const scopeOf = (...ids: string[]): RestNetworkScope => ({ networkIds: ids });
+const ctx = (userId: string) => ({ userId, networkId: null });
+
+describe("#819 resolveRestWriteNetworkId — 作用域里就能确定时,直接用它", () => {
+  test("作用域恰好一个网络 → 用那一个(与是不是 admin 无关)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A), ctx(U_MULTI), false)).toBe(NET_A);
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A), ctx(U_MULTI), true)).toBe(NET_A);
+  });
+
+  test("作用域两个网络 → 歧义,null(即使调用者是 admin)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A, NET_B), ctx(U_MULTI), true)).toBeNull();
+  });
+
+  // 🔴 这一条我一开始断错了,留下来当记录:我以为「作用域为空数组 → null」,
+  // 实测是 NET_A。原因是 `[]` 过不了 singleNetworkId,于是落到 admin 的成员关系
+  // 回退分支,而 U_SINGLE 恰好只有一个成员关系。
+  //
+  // 而 `networkIds: []` 在 resolveRestNetworkScope 里有确切含义:`:46` 那一行,
+  // **非 admin 请求了一个自己没有角色的网络** —— 它带着 `denied: "access denied
+  // to requested network"`。也就是说 `[]` 不是「没指定」,是「明确被拒」。
+  //
+  // 现在**没有**问题,因为那一行只对非 admin 产生(admin 在 `:42` 就提前返回
+  // networkIds:null 了),而非 admin 走到这里必然 null —— 见下一条。
+  //
+  // 但它是一个潜伏的形状:如果将来有任何路径让 admin 拿到 networkIds: [],
+  // 这次写入会**忽略那条明确的拒绝**,回退到他的单一成员关系。所以两条都钉住:
+  // 当前行为,以及那条让它安全的前提。
+  test("作用域为空数组 + admin + 恰好一个成员关系 → 回退到成员关系(当前行为,记录)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(), ctx(U_SINGLE), true)).toBe(NET_A);
+  });
+
+  test("🔴 让上一条安全的前提:空数组作用域只由非 admin 产生,而非 admin → null", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(), ctx(U_SINGLE), false)).toBeNull();
+    // 前提本身也断一次:resolveRestNetworkScope 对 admin 从不产出空数组。
+    const adminScope = resolveRestNetworkScope(NET_B, ctx(U_NONE), true);
+    expect(adminScope.networkIds).toBeNull();
+  });
+});
+
+describe("#819 admin 的全局读作用域不能替写入决定网络", () => {
+  test("🔴 admin + 恰好 1 个成员关系 → 用那一个(放行那半)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_SINGLE), true)).toBe(NET_A);
+  });
+
+  test("🔴 admin + 2 个成员关系 → null,必须显式指定(收紧那半)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_MULTI), true)).toBeNull();
+  });
+
+  test("🔴 admin + 0 个成员关系 → null(不能因为读是全局的就随便挑一个)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_NONE), true)).toBeNull();
+  });
+
+  test("非 admin + 全局作用域 → null(这种组合本身就不该发生,fail closed)", () => {
+    // 正控在上面那条「admin + 单成员 → NET_A」:如果实现改成永远 null,那条会红。
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_SINGLE), false)).toBeNull();
+  });
+
+  test("没有 authCtx + 全局作用域 → null", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, null, true)).toBeNull();
+  });
+});
+
+describe("#819 作用域优先于成员关系回退", () => {
+  test("作用域说 NET_B,而该用户唯一的成员关系是 NET_A → 结果是 NET_B", () => {
+    // 归属由作用域决定,不由「他碰巧属于哪个网络」决定。
+    // 如果实现把两者的优先级搞反,这条会返回 NET_A。
+    expect(resolveRestWriteNetworkId(scopeOf(NET_B), ctx(U_SINGLE), true)).toBe(NET_B);
+  });
+});

package/src/rules-file-transport.test.ts

@@ -0,0 +1,235 @@
+// app#225 — 节点规则文件远程读写：走真 MCP in-process transport 的端到端。
+//
+// 验的是 #225 验收里 hub 能验的那几条：
+//   1. 客户端只用 node_id 就能发起读/写；工具的 inputSchema 里**没有**任何
+//      路径/文件名字段（验收第 5 条「不能借路径参数写任意文件」在 hub 侧的形状）。
+//   2. 节点用网络 token + alias 拉到的请求里也没有路径字段；ack 后客户端轮询拿到内容。
+//   3. SEC-1：跨网络节点发不了、别的节点 ack 不了、用户 token 拉不了。
+//   4. 单飞 + 超时回收。
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/rules.db bun test src/rules-file-transport.test.ts
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_rules_file";
+const OTHER_NET = "net_rules_file_other";
+const USER = "u_rules_file_owner";
+const NODE_ID = "node_rules_file_claude";
+const NODE_ALIAS = "rules-file-claude";
+const OTHER_NODE_ID = "node_rules_file_other";
+const OTHER_NODE_ALIAS = "rules-file-other";
+const NODE_TOKEN = "tok_rules_file_node";
+const OTHER_NODE_TOKEN = "tok_rules_file_other_node";
+
+function cleanup() {
+  for (const net of [NET, OTHER_NET]) {
+    try { db.run("DELETE FROM node_rules_requests WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM audit_log WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM nodes WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM network_members WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM networks WHERE network_id = ?1", [net]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [USER]); } catch {}
+}
+
+function seedWorld() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [USER, USER],
+  );
+  for (const net of [NET, OTHER_NET]) {
+    db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [net, net, USER]);
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [USER, net]);
+  }
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [NODE_ID, NODE_ALIAS, NODE_ALIAS, NET],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [OTHER_NODE_ID, OTHER_NODE_ALIAS, OTHER_NODE_ALIAS, OTHER_NET],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [NODE_TOKEN, USER, NET, `node:${NODE_ALIAS}`, "hash_rules_file_node"],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [OTHER_NODE_TOKEN, USER, OTHER_NET, `node:${OTHER_NODE_ALIAS}`, "hash_rules_file_other"],
+  );
+}
+
+type Identity = { net: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_rules_file_user" };
+const asNode: Identity = { net: NET, alias: NODE_ALIAS, isNetworkToken: true, tokenId: NODE_TOKEN };
+const asOtherNode: Identity = { net: OTHER_NET, alias: OTHER_NODE_ALIAS, isNetworkToken: true, tokenId: OTHER_NODE_TOKEN };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "rules-file-test", version: "1" });
+  registerTools(server, undefined, id.net, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "rules-file-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const first = r.content?.[0];
+    if (!first || first.type !== "text") throw new Error(`no text result from ${name}`);
+    return JSON.parse(first.text);
+  };
+  const close = async () => { await client.close(); await server.close(); };
+  return { client, server, call, close };
+}
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+describe("app#225 rules file — schema has no path", () => {
+  test("read/write tool inputs are node id + content only; no path / file_name / dir field anywhere", async () => {
+    // 🔴 不走 client.listTools():main 上 report_status / send_desktop_message /
+    // update_node_config / create_node 四个存量工具的 zod 形状让 SDK 的
+    // toJSONSchema 抛 `schema._zod`,listTools 整个失败(与本 PR 无关,实验见
+    // PR 正文)。这里直接看 McpServer 登记表里的 zod shape —— 它就是 hub 校验
+    // 入参用的那份,比 JSON schema 更接近真相。
+    const u = await connect(asUser);
+    try {
+      const reg: Record<string, any> = (u.server as any)._registeredTools;
+      const shapeKeys = (name: string): string[] => {
+        expect(reg[name], name).toBeDefined();
+        const schema = reg[name].inputSchema;
+        const shape = schema?.shape ?? schema?._def?.shape?.() ?? schema ?? {};
+        return Object.keys(shape).sort();
+      };
+      expect(shapeKeys("read_node_rules_file")).toEqual(["child_node_id", "network_id", "node_id"]);
+      expect(shapeKeys("write_node_rules_file")).toEqual(["child_node_id", "content", "network_id", "node_id"]);
+      expect(shapeKeys("get_rules_file_request")).toEqual([]);
+      // ack 的 file_name 是节点**回报**它用了哪个文件,不是客户端**指定**用哪个文件。
+      expect(shapeKeys("ack_rules_file_request")).toEqual(["content", "error", "exists", "file_name", "request_id", "status"]);
+      expect(shapeKeys("get_rules_file_result")).toEqual(["network_id", "request_id"]);
+      for (const name of ["read_node_rules_file", "write_node_rules_file", "get_rules_file_request", "get_rules_file_result"]) {
+        for (const k of shapeKeys(name)) expect(k, `${name}.${k}`).not.toMatch(/path|dir|file|cwd/i);
+      }
+    } finally { await u.close(); }
+  }, 20_000);
+});
+
+describe("app#225 rules file — read round trip", () => {
+  test("user enqueues read → node pulls (no path in request) → acks content → user polls done", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: NODE_ID });
+      expect(enq).toMatchObject({ ok: true, op: "read" });
+      expect(enq.request_id).toMatch(/^rf_/);
+
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, status: "pending", op: "read" });
+
+      const pulled = await n.call("get_rules_file_request", {});
+      expect(pulled.ok).toBe(true);
+      expect(Object.keys(pulled.request).sort()).toEqual(["op", "request_id"]);
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "read" });
+      // 第二次拉:已经 in_progress,不再重复下发
+      expect(await n.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+
+      expect(await n.call("ack_rules_file_request", {
+        request_id: enq.request_id, status: "done", file_name: "CLAUDE.md", exists: true, content: "# 规则\n",
+      })).toMatchObject({ ok: true, status: "done" });
+
+      const res = await u.call("get_rules_file_result", { request_id: enq.request_id });
+      expect(res).toMatchObject({ ok: true, status: "done", op: "read", file_name: "CLAUDE.md", exists: true, content: "# 规则\n", error: null });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+
+  test("write: content travels to the node verbatim; result carries no content back", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const body = "# new rules\n\n- 不碰生产 DB\n";
+      const enq = await u.call("write_node_rules_file", { node_id: NODE_ID, content: body });
+      expect(enq).toMatchObject({ ok: true, op: "write" });
+      const pulled = await n.call("get_rules_file_request", {});
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "write", content: body });
+      await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "CLAUDE.md", exists: true });
+      const res = await u.call("get_rules_file_result", { request_id: enq.request_id });
+      expect(res).toMatchObject({ ok: true, status: "done", op: "write", file_name: "CLAUDE.md" });
+      expect(res.content).toBeUndefined();
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+
+  test("node failure is surfaced with its reason", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const enq = await u.call("write_node_rules_file", { node_id: NODE_ID, content: "x" });
+      await n.call("get_rules_file_request", {});
+      await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "failed", file_name: "CLAUDE.md", error: "EACCES: permission denied" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, status: "failed", error: "EACCES: permission denied" });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});
+
+describe("app#225 rules file — SEC-1 and lifecycle", () => {
+  test("cross-network node cannot be targeted", async () => {
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("read_node_rules_file", { node_id: OTHER_NODE_ID })).toMatchObject({ ok: false, error: "cross_network_node" });
+      expect(db.get<{ c: number }>("SELECT COUNT(*) AS c FROM node_rules_requests WHERE node_id = ?1", OTHER_NODE_ID)?.c).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("a node in another network can neither pull nor ack this node's request", async () => {
+    const u = await connect(asUser);
+    const o = await connect(asOtherNode);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: NODE_ID });
+      expect(await o.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+      expect(await o.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "stolen" })).toMatchObject({ ok: true, ignored: "unknown_or_foreign_request" });
+      expect(db.get<{ status: string }>("SELECT status FROM node_rules_requests WHERE request_id = ?1", enq.request_id)?.status).toBe("pending");
+    } finally { await u.close(); await o.close(); }
+  }, 20_000);
+
+  test("user token (not a network token) cannot use the node-side pull/ack", async () => {
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("get_rules_file_request", {})).toMatchObject({ ok: false, error: "network_token_required" });
+      expect(await u.call("ack_rules_file_request", { request_id: "rf_nope", status: "done" })).toMatchObject({ ok: false, error: "network_token_required" });
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("single flight: a second request while one is pending is refused; a stale one is superseded", async () => {
+    const u = await connect(asUser);
+    try {
+      const first = await u.call("read_node_rules_file", { node_id: NODE_ID });
+      expect(await u.call("read_node_rules_file", { node_id: NODE_ID })).toMatchObject({ ok: false, error: "request_in_flight", existing_request_id: first.request_id });
+      db.run("UPDATE node_rules_requests SET created_at = ?1 WHERE request_id = ?2", [Date.now() - 120_000, first.request_id]);
+      const second = await u.call("read_node_rules_file", { node_id: NODE_ID });
+      expect(second.ok).toBe(true);
+      expect(db.get<{ status: string }>("SELECT status FROM node_rules_requests WHERE request_id = ?1", first.request_id)?.status).toBe("timeout");
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("polling a request the node never answered flips it to timeout with a readable reason", async () => {
+    const u = await connect(asUser);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: NODE_ID });
+      db.run("UPDATE node_rules_requests SET created_at = ?1 WHERE request_id = ?2", [Date.now() - 120_000, enq.request_id]);
+      const res = await u.call("get_rules_file_result", { request_id: enq.request_id });
+      expect(res).toMatchObject({ ok: true, status: "timeout" });
+      expect(res.error).toMatch(/did not answer/);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("oversized content is refused before anything is queued", async () => {
+    const u = await connect(asUser);
+    try {
+      const r: any = await u.client.callTool({ name: "write_node_rules_file", arguments: { node_id: NODE_ID, content: "x".repeat(256 * 1024 + 1) } });
+      expect(r.isError).toBe(true);
+      expect(db.get<{ c: number }>("SELECT COUNT(*) AS c FROM node_rules_requests WHERE node_id = ?1", NODE_ID)?.c).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+});