@sleep2agi/commhub-server 0.9.0-preview.0 → 0.9.0-preview.100

package/src/node-permissions.ts

@@ -0,0 +1,242 @@
+// RFC-041 第一阶段(board #487):节点(Agent)自己的权限 —— 先记录、后执行。
+//
+// 节点的权限 = 主人的权限 ∩ 节点的模式(nodes.permission_mode:normal 正常 / readonly 只读 / restricted 受限)。
+//
+//   • 模式是主人主动设的,**设了就立刻生效**(不看开关):只读的节点写什么都拒(mode_readonly);
+//     受限的节点只碰派给它的任务、派活只给主人授权的 Agent(mode_restricted_not_assigned / agent_not_granted_to_owner)。
+//   • 正常模式下的收紧(超出主人可见范围 beyond_owner_visibility、主人没被授权的 Agent agent_not_granted_to_owner、
+//     只有人能做的事 human_only)由 Hub 开关 COMMHUB_NODE_PERMISSIONS 决定:
+//       log(默认)—— 照常放行,只把「本来会被拒」按 (节点, 路由, 原因, 小时) 合并记进 node_permission_log;
+//       enforce   —— 记录并拒绝(REST 403 / MCP 错误 node_permission_denied + reason + hint);
+//       off       —— 不判也不记(显式模式仍然生效)。
+//
+// 判定的入口:REST(requirements.ts、/api/task、/api/broadcast、/api/nodes/:id 写)、MCP(tools.ts 按工具名包一层)、
+// SSE(/events/:session、/events/network/:id)。只对节点令牌(ntok_)生效;用户令牌一条不变。
+// 只增不改:nodes 多一列 permission_mode(默认 normal),新表 node_permission_log。回滚到上一版安全:旧代码不读它们。
+
+import { db } from "./db.js";
+import { canMessageAgent, type AgentRef } from "./agent-access.js";
+
+export type NodePermissionMode = "normal" | "readonly" | "restricted";
+export const NODE_PERMISSION_MODES: readonly NodePermissionMode[] = ["normal", "readonly", "restricted"];
+export type NodePermissionsFlag = "log" | "off" | "enforce";
+export type NodePermissionReason =
+  | "beyond_owner_visibility"
+  | "agent_not_granted_to_owner"
+  | "mode_readonly"
+  | "mode_restricted_not_assigned"
+  | "human_only"
+  | "owner_unknown";
+
+/** 显式模式的原因:不看开关,永远拒。 */
+const MODE_REASONS: ReadonlySet<NodePermissionReason> = new Set(["mode_readonly", "mode_restricted_not_assigned"]);
+
+try { db.exec("ALTER TABLE nodes ADD COLUMN permission_mode TEXT NOT NULL DEFAULT 'normal'"); } catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+db.exec(`
+  CREATE TABLE IF NOT EXISTS node_permission_log (
+    network_id TEXT NOT NULL,
+    node_id    TEXT NOT NULL,
+    route      TEXT NOT NULL,
+    reason     TEXT NOT NULL,
+    hour       TEXT NOT NULL,
+    hits       INTEGER NOT NULL DEFAULT 1,
+    sample     TEXT,
+    PRIMARY KEY (network_id, node_id, route, reason, hour)
+  );
+  CREATE INDEX IF NOT EXISTS idx_node_permission_log_hour ON node_permission_log(network_id, hour);
+`);
+
+/** 开关。未设 / 写错 → log(安全的默认:只记不拦)。每次现读:测试和运维改环境变量后无需重启模块。 */
+export function nodePermissionsFlag(): NodePermissionsFlag {
+  const raw = (process.env.COMMHUB_NODE_PERMISSIONS ?? "").trim().toLowerCase();
+  return raw === "off" || raw === "enforce" ? raw : "log";
+}
+
+export type NodeIdentity = {
+  networkId: string;
+  /** 绑定的节点;老的未绑定令牌 = null(按「正常」判,记录时用 token:<token_id>)。 */
+  nodeId: string | null;
+  logKey: string;
+  aliases: string[];
+  ownerUserId: string | null;
+  mode: NodePermissionMode;
+};
+
+function normalizeMode(raw: unknown): NodePermissionMode {
+  return raw === "readonly" || raw === "restricted" ? raw : "normal";
+}
+
+/** 节点令牌 → 节点身份(一次带索引的查询)。不是节点令牌 / 查不到 → null。 */
+export function nodeIdentity(tokenId: string | null | undefined, networkId: string | null | undefined): NodeIdentity | null {
+  if (!tokenId || !networkId) return null;
+  const row = db.get<{ user_id: string | null; bound_node_id: string | null; name: string | null; owner_user_id: string | null; permission_mode: string | null; alias: string | null }>(
+    `SELECT t.user_id, t.bound_node_id, t.name, n.owner_user_id, n.permission_mode, n.alias
+       FROM api_tokens t LEFT JOIN nodes n ON n.node_id = t.bound_node_id
+      WHERE t.token_id = ?1 AND t.network_id = ?2`,
+    tokenId, networkId,
+  );
+  if (!row) return null;
+  const aliases = new Set<string>();
+  if (row.alias) aliases.add(row.alias);
+  if (row.name?.startsWith("node:")) aliases.add(row.name.slice(5));
+  return {
+    networkId,
+    nodeId: row.bound_node_id,
+    logKey: row.bound_node_id ?? `token:${tokenId}`,
+    aliases: [...aliases],
+    ownerUserId: row.owner_user_id || row.user_id || null,
+    mode: normalizeMode(row.permission_mode),
+  };
+}
+
+export type Verdict = { reason: NodePermissionReason; sample?: string } | null;
+
+/**
+ * 判一次:verdict=null → 放行;否则按原因和开关决定拒不拒,并记一行(off 时正常模式的原因不记)。
+ * 返回 true = 拒绝。
+ */
+export function nodeDecide(id: NodeIdentity, route: string, verdict: Verdict): boolean {
+  if (!verdict) return false;
+  const explicit = MODE_REASONS.has(verdict.reason);
+  const flag = nodePermissionsFlag();
+  if (!explicit && flag === "off") return false;
+  recordNodePermission(id, route, verdict.reason, verdict.sample);
+  return explicit || flag === "enforce";
+}
+
+const HINTS: Record<NodePermissionReason, string> = {
+  beyond_owner_visibility: "this node acts with its owner's permissions, and its owner cannot see or edit this; ask the owner for access, or assign the task to this node",
+  agent_not_granted_to_owner: "this Agent has not been granted to this node's owner; ask a network admin to grant it",
+  mode_readonly: "this node is in read-only mode; the node's owner can switch it to normal in the app",
+  mode_restricted_not_assigned: "this node is in restricted mode and only touches tasks assigned to it; assign the task to this node, or have the owner switch it to normal",
+  human_only: "only people can do this (members, projects, permissions, providers, secrets, other nodes); use a user token",
+  owner_unknown: "this node's owner is unknown; recreate the node token from the owner's account",
+};
+
+export function nodePermissionDeniedBody(reason: NodePermissionReason, route: string): { ok: false; error: "node_permission_denied"; reason: NodePermissionReason; route: string; hint: string } {
+  return { ok: false, error: "node_permission_denied", reason, route, hint: HINTS[reason] };
+}
+
+// ── 记录:按 (网络, 节点, 路由, 原因, 小时) 合并;有上限、会清理 ──
+export const LOG_RETENTION_DAYS = 30;
+export const LOG_MAX_ROWS = 20_000;
+const PRUNE_EVERY_MS = 60 * 60 * 1000;
+let lastPrune = 0;
+let logFull = false;
+
+function hourOf(now = new Date()): string {
+  return now.toISOString().slice(0, 13); // 2026-10-03T08
+}
+
+/** 清掉保留期外的行,并重新判断是否到了上限(到上限后只给已有的行加次数,不再新开行)。 */
+export function pruneNodePermissionLog(now = new Date()): void {
+  const cutoff = hourOf(new Date(now.getTime() - LOG_RETENTION_DAYS * 86_400_000));
+  db.run("DELETE FROM node_permission_log WHERE hour < ?1", [cutoff]);
+  const n = Number(db.get<{ n: number | string }>("SELECT COUNT(*) AS n FROM node_permission_log")?.n ?? 0);
+  logFull = n >= LOG_MAX_ROWS;
+  lastPrune = now.getTime();
+}
+
+export function recordNodePermission(id: NodeIdentity, route: string, reason: NodePermissionReason, sample?: string): void {
+  try {
+    const now = new Date();
+    if (now.getTime() - lastPrune > PRUNE_EVERY_MS) pruneNodePermissionLog(now);
+    const hour = hourOf(now);
+    const s = sample ? sample.slice(0, 200) : null;
+    const updated = db.run(
+      "UPDATE node_permission_log SET hits = hits + 1, sample = COALESCE(?6, sample) WHERE network_id = ?1 AND node_id = ?2 AND route = ?3 AND reason = ?4 AND hour = ?5",
+      [id.networkId, id.logKey, route.slice(0, 120), reason, hour, s],
+    );
+    if (Number(updated?.changes ?? 0) > 0 || logFull) return;
+    db.run(
+      `INSERT INTO node_permission_log (network_id, node_id, route, reason, hour, hits, sample) VALUES (?1, ?2, ?3, ?4, ?5, 1, ?6)
+       ON CONFLICT(network_id, node_id, route, reason, hour) DO UPDATE SET hits = node_permission_log.hits + 1`,
+      [id.networkId, id.logKey, route.slice(0, 120), reason, hour, s],
+    );
+  } catch (e) {
+    // 记录失败绝不影响请求本身。
+    console.error(`[node-permissions] log failed: ${(e as Error).message}`);
+  }
+}
+
+/** Test-only:让下一次记录先清理一遍,并可改上限判断。 */
+export function __resetNodePermissionLogStateForTest(): void { lastPrune = 0; logFull = false; }
+
+// ── 规则 ──
+
+/** 派活 / 发消息 / 重派给 target。发给自己永远可以。 */
+export function dispatchVerdict(id: NodeIdentity, target: AgentRef): Verdict {
+  if ((target.alias && id.aliases.includes(target.alias)) || (target.nodeId && id.nodeId && target.nodeId === id.nodeId)) return null;
+  const sample = target.alias ?? target.nodeId ?? undefined;
+  if (id.mode === "readonly") return { reason: "mode_readonly", sample };
+  if (!id.ownerUserId) return id.mode === "restricted" ? { reason: "mode_restricted_not_assigned", sample } : { reason: "owner_unknown" };
+  if (!canMessageAgent(id.ownerUserId, id.networkId, target)) {
+    // 受限是主人设的 → 必拒(模式原因);正常下是开关管的收紧。
+    return { reason: id.mode === "restricted" ? "mode_restricted_not_assigned" : "agent_not_granted_to_owner", sample };
+  }
+  return null;
+}
+
+/** 广播:只读 / 受限都不行(会发给没派给它、也未必授权的 Agent)。 */
+export function broadcastVerdict(id: NodeIdentity): Verdict {
+  if (id.mode === "readonly") return { reason: "mode_readonly" };
+  if (id.mode === "restricted") return { reason: "mode_restricted_not_assigned" };
+  if (!id.ownerUserId) return { reason: "owner_unknown" };
+  return null;
+}
+
+/** 一般的写(管节点、提交技能、探测模型…):只读 / 受限拒;正常放行(由各自的既有规则管)。 */
+export function writeVerdict(id: NodeIdentity, sample?: string): Verdict {
+  if (id.mode === "readonly") return { reason: "mode_readonly", sample };
+  if (id.mode === "restricted") return { reason: "mode_restricted_not_assigned", sample };
+  return null;
+}
+
+/** 只有人能做的事。只读 / 受限下报模式原因(那是主人设的、必拒);正常下报 human_only。 */
+export function humanOnlyVerdict(id: NodeIdentity, sample?: string): Verdict {
+  return writeVerdict(id, sample) ?? { reason: "human_only", sample };
+}
+
+/** 订阅别的会话 / 整个网络的推送流:受限不行;正常按主人能不能看到那个 Agent。 */
+export function streamVerdict(id: NodeIdentity, target: AgentRef | "network"): Verdict {
+  if (target !== "network" && ((target.alias && id.aliases.includes(target.alias)) || (target.nodeId && target.nodeId === id.nodeId))) return null;
+  if (id.mode === "restricted") return { reason: "mode_restricted_not_assigned", sample: target === "network" ? "network" : target.alias ?? undefined };
+  if (!id.ownerUserId) return { reason: "owner_unknown" };
+  if (target !== "network" && !canMessageAgent(id.ownerUserId, id.networkId, target)) {
+    return { reason: "beyond_owner_visibility", sample: target.alias ?? undefined };
+  }
+  return null;
+}
+
+// ── MCP:每个工具归一类(test 钉住「每个注册的工具都归了类」,新工具忘了归类会红) ──
+export type ToolClass = "always" | "read" | "dispatch" | "broadcast" | "requirements" | "node_write" | "human_only";
+export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
+  // 回复 / 上报 / 自己的收件箱 / 生命周期协议(节点自己的请求)—— 任何模式都能做
+  report_status: "always", report_completion: "always", get_inbox: "always", ack_inbox: "always",
+  mark_tasks_runtime_submitted: "always", mark_tasks_consumed: "always", send_reply: "always", send_peer_reply: "always", send_ack: "always",
+  get_config_update: "always", ack_config_update: "always", get_rules_file_request: "always", ack_rules_file_request: "always", get_rules_file_result: "always",
+  get_create_request: "always", ack_create_request: "always", get_stop_request: "always", ack_stop_request: "always",
+  get_start_request: "always", ack_start_request: "always", get_probe_request: "always", ack_probe_request: "always",
+  list_my_pending_create_requests: "always", list_my_pending_lifecycle_requests: "always", list_my_children: "always",
+  send_desktop_message: "always", // 发给人的私信,不是派活
+  // 读
+  get_all_status: "read", get_session_status: "read", get_task: "read", list_tasks: "read", get_completions: "read",
+  list_skills: "read", get_skill: "read", list_host_supervisors: "read", list_network_secrets: "read", list_providers: "read",
+  get_probe_results: "read", read_node_rules_file: "read", list_node_skills: "read", read_node_skill: "read", list_node_files: "read",
+  read_node_file: "read", tail_node_logs: "read",
+  // 派活
+  send_task: "dispatch", send_message: "dispatch", retry_task: "dispatch", reassign_task: "dispatch", cancel_task: "dispatch",
+  broadcast: "broadcast",
+  // 任务看板:在 requirements.ts 里按卡判(REST 与 MCP 同一处)
+  requirements_list: "requirements", requirements_people: "requirements", requirements_get: "requirements", requirements_create: "requirements",
+  requirements_update: "requirements", requirements_checklist_toggle: "requirements", requirements_upsert_by_external_ref: "requirements",
+  requirements_events: "requirements", requirements_comment: "requirements", projects_list: "requirements",
+  // 写节点 / 技能 / 探测:只读、受限不行;正常由 RFC-036 等既有规则管
+  update_node_config: "node_write", write_node_rules_file: "node_write", restart_node: "node_write", create_node: "node_write",
+  stop_node: "node_write", delete_node: "node_write", start_node: "node_write", submit_skill: "node_write", probe_provider_model: "node_write",
+  // 只有人能做
+  upsert_network_secret: "human_only", upsert_provider: "human_only", update_provider: "human_only",
+  projects_create: "human_only", projects_update: "human_only", review_skill: "human_only",
+};

