@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/server/index.d.ts

@@ -11,6 +11,13 @@ export interface StandaloneServerOptions {
     projectRoot: string;
     port: number;
 }
+export type HttpServerTimeoutSettings = {
+    keepAliveTimeoutMs: number;
+    headersTimeoutMs: number;
+    requestTimeoutMs: number;
+};
+export declare function resolveHttpServerTimeoutSettings(env?: NodeJS.ProcessEnv): HttpServerTimeoutSettings;
+export declare function configureHttpServerTimeouts(server: Pick<http.Server, 'keepAliveTimeout' | 'headersTimeout' | 'requestTimeout'>, env?: NodeJS.ProcessEnv): HttpServerTimeoutSettings;
 export declare const TASKFORCE_PROXY_ORIGIN_HOST_HEADER = "x-taskforce-origin-host";
 export declare const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = "x-taskforce-origin-proto";
 export declare const TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER = "x-taskforce-origin-base-url";
@@ -18,10 +25,15 @@ export declare const TASKFORCE_PROXY_ORIGIN_RUNTIME_HEADER = "x-taskforce-origin
 export declare const TASKFORCE_PROXY_CLOUD_ENVIRONMENT_HEADER = "x-taskforce-cloud-environment";
 interface AuthorizedRequestAccess extends RequestAccessContext {
     disabled?: boolean;
+    accountDisabled?: boolean;
+    workspaceDisabled?: boolean;
 }
+export declare function isWorkspaceAccessRecoveryRoute(pathname: string): boolean;
+export declare function resolveDisabledAccessError(access: Pick<AuthorizedRequestAccess, 'disabled' | 'accountDisabled' | 'workspaceDisabled'>, pathname: string): string | null;
 export declare function shouldProxyCloudPath(pathname: string): boolean;
 export declare function resolveCloudProxyUpstreamBaseUrl(req: http.IncomingMessage, fallbackBaseUrl: string): string;
 export declare function resolveAuthorizedWorkspaceAccess(core: Pick<TaskforceCore, 'resolveUserAccess' | 'getSystemRole'>, access: AuthorizedRequestAccess, requestedWorkspaceId: string): AuthorizedRequestAccess;
+export declare function shouldApplyReadOnlyMutationGuard(methodRaw: string | undefined, pathname: string): boolean;
 export declare function resolveEffectiveRequestUserId(accessUserId: string, explicitUserId: string): string;
 export declare function resolveMaxPayloadBytesForPath(pathname: string, defaultMaxBytes: number): number;
 export declare function shouldRewriteSetCookieForLocalDevHost(hostHeader: string | undefined): boolean;

package/dist/server/index.js

@@ -84,11 +84,85 @@ const CORS_RESPONSE_HEADERS = new Set([
     'access-control-max-age',
     'vary'
 ]);
+const REFRESH_DIAGNOSTIC_PATH_PREFIXES = [
+    '/api/taskforce/auth/session',
+    '/api/taskforce/config',
+    '/api/taskforce/tasks',
+    '/api/taskforce/archive',
+    '/api/taskforce/workspaces',
+    '/api/taskforce/workspace/assignee-options',
+    '/api/taskforce/auth/workspace-members',
+    '/api/taskforce/taxonomy-state',
+    '/api/taskforce/categories',
+    '/api/taskforce/types',
+    '/api/taskforce/priorities',
+    '/api/taskforce/taxonomies',
+    '/api/taskforce/initiative-templates',
+    '/api/taskforce/workflow-templates',
+    '/api/taskforce/workflow-editor/overrides',
+    '/api/taskforce/environments',
+    '/api/taskforce/sync/'
+];
+const REFRESH_DIAGNOSTIC_DURATION_MS = 100;
+const DEFAULT_HTTP_KEEP_ALIVE_TIMEOUT_MS = 65_000;
+const DEFAULT_HTTP_HEADERS_TIMEOUT_MS = 70_000;
+const DEFAULT_HTTP_REQUEST_TIMEOUT_MS = 120_000;
+export function resolveHttpServerTimeoutSettings(env = process.env) {
+    const keepAliveTimeoutMs = readPositiveInteger(env.TASKFORCE_HTTP_KEEP_ALIVE_TIMEOUT_MS, DEFAULT_HTTP_KEEP_ALIVE_TIMEOUT_MS);
+    const configuredHeadersTimeoutMs = readPositiveInteger(env.TASKFORCE_HTTP_HEADERS_TIMEOUT_MS, DEFAULT_HTTP_HEADERS_TIMEOUT_MS);
+    const headersTimeoutMs = Math.max(configuredHeadersTimeoutMs, keepAliveTimeoutMs + 5_000);
+    const requestTimeoutMs = readPositiveInteger(env.TASKFORCE_HTTP_REQUEST_TIMEOUT_MS, DEFAULT_HTTP_REQUEST_TIMEOUT_MS);
+    return {
+        keepAliveTimeoutMs,
+        headersTimeoutMs,
+        requestTimeoutMs
+    };
+}
+export function configureHttpServerTimeouts(server, env = process.env) {
+    const settings = resolveHttpServerTimeoutSettings(env);
+    server.keepAliveTimeout = settings.keepAliveTimeoutMs;
+    server.headersTimeout = settings.headersTimeoutMs;
+    server.requestTimeout = settings.requestTimeoutMs;
+    return settings;
+}
 export const TASKFORCE_PROXY_ORIGIN_HOST_HEADER = 'x-taskforce-origin-host';
 export const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = 'x-taskforce-origin-proto';
 export const TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER = 'x-taskforce-origin-base-url';
 export const TASKFORCE_PROXY_ORIGIN_RUNTIME_HEADER = 'x-taskforce-origin-runtime';
 export const TASKFORCE_PROXY_CLOUD_ENVIRONMENT_HEADER = 'x-taskforce-cloud-environment';
