@sleep2agi/commhub-server 0.9.0-preview.150 → 0.9.0-preview.151

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.150",
+  "version": "0.9.0-preview.151",
   "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/network-rules-http.test.ts

@@ -0,0 +1,117 @@
+// #993 first slice — network-scoped rules: GET / PUT /api/networks/:id/rules
+//
+// The contract this fixes:
+//   * any member may READ (the rules are what nodes obey);
+//   * only owner/admin may WRITE, and only with a matching `expected_revision`
+//     (blind writes would let two people overwrite the document every node inherits);
+//   * node tokens cannot write (user_token_required), and non-members cannot read;
+//   * reads before any write report revision 0 with empty content, so a client can
+//     create with `expected_revision: 0` and no special "create" path;
+//   * size is capped in UTF-8 bytes.
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import "./require-explicit-test-db.js";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+
+let BASE = "";
+let server: any = null;
+let adminToken = "";
+let memberToken = "";
+let netId = "";
+let nodeToken = "";
+
+async function send(token: string, method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const pw = "NetworkRulesPw123Aa!";
+  const a = register(`nr_admin_${suffix}`, pw, undefined, "admin");
+  if (!a.ok) throw new Error("admin register failed");
+  adminToken = a.token!;
+  netId = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [a.user!.user_id]);
+
+  // The server must be listening before any HTTP call below.
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
+
+  const m = await send(adminToken, "POST", "/api/admin/users", { username: `nr_member_${suffix}`, password: pw, network_id: netId, role: "member" });
+  expect(m.status).toBe(200);
+  const login = await send("", "POST", "/api/auth/login", { username: `nr_member_${suffix}`, password: pw });
+  expect(login.status).toBe(200);
+  memberToken = login.body.token;
+
+  const { createNetworkTokenForNode } = await import("./auth.js");
+  const nt = createNetworkTokenForNode(a.user!.user_id, netId, "rules-node");
+  expect(nt.ok).toBe(true);
+  nodeToken = nt.token!;
+}, 30_000);
+
+afterAll(() => { try { server?.stop?.(true); } catch {} });
+
+describe("#993 — network rules storage + CAS write", () => {
+  test("a member reads an empty document as revision 0", async () => {
+    const r = await send(memberToken, "GET", `/api/networks/${netId}/rules`);
+    expect(r.status).toBe(200);
+    expect(r.body.rules).toMatchObject({ network_id: netId, content: "", revision: 0, updated_at: null, updated_by: null });
+  });
+
+  test("a plain member cannot write", async () => {
+    const r = await send(memberToken, "PUT", `/api/networks/${netId}/rules`, { content: "nope", expected_revision: 0 });
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("owner/admin required");
+  });
+
+  test("admin writes with expected_revision 0 and reads it back", async () => {
+    const w = await send(adminToken, "PUT", `/api/networks/${netId}/rules`, {
+      content: "# Team rules\n\n- be precise\n", expected_revision: 0,
+    });
+    expect(w.status).toBe(200);
+    expect(w.body.rules.revision).toBe(1);
+    expect(w.body.rules.updated_by.username).toBeTruthy();
+    const r = await send(memberToken, "GET", `/api/networks/${netId}/rules`);
+    expect(r.body.rules.content).toContain("be precise");
+    expect(r.body.rules.revision).toBe(1);
+  });
+
+  test("a stale expected_revision is a 409, and nothing is overwritten", async () => {
+    const w = await send(adminToken, "PUT", `/api/networks/${netId}/rules`, { content: "clobber", expected_revision: 0 });
+    expect(w.status).toBe(409);
+    expect(w.body.error).toBe("rules_revision_conflict");
+    const r = await send(adminToken, "GET", `/api/networks/${netId}/rules`);
+    expect(r.body.rules.content).toContain("be precise");
+    expect(r.body.rules.revision).toBe(1);
+  });
+
+  test("a node token cannot write (user_token_required)", async () => {
+    const r = await send(nodeToken, "PUT", `/api/networks/${netId}/rules`, { content: "x", expected_revision: 1 });
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("user_token_required");
+  });
+
+  test("oversized content is refused (bytes, not UTF-16 units)", async () => {
+    const r = await send(adminToken, "PUT", `/api/networks/${netId}/rules`, { content: "a".repeat(200 * 1024 + 1), expected_revision: 1 });
+    expect(r.status).toBe(413);
+    expect(r.body.error).toBe("rules_too_large");
+  });
+
+  test("a non-member cannot read", async () => {
+    const other = register(`nr_other_${Date.now()}`, "OtherPw123Aa!", undefined, "other");
+    expect(other.ok).toBe(true);
+    const r = await send(other.token!, "GET", `/api/networks/${netId}/rules`);
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("not_a_member");
+  });
+});

