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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.144",
+  "version": "0.9.0-preview.145",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/db.ts

@@ -322,6 +322,21 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
 `);
 
+// 账号头像上传（二进制 PNG，Hub 自己发 URL）。与 users.avatar_url 并存：
+// avatar_url 仍可指向内建池/外链；这张表只存「上传到 Hub 本人的那张」。
+// 单行/人：新版本覆盖旧版本，旧 URL 立刻 404（version 变了），不做历史留存。
+db.exec(`
+  CREATE TABLE IF NOT EXISTS user_avatar_uploads (
+    user_id    TEXT PRIMARY KEY,
+    version    TEXT NOT NULL,
+    png        BLOB NOT NULL,
+    bytes      INTEGER NOT NULL,
+    width      INTEGER NOT NULL,
+    height     INTEGER NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+`);
+
 // Human profile avatar. Additive for existing databases; old binaries ignore it.
 try {
   db.exec("ALTER TABLE users ADD COLUMN avatar_url TEXT");

package/src/node-lifecycle-read-http.test.ts

@@ -66,8 +66,13 @@ test("public errors redact free text for granted viewers on every projection", a
       "adopt_codex_session_conflict", "adopt_codex_port_unavailable", "adopt_codex_stage_still_running",
       "adopt_codex_identity_unproven",
       "TUI session mismatch", "opencode_launch_health:TUI session mismatch", "opencode_tui_session_mismatch",
+      // #2012：daemon 明确拒绝的固定安全码，必须原样投影给用户，而不是退化成 lifecycle_error。
+      "copresence_adopt_v2",
+      // 负控：带后缀/路径/空白的形状仍必须清成 lifecycle_error（只精确放行这一串）。
+      "copresence_adopt_v2: /private/fixture", "copresence_adopt_v2x", " copresence_adopt_v2",
     ]) {
       const publicCodes = ["adopt_start_timeout", "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed", "opencode_tui_session_mismatch",
+        "copresence_adopt_v2",
         "adopt_codex_external_start_unproven", "adopt_codex_launch_failed", "adopt_codex_launch_timeout",
         "adopt_codex_port_unproven", "adopt_codex_start_superseded", "adopt_codex_binding_generation_unproven",
         "adopt_codex_start_evidence_missing", "adopt_codex_start_evidence_changed",

package/src/node-lifecycle-read.ts

@@ -33,6 +33,9 @@ const publicLifecycleErrors = new Set([
   "adopt_pane_process_mismatch", "adopt_socket_directory_unsafe", "adopt_socket_unsafe",
   "adopt_pid_changed", "adopt_pid_invalid", "adopt_pidfile_unsafe",
   "opencode_tui_session_mismatch",
+  // #2012 —— daemon 的 copresence_adopt_v2 拒绝是固定安全码（无路径/无异常文本），
+  // 不放行会让用户投影退化成 lifecycle_error，看不到「为什么被拒绝」。
+  "copresence_adopt_v2",
   "adopt_proc_invalid", "adopt_proc_unreadable", "adopt_platform_unsupported",
   "adopt_registry_conflict", "adopt_registry_entry_invalid", "adopt_registry_invalid",
   "adopt_registry_unsafe", "adopt_config_env_invalid", "adopt_env_file_invalid",

package/src/node-session-control-http.test.ts

@@ -0,0 +1,308 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, setSystemTime, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-session-control-"));
+process.env.COMMHUB_DB ||= join(dir, "hub.db");
+const root = "/api/node-session-control";
+let server: any, base: string, db: any, net: string, otherNet: string;
+let owner: any, admin: any, member: any, outsider: any, ntok: any, peer: any;
+let legacyOwner: any, legacyAdmin: any, legacyMember: any, legacyOutsider: any, legacyFull: any, legacyNetwork: any;
+let binding = { session_id: "session_1", binding_id: "binding_1" }, serial = 0;
+const nodeId = "n_session_control", peerId = "n_session_control_peer";
+async function api(token: string, path: string, value?: unknown, method?: string) {
+  const res = await fetch(`${base}${path}`, { method: method ?? (value === undefined ? "GET" : "POST"),
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    ...(value === undefined ? {} : { body: JSON.stringify(value) }) });
+  return { status: res.status, body: await res.json() as any };
+}
+const registerBridge = (v = binding, token = ntok.token!) => api(token, `${root}/bridge`,
+  { ...v, expected: { node_id: nodeId, network_id: net } });
+const enqueue = (operation = "background", extra = {}) => api(owner.token!, root,
+  { network_id: net, node_id: nodeId, operation, expected: binding, ...extra });
+const pull = (token = ntok.token!, v = binding) => api(token, `${root}/pull`, v);
+const read = (request: string, token = owner.token!, network = net) => api(token, `${root}/${request}?network_id=${network}`);
+const state = () => ({ ...binding, supported: true, active: true, can_request_background: true, observed_at: Date.now() });
+const ack = (request: string, result: unknown, extra = {}) => api(ntok.token!, `${root}/${request}/ack`,
+  { ...binding, status: "done", result, ...extra });
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register, addNetworkMember, createNetworkTokenForNode, createToken } = await import("./auth.js");
+  const stamp = Date.now();
+  admin = register(`sc_admin_${stamp}`, "SessionControl-Test-1!");
+  owner = register(`sc_owner_${stamp}`, "SessionControl-Test-2!");
+  member = register(`sc_member_${stamp}`, "SessionControl-Test-3!");
+  outsider = register(`sc_other_${stamp}`, "SessionControl-Test-4!");
+  expect(admin.ok && owner.ok && member.ok && outsider.ok).toBe(true);
+  net = admin.network_id!; otherNet = outsider.network_id!;
+  for (const u of [owner, member]) expect(addNetworkMember(net, u.user.user_id, "member", admin.user.user_id, { agentAccess: "all" }).ok).toBe(true);
+  // Real atok hashes via the legacy issuer; only fixture rows are converted
+  // to the historical global scope=user shape. No prefix-based authority.
+  const legacyUser = (u: any) => {
+    const t = createToken(u.user.user_id, "sc-legacy-user");
+    expect(t.ok).toBe(true);
+    expect(t.token).toMatch(/^atok_/);
+    db.run("UPDATE api_tokens SET scope='user' WHERE token_id=?1", t.token_id);
+    return t;
+  };
+  legacyOwner = legacyUser(owner); legacyAdmin = legacyUser(admin);
+  legacyMember = legacyUser(member); legacyOutsider = legacyUser(outsider);
+  legacyFull = createToken(owner.user.user_id, "sc-legacy-global-full");
+  legacyNetwork = createToken(owner.user.user_id, "sc-legacy-network", net);
+  expect(legacyFull.ok && legacyNetwork.ok).toBe(true);
+  ntok = createNetworkTokenForNode(owner.user.user_id, net, "sc-target", nodeId);
+  peer = createNetworkTokenForNode(owner.user.user_id, net, "sc-peer", peerId);
+  expect(ntok.ok && peer.ok).toBe(true);
+  db.run("INSERT INTO sessions(resume_id,alias,node_id,network_id,status) VALUES (?1,?2,?3,?4,'idle')", ["r_sc_target", "sc-target", nodeId, net]);
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+beforeEach(async () => {
+  binding = { session_id: `session_${++serial}`, binding_id: `binding_${serial}` };
+  expect((await registerBridge()).status).toBe(200);
+});
+afterEach(() => setSystemTime());
+afterAll(() => { server?.stop(true); rmSync(dir, { recursive: true, force: true }); });
+
+describe("#2017 human-to-exact-Bridge HTTP relay", () => {
+  test("[2017 identity] missing or malformed expected is refused without fallback", async () => {
+    for (const expected of [undefined, {}, { node_id: nodeId }, { node_id: nodeId, network_id: net, token_id: ntok.token_id }]) {
+      const rejected = await api(ntok.token!, `${root}/bridge`, { ...binding, expected });
+      expect(rejected.status).toBe(400);
+      expect(rejected.body.error).toBe("session_control_request_invalid");
+    }
+    expect((await registerBridge()).status).toBe(200);
+  });
+  test("[2017 identity] A credential expected B cannot sweep, replace or retire the valid binding", async () => {
+    const made = await enqueue("state"), clock = Date.now();
+    const tokenBefore = db.get("SELECT token_id,bound_node_id,network_id FROM api_tokens WHERE token_id=?1", ntok.token_id);
+    const nodeBefore = db.get("SELECT node_id,network_id,owner_user_id FROM nodes WHERE node_id=?1", nodeId);
+    // Advancing beyond the request deadline exposes an accidental sweep before
+    // rejecting expected. Restore only the clock, never the authoritative queue.
+    setSystemTime(new Date(clock + 16_000));
+    for (const expected of [{ node_id: peerId, network_id: net }, { node_id: nodeId, network_id: otherNet }]) {
+      const rejected = await api(ntok.token!, `${root}/bridge`, {
+        session_id: "would_replace_session", binding_id: "would_retire_binding", expected,
+      });
+      expect(rejected.status).toBe(409);
+      expect(rejected.body.error).toBe("session_control_changed");
+    }
+    setSystemTime(new Date(clock));
+    expect((await read(made.body.request_id)).body.status).toBe("pending");
+    expect((await registerBridge()).status).toBe(200); // Original generation was not retired.
+    expect((await pull()).body.request).toMatchObject({ request_id: made.body.request_id, ...binding });
+    expect(db.get("SELECT token_id,bound_node_id,network_id FROM api_tokens WHERE token_id=?1", ntok.token_id)).toEqual(tokenBefore);
+    expect(db.get("SELECT node_id,network_id,owner_user_id FROM nodes WHERE node_id=?1", nodeId)).toEqual(nodeBefore);
+  });
+  test("[2017 identity] success carries the authenticated token row identity, never credential material", async () => {
+    const response = await registerBridge();
+    const row = db.get("SELECT token_id,bound_node_id,network_id FROM api_tokens WHERE token_id=?1", ntok.token_id);
+    expect(response.status).toBe(200);
+    expect(response.body.identity).toEqual({ node_id: row.bound_node_id, network_id: row.network_id, token_id: row.token_id });
+    expect(Object.keys(response.body).sort()).toEqual(["expires_at", "identity", "ok"]);
+    expect(JSON.stringify(response.body)).not.toContain(ntok.token);
+  });
+  test("normal state and background receipts are separate from actual tool completion", async () => {
+    const s = await enqueue("state");
+    expect(s.body).toMatchObject({ ok: true, status: "pending" });
+    expect(s.body.request_id).toMatch(/^sc_\d{13}_[A-Za-z0-9_-]{8,64}$/);
+    expect((await pull()).body.request).toMatchObject({ request_id: s.body.request_id, operation: "state", ...binding });
+    const observed = state();
+    expect((await ack(s.body.request_id, observed)).body.status).toBe("done");
+    expect((await read(s.body.request_id)).body.result).toEqual(observed);
+    const b = await enqueue();
+    expect(b.body.request_id).toMatch(/^bg_\d{13}_[A-Za-z0-9_-]{8,64}$/);
+    expect(b.body.expires_at).toBeGreaterThan(Date.now());
+    await pull();
+    const result = { outcome: "request_processed", state: state() };
+    expect((await ack(b.body.request_id, result)).body.status).toBe("done");
+    expect((await read(b.body.request_id)).body).toMatchObject({ ok: true, status: "done", result });
+  });
+  test("[2017 review] already_idle cannot confirm an active or background-capable state", async () => {
+    for (const flags of [
+      { active: true, can_request_background: true },
+      { active: true, can_request_background: false },
+      { active: false, can_request_background: true },
+    ]) {
+      const made = await enqueue(); await pull();
+      const reply = await ack(made.body.request_id, { outcome: "already_idle", state: { ...state(), ...flags } });
+      expect(reply.status).toBe(400);
+      expect(reply.body.error).toBe("session_control_invalid_response");
+      expect((await read(made.body.request_id)).body).toMatchObject({ status: "unknown", error: "session_control_invalid_response" });
+    }
+  });
+  test("[2017 review] legacy user atok owner/admin and global full can create and read control", async () => {
+    for (const t of [legacyOwner, legacyAdmin, legacyFull]) {
+      for (const operation of ["state", "background"]) {
+        const made = await api(t.token, root, { network_id: net, node_id: nodeId, operation, expected: binding });
+        expect(made.status).toBe(200);
+        expect((await read(made.body.request_id, t.token)).body.status).toBe("pending");
+        expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+        const result = operation === "state" ? state() : { outcome: "request_processed", state: state() };
+        expect((await ack(made.body.request_id, result)).body.status).toBe("done");
+        expect((await read(made.body.request_id, t.token)).body.result).toEqual(result);
+      }
+    }
+  });
+  test("[2017 review] legacy atok still requires current target ownership and exact network", async () => {
+    for (const t of [legacyMember, legacyOutsider]) {
+      expect((await api(t.token, root, { network_id: net, node_id: nodeId, operation: "state" })).status).toBe(403);
+    }
+    expect((await api(legacyOwner.token, root, { network_id: otherNet, node_id: nodeId, operation: "state" })).status).toBe(403);
+    const made = await enqueue("state");
+    for (const t of [legacyMember, legacyOutsider]) expect((await read(made.body.request_id, t.token)).status).toBe(403);
+    expect((await read(made.body.request_id, legacyOwner.token, otherNet)).status).toBe(403);
+  });
+  test("[2017 review] legacy atok user and unbound network credentials cannot impersonate Bridge", async () => {
+    const made = await enqueue("state");
+    for (const t of [legacyOwner, legacyAdmin, legacyFull, legacyNetwork]) {
+      expect((await registerBridge(binding, t.token)).status).toBe(403);
+      expect((await pull(t.token)).status).toBe(403);
+      expect((await api(t.token, `${root}/${made.body.request_id}/ack`, { ...binding, status: "done", result: state() })).status).toBe(403);
+    }
+    expect((await read(made.body.request_id)).body.status).toBe("pending");
+    expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+  });
+  test("[2017 review] unknown, revoked, expired or unsupported-scope credentials stay refused", async () => {
+    const request = () => api(legacyOwner.token, root, { network_id: net, node_id: nodeId, operation: "state" });
+    expect((await api("atok_00000000000000000000000000000000", root, {})).status).toBe(401);
+    for (const patch of ["revoked_at=datetime('now')", "expires_at=datetime('now','-1 day')", "scope='unsupported'"]) {
+      db.run(`UPDATE api_tokens SET ${patch} WHERE token_id=?1`, legacyOwner.token_id);
+      try { expect((await request()).status).toBeGreaterThanOrEqual(400); }
+      finally { db.run("UPDATE api_tokens SET revoked_at=NULL,expires_at=NULL,scope='user' WHERE token_id=?1", legacyOwner.token_id); }
+    }
+    expect((await request()).status).toBe(200);
+  });
+  test("SSE is a scoped doorbell only; the request lives in pull", async () => {
+    const abort = new AbortController();
+    const response = await fetch(`${base}/events/sc-target`, { headers: { authorization: `Bearer ${ntok.token}` }, signal: abort.signal });
+    expect(response.status).toBe(200);
+    const reader = response.body!.getReader();
+    try {
+      const made = await enqueue();
+      let data = "";
+      for (let i = 0; i < 4 && !data.includes('"type":"session_control"'); i++) {
+        const next = await reader.read(); data += new TextDecoder().decode(next.value);
+      }
+      const event = data.split("\n").filter(s => s.startsWith("data: ")).map(s => JSON.parse(s.slice(6))).find(s => s.type === "session_control");
+      expect(event).toEqual({ type: "session_control", request_id: made.body.request_id });
+      expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+    } finally { abort.abort(); await reader.cancel().catch(() => {}); }
+  });
+  test("node, peer, anonymous, master and member cannot impersonate human owner/admin", async () => {
+    for (const token of [ntok.token, peer.token, "", "legacy-test-only", member.token, outsider.token]) {
+      expect((await api(token, root, { network_id: net, node_id: nodeId, operation: "state" })).status).toBeGreaterThanOrEqual(400);
+    }
+    const adminMade = await api(admin.token!, root, { network_id: net, node_id: nodeId, operation: "state" });
+    expect(adminMade.status).toBe(200);
+    expect((await read(adminMade.body.request_id, member.token!)).status).toBe(403);
+    expect((await read(adminMade.body.request_id, ntok.token!)).status).toBe(403);
+    expect((await read(adminMade.body.request_id, owner.token!, otherNet)).status).toBe(403);
+  });
+  test("cross-network, wrong expected, absent expected and command/path keys are refused", async () => {
+    expect((await enqueue("background", { network_id: otherNet })).status).toBe(403);
+    expect((await enqueue("background", { expected: { ...binding, session_id: "other_session" } })).body.error).toBe("session_control_changed");
+    expect((await api(owner.token!, root, { network_id: net, node_id: nodeId, operation: "background" })).status).toBe(400);
+    for (const key of ["url", "path", "keys", "shell"]) expect((await enqueue("state", { [key]: "unsafe" })).status).toBe(400);
+    expect((await registerBridge({ ...binding, node_id: peerId } as any)).status).toBe(400);
+  });
+  test("peer token and legacy unbound token never receive target requests", async () => {
+    const { createNetworkTokenForNode } = await import("./auth.js");
+    const legacy = createNetworkTokenForNode(owner.user.user_id, net, "sc-unbound");
+    expect(legacy.ok).toBe(true);
+    // Same-holder refreshes now bind existing rows. Construct an actual old
+    // unbound credential whose name only hints at this target instead.
+    db.run("UPDATE api_tokens SET name='node:sc-target' WHERE token_id=?1", legacy.token_id);
+    expect(db.get("SELECT bound_node_id FROM api_tokens WHERE token_id=?1", legacy.token_id).bound_node_id).toBeNull();
+    expect((await registerBridge(binding, legacy.token!)).status).toBe(403);
+    expect((await registerBridge(binding, owner.token!)).status).toBe(403);
+    const made = await enqueue();
+    expect((await pull(peer.token!)).body.request).toBeUndefined();
+    expect((await pull()).body.request.request_id).toBe(made.body.request_id);
+    expect((await api(peer.token!, `${root}/${made.body.request_id}/ack`, { ...binding, status: "done", result: state() })).status).toBe(409);
+  });
+  test("concurrent claims yield exactly one delivery and do not replay", async () => {
+    const made = await enqueue();
+    expect((await enqueue()).status).toBe(429);
+    const claims = await Promise.all([pull(), pull(), pull()]);
+    expect(claims.filter(r => r.body.request?.request_id === made.body.request_id)).toHaveLength(1);
+    expect((await read(made.body.request_id)).body.status).toBe("in_progress");
+    expect((await pull()).body.request).toBeNull();
+  });
+  test("expired pending request is never delivered", async () => {
+    const made = await enqueue();
+    setSystemTime(new Date(Date.now() + 16_000));
+    expect((await pull()).body.request).toBeNull();
+    expect((await read(made.body.request_id)).body.status).toBe("expired");
+  });
+  test("lost ACK becomes unknown, never success; late ACK and repeated pull cannot replay", async () => {
+    const made = await enqueue(); await pull();
+    setSystemTime(new Date(Date.now() + 16_000));
+    expect((await read(made.body.request_id)).body).toMatchObject({ status: "unknown", error: "session_background_outcome_unknown" });
+    expect((await ack(made.body.request_id, { outcome: "request_processed", state: state() })).status).toBe(409);
+    expect((await pull()).body.request).toBeNull();
+  });
+  test("new generation invalidates pending and cannot be overwritten by delayed old Bridge", async () => {
+    const old = { ...binding }, made = await enqueue();
+    binding = { session_id: "new_session", binding_id: `new_binding_${serial}` };
+    expect((await registerBridge()).status).toBe(200);
+    expect((await registerBridge(old)).body.error).toBe("session_control_changed");
+    expect((await pull(ntok.token!, old)).body.error).toBe("session_control_changed");
+    expect((await read(made.body.request_id)).body).toMatchObject({ status: "failed", error: "session_control_changed" });
+    expect((await pull()).body.request).toBeNull();
+  });
+  test("handle change after claim is unknown and old-session ACK cannot complete", async () => {
+    const old = { ...binding }, made = await enqueue(); await pull();
+    binding = { ...binding, binding_id: `changed_${serial}` }; await registerBridge();
+    expect((await api(ntok.token!, `${root}/${made.body.request_id}/ack`, { ...old, status: "done", result: { outcome: "already_idle", state: { ...state(), ...old } } })).status).toBe(409);
+    expect((await read(made.body.request_id)).body.status).toBe("unknown");
+  });
+  test("requester revocation before pull prevents delivery and current read permission is rechecked", async () => {
+    const made = await enqueue();
+    db.run("UPDATE network_members SET role='member' WHERE network_id=?1 AND user_id=?2", [net, owner.user.user_id]);
+    db.run("UPDATE nodes SET owner_user_id=?1 WHERE node_id=?2", [member.user.user_id, nodeId]);
+    try {
+      expect((await pull()).body.request).toBeNull();
+      expect((await read(made.body.request_id)).status).toBe(403);
+      expect((await read(made.body.request_id, admin.token!)).body.status).toBe("failed");
+    } finally { db.run("UPDATE nodes SET owner_user_id=?1 WHERE node_id=?2", [owner.user.user_id, nodeId]); }
+  });
+  test("target token revocation is checked at pull, not only registration", async () => {
+    const made = await enqueue();
+    db.run("UPDATE api_tokens SET revoked_at=datetime('now') WHERE token_id=?1", ntok.token_id);
+    try {
+      expect((await pull()).status).toBeGreaterThanOrEqual(400);
+      expect((await read(made.body.request_id)).body.status).toBe("failed");
+    } finally { db.run("UPDATE api_tokens SET revoked_at=NULL WHERE token_id=?1", ntok.token_id); }
+  });
+  test("malformed runtime results and raw exception strings never become success or leak", async () => {
+    const made = await enqueue(); await pull();
+    const reply = await ack(made.body.request_id, { outcome: "request_processed", state: { ...state(), binding_id: "wrong" } });
+    expect(reply.status).toBe(400);
+    expect((await read(made.body.request_id)).body).toMatchObject({ status: "unknown", error: "session_control_invalid_response" });
+    const next = await enqueue(); await pull();
+    const secret = "http://secret-host/?token=ntok_secret";
+    expect((await api(ntok.token!, `${root}/${next.body.request_id}/ack`, { ...binding, status: "failed", error: secret })).body.error).toBe("session_control_invalid_response");
+    expect(JSON.stringify((await read(next.body.request_id)).body)).not.toContain(secret);
+  });
+  test("known runtime refusal is failed; already_idle receipt is accepted", async () => {
+    const made = await enqueue(); await pull();
+    expect((await api(ntok.token!, `${root}/${made.body.request_id}/ack`, { ...binding, status: "failed", error: "session_control_unsupported" })).body.status).toBe("failed");
+    const next = await enqueue(); await pull();
+    expect((await ack(next.body.request_id, { outcome: "already_idle", state: { ...state(), active: false, can_request_background: false } })).body.status).toBe("done");
+  });
+  test("lease expiry refuses new work and Hub restart loses IDs without replay", async () => {
+    const made = await enqueue();
+    setSystemTime(new Date(Date.now() + 76_000));
+    expect((await enqueue()).body.error).toBe("session_control_unavailable");
+    setSystemTime();
+    server.stop(true);
+    const { bootServer } = await import("./server.js");
+    server = bootServer({ port: 0, hostname: "127.0.0.1" }); base = `http://127.0.0.1:${server.port}`;
+    expect((await read(made.body.request_id)).status).toBe(404);
+    expect((await pull()).body.error).toBe("session_control_changed");
+  });
+});

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/user-avatar-image.ts

