@sleep2agi/commhub-server 0.9.0-preview.91 → 0.9.0-preview.93

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/requirements-status-participants-http.test.ts

@@ -208,7 +208,11 @@ describe("tool descriptions", () => {
     expect(update.description).toContain("REPLACES the whole list");
     expect(update.inputSchema.properties.participants.description).toContain("REPLACES");
     expect(Object.keys(update.inputSchema.properties)).toEqual(expect.arrayContaining(["status", "participants_add", "participants_remove"]));
-    for (const name of ["projects_list", "projects_create", "projects_update"]) expect(byName.get(name).description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    // #478:节点令牌的 tools/list 里本来就没有 projects_create / projects_update(调了也是 403),那两条的说明从人的列表里读。
+    expect(byName.has("projects_create")).toBe(false);
+    const human = new Map(((await rpc(U.member.token, "tools/list", {})).result.tools as any[]).map(t => [t.name, t]));
+    expect(byName.get("projects_list").description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    for (const name of ["projects_create", "projects_update"]) expect(human.get(name).description).toMatch(/node \(Agent\) tokens can only read projects/i);
     const denied = await mcp(U.nodeA.token, "projects_create", { name: "示例项目" });
     expect(denied.status).toBe(403);
     expect(denied.error).toBe("user_token_required");

package/src/requirements.ts

@@ -10,9 +10,10 @@ import { applyTagOp, normalizeTags, parseTagOp, storedTags, type TagOp } from ".
 import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-stats.js";
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
+import { nodeDecide, nodeIdentity, nodePermissionDeniedBody, nodePermissionsFlag, type NodeIdentity, type Verdict } from "./node-permissions.js";
 import {
   addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, deletesAsHeadOnly, headOnlyEditScope, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
-  isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
+  cardAssignedToNode, isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
 import { notifyLeaderDeleted, notifyParticipantChange } from "./requirement-notify.js";
 import { departmentCardsFor, departmentSubtree } from "./department-heads.js";
@@ -93,11 +94,67 @@ function jsonError(error: string, status: number, ctx?: ErrorContext): Response
 }
 
 // ── 任务的人员权限(RFC-038 §9,判定在 task-access.ts) ──
-// 节点令牌(Agent)、Hub 管理员、没有身份的旧全局令牌:不受任务权限约束(null)。
+// Hub 管理员、没有身份的旧全局令牌:不受任务权限约束(null)。
+// 节点令牌(RFC-041,#487):受限模式 → 按主人的权限且只碰派给它的卡;执行开关为 enforce → 按主人的权限;
+// 其余(默认 log 下的正常 / 只读节点)→ null,与以前一样(只读的写在 nodeTaskGate 里拒)。
 function taskCaller(ctx: RequirementsRequestContext): TaskCaller {
-  if (!ctx.auth || ctx.isNodeToken || ctx.isAdmin) return null;
+  if (!ctx.auth || ctx.isAdmin) return null;
+  if (ctx.isNodeToken) return nodeTaskCaller(ctx);
   return { userId: ctx.auth.userId };
 }
+
+const nodeIdentities = new WeakMap<RequirementsRequestContext, NodeIdentity | null>();
+function nodeIdent(ctx: RequirementsRequestContext): NodeIdentity | null {
+  if (!ctx.isNodeToken) return null;
+  if (!nodeIdentities.has(ctx)) nodeIdentities.set(ctx, nodeIdentity(ctx.auth?.tokenId, ctx.auth?.networkId));
+  return nodeIdentities.get(ctx) ?? null;
+}
+function nodeTaskCaller(ctx: RequirementsRequestContext): TaskCaller {
+  const id = nodeIdent(ctx);
+  if (!id?.ownerUserId) return null;
+  if (id.mode === "restricted") return { userId: id.ownerUserId, node: { id: id.logKey, only: true } };
+  if (nodePermissionsFlag() === "enforce") return { userId: id.ownerUserId, node: { id: id.logKey, only: false } };
+  return null;
+}
+
+/**
+ * RFC-041 —— 节点的一次任务写(建 / 改 / 勾检查项 / 评论 / upsert)先过这里。row=null 是新建(create 给出目标项目、
+ * 负责 Agent、父卡)。只读 → 必拒;受限 → 不是派给它的必拒;正常 → 主人看不见 / 改不了时按开关记录或拒。
+ */
+function nodeTaskGate(ctx: RequirementsRequestContext, route: string, row: Row | null, create?: { networkId: string; projectId: string | null; agentOwnerJson: string | null; parentId: string | null }): Response | null {
+  const id = nodeIdent(ctx);
+  if (!id) return null;
+  const sample = row ? `#${row.seq ?? "?"} ${row.requirement_id}` : create?.projectId ?? undefined;
+  let verdict: Verdict = null;
+  if (id.mode === "readonly") verdict = { reason: "mode_readonly", sample };
+  else if (id.mode === "restricted") {
+    const nodeRef = JSON.stringify({ kind: "node", id: id.logKey });
+    const parent = create?.parentId ? db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, create.parentId) : undefined;
+    const assigned = row ? cardAssignedToNode(row, id.logKey) : create?.agentOwnerJson === nodeRef || (!!parent && cardAssignedToNode(parent, id.logKey));
+    if (!assigned) verdict = { reason: "mode_restricted_not_assigned", sample };
+  } else if (!id.ownerUserId) verdict = { reason: "owner_unknown", sample };
+  else {
+    const asOwner: TaskCaller = { userId: id.ownerUserId, node: { id: id.logKey, only: false } };
+    const ok = row ? canSeeTask(asOwner, row) && canEditTask(asOwner, row) : canUseProject(asOwner, create!.networkId, create!.projectId);
+    if (!ok) verdict = { reason: "beyond_owner_visibility", sample };
+  }
+  return nodeDecide(id, route, verdict) ? Response.json(nodePermissionDeniedBody(verdict!.reason, route), { status: 403 }) : null;
+}
+
+/** 正常模式的节点读到了主人看不见的卡:只记录(执行时 taskCaller 已按主人收窄,读不到)。主人不受任务范围限制时什么都不做。 */
+function nodeReadNote(ctx: RequirementsRequestContext, route: string, row: Row | null): void {
+  const id = nodeIdent(ctx);
+  if (!id?.ownerUserId || id.mode === "restricted" || nodePermissionsFlag() !== "log" || !isTaskScoped(id.ownerUserId, id.networkId)) return;
+  const asOwner: TaskCaller = { userId: id.ownerUserId };
+  if (row) {
+    if (!canSeeTask(asOwner, row)) nodeDecide(id, route, { reason: "beyond_owner_visibility", sample: `#${row.seq ?? "?"} ${row.requirement_id}` });
+    return;
+  }
+  const all = Number(db.get<{ n: number | string }>("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", id.networkId)?.n ?? 0);
+  const params: unknown[] = [id.networkId];
+  const seen = Number(db.get<{ n: number | string }>(addTaskVisibilityScope("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", params, asOwner), ...params)?.n ?? 0);
+  if (all > seen) nodeDecide(id, route, { reason: "beyond_owner_visibility", sample: `list: ${all - seen} card(s) the owner cannot see` });
+}
 /**
  * 看得见但没权限写:403,并按 (用户, 卡) 每小时最多记一条审计。
  * field:参与人改了参与人不能改的字段 —— 错误码不变(旧 App 照旧认 task_read_only),多带 field + 一句中文 message。
@@ -825,6 +882,8 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   const createdAt = new Date().toISOString();
   let people;
   try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
+  const nodeDenied = nodeTaskGate(ctx, "POST /api/requirements", null, { networkId, projectId, agentOwnerJson: people.agentOwnerJson, parentId });
+  if (nodeDenied) return nodeDenied;
   const actor = JSON.stringify(actorOf(ctx));
   try {
     // 领号、插入、记「新建」这条动态在同一个事务里:插入被唯一索引挡下时,号和动态一起回滚,不留空洞。
@@ -862,6 +921,8 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400, { sent: Object.keys(body), writable: PATCH_FIELDS });
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
   if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+  const nodeDenied = nodeTaskGate(ctx, "PATCH /api/requirements/:id", row);
+  if (nodeDenied) return nodeDenied;
   const caller = taskCaller(ctx);
   if (!canEditTask(caller, row)) {
     // 参与人:只放状态和检查项;别的字段点名拒绝。不是参与人 → 与今天一样。
@@ -1299,6 +1360,7 @@ function rememberList(key: string, entry: ListCacheEntry): void {
 function listCacheAcl(ctx: RequirementsRequestContext): string | null {
   const caller = taskCaller(ctx);
   if (!caller) return `open:${ctx.isAdmin ? 1 : 0}:${ctx.isNodeToken ? 1 : 0}`;
+  if (caller.node) return null; // 按节点收窄的列表不缓存(模式随时可改)
   if (restrictedNetworkIds(caller.userId).length > 0) return null;
   const members = db.all<Record<string, unknown>>("SELECT * FROM network_members WHERE user_id = ?1 ORDER BY network_id", caller.userId);
   const networks = members.map(m => String(m.network_id));
@@ -1417,6 +1479,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     if (changes && url.searchParams.get("updated_since") === null) return jsonError("updated_since_required", 400);
     // changes 模式:server_time 取在读表之前,下次拿它当 updated_since,读表期间的写入不会漏(>= 会重复回一次,客户端按 id 覆盖)。
     const serverTime = new Date().toISOString();
+    nodeReadNote(ctx, "GET /api/requirements", null);
     const cacheKey = changes || url.searchParams.get("q") ? null : listCacheKey(ctx);
     const acl = cacheKey ? listCacheAcl(ctx) : null;
     const generation = requirementsGeneration;
@@ -1470,7 +1533,11 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
       return Response.json({ ...data, created: true }, { status: 201 });
     }
     const { external_ref: _ref, network_id: _net, client_id: _client, ...patch } = body;
-    if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(patch, k))) return Response.json({ ok: true, requirement: toPublicFor(ctx, existing), created: false });
+    if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(patch, k))) {
+      // 没有要改的字段 = 读回这张卡:受限节点只能读派给它的(与列表同一个可见范围)。
+      if (!canSeeTask(taskCaller(ctx), existing)) return jsonError("upsert_not_allowed", 403);
+      return Response.json({ ok: true, requirement: toPublicFor(ctx, existing), created: false });
+    }
     const res = patchRequirement(ctx, existing, patch);
     if (res.status !== 200) return res;
     const data = await res.json() as Record<string, unknown>;
@@ -1491,6 +1558,8 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const row = scopedRow(ctx, decodeURIComponent(commentMatch[1]));
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    const nodeDenied = nodeTaskGate(ctx, "POST /api/requirements/:id/comments", row);
+    if (nodeDenied) return nodeDenied;
     const at = new Date().toISOString();
     const event = db.transaction(() => {
       recordRequirementEvents(db, row, JSON.stringify(actorOf(ctx)), [{ kind: "comment", field: null, old: null, new: { text } }], at);
@@ -1508,6 +1577,8 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const row = scopedRow(ctx, decodeURIComponent(itemMatch[1]));
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    const nodeDenied = nodeTaskGate(ctx, "PATCH /api/requirements/:id/checklist/:item", row);
+    if (nodeDenied) return nodeDenied;
     if (!canEditTask(taskCaller(ctx), row) && !canParticipantEditTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_read_only");
     // 读-改-写在同一个同步段里完成(中间没有 await),同一进程里的两次勾选不会交错。
     const items = storedChecklist(row.checklist_json);
@@ -1533,6 +1604,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
   const id = decodeURIComponent(match[1]);
   if (req.method === "GET") {
     const row = scopedRow(ctx, id);
+    if (!(row instanceof Response)) nodeReadNote(ctx, "GET /api/requirements/:id", row);
     return row instanceof Response ? row : Response.json({ ok: true, requirement: toPublicFor(ctx, row) });
   }
   if (req.method === "DELETE") {