+export function isWorkspaceAccessRecoveryRoute(pathname) {
+    return pathname === '/api/taskforce/workspaces'
+        || pathname === '/api/taskforce/session/workspace';
+}
+export function resolveDisabledAccessError(access, pathname) {
+    if (pathname.startsWith('/api/taskforce/auth/'))
+        return null;
+    if (access.accountDisabled ?? access.disabled) {
+        return 'Forbidden: user account is disabled.';
+    }
+    if (access.workspaceDisabled && !isWorkspaceAccessRecoveryRoute(pathname)) {
+        return 'Forbidden: workspace access is not active for this user.';
+    }
+    return null;
+}
+function shouldLogRefreshDiagnostic(pathname) {
+    return REFRESH_DIAGNOSTIC_PATH_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(prefix));
+}
+function getRequestTimingNow() {
+    return Date.now();
+}
+function isCloudOwnedUserAvatarContextPath(pathname) {
+    const prefix = '/api/taskforce/context/';
+    if (!pathname.startsWith(prefix))
+        return false;
+    try {
+        const decodedPath = decodeURIComponent(pathname.slice(prefix.length)).replace(/\\/g, '/');
+        return /^users\/[^/]+\/profile\/avatar\/[^/]+$/i.test(decodedPath);
+    }
+    catch {
+        return false;
+    }
+}
 export function shouldProxyCloudPath(pathname) {
     if (!pathname)
         return false;
@@ -114,6 +188,7 @@ export function shouldProxyCloudPath(pathname) {
         || pathname.startsWith('/api/taskforce/admin/')
         || pathname.startsWith('/api/taskforce/billing/')
         || pathname.startsWith('/api/taskforce/auth/')
+        || isCloudOwnedUserAvatarContextPath(pathname)
         || pathname.startsWith('/api/taskforce/settings/mcp/')
         || pathname.startsWith('/api/platform/')
         || pathname.startsWith('/api/taskforce/sync/');
@@ -142,11 +217,27 @@ export function resolveAuthorizedWorkspaceAccess(core, access, requestedWorkspac
             workspaceId: resolved.workspaceId,
             userId: resolved.userId,
             systemRole: core.getSystemRole(resolved.userId),
-            disabled: resolved.disabled
+            disabled: resolved.disabled,
+            accountDisabled: resolved.accountDisabled ?? resolved.disabled,
+            workspaceDisabled: resolved.workspaceDisabled ?? false
         };
     }
     return access;
 }
