@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/server/routes/admin.js

@@ -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
@@ -50,9 +53,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { TaskforceRuleError } from '../../core/Taskforce.js';
-import { parseJsonBody } from '../routes.js';
+import { escapeHtml, parseFormBody, parseJsonBody } from './primitives.js';
 import { resolveRequestAccess } from '../auth.js';
-import { resolveEffectiveEmailConfig, sendEmail } from '../email.js';
+import { sendEmail } from '../email.js';
 import { WorkspaceAssetStore } from '../../storage/workspaceAssetStore.js';
 import { scanDocumentIntegrity } from '../../storage/documentIntegrity.js';
 import { normalizeStorageIntegrityScheduleSettings, resolveStorageIntegrityScheduleSettings, } from '../../storage/integritySchedule.js';
@@ -64,67 +67,19 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { randomUUID } from 'crypto';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
-import { getTaskforceCloudEnvironmentConfig, resolveTaskforceCloudEnvironmentFromBaseUrl } from '../../config/cloudEnvironment.js';
+import { getTaskforceCloudEnvironmentConfig, resolveTaskforceCloudEnvironmentFromBaseUrl, resolveTaskforceMcpBaseUrlFromBaseUrl } from '../../config/cloudEnvironment.js';
 import { buildCloudMcpRuntimeAuth, resolveErrorStatusCode } from './shared.js';
+import { buildAuthBehavior, buildSiteBehavior, getRouteEmailConfig, resolvePublicAuthBaseUrl, resolveRuntimeConfigBaseUrl, } from './authSupport.js';
 import { applyWorkspaceRepair, scanWorkspaceRepair } from '../../sync/workspaceRepair.js';
+import { testMintAppleClientSecret } from '../auth/providers/appleClientSecret.js';
 // === SECTION: Registration ===
 export function registerAdminRoutes(deps) {
-    const { addRoute, core, context, requestWorkspaceId, requestUserId, requestRole, requestHeader, requestRuntimeMode, ensureAppAccess, ensureAdminRole, ensureCloudPlanData, requireCloudRuntime, resolveAuthenticatedUserId, resolveAdminRequestActor, auditAdminAction, resolveEffectiveObjectStorageConfig, getObjectStorageClient, taskAssetStore, normalizeDocumentPathInput, ensureWithinDir, getAssetMetadata, markAssetDeleted, clearAssetDeleted, removeAssetMetadata, getStorageTelemetry, appendStorageTelemetry, getStorageIntegrityHistory, appendStorageIntegrityHistory, getDocumentPurgeHistory, appendDocumentPurgeHistory, getCollaborationTelemetry, isCollaborationPolicyEnabled, resolveRuntimeConfigBaseUrl, resolvePublicAuthBaseUrl, parseFormBody, escapeHtml, normalizeMcpOauthScopeString, MCP_TOKEN_SCOPE_VALUES, MCP_CLOUD_TOOL_SCOPE_REQUIREMENTS, MCP_WRITE_RATE_LIMIT_ENABLED, MCP_WRITE_RATE_LIMIT_ACTOR_MAX_REQUESTS, MCP_WRITE_RATE_LIMIT_WORKSPACE_MAX_REQUESTS, MCP_WRITE_RATE_LIMIT_WINDOW_MS, } = deps;
+    const { addRoute, core, context, requestWorkspaceId, requestUserId, requestRole, requestHeader, requestRuntimeMode, ensureAppAccess, ensureAdminRole, ensureCloudPlanData, requireCloudRuntime, resolveAuthenticatedUserId, resolveAdminRequestActor, auditAdminAction, resolveEffectiveObjectStorageConfig, getObjectStorageClient, taskAssetStore, normalizeDocumentPathInput, ensureWithinDir, getAssetMetadata, markAssetDeleted, clearAssetDeleted, removeAssetMetadata, getStorageTelemetry, appendStorageTelemetry, getStorageIntegrityHistory, appendStorageIntegrityHistory, getDocumentPurgeHistory, appendDocumentPurgeHistory, getCollaborationTelemetry, isCollaborationPolicyEnabled, normalizeMcpOauthScopeString, MCP_TOKEN_SCOPE_VALUES, MCP_CLOUD_TOOL_SCOPE_REQUIREMENTS, MCP_WRITE_RATE_LIMIT_ENABLED, MCP_WRITE_RATE_LIMIT_ACTOR_MAX_REQUESTS, MCP_WRITE_RATE_LIMIT_WORKSPACE_MAX_REQUESTS, MCP_WRITE_RATE_LIMIT_WINDOW_MS, } = deps;
     const baseVirusScanConfig = resolveVirusScanConfigFromEnv(process.env);
     const workspaceAssetStore = typeof core.getDatabaseAdapter === 'function' && typeof core.getTenantId === 'function'
         ? new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId())
         : null;
     // === SECTION: Email helpers ===
