@sleep2agi/commhub-server 0.9.0-preview.144 → 0.9.0-preview.146

package/src/node-session-control.ts

@@ -0,0 +1,254 @@
+import { randomBytes } from "node:crypto";
+import { db } from "./db.js";
+import { getUserNetworkRole, resolveToken, sessionIdleDays } from "./auth.js";
+import { isAgentRestricted } from "./agent-access.js";
+import { resolveNodeCaller } from "./create-node.js";
+import { pushEvent } from "./push.js";
+
+type Identity = { session_id: string; binding_id: string };
+type Credential = { token_id: string; user_id: string; network_id: string | null;
+  bound_node_id: string | null; scope: string; role: string };
+type Node = { node_id: string; network_id: string; owner_user_id: string | null; alias: string };
+type Bridge = Identity & { tokenId: string; expires: number; retired: Set<string> };
+type Entry = Identity & { request_id: string; operation: "state" | "background";
+  networkId: string; nodeId: string; tokenId: string; requester: string; expires_at: number;
+  status: "pending" | "in_progress" | "done" | "failed" | "unknown" | "expired";
+  result?: unknown; error?: string };
+const TTL = 15_000, LEASE = 75_000, CAP = 1024, HISTORY = 64;
+const ROOT = "/api/node-session-control";
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+const ERRORS = new Set(["unavailable", "changed", "unsupported", "invalid_response", "request_invalid",
+  "request_expired", "request_limit"].map(s => `session_control_${s}`).concat("session_background_outcome_unknown"));
+const keys = (o: Record<string, unknown>, allowed: string[]) => Object.keys(o).every(k => allowed.includes(k));
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const id = (v: unknown): v is string => typeof v === "string" && ID.test(v);
+const identity = (v: unknown): v is Identity => object(v) && keys(v, ["session_id", "binding_id"])
+  && id(v.session_id) && id(v.binding_id);
+const same = (a: Identity, b: Identity) => a.session_id === b.session_id && a.binding_id === b.binding_id;
+const generation = (token: string, v: Identity) => JSON.stringify([token, v.session_id, v.binding_id]);
+const fail = (error: string, status = 409) => Response.json({ ok: false, error }, { status });
+const ok = (value: object) => Response.json({ ok: true, ...value });
+
+// Recheck stored identities without storing plaintext bearer tokens. The SQL
+// mirrors resolveToken's expiry/revoke/idle rules; membership is checked below.
+function credential(tokenId: string): Credential | null {
+  const days = sessionIdleDays();
+  return db.get<Credential>(`SELECT t.token_id,t.user_id,t.network_id,t.bound_node_id,t.scope,u.role
+    FROM api_tokens t JOIN users u ON u.user_id=t.user_id WHERE t.token_id=?1
+    AND t.revoked_at IS NULL AND (t.expires_at IS NULL OR t.expires_at>datetime('now'))
+    AND NOT (t.scope='user' AND t.network_id IS NULL AND ?2>0
+      AND COALESCE(t.last_used_at,t.created_at)<datetime('now',?3))`,
+    tokenId, days, `-${Math.round(days * 86400)} seconds`) ?? null;
+}
+function node(nodeId: string): Node | null {
+  return db.get<Node>("SELECT node_id,network_id,owner_user_id,alias FROM nodes WHERE node_id=?1", nodeId) ?? null;
+}
+function isHumanCredential(c: Credential | null): c is Credential {
+  return !!c && c.network_id === null && c.bound_node_id === null
+    && (c.scope === "user" || c.scope === "full");
+}
+function human(tokenId: string, n: Node): boolean {
+  const c = credential(tokenId);
+  if (!isHumanCredential(c) || !n.network_id) return false;
+  const role = getUserNetworkRole(c.user_id, n.network_id);
+  return !!role && role !== "viewer" && !isAgentRestricted(c.user_id, n.network_id)
+    && (c.user_id === n.owner_user_id || role === "owner" || role === "admin" || c.role === "admin");
+}
+function bound(tokenId: string, n?: Node | null): Node | null {
+  const c = credential(tokenId);
+  if (!c?.bound_node_id || !c.network_id || c.scope !== "network") return null;
+  const target = n ?? node(c.bound_node_id);
+  if (!target || c.bound_node_id !== target.node_id || c.network_id !== target.network_id
+    || !getUserNetworkRole(c.user_id, c.network_id) || isAgentRestricted(c.user_id, c.network_id)) return null;
+  const caller = resolveNodeCaller(tokenId);
+  return caller.ok && caller.kind === "node" && caller.nodeId === target.node_id
+    && caller.networkId === target.network_id ? target : null;
+}
+async function body(req: Request): Promise<Record<string, unknown> | null> {
+  const reader = req.body?.getReader();
+  if (!reader) return null;
+  const chunks: Uint8Array[] = []; let size = 0;
+  try {
+    for (;;) {
+      const part = await reader.read(); if (part.done) break;
+      size += part.value.byteLength;
+      if (size > 8192) { await reader.cancel(); return null; }
+      chunks.push(part.value);
+    }
+    const v: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return object(v) ? v : null;
+  } catch { return null; }
+}
+function state(value: unknown, e: Entry): boolean {
+  return object(value) && keys(value, ["session_id", "binding_id", "supported", "active", "can_request_background", "observed_at"])
+    && same(value as Identity, e) && typeof value.supported === "boolean" && typeof value.active === "boolean"
+    && typeof value.can_request_background === "boolean" && typeof value.observed_at === "number"
+    && Number.isFinite(value.observed_at) && value.observed_at > 0
+    && (!value.can_request_background || (value.supported && value.active));
+}
+function validResult(v: unknown, e: Entry): boolean {
+  if (e.operation === "state") return state(v, e);
+  return object(v) && keys(v, ["outcome", "state"])
+    && (v.outcome === "request_processed" || v.outcome === "already_idle") && state(v.state, e)
+    && (v.outcome !== "already_idle" || (object(v.state)
+      && v.state.active === false && v.state.can_request_background === false));
+}
+
+/** One finite, process-local relay per Hub boot. Restart loses requests (404),
+ * never replays them. Multi-worker deployments require process affinity.
+ * A claim authorizes one delivery, not proof that any tool moved to background.
+ */
+export function createNodeSessionControlRelay() {
+  const bridges = new Map<string, Bridge>();
+  const entries = new Map<string, Entry>();
+  const key = (n: Node) => JSON.stringify([n.network_id, n.node_id]);
+  function close(e: Entry, error: string) {
+    e.status = e.status === "in_progress" ? "unknown" : "failed";
+    e.error = e.status === "unknown" ? "session_background_outcome_unknown" : error;
+  }
+  function refresh(e: Entry, now: number) {
+    if (e.status !== "pending" && e.status !== "in_progress") return;
+    if (now >= e.expires_at) {
+      e.status = e.status === "in_progress" ? "unknown" : "expired";
+      e.error = e.status === "unknown" ? "session_background_outcome_unknown" : "session_control_request_expired";
+      return;
+    }
+    const n = node(e.nodeId), b = n && bridges.get(key(n));
+    if (!n || n.network_id !== e.networkId || !human(e.requester, n) || !bound(e.tokenId, n)) {
+      close(e, "session_control_unavailable");
+    } else if (!b || b.expires <= now || b.tokenId !== e.tokenId || !same(b, e)) {
+      close(e, "session_control_changed");
+    }
+  }
+  function sweep(now: number) {
+    for (const [k, e] of entries) {
+      refresh(e, now);
+      if (now > e.expires_at + 60_000) entries.delete(k);
+    }
+  }
+  return async function handle(req: Request, url: URL): Promise<Response | null> {
+    if (url.pathname !== ROOT && !url.pathname.startsWith(`${ROOT}/`)) return null;
+    try {
+    // Header-only, persisted credential authority; no master/dev-open fallback.
+    const raw = req.headers.get("authorization")?.match(/^Bearer (\S+)$/)?.[1] ?? "";
+    const auth = resolveToken(raw);
+    if (!auth?.tokenId) return fail("session_control_unavailable", 401);
+    const tokenId = auth.tokenId;
+    const c = credential(tokenId);
+    if (!c) return fail("session_control_unavailable", 401);
+    const isHuman = isHumanCredential(c);
+    const isNode = c.scope === "network" && !!c.network_id;
+    const suffix = url.pathname.slice(ROOT.length);
+      if (req.method === "GET" && /^\/(bg|sc)_\d{13}_[A-Za-z0-9_-]{8,64}$/.test(suffix)) {
+        const e = entries.get(suffix.slice(1));
+        // Unknown/restarted Hub and unauthorized reads reveal no request data.
+        if (!isHuman) return fail("session_control_unavailable", 403);
+        if (!e) return fail("session_control_unavailable", 404);
+        const n = node(e.nodeId);
+        if (!n || url.searchParams.get("network_id") !== e.networkId || n.network_id !== e.networkId || !human(tokenId, n)) {
+          return fail("session_control_unavailable", 403);
+        }
+        refresh(e, Date.now());
+        return ok({ request_id: e.request_id, status: e.status,
+          ...(e.result === undefined ? {} : { result: e.result }), ...(e.error ? { error: e.error } : {}) });
+      }
+      if (req.method !== "POST") return fail("session_control_request_invalid", 405);
+      const v = await body(req);
+      if (!v) return fail("session_control_request_invalid", 400);
+      const now = Date.now();
+      if (suffix === "/bridge") {
+        if (!isNode) return fail("session_control_unavailable", 403);
+        if (!keys(v, ["session_id", "binding_id", "expected"]) || !id(v.session_id) || !id(v.binding_id)
+          || !object(v.expected) || !keys(v.expected, ["node_id", "network_id"])
+          || !id(v.expected.node_id) || !id(v.expected.network_id)) return fail("session_control_request_invalid", 400);
+        // Body reading is complete. This synchronous section rechecks authority
+        // and expected identity BEFORE sweep, retirement, or registration writes.
+        // expected is an assertion, never a source for binding or proof fields.
+        const c = credential(tokenId), n = bound(tokenId);
+        if (!c || !n) return fail("session_control_unavailable", 403);
+        if (c.bound_node_id !== n.node_id || c.network_id !== n.network_id
+          || v.expected.node_id !== c.bound_node_id || v.expected.network_id !== c.network_id) {
+          return fail("session_control_changed");
+        }
+        const registration = { session_id: v.session_id, binding_id: v.binding_id };
+        const k = key(n), b = bridges.get(k), g = generation(tokenId, registration);
+        if (b?.retired.has(g)) return fail("session_control_changed");
+        const replacing = b && (b.tokenId !== tokenId || !same(b, registration));
+        if ((replacing && b.retired.size >= HISTORY) || (!b && bridges.size >= CAP)) {
+          return fail("session_control_request_limit", 429);
+        }
+        sweep(now);
+        if (replacing) {
+          b.retired.add(generation(b.tokenId, b));
+          for (const e of entries.values()) if (e.nodeId === n.node_id && e.networkId === n.network_id
+            && (e.status === "pending" || e.status === "in_progress")) close(e, "session_control_changed");
+        }
+        bridges.set(k, { ...registration, tokenId, expires: now + LEASE, retired: b?.retired ?? new Set() });
+        return ok({ expires_at: now + LEASE,
+          identity: { node_id: c.bound_node_id, network_id: c.network_id, token_id: c.token_id } });
+      }
+      sweep(now);
+      if (!suffix) {
+        if (!isHuman) return fail("session_control_unavailable", 403);
+        if (!keys(v, ["network_id", "node_id", "operation", "expected"]) || !id(v.network_id) || !id(v.node_id)
+          || (v.operation !== "state" && v.operation !== "background")
+          || (v.expected !== undefined && !identity(v.expected)) || (v.operation === "background" && !identity(v.expected))) {
+          return fail("session_control_request_invalid", 400);
+        }
+        const n = node(v.node_id);
+        if (!n || n.network_id !== v.network_id || !human(tokenId, n)) return fail("session_control_unavailable", 403);
+        const b = bridges.get(key(n));
+        if (!b || b.expires <= now || !bound(b.tokenId, n)) return fail("session_control_unavailable");
+        if (v.expected && !same(v.expected as Identity, b)) return fail("session_control_changed");
+        if (entries.size >= CAP || [...entries.values()].some(e => e.nodeId === n.node_id
+          && e.networkId === n.network_id && (e.status === "pending" || e.status === "in_progress"))) {
+          return fail("session_control_request_limit", 429);
+        }
+        const request_id = `${v.operation === "background" ? "bg" : "sc"}_${now}_${randomBytes(18).toString("base64url")}`;
+        entries.set(request_id, { session_id: b.session_id, binding_id: b.binding_id, request_id,
+          operation: v.operation, networkId: n.network_id, nodeId: n.node_id, tokenId: b.tokenId,
+          requester: tokenId, expires_at: now + TTL, status: "pending" });
+        pushEvent(n.alias, { type: "session_control", request_id }, n.network_id);
+        return ok({ request_id, status: "pending", expires_at: now + TTL });
+      }
+      if (!isNode) return fail("session_control_unavailable", 403);
+      const n = bound(tokenId);
+      if (!n) return fail("session_control_unavailable", 403);
+      const k = key(n), b = bridges.get(k);
+      if (!b || b.expires <= now || b.tokenId !== tokenId) return fail("session_control_changed");
+      if (suffix === "/pull") {
+        if (!identity(v)) return fail("session_control_request_invalid", 400);
+        if (!same(b, v)) return fail("session_control_changed");
+        const e = [...entries.values()].find(e => e.nodeId === n.node_id && e.networkId === n.network_id && e.status === "pending");
+        if (!e) return ok({ request: null });
+        refresh(e, now);
+        if (e.status !== "pending") return ok({ request: null });
+        // No await between authority recheck, claim, and response. Never requeue.
+        e.status = "in_progress";
+        return ok({ request: { request_id: e.request_id, operation: e.operation,
+          session_id: e.session_id, binding_id: e.binding_id, expires_at: e.expires_at } });
+      }
+      if (/^\/(bg|sc)_\d{13}_[A-Za-z0-9_-]{8,64}\/ack$/.test(suffix)) {
+        if (!keys(v, ["session_id", "binding_id", "status", "result", "error"]) || !id(v.session_id) || !id(v.binding_id)
+          || (v.status !== "done" && v.status !== "failed")) return fail("session_control_request_invalid", 400);
+        const e = entries.get(suffix.split("/")[1]);
+        if (!e) return fail("session_control_unavailable", 404);
+        if (e.nodeId !== n.node_id || e.networkId !== n.network_id || e.tokenId !== tokenId || !same(e, v as Identity)
+          || !same(b, e)) return fail("session_control_changed");
+        refresh(e, now);
+        if (e.status !== "in_progress") return fail("session_control_request_expired");
+        if (v.status === "done" && validResult(v.result, e) && v.error === undefined) {
+          e.status = "done"; e.result = v.result;
+        } else if (v.status === "failed" && typeof v.error === "string" && ERRORS.has(v.error) && v.result === undefined) {
+          e.status = "failed"; e.error = v.error;
+        } else {
+          // Invalid/untrusted runtime replies never become success or leak raw errors.
+          e.status = "unknown"; e.error = "session_control_invalid_response";
+          return fail(e.error, 400);
+        }
+        return ok({ request_id: e.request_id, status: e.status });
+      }
+      return fail("session_control_request_invalid", 404);
+    } catch { return fail("session_control_unavailable", 503); }
+  };
+}