@@ -0,0 +1,153 @@
+// #725-adjacent? No: Hub 专用账号头像上传（通信Mac马 交付单）。
+//
+// 头像不是普通附件：它必须 PNG、边长 ≤512、≤8 MiB，且只能由本人用自己的
+// **用户令牌**写入；读取按「人类资料可见性」（本人或共享网络的合法成员）判定，
+// 不借用 /api/files 的附件 ACL（那是按网络/会话/DM 作用域判的，语义不同）。
+//
+// 这个模块只做纯校验，便于单测与复用；HTTP 与落库在 server.ts。
+import { inflateSync } from "node:zlib";
+
+// 校验强度：结构（签名/chunk/CRC）+ 真实解码（IDAT 解压且扫描行长度与 IHDR 相符）。
+
+export const MAX_AVATAR_BYTES = 8 * 1024 * 1024;
+/** 客户端会把图重编码到最长边 512；服务端独立复核这条上限。 */
+export const MAX_AVATAR_EDGE = 512;
+/** version 只允许 URL 安全字符，长度有界（避免拼路径时引入 `.`、`/`）。 */
+export const AVATAR_VERSION_RE = /^[A-Za-z0-9_-]{1,128}$/;
+export const AVATAR_FIELD = "file";
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+export type AvatarImageCheck =
+  | { ok: true; width: number; height: number }
+  | { ok: false; reason: "empty" | "too_large" | "not_png" | "truncated" | "bad_dimensions" | "too_big" | "bad_crc" | "bad_image" | "interlaced_unsupported" };
+
+const CHANNELS: Record<number, number> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+
+/** 标准 CRC-32（PNG 每个 chunk 的尾部）。表只建一次。 */
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function be32(bytes: Uint8Array, offset: number): number {
+  return ((bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]) >>> 0;
+}
+
+/**
+ * PNG 结构校验：签名 + 逐个 chunk 的 CRC + 必须有 IDAT 且以 IEND 结尾。
+ *
+ * 只信任「结构完整」而不是「声明了什么」：截断的 33/40 字节、零填充的伪图
+ * （IHDR 对但 CRC 与 IDAT 缺失）都会被拒；合法用户因此不能把已有头像
+ * 覆盖成一张显示不出来的图。
+ */
+export function inspectAvatarImage(input: Uint8Array): AvatarImageCheck {
+  if (input.byteLength === 0) return { ok: false, reason: "empty" };
+  if (input.byteLength > MAX_AVATAR_BYTES) return { ok: false, reason: "too_large" };
+  for (let i = 0; i < PNG_SIGNATURE.length && i < input.byteLength; i++) {
+    if (input[i] !== PNG_SIGNATURE[i]) return { ok: false, reason: "not_png" };
+  }
+  if (input.byteLength < 45) return { ok: false, reason: "truncated" }; // 签名 + IHDR(25) + 最小 IEND(12)
+
+  let pos = 8;
+  let width = 0;
+  let height = 0;
+  let sawIHDR = false;
+  let idatChunks = 0;
+  let sawIEND = false;
+  let sawPLTE = false;
+  let bitDepth = 0;
+  let colorType = 0;
+  const idat: Uint8Array[] = [];
+
+  while (pos + 12 <= input.byteLength) {
+    const length = be32(input, pos);
+    const type = String.fromCharCode(input[pos + 4], input[pos + 5], input[pos + 6], input[pos + 7]);
+    const dataStart = pos + 8;
+    const dataEnd = dataStart + length;
+    const crcEnd = dataEnd + 4;
+    if (crcEnd > input.byteLength) return { ok: false, reason: "truncated" };
+    if (!sawIHDR && type !== "IHDR") return { ok: false, reason: "not_png" };
+    if ((crc32(input.subarray(pos + 4, dataEnd)) >>> 0) !== be32(input, dataEnd)) {
+      return { ok: false, reason: "bad_crc" };
+    }
+    if (type === "IHDR") {
+      if (sawIHDR || length !== 13) return { ok: false, reason: "not_png" };
+      width = be32(input, dataStart);
+      height = be32(input, dataStart + 4);
+      bitDepth = input[dataStart + 8];
+      colorType = input[dataStart + 9];
+      const compression = input[dataStart + 10];
+      const filter = input[dataStart + 11];
+      const interlace = input[dataStart + 12];
+      // 只接受规范的 IHDR 取值组合；非法组合的图多数解码器也会拒绝。
+      const legalDepth: Record<number, number[]> = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+      if (!legalDepth[colorType]?.includes(bitDepth)) return { ok: false, reason: "not_png" };
+      if (compression !== 0 || filter !== 0) return { ok: false, reason: "not_png" };
+      // 本实现只校验逐行（interlace=0）扫描布局：Adam7(=1) 的布局不同，其余取值(2..255)
+      // 在 PNG 规范里根本不合法。一律明确拒收，而不是错算长度后放行。
+      if (interlace !== 0) return { ok: false, reason: "interlaced_unsupported" };
+      if (width === 0 || height === 0) return { ok: false, reason: "bad_dimensions" };
+      if (width > MAX_AVATAR_EDGE || height > MAX_AVATAR_EDGE) return { ok: false, reason: "too_big" };
+      sawIHDR = true;
+    } else if (type === "PLTE") {
+      if (length === 0 || length % 3 !== 0) return { ok: false, reason: "not_png" };
+      sawPLTE = true;
+    } else if (type === "IDAT") {
+      idatChunks++;
+      idat.push(input.subarray(dataStart, dataEnd));
+    } else if (type === "IEND") {
+      if (length !== 0) return { ok: false, reason: "not_png" };
+      if (crcEnd !== input.byteLength) return { ok: false, reason: "not_png" };
+      sawIEND = true;
+      break;
+    }
+    pos = crcEnd;
+  }
+
+  if (!sawIHDR || !sawIEND) return { ok: false, reason: "truncated" };
+  if (idatChunks === 0) return { ok: false, reason: "not_png" };
+  // 调色板图必须带 PLTE，否则解码器无从取色。
+  if (colorType === 3 && !sawPLTE) return { ok: false, reason: "not_png" };
+  // CRC 只证明「容器没坏」，不证明 IDAT 里是图像数据：真解一次 zlib，并核对
+  // 解压后长度正好等于 IHDR 声明的扫描行总长（每行 1 字节 filter + 像素字节）。
+  const bytesPerRow = Math.ceil((width * (CHANNELS[colorType] ?? 0) * bitDepth) / 8);
+  const expected = height * (1 + bytesPerRow);
+  let raw: Uint8Array;
+  try {
+    const merged = Buffer.concat(idat.map(part => Buffer.from(part)));
+    raw = new Uint8Array(inflateSync(merged, { maxOutputLength: expected + 1024 }));
+  } catch {
+    return { ok: false, reason: "bad_image" };
+  }
+  if (raw.byteLength !== expected) return { ok: false, reason: "bad_image" };
+  for (let row = 0; row < height; row++) {
+    if (raw[row * (1 + bytesPerRow)] > 4) return { ok: false, reason: "bad_image" }; // 过滤器 0..4
+  }
+  return { ok: true, width, height };
+}
+
+export function isValidAvatarVersion(value: unknown): value is string {
+  return typeof value === "string" && AVATAR_VERSION_RE.test(value);
+}
+
+export function avatarUrl(userId: string, version: string): string {
+  return `/api/users/${encodeURIComponent(userId)}/avatar/${version}.png`;
+}
+
+/** 只接受 multipart 里的单张图；多余字段一律拒绝，避免「顺手塞个 filename 覆盖路径」。 */
+export function isMultipart(contentType: string | null): boolean {
+  return !!contentType && /^multipart\/form-data\b/i.test(contentType);
+}