+export function shouldApplyReadOnlyMutationGuard(methodRaw, pathname) {
+    const method = String(methodRaw || 'GET').toUpperCase();
+    if (method !== 'POST' && method !== 'PATCH' && method !== 'DELETE')
+        return false;
+    if (!pathname.startsWith('/api/taskforce/'))
+        return false;
+    if (pathname.startsWith('/api/taskforce/auth/'))
+        return false;
+    if (pathname === '/api/taskforce/health')
+        return false;
+    if (method === 'POST' && pathname === '/api/taskforce/session/workspace')
+        return false;
+    return true;
+}
 export function resolveEffectiveRequestUserId(accessUserId, explicitUserId) {
     const normalizedAccessUserId = String(accessUserId || '').trim();
     if (normalizedAccessUserId && normalizedAccessUserId !== 'anonymous') {
@@ -163,6 +254,10 @@ export function resolveMaxPayloadBytesForPath(pathname, defaultMaxBytes) {
         // Sync routes (especially applying local changes) often include large binary attachments
         return Math.max(defaultMaxBytes, 50 * 1024 * 1024);
     }
+    if (pathname === '/api/taskforce/ui-state') {
+        // Workspace-sync UI state can carry large baselines; keep the global guard aligned with its route parser.
+        return Math.max(defaultMaxBytes, 50 * 1024 * 1024);
+    }
     return defaultMaxBytes;
 }
 export function shouldRewriteSetCookieForLocalDevHost(hostHeader) {
@@ -259,6 +354,7 @@ export function shouldApplyAuthRateLimitForPath(pathname) {
     const normalizedPath = String(pathname || '').trim();
     return normalizedPath.startsWith('/api/taskforce/auth/')
         && normalizedPath !== '/api/taskforce/auth/session'
+        && normalizedPath !== '/api/taskforce/auth/providers'
         && normalizedPath !== '/api/taskforce/auth/runtime-config'
         && normalizedPath !== '/api/taskforce/auth/admin-session';
 }
@@ -458,6 +554,17 @@ export function createStandaloneServer(options) {
             statusCode
         }, counterKeys);
     };
+    const logRefreshDiagnostic = (input) => {
+        const { pathname, method, statusCode, durationMs, req } = input;
+        if (!shouldLogRefreshDiagnostic(pathname))
+            return;
+        if (durationMs < REFRESH_DIAGNOSTIC_DURATION_MS && statusCode < 400)
+            return;
+        const requestId = String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || '-';
+        const workspaceId = String(req.headers['x-taskforce-workspace-id'] || '').trim() || '-';
+        const userId = String(req.headers['x-taskforce-user-id'] || '').trim() || '-';
+        console.info(`[Taskforce RefreshDiag] method=${method} path=${pathname} status=${statusCode} durationMs=${durationMs} requestId=${requestId} workspaceId=${workspaceId} userId=${userId}`);
+    };
     // 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/
