@taskforcehq/taskforce 0.3.168

package/dist/server/index.js

@@ -0,0 +1,757 @@
+/**
+ * Taskforce Standalone Server
+ *
+ * Lightweight HTTP server with WebSocket support for live updates.
+ * Serves pre-built static UI and provides API endpoints.
+ */
+import * as http from 'http';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { WebSocketServer } from 'ws';
+import chokidar from 'chokidar';
+import { TaskforceCore } from '../core/Taskforce.js';
+import { createRoutes, matchRoute } from './routes.js';
+import { applyCorsHeaders, getAllowedOriginsFromEnv } from './cors.js';
+import { applyPrefixedRateLimitHeaders, applyRateLimitHeaders, InMemoryRateLimiter, resolveRateLimitKey } from './rateLimit.js';
+import { isRequestAuthorized, resolveAuthConfigFromEnv, resolveRequestAccess } from './auth.js';
+import { assertCloudDatabaseProvider, resolveRuntimeModeFromEnv } from './runtimeMode.js';
+import { applySecurityHeaders } from './securityHeaders.js';
+import { resolveDatabaseConfigFromEnv } from '../storage/providerConfig.js';
+import { resolveObjectStorageConfigFromEnv } from '../storage/objectStorageConfig.js';
+import { purgeExpiredDocuments } from '../storage/documentPurge.js';
+import { scanDocumentIntegrity } from '../storage/documentIntegrity.js';
+import { resolveStorageIntegrityScheduleSettings, shouldRunStorageIntegritySchedule } from '../storage/integritySchedule.js';
+import { TaskAssetStore } from '../storage/taskAssetStore.js';
+import { DocumentRegistry } from '../storage/documentRegistry.js';
+import { assertEnvironment } from '../config/envSchema.js';
+import { createRealtimeSyncWsManager } from './realtimeSyncWs.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.svg': 'image/svg+xml',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+};
+function resolveStaticUiPath() {
+    const candidates = [
+        // Current output layout
+        path.resolve(__dirname, '../../dist/ui'),
+        // Legacy/alternative layouts from older package builds
+        path.resolve(__dirname, '../../ui'),
+        path.resolve(__dirname, '../../dist/public'),
+        path.resolve(__dirname, '../../public')
+    ];
+    for (const candidate of candidates) {
+        const indexPath = path.join(candidate, 'index.html');
+        if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
+            return { uiPath: candidate, candidates };
+        }
+    }
+    return { uiPath: null, candidates };
+}
+function readPositiveInteger(value, fallback) {
+    const parsed = Number.parseInt(String(value || '').trim(), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+const STORAGE_INTEGRITY_HISTORY_LIMIT = 50;
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+const CORS_RESPONSE_HEADERS = new Set([
+    'access-control-allow-origin',
+    'access-control-allow-credentials',
+    'access-control-allow-methods',
+    'access-control-allow-headers',
+    'access-control-expose-headers',
+    'access-control-max-age',
+    'vary'
+]);
+function shouldProxyCloudPath(pathname) {
+    if (!pathname)
+        return false;
+    if (pathname === '/api/taskforce/auth/runtime-config')
+        return false;
+    return pathname.startsWith('/api/taskforce/auth/') || pathname.startsWith('/api/taskforce/sync/');
+}
+export function shouldRewriteSetCookieForLocalDevHost(hostHeader) {
+    const host = String(hostHeader || '').trim().toLowerCase();
+    if (!host)
+        return false;
+    const hostname = host.replace(/:\d+$/, '');
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+}
+export function rewriteProxySetCookieForLocalHost(cookie) {
+    const parts = String(cookie || '').split(';').map((part) => part.trim()).filter(Boolean);
+    if (parts.length === 0)
+        return cookie;
+    const [nameValue, ...attrs] = parts;
+    const filteredAttrs = attrs.filter((attr) => !attr.toLowerCase().startsWith('domain='));
+    return [nameValue, ...filteredAttrs].join('; ');
+}
+async function readRequestBody(req, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > maxBytes) {
+            throw new Error(`PAYLOAD_TOO_LARGE:${maxBytes}`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+export function shouldApplyAuthRateLimitForPath(pathname) {
+    const normalizedPath = String(pathname || '').trim();
+    return normalizedPath.startsWith('/api/taskforce/auth/')
+        && normalizedPath !== '/api/taskforce/auth/session';
+}
+const BILLING_WEBHOOK_PATH = '/api/taskforce/billing/webhook';
+export function ensureBillingWebhookAuthExclusion(excludedPaths) {
+    if (excludedPaths.includes(BILLING_WEBHOOK_PATH))
+        return excludedPaths;
+    return [...excludedPaths, BILLING_WEBHOOK_PATH];
+}
+export function isBillingWebhookPath(pathname) {
+    return String(pathname || '').trim() === BILLING_WEBHOOK_PATH;
+}
+export function createStandaloneServer(options) {
+    assertEnvironment(process.env, { target: 'server', strictUnknown: true });
+    const db = resolveDatabaseConfigFromEnv();
+    const runtimeMode = resolveRuntimeModeFromEnv(process.env, db.provider);
+    assertCloudDatabaseProvider(runtimeMode, db.provider, process.env);
+    const core = new TaskforceCore({
+        projectRoot: options.projectRoot,
+        tenantId: process.env.TASKFORCE_TENANT_ID || 'default',
+        database: {
+            provider: db.provider,
+            connectionString: db.connectionString
+        }
+    });
+    const { basePath } = core.getPaths();
+    const taskAssetStore = new TaskAssetStore(core.getDatabaseAdapter(), core.getTenantId(), basePath, new DocumentRegistry(basePath));
+    const authConfig = resolveAuthConfigFromEnv(runtimeMode, process.env);
+    authConfig.excludedPaths = ensureBillingWebhookAuthExclusion(authConfig.excludedPaths);
+    const objectStorage = resolveObjectStorageConfigFromEnv(process.env);
+    const resolveEffectiveObjectStorage = () => {
+        if (objectStorage.provider !== 'r2' || !objectStorage.r2)
+            return objectStorage;
+        const globalSettings = core.getGlobalSettings();
+        const storageSettings = globalSettings.objectStorage && typeof globalSettings.objectStorage === 'object'
+            ? globalSettings.objectStorage
+            : {};
+        const keyPrefixRaw = typeof storageSettings.keyPrefix === 'string'
+            ? storageSettings.keyPrefix.trim().replace(/^\/+|\/+$/g, '')
+            : '';
+        const uploadTtlRaw = Number(storageSettings.signedUploadTtlSeconds);
+        const downloadTtlRaw = Number(storageSettings.signedDownloadTtlSeconds);
+        return {
+            provider: 'r2',
+            r2: {
+                ...objectStorage.r2,
+                keyPrefix: keyPrefixRaw || objectStorage.r2.keyPrefix,
+                signedUploadTtlSeconds: Number.isFinite(uploadTtlRaw) && uploadTtlRaw > 0
+                    ? Math.floor(uploadTtlRaw)
+                    : objectStorage.r2.signedUploadTtlSeconds,
+                signedDownloadTtlSeconds: Number.isFinite(downloadTtlRaw) && downloadTtlRaw > 0
+                    ? Math.floor(downloadTtlRaw)
+                    : objectStorage.r2.signedDownloadTtlSeconds
+            }
+        };
+    };
+    const routes = createRoutes(core, {
+        authConfig,
+        objectStorage: resolveEffectiveObjectStorage()
+    });
+    const allowedOrigins = getAllowedOriginsFromEnv(process.env.TASKFORCE_ALLOWED_ORIGINS);
+    const cloudProxyBaseUrl = String(process.env.TASKFORCE_CLOUD_PROXY_BASE_URL || '').trim().replace(/\/+$/, '');
+    const cloudProxyEnabled = runtimeMode === 'local' && Boolean(cloudProxyBaseUrl);
+    const cloudProxyClientId = String(process.env.TASKFORCE_CF_ACCESS_CLIENT_ID || process.env.CF_ACCESS_CLIENT_ID || '').trim();
+    const cloudProxyClientSecret = String(process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET || process.env.CF_ACCESS_CLIENT_SECRET || '').trim();
+    const rateLimitEnabled = typeof process.env.TASKFORCE_API_RATE_LIMIT_ENABLED === 'string'
+        ? process.env.TASKFORCE_API_RATE_LIMIT_ENABLED !== 'false'
+        : (runtimeMode === 'cloud');
+    const rateLimitLimit = Number.parseInt(process.env.TASKFORCE_API_RATE_LIMIT_MAX_REQUESTS || '', 10) || 120;
+    const rateLimitWindowMs = Number.parseInt(process.env.TASKFORCE_API_RATE_LIMIT_WINDOW_MS || '', 10) || 60_000;
+    const webhookRateLimitMaxRequests = Number.parseInt(process.env.TASKFORCE_STRIPE_WEBHOOK_RATE_LIMIT_MAX_REQUESTS || '', 10) || 600;
+    const webhookRateLimitWindowMs = Number.parseInt(process.env.TASKFORCE_STRIPE_WEBHOOK_RATE_LIMIT_WINDOW_MS || '', 10) || 60_000;
+    const maxPayloadBytes = Number.parseInt(process.env.TASKFORCE_MAX_PAYLOAD_BYTES || '', 10) || 1_048_576;
+    const rateLimiter = new InMemoryRateLimiter(rateLimitLimit, rateLimitWindowMs);
+    const webhookRateLimiter = new InMemoryRateLimiter(webhookRateLimitMaxRequests, webhookRateLimitWindowMs);
+    const resolveAuthRateLimitSettings = () => {
+        const auth = core.getGlobalSettings().auth || {};
+        const maxRequestsRaw = Number(auth.authRateLimitMaxRequests);
+        const windowMsRaw = Number(auth.authRateLimitWindowMs);
+        return {
+            enabled: auth.authRateLimitEnabled !== false,
+            maxRequests: Number.isFinite(maxRequestsRaw) && maxRequestsRaw >= 1 ? Math.floor(maxRequestsRaw) : 10,
+            windowMs: Number.isFinite(windowMsRaw) && windowMsRaw >= 1000 ? Math.floor(windowMsRaw) : 15 * 60_000
+        };
+    };
+    let authRateLimitSettings = resolveAuthRateLimitSettings();
+    let authRateLimiter = new InMemoryRateLimiter(authRateLimitSettings.maxRequests, authRateLimitSettings.windowMs);
+    const isCollaborationPolicyEnabled = () => {
+        const rawDefault = String(process.env.TASKFORCE_COLLAB_POLICY_V1 || 'true').trim().toLowerCase();
+        const envDefaultEnabled = !(rawDefault === '0' || rawDefault === 'false' || rawDefault === 'off' || rawDefault === 'no');
+        const settings = core.getGlobalSettings();
+        const override = settings?.collaborationPolicy && typeof settings.collaborationPolicy === 'object'
+            ? settings.collaborationPolicy
+            : null;
+        if (typeof override?.enabled === 'boolean')
+            return override.enabled;
+        return envDefaultEnabled;
+    };
+    const getCollaborationTelemetryState = () => {
+        const settings = core.getGlobalSettings();
+        const raw = settings?.collaborationTelemetry || {};
+        const counters = raw?.counters && typeof raw.counters === 'object'
+            ? raw.counters
+            : {};
+        const recent = Array.isArray(raw?.recent)
+            ? raw.recent
+                .filter((item) => item && typeof item === 'object')
+                .slice(0, 100)
+                .map((item) => ({
+                ts: String(item.ts || ''),
+                scope: item.scope === 'auth' || item.scope === 'admin' || item.scope === 'member-mutation'
+                    ? item.scope
+                    : 'auth',
+                method: String(item.method || 'GET'),
+                path: String(item.path || ''),
+                statusCode: Number(item.statusCode) || 0
+            }))
+            : [];
+        return {
+            counters,
+            updatedAt: typeof raw?.updatedAt === 'string' ? raw.updatedAt : null,
+            recent
+        };
+    };
+    const appendCollaborationTelemetry = (entry, counterKeys) => {
+        const current = getCollaborationTelemetryState();
+        const counters = { ...current.counters };
+        for (const key of counterKeys) {
+            counters[key] = Number(counters[key] || 0) + 1;
+        }
+        core.updateGlobalSettings({
+            collaborationTelemetry: {
+                counters,
+                updatedAt: entry.ts,
+                recent: [entry, ...current.recent].slice(0, 100)
+            }
+        });
+    };
+    const recordCollaborationRouteTelemetry = (pathname, methodRaw, statusCodeRaw) => {
+        const method = String(methodRaw || 'GET').toUpperCase();
+        const statusCode = Number(statusCodeRaw);
+        const isAuth = pathname.startsWith('/api/taskforce/auth/');
+        const isAdmin = pathname.startsWith('/api/taskforce/admin/');
+        const isMutation = method === 'POST' || method === 'PATCH' || method === 'DELETE';
+        const isMemberMutation = isMutation && pathname.startsWith('/api/taskforce/') && !isAuth && !isAdmin;
+        const scope = isAuth
+            ? 'auth'
+            : (isAdmin ? 'admin' : (isMemberMutation ? 'member-mutation' : null));
+        if (!scope)
+            return;
+        const counterKeys = [`${scope}.requests.total`, `status.${statusCode}`];
+        if (statusCode === 401 || statusCode === 403) {
+            counterKeys.push(`${scope}.status.${statusCode}`);
+        }
+        if (pathname === '/api/taskforce/auth/invite/accept' && statusCode >= 400) {
+            counterKeys.push('auth.invite_accept.failures');
+        }
+        if (counterKeys.length <= 2 && statusCode !== 401 && statusCode !== 403 && pathname !== '/api/taskforce/auth/invite/accept') {
+            return;
+        }
+        appendCollaborationTelemetry({
+            ts: new Date().toISOString(),
+            scope,
+            method,
+            path: pathname,
+            statusCode
+        }, counterKeys);
+    };
+    // Resolve static files directory at runtime
+    // Standalone UI source now lives in apps/app and builds to dist/ui.
+    // When built: dist/server/index.js -> dist/ui/
+    // When source: src/server/index.ts -> dist/ui/
+    const uiResolution = resolveStaticUiPath();
+    const distUiPath = uiResolution.uiPath;
+    if (distUiPath) {
+        console.log(`[Taskforce] Serving static files from: ${distUiPath}`);
+    }
+    else {
+        console.warn('[Taskforce] UI bundle not found. Checked:');
+        for (const candidate of uiResolution.candidates) {
+            console.warn(`  - ${candidate}`);
+        }
+    }
+    console.log(`[Taskforce] Watching for changes in: ${basePath}`);
+    console.log(`[Taskforce] Runtime mode: ${runtimeMode}`);
+    if (rateLimitEnabled) {
+        console.log(`[Taskforce] API rate limit enabled: ${rateLimitLimit} req/${Math.ceil(rateLimitWindowMs / 1000)}s`);
+        console.log(`[Taskforce] Webhook rate limit enabled: ${webhookRateLimitMaxRequests} req/${Math.ceil(webhookRateLimitWindowMs / 1000)}s`);
+    }
+    else {
+        console.log('[Taskforce] API rate limit disabled');
+    }
+    if (authRateLimitSettings.enabled) {
+        console.log(`[Taskforce] Auth rate limit enabled: ${authRateLimitSettings.maxRequests} req/${Math.ceil(authRateLimitSettings.windowMs / 1000)}s`);
+    }
+    else {
+        console.log('[Taskforce] Auth rate limit disabled');
+    }
+    if (authConfig.enabled && authConfig.requiredForApi) {
+        console.log('[Taskforce] API auth enabled');
+    }
+    else {
+        console.log('[Taskforce] API auth disabled');
+    }
+    console.log(`[Taskforce] Auth session cookie domain: ${authConfig.sessionCookieDomain || '(host-only)'}`);
+    console.log(`[Taskforce] Object storage provider: ${objectStorage.provider}`);
+    if (objectStorage.provider === 'r2' && objectStorage.r2) {
+        console.log(`[Taskforce] Object storage bucket: ${objectStorage.r2.bucket}`);
+    }
+    console.log(`[Taskforce] Max API payload size: ${maxPayloadBytes} bytes`);
+    if (cloudProxyEnabled) {
+        console.log(`[Taskforce] Cloud proxy enabled: ${cloudProxyBaseUrl}`);
+    }
+    const purgeEnabled = process.env.TASKFORCE_DOCUMENT_PURGE_ENABLED !== 'false';
+    const purgeIntervalMinutes = readPositiveInteger(process.env.TASKFORCE_DOCUMENT_PURGE_INTERVAL_MINUTES, 15);
+    if (purgeEnabled) {
+        console.log(`[Taskforce] Document purge enabled: every ${purgeIntervalMinutes} minute(s)`);
+    }
+    else {
+        console.log('[Taskforce] Document purge disabled');
+    }
+    const integritySchedulePollMinutes = readPositiveInteger(process.env.TASKFORCE_STORAGE_INTEGRITY_SCHEDULE_POLL_MINUTES, 1);
+    console.log(`[Taskforce] Storage integrity scheduler poll: every ${integritySchedulePollMinutes} minute(s)`);
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url || '/', `http://localhost`);
+        applySecurityHeaders(res, runtimeMode);
+        // Handle CORS preflight
+        if (req.method === 'OPTIONS') {
+            const cors = applyCorsHeaders(req, res, allowedOrigins);
+            if (!cors.allowed) {
+                console.warn(`[Taskforce] CORS preflight rejected origin="${String(req.headers.origin || '')}" path="${url.pathname}"`);
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'CORS origin not allowed' }));
+                return;
+            }
+            res.writeHead(200);
+            res.end();
+            return;
+        }
+        if (cloudProxyEnabled && shouldProxyCloudPath(url.pathname)) {
+            const cors = applyCorsHeaders(req, res, allowedOrigins);
+            if (!cors.allowed) {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'CORS origin not allowed' }));
+                return;
+            }
+            try {
+                const method = String(req.method || 'GET').toUpperCase();
+                const upstreamUrl = `${cloudProxyBaseUrl}${url.pathname}${url.search || ''}`;
+                const headers = new Headers();
+                for (const [key, value] of Object.entries(req.headers)) {
+                    const name = key.toLowerCase();
+                    if (!value)
+                        continue;
+                    if (name === 'host' || name === 'content-length' || HOP_BY_HOP_HEADERS.has(name))
+                        continue;
+                    const serialized = Array.isArray(value) ? value.join(', ') : String(value);
+                    if (!serialized.trim())
+                        continue;
+                    headers.set(key, serialized);
+                }
+                if (cloudProxyClientId && cloudProxyClientSecret) {
+                    headers.set('CF-Access-Client-Id', cloudProxyClientId);
+                    headers.set('CF-Access-Client-Secret', cloudProxyClientSecret);
+                }
+                const hasBody = method !== 'GET' && method !== 'HEAD';
+                const body = hasBody ? await readRequestBody(req, maxPayloadBytes) : undefined;
+                const upstream = await fetch(upstreamUrl, {
+                    method,
+                    headers,
+                    body: body && body.length > 0 ? new Uint8Array(body) : undefined,
+                    redirect: 'manual'
+                });
+                const outgoingHeaders = {};
+                for (const [key, value] of upstream.headers.entries()) {
+                    const name = key.toLowerCase();
+                    if (HOP_BY_HOP_HEADERS.has(name))
+                        continue;
+                    if (CORS_RESPONSE_HEADERS.has(name))
+                        continue;
+                    if (name === 'set-cookie')
+                        continue;
+                    outgoingHeaders[key] = value;
+                }
+                const setCookies = upstream.headers.getSetCookie?.();
+                if (Array.isArray(setCookies) && setCookies.length > 0) {
+                    const normalizedSetCookies = shouldRewriteSetCookieForLocalDevHost(String(req.headers.host || '').trim())
+                        ? setCookies.map((cookie) => rewriteProxySetCookieForLocalHost(cookie))
+                        : setCookies;
+                    res.setHeader('Set-Cookie', normalizedSetCookies);
+                }
+                res.writeHead(upstream.status, outgoingHeaders);
+                const responseBuffer = Buffer.from(await upstream.arrayBuffer());
+                res.end(responseBuffer);
+            }
+            catch (error) {
+                const message = String(error?.message || '');
+                if (message.startsWith('PAYLOAD_TOO_LARGE:')) {
+                    const max = Number(message.split(':')[1] || maxPayloadBytes);
+                    res.writeHead(413, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `Payload too large (max ${max} bytes)` }));
+                    return;
+                }
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Cloud proxy request failed.' }));
+            }
+            return;
+        }
+        // 1. Try API routes first (with dynamic param matching)
+        const match = matchRoute(req.method || 'GET', url.pathname, routes);
+        if (match) {
+            let observedStatusCode = null;
+            const originalWriteHead = res.writeHead.bind(res);
+            res.writeHead = ((statusCode, ...args) => {
+                observedStatusCode = Number(statusCode);
+                return originalWriteHead(statusCode, ...args);
+            });
+            try {
+                req.headers['x-taskforce-runtime-mode'] = runtimeMode;
+                req.headers['x-taskforce-auth-required'] = String(authConfig.enabled && authConfig.requiredForApi);
+                res.req = req;
+                // Apply CORS headers + reject disallowed origins.
+                const cors = applyCorsHeaders(req, res, allowedOrigins);
+                if (!cors.allowed) {
+                    console.warn(`[Taskforce] CORS request rejected origin="${String(req.headers.origin || '')}" path="${url.pathname}" method="${req.method || 'GET'}"`);
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'CORS origin not allowed' }));
+                    return;
+                }
+                // Enforce request payload guard before route handlers parse bodies.
+                const contentLength = req.headers['content-length'];
+                if (typeof contentLength === 'string') {
+                    const contentLengthNumber = Number.parseInt(contentLength, 10);
+                    if (Number.isFinite(contentLengthNumber) && contentLengthNumber > maxPayloadBytes) {
+                        req.resume();
+                        res.writeHead(413, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: `Payload too large (max ${maxPayloadBytes} bytes)` }));
+                        return;
+                    }
+                }
+                const isAuthApiPath = url.pathname.startsWith('/api/taskforce/auth/');
+                const shouldApplyAuthRateLimit = shouldApplyAuthRateLimitForPath(url.pathname);
+                const accessForRateLimit = resolveRequestAccess(req, authConfig);
+                const isBillingWebhook = isBillingWebhookPath(url.pathname);
+                if (rateLimitEnabled && !isAuthApiPath) {
+                    const key = resolveRateLimitKey({
+                        req,
+                        pathname: url.pathname,
+                        method: req.method,
+                        authenticated: accessForRateLimit.authenticated,
+                        sessionId: accessForRateLimit.sessionId,
+                        userId: accessForRateLimit.userId
+                    });
+                    const rateLimitResult = isBillingWebhook
+                        ? webhookRateLimiter.check(key)
+                        : rateLimiter.check(key);
+                    if (isBillingWebhook) {
+                        applyPrefixedRateLimitHeaders(res, rateLimitResult, 'X-Webhook-RateLimit');
+                    }
+                    else {
+                        applyRateLimitHeaders(res, rateLimitResult);
+                    }
+                    if (!rateLimitResult.allowed) {
+                        res.writeHead(429, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Rate limit exceeded. Retry later.' }));
+                        return;
+                    }
+                }
+                if (isAuthApiPath) {
+                    const latestAuthRateSettings = resolveAuthRateLimitSettings();
+                    if (latestAuthRateSettings.enabled !== authRateLimitSettings.enabled
+                        || latestAuthRateSettings.maxRequests !== authRateLimitSettings.maxRequests
+                        || latestAuthRateSettings.windowMs !== authRateLimitSettings.windowMs) {
+                        authRateLimitSettings = latestAuthRateSettings;
+                        authRateLimiter = new InMemoryRateLimiter(authRateLimitSettings.maxRequests, authRateLimitSettings.windowMs);
+                        if (authRateLimitSettings.enabled) {
+                            console.log(`[Taskforce] Auth rate limit updated: ${authRateLimitSettings.maxRequests} req/${Math.ceil(authRateLimitSettings.windowMs / 1000)}s`);
+                        }
+                        else {
+                            console.log('[Taskforce] Auth rate limit updated: disabled');
+                        }
+                    }
+                }
+                if (authRateLimitSettings.enabled && shouldApplyAuthRateLimit) {
+                    const key = resolveRateLimitKey({
+                        req,
+                        pathname: url.pathname,
+                        method: req.method,
+                        authenticated: accessForRateLimit.authenticated,
+                        sessionId: accessForRateLimit.sessionId,
+                        userId: accessForRateLimit.userId
+                    });
+                    const authRateResult = authRateLimiter.check(key);
+                    applyPrefixedRateLimitHeaders(res, authRateResult, 'X-Auth-RateLimit');
+                    if (!authRateResult.allowed) {
+                        res.writeHead(429, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Too many auth attempts. Retry later.' }));
+                        return;
+                    }
+                }
+                const auth = isRequestAuthorized(req, authConfig);
+                if (!auth.allowed) {
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: auth.reason || 'Unauthorized' }));
+                    return;
+                }
+                const pathname = url.pathname;
+                const isMutation = (req.method === 'POST' || req.method === 'PATCH' || req.method === 'DELETE')
+                    && pathname.startsWith('/api/taskforce/')
+                    && !pathname.startsWith('/api/taskforce/auth/')
+                    && pathname !== '/api/taskforce/health';
+                let access = accessForRateLimit;
+                const isAuthRoute = pathname.startsWith('/api/taskforce/auth/');
+                if (access.authenticated) {
+                    const resolved = core.resolveUserAccess(access.userId, access.workspaceId, access.role);
+                    if (resolved) {
+                        const systemRole = core.getSystemRole(resolved.userId);
+                        access = {
+                            ...access,
+                            role: resolved.role,
+                            workspaceId: resolved.workspaceId,
+                            userId: resolved.userId,
+                            systemRole
+                        };
+                        if (resolved.disabled && !isAuthRoute) {
+                            res.writeHead(403, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'Forbidden: user account is disabled.' }));
+                            return;
+                        }
+                    }
+                }
+                req.headers['x-taskforce-role'] = access.role;
+                req.headers['x-taskforce-system-role'] = access.systemRole;
+                req.headers['x-taskforce-workspace-id'] = access.workspaceId;
+                req.headers['x-taskforce-user-id'] = access.userId;
+                if (isCollaborationPolicyEnabled() && isMutation && access.role === 'read-only') {
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Forbidden: read-only role cannot mutate data.' }));
+                    return;
+                }
+                await match.handler(req, res, match.params);
+            }
+            catch (error) {
+                console.error('[Taskforce] API error:', error);
+                const statusCode = Number.isFinite(Number(error?.statusCode))
+                    ? Math.max(400, Math.min(599, Number(error.statusCode)))
+                    : 500;
+                res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: error.message }));
+            }
+            finally {
+                res.writeHead = originalWriteHead;
+                const finalStatus = Number.isFinite(Number(observedStatusCode)) ? Number(observedStatusCode) : 200;
+                recordCollaborationRouteTelemetry(url.pathname, req.method || 'GET', finalStatus);
+            }
+            return;
+        }
+        // 2. Serve static files from dist/ui/
+        let filePath = url.pathname.replace(/^\/taskforce/, '');
+        if (filePath === '' || filePath === '/')
+            filePath = '/index.html';
+        const fullPath = distUiPath ? path.join(distUiPath, filePath) : '';
+        if (distUiPath && fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+            const ext = path.extname(fullPath);
+            res.writeHead(200, { 'Content-Type': MIME_TYPES[ext] || 'application/octet-stream' });
+            fs.createReadStream(fullPath).pipe(res);
+            return;
+        }
+        // 3. SPA fallback: serve index.html for client-side routing
+        const indexPath = distUiPath ? path.join(distUiPath, 'index.html') : '';
+        if (!url.pathname.startsWith('/api/') && distUiPath && fs.existsSync(indexPath)) {
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            fs.createReadStream(indexPath).pipe(res);
+            return;
+        }
+        // 4. 404 fallback (or missing UI diagnostics)
+        if (!url.pathname.startsWith('/api/') && !distUiPath) {
+            res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end(`Taskforce UI bundle not found.\nChecked:\n${uiResolution.candidates.map((p) => `- ${p}`).join('\n')}`);
+            return;
+        }
+        res.writeHead(404);
+        res.end('Not Found');
+    });
+    // WebSocket server at /Taskforce-ws path
+    const wss = new WebSocketServer({ server, path: '/taskforce-ws' });
+    const realtimeWsManager = createRealtimeSyncWsManager(core, authConfig);
+    const offRealtimeMutation = core.onRealtimeMutation((event) => {
+        realtimeWsManager.broadcastMutation(event);
+    });
+    // Prevent WebSocketServer from crashing the process on server errors (like EADDRINUSE)
+    wss.on('error', (err) => {
+        // Only log if it's not a bind error (which we handle in CLI)
+        if (err.code !== 'EADDRINUSE') {
+            console.error('[Taskforce] WebSocket error:', err);
+        }
+    });
+    server.once('listening', () => {
+        let purgeTimer = null;
+        let integrityScheduleTimer = null;
+        const appendDocumentPurgeHistory = (summary) => {
+            const settings = core.getGlobalSettings();
+            const existing = Array.isArray(settings?.documentPurgeHistory)
+                ? settings.documentPurgeHistory
+                : [];
+            const history = [{
+                    id: `purge-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                    ranAt: new Date().toISOString(),
+                    actorUserId: 'system',
+                    actorRole: 'system',
+                    workspaceId: 'system',
+                    summary
+                }, ...existing].slice(0, STORAGE_INTEGRITY_HISTORY_LIMIT);
+            core.updateGlobalSettings({
+                documentPurgeHistory: history
+            });
+        };
+        const runDocumentPurge = async () => {
+            try {
+                const { basePath, taskDataDir } = core.getPaths();
+                const summary = await purgeExpiredDocuments({
+                    basePath,
+                    taskDataDir,
+                    objectStorage: resolveEffectiveObjectStorage(),
+                    assetStore: taskAssetStore
+                });
+                appendDocumentPurgeHistory(summary);
+                if (summary.total > 0) {
+                    console.log(`[Taskforce] Document purge run: total=${summary.total} purged=${summary.purged} failed=${summary.failed}`);
+                }
+            }
+            catch (error) {
+                console.warn(`[Taskforce] Document purge failed: ${String(error?.message || error)}`);
+            }
+        };
+        if (purgeEnabled) {
+            void runDocumentPurge();
+            purgeTimer = setInterval(() => {
+                void runDocumentPurge();
+            }, purgeIntervalMinutes * 60_000);
+        }
+        const appendStorageIntegrityHistory = (item) => {
+            const settings = core.getGlobalSettings();
+            const existing = Array.isArray(settings?.storageIntegrityHistory)
+                ? settings.storageIntegrityHistory
+                : [];
+            const history = [item, ...existing].slice(0, STORAGE_INTEGRITY_HISTORY_LIMIT);
+            core.updateGlobalSettings({
+                storageIntegrityHistory: history
+            });
+        };
+        const runScheduledIntegrityScanIfDue = async () => {
+            try {
+                const globalSettings = core.getGlobalSettings();
+                const schedule = resolveStorageIntegrityScheduleSettings(globalSettings);
+                const now = new Date();
+                if (!shouldRunStorageIntegritySchedule(schedule, now))
+                    return;
+                const { basePath } = core.getPaths();
+                const result = await scanDocumentIntegrity({
+                    basePath,
+                    objectStorage: resolveEffectiveObjectStorage(),
+                    verifyHash: schedule.verifyHash,
+                    includeDeleted: schedule.includeDeleted,
+                    requireMirror: schedule.requireMirror,
+                    limit: schedule.limit,
+                    assetStore: taskAssetStore
+                });
+                core.updateGlobalSettings({
+                    storageIntegritySchedule: {
+                        ...schedule,
+                        lastRunAt: now.toISOString()
+                    }
+                });
+                appendStorageIntegrityHistory({
+                    id: `integrity-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                    ranAt: now.toISOString(),
+                    actorUserId: 'system',
+                    actorRole: 'system',
+                    workspaceId: 'system',
+                    options: {
+                        verifyHash: schedule.verifyHash,
+                        includeDeleted: schedule.includeDeleted,
+                        requireMirror: schedule.requireMirror,
+                        limit: schedule.limit
+                    },
+                    summary: result.summary
+                });
+                console.log(`[Taskforce] Scheduled integrity scan: checked=${result.summary.totalChecked} issues=${result.summary.totalIssues}`);
+            }
+            catch (error) {
+                console.warn(`[Taskforce] Scheduled integrity scan failed: ${String(error?.message || error)}`);
+            }
+        };
+        integrityScheduleTimer = setInterval(() => {
+            void runScheduledIntegrityScanIfDue();
+        }, integritySchedulePollMinutes * 60_000);
+        void runScheduledIntegrityScanIfDue();
+        wss.on('connection', (ws, req) => {
+            realtimeWsManager.handleConnection(ws, req);
+        });
+        // Use chokidar for cross-platform file watching (works on Linux)
+        const watcher = chokidar.watch(basePath, {
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 100 }
+        });
+        watcher.on('change', (filepath) => {
+            if (filepath.endsWith('.json') || filepath.endsWith('.db') || filepath.endsWith('.db-wal')) {
+                console.log(`[Taskforce] File changed: ${path.basename(filepath)}`);
+                realtimeWsManager.broadcastTaskforceUpdate();
+            }
+        });
+        // Graceful shutdown
+        const shutdown = () => {
+            console.log('\n[Taskforce] Shutting down...');
+            if (purgeTimer) {
+                clearInterval(purgeTimer);
+                purgeTimer = null;
+            }
+            if (integrityScheduleTimer) {
+                clearInterval(integrityScheduleTimer);
+                integrityScheduleTimer = null;
+            }
+            watcher.close();
+            offRealtimeMutation();
+            wss.clients.forEach(client => client.close());
+            wss.close();
+            server.close();
+            process.exit(0);
+        };
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+    });
+    return server;
+}