-    const getEmailConfig = () => {
-        if (context.authConfig?.runtimeMode !== 'cloud') {
-            return resolveEffectiveEmailConfig(process.env, { provider: 'console' });
-        }
-        const globalSettings = core.getGlobalSettings();
-        return resolveEffectiveEmailConfig(process.env, globalSettings.email || null);
-    };
-    const resolveBooleanSetting = (value, fallback) => {
-        if (typeof value === 'boolean')
-            return value;
-        if (typeof value === 'number')
-            return value !== 0;
-        const normalized = String(value || '').trim().toLowerCase();
-        if (!normalized)
-            return fallback;
-        if (['1', 'true', 'yes', 'on'].includes(normalized))
-            return true;
-        if (['0', 'false', 'no', 'off'].includes(normalized))
-            return false;
-        return fallback;
-    };
-    const getAuthBehavior = () => {
-        const globalSettings = core.getGlobalSettings();
-        const authSettings = globalSettings.auth || {};
-        const authRateLimitMaxRequestsRaw = Number(authSettings.authRateLimitMaxRequests);
-        const authRateLimitWindowMsRaw = Number(authSettings.authRateLimitWindowMs);
-        const onboardingPolicy = core.getOnboardingPolicy();
-        return {
-            allowSelfRegistration: resolveBooleanSetting(authSettings.allowSelfRegistration, true),
-            requireVerifiedEmail: resolveBooleanSetting(authSettings.requireVerifiedEmail, true),
-            defaultNewUserBetaAccess: resolveBooleanSetting(authSettings.defaultNewUserBetaAccess, false),
-            authRateLimitEnabled: resolveBooleanSetting(authSettings.authRateLimitEnabled, true),
-            authRateLimitMaxRequests: Number.isFinite(authRateLimitMaxRequestsRaw) && authRateLimitMaxRequestsRaw >= 1
-                ? Math.floor(authRateLimitMaxRequestsRaw)
-                : 10,
-            authRateLimitWindowMs: Number.isFinite(authRateLimitWindowMsRaw) && authRateLimitWindowMsRaw >= 1000
-                ? Math.floor(authRateLimitWindowMsRaw)
-                : 15 * 60_000,
-            onboardingPolicyMode: onboardingPolicy.mode,
-            onboardingPlanVersionId: onboardingPolicy.planVersionId
-        };
-    };
-    const getSiteBehavior = () => {
-        const globalSettings = core.getGlobalSettings();
-        const siteSettings = globalSettings.site || {};
-        return {
-            showRunTaskforceLocally: resolveBooleanSetting(siteSettings.showRunTaskforceLocally, true),
-            pricingPageEnabled: resolveBooleanSetting(siteSettings.pricingPageEnabled, true)
-        };
-    };
     const resolveEffectiveVirusScanSettings = () => {
         const settings = core.getGlobalSettings().objectStorage || {};
         const asyncEnabled = typeof settings.virusScanAsyncEnabled === 'boolean'
@@ -139,6 +94,7 @@ export function registerAdminRoutes(deps) {
         };
     };
     // === SECTION: MCP helpers ===