package/src/node-request-retention.test.ts

@@ -0,0 +1,281 @@
+// node_rules_requests content retention — privacy purge of node file bytes.
+//
+// Real MCP in-process transport, same harness as rules-file-transport.test.ts.
+// Covers:
+//   1. read result is handed out on the first terminal read, still handed out to
+//      a second reader inside the grace window (the desktop app's
+//      request_in_flight → follow path), then purged: status + metadata stay,
+//      `content_purged: true` replaces content.
+//   2. a caller outside the row's network can neither read nor stamp/purge it.
+//   3. TTL sweep: >24h content cleared (stale pending flipped to timeout first),
+//      >30d rows deleted, fresh unread rows untouched.
+//   4. write payload (`content` column) is cleared; skill_read name is kept.
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/nrr.db bun test src/node-request-retention.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";
+import { CONTENT_GRACE_MS, CONTENT_TTL_MS, ROW_TTL_MS, sweepNodeRequestContent } from "./node-request-retention.js";
+import { sweepRetention } from "./retention.js";
+
+const NET = "net_nrr";
+const OTHER_NET = "net_nrr_other";
+const USER = "u_nrr_owner";
+const NODE_ID = "node_nrr_claude";
+const NODE_ALIAS = "nrr-claude";
+const NODE_TOKEN = "tok_nrr_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 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_nrr_node"],
+  );
+}
+
+type Identity = { net: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_nrr_user" };
+// Same human, scoped to the OTHER network: passes canWrite there, but the row
+// lives in NET — SEC-1 must answer request_not_found and touch nothing.
+const asUserOtherScope: Identity = { net: OTHER_NET, alias: USER, isNetworkToken: false, tokenId: "tok_nrr_user_other" };
+const asNode: Identity = { net: NET, alias: NODE_ALIAS, isNetworkToken: true, tokenId: NODE_TOKEN };
+// Same user, same network, a different login token: #1999 makes project-file
+// results readable only by the token that asked.
+const asUserOtherLogin: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_nrr_user_other_login" };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "nrr-test", version: "1" });
+  registerTools(server, undefined, id.net, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "nrr-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 { call, close };
+}
+
+type Row = { status: string; content: string | null; result_content: string | null; file_name: string | null; first_read_at: number | null; content_purged_at: number | null; op: string };
+const rowOf = (id: string) => db.get<Row>(
+  "SELECT status, content, result_content, file_name, first_read_at, content_purged_at, op FROM node_rules_requests WHERE request_id = ?1", id,
+);
+const ageFirstRead = (id: string, ms: number) => db.run("UPDATE node_rules_requests SET first_read_at = first_read_at - ?1 WHERE request_id = ?2", [ms, id]);
+const ageCreated = (id: string, ms: number) => db.run("UPDATE node_rules_requests SET created_at = created_at - ?1 WHERE request_id = ?2", [ms, id]);
+
+async function readRoundTrip(u: Awaited<ReturnType<typeof connect>>, n: Awaited<ReturnType<typeof connect>>, body: string) {
+  const enq = await u.call("read_node_rules_file", { node_id: NODE_ID });
+  expect(enq.ok).toBe(true);
+  await n.call("get_rules_file_request", {});
+  await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "CLAUDE.md", exists: true, content: body });
+  return enq.request_id as string;
+}
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+describe("node_rules_requests — read once, purge after grace", () => {
+  test("content returned on first terminal read and to a follower inside the grace window, then purged", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const body = "# secret rules\n";
+      const rid = await readRoundTrip(u, n, body);
+      expect(rowOf(rid)!.first_read_at).toBeNull();
+
+      const first = await u.call("get_rules_file_result", { request_id: rid });
+      expect(first).toMatchObject({ ok: true, status: "done", content: body, file_name: "CLAUDE.md", exists: true });
+      expect(first.content_purged).toBeUndefined();
+      const stamped = rowOf(rid)!.first_read_at;
+      expect(stamped).not.toBeNull();
+
+      // Second reader (app follow path) inside the grace window still gets it,
+      // and the stamp is NOT pushed forward (a poller can't keep it alive).
+      sweepNodeRequestContent();
+      const follower = await u.call("get_rules_file_result", { request_id: rid });
+      expect(follower.content).toBe(body);
+      expect(rowOf(rid)!.first_read_at).toBe(stamped);
+
+      ageFirstRead(rid, CONTENT_GRACE_MS + 1);
+      // Any enqueue runs the opportunistic sweep.
+      await u.call("list_node_skills", { node_id: NODE_ID });
+      const row = rowOf(rid)!;
+      expect(row.result_content).toBeNull();
+      expect(row.content_purged_at).not.toBeNull();
+      expect(row.status).toBe("done");
+      expect(row.file_name).toBe("CLAUDE.md");
+
+      const after = await u.call("get_rules_file_result", { request_id: rid });
+      expect(after).toMatchObject({ ok: true, status: "done", file_name: "CLAUDE.md", exists: true, content_purged: true });
+      expect("content" in after).toBe(false);
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+
+  test("non-terminal polls do not stamp; a never-read result keeps its content until TTL", 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((await u.call("get_rules_file_result", { request_id: enq.request_id })).status).toBe("pending");
+      expect(rowOf(enq.request_id)!.first_read_at).toBeNull();
+      await n.call("get_rules_file_request", {});
+      await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "CLAUDE.md", exists: true, content: "x" });
+      sweepNodeRequestContent(Date.now() + CONTENT_GRACE_MS * 10);
+      expect(rowOf(enq.request_id)!.result_content).toBe("x");
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — authorization", () => {
+  test("a caller outside the row's network gets request_not_found and cannot stamp or purge it", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    const o = await connect(asUserOtherScope);
+    try {
+      const rid = await readRoundTrip(u, n, "# mine\n");
+      for (let i = 0; i < 3; i++) {
+        expect(await o.call("get_rules_file_result", { request_id: rid })).toMatchObject({ ok: false, error: "request_not_found" });
+      }
+      // Also pass the owner's network_id explicitly — scope is the token's, not the arg's.
+      expect((await o.call("get_rules_file_result", { request_id: rid, network_id: NET })).content).toBeUndefined();
+      expect(rowOf(rid)!.first_read_at).toBeNull();
+      sweepNodeRequestContent(Date.now() + CONTENT_GRACE_MS * 10);
+      expect(rowOf(rid)!.result_content).toBe("# mine\n");
+      // The rightful requester still gets it.
+      expect((await u.call("get_rules_file_result", { request_id: rid })).content).toBe("# mine\n");
+    } finally { await u.close(); await n.close(); await o.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — project files (#1999)", () => {
+  test("another login token can't read or stamp a file_read row; the requester's read starts the grace clock; path is kept", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    const other = await connect(asUserOtherLogin);
+    try {
+      const enq = await u.call("read_node_file", { node_id: NODE_ID, path: "docs/plan.md" });
+      expect(enq.ok).toBe(true);
+      await n.call("get_rules_file_request", {});
+      const body = JSON.stringify({ path: "docs/plan.md", kind: "text", content: "TOP SECRET PLAN" });
+      await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: body });
+
+      expect(await other.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      expect(rowOf(enq.request_id)!.first_read_at).toBeNull();
+
+      expect((await u.call("get_rules_file_result", { request_id: enq.request_id })).content).toBe(body);
+      ageFirstRead(enq.request_id, CONTENT_GRACE_MS + 1);
+      sweepNodeRequestContent();
+      const row = rowOf(enq.request_id)!;
+      expect(row.result_content).toBeNull();
+      expect(row.content).toBe("docs/plan.md");
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "done", content_purged: true });
+    } finally { await u.close(); await n.close(); await other.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — write payload", () => {
+  test("write body in `content` is cleared after the grace window; skill_read name is kept", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const body = "# new rules with a secret\n";
+      const w = await u.call("write_node_rules_file", { node_id: NODE_ID, content: body });
+      await n.call("get_rules_file_request", {});
+      await n.call("ack_rules_file_request", { request_id: w.request_id, status: "done", file_name: "CLAUDE.md", exists: true });
+      expect(rowOf(w.request_id)!.content).toBe(body);
+
+      const s = await u.call("read_node_skill", { node_id: NODE_ID, name: "my-skill" });
+      await n.call("get_rules_file_request", {});
+      await n.call("ack_rules_file_request", { request_id: s.request_id, status: "done", content: JSON.stringify({ name: "my-skill", content: "SKILL BODY" }) });
+
+      const wr = await u.call("get_rules_file_result", { request_id: w.request_id });
+      expect(wr).toMatchObject({ status: "done", op: "write" });
+      expect(wr.content).toBeUndefined();
+      expect((await u.call("get_rules_file_result", { request_id: s.request_id })).content).toContain("SKILL BODY");
+
+      ageFirstRead(w.request_id, CONTENT_GRACE_MS + 1);
+      ageFirstRead(s.request_id, CONTENT_GRACE_MS + 1);
+      sweepNodeRequestContent();
+
+      const wRow = rowOf(w.request_id)!;
+      expect(wRow.content).toBeNull();
+      expect(wRow.content_purged_at).not.toBeNull();
+      expect(wRow.status).toBe("done");
+      const sRow = rowOf(s.request_id)!;
+      expect(sRow.result_content).toBeNull();
+      expect(sRow.content).toBe("my-skill");
+      expect(await u.call("get_rules_file_result", { request_id: w.request_id })).toMatchObject({ status: "done", op: "write", content_purged: true });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — TTL sweep", () => {
+  test(">24h content cleared (stale pending write expired first, so no node can pull an emptied write); >30d rows deleted; fresh rows kept", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      // Create everything first, age afterwards: every enqueue runs the sweep.
+      const oldRead = await readRoundTrip(u, n, "# old, never fetched\n");
+      const ancient = await readRoundTrip(u, n, "# ancient\n");
+      const fresh = await readRoundTrip(u, n, "# fresh, never fetched\n");
+      // A write the node never pulled (offline for a day). Enqueued last so
+      // single-flight doesn't refuse it.
+      const w = await u.call("write_node_rules_file", { node_id: NODE_ID, content: "# stale write body\n" });
+      expect(w.ok).toBe(true);
+      ageCreated(oldRead, CONTENT_TTL_MS + 60_000);
+      ageCreated(ancient, ROW_TTL_MS + 60_000);
+      ageCreated(w.request_id, CONTENT_TTL_MS + 60_000);
+
+      const r = sweepRetention();
+      expect(r.nodeRequests.deleted).toBe(1);
+      expect(r.nodeRequests.timedOut).toBe(1);
+      expect(r.nodeRequests.purged).toBe(2);
+
+      expect(rowOf(ancient)).toBeNull();
+      const o = rowOf(oldRead)!;
+      expect(o.result_content).toBeNull();
+      expect(o.status).toBe("done");
+      expect(o.file_name).toBe("CLAUDE.md");
+      expect(rowOf(fresh)!.result_content).toBe("# fresh, never fetched\n");
+
+      const wr = rowOf(w.request_id)!;
+      expect(wr.status).toBe("timeout");
+      expect(wr.content).toBeNull();
+      // The node coming back must not receive the emptied write.
+      expect(await n.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+
+      expect(await u.call("get_rules_file_result", { request_id: oldRead })).toMatchObject({ status: "done", content_purged: true });
+
+      // Idempotent.
+      const again = sweepNodeRequestContent();
+      expect(again).toEqual({ timedOut: 0, purged: 0, deleted: 0 });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});

package/src/node-request-retention.ts

@@ -0,0 +1,120 @@
+// node_rules_requests content retention (privacy).
+//
+// The rules-file / skills (and project-folder) queue carries **node file
+// contents** through the hub: `result_content` holds what the node sent back
+// (CLAUDE.md / AGENTS.md, SKILL.md, directory listings, file bodies) and
+// `content` holds write payloads (the full new rules file). Before this module
+// nothing ever cleared or deleted those rows — every file anyone ever opened in
+// the desktop app stayed in the hub DB forever.
+//
+// Policy (metadata — status, op, file_name, file_exists, error, timestamps,
+// requester — is kept for audit; only file bytes are dropped):
+//
+//   1. Read-once + grace: the first time an authorized requester reads a
+//      TERMINAL result (done/failed/timeout) the row is stamped `first_read_at`.
+//      CONTENT_GRACE_MS later the content is purged. Not immediate, because the
+//      desktop app has a real second-reader path: when enqueue is rejected with
+//      `request_in_flight` the app FOLLOWS the existing request id
+//      (requestIdToFollow → waitForRulesFileResult, NodeRulesSection /
+//      NodeSkillsSection / NodeFilesSection). Two windows (or a remount) polling
+//      the same request reach terminal within one poll interval (≤ 3 s) of each
+//      other; an immediate purge would hand the second one `done` with no
+//      content and NodeRulesSection would load an EMPTY editor (`content ?? ''`)
+//      that a Save would then write back to the node. 60 s is 20× the slowest
+//      poll interval.
+//   2. TTL: anything older than CONTENT_TTL_MS gets its content purged whether
+//      or not anyone ever read it (e.g. the app was closed mid-request). A
+//      still-pending/in_progress row that old is first flipped to `timeout`, so
+//      a node that comes back after a day can never pull a write whose payload
+//      was just nulled (it would otherwise receive `content: ""` and write an
+//      empty rules file).
+//   3. Rows older than ROW_TTL_MS are deleted outright.
+//   4. Run logs (op = logs_tail) are stricter: read-once with NO grace — the
+//      first authorized terminal read purges them in the same call
+//      (purgeLogsResultNow), because the app never follows another request's
+//      logs result (it simply asks again) and a process log is the most
+//      sensitive thing on this queue. Unread terminal results are purged after
+//      LOGS_CONTENT_TTL_MS (the requester closed the page). The filter JSON in
+//      `content` (it can hold a user-typed grep) goes with it.
+//
+// Every statement is bounded (LIMIT via `request_id IN (SELECT … LIMIT n)` —
+// SQLite's UPDATE/DELETE … LIMIT needs a compile flag we don't control) and
+// uses an index (idx_nrr_created / idx_nrr_first_read). It runs
+// opportunistically on enqueue and on terminal reads, from a one-shot timer
+// armed at the first terminal read, and from the hourly retention sweeper
+// (retention.ts) — so the first sweep after deploy also clears every old row
+// that predates this module.
+
+import { db } from "./db.js";
+
+export const CONTENT_GRACE_MS = 60_000;
+export const CONTENT_TTL_MS = 24 * 60 * 60 * 1000;
+export const ROW_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const SWEEP_BATCH = 500;
+export const LOGS_CONTENT_TTL_MS = 5 * 60 * 1000;
+
+export type NodeRequestSweepResult = { timedOut: number; purged: number; deleted: number };
+
+// `content` is only a file body for op=write. For skill_read / file_read it is
+// the skill name / relative path the requester asked for — audit metadata, kept.
+// For logs_tail it is the filter JSON, which may carry a user-typed grep — purged.
+const PURGE_SET =
+  "result_content = NULL, content = CASE WHEN op IN ('write', 'logs_tail') THEN NULL ELSE content END, content_purged_at = ?1";
+
+function purgeWhere(where: string, params: (string | number)[], now: number): number {
+  const r = db.run(
+    `UPDATE node_rules_requests SET ${PURGE_SET} WHERE request_id IN (SELECT request_id FROM node_rules_requests WHERE content_purged_at IS NULL AND ${where} LIMIT ${SWEEP_BATCH})`,
+    [now, ...params],
+  );
+  return r.changes ?? 0;
+}
+
+export function sweepNodeRequestContent(now: number = Date.now()): NodeRequestSweepResult {
+  const out: NodeRequestSweepResult = { timedOut: 0, purged: 0, deleted: 0 };
+  try {
+    // Delete first so rows past the row TTL aren't pointlessly purged, then
+    // expire stale non-terminal rows, then purge.
+    out.deleted = db.run(
+      `DELETE FROM node_rules_requests WHERE request_id IN (SELECT request_id FROM node_rules_requests WHERE created_at < ?1 LIMIT ${SWEEP_BATCH})`,
+      [now - ROW_TTL_MS],
+    ).changes ?? 0;
+    const ttlCutoff = now - CONTENT_TTL_MS;
+    out.timedOut = db.run(
+      `UPDATE node_rules_requests SET status = 'timeout', acked_at = ?1, error = ?2 WHERE request_id IN (SELECT request_id FROM node_rules_requests WHERE created_at < ?3 AND status IN ('pending', 'in_progress') LIMIT ${SWEEP_BATCH})`,
+      [now, "expired by retention sweep (node never answered)", ttlCutoff],
+    ).changes ?? 0;
+    // ?1 = now (PURGE_SET), ?2… = where params.
+    out.purged += purgeWhere("first_read_at IS NOT NULL AND first_read_at <= ?2 AND status IN ('done', 'failed', 'timeout')", [now - CONTENT_GRACE_MS], now);
+    out.purged += purgeWhere("created_at < ?2 AND status IN ('done', 'failed', 'timeout')", [ttlCutoff], now);
+    out.purged += purgeWhere("op = 'logs_tail' AND created_at < ?2 AND status IN ('done', 'failed', 'timeout')", [now - LOGS_CONTENT_TTL_MS], now);
+  } catch (e: any) {
+    console.log(`[commhub retention] node_rules_requests sweep failed: ${e?.message ?? e}`);
+  }
+  return out;
+}
+
+/** Called by get_rules_file_result AFTER the requester passed every auth check
+ *  and only for a terminal status. Stamps the first terminal read, arms a
+ *  one-shot purge for after the grace window, and reports whether this row's
+ *  content is already gone. */
+export function noteTerminalResultRead(requestId: string, now: number = Date.now()): { purged: boolean } {
+  const r = db.run(
+    "UPDATE node_rules_requests SET first_read_at = ?1 WHERE request_id = ?2 AND first_read_at IS NULL",
+    [now, requestId],
+  );
+  if ((r.changes ?? 0) > 0) {
+    const t = setTimeout(() => { sweepNodeRequestContent(); }, CONTENT_GRACE_MS + 1_000);
+    (t as any).unref?.();
+  }
+  const row = db.get<{ content_purged_at: number | null }>(
+    "SELECT content_purged_at FROM node_rules_requests WHERE request_id = ?1",
+    requestId,
+  );
+  return { purged: row?.content_purged_at != null };
+}
+
+/** Run-log results are read-once: called by get_rules_file_result right after it
+ *  handed a terminal logs_tail result to its (authorized) requester. */
+export function purgeLogsResultNow(requestId: string, now: number = Date.now()): void {
+  db.run(`UPDATE node_rules_requests SET ${PURGE_SET} WHERE request_id = ?2 AND op = 'logs_tail' AND content_purged_at IS NULL`, [now, requestId]);
+}