@@ -514,6 +621,7 @@ export function createStandaloneServer(options) {
     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 requestStartedAt = getRequestTimingNow();
         if (!distUiPath) {
             uiResolution = resolveStaticUiPath();
             distUiPath = uiResolution.uiPath;
@@ -568,11 +676,12 @@ export function createStandaloneServer(options) {
                 const hasBody = method !== 'GET' && method !== 'HEAD';
                 const requestMaxPayload = resolveMaxPayloadBytesForPath(url.pathname, maxPayloadBytes);
                 const body = hasBody ? await readRequestBody(req, requestMaxPayload) : undefined;
+                const shouldStreamCloudAvatar = method === 'GET' && isCloudOwnedUserAvatarContextPath(url.pathname);
                 const upstream = await fetch(upstreamUrl, {
                     method,
                     headers,
                     body: body && body.length > 0 ? new Uint8Array(body) : undefined,
-                    redirect: 'manual'
+                    redirect: shouldStreamCloudAvatar ? 'follow' : 'manual'
                 });
                 const outgoingHeaders = {};
                 for (const [key, value] of upstream.headers.entries()) {
@@ -714,19 +823,16 @@ export function createStandaloneServer(options) {
                     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';
+                const isMutation = shouldApplyReadOnlyMutationGuard(req.method, pathname);
                 let access = accessForRateLimit;
-                const isAuthRoute = pathname.startsWith('/api/taskforce/auth/');
                 if (access.authenticated) {
                     access = resolveAuthorizedWorkspaceAccess(core, access, Array.isArray(req.headers['x-taskforce-workspace-id'])
                         ? String(req.headers['x-taskforce-workspace-id'][0] || '')
                         : String(req.headers['x-taskforce-workspace-id'] || ''));
-                    if (access.disabled && !isAuthRoute) {
+                    const disabledAccessError = resolveDisabledAccessError(access, pathname);
+                    if (disabledAccessError) {
                         res.writeHead(403, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ error: 'Forbidden: user account is disabled.' }));
+                        res.end(JSON.stringify({ error: disabledAccessError }));
                         return;
                     }
                 }
@@ -756,6 +862,13 @@ export function createStandaloneServer(options) {
                 res.writeHead = originalWriteHead;
                 const finalStatus = Number.isFinite(Number(observedStatusCode)) ? Number(observedStatusCode) : 200;
                 recordCollaborationRouteTelemetry(url.pathname, req.method || 'GET', finalStatus);
+                logRefreshDiagnostic({
+                    pathname: url.pathname,
+                    method: String(req.method || 'GET').toUpperCase(),
+                    statusCode: finalStatus,
+                    durationMs: Math.max(0, Math.round(getRequestTimingNow() - requestStartedAt)),
+                    req
+                });
             }
             return;
         }
@@ -789,6 +902,8 @@ export function createStandaloneServer(options) {
         res.writeHead(404);
         res.end('Not Found');
     });
+    const timeoutSettings = configureHttpServerTimeouts(server);
+    console.log(`[Taskforce] HTTP timeouts: keepAlive=${timeoutSettings.keepAliveTimeoutMs}ms headers=${timeoutSettings.headersTimeoutMs}ms request=${timeoutSettings.requestTimeoutMs}ms`);
     // WebSocket server at /Taskforce-ws path
     const wss = new WebSocketServer({ server, path: '/taskforce-ws' });
     const realtimeWsManager = createRealtimeSyncWsManager(core, authConfig);

package/dist/server/index.rateLimit.test.js

@@ -7,6 +7,9 @@ describe('shouldApplyAuthRateLimitForPath', () => {
     it('excludes auth session endpoint', () => {
         expect(shouldApplyAuthRateLimitForPath('/api/taskforce/auth/session')).toBe(false);
     });
+    it('excludes auth providers metadata endpoint', () => {
+        expect(shouldApplyAuthRateLimitForPath('/api/taskforce/auth/providers')).toBe(false);
+    });
     it('excludes runtime config bootstrap endpoint', () => {
         expect(shouldApplyAuthRateLimitForPath('/api/taskforce/auth/runtime-config')).toBe(false);
     });

package/dist/server/index.test.js

@@ -1,6 +1,42 @@
 import { describe, expect, it, vi } from 'vitest';
-import { ensureBillingWebhookAuthExclusion, ensurePublicSiteConfigAuthExclusion, isBillingWebhookPath, rewriteProxySetCookieForLocalHost, resolveEffectiveRequestUserId, resolveAuthorizedWorkspaceAccess, shouldRewriteProxySetCookieDomain, shouldApplyAuthRateLimitForPath, shouldProxyCloudPath, writeJsonErrorIfPossible } from './index.js';
+import { ensureBillingWebhookAuthExclusion, ensurePublicSiteConfigAuthExclusion, configureHttpServerTimeouts, isBillingWebhookPath, rewriteProxySetCookieForLocalHost, resolveHttpServerTimeoutSettings, resolveEffectiveRequestUserId, resolveAuthorizedWorkspaceAccess, resolveDisabledAccessError, resolveMaxPayloadBytesForPath, shouldApplyReadOnlyMutationGuard, shouldRewriteProxySetCookieDomain, shouldApplyAuthRateLimitForPath, shouldProxyCloudPath, writeJsonErrorIfPossible } from './index.js';
 describe('server index helper policies', () => {
+    it('uses proxy-friendly HTTP server timeouts by default', () => {
+        const settings = resolveHttpServerTimeoutSettings({});
+        expect(settings.keepAliveTimeoutMs).toBe(65_000);
+        expect(settings.headersTimeoutMs).toBe(70_000);
+        expect(settings.requestTimeoutMs).toBe(120_000);
+    });
+    it('keeps headers timeout above keep-alive timeout for reverse proxies', () => {
+        const settings = resolveHttpServerTimeoutSettings({
+            TASKFORCE_HTTP_KEEP_ALIVE_TIMEOUT_MS: '80000',
+            TASKFORCE_HTTP_HEADERS_TIMEOUT_MS: '1000',
+            TASKFORCE_HTTP_REQUEST_TIMEOUT_MS: '150000'
+        });
+        expect(settings.keepAliveTimeoutMs).toBe(80_000);
+        expect(settings.headersTimeoutMs).toBe(85_000);
+        expect(settings.requestTimeoutMs).toBe(150_000);
+    });
+    it('applies resolved HTTP server timeouts to the Node server', () => {
+        const server = {
+            keepAliveTimeout: 0,
+            headersTimeout: 0,
+            requestTimeout: 0
+        };
+        const settings = configureHttpServerTimeouts(server, {
+            TASKFORCE_HTTP_KEEP_ALIVE_TIMEOUT_MS: '61000',
+            TASKFORCE_HTTP_HEADERS_TIMEOUT_MS: '66000',
+            TASKFORCE_HTTP_REQUEST_TIMEOUT_MS: '90000'
+        });
+        expect(settings).toEqual({
+            keepAliveTimeoutMs: 61_000,
+            headersTimeoutMs: 66_000,
+            requestTimeoutMs: 90_000
+        });
+        expect(server.keepAliveTimeout).toBe(61_000);
+        expect(server.headersTimeout).toBe(66_000);
+        expect(server.requestTimeout).toBe(90_000);
+    });
     it('adds webhook path to auth exclusions without duplicates', () => {
         const base = ['/api/taskforce/health', '/api/taskforce/auth'];
         const next = ensureBillingWebhookAuthExclusion(base);
@@ -24,6 +60,11 @@ describe('server index helper policies', () => {
         expect(shouldApplyAuthRateLimitForPath('/api/taskforce/auth/session')).toBe(false);
         expect(shouldApplyAuthRateLimitForPath('/api/taskforce/billing/webhook')).toBe(false);
     });
+    it('allows workspace sync-sized ui-state payloads through the global guard', () => {
+        expect(resolveMaxPayloadBytesForPath('/api/taskforce/ui-state', 1_048_576)).toBe(50 * 1024 * 1024);
+        expect(resolveMaxPayloadBytesForPath('/api/taskforce/sync/workspace/push', 1_048_576)).toBe(50 * 1024 * 1024);
+        expect(resolveMaxPayloadBytesForPath('/api/taskforce/task', 1_048_576)).toBe(1_048_576);
+    });
     it('writes a json error when headers are still available', () => {
         let headersSent = false;
         let writableEnded = false;
@@ -82,6 +123,12 @@ describe('shouldProxyCloudPath', () => {
         expect(shouldProxyCloudPath('/api/taskforce/sync/workspace/pull')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/sync/workspace/push')).toBe(true);
     });
+    it('proxies cloud-owned user avatar context paths only', () => {
+        expect(shouldProxyCloudPath('/api/taskforce/context/users%2Fuser-1%2Fprofile%2Favatar%2Favatar.webp')).toBe(true);
+        expect(shouldProxyCloudPath('/api/taskforce/context/users/user-1/profile/avatar/avatar.webp')).toBe(true);
+        expect(shouldProxyCloudPath('/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fasset.png')).toBe(false);
+        expect(shouldProxyCloudPath('/api/taskforce/context/users%2Fuser-1%2Fexports%2Favatar.webp')).toBe(false);
+    });
     it('proxies admin, billing, and auth routes', () => {
         expect(shouldProxyCloudPath('/api/taskforce/admin/users')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/billing/plans')).toBe(true);
@@ -91,6 +138,11 @@ describe('shouldProxyCloudPath', () => {
         expect(shouldProxyCloudPath('/api/taskforce/public/site-config')).toBe(true);
         expect(shouldProxyCloudPath('/api/taskforce/public/site-config-script')).toBe(true);
     });
+    it('keeps AI profile workspace mutations local so workspace sync owns replication', () => {
+        expect(shouldProxyCloudPath('/api/taskforce/workspace/ai-profiles/avatar')).toBe(false);
+        expect(shouldProxyCloudPath('/api/taskforce/workspace/ai-profiles/archive')).toBe(false);
+        expect(shouldProxyCloudPath('/api/taskforce/workspace/ai-profiles/merge')).toBe(false);
+    });
 });
 describe('proxy cookie helpers', () => {
     it('rewrites mismatched cookie domains for non-loopback local hosts', () => {
@@ -126,7 +178,8 @@ describe('resolveAuthorizedWorkspaceAccess', () => {
             userId: 'user-1',
             workspaceId: 'workspace-personal',
             role: 'member',
-            systemRole: 'user'
+            systemRole: 'user',
+            identityId: null
         }, 'workspace-team');
         expect(core.resolveUserAccess).toHaveBeenCalledWith('user-1', 'workspace-team', 'member');
         expect(next.workspaceId).toBe('workspace-team');
@@ -154,12 +207,67 @@ describe('resolveAuthorizedWorkspaceAccess', () => {
             userId: 'user-1',
             workspaceId: 'workspace-personal',
             role: 'member',
-            systemRole: 'user'
+            systemRole: 'user',
+            identityId: null
         }, 'workspace-team');
         expect(core.resolveUserAccess).toHaveBeenNthCalledWith(1, 'user-1', 'workspace-team', 'member');
         expect(core.resolveUserAccess).toHaveBeenNthCalledWith(2, 'user-1', 'workspace-personal', 'member');
         expect(next.workspaceId).toBe('workspace-personal');
     });
+    it('preserves account and workspace disabled scopes separately', () => {
+        const core = {
+            resolveUserAccess: vi.fn((userId, workspaceId, role) => ({
+                userId,
+                workspaceId,
+                role,
+                permissionMode: 'read-write',
+                disabled: true,
+                accountDisabled: false,
+                workspaceDisabled: true,
+                betaAccess: true
+            })),
+            getSystemRole: vi.fn(() => 'user')
+        };
+        const next = resolveAuthorizedWorkspaceAccess(core, {
+            authenticated: true,
+            sessionId: 'session-1',
+            userId: 'user-1',
+            workspaceId: 'workspace-shared',
+            role: 'member',
+            systemRole: 'user',
+            identityId: null
+        }, 'workspace-shared');
+        expect(next.disabled).toBe(true);
+        expect(next.accountDisabled).toBe(false);
+        expect(next.workspaceDisabled).toBe(true);
+    });
+});
+describe('resolveDisabledAccessError', () => {
+    it('blocks globally disabled accounts outside auth routes', () => {
+        expect(resolveDisabledAccessError({ disabled: true, accountDisabled: true }, '/api/taskforce/workspaces')).toBe('Forbidden: user account is disabled.');
+        expect(resolveDisabledAccessError({ disabled: true, accountDisabled: true }, '/api/taskforce/auth/session')).toBeNull();
+    });
+    it('allows workspace-disabled sessions to reach recovery routes only', () => {
+        const access = { disabled: true, accountDisabled: false, workspaceDisabled: true };
+        expect(resolveDisabledAccessError(access, '/api/taskforce/workspaces')).toBeNull();
+        expect(resolveDisabledAccessError(access, '/api/taskforce/session/workspace')).toBeNull();
+        expect(resolveDisabledAccessError(access, '/api/taskforce/tasks')).toBe('Forbidden: workspace access is not active for this user.');
+    });
+});
+describe('shouldApplyReadOnlyMutationGuard', () => {
+    it('guards ordinary Taskforce mutations', () => {
+        expect(shouldApplyReadOnlyMutationGuard('POST', '/api/taskforce/tasks')).toBe(true);
+        expect(shouldApplyReadOnlyMutationGuard('PATCH', '/api/taskforce/task/task-1')).toBe(true);
+        expect(shouldApplyReadOnlyMutationGuard('DELETE', '/api/taskforce/task/task-1')).toBe(true);
+    });
+    it('allows session workspace switching through route-level access validation', () => {
+        expect(shouldApplyReadOnlyMutationGuard('POST', '/api/taskforce/session/workspace')).toBe(false);
+    });
+    it('does not guard non-mutations, auth routes, or health checks', () => {
+        expect(shouldApplyReadOnlyMutationGuard('GET', '/api/taskforce/tasks')).toBe(false);
+        expect(shouldApplyReadOnlyMutationGuard('POST', '/api/taskforce/auth/login')).toBe(false);
+        expect(shouldApplyReadOnlyMutationGuard('POST', '/api/taskforce/health')).toBe(false);
+    });
 });
 describe('resolveEffectiveRequestUserId', () => {
     it('prefers the authenticated access user when present', () => {

package/dist/server/routes/admin.d.ts

@@ -7,6 +7,7 @@
  *
  * Routes registered here:
  *   GET/POST  /api/platform/plans
+ *   GET       /api/platform/onboarding-plan-options
  *   GET/POST  /api/platform/plans/:planId/versions
  *   GET       /api/platform/features
  *   GET/PATCH /api/platform/plans/:planId/versions/:versionId/features
@@ -23,6 +24,8 @@
  *   GET/POST  /api/taskforce/admin/email-settings
  *   GET       /api/taskforce/admin/email-settings/health
  *   POST      /api/taskforce/admin/email-settings/test
+ *   GET/POST  /api/taskforce/admin/auth-provider-settings
+ *   GET       /api/taskforce/admin/auth-provider-settings/health
  *   GET/POST  /api/taskforce/admin/system-settings
  *   GET/POST  /api/taskforce/admin/object-storage-settings
  *   GET       /api/taskforce/admin/object-storage-telemetry