+    const MCP_CONNECTION_TEST_TIMEOUT_MS = 5000;
     const writeMcpHttpError = (res, statusCode, message) => {
         res.writeHead(statusCode, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
@@ -171,6 +127,112 @@ export function registerAdminRoutes(deps) {
     const resolveMcpOauthTokenUrl = (req) => `${resolveMcpOauthIssuer(req)}/oauth/mcp/token`;
     const resolveMcpOauthRegisterUrl = (req) => `${resolveMcpOauthIssuer(req)}/oauth/mcp/register`;
     const resolveMcpOauthResourceUrl = (req) => `${resolveMcpOauthIssuer(req)}/mcp`;
+    const resolveCloudMcpEndpoint = (req) => {
+        const requestBaseUrl = resolveRuntimeConfigBaseUrl(req);
+        const deployment = resolveDeploymentConfig(process.env, { requestBaseUrl });
+        const inferredMcpBaseUrl = resolveTaskforceMcpBaseUrlFromBaseUrl(deployment.cloudMcpBaseUrl
+            || deployment.cloudAuthBaseUrl
+            || deployment.cloudBaseUrl
+            || requestBaseUrl
+            || '');
+        const baseUrl = String(inferredMcpBaseUrl || deployment.cloudMcpBaseUrl || resolveMcpOauthIssuer(req)).trim().replace(/\/+$/, '');
+        return `${baseUrl}/mcp`;
+    };
+    const probeCloudMcpEndpoint = async (req, token) => {
+        const endpoint = resolveCloudMcpEndpoint(req);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), MCP_CONNECTION_TEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/json, text/event-stream',
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: `mcp-connection-test-${randomUUID()}`,
+                    method: 'initialize',
+                    params: {
+                        protocolVersion: '2025-03-26',
+                        capabilities: {},
+                        clientInfo: {
+                            name: 'taskforce-settings-test',
+                            version: '1.0.0'
+                        }
+                    }
+                }),
+                signal: controller.signal
+            });
+            const responseText = await response.text();
+            let payload = null;
+            try {
+                payload = responseText ? JSON.parse(responseText) : null;
+            }
+            catch {
+                payload = null;
+            }
+            const remoteMessage = typeof payload?.error?.message === 'string'
+                ? payload.error.message.trim()
+                : '';
+            if (!response.ok) {
+                if (response.status >= 500) {
+                    return {
+                        ok: false,
+                        statusCode: 502,
+                        code: 'MCP_ENDPOINT_GATEWAY_ERROR',
+                        error: `Cloud MCP endpoint ${endpoint} returned ${response.status}. The dedicated MCP host may be degraded or unavailable.`,
+                        details: {
+                            endpoint,
+                            upstreamStatus: response.status,
+                            remoteMessage: remoteMessage || null
+                        }
+                    };
+                }
+                return {
+                    ok: false,
+                    statusCode: 502,
+                    code: 'MCP_ENDPOINT_REJECTED_VALIDATED_TOKEN',
+                    error: `Cloud MCP endpoint ${endpoint} rejected a token that validated locally. This usually means the MCP service is stale, routed incorrectly, or out of sync with the auth database.`,
+                    details: {
+                        endpoint,
+                        upstreamStatus: response.status,
+                        remoteMessage: remoteMessage || null
+                    }
+                };
+            }
+            return {
+                ok: true,
+                endpoint,
+                serverName: typeof payload?.result?.serverInfo?.name === 'string'
+                    ? payload.result.serverInfo.name
+                    : null,
+                protocolVersion: typeof payload?.result?.protocolVersion === 'string'
+                    ? payload.result.protocolVersion
+                    : null
+            };
+        }
+        catch (error) {
+            const timedOut = error?.name === 'AbortError';
+            return {
+                ok: false,
+                statusCode: 502,
+                code: timedOut ? 'MCP_ENDPOINT_TIMEOUT' : 'MCP_ENDPOINT_UNREACHABLE',
+                error: timedOut
+                    ? `Cloud MCP endpoint ${endpoint} did not respond within ${MCP_CONNECTION_TEST_TIMEOUT_MS}ms.`
+                    : `Could not reach cloud MCP endpoint ${endpoint}. The dedicated MCP host may be unavailable or misconfigured.`,
+                details: {
+                    endpoint,
+                    timeoutMs: MCP_CONNECTION_TEST_TIMEOUT_MS,
+                    reason: String(error?.message || error || '')
+                }
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    };
     const renderMcpOauthAuthorizePage = (input) => {
         const options = input.workspaces.map((workspace) => {
             const selected = workspace.id === input.preselectedWorkspaceId ? ' selected' : '';
@@ -513,6 +575,18 @@ export function registerAdminRoutes(deps) {
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ success: true, plans }));
     });