package/src/user-avatar-upload-http.test.ts

@@ -0,0 +1,294 @@
+import { expect, test } from "bun:test";
+import { register, createNetworkTokenForNode, addNetworkMember } from "./auth.js";
+import { db } from "./db.js";
+import { inspectAvatarImage, MAX_AVATAR_BYTES } from "./user-avatar-image.js";
+import { deflateSync } from "node:zlib";
+
+// 1×1 PNG（透明）。只用来走真实 multipart → 真实文件头校验。
+const PNG_1X1 = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+  "base64",
+);
+/** 真的 8-bit RGBA PNG：IHDR + 一段 zlib 压缩的扫描行 + IEND，CRC 全对。 */
+function realPng(width: number, height: number): Buffer {
+  const crcTable = new Uint32Array(256).map((_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+  });
+  const crc = (buf: Buffer) => {
+    let c = 0xffffffff;
+    for (const byte of buf) c = crcTable[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const chunk = (type: string, data: Buffer) => {
+    const len = Buffer.alloc(4); len.writeUInt32BE(data.length);
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const sum = Buffer.alloc(4); sum.writeUInt32BE(crc(body));
+    return Buffer.concat([len, body, sum]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0; // 8-bit RGBA
+  const raw = Buffer.alloc((1 + width * 4) * height); // 每行前面一个 filter 字节 0
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw)),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+
+/** CRC 全对、但 IDAT 内容非法的 PNG：用来证明「结构通过 ≠ 图像有效」。 */
+function pngWithIdat(idat: Buffer, opts: { colorType?: number; bitDepth?: number; width?: number; height?: number; interlace?: number } = {}): Buffer {
+  const crcTable = new Uint32Array(256).map((_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+  });
+  const crc = (buf: Buffer) => {
+    let c = 0xffffffff;
+    for (const byte of buf) c = crcTable[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const chunk = (type: string, data: Buffer) => {
+    const len = Buffer.alloc(4); len.writeUInt32BE(data.length);
+    const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    const sum = Buffer.alloc(4); sum.writeUInt32BE(crc(body));
+    return Buffer.concat([len, body, sum]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(opts.width ?? 1, 0); ihdr.writeUInt32BE(opts.height ?? 1, 4);
+  ihdr[8] = opts.bitDepth ?? 8; ihdr[9] = opts.colorType ?? 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = opts.interlace ?? 0;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr), chunk("IDAT", idat), chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+test("account avatar upload: user token only, PNG limits, visibility by shared network, revoke, atomic replace", async () => {
+  const a = register("avup_alice", "AvatarUpload1!");
+  const b = register("avup_bob", "AvatarUpload1!");
+  const outsider = register("avup_outsider", "AvatarUpload1!");
+  expect(a.ok && b.ok && outsider.ok).toBe(true);
+  expect(addNetworkMember(a.network_id!, b.user!.user_id, "member").ok).toBe(true);
+  const node = createNetworkTokenForNode(a.user!.user_id, a.network_id!, "avup_alice", "avup_node");
+  expect(node.ok).toBe(true);
+
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+
+  const upload = async (token: string | null, bytes: Buffer, fieldName = "file", extra?: [string, string]) => {
+    const form = new FormData();
+    form.append(fieldName, new Blob([new Uint8Array(bytes)], { type: "image/png" }), "a.png");
+    if (extra) form.append(extra[0], extra[1]);
+    const headers: Record<string, string> = {};
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(`${base}/api/auth/me/avatar/upload`, { method: "POST", headers, body: form });
+    const body = await res.json().catch(() => null);
+    return { status: res.status, body: body as any };
+  };
+  const getAvatar = async (token: string | null, path: string) => {
+    const res = await fetch(base + path, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
+    return { status: res.status, headers: res.headers, bytes: new Uint8Array(await res.arrayBuffer()) };
+  };
+
+  try {
+    // 前置：陌生人之间没有共享网络。
+    expect(db.get("SELECT 1 AS ok FROM network_members m WHERE m.user_id=?1 AND m.network_id=?2", outsider.user!.user_id, a.network_id!)).toBeNull();
+
+    // 匿名/节点令牌都不是「本人」。
+    expect((await upload(null, PNG_1X1)).status).toBe(401);
+    expect((await upload(node.token!, PNG_1X1)).status).toBe(403);
+
+    // 畸形输入：非 PNG、超边长、空、多字段、非 multipart。
+    expect((await upload(a.token!, Buffer.from("not a png"))).body.error).toBe("invalid_image");
+    expect((await upload(a.token!, realPng(600, 600))).body.reason).toBe("too_big");
+    expect((await upload(a.token!, Buffer.alloc(0))).status).toBe(400);
+    expect((await upload(a.token!, PNG_1X1, "other")).status).toBe(400);
+    expect((await upload(a.token!, PNG_1X1, "file", ["avatar_url", "/etc/passwd"])).status).toBe(400);
+    const notMultipart = await fetch(`${base}/api/auth/me/avatar/upload`, {
+      method: "POST", headers: { Authorization: `Bearer ${a.token}`, "Content-Type": "application/json" }, body: "{}",
+    });
+    expect(notMultipart.status).toBe(415);
+
+    // 成功：URL 由 Hub 发，version 只含 URL 安全字符。
+    const ok1 = await upload(a.token!, PNG_1X1);
+    expect(ok1.status).toBe(200);
+    expect(ok1.body.ok).toBe(true);
+    expect(ok1.body.user_id).toBe(a.user!.user_id);
+    expect(ok1.body.avatar_url).toMatch(new RegExp(`^/api/users/${a.user!.user_id}/avatar/[A-Za-z0-9_-]{1,128}\\.png$`));
+
+    // 资料读取面必须同步看到这张头像（同一事务写 users.avatar_url）。
+    const meAfter = await fetch(`${base}/api/auth/me`, { headers: { Authorization: `Bearer ${a.token}` } });
+    const meBody = await meAfter.json() as any;
+    expect(meBody.user.avatar_url).toBe(ok1.body.avatar_url);
+
+    const first = await getAvatar(a.token!, ok1.body.avatar_url);
+    expect(first.status).toBe(200);
+    expect(first.headers.get("content-type")).toBe("image/png");
+    expect(first.headers.get("cache-control")).toBe("private, no-store");
+    expect(first.headers.get("location")).toBeNull();
+    expect(first.bytes.byteLength).toBe(PNG_1X1.byteLength);
+
+    // 同网络成员可读；不同网络的人读不到（与不存在同码，避免探测）。
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(200);
+    expect((await getAvatar(outsider.token!, ok1.body.avatar_url)).status).toBe(404);
+    expect((await getAvatar(null, ok1.body.avatar_url)).status).toBe(401);
+    expect((await getAvatar(node.token!, ok1.body.avatar_url)).status).toBe(403);
+    expect((await getAvatar(a.token!, `/api/users/${a.user!.user_id}/avatar/nope..%2F.png`)).status).toBe(404);
+
+    // 撤权后立刻读不到。
+    expect(db.run("DELETE FROM network_members WHERE user_id=?1 AND network_id=?2", [b.user!.user_id, a.network_id!]).changes).toBeGreaterThan(0);
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(404);
+
+    // 「CRC 正确但图像数据非法」也必须 400：结构通过不等于可解码。
+    const beforeInvalid = db.get<{ version: string; bytes: number }>(
+      "SELECT version, bytes FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id);
+    expect((await upload(a.token!, pngWithIdat(Buffer.alloc(0)))).body.reason).toBe("bad_image");
+    expect((await upload(a.token!, pngWithIdat(Buffer.from("not-a-zlib-stream")))).body.reason).toBe("bad_image");
+    // 解压成功但扫描行长度不符（声明 2×2 RGBA，实际只给 1×1）
+    expect((await upload(a.token!, pngWithIdat(deflateSync(Buffer.alloc(5)), { width: 2, height: 2 }))).body.reason).toBe("bad_image");
+    const afterInvalid = db.get<{ version: string; bytes: number }>(
+      "SELECT version, bytes FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id);
+    expect(afterInvalid).toEqual(beforeInvalid);
+
+    // P2：清空后旧托管 URL 立即失效（本人与同网络成员都不能再读到）。
+    const putProfile = async (token: string, avatar_url: string | null) => {
+      const res = await fetch(`${base}/api/auth/me/avatar`, {
+        method: "PUT", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ avatar_url }),
+      });
+      return { status: res.status, body: await res.json() as any };
+    };
+    // 重新造一张可读的：此刻 b 已被撤权，先用 outsider 之外的同网成员做读校验
+    expect(addNetworkMember(a.network_id!, b.user!.user_id, "member").ok).toBe(true);
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(200);
+    expect((await putProfile(a.token!, null)).status).toBe(200);
+    expect((await getAvatar(a.token!, ok1.body.avatar_url)).status).toBe(404);
+    expect((await getAvatar(b.token!, ok1.body.avatar_url)).status).toBe(404);
+    const meCleared = await fetch(`${base}/api/auth/me`, { headers: { Authorization: `Bearer ${a.token}` } });
+    expect(((await meCleared.json()) as any).user.avatar_url).toBeNull();
+    expect(db.get("SELECT 1 AS ok FROM user_avatar_uploads WHERE user_id=?1", [a.user!.user_id])).toBeNull();
+
+    // 换成池里的一张（非托管 URL）也必须撤销旧托管行。
+    const again = await upload(a.token!, PNG_1X1);
+    expect(again.status).toBe(200);
+    expect((await getAvatar(a.token!, again.body.avatar_url)).status).toBe(200);
+    expect((await putProfile(a.token!, "/avatars/avatar-03.webp")).status).toBe(200);
+    expect((await getAvatar(a.token!, again.body.avatar_url)).status).toBe(404);
+    expect(db.get("SELECT 1 AS ok FROM user_avatar_uploads WHERE user_id=?1", [a.user!.user_id])).toBeNull();
+
+    // 原子替换：一次失败的上传不能把上一张弄丢；成功后旧 version 立刻 404。
+    const baseline = await upload(a.token!, PNG_1X1);
+    expect(baseline.status).toBe(200);
+    const beforeBad = db.get<{ version: string }>("SELECT version FROM user_avatar_uploads WHERE user_id=?1", [a.user!.user_id]);
+    expect(beforeBad?.version).toBeTruthy();
+    expect((await upload(a.token!, Buffer.from("broken"))).status).toBe(400);
+    expect(db.get<{ version: string }>("SELECT version FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id)!.version).toBe(beforeBad!.version);
+    expect((await getAvatar(a.token!, baseline.body.avatar_url)).status).toBe(200);
+
+    const ok2 = await upload(a.token!, realPng(512, 512));
+    expect(ok2.status).toBe(200);
+    expect(ok2.body.avatar_url).not.toBe(baseline.body.avatar_url);
+    expect((await getAvatar(a.token!, baseline.body.avatar_url)).status).toBe(404);
+    expect((await getAvatar(a.token!, ok2.body.avatar_url)).status).toBe(200);
+    expect(db.get<{ width: number }>("SELECT width FROM user_avatar_uploads WHERE user_id=?1", a.user!.user_id)!.width).toBe(512);
+  } finally {
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id IN (?1, ?2, ?3)", [a.user!.user_id, b.user!.user_id, outsider.user!.user_id]);
+    await hub.stop?.();
+  }
+});
+
+test("deleted network leaves only ghost membership: member loses read, owner keeps it", async () => {
+  const owner = register("avup_netowner", "AvatarUpload1!");
+  const member = register("avup_netmember", "AvatarUpload1!");
+  expect(owner.ok && member.ok).toBe(true);
+  expect(addNetworkMember(owner.network_id!, member.user!.user_id, "member").ok).toBe(true);
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+  const read = async (token: string, path: string) => (await fetch(base + path, { headers: { Authorization: `Bearer ${token}` } })).status;
+  try {
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(PNG_1X1)], { type: "image/png" }), "a.png");
+    const up = await fetch(`${base}/api/auth/me/avatar/upload`, { method: "POST", headers: { Authorization: `Bearer ${owner.token}` }, body: form });
+    expect(up.status).toBe(200);
+    const url = ((await up.json()) as any).avatar_url as string;
+    expect(await read(member.token!, url)).toBe(200);
+    // 只删网络行，故意留下 network_members 残行：live membership 必须据此拒绝。
+    db.run("DELETE FROM networks WHERE network_id = ?1", [owner.network_id!]);
+    expect(await read(member.token!, url)).toBe(404);
+    expect(await read(owner.token!, url)).toBe(200); // 本人不依赖成员关系
+  } finally {
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id = ?1", [owner.user!.user_id]);
+    db.run("UPDATE users SET avatar_url = NULL WHERE user_id = ?1", [owner.user!.user_id]);
+    await hub.stop?.();
+  }
+});
+
+test("upload is rate limited before multipart parsing, and rejects keepalive leftovers", async () => {
+  const u = register("avup_ratelimit", "AvatarUpload1!");
+  expect(u.ok).toBe(true);
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+  const send = async (body: BodyInit | null, contentType?: string) => {
+    const headers: Record<string, string> = { Authorization: `Bearer ${u.token}` };
+    if (contentType) headers["Content-Type"] = contentType;
+    const res = await fetch(`${base}/api/auth/me/avatar/upload`, { method: "POST", headers, body });
+    return { status: res.status, connection: res.headers.get("connection"), body: await res.json().catch(() => null) as any };
+  };
+  const multipart = () => {
+    const form = new FormData();
+    form.append("file", new Blob([PNG_1X1], { type: "image/png" }), "a.png");
+    return form;
+  };
+  try {
+    // 60 次成功用满这一小时的桶（每张 1×1，成本可忽略）。
+    for (let i = 0; i < 60; i++) {
+      const r = await send(multipart());
+      expect(r.status).toBe(200);
+    }
+    const limited = await send(multipart());
+    expect(limited.status).toBe(429);
+    expect(limited.body.error).toBe("rate_limited");
+    expect(limited.connection).toBe("close");
+    // 关键：限流在 multipart 解析之前——普通 JSON 也被先拒成 429，而不是 415。
+    const early = await send("{}", "application/json");
+    expect(early.status).toBe(429);
+    expect(early.connection).toBe("close");
+  } finally {
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id = ?1", [u.user!.user_id]);
+    db.run("UPDATE users SET avatar_url = NULL WHERE user_id = ?1", [u.user!.user_id]);
+    await hub.stop?.();
+  }
+});
+
+test("image inspector: signature, shape and size limits", () => {
+  expect(inspectAvatarImage(PNG_1X1)).toEqual({ ok: true, width: 1, height: 1 });
+  expect(inspectAvatarImage(new Uint8Array(0))).toEqual({ ok: false, reason: "empty" });
+  expect(inspectAvatarImage(new Uint8Array(10))).toEqual({ ok: false, reason: "not_png" });
+  expect(inspectAvatarImage(Buffer.from(realPng(16, 16).subarray(0, 20)))).toEqual({ ok: false, reason: "truncated" });
+  expect(inspectAvatarImage(Buffer.from(realPng(16, 16).subarray(0, 40)))).toEqual({ ok: false, reason: "truncated" });
+  const truePng = realPng(16, 16);
+  const corrupt = Buffer.from(truePng); corrupt[corrupt.length - 20] ^= 0xff;
+  expect(inspectAvatarImage(corrupt).ok).toBe(false);
+  expect(inspectAvatarImage(realPng(513, 16))).toEqual({ ok: false, reason: "too_big" });
+  // Adam7 隔行：明确拒收（不按非隔行长度错算）
+  const interlaced = pngWithIdat(deflateSync(Buffer.alloc(6)), { width: 1, height: 1, interlace: 1 });
+  expect(inspectAvatarImage(interlaced)).toEqual({ ok: false, reason: "interlaced_unsupported" });
+  // 规范外取值 2..255：同样拒收（负控：扫描数据本来是非隔行的合法布局，
+  // 只有 interlace 字节非法，证明拦截来自 interlace 判断而不是解码失败）
+  for (const bad of [2, 3, 128, 255]) {
+    const invalidInterlace = pngWithIdat(deflateSync(Buffer.alloc(6)), { width: 1, height: 1, interlace: bad });
+    expect(inspectAvatarImage(invalidInterlace)).toEqual({ ok: false, reason: "interlaced_unsupported" });
+  }
+  const zeroWide = realPng(0, 1); // 宽 0 + 正确 CRC：专证 bad_dimensions 而不是 bad_crc
+  expect(inspectAvatarImage(zeroWide)).toEqual({ ok: false, reason: "bad_dimensions" });
+  const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0xe0, ...new Array(40).fill(0)]);
+  expect(inspectAvatarImage(jpeg)).toEqual({ ok: false, reason: "not_png" });
+  expect(inspectAvatarImage(Buffer.alloc(MAX_AVATAR_BYTES + 1))).toEqual({ ok: false, reason: "too_large" });
+});