studiograph 1.3.46 → 1.3.48-beta.0

package/dist/server/index.js

@@ -4,75 +4,180 @@
  * Hosts:
  *   - Graph API (read-only REST over WorkspaceManager)
  *   - Agent chat via POST /api/chat and SSE GET /api/chat/stream
- *   - App plugins mounted via PluginLoader
+ *   - Static web UI (SvelteKit build) with SPA fallback
  */
 import Fastify from 'fastify';
 import cookie from '@fastify/cookie';
 import cors from '@fastify/cors';
+import rateLimit from '@fastify/rate-limit';
 import websocket from '@fastify/websocket';
+import { sanitize } from './middleware/sanitize.js';
 import { existsSync, readFileSync, createReadStream, statSync } from 'fs';
-import { join, extname } from 'path';
+import { join, extname, resolve, sep } from 'path';
 import { Workspace } from '../core/workspace.js';
 import { AgentOrchestrator } from '../agent/orchestrator.js';
-import { PluginLoader, MIME_TYPES } from './plugin-loader.js';
 import { registerGraphApiRoutes } from './routes/graph-api.js';
 import { registerChatRoutes } from './routes/chat.js';
 import { registerWorkspaceApiRoutes } from './routes/workspace-api.js';
+import { registerHealthApiRoutes } from './routes/health.js';
 import { registerPermissionsApiRoutes } from './routes/permissions-api.js';
 import { registerAuthApiRoutes } from './routes/auth-api.js';
 import { registerGitHttpRoutes } from './routes/git-http.js';
-import { registerSyncApiRoutes } from './routes/sync-api.js';
 import { registerViewsApiRoutes } from './routes/views-api.js';
 import { registerInsightsApiRoutes } from './routes/insights-api.js';
 import { registerMcpRoutes } from './routes/mcp.js';
-import { registerMeetingIngestRoutes } from './routes/meeting-ingest-api.js';
-import { AuthService } from '../services/auth-service.js';
+import { registerConnectorsApiRoutes } from './routes/connectors-api.js';
+import { registerAssetApiRoutes } from './routes/asset-api.js';
+import { registerR2ApiRoutes } from './routes/r2-api.js';
+import multipart from '@fastify/multipart';
+import { registerEventIngestRoutes } from './routes/event-ingest-api.js';
+import { registerCaptureRoutes } from './routes/capture-api.js';
+import { registerUrlRoutes } from './routes/url-api.js';
+import { registerConfigApiRoutes } from './routes/config-api.js';
+import { registerSettingsApiRoutes } from './routes/settings-api.js';
+import { registerSecretsApiRoutes } from './routes/secrets-api.js';
+import { registerAuditApiRoutes } from './routes/audit-api.js';
+import { registerCommentsApiRoutes } from './routes/comments-api.js';
+import { AuthService, isWorkspaceOwner } from '../services/auth-service.js';
 import { MemoryService } from '../services/memory-service.js';
+import { CommentService } from '../services/comment-service.js';
+import { NotificationService } from '../services/notification-service.js';
 import { WsHub } from './ws-hub.js';
 import { registerWsRoute } from './routes/ws.js';
 import { SessionManager } from './session-manager.js';
 import { YjsManager } from './yjs-manager.js';
+import { YjsPersistence, acquireYjsStateLock } from './yjs-persistence.js';
+import { BodyWriteCoordinator } from './body-write-coordinator.js';
+import { ensurePersonalFolder } from '../services/personal-folder.js';
+/** Ensure every user has a personal "My Folder" folder + admin access on it (idempotent). */
+async function ensureAllPersonalFolders(authService, workspacePath, workspaceManager) {
+    const users = authService.listUsers();
+    const workspace = new Workspace(workspacePath);
+    for (const user of users) {
+        try {
+            await ensurePersonalFolder(workspace, authService, user);
+        }
+        catch { /* non-fatal — skip and let the user re-authenticate */ }
+    }
+    workspaceManager.reloadConfig();
+}
+/** MIME types for static file serving (web UI assets). */
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+};
+export function resolveStaticFilePath(webDir, urlPath) {
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(urlPath);
+    }
+    catch {
+        return null;
+    }
+    const filePath = decodedPath === '/' ? '/index.html' : decodedPath;
+    const webRoot = resolve(webDir);
+    const fullPath = resolve(webRoot, `.${filePath}`);
+    if (fullPath !== webRoot && !fullPath.startsWith(webRoot + sep)) {
+        return null;
+    }
+    return fullPath;
+}
+function normalizeOrigin(value) {
+    if (!value)
+        return null;
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildAllowedCorsOrigins(workspaceConfig, port) {
+    const rawOrigins = [];
+    const envOrigins = process.env.STUDIOGRAPH_CORS_ORIGINS;
+    if (envOrigins)
+        rawOrigins.push(...envOrigins.split(',').map(o => o.trim()).filter(Boolean));
+    const configured = workspaceConfig.cors_origins;
+    if (Array.isArray(configured)) {
+        rawOrigins.push(...configured.filter((o) => typeof o === 'string'));
+    }
+    else if (typeof configured === 'string') {
+        rawOrigins.push(...configured.split(',').map(o => o.trim()).filter(Boolean));
+    }
+    const serverUrl = workspaceConfig.server_url;
+    if (typeof serverUrl === 'string')
+        rawOrigins.push(serverUrl);
+    rawOrigins.push(`http://localhost:${port}`, `http://127.0.0.1:${port}`, `http://[::1]:${port}`);
+    return new Set(rawOrigins.map(normalizeOrigin).filter((o) => Boolean(o)));
+}
+export function isCorsOriginAllowed(origin, allowedOrigins) {
+    if (!origin)
+        return true;
+    const normalized = normalizeOrigin(origin);
+    return Boolean(normalized && allowedOrigins.has(normalized));
+}
+function isTruthyEnv(value) {
+    return Boolean(value && ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase()));
+}
 /**
  * Auth middleware — validates JWT cookie or Authorization: Bearer <key> header.
  * When users exist in the auth database, all routes require authentication
  * (except auth endpoints and static assets). When no users exist, everything
  * is open (backward compatible).
  */