+    addRoute('GET', '/api/platform/onboarding-plan-options', async (req, res) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const options = core.listOnboardingPlanOptions();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, options }));
+    });
     addRoute('POST', '/api/platform/plans', async (req, res) => {
         if (!ensureCloudPlanData(req, res))
             return;
@@ -522,10 +596,19 @@ export function registerAdminRoutes(deps) {
             return;
         }
         const body = await parseJsonBody(req);
+        const description = body?.description === undefined || body?.description === null
+            ? body?.description
+            : String(body.description);
+        if (typeof description === 'string' && description.trim().length > 240) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Plan description must be 240 characters or fewer.', code: 'PLAN_DESCRIPTION_TOO_LONG' }));
+            return;
+        }
         try {
             const plan = core.upsertPlanCatalog({
                 planId: body?.planId,
                 displayName: body?.displayName,
+                description,
                 status: body?.status,
                 initialMode: body?.initialMode,
                 initialTrialDays: body?.initialTrialDays === undefined ? undefined : Number(body?.initialTrialDays),
@@ -581,6 +664,62 @@ export function registerAdminRoutes(deps) {
             res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to list feature catalog'), code: error?.code }));
         }
     });
+    addRoute('PATCH', '/api/platform/features/:featureKey', async (req, res, params) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const featureKey = String(params.featureKey || '').trim();
+        const publicLabel = body?.publicLabel === undefined || body?.publicLabel === null
+            ? body?.publicLabel
+            : String(body.publicLabel);
+        const publicDescription = body?.publicDescription === undefined || body?.publicDescription === null
+            ? body?.publicDescription
+            : String(body.publicDescription);
+        const publicDisplayOrder = body?.publicDisplayOrder === undefined || body?.publicDisplayOrder === null || body?.publicDisplayOrder === ''
+            ? null
+            : Math.max(0, Math.floor(Number(body.publicDisplayOrder)));
+        if (typeof publicLabel === 'string' && publicLabel.trim().length > 120) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Public label must be 120 characters or fewer.', code: 'PLAN_FEATURE_PUBLIC_LABEL_TOO_LONG' }));
+            return;
+        }
+        if (typeof publicDescription === 'string' && publicDescription.trim().length > 280) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Public description must be 280 characters or fewer.', code: 'PLAN_FEATURE_PUBLIC_DESCRIPTION_TOO_LONG' }));
+            return;
+        }
+        if (publicDisplayOrder !== null && !Number.isFinite(publicDisplayOrder)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Public display order must be a non-negative number.', code: 'PLAN_FEATURE_PUBLIC_DISPLAY_ORDER_INVALID' }));
+            return;
+        }
+        try {
+            const feature = core.updatePlanFeatureCatalogMarketingCopy({
+                featureKey,
+                publicLabel,
+                publicDescription,
+                publicDisplayOrder
+            });
+            auditAdminAction(req, 'platform-plan-feature-catalog-updated', {
+                featureKey,
+                publicLabel: feature.publicLabel ?? null,
+                publicDescription: feature.publicDescription ?? null,
+                publicDisplayOrder: feature.publicDisplayOrder ?? null
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, feature }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to update feature catalog entry'), code: error?.code }));
+        }
+    });
     addRoute('POST', '/api/platform/plans/:planId/versions', async (req, res, params) => {
         if (!ensureCloudPlanData(req, res))
             return;
@@ -797,9 +936,23 @@ export function registerAdminRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
             return;
         }
-        const users = core.listSystemUsers();
+        const reqUrl = new URL(req.url || '/api/taskforce/admin/system-users', 'http://localhost');
+        const query = String(reqUrl.searchParams.get('q') || '').trim();
+        const sort = reqUrl.searchParams.get('sort') === 'oldest' ? 'oldest' : 'newest';
+        const limitRaw = Number(reqUrl.searchParams.get('limit') || '50');
+        const offsetRaw = Number(reqUrl.searchParams.get('offset') || '0');
+        const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(200, Math.floor(limitRaw))) : 50;
+        const offset = Number.isFinite(offsetRaw) ? Math.max(0, Math.floor(offsetRaw)) : 0;
+        const total = core.countSystemUsers({ query });
+        const users = core.listSystemUsers({ query, sort, limit, offset });
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ users }));
+        res.end(JSON.stringify({
+            users,
+            total,
+            limit,
+            offset,
+            hasMore: offset + users.length < total
+        }));
     });
     // GET /api/taskforce/admin/audit-logs - Read recent admin audit events
     addRoute('GET', '/api/taskforce/admin/audit-logs', async (req, res) => {
@@ -1013,7 +1166,7 @@ export function registerAdminRoutes(deps) {
             return;
         }
         if (context.authConfig?.runtimeMode !== 'cloud') {
-            const effective = getEmailConfig();
+            const effective = getRouteEmailConfig(core, context);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
                 settings: { provider: 'console', from: effective.from, replyTo: '' },
@@ -1022,7 +1175,7 @@ export function registerAdminRoutes(deps) {
             return;
         }
         const settings = core.getGlobalSettings().email || {};
-        const effective = getEmailConfig();
+        const effective = getRouteEmailConfig(core, context);
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
             settings: {
@@ -1047,7 +1200,7 @@ export function registerAdminRoutes(deps) {
             return;
         }
         const settings = core.getGlobalSettings().email || {};
-        const effective = getEmailConfig();
+        const effective = getRouteEmailConfig(core, context);
         const keyRequired = effective.provider === 'resend' || effective.provider === 'google-workspace';
         const ready = keyRequired ? Boolean(effective.providerApiKey) : true;
         const reason = ready
@@ -1078,8 +1231,8 @@ export function registerAdminRoutes(deps) {
         }
         const globalSettings = core.getGlobalSettings();
         const authSettings = globalSettings.auth || {};
-        const billingSettings = globalSettings.billing || {};
-        const effective = getAuthBehavior();
+        const onboardingPolicy = core.getOnboardingPolicy();
+        const effective = buildAuthBehavior(core);
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
             settings: {
@@ -1089,14 +1242,8 @@ export function registerAdminRoutes(deps) {
                 ...(typeof authSettings.authRateLimitEnabled === 'boolean' ? { authRateLimitEnabled: authSettings.authRateLimitEnabled } : {}),
                 ...(typeof authSettings.authRateLimitMaxRequests === 'number' ? { authRateLimitMaxRequests: authSettings.authRateLimitMaxRequests } : {}),
                 ...(typeof authSettings.authRateLimitWindowMs === 'number' ? { authRateLimitWindowMs: authSettings.authRateLimitWindowMs } : {}),
-                ...((billingSettings.onboardingPolicy?.mode === 'require_plan_selection'
-                    || billingSettings.onboardingPolicy?.mode === 'auto_grant_free'
-                    || billingSettings.onboardingPolicy?.mode === 'auto_start_trial')
-                    ? { onboardingPolicyMode: billingSettings.onboardingPolicy.mode }
-                    : {}),
-                ...(typeof billingSettings.onboardingPolicy?.planVersionId === 'string' || billingSettings.onboardingPolicy?.planVersionId === null
-                    ? { onboardingPlanVersionId: billingSettings.onboardingPolicy?.planVersionId ?? null }
-                    : {})
+                onboardingPolicyMode: onboardingPolicy.mode,
+                onboardingPlanId: onboardingPolicy.planId
             },
             status: {
                 allowSelfRegistration: effective.allowSelfRegistration,
@@ -1106,7 +1253,7 @@ export function registerAdminRoutes(deps) {
                 authRateLimitMaxRequests: effective.authRateLimitMaxRequests,
                 authRateLimitWindowMs: effective.authRateLimitWindowMs,
                 onboardingPolicyMode: effective.onboardingPolicyMode,
-                onboardingPlanVersionId: effective.onboardingPlanVersionId
+                onboardingPlanId: effective.onboardingPlanId
             }
         }));
     });
@@ -1117,7 +1264,7 @@ export function registerAdminRoutes(deps) {
             return;
         }
         const siteSettings = core.getGlobalSettings().site || {};
-        const siteBehavior = getSiteBehavior();
+        const siteBehavior = buildSiteBehavior(core);
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
             settings: {
@@ -1413,7 +1560,8 @@ export function registerAdminRoutes(deps) {
             workspaceAssetStore.deleteLink({
                 workspaceId,
                 assetId,
-                taskId: link.taskId,
+                targetType: link.targetType,
+                targetId: link.targetId,
                 role: link.role
             });
         }
@@ -1738,14 +1886,14 @@ export function registerAdminRoutes(deps) {
             : body?.onboardingPolicyMode === 'require_plan_selection'
                 ? 'require_plan_selection'
                 : currentOnboardingPolicy.mode;
-        const onboardingPlanVersionId = typeof body?.onboardingPlanVersionId === 'string'
-            ? body.onboardingPlanVersionId.trim() || null
-            : body?.onboardingPlanVersionId === null
+        const onboardingPlanId = typeof body?.onboardingPlanId === 'string'
+            ? body.onboardingPlanId.trim().toLowerCase() || null
+            : body?.onboardingPlanId === null
                 ? null
-                : currentOnboardingPolicy.planVersionId;
+                : currentOnboardingPolicy.planId;
         const validation = core.validateOnboardingPolicy({
             mode: onboardingPolicyMode,
-            planVersionId: onboardingPlanVersionId
+            planId: onboardingPlanId
         });
         if (!validation.valid) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -1766,7 +1914,7 @@ export function registerAdminRoutes(deps) {
             billing: {
                 onboardingPolicy: {
                     mode: onboardingPolicyMode,
-                    planVersionId: onboardingPlanVersionId ?? null
+                    planId: onboardingPlanId ?? null
                 }
             }
         });
@@ -1842,7 +1990,7 @@ export function registerAdminRoutes(deps) {
             res.end(JSON.stringify({ success: false, error: 'Valid test email address is required.' }));
             return;
         }
-        const config = getEmailConfig();
+        const config = getRouteEmailConfig(core, context);
         const result = await sendEmail({
             to,
             subject: 'Taskforce email settings test',
@@ -1856,6 +2004,169 @@ export function registerAdminRoutes(deps) {
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ success: true, provider: result.provider, messageId: result.messageId || null }));
     });