package/src/server.ts

@@ -92,12 +92,14 @@ import { requestNodeSecrets, getScopedSecrets } from "./scoped-secrets.js";
 import { readEnvTransportLog } from "./env-transport-gate.js";
 import { labelRoute, mcpRouteLabel, recordRouteTiming, routeStats, setRouteCallerMasterToken, setRouteCallerTokenReader } from "./route-timing.js";
 import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js";
+import { createNodeSessionControlRelay } from "./node-session-control.js";
 import { recordDeliveredStaleEvents } from "./task-lifecycle-watcher.js";
 import { SIDE_THREAD_FEATURE_FLAG, SideThreadCoordinator, SideThreadPortRegistry, SideThreadStore, type SideThreadActor, type SideThreadAttachmentRef, type SideThreadExecutionPort } from "./side-thread.js";
 import { handleSideThreadHttpRequest } from "./side-thread-http.js";
 import { createProductionSideThreadTransport } from "./side-thread-production.js";
 import { parseHubTimestamp } from "./hub-timestamp";
 import { logTaskRejection } from "./task-rejection-log.js";
+import { AVATAR_FIELD, avatarUrl, inspectAvatarImage, isMultipart, isValidAvatarVersion, MAX_AVATAR_BYTES } from "./user-avatar-image.js";
 
 const PORT = resolvePort(process.env.PORT);
 const HOST = process.env.HOST || "127.0.0.1";
