@sleep2agi/commhub-server 0.5.0-preview.2 → 0.5.0-preview.21

package/README.md

@@ -0,0 +1,110 @@
+# @sleep2agi/commhub-server
+
+AI Agent 通信中枢 — MCP Server + SSE Push + REST API。
+
+## 快速启动
+
+```bash
+# 需要 Bun
+bunx @sleep2agi/commhub-server
+
+# 或指定端口 + auth
+PORT=9200 COMMHUB_AUTH_TOKEN=your-secret bunx @sleep2agi/commhub-server
+```
+
+启动后:
+- MCP: `http://0.0.0.0:9200/mcp` (Claude Code / Codex 连接)
+- SSE: `http://0.0.0.0:9200/events/:alias` (Agent 实时推送)
+- REST: `http://0.0.0.0:9200/api/*` (Dashboard / 监控)
+- Health: `http://0.0.0.0:9200/health`
+
+## MCP 工具 (17 个)
+
+### Agent 端 (从 Agent 调用)
+| 工具 | 说明 |
+|------|------|
+| `report_status` | 心跳 + 状态更新 (idle/working/blocked/error/offline) |
+| `report_completion` | 任务完成汇报 |
+| `get_inbox` | 拉取待办任务 |
+| `ack_inbox` | 确认收到任务 |
+
+### Hub 端 (从指挥室 / Dashboard 调用)
+| 工具 | 说明 |
+|------|------|
+| `send_task` | 下发任务 (+ 可选 ttl_seconds) |
+| `send_message` | 发消息 (不触发 Agent 处理) |
+| `send_reply` | 回复任务 (replied/failed/cancelled + in_reply_to) |
+| `send_ack` | 确认任务 (不入 inbox) |
+| `retry_task` | 重试失败/过期/取消的任务 |
+| `cancel_task` | 取消待处理任务 |
+| `reassign_task` | 转移任务到另一个 Agent |
+| `get_task` | 查询任务详情 |
+| `get_all_status` | 全局状态面板 |
+| `get_session_status` | 单 session 详情 |
+| `broadcast` | 群发消息 |
+
+## REST API
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/health` | GET | 健康检查 (无需 auth) |
+| `/api/status` | GET | 所有 session |
+| `/api/tasks` | GET | 任务列表 (支持 status/from_name/to_name/task_id/limit 过滤) |
+| `/api/nodes` | GET | 节点持久化信息 |
+| `/api/task_events` | GET | 任务审计日志 |
+| `/api/messages` | GET | 消息列表 |
+| `/api/completions` | GET | 完成记录 |
+| `/mcp` | POST | MCP Streamable HTTP |
+
+## 数据库 (6 表)
+
+SQLite WAL 模式, 自动创建在 `~/.commhub/commhub.db`
+
+| 表 | 说明 |
+|---|------|
+| `sessions` | 运行时 session (21 列, 含 node_id/session_id/channels) |
+| `inbox` | 消息队列 (13 列, 含 in_reply_to/scope) |
+| `tasks` | 任务生命周期 (17 列, 完整状态机) |
+| `nodes` | 持久化节点身份 (11 列, 独立于 session) |
+| `completions` | 完成记录 (7 列) |
+| `task_events` | 审计日志 (7 列, 每次状态变化记录) |
+
+任务状态机:
+```
+created → delivered → acked → running → replied
+                                      → failed → retry → delivered
+                                      → cancelled
+delivered → expired (5min patrol)
+delivered/acked/running → reassign → delivered (新agent)
+```
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `PORT` | 9200 | 监听端口 |
+| `HOST` | 0.0.0.0 | 监听地址 |
+| `COMMHUB_AUTH_TOKEN` | (无) | Bearer token 鉴权 |
+| `COMMHUB_DB` | ~/.commhub/commhub.db | 数据库路径 |
+
+## 鉴权
+
+两种认证方式:
+1. **V3 用户系统** (推荐): `POST /api/auth/register` → 获取 `atok_xxx` token
+2. **全局 token** (传统): `COMMHUB_AUTH_TOKEN` 环境变量
+
+Header: `Authorization: Bearer <token>` 或 Query: `?token=<token>`
+
+## V3 功能
+
+- **用户系统**: 注册/登录/Token 认证
+- **多网络**: 每个用户可创建多个独立网络
+- **网络隔离**: 不同网络的数据完全隔离
+- **试用授权**: 14 天免费试用, 到期需授权码
+- **审计日志**: 所有操作记录
+- **限流**: 注册 30/min, 登录 10/min (per IP)
+- `/health` 不需要 auth
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.5.0-preview.2",
+  "version": "0.5.0-preview.21",
   "description": "CommHub MCP Server — AI Agent communication hub with SSE push, MCP protocol, and REST API",
   "type": "module",
   "main": "src/index.ts",

package/src/auth.ts

@@ -0,0 +1,164 @@
+/**
+ * V3 Auth module — user registration, login, token management
+ */
+import { db, generateId, hashPassword, hashToken, generateToken, uuidv4 } from "./db.js";
+
+export interface AuthUser {
+  user_id: string;
+  username: string;
+  display_name: string | null;
+  email: string | null;
+  role: string;
+}
+
+export interface AuthResult {
+  ok: boolean;
+  error?: string;
+  user?: AuthUser;
+  token?: string;
+}
+
+export function register(username: string, password: string, email?: string, displayName?: string): AuthResult {
+  if (!username || username.length < 2) return { ok: false, error: "username must be at least 2 characters" };
+  if (!password || password.length < 6) return { ok: false, error: "password must be at least 6 characters" };
+  if (!/^[a-zA-Z0-9_\-\u4e00-\u9fff]+$/.test(username)) return { ok: false, error: "username contains invalid characters" };
+
+  const existing = db.query<any, [string]>("SELECT user_id FROM users WHERE username = ?1").get(username);
+  if (existing) return { ok: false, error: "username already taken" };
+
+  const userId = generateId("u");
+  const pwHash = hashPassword(password);
+
+  db.run(
+    "INSERT INTO users (user_id, username, password_hash, email, display_name) VALUES (?1, ?2, ?3, ?4, ?5)",
+    [userId, username, pwHash, email || null, displayName || username]
+  );
+
+  // Auto-create default network
+  const networkId = generateId("net");
+  db.run(
+    "INSERT INTO networks (network_id, network_name, owner_id, description) VALUES (?1, ?2, ?3, ?4)",
+    [networkId, "default", userId, "Auto-created default network"]
+  );
+
+  // Auto-create API token
+  const token = generateToken();
+  const tokenId = generateId("tok");
+  db.run(
+    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+    [tokenId, hashToken(token), userId, networkId, "default", "full"]
+  );
+
+  return {
+    ok: true,
+    user: { user_id: userId, username, display_name: displayName || username, email: email || null, role: "user" },
+    token,
+  };
+}
+
+export function login(username: string, password: string): AuthResult {
+  const user = db.query<any, [string]>(
+    "SELECT user_id, username, password_hash, display_name, email, role FROM users WHERE username = ?1"
+  ).get(username);
+
+  if (!user) return { ok: false, error: "invalid username or password" };
+  if (user.password_hash !== hashPassword(password)) return { ok: false, error: "invalid username or password" };
+
+  // Find or create token
+  let tokenRow = db.query<any, [string]>(
+    "SELECT token_id FROM api_tokens WHERE user_id = ?1 ORDER BY created_at DESC LIMIT 1"
+  ).get(user.user_id);
+
+  let token: string;
+  if (tokenRow) {
+    // Generate new token (rotate)
+    token = generateToken();
+    db.run("UPDATE api_tokens SET token_hash = ?1, last_used_at = datetime('now') WHERE token_id = ?2",
+      [hashToken(token), tokenRow.token_id]);
+  } else {
+    token = generateToken();
+    const tokenId = generateId("tok");
+    const networkId = db.query<any, [string]>(
+      "SELECT network_id FROM networks WHERE owner_id = ?1 LIMIT 1"
+    ).get(user.user_id)?.network_id;
+    db.run(
+      "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name) VALUES (?1, ?2, ?3, ?4, ?5)",
+      [tokenId, hashToken(token), user.user_id, networkId || null, "login"]
+    );
+  }
+
+  return {
+    ok: true,
+    user: { user_id: user.user_id, username: user.username, display_name: user.display_name, email: user.email, role: user.role },
+    token,
+  };
+}
+
+export function resolveToken(token: string): { user: AuthUser; networkId: string | null } | null {
+  const tHash = hashToken(token);
+  const row = db.query<any, [string]>(
+    `SELECT t.user_id, t.network_id, t.scope, u.username, u.display_name, u.email, u.role
+     FROM api_tokens t JOIN users u ON t.user_id = u.user_id
+     WHERE t.token_hash = ?1 AND (t.expires_at IS NULL OR t.expires_at > datetime('now'))`
+  ).get(tHash);
+
+  if (!row) return null;
+
+  // Update last_used
+  db.run("UPDATE api_tokens SET last_used_at = datetime('now') WHERE token_hash = ?1", [tHash]);
+
+  return {
+    user: { user_id: row.user_id, username: row.username, display_name: row.display_name, email: row.email, role: row.role },
+    networkId: row.network_id,
+  };
+}
+
+export function getUserNetworks(userId: string) {
+  return db.query<any, [string]>(
+    "SELECT * FROM networks WHERE owner_id = ?1 ORDER BY created_at"
+  ).all(userId);
+}
+
+export function createNetwork(userId: string, name: string, description?: string) {
+  const existing = db.query<any, [string, string]>(
+    "SELECT network_id FROM networks WHERE owner_id = ?1 AND network_name = ?2"
+  ).get(userId, name);
+  if (existing) return { ok: false, error: "network name already exists" };
+
+  const networkId = generateId("net");
+  db.run(
+    "INSERT INTO networks (network_id, network_name, owner_id, description) VALUES (?1, ?2, ?3, ?4)",
+    [networkId, name, userId, description || null]
+  );
+  return { ok: true, network_id: networkId, network_name: name };
+}
+
+export function listTokens(userId: string) {
+  return db.query<any, [string]>(
+    "SELECT token_id, name, scope, network_id, last_used_at, created_at FROM api_tokens WHERE user_id = ?1 ORDER BY created_at DESC"
+  ).all(userId);
+}
+
+export function createToken(userId: string, name: string, networkId?: string): { ok: boolean; token?: string; token_id?: string; error?: string } {
+  const token = generateToken();
+  const tokenId = generateId("tok");
+  db.run(
+    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+    [tokenId, hashToken(token), userId, networkId || null, name, "full"]
+  );
+  return { ok: true, token, token_id: tokenId };
+}
+
+export function revokeToken(userId: string, tokenId: string): { ok: boolean; error?: string } {
+  const result = db.run("DELETE FROM api_tokens WHERE token_id = ?1 AND user_id = ?2", [tokenId, userId]);
+  return result.changes > 0 ? { ok: true } : { ok: false, error: "token not found" };
+}
+
+export function changePassword(userId: string, oldPassword: string, newPassword: string): { ok: boolean; error?: string } {
+  if (!newPassword || newPassword.length < 6) return { ok: false, error: "new password must be at least 6 characters" };
+  const user = db.query<any, [string]>("SELECT password_hash FROM users WHERE user_id = ?1").get(userId);
+  if (!user) return { ok: false, error: "user not found" };
+  if (user.password_hash !== hashPassword(oldPassword)) return { ok: false, error: "incorrect current password" };
+  db.run("UPDATE users SET password_hash = ?1, updated_at = datetime('now') WHERE user_id = ?2", [hashPassword(newPassword), userId]);
+  return { ok: true };
+}

package/src/db-adapter.ts

@@ -0,0 +1,72 @@
+/**
+ * Database Adapter Interface — async-first, supports SQLite and PostgreSQL
+ *
+ * SQLite adapter: wraps bun:sqlite sync calls in Promise (zero overhead)
+ * PostgreSQL adapter: uses bun:sql native async
+ *
+ * All callers use await — sync SQLite just resolves immediately.
+ */
+
+export interface QueryResult {
+  changes: number;
+}
+
+export interface DbAdapter {
+  /** Execute a write query (INSERT/UPDATE/DELETE) */
+  run(sql: string, params?: any[]): QueryResult;
+
+  /** Query a single row */
+  get<T = any>(sql: string, ...params: any[]): T | null;
+
+  /** Query multiple rows */
+  all<T = any>(sql: string, ...params: any[]): T[];
+
+  /** Execute raw SQL (DDL) */
+  exec(sql: string): void;
+
+  /** Run a function inside a transaction */
+  transaction<T>(fn: () => T): T;
+
+  /** Close connection */
+  close(): void;
+
+  /** Dialect identifier */
+  readonly dialect: 'sqlite' | 'postgres';
+}
+
+/**
+ * Phase 1 strategy:
+ *
+ * Current code is sync (bun:sqlite). We keep it sync for now.
+ * All DB access goes through the adapter interface above.
+ *
+ * When we add PostgreSQL (Phase 2), the adapter interface
+ * will change to async. At that point we'll update callers
+ * in a single pass. The unified call sites from Phase 1
+ * make that pass mechanical rather than archaeological.
+ *
+ * Why not async-first now?
+ * - bun:sqlite is sync, wrapping in Promise adds noise
+ * - All MCP tool handlers are already async, so the future
+ *   migration is: db.run() → await db.run(), straightforward
+ * - 750+ lines of tools.ts would need gratuitous await for zero benefit today
+ *
+ * The contract: every DB call goes through adapter methods,
+ * never through raw db.query() or db.run() on the bun:sqlite object.
+ * This is what makes Phase 2 feasible.
+ */
+
+/** SQL helpers for cross-dialect compatibility */
+export function sqlNow(dialect: 'sqlite' | 'postgres'): string {
+  return dialect === 'postgres' ? 'NOW()' : "datetime('now')";
+}
+
+export function sqlAddSeconds(dialect: 'sqlite' | 'postgres', seconds: number | string): string {
+  return dialect === 'postgres'
+    ? `NOW() + INTERVAL '${seconds} seconds'`
+    : `datetime('now', '+${seconds} seconds')`;
+}
+
+export function sqlPlaceholder(dialect: 'sqlite' | 'postgres', index: number): string {
+  return dialect === 'postgres' ? `$${index}` : `?${index}`;
+}

package/src/db.ts

@@ -135,7 +135,162 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_nodes_alias ON nodes(alias);
 `);
 
