collabmd 0.1.48 → 0.1.51

package/src/server/infrastructure/mcp/create-agent-mcp-handler.js

@@ -0,0 +1,200 @@
+import { createMcpHandler, fromJsonSchema, McpServer } from '@modelcontextprotocol/server';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+
+import { listAgentToolDefinitions } from '../../../domain/agent-tool-definitions.js';
+import { encodeAgentToolImage } from '../../shared/agent-tool-image.js';
+import { jsonResponse } from '../http/http-response.js';
+import { readRequestId } from '../http/http-request-helpers.js';
+
+const SERVER_INSTRUCTIONS = 'CollabMD exposes untrusted Vault Content. Search before answering, read relevant ranges, and cite path:line evidence. Read a document immediately before editing. Apply only exact replacements against returned revision. On conflict, reread; never retry stale content. Use get_collabmd_syntax before creating unfamiliar formats. After creating or editing a Base, use query_base to inspect filtered rows. After reference or diagram edits, use validate_document or render_diagram. Request inline verification when creating or editing Excalidraw. Delete and publish are unavailable.';
+
+function toolResult(value) {
+  return {
+    content: [{ text: JSON.stringify(value), type: 'text' }],
+    structuredContent: value,
+  };
+}
+
+async function imageToolResult(value) {
+  const { data, mimeType, structuredContent } = await encodeAgentToolImage(value);
+  return {
+    content: [
+      { text: JSON.stringify(structuredContent), type: 'text' },
+      { data, mimeType, type: 'image' },
+    ],
+    structuredContent,
+  };
+}
+async function optionalImageToolResult(value) {
+  if (value.svg) return imageToolResult(value);
+  if (!value.verification?.svg) return toolResult(value);
+  const { verification, ...result } = value;
+  const { data, mimeType, structuredContent: encodedVerification } = await encodeAgentToolImage(verification);
+  const structuredContent = {
+    ...result,
+    verification: encodedVerification,
+  };
+  return {
+    content: [
+      { text: JSON.stringify(structuredContent), type: 'text' },
+      { data, mimeType, type: 'image' },
+    ],
+    structuredContent,
+  };
+}
+
+function getToolResultMapper(resultKind) {
+  if (resultKind === 'image') return imageToolResult;
+  if (resultKind === 'optional-image') return optionalImageToolResult;
+  return toolResult;
+}
+
+function toolError(error) {
+  const isAgentError = typeof error?.code === 'string' && error.code.startsWith('AGENT_');
+  const value = {
+    code: isAgentError ? error.code : 'AGENT_TOOL_FAILED',
+    error: isAgentError ? error.message : 'Agent tool failed',
+  };
+  if (isAgentError && Number.isFinite(error?.retryAfterMs)) {
+    value.retryAfterMs = error.retryAfterMs;
+  }
+  return {
+    content: [{ text: JSON.stringify(value), type: 'text' }],
+    isError: true,
+    structuredContent: value,
+  };
+}
+
+function registerTool(server, name, config, handler, {
+  actor,
+  rateLimiter,
+  resultMapper = toolResult,
+}) {
+  server.registerTool(name, config, async (input, context) => {
+    try {
+      rateLimiter(actor.rateLimitKey);
+      return await resultMapper(await handler(input, context));
+    } catch (error) {
+      if (typeof error?.code !== 'string' || !error.code.startsWith('AGENT_')) {
+        console.error(`[mcp] ${name} failed (${actor.requestId}):`, error?.message || 'Unknown error');
+      }
+      return toolError(error);
+    }
+  });
+}
+
+function buildAgentServer({ actor, agentContentService, rateLimiter, version }) {
+  const server = new McpServer(
+    { name: 'collabmd', version },
+    { instructions: SERVER_INSTRUCTIONS },
+  );
+  for (const definition of listAgentToolDefinitions(actor.scopes)) {
+    registerTool(server, definition.name, {
+      annotations: definition.annotations,
+      description: definition.description,
+      inputSchema: fromJsonSchema(definition.inputSchema),
+      outputSchema: fromJsonSchema(definition.outputSchema),
+    }, (input, context) => agentContentService[definition.method](actor, {
+      ...input,
+      signal: context.signal,
+    }), {
+      actor,
+      rateLimiter,
+      resultMapper: getToolResultMapper(definition.resultKind),
+    });
+  }
+  return server;
+}
+
+function readHttpHostname(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return '';
+    return url.hostname.replace(/^\[|\]$/gu, '').toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+function readRequestHostname(req) {
+  return readHttpHostname(`http://${String(req.headers.host || '')}`);
+}
+
+export function createAgentMcpHandler({
+  agentConnectionService,
+  agentContentService,
+  config,
+  rateLimiter,
+}) {
+  const mcpHandler = createMcpHandler(({ authInfo }) => buildAgentServer({
+    actor: authInfo.extra.actor,
+    agentContentService,
+    rateLimiter,
+    version: config.build?.version || '0.1.0',
+  }));
+  const nodeHandler = toNodeHandler(mcpHandler, {
+    onerror: (error) => console.error('[mcp] Transport failed:', error.message),
+  });
+
+  return async function handleAgentMcp(req, res, requestUrl) {
+    if (requestUrl.pathname !== '/mcp') return false;
+    const authRequired = config.auth.strategy !== 'none';
+    const allowedHosts = config.agentAccess.allowedHosts;
+    const hostname = readRequestHostname(req);
+    const hasOrigin = Boolean(req.headers.origin);
+    const originHostname = hasOrigin ? readHttpHostname(String(req.headers.origin)) : '';
+    const browserOriginAllowed = hasOrigin
+      && hostname
+      && originHostname === hostname
+      && allowedHosts.includes(hostname);
+    if (
+      (authRequired && (!hostname || !allowedHosts.includes(hostname)))
+      || (hasOrigin && !browserOriginAllowed)
+    ) {
+      jsonResponse(req, res, 403, { error: 'MCP request origin or host is not allowed' });
+      return true;
+    }
+
+    let actor;
+    let token = '';
+    if (authRequired) {
+      const authorization = String(req.headers.authorization || '');
+      const match = authorization.match(/^Bearer\s+(.+)$/iu);
+      if (!match) {
+        res.setHeader('WWW-Authenticate', 'Bearer scope="vault:read"');
+        jsonResponse(req, res, 401, { error: 'Agent Connection token is required' });
+        return true;
+      }
+      token = match[1];
+      try {
+        actor = await agentConnectionService.authenticateToken(token);
+      } catch (error) {
+        res.setHeader('WWW-Authenticate', 'Bearer scope="vault:read"');
+        jsonResponse(req, res, Number(error?.statusCode) || 401, {
+          code: error?.code || 'AGENT_TOKEN_INVALID',
+          error: error?.message || 'Agent Connection token is invalid',
+        });
+        return true;
+      }
+    } else {
+      actor = {
+        collaborator: null,
+        connectionId: 'anonymous',
+        scopes: ['vault:edit', 'vault:read'],
+      };
+    }
+
+    actor.requestId = readRequestId(req);
+    actor.rateLimitKey = actor.connectionId === 'anonymous'
+      ? `anonymous:${req.socket?.remoteAddress || 'unknown'}`
+      : actor.connectionId;
+    req.auth = {
+      clientId: actor.connectionId,
+      extra: { actor },
+      scopes: actor.scopes,
+      token,
+    };
+    await nodeHandler(req, res);
+    return true;
+  };
+}

package/src/server/infrastructure/persistence/agent-connection-store.js

@@ -0,0 +1,120 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+function parseScopes(value) {
+  try {
+    const scopes = JSON.parse(value || '[]');
+    return Array.isArray(scopes) ? scopes : [];
+  } catch {
+    return [];
+  }
+}
+
+function rowToConnection(row) {
+  if (!row) return null;
+  return {
+    clientKind: row.client_kind,
+    createdAt: row.created_at,
+    expiresAt: row.expires_at,
+    id: row.id,
+    label: row.label,
+    revokedAt: row.revoked_at,
+    scopes: parseScopes(row.scopes_json),
+    subjectEmail: row.subject_email,
+    subjectId: row.subject_id,
+    subjectType: row.subject_type,
+    tokenHash: row.token_hash,
+  };
+}
+
+export class AgentConnectionStore {
+  constructor({ dbPath }) {
+    this.dbPath = dbPath;
+    this.db = null;
+    this.statements = new Map();
+  }
+
+  async initialize() {
+    if (this.db) return;
+    await mkdir(dirname(this.dbPath), { recursive: true });
+    const { DatabaseSync } = await import('node:sqlite');
+    this.db = new DatabaseSync(this.dbPath);
+    this.db.exec('PRAGMA journal_mode = WAL');
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agent_connections (
+        id TEXT PRIMARY KEY,
+        subject_type TEXT NOT NULL,
+        subject_id TEXT NOT NULL,
+        subject_email TEXT NOT NULL DEFAULT '',
+        label TEXT NOT NULL,
+        client_kind TEXT NOT NULL,
+        scopes_json TEXT NOT NULL,
+        token_hash TEXT NOT NULL UNIQUE,
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL,
+        revoked_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS agent_connections_subject_idx
+        ON agent_connections(subject_type, subject_id, created_at DESC);
+    `);
+  }
+
+  prepare(key, sql) {
+    if (!this.statements.has(key)) this.statements.set(key, this.db.prepare(sql));
+    return this.statements.get(key);
+  }
+
+  async close() {
+    this.statements.clear();
+    this.db?.close();
+    this.db = null;
+  }
+
+  async create(connection) {
+    this.prepare(
+      'create',
+      `INSERT INTO agent_connections (
+        id, subject_type, subject_id, subject_email, label, client_kind,
+        scopes_json, token_hash, created_at, expires_at, revoked_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`,
+    ).run(
+      connection.id,
+      connection.subjectType,
+      connection.subjectId,
+      connection.subjectEmail,
+      connection.label,
+      connection.clientKind,
+      JSON.stringify(connection.scopes),
+      connection.tokenHash,
+      connection.createdAt,
+      connection.expiresAt,
+    );
+    return connection;
+  }
+
+  async getByTokenHash(tokenHash) {
+    return rowToConnection(this.prepare(
+      'getByTokenHash',
+      'SELECT * FROM agent_connections WHERE token_hash = ? LIMIT 1',
+    ).get(tokenHash));
+  }
+
+  async listBySubject(subjectType, subjectId) {
+    return this.prepare(
+      'listBySubject',
+      `SELECT * FROM agent_connections
+       WHERE subject_type = ? AND subject_id = ? AND revoked_at IS NULL
+       ORDER BY created_at DESC`,
+    ).all(subjectType, subjectId).map(rowToConnection);
+  }
+
+  async revoke(id, subjectType, subjectId, revokedAt) {
+    const result = this.prepare(
+      'revoke',
+      `UPDATE agent_connections SET revoked_at = ?
+       WHERE id = ? AND subject_type = ? AND subject_id = ? AND revoked_at IS NULL`,
+    ).run(revokedAt, id, subjectType, subjectId);
+    return Number(result.changes) > 0;
+  }
+
+}

package/src/server/infrastructure/persistence/pull-backup-store.js

@@ -1,6 +1,7 @@
 import { copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
+import { ensureCollabMetadataGitExclude } from '../git/local-exclude.js';
 import { sanitizeVaultPath } from './path-utils.js';
 
 const PULL_BACKUP_STORAGE_ROOT = '.collabmd/pull-backups';
@@ -98,32 +99,6 @@ function formatSummary({
   ].join('\n');
 }
 
-async function ensureLocalGitExclude(vaultDir) {
-  const excludePath = resolve(vaultDir, '.git/info/exclude');
-  let existingContent = '';
-
-  try {
-    existingContent = await readFile(excludePath, 'utf8');
-  } catch (error) {
-    if (error?.code !== 'ENOENT') {
-      throw error;
-    }
-  }
-
-  const lines = existingContent
-    .split(/\r?\n/u)
-    .map((line) => line.trim())
-    .filter(Boolean);
-  if (lines.includes('.collabmd') || lines.includes('.collabmd/')) {
-    return;
-  }
-
-  const prefix = existingContent.length > 0 && !existingContent.endsWith('\n')
-    ? '\n'
-    : '';
-  await writeFile(excludePath, `${existingContent}${prefix}.collabmd/\n`, 'utf8');
-}
-
 export class PullBackupStore {
   constructor({ vaultDir }) {
     this.vaultDir = resolve(vaultDir);
@@ -148,7 +123,7 @@ export class PullBackupStore {
     headRef = null,
     targetRef = null,
   } = {}) {
-    await ensureLocalGitExclude(this.vaultDir);
+    await ensureCollabMetadataGitExclude(this.vaultDir);
 
     const backupId = createBackupId(headRef, createdAt);
     const backupDir = this.getBackupPath(backupId);

package/src/server/infrastructure/persistence/sidecar-store.js

@@ -2,9 +2,11 @@ import { dirname, join, resolve } from 'path';
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'fs/promises';
 
 import { resolveVaultFilePath, toVaultRelativePath } from './path-utils.js';
+import { mapWithConcurrency } from '../../shared/async-utils.js';
 
 const COMMENT_STORAGE_ROOT = '.collabmd/comments';
 const YJS_SNAPSHOT_STORAGE_ROOT = '.collabmd/yjs';
+const COMMENT_READ_CONCURRENCY = 8;
 
 function resolveSidecarPath(vaultDir, filePath, storageRoot, extension) {
   const { absolute: absoluteVaultPath } = resolveVaultFilePath(vaultDir, filePath);
@@ -75,7 +77,7 @@ export class SidecarStore {
   async listCommentThreadEntries({ filePaths = null } = {}) {
     const allowedPaths = filePaths ? new Set(filePaths) : null;
     const rootPath = this.getCommentStorageRootPath();
-    const entries = [];
+    const commentFilePaths = [];
 
     const visitDirectory = async (absoluteDirectoryPath, relativeDirectoryPath = '') => {
       let dirEntries;
@@ -108,14 +110,19 @@ export class SidecarStore {
           continue;
         }
 
-        const threads = await this.readCommentThreads(filePath);
-        if (threads.length > 0) {
-          entries.push({ filePath, threads });
-        }
+        commentFilePaths.push(filePath);
       }
     };
 
     await visitDirectory(rootPath);
+    const entries = (await mapWithConcurrency(
+      commentFilePaths,
+      COMMENT_READ_CONCURRENCY,
+      async (filePath) => {
+        const threads = await this.readCommentThreads(filePath);
+        return threads.length > 0 ? { filePath, threads } : null;
+      },
+    )).filter(Boolean);
     return entries.sort((left, right) => left.filePath.localeCompare(right.filePath, undefined, { sensitivity: 'base' }));
   }
 

package/src/server/infrastructure/persistence/vault-file-store.js

@@ -1,5 +1,5 @@
 import { createReadStream } from 'fs';
-import { mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from 'fs/promises';
+import { copyFile, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from 'fs/promises';
 import { basename, dirname, extname, join, relative, resolve } from 'path';
 import sharp from 'sharp';
 
@@ -708,7 +708,11 @@ export class VaultFileStore {
             : null;
 
           if (backupPath) {
-            await rename(operation.targetPath, backupPath);
+            if (operation.kind === 'write') {
+              await copyFile(operation.targetPath, backupPath);
+            } else {
+              await rename(operation.targetPath, backupPath);
+            }
           }
 
           try {
@@ -721,6 +725,9 @@ export class VaultFileStore {
             }
           } catch (error) {
             if (backupPath) {
+              if (operation.kind === 'write') {
+                await rm(operation.targetPath, { force: true });
+              }
               await rename(backupPath, operation.targetPath);
             }
             throw error;
@@ -757,9 +764,8 @@ export class VaultFileStore {
     return this.sidecarStore.readCommentThreads(filePath);
   }
 
-  async readCommentOverview() {
-    const snapshot = await this.scanWorkspaceState();
-    const commentSupportedFilePaths = snapshot.filePaths.filter((filePath) => (
+  async readCommentOverview({ filePaths }) {
+    const commentSupportedFilePaths = filePaths.filter((filePath) => (
       supportsCommentsForFilePath(filePath)
     ));
     const entries = await this.sidecarStore.listCommentThreadEntries({

package/src/server/infrastructure/websocket/attach-collaboration-gateway.js

@@ -24,9 +24,22 @@ function rejectUpgrade(socket, statusCode, statusMessage, {
   socket.destroy();
 }
 
-function extractRoomName(pathname, wsBasePath) {
-  const roomSegment = pathname.slice(wsBasePath.length + 1);
-  return decodeURIComponent(roomSegment || 'default');
+// ponytail: /ws/v/:knownId/:room scopes to a vault; anything else stays a legacy primary room.
+// A primary-vault file literally at v/<vaultId>/... is shadowed by design.
+function extractVaultAndRoom(pathname, wsBasePath, isKnownVaultId) {
+  const rest = pathname.slice(wsBasePath.length + 1);
+  if (rest === 'v' || rest.startsWith('v/')) {
+    const after = rest === 'v' ? '' : rest.slice('v/'.length);
+    const slashIndex = after.indexOf('/');
+    if (slashIndex > 0) {
+      const candidate = after.slice(0, slashIndex);
+      const roomPart = after.slice(slashIndex + 1);
+      if (roomPart && isKnownVaultId?.(candidate)) {
+        return { roomName: decodeURIComponent(roomPart) || 'default', vaultId: candidate };
+      }
+    }
+  }
+  return { roomName: decodeURIComponent(rest || 'default'), vaultId: null };
 }
 
 export function attachCollaborationGateway({
@@ -37,6 +50,7 @@ export function attachCollaborationGateway({
   httpServer,
   maxPayload,
   roomRegistry,
+  vaultRegistry = null,
   wsBasePath,
 }) {
   const websocketServer = new WebSocketServer({
@@ -99,26 +113,38 @@ export function attachCollaborationGateway({
   }) ?? (() => {});
 
   websocketServer.on('connection', (ws, req, requestUrl, user = null) => {
-    const roomName = extractRoomName(requestUrl.pathname, wsBasePath);
-    const room = roomRegistry.getOrCreate(roomName);
-    const session = new ClientSocketSession({
-      onDisconnected: (disconnectedRoomName) => {
-        socketSessions.delete(ws);
-        const remaining = roomRegistry.rooms.get(disconnectedRoomName)?.clients.size ?? 0;
-        console.log(`[ws] "${disconnectedRoomName}" disconnected (${remaining} active client(s))`);
-      },
-      onFailed: () => {
-        socketSessions.delete(ws);
-      },
-      room,
-      roomName,
-      ws,
-    });
-    socketSessions.set(ws, {
-      session,
-      userEmail: normalizeHostedEmail(user?.email),
+    const { roomName, vaultId } = extractVaultAndRoom(requestUrl.pathname, wsBasePath, vaultRegistry?.isKnownVaultId?.bind(vaultRegistry));
+    const registryPromise = vaultId && vaultRegistry
+      ? vaultRegistry.getOrCreateContextAsync(vaultId).then((context) => context.roomRegistry)
+      : Promise.resolve(roomRegistry);
+    registryPromise.then((targetRegistry) => {
+      const room = targetRegistry.getOrCreate(roomName);
+      const session = new ClientSocketSession({
+        onDisconnected: (disconnectedRoomName) => {
+          socketSessions.delete(ws);
+          const remaining = targetRegistry.rooms.get(disconnectedRoomName)?.clients.size ?? 0;
+          console.log(`[ws] "${disconnectedRoomName}" disconnected (${remaining} active client(s))`);
+        },
+        onFailed: () => {
+          socketSessions.delete(ws);
+        },
+        room,
+        roomName,
+        ws,
+      });
+      socketSessions.set(ws, {
+        session,
+        userEmail: normalizeHostedEmail(user?.email),
+      });
+      void session.initialize();
+    }).catch((error) => {
+      console.error(`[ws] Failed to open room "${roomName}":`, error.message);
+      try {
+        ws.close(1011, 'Vault unavailable');
+      } catch {
+        try { ws.terminate(); } catch { /* ignore */ }
+      }
     });
-    void session.initialize();
   });
 
   httpServer.on('upgrade', (req, socket, head) => {

package/src/server/shared/agent-tool-image.js

@@ -0,0 +1,22 @@
+import sharp from 'sharp';
+
+export async function encodeAgentToolImage(value) {
+  const { format, svg } = value;
+  const metadata = { ...value };
+  delete metadata.format;
+  delete metadata.scene;
+  delete metadata.svg;
+  const mimeType = format === 'svg' ? 'image/svg+xml' : 'image/png';
+  const image = format === 'svg'
+    ? Buffer.from(svg)
+    : await sharp(Buffer.from(svg)).png().toBuffer();
+  return {
+    data: image.toString('base64'),
+    mimeType,
+    structuredContent: {
+      ...metadata,
+      format,
+      mimeType,
+    },
+  };
+}

package/src/server/shared/agent-tool-rate-limiter.js

@@ -0,0 +1,27 @@
+export function createAgentToolRateLimiter(requestsPerMinute) {
+  const limit = Math.max(1, Number.parseInt(requestsPerMinute, 10) || 120);
+  const windows = new Map();
+  let nextSweepAt = 0;
+  return (key) => {
+    const timestamp = Date.now();
+    if (timestamp >= nextSweepAt) {
+      for (const [windowKey, window] of windows) {
+        if (timestamp >= window.resetAt) windows.delete(windowKey);
+      }
+      nextSweepAt = timestamp + 60_000;
+    }
+    let window = windows.get(key);
+    if (!window || timestamp >= window.resetAt) {
+      window = { count: 0, resetAt: timestamp + 60_000 };
+      windows.set(key, window);
+    }
+    if (window.count >= limit) {
+      const error = new Error('Agent tool request limit reached; retry after the current window');
+      error.code = 'AGENT_RATE_LIMITED';
+      error.retryAfterMs = Math.max(1, window.resetAt - timestamp);
+      error.statusCode = 429;
+      throw error;
+    }
+    window.count += 1;
+  };
+}