@@ -1027,6 +1029,7 @@ function patrolDeliveredStaleTasks(): void {
 // Note: `opts.port ?? PORT` uses nullish-coalescing on purpose — `||`
 // would swallow a legitimate `0`. Same for hostname.
 export function bootServer(opts?: { port?: number; hostname?: string }): ReturnType<typeof Bun.serve> {
+const nodeSessionControl = createNodeSessionControlRelay();
 return Bun.serve({
   port: opts?.port ?? PORT,
   hostname: opts?.hostname ?? HOST,
@@ -1485,10 +1488,148 @@ return Bun.serve({
       const avatar = validateAvatarUrl((body as { avatar_url: unknown }).avatar_url);
       if (!avatar.ok) return withCors(req, Response.json({ ok: false, error: "invalid_avatar_url", reason: avatar.reason }, { status: 400 }));
       // No supplied target ID/alias; user identity comes exclusively from auth.
-      db.run("UPDATE users SET avatar_url = ?1, updated_at = datetime('now') WHERE user_id = ?2", [avatar.value, resolved.user.user_id]);
+      // 清空或换成另一张（池/外链）时，旧托管行必须同一事务撤销：否则「清空后旧 URL 仍可读」。
+      db.transaction(() => {
+        db.run("UPDATE users SET avatar_url = ?1, updated_at = datetime('now') WHERE user_id = ?2", [avatar.value, resolved.user.user_id]);
+        const keepsUploaded = typeof avatar.value === "string" && /^\/api\/users\/[^/]+\/avatar\/[A-Za-z0-9_-]{1,128}\.png$/.test(avatar.value);
+        if (!keepsUploaded) db.run("DELETE FROM user_avatar_uploads WHERE user_id = ?1", [resolved.user.user_id]);
+      });
       return withCors(req, Response.json({ ok: true, user_id: resolved.user.user_id, avatar_url: avatar.value }));
     }
 
+    // ── 账号头像上传（Hub 托管，非普通附件）──
+    //
+    // 契约（通信Mac马 交付单）：用户令牌 + multipart 仅一个 `file` 字段；PNG、
+    // 最长边 ≤512、≤8 MiB；服务端独立复核后原子覆盖本人头像；URL 由 Hub 发。
+    // 读取走 GET /api/users/:id/avatar/:version.png，按**人类资料可见性**判读
+    // （本人或共享网络的合法成员），不借用 /api/files 的附件 ACL。
+    if (url.pathname === "/api/auth/me/avatar/upload" && req.method === "POST") {
+      // pre-drain 拒绝统一关闭连接：keepalive 上残留的 multipart 未读字节会把
+      // 下一个请求读成垃圾（与 /api/upload 的 earlyReject 同一理由）。
+      const earlyReject = (res: Response): Response => {
+        const wrapped = withCors(req, res);
+        wrapped.headers.set("Connection", "close");
+        return wrapped;
+      };
+      const token = req.headers.get("Authorization")?.replace("Bearer ", "");
+      if (!token) return earlyReject(Response.json({ ok: false, error: "token required" }, { status: 401 }));
+      const resolved = resolveToken(token);
+      if (!resolved) return earlyReject(Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
+      // 节点令牌代表机器，不是这个人：头像只能由本人用用户令牌写。
+      if (isNodeCredential(resolved)) return earlyReject(userTokenRequired(req));
+
+      // 解析 multipart **之前**先限流：否则一个被限流的调用方仍能让 Hub 读满 8 MiB。
+      const authCtx = resolveRequestAuth(req);
+      const rateKey = authCtx?.tokenId ?? `ip:${getClientIP(req, server)}`;
+      const rate = sharedUploadRateLimiter.check(rateKey);
+      if (!rate.allowed) {
+        const headers: Record<string, string> = {
+          "X-RateLimit-Limit": String(60),
+          "X-RateLimit-Remaining": "0",
+          "X-RateLimit-Reset": String(Math.floor(rate.resetAt / 1000)),
+        };
+        if (rate.retryAfterMs) headers["Retry-After"] = String(Math.ceil(rate.retryAfterMs / 1000));
+        return earlyReject(new Response(
+          JSON.stringify({ ok: false, error: "rate_limited", message: "Upload rate limit exceeded (60/hour). Try again later.", retry_after_ms: rate.retryAfterMs }),
+          { status: 429, headers: { ...headers, "Content-Type": "application/json; charset=utf-8" } },
+        ));
+      }
+
+      if (!isMultipart(req.headers.get("content-type"))) {
+        return earlyReject(Response.json({ ok: false, error: "multipart_required" }, { status: 415 }));
+      }
+      const declared = Number(req.headers.get("content-length") ?? NaN);
+      // 多留 1 MiB 给 multipart 信封；真正的二进制上限在解析后按 MAX_AVATAR_BYTES 再判一次。
+      if (Number.isFinite(declared) && declared > MAX_AVATAR_BYTES + 1024 * 1024) {
+        return earlyReject(Response.json({ ok: false, error: "too_large" }, { status: 413 }));
+      }
+      let form: FormData;
+      try { form = await req.formData(); } catch {
+        return withCors(req, Response.json({ ok: false, error: "invalid_multipart" }, { status: 400 }));
+      }
+      const fields = [...form.keys()];
+      const file = form.get(AVATAR_FIELD);
+      if (fields.length !== 1 || fields[0] !== AVATAR_FIELD || !(file instanceof File)) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_avatar_body", reason: "expected exactly one `file` part" }, { status: 400 }));
+      }
+      if (file.size > MAX_AVATAR_BYTES) return withCors(req, Response.json({ ok: false, error: "too_large" }, { status: 413 }));
+      const bytes = new Uint8Array(await file.arrayBuffer());
+      const check = inspectAvatarImage(bytes);
+      if (!check.ok) return withCors(req, Response.json({ ok: false, error: "invalid_image", reason: check.reason }, { status: 400 }));
+      const version = crypto.randomUUID().replace(/-/g, "");
+      const url = avatarUrl(resolved.user.user_id, version);
+      // 头像表与用户资料必须在同一事务里落地：否则会出现「上传成功但资料页还是旧头像」，
+      // 或反过来点了清空却仍能读到旧字节。
+      db.transaction(() => {
+        db.run(
+          `INSERT INTO user_avatar_uploads (user_id, version, png, bytes, width, height, updated_at)
+           VALUES (?1, ?2, ?3, ?4, ?5, ?6, datetime('now'))
+           ON CONFLICT(user_id) DO UPDATE SET
+             version = excluded.version, png = excluded.png, bytes = excluded.bytes,
+             width = excluded.width, height = excluded.height, updated_at = excluded.updated_at`,
+          [resolved.user.user_id, version, bytes, bytes.byteLength, check.width, check.height],
+        );
+        db.run("UPDATE users SET avatar_url = ?1, updated_at = datetime('now') WHERE user_id = ?2", [url, resolved.user.user_id]);
+      });
+      // 回读用户资料行，确认读取面能看到这张新头像（而不是只信内存里的变量）。
+      const persisted = db.get<{ avatar_url: string | null }>("SELECT avatar_url FROM users WHERE user_id = ?1", [resolved.user.user_id]);
+      if (persisted?.avatar_url !== url) {
+        return withCors(req, Response.json({ ok: false, error: "avatar_persist_failed" }, { status: 500 }));
+      }
+      return withCors(req, Response.json({ ok: true, user_id: resolved.user.user_id, avatar_url: url }));
+    }
+
+    // GET /api/users/:user_id/avatar/:version.png —— Bearer 用户令牌鉴权。
+    // 可见性 = 本人，或与调用者共享至少一个网络的合法人类成员；节点令牌不是「人」。
+    // 不可见与不存在都回 404：不让人用状态码探测别人的账号是否存在。
+    const userAvatarMatch = url.pathname.match(/^\/api\/users\/([^/]+)\/avatar\/([^/]+)\.png$/);
+    if (userAvatarMatch && req.method === "GET") {
+      const [, rawUserId, rawVersion] = userAvatarMatch;
+      let targetUserId: string;
+      try { targetUserId = decodeURIComponent(rawUserId); } catch {
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      }
+      if (!isValidAvatarVersion(rawVersion)) return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      const token = req.headers.get("Authorization")?.replace("Bearer ", "");
+      if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
+      const resolved = resolveToken(token);
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
+      if (isNodeCredential(resolved)) return userTokenRequired(req);
+      const callerId = resolved.user.user_id;
+      if (callerId !== targetUserId) {
+        // live membership：网络必须仍然存在（删除网络只留下 network_members 残行时不算共享）。
+        const shared = db.get<{ ok: number }>(
+          `SELECT 1 AS ok FROM network_members me
+             JOIN networks n ON n.network_id = me.network_id
+             JOIN network_members them ON them.network_id = me.network_id
+            WHERE me.user_id = ?1 AND them.user_id = ?2 LIMIT 1`,
+          [callerId, targetUserId],
+        );
+        if (!shared) return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      }
+      // 只服务「当前」头像：清空/替换后旧 version 立即失效，即使行还没被删。
+      const current = db.get<{ avatar_url: string | null }>(
+        "SELECT avatar_url FROM users WHERE user_id = ?1", [targetUserId],
+      );
+      if (!current || current.avatar_url !== avatarUrl(targetUserId, rawVersion)) {
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      }
+      const row = db.get<{ png: Uint8Array }>(
+        "SELECT png FROM user_avatar_uploads WHERE user_id = ?1 AND version = ?2",
+        [targetUserId, rawVersion],
+      );
+      if (!row) return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      return withCors(req, new Response(Buffer.from(row.png), {
+        status: 200,
+        headers: {
+          "Content-Type": "image/png",
+          // 头像随账号更新，不能让中间层缓存住旧的那张；也不做重定向。
+          "Cache-Control": "private, no-store",
+          "X-Content-Type-Options": "nosniff",
+        },
+      }));
+    }
+
     if (url.pathname === "/api/auth/me" && req.method === "PUT") {
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
@@ -2655,6 +2796,9 @@ return Bun.serve({
     });
     if (externalScheduleEditResponse) return withCors(req, externalScheduleEditResponse);
 
+    const sessionControlResponse = await nodeSessionControl(req, url);
+    if (sessionControlResponse) return withCors(req, sessionControlResponse);
+
     // Hub-owned scheduled tasks. Dashboard and mobile are management
     // clients only; each occurrence is dispatched as an ordinary task by the
     // scheduler started in startHub(). Node tokens are rejected in the

package/src/tool-audience-http.test.ts

@@ -207,7 +207,11 @@ describe("bytes per role (#476 ceilings stay meaningful per role)", () => {
   // tools. Measured on this combined tree: all 95 / 85,069 B; node 62 / 63,281 B
   // unchanged (protocol tools stay off the node list); user 62 / 59,409 B.
   // Ceilings keep about 400 B and nothing else.
-  const CEILINGS = { node: 63_700, user: 59_810, all: 85_500 } as const;
+  // #1894（2026-10-23）：新增一个 `departments` MCP 工具（list/create/update/delete/
+  // assign_agent 合并成一个，尽量小）。实测 node 64,112 B / user 60,117 B，比原上限
+  // 分别高 412 / 279 B —— 这是有意的功能增长（组织架构可由 Agent 直接调），不是文案偷偷变长。
+  // 留约 400 B 余量；再要加工具时请先合并动作或砍描述，别连续抬上限。
+  const CEILINGS = { node: 64_500, user: 60_500, all: 86_500 } as const;
   test("node / user / all", async () => {
     const node = await listTools(T.node_normal);
     const user = await listTools(T.owner);

package/src/tool-audience.ts

@@ -59,6 +59,8 @@ export const TOOL_AUDIENCE: Readonly<Record<string, ToolAudience>> = {
   upsert_network_secret: "both", list_network_secrets: "both", upsert_provider: "both", update_provider: "both",
   list_providers: "both", probe_provider_model: "both", get_probe_results: "both",
   requirements_list: "both", requirements_people: "both", requirements_get: "both", requirements_create: "both",
+  // #1894 —— 组织架构：人和 Agent 都能用（Agent 用它归部门，人用它看树）。
+  departments: "both",
   requirements_update: "both", requirements_checklist_toggle: "both", requirements_upsert_by_external_ref: "both",
   requirements_events: "both", requirements_comment: "both", projects_list: "both",
 };

package/src/tools-list-json-schema.test.ts

@@ -65,3 +65,30 @@ describe("#1756 tools/list", () => {
     } finally { await close(); }
   }, 20_000);
 });
+
+// #1075 / #2662 —— `node_secrets_capable` 是**节点自述**的一格，运行时把它放在
+// `config_snapshot` 里（agent-node/src/cli.ts:1894）。而 zod 对象默认**丢掉未声明
+// 的键**：只要 `config_snapshot` 的形状里没有这一条，节点上报得再好，到 Hub 也被
+// 静默剥掉 → 客户端「保存密钥」永远是灰的，日志里一个字都不会说。
+//
+// 所以钉在这里：`report_status.config_snapshot` 的形状里**必须有**这一格。
+// 剥掉它的方式有很多种（重写对象、加 .strict()、换 z.record），这条断言对它们都红。
+describe("#1075 node_secrets_capable survives report_status", () => {
+  test("config_snapshot's shape declares node_secrets_capable", async () => {
+    const { server, close } = await connect();
+    try {
+      const reg: Record<string, any> = (server as any)._registeredTools;
+      const shape = reg["report_status"]?.inputSchema?.shape ?? {};
+      const snapshotField = shape["config_snapshot"];
+      expect(snapshotField).toBeTruthy();
+      // config_snapshot 是 ZodOptional 包着 ZodObject：.unwrap() 之后才有 shape。
+      const unwrapped = (snapshotField as any)?.unwrap ? (snapshotField as any).unwrap() : snapshotField;
+      const inner = (unwrapped as any)?.shape ?? {};
+      expect(Object.keys(inner)).toContain("node_secrets_capable");
+      // 同族的另一格（daemon 级能力）也在这份形状里，顺手一起钉住。
+      expect(Object.keys(inner)).toContain("daemon_capabilities");
+    } finally {
+      await close();
+    }
+  });
+});

package/src/tools.ts

@@ -107,6 +107,7 @@ import { dispatchQueueInfo, queueDepthByNode, queueDepthKey } from "./task-queue
 import { parseHubTimestamp } from "./hub-timestamp";
 import { noteTerminalResultRead, purgeLogsResultNow, sweepNodeRequestContent } from "./node-request-retention.js";
 import { listTaskLateReplies } from "./task-late-replies.js";
+import { auditDepartment, createDepartment, deleteDepartment, listDepartments, setAgentDepartment, updateDepartment } from "./departments.js";
 
 function ts(): string {
   return new Date().toTimeString().slice(0, 8);
@@ -425,6 +426,96 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     content: [{ type: "text" as const, text: JSON.stringify(value) }],
   });
 
+  // ── #1894 组织架构：Agent 用 API 就能建部门、把 Agent 归进去（admin 2026-10-23：
+  // 不要靠人手动点）。写权限 = 网络 owner/admin（实测 `canWrite` 对普通成员也是 true，
+  // 口径太宽，所以这里显式判角色）；读权限 = 能读这个网络的人。
+  // 归属写的是 nodes.department_id，显式归属，绝不按负责人推断。
+  const deptReply = (value: Record<string, unknown>) => ({
+    content: [{ type: "text" as const, text: JSON.stringify(value) }],
+  });
+  const canManageDepartments = (netId: string | null): boolean => {
+    if (!netId) return false;
+    if (!enforceUserId) return canWrite(netId); // legacy open mode
+    const role = getUserNetworkRole(enforceUserId, netId);
+    return role === "owner" || role === "admin";
+  };
+  const deptFail = (result: any) =>
+    deptReply({ ok: false, error: result?.error ?? "department_failed", status: result?.status ?? 400, ...(result?.children || result?.members || result?.agents ? { children: result.children, members: result.members, agents: result.agents } : {}) });
+
+  server.tool(
+    "departments",
+    "Agent org structure: list / create / update / delete / assign_agent. Writes need network owner or admin; assign_agent sets nodes.department_id.",
+    {
+      action: z.enum(["list", "create", "update", "delete", "assign_agent"]),
+      department_id: z.string().max(64).nullable().optional(),
+      name: z.string().min(1).max(80).optional(),
+      parent_id: z.string().max(64).nullable().optional(),
+      node_id: z.string().max(200).optional(),
+      alias: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ action, department_id, name, parent_id, node_id, alias, network_id: clientNetId }) => {
+      const netId = getNetworkId(clientNetId);
+      if (!netId) return deptReply({ ok: false, error: "network_required" });
+      if (action === "list") {
+        if (!canManageDepartments(netId) && !canWriteHuman(netId)) return writeDeniedReply(netId, "read") as any;
+        const listed = listDepartments(netId);
+        const agents = db.all<{ node_id: string; alias: string; department_id: string | null }>(
+          "SELECT node_id, alias, department_id FROM nodes WHERE network_id = ?1 ORDER BY alias", netId,
+        );
+        const counts = new Map<string, number>();
+        let unassigned = 0;
+        for (const a of agents) {
+          if (a.department_id) counts.set(a.department_id, (counts.get(a.department_id) ?? 0) + 1);
+          else unassigned += 1;
+        }
+        return deptReply({
+          ok: true, network_id: netId, unassigned_agents: unassigned, agents,
+          departments: listed.departments.map((d) => ({ ...d, agent_count: counts.get(d.id) ?? 0 })),
+        });
+      }
+      if (!canManageDepartments(netId)) return writeDeniedReply(netId, "write") as any;
+      const actor = { user_id: enforceUserId || "node", username: callerAlias || "agent" };
+      if (action === "create") {
+        if (!name) return deptReply({ ok: false, error: "invalid_department_name" });
+        const result = createDepartment(netId, enforceUserId || callerAlias || "mcp", {
+          name, ...(parent_id ? { parent_id } : {}), ...(department_id ? { id: department_id } : {}),
+        }) as any;
+        if (result?.ok === false) return deptFail(result);
+        auditDepartment(actor, "department_create", netId, String(result.department?.id ?? ""));
+        return deptReply({ ok: true, department: result.department });
+      }
+      if (action === "update") {
+        if (!department_id) return deptReply({ ok: false, error: "department_required" });
+        const body: Record<string, unknown> = {};
+        if (name !== undefined) body.name = name;
+        if (parent_id !== undefined) body.parent_id = parent_id;
+        const result = updateDepartment(netId, department_id, body) as any;
+        if (result?.ok === false) return deptFail(result);
+        auditDepartment(actor, "department_update", netId, `id=${department_id}`);
+        return deptReply({ ok: true, department: result.department });
+      }
+      if (action === "delete") {
+        if (!department_id) return deptReply({ ok: false, error: "department_required" });
+        const result = deleteDepartment(netId, department_id) as any;
+        if (result?.ok === false) return deptFail(result);
+        auditDepartment(actor, "department_delete", netId, `id=${department_id}`);
+        return deptReply({ ok: true, deleted: department_id });
+      }
+      let target = node_id ?? "";
+      if (!target && alias) {
+        const row = db.get<{ node_id: string }>("SELECT node_id FROM nodes WHERE network_id = ?1 AND alias = ?2", netId, resolveCanonicalAlias(netId, alias).alias);
+        if (!row) return deptReply({ ok: false, error: "agent_not_found" });
+        target = row.node_id;
+      }
+      if (!target) return deptReply({ ok: false, error: "agent_required" });
+      const result = setAgentDepartment(netId, target, department_id === undefined ? null : department_id) as any;
+      if (result?.ok === false) return deptFail(result);
+      auditDepartment(actor, "department_assign_agent", netId, `${target} -> ${department_id ?? "null"}`);
+      return deptReply({ ok: true, node_id: result.node_id, department_id: result.department_id });
+    },
+  );
+
   // SkillHub is a network registry, not a public filesystem. Content is an
   // immutable SKILL.md snapshot; identity comes only from the authenticated
   // MCP principal (never from request fields).