@sleep2agi/commhub-server 0.9.0-preview.22 → 0.9.0-preview.24

package/src/server.ts

@@ -3,9 +3,10 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit } from "./db.js";
-import { createSSEStream, createNetworkObserverStream, pushEvent, pushNetworkObserverEvent, getSSEStats } from "./push.js";
+import { createSSEStream, createNetworkObserverStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { validateAvatarUrl } from "./avatar-validate.js";
+import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
 import { register, login, resolveToken, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getUserNetworkRole, addNetworkMember, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
 import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
 import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
@@ -213,6 +214,45 @@ function resolveRequestAuth(req: Request): { userId: string; networkId: string |
   return { userId: resolved.user.user_id, networkId: resolved.networkId, username: resolved.user.username, tokenName: resolved.tokenName, tokenId: resolved.tokenId };
 }
 
+// #495 — shared authorization gate for /api/files/:file_id downloads.
+// Called from the GET handler and any future HEAD/Range/dashboard-proxy
+// entry so the allow-list can't drift between methods (通信龙 clause 2:
+// "授权若只在 GET 分支实现, HEAD 或 Range 走别路径 = 等于没修").
+//
+// Returns true if the caller may read this entry; false otherwise. The
+// caller emits 404 on false — never 403; 403 would leak that the
+// file_id exists and enables enumeration.
+//
+// Allow-list (staged P0 hotfix; same-network non-owner is NOT included
+// here — see follow-up #503):
+//   - Legacy master AUTH_TOKEN (RFC-001 read-only) → allow.
+//   - admin utok_ → allow (mirrors requireAdminAuth).
+//   - Owner match: caller's resolved user_id === entry.owner_id.
+//   - null owner_id + DEV_OPEN → allow. DEV_OPEN uploads carry
+//     owner_id=null (authCtx=null in DEV_OPEN mode); rejecting them
+//     would break the intended local-dev anonymous flow. Encoded as
+//     an explicit env-gated branch so if DEV_OPEN semantics change,
+//     the code fails loudly instead of trusting a stale note.
+//   - Everything else → deny (404). New uploads in production always
+//     carry a truthy owner_id (requireAuth blocks the null-owner-
+//     producing path when DEV_OPEN=off and no legacy master token is
+//     configured), so denying null-owner in production closes the
+//     enumeration vector for legacy blobs without breaking new uploads.
+export function authorizeFileDownload(req: Request, entry: { owner_id?: unknown }): boolean {
+  const token = requestToken(req);
+  const authCtx = resolveRequestAuth(req);
+  const resolved = token ? resolveToken(token) : null;
+  const isLegacyMasterCaller = !authCtx && isLegacyAuthToken(req);
+  const isAdminCaller = !!resolved && resolved.user.role === "admin";
+  const ownerId = typeof entry.owner_id === "string" && entry.owner_id.length > 0
+    ? entry.owner_id
+    : null;
+  const isOwnerCaller = !!authCtx && !!ownerId && authCtx.userId === ownerId;
+  if (isLegacyMasterCaller || isAdminCaller || isOwnerCaller) return true;
+  if (ownerId === null && DEV_OPEN) return true;
+  return false;
+}
+
 type RestNetworkScope = {
   networkId: string | null;
   networkIds: string[] | null;
@@ -1157,10 +1197,86 @@ return Bun.serve({
       // now lives behind auth at GET /api/stats/sse.
       // `version` stays: it does help fingerprinting, but ops needs it
       // to verify deploys land, and the tradeoff was accepted in review.
+      //
+      // #495-followup / f28a6c1b — auth-gated `sse_sessions` restored so
+      // the dashboard's own "online" widget can compute per-agent status
+      // in one round-trip. Rules:
+      //   - anonymous (no valid token): NO sse_sessions field → watchdog
+      //     contract untouched, no topology leak (mutation removing this
+      //     gate turns the anonymous test RED — see health-redaction.test)
+      //   - admin utok_ / legacy master / DEV_OPEN: full sessions map
+      //     (parity with /api/stats/sse ops path)
+      //   - regular utok_ member: sessions map FILTERED to network_ids
+      //     the caller is a member of — safe against the "any account
+      //     sees all-network topology" regression the #473 fix closed;
+      //     dashboard user proxies with the logged-in user's utok_ so
+      //     their own network's aliases surface; strangers' networks do
+      //     not
       const count = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM sessions");
       const sse = getSSEStats();
       const license = db.get<any>("SELECT type, expires_at FROM licenses LIMIT 1");
-      return withCors(req, Response.json({
+
+      // Non-fatal auth probe (no 401 — /health must stay 200 anonymous).
+      const healthAuth = resolveRequestAuth(req);
+      const healthIsMaster = !healthAuth && isLegacyAuthToken(req);
+      const healthIsDevOpen = !healthAuth && !AUTH_TOKEN && DEV_OPEN;
+      const healthIsAdmin = !!(healthAuth?.username && db.get<any>(
+        "SELECT role FROM users WHERE username = ?1", healthAuth.username,
+      )?.role === "admin");
+
+      let scopedSessions: Record<string, number> | undefined;
+      if (healthIsMaster || healthIsDevOpen || healthIsAdmin) {
+        // Ops parity with /api/stats/sse — full map.
+        scopedSessions = sse.sessions;
+      } else if (healthAuth?.userId) {
+        // Regular authenticated member — filter to networks they belong
+        // to. Keys are `{networkId}:{alias}` (or observer keys shaped
+        // `\0netobs:{networkId}`); parse the network prefix and keep
+        // only entries whose network is in the member's set.
+        //
+        // 🔴 ntok_ (network-scoped token) MUST be forced to its single
+        // bound network (parity with resolveRestNetworkScope L277:
+        // `if (authCtx.networkId) return { networkId: authCtx.networkId }`).
+        // Falling through to the utok_ union query would return
+        // sessions from every network the underlying user belongs to,
+        // silently escalating a network-scoped token to a user-scoped
+        // token — the exact "认证 ≠ 已授权" mistake this whole change
+        // is meant to prevent. Same shape as f28a6c1b root cause; see
+        // CR3 audit 4703b0e7.
+        const memberNets = new Set<string>(
+          healthAuth.networkId
+            ? [healthAuth.networkId]  // ntok_ single-network enforce
+            : db.all<{ network_id: string }>(
+                "SELECT network_id FROM network_members WHERE user_id = ?1",
+                healthAuth.userId,
+              ).map((r) => r.network_id),
+        );
+        // If member has no networks at all, keep field present but empty
+        // so the dashboard can distinguish "authenticated + none active"
+        // from "not authenticated at all".
+        const filtered: Record<string, number> = {};
+        for (const [key, n] of Object.entries(sse.sessions)) {
+          // Observer keys are shape `\0netobs:<networkId>` raw; keyed
+          // through `printableKey()` in push.ts, they surface here as
+          // the literal string `\\0netobs:<networkId>` (backslash-zero,
+          // not NUL byte). Use the shared `PRINTABLE_OBSERVER_KEY_PREFIX`
+          // export so this side and the emitter side stay locked to the
+          // same literal — CR3 audit 4703b0e7 caught prior check
+          // `startsWith("netobs:")` was always false → observer keys
+          // silently over-filtered out of member views.
+          const isObserver = key.startsWith(PRINTABLE_OBSERVER_KEY_PREFIX);
+          const netId = isObserver
+            ? key.slice(PRINTABLE_OBSERVER_KEY_PREFIX.length)
+            : key.split(":")[0];
+          if (memberNets.has(netId)) filtered[key] = n;
+        }
+        scopedSessions = filtered;
+      }
+      // healthAuth == null AND no legacy master AND no DEV_OPEN → leave
+      // scopedSessions undefined → sse_sessions field omitted entirely
+      // (watchdog + arbitrary internet strangers see aggregates only).
+
+      const body: Record<string, unknown> = {
         ok: true,
         version: SERVER_VERSION,
         api_version: "v3",
@@ -1174,7 +1290,9 @@ return Bun.serve({
         multi_network: true,
         license: license?.type || "none",
         uptime: Math.floor(process.uptime()),
-      }));
+      };
+      if (scopedSessions !== undefined) body.sse_sessions = scopedSessions;
+      return withCors(req, Response.json(body));
     }
 
     // ── All REST /api endpoints require auth (if token configured) ──
@@ -1619,14 +1737,27 @@ return Bun.serve({
       }));
     }
 
-    // ── REST: file download (#221) ──
-    // GET /api/files/:file_id with Bearer auth. Always forces
-    // Content-Disposition: attachment + X-Content-Type-Options: nosniff
-    // so the served file can never be executed or rendered as HTML.
-    // The file_id is validated against the same strict regex used at
-    // generation time before any filesystem access.
+    // ── REST: file download (#221 + #495 + #500 CR2 HEAD) ──
+    // GET or HEAD /api/files/:file_id with Bearer auth + ownership
+    // check. Always forces Content-Disposition: attachment +
+    // X-Content-Type-Options: nosniff so the served file can never be
+    // executed or rendered as HTML. The file_id is validated against
+    // the same strict regex used at generation time before any
+    // filesystem access.
+    //
+    // Ownership gate is factored into `authorizeFileDownload` (see
+    // src/server.ts near resolveRequestAuth). HEAD MUST route through
+    // the same helper — pre-#500-CR2, HEAD fell through to a fallback
+    // 200 page whose body happened to be byte-identical to the
+    // "unknown file" case, so no enumeration oracle formed in practice.
+    // That was coincidence, not a gate. A change to the fallback (e.g.
+    // adding "Requested resource: <hint>") would materialize the oracle
+    // with zero failing tests. Any future Range, conditional-request,
+    // or dashboard-proxy path for /api/files MUST route through this
+    // handler (via authorizeFileDownload) — do not duplicate the
+    // allow-list inline, or the branches will drift.
     const fileMatch = url.pathname.match(/^\/api\/files\/(.+)$/);
-    if (fileMatch && req.method === "GET") {
+    if (fileMatch && (req.method === "GET" || req.method === "HEAD")) {
       const authErr = requireAuth(req);
       if (authErr) return withCors(req, authErr);
 
@@ -1648,6 +1779,15 @@ return Bun.serve({
         return withCors(req, Response.json({ ok: false, error: "index_invalid" }, { status: 500 }));
       }
 
+      // #495 ownership gate — placed AFTER file-exists so denied
+      // callers cannot distinguish "you don't own this" from
+      // "no such file". Both branches return the same 404 shape
+      // for BOTH GET and HEAD (HEAD honours body-omission but the
+      // status code and headers are the authoritative signal).
+      if (!authorizeFileDownload(req, entry)) {
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      }
+
       let storage;
       try {
         storage = buildStoragePath(entry.file_id, entry.ext);
@@ -1675,7 +1815,6 @@ return Bun.serve({
       const safeFilename = (entry.name && /^[\x20-\x7e]+$/.test(entry.name))
         ? entry.name
         : `${fileId}${entry.ext}`;
-      const blob = Bun.file(storage.absolutePath);
       const responseHeaders: Record<string, string> = {
         ...corsHeaders(req),
         "Content-Type": "application/octet-stream", // always opaque; nosniff prevents the client from re-deciding
@@ -1684,6 +1823,15 @@ return Bun.serve({
         "X-Content-Type-Options": "nosniff",
         "Cache-Control": "private, no-store",
       };
+      // HEAD: return the same status and headers as GET, but no body,
+      // per RFC 9110 §9.3.2. This ensures HEAD passes through the same
+      // authorization helper — a cross-owner HEAD is 404 (same as GET),
+      // not a fallback 200. Status/headers are the authoritative
+      // signal; body omission is HTTP-standard for HEAD.
+      if (req.method === "HEAD") {
+        return new Response(null, { status: 200, headers: responseHeaders });
+      }
+      const blob = Bun.file(storage.absolutePath);
       return new Response(blob, { status: 200, headers: responseHeaders });
     }
 
@@ -2129,6 +2277,115 @@ return Bun.serve({
     // legacy master token). Value passes validateAvatarUrl (http/https
     // only, ≤ 2048 chars, no control chars — XSS boundary, see
     // avatar-validate.ts).
+    // ── REST: node DISPLAY attributes (display_name / team / tags) ──
+    // Companion to the avatar route below: hub-side presentation fields that
+    // agent-node does not consume, so they deliberately bypass the RFC-024
+    // config-apply pipeline (no doorbell, no ack, no config_revision bump).
+    //
+    // Unlike avatar, these are multi-field and multi-editor, so they carry
+    // their OWN optimistic lock (`attrs_revision`). A stale base revision is
+    // a 409 with the current value, mirroring update_node_config's contract
+    // so the dashboard can reuse its conflict-resolution UX.
+    //
+    // NOT editable here: `alias` (message-routing key) and `node_name`
+    // (addressing key). Renaming those must go through the rename 2PC at
+    // /api/node-rename/* which cascades sessions + api_tokens + SSE cleanup;
+    // a single-table UPDATE would strand the node (see #146).
+    const nodeAttrsMatch = url.pathname.match(/^\/api\/nodes\/([^/]+)\/attrs$/);
+    if (nodeAttrsMatch && req.method === "PUT") {
+      let attrsBody: any;
+      try {
+        attrsBody = await req.json();
+      } catch {
+        return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 }));
+      }
+      const ref = decodeURIComponent(nodeAttrsMatch[1]);
+      const params: any[] = [ref, ref, ref];
+      let sql = "SELECT node_id, alias, network_id, display_name, team, tags, attrs_revision FROM nodes WHERE (node_id = ?1 OR node_name = ?2 OR alias = ?3)";
+      sql = addNetworkScope(sql, params, restScope);
+      sql += " ORDER BY updated_at DESC LIMIT 1";
+      const node = db.get<any>(sql, ...params);
+      if (!node) return withCors(req, Response.json({ ok: false, error: "node not found" }, { status: 404 }));
+
+      const nodeNetId = node.network_id ?? singleNetworkId(restScope);
+      if (!canRestWriteNetwork(restAuth, nodeNetId, isAdmin)) {
+        return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
+      }
+
+      // Optimistic lock BEFORE any narrowing work, so a losing writer never
+      // has side effects.
+      const currentRev = Number(node.attrs_revision ?? 0);
+      const baseRev = attrsBody?.base_attrs_revision;
+      if (typeof baseRev !== "number" || !Number.isInteger(baseRev) || baseRev < 0) {
+        return withCors(req, Response.json({
+          ok: false, error: "base_attrs_revision required (integer >= 0)",
+        }, { status: 400 }));
+      }
+      if (baseRev !== currentRev) {
+        return withCors(req, Response.json({
+          ok: false,
+          error: "attrs_revision_conflict",
+          current_attrs_revision: currentRev,
+          message: "another editor changed this node's attributes; re-read and retry",
+        }, { status: 409 }));
+      }
+
+      // Scalars reject on wrong type (never coerce); tags drop junk per item.
+      const nextDisplay = "display_name" in attrsBody
+        ? validateScalarAttr(attrsBody.display_name, "display_name")
+        : null;
+      if (nextDisplay && !nextDisplay.ok) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_display_name", reason: nextDisplay.reason }, { status: 400 }));
+      }
+      const nextTeam = "team" in attrsBody ? validateScalarAttr(attrsBody.team, "team") : null;
+      if (nextTeam && !nextTeam.ok) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_team", reason: nextTeam.reason }, { status: 400 }));
+      }
+      const nextTags = "tags" in attrsBody ? narrowTags(attrsBody.tags) : null;
+
+      // Only the supplied fields move; the rest keep their stored value.
+      const sets: string[] = [];
+      const vals: any[] = [];
+      if (nextDisplay) { sets.push(`display_name = ?${vals.length + 1}`); vals.push(nextDisplay.value); }
+      if (nextTeam) { sets.push(`team = ?${vals.length + 1}`); vals.push(nextTeam.value); }
+      if (nextTags) { sets.push(`tags = ?${vals.length + 1}`); vals.push(JSON.stringify(nextTags)); }
+      // A no-op patch still bumps the revision: the caller observed a state
+      // and asserted it, so honouring the CAS keeps client counters in step.
+      sets.push(`attrs_revision = ?${vals.length + 1}`); vals.push(currentRev + 1);
+      sets.push(`updated_at = datetime('now')`);
+      vals.push(node.node_id);
+      // Guard the UPDATE with the same revision so two concurrent writers
+      // that both passed the read above cannot both land.
+      vals.push(currentRev);
+      const res = db.run(
+        `UPDATE nodes SET ${sets.join(", ")} WHERE node_id = ?${vals.length - 1} AND attrs_revision = ?${vals.length}`,
+        vals,
+      );
+      if (!res.changes) {
+        const fresh = db.get<any>("SELECT attrs_revision FROM nodes WHERE node_id = ?1", node.node_id);
+        return withCors(req, Response.json({
+          ok: false,
+          error: "attrs_revision_conflict",
+          current_attrs_revision: Number(fresh?.attrs_revision ?? currentRev),
+          message: "another editor changed this node's attributes; re-read and retry",
+        }, { status: 409 }));
+      }
+      logAudit(restAuth?.userId ?? null, restAuth?.username ?? null, "node_attrs_updated", "node", node.node_id,
+        JSON.stringify({ display_name: nextDisplay?.value ?? undefined, team: nextTeam?.value ?? undefined, tags: nextTags ?? undefined }),
+        undefined, nodeNetId ?? undefined);
+      const after = db.get<any>(
+        "SELECT display_name, team, tags, attrs_revision FROM nodes WHERE node_id = ?1", node.node_id);
+      return withCors(req, Response.json({
+        ok: true,
+        node_id: node.node_id,
+        alias: node.alias,
+        display_name: after?.display_name ?? null,
+        team: after?.team ?? null,
+        tags: parseStoredTags(after?.tags),
+        attrs_revision: Number(after?.attrs_revision ?? currentRev + 1),
+      }));
+    }
+
     const nodeAvatarMatch = url.pathname.match(/^\/api\/nodes\/([^/]+)\/avatar$/);
     if (nodeAvatarMatch && req.method === "PUT") {
       let avatarBody: any;
@@ -2315,7 +2572,8 @@ return Bun.serve({
       let sql = `SELECT node_id, node_name, alias, runtime, model,
                         config_path, channels, server, hostname,
                         network_id, created_at, updated_at,
-                        config_snapshot, lifecycle_state, avatar_url
+                        config_snapshot, lifecycle_state, avatar_url,
+                        display_name, team, tags, attrs_revision
                  FROM nodes WHERE 1=1`;
       const params: any[] = [];
       sql = addNetworkScope(sql, params, restScope);
@@ -2337,7 +2595,16 @@ return Bun.serve({
           catch { /* malformed snapshot — leave role null */ }
         }
         const { config_snapshot, ...rest } = r;
-        return { ...rest, role };
+        // `tags` is stored as JSON text; hand the dashboard a real array so
+        // it can map() without a guard, and normalise legacy/absent values
+        // to [] rather than null. attrs_revision is normalised to a number
+        // so pre-migration rows (NULL) read as 0.
+        return {
+          ...rest,
+          tags: parseStoredTags(r.tags),
+          attrs_revision: Number(r.attrs_revision ?? 0),
+          role,
+        };
       });
       return withCors(req, Response.json({ ok: true, nodes: rows, count: rows.length }));
     }

package/src/tools.ts

@@ -1058,7 +1058,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // ── V2: send_reply (关联 task_id，不触发 think) ──
   server.tool(
     "send_reply",
-    "Send a reply to a task. Linked to task_id via in_reply_to. Does NOT trigger agent processing.",
+    "Send a reply to a Dashboard/UI-originated task (updates task row, emits new_reply SSE — Dashboard reads it). ⚠ NOT for agent-to-agent replies: agent nodes only log new_reply and do not processInbox on it, so the peer will not see the reply in real time. Use send_task for peer-to-peer replies (RFC-030, Vincent 2026-07-28 全网规则). If the target alias resolves to a live agent node, the response includes a `warning` field pointing to send_task.",
     {
       alias: z.string().min(1).max(200).describe("Target session alias"),
       text: z.string().min(1).max(10000).describe("Reply content"),
@@ -1191,10 +1191,26 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // #461 network observer summary — ids + routing only, no reply text.
       pushNetworkObserverEvent(effectiveNetId, { type: "new_reply", task_id: in_reply_to ?? null, message_id: id, from: from_session, to: alias, status: replyStatus });
 
+      // #498 — When the reply target is a live agent node (not Dashboard/UI),
+      // warn the caller that agent peers only log new_reply and do not
+      // processInbox on it. Points at the correct next action (send_task)
+      // so a follow-up turn corrects course rather than "why didn't they
+      // respond" spelunking. Absent field when target is Dashboard/hub/api
+      // (the correct path for commhub_reply) — silence is affirmation.
+      const targetIsAgent = replyTargetNodeId !== null && alias !== "hub" && alias !== "api";
+      const warning = targetIsAgent
+        ? `Target "${alias}" is an agent node. commhub_reply/send_reply does NOT wake agent peers (they only log new_reply, they do not processInbox on it) — the peer will not see this reply in real time. For agent-to-agent replies, use commhub_send_task(alias="${alias}", task="<your reply>") so the peer wakes via new_task SSE and processes it. (RFC-030, Vincent 2026-07-28 全网规则.)`
+        : undefined;
+
       return {
         content: [{
           type: "text" as const,
-          text: JSON.stringify({ ok: true, message_id: id, session_status: session?.status ?? "unknown" }),
+          text: JSON.stringify({
+            ok: true,
+            message_id: id,
+            session_status: session?.status ?? "unknown",
+            ...(warning ? { warning } : {}),
+          }),
         }],
       };
     }