+    // === SECTION: Admin auth provider settings ===
+    // GET /api/taskforce/admin/auth-provider-settings - Read OAuth provider config (secrets masked)
+    addRoute('GET', '/api/taskforce/admin/auth-provider-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (context.authConfig?.runtimeMode !== 'cloud') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: {
+                    google: { enabled: false, clientId: '', hasClientSecret: false, ready: false },
+                    github: { enabled: false, clientId: '', hasClientSecret: false, ready: false },
+                    apple: { enabled: false, servicesId: '', teamId: '', keyId: '', hasPrivateKeyPem: false, ready: false }
+                }
+            }));
+            return;
+        }
+        const providers = core.getGlobalSettings().oauthProviders || {};
+        const g = providers.google || {};
+        const gh = providers.github || {};
+        const ap = providers.apple || {};
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            status: {
+                google: {
+                    enabled: g.enabled === true,
+                    clientId: String(g.clientId || ''),
+                    hasClientSecret: typeof g.clientSecret === 'string' && g.clientSecret.trim().length > 0,
+                    ready: g.enabled === true && Boolean(g.clientId) && typeof g.clientSecret === 'string' && g.clientSecret.trim().length > 0
+                },
+                github: {
+                    enabled: gh.enabled === true,
+                    clientId: String(gh.clientId || ''),
+                    hasClientSecret: typeof gh.clientSecret === 'string' && gh.clientSecret.trim().length > 0,
+                    ready: gh.enabled === true && Boolean(gh.clientId) && typeof gh.clientSecret === 'string' && gh.clientSecret.trim().length > 0
+                },
+                apple: {
+                    enabled: ap.enabled === true,
+                    servicesId: String(ap.servicesId || ''),
+                    teamId: String(ap.teamId || ''),
+                    keyId: String(ap.keyId || ''),
+                    hasPrivateKeyPem: typeof ap.privateKeyPem === 'string' && ap.privateKeyPem.trim().length > 0,
+                    ready: ap.enabled === true && Boolean(ap.servicesId) && Boolean(ap.teamId) && Boolean(ap.keyId)
+                        && typeof ap.privateKeyPem === 'string' && ap.privateKeyPem.trim().length > 0
+                }
+            }
+        }));
+    });
+    // GET /api/taskforce/admin/auth-provider-settings/health - Per-provider readiness check
+    addRoute('GET', '/api/taskforce/admin/auth-provider-settings/health', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const providers = core.getGlobalSettings().oauthProviders || {};
+        const g = providers.google || {};
+        const gh = providers.github || {};
+        const ap = providers.apple || {};
+        const googleReady = g.enabled === true && Boolean(g.clientId) && typeof g.clientSecret === 'string' && g.clientSecret.trim().length > 0;
+        const googleReason = !g.enabled
+            ? 'Provider disabled.'
+            : !g.clientId ? 'Missing Client ID.'
+                : !googleReady ? 'Missing Client Secret.'
+                    : null;
+        const githubReady = gh.enabled === true && Boolean(gh.clientId) && typeof gh.clientSecret === 'string' && gh.clientSecret.trim().length > 0;
+        const githubReason = !gh.enabled
+            ? 'Provider disabled.'
+            : !gh.clientId ? 'Missing Client ID.'
+                : !githubReady ? 'Missing Client Secret.'
+                    : null;
+        const appleBaseReady = ap.enabled === true && Boolean(ap.servicesId) && Boolean(ap.teamId) && Boolean(ap.keyId)
+            && typeof ap.privateKeyPem === 'string' && ap.privateKeyPem.trim().length > 0;
+        let appleSecretMintOk;
+        let appleReason = null;
+        if (!ap.enabled) {
+            appleReason = 'Provider disabled.';
+        }
+        else if (!ap.servicesId || !ap.teamId || !ap.keyId) {
+            appleReason = 'Missing Services ID, Team ID, or Key ID.';
+        }
+        else if (!appleBaseReady) {
+            appleReason = 'Missing private key PEM.';
+        }
+        else {
+            // Attempt a test-mint to verify the key is valid
+            const mintResult = testMintAppleClientSecret({
+                teamId: ap.teamId,
+                servicesId: ap.servicesId,
+                keyId: ap.keyId,
+                privateKeyPem: ap.privateKeyPem
+            });
+            appleSecretMintOk = mintResult.ok;
+            if (!mintResult.ok) {
+                appleReason = `Client-secret JWT mint failed: ${mintResult.error}`;
+            }
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            health: {
+                google: { enabled: g.enabled === true, ready: googleReady, reason: googleReason },
+                github: { enabled: gh.enabled === true, ready: githubReady, reason: githubReason },
+                apple: {
+                    enabled: ap.enabled === true,
+                    ready: appleBaseReady && appleSecretMintOk !== false,
+                    reason: appleReason,
+                    ...(typeof appleSecretMintOk === 'boolean' ? { secretMintOk: appleSecretMintOk } : {})
+                }
+            }
+        }));
+    });
+    // POST /api/taskforce/admin/auth-provider-settings - Save OAuth provider config (including secrets)
+    addRoute('POST', '/api/taskforce/admin/auth-provider-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (!requireCloudRuntime(res, 'Auth provider settings'))
+            return;
+        const body = await parseJsonBody(req);
+        const update = {};
+        if (body?.google && typeof body.google === 'object') {
+            const g = body.google;
+            update.google = {
+                ...(typeof g.enabled === 'boolean' ? { enabled: g.enabled } : {}),
+                ...(typeof g.clientId === 'string' ? { clientId: g.clientId } : {}),
+                ...(typeof g.clientSecret === 'string' ? { clientSecret: g.clientSecret } : {})
+            };
+        }
+        if (body?.github && typeof body.github === 'object') {
+            const gh = body.github;
+            update.github = {
+                ...(typeof gh.enabled === 'boolean' ? { enabled: gh.enabled } : {}),
+                ...(typeof gh.clientId === 'string' ? { clientId: gh.clientId } : {}),
+                ...(typeof gh.clientSecret === 'string' ? { clientSecret: gh.clientSecret } : {})
+            };
+        }
+        if (body?.apple && typeof body.apple === 'object') {
+            const ap = body.apple;
+            update.apple = {
+                ...(typeof ap.enabled === 'boolean' ? { enabled: ap.enabled } : {}),
+                ...(typeof ap.servicesId === 'string' ? { servicesId: ap.servicesId } : {}),
+                ...(typeof ap.teamId === 'string' ? { teamId: ap.teamId } : {}),
+                ...(typeof ap.keyId === 'string' ? { keyId: ap.keyId } : {}),
+                ...(typeof ap.privateKeyPem === 'string' ? { privateKeyPem: ap.privateKeyPem } : {})
+            };
+        }
+        if (Object.keys(update).length === 0) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No provider settings provided.' }));
+            return;
+        }
+        core.updateGlobalSettings({ oauthProviders: update });
+        auditAdminAction(req, 'auth-provider-settings.update', {
+            providers: Object.keys(update)
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
     // === SECTION: Cloud MCP HTTP transport ===
     addRoute('POST', '/mcp', async (req, res) => { await handleCloudMcpRequest(req, res); });
     addRoute('POST', '/mcp/', async (req, res) => { await handleCloudMcpRequest(req, res); });
@@ -2267,9 +2578,28 @@ export function registerAdminRoutes(deps) {
                 res.end(JSON.stringify({ success: false, error: 'Token is missing required scopes.', code: 'MCP_TOKEN_MISSING_SCOPES', details: { requiredScopes, missingScopes, grantedScopes: inspection.scopes } }));
                 return;
             }
+            const probe = await probeCloudMcpEndpoint(req, token);
+            if (!probe.ok) {
+                res.writeHead(probe.statusCode, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: probe.error, code: probe.code, details: probe.details }));
+                return;
+            }
             const workspace = core.getWorkspaceProfile(wid);
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: true, result: { tokenId: inspection.tokenId, tokenName: inspection.name, workspaceId: wid, workspaceName: String(workspace?.name || wid), scopes: inspection.scopes, requiredScopes, endpoint: '/mcp' } }));
+            res.end(JSON.stringify({
+                success: true,
+                result: {
+                    tokenId: inspection.tokenId,
+                    tokenName: inspection.name,
+                    workspaceId: wid,
+                    workspaceName: String(workspace?.name || wid),
+                    scopes: inspection.scopes,
+                    requiredScopes,
+                    endpoint: probe.endpoint,
+                    serverName: probe.serverName,
+                    protocolVersion: probe.protocolVersion
+                }
+            }));
         }
         catch (error) {
             const statusCode = resolveErrorStatusCode(error);