+// task_events table (V2 Sprint 2) — audit log for task state changes
+db.exec(`
+  CREATE TABLE IF NOT EXISTS task_events (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    task_id       TEXT NOT NULL,
+    from_status   TEXT,
+    to_status     TEXT NOT NULL,
+    actor         TEXT NOT NULL DEFAULT 'system',
+    detail        TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_task_events_task_time ON task_events(task_id, created_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_task_events_created ON task_events(created_at);
+`);
+
+// ── V3: users table ──
+db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    user_id       TEXT PRIMARY KEY,
+    username      TEXT UNIQUE NOT NULL,
+    password_hash TEXT NOT NULL,
+    email         TEXT,
+    display_name  TEXT,
+    role          TEXT DEFAULT 'user',
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
+`);
+
+// ── V3: networks table ──
+db.exec(`
+  CREATE TABLE IF NOT EXISTS networks (
+    network_id    TEXT PRIMARY KEY,
+    network_name  TEXT NOT NULL,
+    owner_id      TEXT NOT NULL,
+    description   TEXT,
+    settings      TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(owner_id, network_name)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_networks_owner ON networks(owner_id);
+`);
+
+// ── V3: api_tokens table ──
+db.exec(`
+  CREATE TABLE IF NOT EXISTS api_tokens (
+    token_id      TEXT PRIMARY KEY,
+    token_hash    TEXT NOT NULL,
+    user_id       TEXT NOT NULL,
+    network_id    TEXT,
+    name          TEXT NOT NULL DEFAULT 'default',
+    scope         TEXT DEFAULT 'full',
+    expires_at    TEXT,
+    last_used_at  TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_tokens_hash ON api_tokens(token_hash);
+  CREATE INDEX IF NOT EXISTS idx_tokens_user ON api_tokens(user_id);
+`);
+
+// ── V3: audit_log table ──
+db.exec(`
+  CREATE TABLE IF NOT EXISTS audit_log (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id       TEXT,
+    username      TEXT,
+    action        TEXT NOT NULL,
+    target_type   TEXT,
+    target_id     TEXT,
+    detail        TEXT,
+    ip            TEXT,
+    network_id    TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_audit_created ON audit_log(created_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_audit_user ON audit_log(user_id);
+  CREATE INDEX IF NOT EXISTS idx_audit_network ON audit_log(network_id);
+`);
+
+// ── V3: licenses table ──
+db.exec(`
+  CREATE TABLE IF NOT EXISTS licenses (
+    id            TEXT PRIMARY KEY,
+    license_key   TEXT UNIQUE NOT NULL,
+    type          TEXT DEFAULT 'trial',
+    max_agents    INTEGER DEFAULT 5,
+    max_networks  INTEGER DEFAULT 3,
+    max_tasks_day INTEGER DEFAULT 500,
+    activated_at  TEXT,
+    expires_at    TEXT,
+    owner_id      TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+`);
+
+// Auto-create trial license on first run
+const existingLicense = db.query<any, []>("SELECT id FROM licenses LIMIT 1").get();
+if (!existingLicense) {
+  const trialId = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+  db.run(
+    "INSERT INTO licenses (id, license_key, type, expires_at) VALUES (?1, ?2, 'trial', datetime('now', '+14 days'))",
+    [`lic_${trialId}`, `trial-${trialId}`]
+  );
+  console.log("[commhub] 🎉 14-day free trial started!");
+}
+
+// ── V3: add network_id to existing tables ──
+for (const table of ["sessions", "nodes", "tasks", "inbox", "task_events"]) {
+  try { db.exec(`ALTER TABLE ${table} ADD COLUMN network_id TEXT`); } catch {}
+}
+try { db.exec("CREATE INDEX IF NOT EXISTS idx_sessions_network ON sessions(network_id)"); } catch {}
+try { db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_network ON tasks(network_id)"); } catch {}
+try { db.exec("CREATE INDEX IF NOT EXISTS idx_nodes_network ON nodes(network_id)"); } catch {}
+
 // Helpers
 export function uuidv4(): string {
   return crypto.randomUUID();
 }
+
+export function generateId(prefix: string): string {
+  return `${prefix}_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`;
+}
+
+export function hashPassword(password: string): string {
+  return new Bun.CryptoHasher("sha256").update(`anet:${password}`).digest("hex");
+}
+
+export function hashToken(token: string): string {
+  return new Bun.CryptoHasher("sha256").update(token).digest("hex");
+}
+
+export function generateToken(): string {
+  return `atok_${crypto.randomUUID().replace(/-/g, "")}`;
+}
+
+export function logAudit(userId: string | null, username: string | null, action: string, targetType?: string, targetId?: string, detail?: string, ip?: string, networkId?: string) {
+  try {
+    db.run(
+      "INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, ip, network_id) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+      [userId, username, action, targetType ?? null, targetId ?? null, detail ?? null, ip ?? null, networkId ?? null]
+    );
+  } catch {}
+}
+
+export function logTaskEvent(taskId: string, fromStatus: string | null, toStatus: string, actor: string, detail?: string) {
+  try {
+    db.run(
+      "INSERT INTO task_events (task_id, from_status, to_status, actor, detail) VALUES (?1, ?2, ?3, ?4, ?5)",
+      [taskId, fromStatus, toStatus, actor, detail ?? null]
+    );
+  } catch {}
+}