package/src/network-rules.ts

@@ -0,0 +1,119 @@
+// #993 — network-scoped rules text.
+//
+// First slice: storage + a read/write API with a compare-and-swap revision and an
+// audit entry. Inheritance (Hub → Daemon → node) is NOT implemented here: it needs
+// a precedence and conflict story of its own, and shipping the storage first is
+// what lets that be reviewed against real content.
+//
+// Deliberate choices:
+//   * one row per network, text is the whole document (no chunking) — a team rule
+//     file is a few kilobytes, and partial reads would make "which revision did I
+//     read" ambiguous;
+//   * `revision` starts at 1 for the first write; reads before any write report
+//     revision 0 and empty content, so a client can PUT with expected_revision 0
+//     without a special "create" path;
+//   * the size cap is measured in UTF-8 bytes, not UTF-16 units, because the
+//     content is a file the node will write to disk.
+import type { DbAdapter } from "./db-adapter.js";
+
+/** 200 KiB. A team rule file is small; anything near this is a mistake. */
+export const NETWORK_RULES_MAX_BYTES = 200 * 1024;
+
+export type NetworkRules = {
+  network_id: string;
+  content: string;
+  revision: number;
+  updated_at: string | null;
+  updated_by: { user_id: string; username: string | null } | null;
+};
+
+type Row = { content: string; revision: number; updated_at: string; updated_by_json: string | null };
+
+export function ensureNetworkRules(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS network_rules (
+      network_id      TEXT NOT NULL PRIMARY KEY,
+      content         TEXT NOT NULL,
+      revision        INTEGER NOT NULL,
+      updated_at      TEXT NOT NULL,
+      updated_by_json TEXT
+    );
+  `);
+}
+
+let ensured = false;
+/** Idempotent: the table is created on first use, not on every request. */
+export function ensureNetworkRulesOnce(database: DbAdapter): void {
+  if (ensured) return;
+  ensureNetworkRules(database);
+  ensured = true;
+}
+
+function current(database: DbAdapter, networkId: string): Row | null {
+  return database.get<Row>(
+    "SELECT content, revision, updated_at, updated_by_json FROM network_rules WHERE network_id = ?1",
+    networkId,
+  ) ?? null;
+}
+
+export function readNetworkRules(database: DbAdapter, networkId: string): NetworkRules {
+  const row = current(database, networkId);
+  if (!row) return { network_id: networkId, content: "", revision: 0, updated_at: null, updated_by: null };
+  let updatedBy: NetworkRules["updated_by"] = null;
+  try {
+    const parsed = JSON.parse(row.updated_by_json ?? "null");
+    if (parsed && typeof parsed === "object" && typeof parsed.user_id === "string") {
+      updatedBy = { user_id: parsed.user_id, username: typeof parsed.username === "string" ? parsed.username : null };
+    }
+  } catch { /* a corrupt actor blob must not make the rules unreadable */ }
+  return {
+    network_id: networkId,
+    content: row.content,
+    revision: Number(row.revision) || 0,
+    updated_at: row.updated_at,
+    updated_by: updatedBy,
+  };
+}
+
+export type WriteResult =
+  | { ok: true; rules: NetworkRules }
+  | { ok: false; status: number; error: "invalid_rules_content" | "rules_too_large" | "rules_revision_conflict" };
+
+/**
+ * Compare-and-swap write. `expectedRevision` is required: a blind PUT would let two
+ * clients overwrite each other, and this is the same document every node in the
+ * network would inherit.
+ */
+export function writeNetworkRules(
+  database: DbAdapter,
+  networkId: string,
+  content: unknown,
+  expectedRevision: unknown,
+  actor: { user_id: string; username: string | null },
+  now = new Date().toISOString(),
+): WriteResult {
+  if (typeof content !== "string") return { ok: false, status: 400, error: "invalid_rules_content" };
+  if (typeof expectedRevision !== "number" || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+    return { ok: false, status: 400, error: "invalid_rules_content" };
+  }
+  if (Buffer.byteLength(content, "utf8") > NETWORK_RULES_MAX_BYTES) {
+    return { ok: false, status: 413, error: "rules_too_large" };
+  }
+  const row = current(database, networkId);
+  const revision = row ? Number(row.revision) || 0 : 0;
+  if (revision !== expectedRevision) return { ok: false, status: 409, error: "rules_revision_conflict" };
+  const next = revision + 1;
+  const actorJson = JSON.stringify({ user_id: actor.user_id, username: actor.username });
+  if (row) {
+    database.run(
+      "UPDATE network_rules SET content = ?1, revision = ?2, updated_at = ?3, updated_by_json = ?4 WHERE network_id = ?5",
+      [content, next, now, actorJson, networkId],
+    );
+  } else {
+    database.run(
+      "INSERT INTO network_rules (network_id, content, revision, updated_at, updated_by_json) VALUES (?1, ?2, ?3, ?4, ?5)",
+      [networkId, content, next, now, actorJson],
+    );
+  }
+  return { ok: true, rules: readNetworkRules(database, networkId) };
+}

package/src/server.ts

@@ -24,6 +24,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit, syncScheduledRunForTask } from "./db.js";
+import { ensureNetworkRulesOnce, readNetworkRules, writeNetworkRules } from "./network-rules.js";
 import { recentNodeIdentityConflicts } from "./node-identity-conflict.js";
 import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX, closeUserStreamsInNetwork, getUserPresence, onUserPresenceChange, pushUserEventToNetwork } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
@@ -1889,6 +1890,46 @@ return Bun.serve({
 
     // ── Agent 分组(RFC-038 §8):owner/admin/Hub 管理员管理;组授权动态生效 ──
     // GET/POST /api/networks/:id/agent-groups · PATCH/DELETE …/:gid · PUT …/:gid/members {node_ids}
+    // #993 — network-scoped rules text (first slice: storage + CAS write + audit).
+    // Inheritance (Hub → Daemon → node) is deliberately NOT here: it needs its own
+    // precedence/conflict decision, and shipping storage first keeps that reviewable.
+    const networkRulesMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/rules$/);
+    if (networkRulesMatch) {
+      const token = requestToken(req, { allowQueryToken: false });
+      const resolved = token ? resolveToken(token) : null;
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      const netId = decodeURIComponent(networkRulesMatch[1]);
+      const hubAdmin = resolved.user.role === "admin";
+      const role = getUserNetworkRole(resolved.user.user_id, netId);
+      ensureNetworkRulesOnce(db);
+      if (req.method === "GET") {
+        // Reading is for anyone in the network: the rules are what the nodes obey.
+        if (!hubAdmin && !role) return withCors(req, Response.json({ ok: false, error: "not_a_member" }, { status: 403 }));
+        return withCors(req, Response.json({ ok: true, rules: readNetworkRules(db, netId) }));
+      }
+      if (req.method === "PUT") {
+        // Writing changes what every node in the network would inherit.
+        if (resolved.networkId) return withCors(req, Response.json({ ok: false, error: "user_token_required" }, { status: 403 }));
+        if (!hubAdmin && role !== "owner" && role !== "admin") {
+          return withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
+        }
+        let body: any = null;
+        try { body = await req.json(); } catch { body = null; }
+        if (!body || typeof body !== "object" || Array.isArray(body)) {
+          return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 }));
+        }
+        const result = writeNetworkRules(db, netId, body.content, body.expected_revision, {
+          user_id: resolved.user.user_id,
+          username: resolved.user.username ?? null,
+        });
+        if (!result.ok) return withCors(req, Response.json({ ok: false, error: result.error }, { status: result.status }));
+        logAudit(resolved.user.user_id, resolved.user.username ?? null, "network_rules_updated", "network_rules", netId,
+          JSON.stringify({ revision: result.rules.revision, bytes: Buffer.byteLength(result.rules.content, "utf8") }), undefined, netId);
+        return withCors(req, Response.json({ ok: true, rules: result.rules }));
+      }
+      return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+    }
+
     const groupsMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/agent-groups(?:\/([^/]+)(\/members)?)?$/);
     if (groupsMatch) {
       const token = requestToken(req, { allowQueryToken: false });