-function createAuthHook(apiKeys, authService) {
+function createAuthHook(authService) {
     return async (req, reply) => {
         // Always allow auth endpoints
         if (req.url.startsWith('/api/auth/'))
             return;
-        // OAuth callbacks identify the user via the state parameter, not cookies
+        // Managed Cloud login handoff verifies its own short-lived token.
+        if (req.url.startsWith('/api/cloud/auth/'))
+            return;
+        // OAuth callbacks and claims identify the user via state/claim code, not cookies
         if (req.url.startsWith('/api/oauth/callback/'))
             return;
+        if (req.url.startsWith('/api/oauth/claim/'))
+            return;
         // Git HTTP routes have their own Basic Auth
         if (req.url.startsWith('/git/'))
             return;
         // WebSocket route handles its own auth
         if (req.url.startsWith('/ws'))
             return;
-        // Allow static assets (JS, CSS, fonts, images) — needed for login page
-        if (req.url.startsWith('/_app/') || req.url.startsWith('/api/chrome/'))
+        // Allow static assets (JS, CSS, fonts, images) — needed for login page.
+        // Covers SvelteKit-bundled output under /_app/ and root-level public
+        // files (favicon.ico, studiograph-logomark.svg, …) identified by a file
+        // extension on a non-API GET.
+        if (req.url.startsWith('/_app/'))
+            return;
+        if (req.method === 'GET' &&
+            !req.url.startsWith('/api/') &&
+            extname(req.url.split('?')[0]).length > 1)
             return;
         // Allow HTML page requests (SPA routing) — the app handles auth client-side
         if (req.method === 'GET' && req.headers.accept?.includes('text/html'))
             return;
-        // If no users configured, allow everything (open mode)
-        if (!authService.hasUsers()) {
-            // Still check API keys for programmatic routes if configured
-            if (apiKeys.length > 0) {
-                const authHeader = req.headers['authorization'];
-                const bearer = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : undefined;
-                if (bearer && apiKeys.includes(bearer))
-                    return;
-                // For non-API routes (i.e. browser requests), allow without auth
-                if (!req.url.startsWith('/api/') || req.url.startsWith('/api/auth/'))
-                    return;
-                // For API routes without a bearer token, allow if no users exist
-            }
+        // If no users configured, allow everything in local open mode. Managed
+        // Cloud workspaces still require auth before the first user handoff lands.
+        if (!authService.hasUsers() && !isTruthyEnv(process.env.STUDIOGRAPH_MANAGED_AUTH))
             return;
-        }
         // Check JWT cookie (web UI sessions)
         const jwtToken = req.cookies?.['__sg_token'];
         if (jwtToken) {
@@ -82,11 +187,26 @@ function createAuthHook(apiKeys, authService) {
                 return;
             }
         }
-        // Check Bearer token (API clients, MCP)
+        // Check Bearer token (API clients, MCP, CLI): JWT → per-user API token.
+        // Both yield a user identity. There is no shared workspace key — every
+        // caller must be identifiable so access control can enforce per-folder rules.
         const authHeader = req.headers['authorization'];
         const bearer = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : undefined;
-        if (bearer && apiKeys.includes(bearer))
-            return;
+        if (bearer) {
+            const jwtUser = authService.verifyToken(bearer);
+            if (jwtUser) {
+                req.user = jwtUser;
+                return;
+            }
+            const tokenMeta = authService.verifyApiTokenWithMeta(bearer);
+            if (tokenMeta) {
+                req.user = tokenMeta.user;
+                // Stash the token's user-set name so downstream surfaces (MCP, agent
+                // activity) can label the integration. Absent for cookie/JWT auth.
+                req.apiTokenName = tokenMeta.tokenName;
+                return;
+            }
+        }
         // Check Basic Auth (CLI join command)
         if (authHeader?.startsWith('Basic ')) {
             try {
@@ -105,22 +225,143 @@ function createAuthHook(apiKeys, authService) {
         return reply.status(401).send({ error: 'Unauthorized' });
     };
 }
+/**
+ * Phase 11 — preSerialization payload sanitizer.
+ *
+ * The API has many routes that respond with `{ error: err.message }` from a
+ * catch block. Those messages can carry upstream provider errors, git
+ * stderr (with embedded credentials), or other free-form text that we
+ * don't want surfacing in HTTP responses. Walk the response payload,
+ * sanitize any string value at a "message" / "error" / "detail" key,
+ * and leave structured fields (status codes, IDs, classification flags)
+ * alone.
+ *
+ * Conservatively, we ONLY redact at keys that conventionally carry
+ * free-form text. Arbitrary string fields (entity names, IDs, etc.) are
+ * left untouched so we don't garble legitimate content. The Fastify
+ * logger sanitization (above) handles log-line redaction independently;
+ * this hook focuses on the wire response.
+ */
+const FREEFORM_ERROR_KEYS = new Set(['error', 'message', 'detail', 'stack', 'description', 'error_description']);
+function sanitizeResponsePayload(value) {
+    if (typeof value === 'string')
+        return sanitize(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeResponsePayload);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (FREEFORM_ERROR_KEYS.has(k) && typeof v === 'string') {
+                out[k] = sanitize(v);
+            }
+            else if (v && typeof v === 'object') {
+                out[k] = sanitizeResponsePayload(v);
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    return value;
+}
 export async function createServer(config) {
+    // Phase 11: every Fastify log line flows through sanitize() before
+    // reaching stdout. A thin Writable wrapper passes each chunk through
+    // the redactor; pino accepts any `stream` with a `write()` method.
+    // STUDIOGRAPH_LOG_RAW=1 disables redaction for local debugging.
+    const shouldRedactFastifyLogs = process.env.STUDIOGRAPH_LOG_RAW !== '1' &&
+        (process.env.NODE_ENV === 'production' || !!process.env.RAILWAY_ENVIRONMENT);
+    const redactingStream = {
+        write(chunk) {
+            const out = shouldRedactFastifyLogs ? sanitize(chunk) : chunk;
+            process.stdout.write(out);
+        },
+    };
     const fastify = Fastify({
         logger: process.env.STUDIOGRAPH_LOG === '1'
-            ? true
-            : { level: 'warn' },
+            ? { stream: redactingStream }
+            : { level: 'warn', stream: redactingStream },
         bodyLimit: 10 * 1024 * 1024, // 10 MB — entities can be large (e.g. meeting transcripts)
     });
+    // Phase 11: sanitize uncaught errors before serialization so neither
+    // err.message nor err.stack echoes upstream secrets. Stable error
+    // codes (err.code) pass through; we only redact freeform text.
+    fastify.setErrorHandler((error, _req, reply) => {
+        const sanitizedMsg = shouldRedactFastifyLogs ? sanitize(error.message) : error.message;
+        const status = error.statusCode ?? 500;
+        fastify.log.error({
+            err: { message: sanitizedMsg, code: error.code },
+        });
+        reply.status(status).send({
+            statusCode: status,
+            code: error.code,
+            error: status >= 500 ? 'Internal Server Error' : (error.name || 'Error'),
+            message: status >= 500 ? 'An internal error occurred.' : sanitizedMsg,
+        });
+    });
+    // Phase 11: pre-serialization hook scans every response body for
+    // freeform error/message strings and runs them through sanitize().
+    // This catches the many `reply.status(4xx).send({ error: err.message })`
+    // call sites scattered across the API routes — without this, an
+    // upstream provider error or git remote error would echo through to
+    // the API consumer with embedded credentials. Stable error codes pass
+    // through unchanged. Only kicks in when redaction is enabled.
+    if (shouldRedactFastifyLogs) {
+        fastify.addHook('preSerialization', async (_req, _reply, payload) => {
+            if (!payload || typeof payload !== 'object')
+                return payload;
+            return sanitizeResponsePayload(payload);
+        });
+    }
     // CORS
+    const allowedCorsOrigins = buildAllowedCorsOrigins(config.workspaceConfig, config.port);
     await fastify.register(cors, {
-        origin: true,
+        origin: (origin, cb) => {
+            cb(null, isCorsOriginAllowed(origin, allowedCorsOrigins));
+        },
         credentials: true,
     });
     // Cookie support for web UI session auth
     await fastify.register(cookie);
-    // WebSocket support for real-time notifications
-    await fastify.register(websocket);
+    // WebSocket support for real-time notifications.
+    //
+    // perMessageDeflate is enabled here on purpose. Our origin would otherwise
+    // leave compression off (ws lib default), but Railway's edge proxy
+    // negotiates `permessage-deflate` with the browser anyway and does its own
+    // inflate/deflate layer in the middle — which Safari/WebKit mis-decodes,
+    // producing truncated buffers and `RangeError: Length out of range of buffer`
+    // inside Yjs's varint reader, followed by WS disconnect loops.
+    //
+    // Negotiating compression at the origin forces end-to-end deflate (Node's
+    // zlib ↔ browser) and prevents the proxy from inserting its own layer.
+    // `noContextTakeover` on both sides keeps each frame independently
+    // decompressible, which avoids cross-frame state bugs that have historically
+    // hit Safari.
+    await fastify.register(websocket, {
+        options: {
+            perMessageDeflate: {
+                threshold: 1024,
+                serverNoContextTakeover: true,
+                clientNoContextTakeover: true,
+            },
+        },
+    });
+    // Multipart support for file uploads (images, assets)
+    await fastify.register(multipart, { limits: { fileSize: 10 * 1024 * 1024 } });
+    // Global rate-limit registration with a permissive default; individual
+    // routes opt into tighter limits via `config: { rateLimit: ... }`. Today
+    // only comment mutations apply tight limits — keeps the runtime in
+    // place without changing the rest of the API's request-rate behaviour.
+    await fastify.register(rateLimit, {
+        global: false,
+        max: 1000,
+        timeWindow: '1 minute',
+        keyGenerator: (req) => {
+            const u = req.user;
+            return u?.id ? `u:${u.id}` : (req.ip ?? 'unknown');
+        },
+    });
     fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => {
         try {
             req.rawBody = body;
@@ -139,104 +380,135 @@ export async function createServer(config) {
             done(null); // Don't consume the body — the route handler pipes req.raw directly
         });
     }
-    // Initialize auth service, WebSocket hub, session manager, and collab server
-    const authService = new AuthService(config.workspacePath);
-    // Ensure API key is committed to auth-seed.json so `studiograph pull` can use it
-    authService.syncApiKeyToSeed();
-    const wsHub = new WsHub();
+    // Initialize auth service, WebSocket hub, session manager, and collab server.
+    // Phase 8: when the boot path provided master-key options, hand them through
+    // so OAuth tokens + per-user secret prefs use the encrypted column path.
+    const authService = new AuthService(config.workspacePath, config.authCryptoOptions);
+    // Ensure all users have their personal "My Folder" folder
+    await ensureAllPersonalFolders(authService, config.workspacePath, config.workspaceManager);
+    const { getCurrentVersion } = await import('../utils/version-checker.js');
+    const wsHub = new WsHub(getCurrentVersion());
+    const commentService = new CommentService(config.workspacePath);
+    const notificationService = new NotificationService(config.workspacePath);
     const sessionManager = new SessionManager(config.workspaceManager, wsHub);
-    const yjsManager = new YjsManager(config.workspaceManager);
+    // Recover any dirty repos before accepting requests. Replays persisted
+    // pending commits from a previous process AND sweeps every working tree
+    // for uncommitted state. Catches anything dropped by a crash, OOM, or
+    // hard restart. Logs and continues on failure — recovery is best-effort
+    // and must never block server startup.
+    try {
+        await sessionManager.recoverOnBoot();
+    }
+    catch (err) {
+        console.warn('[server] sessionManager.recoverOnBoot failed:', err.message);
+    }
+    // Persistence layer: durable Y.Doc snapshot store across server restarts.
+    // Lives at `<workspace>/.studiograph/yjs-state/` — gitignored binary state
+    // separate from the .md files (which remain canonical for git, MCP, agents).
+    // See yjs-persistence.ts for the file format and concurrency model.
+    const yjsStateDir = join(config.workspacePath, '.studiograph', 'yjs-state');
+    // Single-instance lock. Throws if another studiograph server is already
+    // running against this workspace. We don't support horizontal scaling today
+    // (no shared Yjs pubsub), so the safe default is to fail fast on misuse
+    // rather than silently corrupt snapshots via concurrent writers.
+    const releaseYjsLock = acquireYjsStateLock(yjsStateDir);
+    const yjsPersistence = new YjsPersistence(yjsStateDir);
+    const yjsManager = new YjsManager(config.workspaceManager, yjsPersistence);
+    // Yjs configuration startup log. Surfacing the flags at boot lets operators
+    // verify the configuration without reading source. The fail-closed guards
+    // (`assertWritable`, 412 convergence gate) prevent silent data corruption
+    // regardless of how the flags are set, but `broadcast=off` while clients
+    // are connected degrades UX, so we warn explicitly.
+    const broadcastEnabled = process.env.STUDIOGRAPH_YJS_BROADCAST !== '0';
+    const allowDegradedWrites = process.env.STUDIOGRAPH_ALLOW_DEGRADED_WRITES === '1';
+    console.log(`[yjs] config: broadcast=${broadcastEnabled ? 'on' : 'OFF'} ` +
+        `allow-degraded-writes=${allowDegradedWrites ? 'on' : 'off'}`);
+    if (!broadcastEnabled && !allowDegradedWrites) {
+        console.warn('[yjs] STUDIOGRAPH_YJS_BROADCAST=0 without STUDIOGRAPH_ALLOW_DEGRADED_WRITES=1: ' +
+            'server-side body writes will REFUSE while clients are connected. ' +
+            'This is the fail-closed kill-switch path — intentional during incident response, ' +
+            'misconfiguration otherwise.');
+    }
+    // Wire the Yjs persistence layer to follow structural .md mutations.
+    // delete / rename / changeType all change a doc's identity (path on disk
+    // and its docName), so the snapshot file has to move with it. Without
+    // these hooks, snapshots leak (orphaned files for deleted entities) or
+    // serve stale state at the new identity (ghost content after a rename).
+    config.workspaceManager.setPersistenceCallbacks({
+        onDelete: (repo, entityType, entityId) => yjsPersistence.delete(`${repo}/${entityType}/${entityId}`),
+        onRename: (repo, entityType, oldId, newId) => yjsPersistence.rename(`${repo}/${entityType}/${oldId}`, `${repo}/${entityType}/${newId}`),
+        onChangeType: (repo, entityId, fromType, toType) => yjsPersistence.rename(`${repo}/${fromType}/${entityId}`, `${repo}/${toType}/${entityId}`),
+    });
+    // Body-write coordinator owns the single critical section for every body
+    // write (autosave PUT + MCP / agent / event-processor server-writes). Holds
+    // the per-doc lock, base-hash precondition, atomic disk write, commit +
+    // dirty recovery, post-commit applyAgentContent broadcast, and
+    // mdRevisionHash bookkeeping. Replaces the previous nine-callback shape on
+    // graph.update.
+    const bodyWriteCoordinator = new BodyWriteCoordinator({
+        // Narrow commit hook — keeps the coordinator from reaching back
+        // through WorkspaceManager. No-op when the repo has no GitService.
+        commit: async (coords, actor, message) => {
+            const gitService = config.workspaceManager.getGraph(coords.repo).getGitService();
+            if (!gitService)
+                return;
+            const tx = gitService.createTransaction();
+            tx.add({
+                operation: 'update',
+                entityType: coords.entityType,
+                entityId: coords.entityId,
+                filePath: coords.entityPath,
+            });
+            await tx.commit(actor, message);
+        },
+    }, yjsManager, sessionManager);
+    config.workspaceManager.setBodyWriteCoordinator(bodyWriteCoordinator);
     // Register auth API routes (before the auth hook so they are always accessible)
-    await registerAuthApiRoutes(fastify, authService, config.workspaceConfig.team_name);
+    await registerAuthApiRoutes(fastify, authService, config.workspacePath, config.workspaceManager, config.workspaceConfig.team_name);
     // Auth hook — applied to all routes
-    const authHook = createAuthHook(config.apiKeys, authService);
+    const authHook = createAuthHook(authService);
     fastify.addHook('preHandler', authHook);
     // Register WebSocket route (real-time change notifications + cursor broadcasting)
-    await registerWsRoute(fastify, wsHub, authService, yjsManager);
-    // Register graph API routes (with per-collection access filtering)
-    await registerGraphApiRoutes(fastify, config.workspaceManager, authService, wsHub, sessionManager);
+    await registerWsRoute(fastify, wsHub, authService, config.workspaceManager, yjsManager);
+    // Register graph API routes (with per-folder access filtering)
+    await registerGraphApiRoutes(fastify, config.workspaceManager, authService, wsHub, sessionManager, yjsManager);
     // Register workspace API routes (git operations)
-    await registerWorkspaceApiRoutes(fastify, config.workspaceManager, config.gitUser);
-    // Register permissions API routes (self-hosted collection access)
+    await registerWorkspaceApiRoutes(fastify, config.workspaceManager, config.gitUser, authService);
+    // Register health endpoints (per-repo dirty status)
+    await registerHealthApiRoutes(fastify, config.workspaceManager, sessionManager);
+    // Register config + workspace data API routes (for `studiograph push/pull --remote`)
+    await registerConfigApiRoutes(fastify, config.workspaceManager, config.workspacePath, authService);
+    // Register Phase 7 settings/secrets/audit API routes. Owner-only via
+    // isWorkspaceOwner() inside each handler.
+    await registerSettingsApiRoutes(fastify, authService);
+    await registerSecretsApiRoutes(fastify, authService);
+    await registerAuditApiRoutes(fastify, authService);
+    // Register comments API + notifications feed (Comments-First Phase 1).
+    // The getAgent closure resolves the orchestrator lazily — it's
+    // initialised below at line ~613, AFTER routes register, so route
+    // handlers can't capture it eagerly. The closure binding to the outer
+    // `agent` variable picks up the value once the orchestrator is alive.
+    await registerCommentsApiRoutes(fastify, commentService, notificationService, authService, wsHub, config.workspaceManager, () => agent);
+    // Register permissions API routes (self-hosted folder access)
     await registerPermissionsApiRoutes(fastify, authService, config.workspaceManager, wsHub);
+    // Messages API routes registered after agent init (below) so @agent invocation works
+    // Register connectors API routes (MCP connector management + OAuth)
+    await registerConnectorsApiRoutes(fastify, authService, config.workspacePath);
+    // Register asset upload routes (image upload to R2/local)
+    await registerAssetApiRoutes(fastify, config.workspaceManager, authService);
+    // Register R2 management routes (bucket creation, local-asset sync, status)
+    await registerR2ApiRoutes(fastify, config.workspaceManager, authService, config.gitUser);
     // Register git Smart HTTP routes (clone/fetch/push with Basic Auth)
     await registerGitHttpRoutes(fastify, config.workspaceManager, authService, config.workspacePath, wsHub);
-    // Register sync API routes (collection-scoped sync)
-    await registerSyncApiRoutes(fastify, config.workspaceManager, authService, config.workspacePath, wsHub);
     // Register views API routes (per-user saved views)
     await registerViewsApiRoutes(fastify, authService, config.workspaceManager);
     // Register insights + preferences API routes
-    // Build core tool metadata once from actual tool factories
-    const coreToolMeta = [];
-    try {
-        const { createGraphTools } = await import('../agent/tools/graph-tools.js');
-        const { createSyncTools } = await import('../agent/tools/sync-tools.js');
-        const { createOpsTools } = await import('../agent/tools/ops-tools.js');
-        const dummyUser = { id: '0', name: 'system', email: 'system' };
-        const allTools = [
-            ...createGraphTools(config.workspaceManager, dummyUser, config.workspacePath, undefined, undefined, () => null, authService),
-            ...createSyncTools(config.workspacePath, config.workspaceConfig),
-            ...createOpsTools(config.workspacePath, config.workspaceConfig),
-        ];
-        for (const t of allTools) {
-            if (t.name && t.description) {
-                coreToolMeta.push({ name: t.name, description: t.description });
-            }
-        }
-    }
-    catch (err) {
-        console.warn('[insights] Failed to build tool metadata:', err);
-    }
-    const getToolsForUser = (userId) => {
-        const tools = [...coreToolMeta];
-        // Add connector tools based on user's actually connected services
-        try {
-            const connectedConnectors = authService.getUserConnectedConnectors(userId);
-            for (const c of connectedConnectors) {
-                tools.push({ name: `${c.connector_name}_connector`, description: `Connected ${c.connector_name} integration — can sync and access ${c.connector_name} data` });
-            }
-        }
-        catch { /* no connector tools */ }
-        return tools;
-    };
-    await registerInsightsApiRoutes(fastify, config.workspaceManager, authService, config.workspacePath, wsHub, getToolsForUser);
-    // Register meeting ingest API (Chrome extension + other capture tools)
-    await registerMeetingIngestRoutes(fastify, config.workspaceManager, authService, wsHub);
+    await registerInsightsApiRoutes(fastify, config.workspaceManager, authService, config.workspacePath, wsHub);
+    // Register event ingest API (meeting capture from desktop and external sources)
+    await registerEventIngestRoutes(fastify, config.workspaceManager, authService, wsHub, yjsManager);
     // Register MCP Streamable HTTP endpoint
-    await registerMcpRoutes(fastify, config.workspaceManager, authService);
-    // Serve chrome assets (shared header/footer for app editors)
-    const chromeDir = join(import.meta.dirname, 'chrome');
-    if (existsSync(chromeDir)) {
-        const CHROME_MIME = { '.js': 'application/javascript', '.css': 'text/css' };
-        fastify.get('/api/chrome/:file', async (req, reply) => {
-            const file = req.params.file;
-            if (file.includes('..') || file.includes('/')) {
-                return reply.status(400).send({ error: 'Invalid path' });
-            }
-            const filePath = join(chromeDir, file);
-            if (!existsSync(filePath) || !statSync(filePath).isFile()) {
-                return reply.status(404).send({ error: 'Not found' });
-            }
-            const ext = extname(filePath).toLowerCase();
-            reply.type(CHROME_MIME[ext] || 'application/octet-stream');
-            reply.header('Cache-Control', 'public, max-age=300');
-            return reply.send(createReadStream(filePath));
-        });
-    }
-    // Discover installed apps and collect their skill/tool dirs
-    const loader = new PluginLoader();
-    const manifests = loader.loadApps(config.appsDir);
-    const appSkillsDirs = [];
-    const appToolsDirs = [];
-    for (const manifest of manifests) {
-        const skillsDir = loader.getSkillsDir(config.appsDir, manifest);
-        if (skillsDir)
-            appSkillsDirs.push(skillsDir);
-        const toolsDir = loader.getToolsDir(config.appsDir, manifest);
-        if (toolsDir)
-            appToolsDirs.push(toolsDir);
-    }
-    // Initialize memory service and agent — non-fatal so the server can still serve graph API and apps
+    await registerMcpRoutes(fastify, config.workspaceManager, authService, wsHub, commentService);
+    // Initialize memory service and agent — non-fatal so the server can still serve graph API
     const memoryService = new MemoryService();
     let agent = null;
     try {
@@ -245,12 +517,18 @@ export async function createServer(config) {
             workspacePath: config.workspacePath,
             workspaceConfig: config.workspaceConfig,
             gitUser: config.gitUser,
-            skillsDirs: appSkillsDirs,
-            toolsDirs: appToolsDirs,
             recentMemory,
             workspaceManager: config.workspaceManager,
+            // Share the route-level AuthService. Without this the orchestrator
+            // constructs its own crypto-less copy and (a) errors when reading
+            // encrypted oauth_tokens rows, (b) subscribes to a different
+            // pubsub than the one the OAuth callback fires on — so per-user
+            // OAuth state changes never invalidate the agent pool.
+            authService,
         });
-        await registerChatRoutes(fastify, agent, memoryService);
+        await registerChatRoutes(fastify, agent, wsHub, authService, memoryService);
+        await registerCaptureRoutes(fastify, agent);
+        await registerUrlRoutes(fastify);
     }
     catch (err) {
         fastify.log.warn(`Agent not available: ${err.message ?? err} — chat routes will return setup message`);
@@ -268,55 +546,22 @@ export async function createServer(config) {
             return reply.status(503).send({ error: 'The AI agent is not configured yet. Please set the API key for your model provider in the server environment variables and restart.' });
         });
     }
-    // GET /api/apps — list installed app manifests with resolved entity type names
-    const resolvedApps = manifests.map(m => {
-        let entityTypes = [];
-        try {
-            const etPath = join(config.appsDir, m.name, m.entityTypes);
-            if (existsSync(etPath)) {
-                const raw = JSON.parse(readFileSync(etPath, 'utf-8'));
-                if (Array.isArray(raw)) {
-                    entityTypes = raw.map((item) => item.name).filter(Boolean);
-                }
-            }
-        }
-        catch {
-            // gracefully degrade — return empty array
-        }
-        return { name: m.name, version: m.version, description: m.description, mountPath: m.mountPath, entityTypes };
-    });
-    fastify.get('/api/apps', async (_req, reply) => {
-        return reply.send(resolvedApps);
-    });
     // GET /api/workspace — workspace metadata
     fastify.get('/api/workspace', async (_req, reply) => {
         const workspace = new Workspace(config.workspacePath);
         const about = workspace.loadAbout();
-        return reply.send({ name: config.workspaceConfig.team_name, about, accent_color: config.workspaceConfig.accent_color ?? null });
+        return reply.send({ name: config.workspaceConfig.team_name, about });
     });
-    // PUT /api/workspace — update workspace identity (admin only)
+    // PUT /api/workspace — update workspace identity (owner only)
     fastify.put('/api/workspace', async (req, reply) => {
         const user = req.user;
-        if (user && user.role !== 'admin') {
-            return reply.status(403).send({ error: 'Admin access required' });
+        if (user && !isWorkspaceOwner(user.role)) {
+            return reply.status(403).send({ error: 'Workspace owner access required' });
         }
-        const { name, about, accent_color } = req.body ?? {};
+        const { name, about } = req.body ?? {};
         const workspace = new Workspace(config.workspacePath);
-        let configChanged = false;
         if (typeof name === 'string' && name.trim()) {
             config.workspaceConfig.team_name = name.trim();
-            configChanged = true;
-        }
-        if (accent_color !== undefined) {
-            if (accent_color === null) {
-                delete config.workspaceConfig.accent_color;
-            }
-            else {
-                config.workspaceConfig.accent_color = accent_color;
-            }
-            configChanged = true;
-        }
-        if (configChanged) {
             workspace.writeConfig(config.workspaceConfig);
         }
         if (typeof about === 'string') {
@@ -324,28 +569,28 @@ export async function createServer(config) {
         }
         return reply.send({ success: true });
     });
-    // GET /api/workspace/mcp-config — MCP client configuration snippet (admin only)
+    // GET /api/workspace/mcp-config — MCP client configuration snippet.
+    // Returns a template with `<your-token-here>` in the Authorization header;
+    // the frontend fills it in after the user mints a personal token via
+    // POST /api/auth/tokens. We never embed a shared key here because doing so
+    // would leak a workspace-wide credential and re-introduce the bug the
+    // per-user-token model exists to solve.
     fastify.get('/api/workspace/mcp-config', async (req, reply) => {
-        const user = req.user;
-        if (user && user.role !== 'admin') {
-            return reply.status(403).send({ error: 'Admin access required' });
-        }
         const proto = req.headers['x-forwarded-proto'] === 'https' ? 'https' : (req.protocol ?? 'http');
         const host = req.headers['x-forwarded-host'] || req.headers.host || 'localhost';
         const baseUrl = `${proto}://${host}`;
-        const apiKey = authService.getApiKey();
         const mcpConfig = {
             mcpServers: {
                 studiograph: {
                     type: 'streamable-http',
                     url: `${baseUrl}/mcp`,
                     headers: {
-                        Authorization: `Bearer ${apiKey}`,
+                        Authorization: 'Bearer <your-token-here>',
                     },
                 },
             },
         };
-        return reply.send({ config: mcpConfig });
+        return reply.send({ config: mcpConfig, url: `${baseUrl}/mcp` });
     });
     // DELETE /api/memory — clear all agent memory files
     fastify.delete('/api/memory', async (_req, reply) => {
@@ -357,19 +602,6 @@ export async function createServer(config) {
         const count = agent?.clearSessions() ?? 0;
         return reply.send({ cleared: count });
     });
-    // Mount app plugins
-    for (const manifest of manifests) {
-        try {
-            await loader.mountPlugin(fastify, manifest, config.appsDir, {
-                workspaceManager: config.workspaceManager,
-                gitUser: config.gitUser,
-            });
-            fastify.log.info(`Mounted app "${manifest.name}" at ${manifest.mountPath}`);
-        }
-        catch (err) {
-            fastify.log.error(err, `Failed to mount app "${manifest.name}"`);
-        }
-    }
     // Serve web UI static files from dist/web/ with SPA fallback
     // When running via tsx from source, import.meta.dirname is src/server/ so ../web doesn't exist.
     // Fall back to dist/web/ relative to project root.
@@ -377,12 +609,34 @@ export async function createServer(config) {
     const webDir = existsSync(webDirCandidate) ? webDirCandidate : join(import.meta.dirname, '..', '..', 'dist', 'web');
     if (existsSync(webDir)) {
         const indexPath = join(webDir, 'index.html');
-        // SPA fallback for app routes: if an app plugin returns a JSON error for a
-        // browser GET request, serve the SPA instead. This happens when the browser
-        // refreshes a URL like /documents/document/doc-123 — the app's greedy route
-        // catches it but fails because the params don't match its expectations.
+        // SPA fallback: if any API route returns a JSON error for a browser GET,
+        // serve the SPA instead so client-side routing can handle the URL.
         // Read fresh from disk each time so rebuilds take effect without server restart.
         const readIndexHtml = () => readFileSync(indexPath);
+        /**
+         * Cache policy for static assets:
+         * - `/_app/immutable/*` are content-hashed by SvelteKit, so the URL
+         *   changes every time the file does — safe to cache forever.
+         * - `index.html` (and the SPA fallback) MUST revalidate every load,
+         *   otherwise stale HTML keeps pointing at expired immutable hashes.
+         * - Other root assets (favicons, og images, etc.) get a modest TTL.
+         *
+         * Without these headers the upstream CDN (Fastly in front of Railway)
+         * forwards almost every request to origin, producing multi-second
+         * TTFB on cold edges and a 3-5s "black screen" while the SPA bundle
+         * loads.
+         */
+        function setStaticCacheHeader(reply, urlPath) {
+            if (urlPath.startsWith('/_app/immutable/')) {
+                reply.header('Cache-Control', 'public, max-age=31536000, immutable');
+            }
+            else if (urlPath === '/' || urlPath === '/index.html' || !extname(urlPath)) {
+                reply.header('Cache-Control', 'no-cache');
+            }
+            else {
+                reply.header('Cache-Control', 'public, max-age=3600');
+            }
+        }
         fastify.addHook('onSend', async (request, reply, payload) => {
             if (reply.sent)
                 return payload;
@@ -393,23 +647,24 @@ export async function createServer(config) {
                 typeof ct === 'string' && ct.includes('application/json')) {
                 reply.removeHeader('content-length');
                 reply.code(200).type('text/html');
+                reply.header('Cache-Control', 'no-cache');
                 return readIndexHtml();
             }
             return payload;
         });
-        // Use setNotFoundHandler so app plugins and API routes take priority
+        // Use setNotFoundHandler so API routes take priority over SPA fallback
         fastify.setNotFoundHandler(async (req, reply) => {
             const urlPath = req.url.split('?')[0];
-            const filePath = urlPath === '/' ? '/index.html' : urlPath;
-            const fullPath = join(webDir, filePath);
+            const fullPath = resolveStaticFilePath(webDir, urlPath);
+            if (!fullPath) {
+                return reply.status(400).send({ error: 'Invalid path' });
+            }
             // Serve the file if it exists (and is a file, not directory)
             if (existsSync(fullPath) && statSync(fullPath).isFile()) {
-                if (fullPath.includes('..')) {
-                    return reply.status(400).send({ error: 'Invalid path' });
-                }
                 const ext = extname(fullPath).toLowerCase();
                 const contentType = MIME_TYPES[ext] || 'application/octet-stream';
                 reply.type(contentType);
+                setStaticCacheHeader(reply, urlPath);
                 return reply.send(createReadStream(fullPath));
             }
             // SPA fallback — serve index.html for client-side routing.
@@ -419,18 +674,21 @@ export async function createServer(config) {
             const hasFileExt = extname(urlPath).length > 1;
             if (req.method === 'GET' && !hasFileExt && existsSync(indexPath)) {
                 reply.type('text/html');
+                reply.header('Cache-Control', 'no-cache');
                 return reply.send(createReadStream(indexPath));
             }
             return reply.status(404).send({ error: 'Not found' });
         });
         fastify.log.info('Web UI enabled — serving from dist/web/');
     }
-    // Graceful shutdown — flush pending git commits before server closes
+    // Graceful shutdown — sessionManager.shutdown() flushes pending commits
+    // BEFORE tearing down the timer (the old destroy()-only path could lose
+    // dirty sessions if called without an explicit flush).
     fastify.addHook('onClose', async () => {
-        await sessionManager.flushAll();
-        sessionManager.destroy();
-        yjsManager.destroy();
+        await sessionManager.shutdown();
+        await yjsManager.destroy();
         wsHub.destroy();
+        releaseYjsLock();
     });
     return fastify;
 }