@taskforcehq/taskforce 0.3.305 → 0.3.306

package/dist/server/routes/auth.js

@@ -6,9 +6,20 @@
  *
  * Routes registered here:
  *   GET  /api/taskforce/auth/runtime-config
+ *   GET  /api/taskforce/auth/providers
+ *   GET  /api/taskforce/auth/oauth/:provider/start
+ *   GET  /api/taskforce/auth/oauth/:provider/callback
+ *   POST /api/taskforce/auth/oauth/apple/callback
+ *   GET  /api/taskforce/account/login-methods
+ *   DELETE /api/taskforce/account/login-methods/:provider
+ *   POST /api/taskforce/account/login-methods/password
  *   GET  /api/taskforce/auth/session
  *   GET  /api/taskforce/auth/admin-session
  *   POST /api/taskforce/auth/profile
+ *   POST /api/taskforce/auth/profile/avatar/init
+ *   POST /api/taskforce/auth/profile/avatar/upload
+ *   POST /api/taskforce/auth/profile/avatar/finalize
+ *   POST /api/taskforce/auth/profile/avatar/discard
  *   POST /api/taskforce/auth/login
  *   POST /api/taskforce/auth/register
  *   POST /api/taskforce/auth/verify-email/request
@@ -26,6 +37,7 @@
  *   GET  /api/taskforce/account/plan-preview
  *   GET  /api/taskforce/auth/workspace-members
  *   GET  /api/taskforce/workspace/assignee-options
+ *   POST /api/taskforce/workspace/ai-profiles/avatar
  *   GET  /api/taskforce/admin/users
  *   POST /api/taskforce/admin/users/invite
  *   PATCH /api/taskforce/admin/users/:id/role
@@ -38,17 +50,20 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
-import { parseJsonBody } from './primitives.js';
+import { parseJsonBody, parseFormBody } from './primitives.js';
+import { buildGoogleAuthUrl, exchangeGoogleCode } from '../auth/providers/google.js';
+import { buildAppleAuthUrl, exchangeAppleCode } from '../auth/providers/apple.js';
+import { buildGithubAuthUrl, exchangeGithubCode } from '../auth/providers/github.js';
 import { hasValidSession, createClearSessionCookie, createSessionTokenCookie, resolveRequestAccess, resolveSessionCookieAttributesForRequest, } from '../auth.js';
 import { sendEmail } from '../email.js';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
 import { resolveRuntimeModeContract } from '../../shared/runtimeContract.js';
-import { requestHeader, resolveErrorStatusCode } from './shared.js';
+import { getRouteTimingNow, logSlowBootstrapRoute, requestBootstrapTraceId, requestHeader, resolveErrorStatusCode, serializeJsonWithTiming, setServerTimingHeader } from './shared.js';
 import { buildAuthFlowBehavior, buildSiteBehavior, getRouteEmailConfig, resolvePublicAuthBaseUrl, resolveRuntimeConfigBaseUrl, shouldExposeDevAuthTokens } from './authSupport.js';
 import { normalizeTaskDataRelativePath } from '../../storage/objectStorageClient.js';
 // === SECTION: Registration ===
 export function registerAuthRoutes(deps) {
-    const { addRoute, core, context, requestWorkspaceId, requestUserId, ensureAppAccess, ensureAuthenticatedUser, ensureWorkspaceAdminRole, ensureCloudPlanData, requireCloudRuntime, auditAuthAction, resolveAdminRequestActor, resolveEffectiveObjectStorageConfig, getObjectStorageClient, } = deps;
+    const { addRoute, core, context, requestWorkspaceId, requestUserId, resolveAuthenticatedUserId, ensureAppAccess, ensureAuthenticatedUser, ensureWorkspaceAdminRole, ensureCloudPlanData, requireCloudRuntime, auditAuthAction, resolveAdminRequestActor, resolveEffectiveObjectStorageConfig, getObjectStorageClient, } = deps;
     const normalizeTeamWorkspaceRole = (value) => {
         const role = String(value || '').trim().toLowerCase();
         if (role === 'owner' || role === 'admin' || role === 'member' || role === 'read-only')
@@ -103,7 +118,7 @@ export function registerAuthRoutes(deps) {
         return null;
     };
     const buildAccountProfileSummary = (req) => {
-        const userId = requestUserId(req);
+        const userId = resolveAuthenticatedUserId(req);
         const workspaceId = requestWorkspaceId(req);
         const access = core.getAccountAccessStatus(userId);
         const resolvedAccess = core.resolveUserAccess(userId, workspaceId, 'member');
@@ -125,8 +140,12 @@ export function registerAuthRoutes(deps) {
         catch {
             billingRow = undefined;
         }
-        const planId = String(access.entitlement?.planId || billingRow?.tier || '').trim() || null;
+        const allowBillingPlanFallback = access.gate === 'plan_selection_required' || access.gate === 'checkout_pending';
+        const planId = String(access.entitlement?.planId
+            || (allowBillingPlanFallback ? billingRow?.tier : '')
+            || '').trim() || null;
         const planVersionId = String(access.entitlement?.planVersionId || '').trim() || null;
+        const entitlementState = access.entitlement?.state || null;
         let planRow;
         if (planId) {
             try {
@@ -151,6 +170,7 @@ export function registerAuthRoutes(deps) {
                 teamPlanMode = 'personal';
             }
         }
+        const aiProfileSeatUsage = core.countAiProfileUsage(workspaceId);
         const billingConflictCode = resolveBillingConflictCodeForUser(userId, access.gate);
         return {
             stripeStatus: billingRow?.stripe_status || null,
@@ -161,7 +181,7 @@ export function registerAuthRoutes(deps) {
             trialEnd: billingRow?.trial_end || null,
             currentPeriodEnd: billingRow?.current_period_end || null,
             effectiveUntil: billingRow?.effective_until || null,
-            entitlementState: access.entitlement?.state || billingRow?.entitlement_state || null,
+            entitlementState,
             planVersionId,
             planId,
             planName: planRow?.display_name ? String(planRow.display_name) : planId,
@@ -173,7 +193,8 @@ export function registerAuthRoutes(deps) {
             workspaceRole,
             canManageWorkspace,
             teamPlanMode,
-            teamManagementAllowed: canManageWorkspace && teamPlanMode === 'team'
+            teamManagementAllowed: canManageWorkspace && teamPlanMode === 'team',
+            aiProfileSeatUsage
         };
     };
     // === SECTION: Email delivery helpers ===
@@ -187,7 +208,7 @@ export function registerAuthRoutes(deps) {
         const access = resolvedWorkspaceId
             ? core.resolveUserAccess(userId, resolvedWorkspaceId, fallbackRole)
             : null;
-        return createSessionTokenCookie(`pwd:${userId}`, authConfig, {
+        return createSessionTokenCookie(`usr:${userId}`, authConfig, {
             role: (access?.role || fallbackRole),
             workspaceId: access?.workspaceId || '',
             userId,
@@ -241,6 +262,29 @@ export function registerAuthRoutes(deps) {
             await deleteStoredAvatarObject(draft.storageKey);
         }
     };
+    const parseBinaryBody = async (req, maxBytes) => {
+        const safeMaxBytes = Number.isFinite(maxBytes) && maxBytes > 0
+            ? Math.floor(maxBytes)
+            : MAX_AVATAR_UPLOAD_BYTES;
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            let receivedBytes = 0;
+            req.on('data', (chunk) => {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                receivedBytes += buffer.length;
+                if (receivedBytes > safeMaxBytes) {
+                    req.pause();
+                    reject(Object.assign(new Error(`Payload too large (max ${safeMaxBytes} bytes)`), { statusCode: 413 }));
+                    return;
+                }
+                chunks.push(buffer);
+            });
+            req.on('end', () => {
+                resolve(Buffer.concat(chunks));
+            });
+            req.on('error', reject);
+        });
+    };
     const logAuthLink = (kind, email, token, req) => {
         const base = resolvePublicAuthBaseUrl(req);
         const urlPath = kind === 'verify-email'
@@ -339,11 +383,650 @@ export function registerAuthRoutes(deps) {
         });
         res.end(`window.__TASKFORCE_SITE_CONFIG__ = ${payload};`);
     });
+    // GET /api/taskforce/auth/providers - Public: list enabled OAuth login providers (no secrets)
+    addRoute('GET', '/api/taskforce/auth/providers', async (_req, res) => {
+        const providers = core.getGlobalSettings().oauthProviders || {};
+        const enabled = [];
+        if (providers.google?.enabled === true)
+            enabled.push('google');
+        if (providers.github?.enabled === true)
+            enabled.push('github');
+        if (providers.apple?.enabled === true)
+            enabled.push('apple');
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ providers: enabled }));
+    });
+    // === SECTION: OAuth 2.0 / OpenID Connect ===
+    const OAUTH_RETURN_TO_PATTERN = /^\/[A-Za-z0-9_\-./?=&%]*$/;
+    /**
+     * Validates a `return_to` value and defaults to '/' on failure.
+     * Prevents open-redirect attacks by only allowing same-site relative paths.
+     */
+    const sanitizeReturnTo = (raw) => {
+        const value = String(raw || '').trim();
+        if (!value || !OAUTH_RETURN_TO_PATTERN.test(value))
+            return '/';
+        return value;
+    };
+    /**
+     * Provider-agnostic session cookie builder for OAuth-authenticated users.
+     * Resolves workspace/role and mints the signed session token.
+     */
+    const buildOAuthSessionCookie = (req, authConfig, userId, identityId) => {
+        const resolvedWorkspaceId = core.resolvePreferredUserWorkspaceId(userId, {
+            preferredWorkspaceId: null,
+            persistedWorkspaceId: null
+        });
+        const fallbackRole = String(authConfig.defaultRole || 'member').trim() || 'member';
+        const access = resolvedWorkspaceId
+            ? core.resolveUserAccess(userId, resolvedWorkspaceId, fallbackRole)
+            : null;
+        return createSessionTokenCookie(`usr:${userId}`, authConfig, {
+            role: (access?.role || fallbackRole),
+            workspaceId: access?.workspaceId || '',
+            userId,
+            identityId,
+            ...resolveSessionCookieAttributesForRequest(req, authConfig),
+        });
+    };
+    /**
+     * Handles the post-exchange OAuth profile: find or create the user,
+     * link the provider identity if needed, and return { userId, identityId }.
+     *
+     * Resolution order:
+     *  1. Existing identity matching (provider, providerSubject) → login.
+     *  2. Existing user with same email (provider must have verified it) → link + login.
+     *  3. Self-registration allowed → register new user → login.
+     *  4. Otherwise → reject.
+     */
+    const resolveOAuthUser = (profile) => {
+        // Case 1: known identity
+        const found = core.findUserByOAuthProvider(profile.provider, profile.providerSubject);
+        if (found) {
+            // Update last_login_at snapshot
+            try {
+                const db = core.getDatabaseAdapter();
+                const tenantId = core.getTenantId();
+                db.prepare(`
+                    UPDATE user_auth_identities
+                    SET last_login_at = ?, avatar_url_snapshot = COALESCE(?, avatar_url_snapshot),
+                        updated_at = ?
+                    WHERE tenant_id = ? AND id = ?
+                `).run(new Date().toISOString(), profile.avatarUrl ?? null, new Date().toISOString(), tenantId, found.identityId);
+            }
+            catch { /* non-fatal */ }
+            return { userId: found.userId, identityId: found.identityId, isNew: false };
+        }
+        // Case 2: email match (provider must have verified it)
+        if (profile.email && profile.emailVerified) {
+            const byEmail = core.findUserByEmail(profile.email);
+            if (byEmail) {
+                try {
+                    const identityId = core.linkOAuthProviderToUser({
+                        userId: byEmail.userId,
+                        provider: profile.provider,
+                        providerSubject: profile.providerSubject,
+                        providerEmail: profile.email,
+                        providerEmailVerified: profile.emailVerified,
+                        displayNameSnapshot: profile.displayName,
+                        avatarUrlSnapshot: profile.avatarUrl,
+                    });
+                    return { userId: byEmail.userId, identityId, isNew: false };
+                }
+                catch (e) {
+                    if (e?.code !== 'IDENTITY_ALREADY_EXISTS')
+                        throw e;
+                    // Race condition: already linked — re-query
+                    const refound = core.findUserByOAuthProvider(profile.provider, profile.providerSubject);
+                    if (refound)
+                        return { ...refound, isNew: false };
+                    throw e;
+                }
+            }
+        }
+        // Case 3: self-registration
+        const authBehavior = buildAuthFlowBehavior(core);
+        if (!authBehavior.allowSelfRegistration) {
+            throw Object.assign(new Error('Self-registration is currently disabled.'), {
+                code: 'REGISTRATION_DISABLED',
+                statusCode: 403
+            });
+        }
+        const created = core.registerOAuthUser({
+            email: profile.email,
+            emailVerified: profile.emailVerified,
+            provider: profile.provider,
+            providerSubject: profile.providerSubject,
+            displayName: profile.displayName,
+            avatarUrl: profile.avatarUrl,
+            betaAccess: authBehavior.defaultNewUserBetaAccess,
+        });
+        return { userId: created.userId, identityId: created.identityId, isNew: true };
+    };
+    // GET /api/taskforce/auth/oauth/:provider/start
+    // Initiates the OAuth authorisation redirect for Google, GitHub, or Apple.
+    addRoute('GET', '/api/taskforce/auth/oauth/:provider/start', async (req, res, params) => {
+        if (!requireCloudRuntime(res, 'OAuth Login'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig?.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth is not enabled.' }));
+            return;
+        }
+        const provider = String(params.provider || '').toLowerCase();
+        if (provider !== 'google' && provider !== 'github' && provider !== 'apple') {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Unknown OAuth provider.' }));
+            return;
+        }
+        const oauthProviders = core.getGlobalSettings().oauthProviders || {};
+        const providerConfig = oauthProviders[provider];
+        if (!providerConfig?.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: `${provider} login is not enabled.` }));
+            return;
+        }
+        const queryString = (req.url || '').split('?')[1] || '';
+        const queryParams = new URLSearchParams(queryString);
+        const returnTo = sanitizeReturnTo(queryParams.get('return_to'));
+        const clientIp = requestHeader(req, 'x-forwarded-for', '') || requestHeader(req, 'x-real-ip', '') || null;
+        const rawInviteToken = String(queryParams.get('invite_token') || '').trim();
+        const rawFlowHint = String(queryParams.get('flow') || '').trim().toLowerCase();
+        // Determine flow mode: link > invite_claim > login
+        let flowMode = 'login';
+        let validatedInviteToken = null;
+        let linkUserId = null;
+        if (rawFlowHint === 'link') {
+            // Provider-link flow: require an authenticated session
+            if (!authConfig || !hasValidSession(req, authConfig)) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Sign in required to link a provider.', code: 'AUTH_REQUIRED' }));
+                return;
+            }
+            const access = resolveRequestAccess(req, authConfig);
+            linkUserId = access?.userId || null;
+            if (!linkUserId) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Unable to resolve authenticated user.', code: 'AUTH_REQUIRED' }));
+                return;
+            }
+            flowMode = 'link';
+        }
+        else if (rawInviteToken) {
+            // Invite-claim flow
+            const inviteDetails = core.inspectInviteAcceptance(rawInviteToken);
+            if (inviteDetails.state !== 'valid') {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Invite token is invalid or expired.', code: 'INVITE_TOKEN_INVALID' }));
+                return;
+            }
+            if (inviteDetails.inviteeState !== 'pending_setup') {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'This invite has already been claimed.', code: 'INVITE_ALREADY_CLAIMED' }));
+                return;
+            }
+            flowMode = 'invite_claim';
+            validatedInviteToken = rawInviteToken;
+        }
+        const { state, codeChallenge, nonce } = core.createOAuthLoginState({
+            provider,
+            flowMode,
+            userId: linkUserId,
+            returnTo,
+            inviteToken: validatedInviteToken,
+            createdIp: clientIp,
+        });
+        const baseUrl = resolvePublicAuthBaseUrl(req);
+        const redirectUri = `${baseUrl}/api/taskforce/auth/oauth/${provider}/callback`;
+        let authUrl;
+        if (provider === 'google') {
+            const cfg = providerConfig;
+            if (!cfg.clientId) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Google OAuth is not fully configured.' }));
+                return;
+            }
+            authUrl = buildGoogleAuthUrl({
+                clientId: cfg.clientId,
+                redirectUri,
+                state,
+                codeChallenge,
+            });
+        }
+        else if (provider === 'github') {
+            const cfg = providerConfig;
+            if (!cfg.clientId) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'GitHub OAuth is not fully configured.' }));
+                return;
+            }
+            authUrl = buildGithubAuthUrl({
+                clientId: cfg.clientId,
+                redirectUri,
+                state,
+                codeChallenge,
+            });
+        }
+        else {
+            // Apple
+            const cfg = providerConfig;
+            if (!cfg.servicesId) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Apple Sign In is not fully configured.' }));
+                return;
+            }
+            authUrl = buildAppleAuthUrl({
+                servicesId: cfg.servicesId,
+                redirectUri,
+                state,
+                nonce,
+            });
+        }
+        res.writeHead(302, { Location: authUrl });
+        res.end();
+    });
+    // GET /api/taskforce/auth/oauth/:provider/callback
+    // Handles the OAuth callback for Google and GitHub (GET redirect with `code` + `state`).
+    addRoute('GET', '/api/taskforce/auth/oauth/:provider/callback', async (req, res, params) => {
+        if (!requireCloudRuntime(res, 'OAuth Login'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig?.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth is not enabled.' }));
+            return;
+        }
+        const provider = String(params.provider || '').toLowerCase();
+        if (provider !== 'google' && provider !== 'github') {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Unknown OAuth provider.' }));
+            return;
+        }
+        const queryString = (req.url || '').split('?')[1] || '';
+        const queryParams = new URLSearchParams(queryString);
+        const stateParam = String(queryParams.get('state') || '').trim();
+        const codeParam = String(queryParams.get('code') || '').trim();
+        const errorParam = String(queryParams.get('error') || '').trim();
+        const baseUrl = resolvePublicAuthBaseUrl(req);
+        const redirectUri = `${baseUrl}/api/taskforce/auth/oauth/${provider}/callback`;
+        if (errorParam) {
+            auditAuthAction(req, 'auth-oauth-callback-denied', { provider, error: errorParam });
+            res.writeHead(302, { Location: `/login?error=oauth_denied&provider=${encodeURIComponent(provider)}` });
+            res.end();
+            return;
+        }
+        if (!stateParam || !codeParam) {
+            res.writeHead(302, { Location: `/login?error=oauth_invalid&provider=${encodeURIComponent(provider)}` });
+            res.end();
+            return;
+        }
+        // Consume state (single-use, validates expiry)
+        const stateRecord = core.consumeOAuthLoginState(stateParam);
+        if (!stateRecord) {
+            auditAuthAction(req, 'auth-oauth-state-invalid', { provider, stateProvided: true });
+            res.writeHead(302, { Location: `/login?error=oauth_state_invalid&provider=${encodeURIComponent(provider)}` });
+            res.end();
+            return;
+        }
+        if (stateRecord.provider !== provider) {
+            auditAuthAction(req, 'auth-oauth-state-provider-mismatch', { provider, stateProvider: stateRecord.provider });
+            res.writeHead(302, { Location: `/login?error=oauth_state_invalid&provider=${encodeURIComponent(provider)}` });
+            res.end();
+            return;
+        }
+        const codeVerifier = stateRecord.pkceVerifier || '';
+        const returnTo = sanitizeReturnTo(stateRecord.returnTo);
+        const oauthProviders = core.getGlobalSettings().oauthProviders || {};
+        try {
+            let profile;
+            if (provider === 'google') {
+                const cfg = (oauthProviders.google || {});
+                if (!cfg.clientId || !cfg.clientSecret) {
+                    throw Object.assign(new Error('Google OAuth is not configured.'), { statusCode: 500 });
+                }
+                profile = await exchangeGoogleCode({
+                    code: codeParam,
+                    codeVerifier,
+                    redirectUri,
+                    clientId: cfg.clientId,
+                    clientSecret: cfg.clientSecret,
+                });
+            }
+            else {
+                const cfg = (oauthProviders.github || {});
+                if (!cfg.clientId || !cfg.clientSecret) {
+                    throw Object.assign(new Error('GitHub OAuth is not configured.'), { statusCode: 500 });
+                }
+                profile = await exchangeGithubCode({
+                    code: codeParam,
+                    codeVerifier,
+                    redirectUri,
+                    clientId: cfg.clientId,
+                    clientSecret: cfg.clientSecret,
+                });
+            }
+            let userId;
+            let identityId;
+            let isNew = false;
+            if (stateRecord.flowMode === 'link') {
+                if (!stateRecord.userId) {
+                    throw Object.assign(new Error('User ID missing from OAuth link state.'), { code: 'AUTH_REQUIRED', statusCode: 401 });
+                }
+                identityId = core.linkOAuthProviderToUser({
+                    userId: stateRecord.userId,
+                    provider: profile.provider,
+                    providerSubject: profile.providerSubject,
+                    providerEmail: profile.email,
+                    providerEmailVerified: profile.emailVerified,
+                    displayNameSnapshot: profile.displayName,
+                    avatarUrlSnapshot: profile.avatarUrl,
+                });
+                userId = stateRecord.userId;
+                isNew = false;
+            }
+            else if (stateRecord.flowMode === 'invite_claim') {
+                if (!stateRecord.inviteToken) {
+                    throw Object.assign(new Error('Invite token missing from OAuth state.'), { code: 'INVITE_TOKEN_MISSING', statusCode: 400 });
+                }
+                const claimed = core.claimInviteWithOAuthProvider({
+                    token: stateRecord.inviteToken,
+                    provider: profile.provider,
+                    providerSubject: profile.providerSubject,
+                    providerEmail: profile.email,
+                    providerEmailVerified: profile.emailVerified,
+                    displayNameSnapshot: profile.displayName,
+                    avatarUrlSnapshot: profile.avatarUrl,
+                });
+                userId = claimed.userId;
+                identityId = claimed.identityId;
+                isNew = true;
+            }
+            else {
+                ({ userId, identityId, isNew } = resolveOAuthUser(profile));
+            }
+            const cookie = buildOAuthSessionCookie(req, authConfig, userId, identityId);
+            res.setHeader('Set-Cookie', cookie);
+            auditAuthAction(req, 'auth-oauth-login-success', {
+                provider,
+                userId,
+                isNew,
+                flowMode: stateRecord.flowMode,
+                email: profile.email || null,
+            });
+            res.writeHead(302, { Location: returnTo });
+            res.end();
+        }
+        catch (err) {
+            const code = err?.code || 'OAUTH_ERROR';
+            auditAuthAction(req, 'auth-oauth-callback-error', { provider, code, message: String(err?.message || '') });
+            if (code === 'REGISTRATION_DISABLED') {
+                res.writeHead(302, { Location: `/login?error=registration_disabled&provider=${encodeURIComponent(provider)}` });
+            }
+            else if (code === 'IDENTITY_ALREADY_EXISTS') {
+                res.writeHead(302, { Location: `${returnTo}?error=provider_already_linked&provider=${encodeURIComponent(provider)}` });
+            }
+            else if (code === 'INVITE_TOKEN_EXPIRED' || code === 'INVITE_TOKEN_REVOKED' || code === 'INVITE_TOKEN_USED' || code === 'INVITE_TOKEN_INVALID') {
+                res.writeHead(302, { Location: `/login?error=invite_invalid&provider=${encodeURIComponent(provider)}` });
+            }
+            else {
+                res.writeHead(302, { Location: `/login?error=oauth_failed&provider=${encodeURIComponent(provider)}` });
+            }
+            res.end();
+        }
+    });
+    // POST /api/taskforce/auth/oauth/apple/callback
+    // Apple Sign In sends `code`, `state`, `id_token` and optional `user` JSON via form_post.
+    addRoute('POST', '/api/taskforce/auth/oauth/apple/callback', async (req, res) => {
+        if (!requireCloudRuntime(res, 'Apple Sign In'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig?.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth is not enabled.' }));
+            return;
+        }
+        let formData;
+        try {
+            formData = await parseFormBody(req);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Invalid form body.' }));
+            return;
+        }
+        const stateParam = String(formData.state || '').trim();
+        const codeParam = String(formData.code || '').trim();
+        const errorParam = String(formData.error || '').trim();
+        const userJson = formData.user ? String(formData.user).trim() : null;
+        if (errorParam) {
+            auditAuthAction(req, 'auth-oauth-callback-denied', { provider: 'apple', error: errorParam });
+            res.writeHead(302, { Location: '/login?error=oauth_denied&provider=apple' });
+            res.end();
+            return;
+        }
+        if (!stateParam || !codeParam) {
+            res.writeHead(302, { Location: '/login?error=oauth_invalid&provider=apple' });
+            res.end();
+            return;
+        }
+        const stateRecord = core.consumeOAuthLoginState(stateParam);
+        if (!stateRecord || stateRecord.provider !== 'apple') {
+            auditAuthAction(req, 'auth-oauth-state-invalid', { provider: 'apple', stateProvided: true });
+            res.writeHead(302, { Location: '/login?error=oauth_state_invalid&provider=apple' });
+            res.end();
+            return;
+        }
+        const returnTo = sanitizeReturnTo(stateRecord.returnTo);
+        const oauthProviders = core.getGlobalSettings().oauthProviders || {};
+        const appleCfg = (oauthProviders.apple || {});
+        if (!appleCfg.servicesId || !appleCfg.teamId || !appleCfg.keyId || !appleCfg.privateKeyPem) {
+            auditAuthAction(req, 'auth-oauth-callback-error', { provider: 'apple', code: 'APPLE_NOT_CONFIGURED' });
+            res.writeHead(302, { Location: '/login?error=oauth_failed&provider=apple' });
+            res.end();
+            return;
+        }
+        const baseUrl = resolvePublicAuthBaseUrl(req);
+        const redirectUri = `${baseUrl}/api/taskforce/auth/oauth/apple/callback`;
+        try {
+            const profile = await exchangeAppleCode({
+                code: codeParam,
+                redirectUri,
+                servicesId: appleCfg.servicesId,
+                teamId: appleCfg.teamId,
+                keyId: appleCfg.keyId,
+                privateKeyPem: appleCfg.privateKeyPem,
+                userJson,
+            });
+            let userId;
+            let identityId;
+            let isNew = false;
+            if (stateRecord.flowMode === 'link') {
+                if (!stateRecord.userId) {
+                    throw Object.assign(new Error('User ID missing from OAuth link state.'), { code: 'AUTH_REQUIRED', statusCode: 401 });
+                }
+                identityId = core.linkOAuthProviderToUser({
+                    userId: stateRecord.userId,
+                    provider: 'apple',
+                    providerSubject: profile.providerSubject,
+                    providerEmail: profile.email,
+                    providerEmailVerified: profile.emailVerified,
+                    displayNameSnapshot: profile.displayName,
+                    avatarUrlSnapshot: profile.avatarUrl,
+                });
+                userId = stateRecord.userId;
+                isNew = false;
+            }
+            else if (stateRecord.flowMode === 'invite_claim') {
+                if (!stateRecord.inviteToken) {
+                    throw Object.assign(new Error('Invite token missing from OAuth state.'), { code: 'INVITE_TOKEN_MISSING', statusCode: 400 });
+                }
+                const claimed = core.claimInviteWithOAuthProvider({
+                    token: stateRecord.inviteToken,
+                    provider: 'apple',
+                    providerSubject: profile.providerSubject,
+                    providerEmail: profile.email,
+                    providerEmailVerified: profile.emailVerified,
+                    displayNameSnapshot: profile.displayName,
+                    avatarUrlSnapshot: profile.avatarUrl,
+                });
+                userId = claimed.userId;
+                identityId = claimed.identityId;
+                isNew = true;
+            }
+            else {
+                ({ userId, identityId, isNew } = resolveOAuthUser(profile));
+            }
+            const cookie = buildOAuthSessionCookie(req, authConfig, userId, identityId);
+            res.setHeader('Set-Cookie', cookie);
+            auditAuthAction(req, 'auth-oauth-login-success', {
+                provider: 'apple',
+                userId,
+                isNew,
+                flowMode: stateRecord.flowMode,
+                email: profile.email || null,
+            });
+            res.writeHead(302, { Location: returnTo });
+            res.end();
+        }
+        catch (err) {
+            const code = err?.code || 'OAUTH_ERROR';
+            auditAuthAction(req, 'auth-oauth-callback-error', { provider: 'apple', code, message: String(err?.message || '') });
+            if (code === 'REGISTRATION_DISABLED') {
+                res.writeHead(302, { Location: '/login?error=registration_disabled&provider=apple' });
+            }
+            else if (code === 'IDENTITY_ALREADY_EXISTS') {
+                res.writeHead(302, { Location: `${returnTo}?error=provider_already_linked&provider=apple` });
+            }
+            else if (code === 'INVITE_TOKEN_EXPIRED' || code === 'INVITE_TOKEN_REVOKED' || code === 'INVITE_TOKEN_USED' || code === 'INVITE_TOKEN_INVALID') {
+                res.writeHead(302, { Location: '/login?error=invite_invalid&provider=apple' });
+            }
+            else {
+                res.writeHead(302, { Location: '/login?error=oauth_failed&provider=apple' });
+            }
+            res.end();
+        }
+    });
+    // GET /api/taskforce/account/login-methods
+    // Returns the list of active login identities for the authenticated user.
+    addRoute('GET', '/api/taskforce/account/login-methods', async (req, res) => {
+        if (!requireCloudRuntime(res, 'Login methods'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig?.enabled || !hasValidSession(req, authConfig)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = access?.userId || '';
+        if (!userId) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Unable to resolve user.' }));
+            return;
+        }
+        const identities = core.listLoginMethodsForUser(userId);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            methods: identities.map(id => ({
+                provider: id.provider,
+                providerEmail: id.providerEmail || null,
+                displayNameSnapshot: id.displayNameSnapshot || null,
+                avatarUrlSnapshot: id.avatarUrlSnapshot || null,
+                linkedAt: id.linkedAt || id.createdAt,
+                lastLoginAt: id.lastLoginAt || null,
+            }))
+        }));
+    });
+    // DELETE /api/taskforce/account/login-methods/:provider
+    // Unlinks a provider identity from the authenticated user.
+    // Rejects with 409 if it would be the last active login method.
+    addRoute('DELETE', '/api/taskforce/account/login-methods/:provider', async (req, res, params) => {
+        if (!requireCloudRuntime(res, 'Login methods'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig?.enabled || !hasValidSession(req, authConfig)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = access?.userId || '';
+        if (!userId) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Unable to resolve user.' }));
+            return;
+        }
+        const provider = String(params.provider || '').toLowerCase();
+        if (!provider) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Provider is required.' }));
+            return;
+        }
+        try {
+            core.unlinkLoginMethod(userId, provider);
+            auditAuthAction(req, 'account-login-method-unlinked', { userId, provider });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true }));
+        }
+        catch (err) {
+            const code = err?.code || 'UNLINK_ERROR';
+            const status = code === 'LAST_IDENTITY_REQUIRED' ? 409 : resolveErrorStatusCode(err);
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: err?.message || 'Unlink failed.', code }));
+        }
+    });
+    // POST /api/taskforce/account/login-methods/password
+    // Adds (or replaces) a password identity for the authenticated user.
+    // Social-only accounts use this to add a password login method.
+    addRoute('POST', '/api/taskforce/account/login-methods/password', async (req, res) => {
+        if (!requireCloudRuntime(res, 'Login methods'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig?.enabled || !hasValidSession(req, authConfig)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = access?.userId || '';
+        if (!userId) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Unable to resolve user.' }));
+            return;
+        }
+        let body;
+        try {
+            body = await parseJsonBody(req);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Invalid JSON body.' }));
+            return;
+        }
+        const password = String(body?.password || '');
+        try {
+            core.addPasswordToAccount(userId, password);
+            auditAuthAction(req, 'account-password-added', { userId });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true }));
+        }
+        catch (err) {
+            const code = err?.code || 'ADD_PASSWORD_ERROR';
+            const status = resolveErrorStatusCode(err);
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: err?.message || 'Failed to add password.', code }));
+        }
+    });
     // GET /api/taskforce/auth/session - Return current auth/session state
     addRoute('GET', '/api/taskforce/auth/session', async (req, res) => {
+        const routeStartedAt = getRouteTimingNow();
+        const traceId = requestBootstrapTraceId(req);
         const authConfig = context.authConfig;
         const access = authConfig ? resolveRequestAccess(req, authConfig) : null;
         const authenticated = Boolean(authConfig && hasValidSession(req, authConfig));
+        const authResolvedAt = getRouteTimingNow();
         let role = access?.role || authConfig?.defaultRole || 'member';
         let workspaceId = String(access?.workspaceId || authConfig?.defaultWorkspaceId || '').trim();
         let userId = access?.userId || 'anonymous';
@@ -351,11 +1034,16 @@ export function registerAuthRoutes(deps) {
         let displayName = null;
         let avatarUrl = null;
         let betaAccess = true;
+        let betaAccessResolvedAt = authResolvedAt;
+        let userAccessResolvedAt = authResolvedAt;
+        let identityResolvedAt = authResolvedAt;
         if (authenticated && access?.userId) {
             // Keep the session endpoint fast on reload; avatar draft cleanup is best-effort housekeeping.
             void cleanupStaleAvatarDrafts(access.userId).catch(() => { });
             betaAccess = core.getUserBetaAccess(access.userId);
+            betaAccessResolvedAt = getRouteTimingNow();
             const resolved = core.resolveUserAccess(access.userId, workspaceId, role);
+            userAccessResolvedAt = getRouteTimingNow();
             if (resolved) {
                 role = resolved.role;
                 workspaceId = resolved.workspaceId;
@@ -370,9 +1058,9 @@ export function registerAuthRoutes(deps) {
             email = identity?.email || null;
             displayName = identity?.displayName || null;
             avatarUrl = identity?.avatarUrl || null;
+            identityResolvedAt = getRouteTimingNow();
         }
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
+        const payload = {
             authenticated,
             userId,
             workspaceId,
@@ -381,7 +1069,34 @@ export function registerAuthRoutes(deps) {
             displayName,
             avatarUrl,
             betaAccess
-        }));
+        };
+        const serialized = serializeJsonWithTiming(payload, identityResolvedAt);
+        const totalDurationMs = getRouteTimingNow() - routeStartedAt;
+        setServerTimingHeader(res, [
+            { name: 'auth-session', durationMs: totalDurationMs },
+            { name: 'auth-session-cookie', durationMs: authResolvedAt - routeStartedAt },
+            { name: 'auth-session-beta-access', durationMs: betaAccessResolvedAt - authResolvedAt },
+            { name: 'auth-session-user-access', durationMs: userAccessResolvedAt - betaAccessResolvedAt },
+            { name: 'auth-session-identity', durationMs: identityResolvedAt - userAccessResolvedAt },
+            { name: 'auth-session-json', durationMs: serialized.durationMs },
+        ]);
+        logSlowBootstrapRoute({
+            route: '/api/taskforce/auth/session',
+            workspaceId: workspaceId || access?.workspaceId || authConfig?.defaultWorkspaceId || 'default',
+            traceId,
+            durationMs: totalDurationMs,
+            details: {
+                authenticated,
+                payloadBytes: serialized.byteLength,
+                cookieMs: authResolvedAt - routeStartedAt,
+                betaAccessMs: betaAccessResolvedAt - authResolvedAt,
+                userAccessMs: userAccessResolvedAt - betaAccessResolvedAt,
+                identityMs: identityResolvedAt - userAccessResolvedAt,
+                serializeMs: serialized.durationMs,
+            }
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(serialized.body);
     });
     // GET /api/taskforce/auth/admin-session - Return global admin auth/session state
     addRoute('GET', '/api/taskforce/auth/admin-session', async (req, res) => {
@@ -537,6 +1252,63 @@ export function registerAuthRoutes(deps) {
             path: `/api/taskforce/context/${encodeURIComponent(relativePath)}`
         }));
     });
+    addRoute('POST', '/api/taskforce/auth/profile/avatar/upload', async (req, res) => {
+        if (!requireCloudRuntime(res, 'Authentication'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth context unavailable.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = String(access.userId || '').trim();
+        if (!access.authenticated || !userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const draftId = String(requestHeader(req, 'x-taskforce-avatar-draft-id', '') || '').trim();
+        if (!draftId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Avatar draft id is required.', code: 'AVATAR_DRAFT_REQUIRED' }));
+            return;
+        }
+        await cleanupStaleAvatarDrafts(userId);
+        const draft = core.getUserAvatarUploadDraft(userId, draftId);
+        if (!draft || draft.discardedAt) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Avatar draft is invalid or expired.', code: 'AVATAR_DRAFT_INVALID' }));
+            return;
+        }
+        const objectStorageClient = getObjectStorageClient();
+        const effectiveObjectStorage = resolveEffectiveObjectStorageConfig();
+        if (!objectStorageClient || effectiveObjectStorage.provider !== 'r2') {
+            res.writeHead(501, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Avatar uploads require object storage.' }));
+            return;
+        }
+        try {
+            const body = await parseBinaryBody(req, MAX_AVATAR_UPLOAD_BYTES);
+            if (body.length === 0) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Avatar upload body is empty.', code: 'AVATAR_UPLOAD_EMPTY' }));
+                return;
+            }
+            await objectStorageClient.putObject(draft.storageKey, body, draft.mimeType || 'application/octet-stream');
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, draftId, relativePath: draft.storageKey }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: String(error?.message || 'Failed to upload avatar.'),
+                code: error?.code
+            }));
+        }
+    });
     addRoute('POST', '/api/taskforce/auth/profile/avatar/finalize', async (req, res) => {
         if (!requireCloudRuntime(res, 'Authentication'))
             return;
@@ -708,10 +1480,11 @@ export function registerAuthRoutes(deps) {
                     };
                 }
             }
-            const cookie = createSessionTokenCookie(`pwd:${access.userId}`, authConfig, {
+            const cookie = createSessionTokenCookie(`usr:${access.userId}`, authConfig, {
                 role: access.role,
                 workspaceId: access.workspaceId,
                 userId: access.userId,
+                identityId: authResult.access?.identityId,
                 ...resolveSessionCookieAttributesForRequest(req, authConfig)
             });
             auditAuthAction(req, 'auth-login-success', {
@@ -1016,7 +1789,7 @@ export function registerAuthRoutes(deps) {
         const password = String(body?.password || '');
         if (!token || !password) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Token and password are required.' }));
+            res.end(JSON.stringify({ success: false, error: 'Token and password are required.', code: 'TOKEN_PASSWORD_REQUIRED' }));
             return;
         }
         try {
@@ -1041,7 +1814,7 @@ export function registerAuthRoutes(deps) {
                 statusCode: resolveErrorStatusCode(error, 400)
             });
             res.writeHead(resolveErrorStatusCode(error, 400), { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to reset password') }));
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to reset password'), code: error?.code }));
         }
     });
     // === SECTION: Invite flows ===
@@ -1065,6 +1838,18 @@ export function registerAuthRoutes(deps) {
             res.end(JSON.stringify({ success: false, state: details.state, error: 'Invalid or expired invite token.' }));
             return;
         }
+        // Augment availableMethods with enabled OAuth providers for pending_setup invitees
+        const oauthProviders = core.getGlobalSettings().oauthProviders || {};
+        const enabledOAuthProviders = [];
+        if (oauthProviders.google?.enabled)
+            enabledOAuthProviders.push('google');
+        if (oauthProviders.github?.enabled)
+            enabledOAuthProviders.push('github');
+        if (oauthProviders.apple?.enabled)
+            enabledOAuthProviders.push('apple');
+        const augmentedMethods = details.inviteeState === 'pending_setup'
+            ? [...(details.availableMethods || []), ...enabledOAuthProviders.filter(p => !(details.availableMethods || []).includes(p))]
+            : (details.availableMethods || []);
         auditAuthAction(req, 'auth-invite-opened', {
             userId: details.userId,
             email: details.email,
@@ -1078,6 +1863,8 @@ export function registerAuthRoutes(deps) {
             state: details.state,
             email: details.email,
             workspaceId: details.workspaceId,
+            inviteeState: details.inviteeState,
+            availableMethods: augmentedMethods,
             inviteeKind: details.inviteeKind,
             passwordRequired: details.passwordRequired === true
         }));
@@ -1107,10 +1894,11 @@ export function registerAuthRoutes(deps) {
         }
         try {
             const accepted = core.acceptInviteWithToken({ token, password });
-            const cookie = createSessionTokenCookie(`pwd:${accepted.userId}`, authConfig, {
+            const cookie = createSessionTokenCookie(`usr:${accepted.userId}`, authConfig, {
                 role: accepted.role,
                 workspaceId: accepted.workspaceId,
                 userId: accepted.userId,
+                identityId: accepted.identityId,
                 ...resolveSessionCookieAttributesForRequest(req, authConfig)
             });
             res.setHeader('Set-Cookie', cookie);
@@ -1163,11 +1951,12 @@ export function registerAuthRoutes(deps) {
         }
         try {
             const accepted = core.joinInviteWithAuthenticatedUser({ token, userId: access.userId });
-            const sessionId = String(access.sessionId || `pwd:${accepted.userId}`).trim() || `pwd:${accepted.userId}`;
+            const sessionId = String(access.sessionId || `usr:${accepted.userId}`).trim() || `usr:${accepted.userId}`;
             const cookie = createSessionTokenCookie(sessionId, authConfig, {
                 role: accepted.role,
                 workspaceId: accepted.workspaceId,
                 userId: accepted.userId,
+                identityId: access.identityId || undefined,
                 ...resolveSessionCookieAttributesForRequest(req, authConfig)
             });
             res.setHeader('Set-Cookie', cookie);
@@ -1236,7 +2025,7 @@ export function registerAuthRoutes(deps) {
             return;
         }
         try {
-            const userId = requestUserId(req);
+            const userId = resolveAuthenticatedUserId(req);
             const payload = core.getAccountAccessStatus(userId);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify(payload));
@@ -1359,6 +2148,31 @@ export function registerAuthRoutes(deps) {
             res.end(JSON.stringify({ error: String(error?.message || 'Unable to build plan preview'), code: error?.code, details: error?.details }));
         }
     });
+    // GET /api/taskforce/account/ai-profile-seat-usage - Read cloud-authoritative AI seat usage for the current workspace.
+    addRoute('GET', '/api/taskforce/account/ai-profile-seat-usage', async (req, res) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        try {
+            const wid = requestWorkspaceId(req);
+            const aiProfileSeatUsage = core.countAiProfileUsage(wid);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ aiProfileSeatUsage }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: String(error?.message || 'Unable to build AI profile seat usage'),
+                code: error?.code,
+                details: error?.details
+            }));
+        }
+    });
     // === SECTION: Workspace team management (workspace admin) ===
     // GET /api/taskforce/auth/workspace-members - Auth-backed workspace member list for local runtime identity hydration.
     addRoute('GET', '/api/taskforce/auth/workspace-members', async (req, res) => {
@@ -1383,12 +2197,17 @@ export function registerAuthRoutes(deps) {
             res.end(JSON.stringify({ error: 'Authentication required.' }));
             return;
         }
+        const startedAt = getRouteTimingNow();
         const wid = requestWorkspaceId(req);
+        const traceId = requestBootstrapTraceId(req);
+        const adminRoleStartedAt = getRouteTimingNow();
         const includeProfileToken = context.authConfig?.enabled !== true || ensureWorkspaceAdminRole(req);
-        const workspaceUsers = core
-            .listWorkspaceUsers(wid)
-            .filter((user) => String(user.status || '').trim().toLowerCase() === 'active' && user.disabled !== true)
-            .map((user) => ({
+        const adminRoleResolvedAt = getRouteTimingNow();
+        const usersStartedAt = getRouteTimingNow();
+        const activeWorkspaceUsers = core.listWorkspaceUsers(wid)
+            .filter((user) => String(user.status || '').trim().toLowerCase() === 'active' && user.disabled !== true);
+        const usersLoadedAt = getRouteTimingNow();
+        const workspaceUsers = activeWorkspaceUsers.map((user) => ({
             value: user.userId,
             label: String(user.displayName || user.email || user.userId).trim() || user.userId,
             icon: 'User',
@@ -1397,11 +2216,15 @@ export function registerAuthRoutes(deps) {
             userId: user.userId,
             email: user.email,
             displayName: user.displayName ?? null,
+            avatarUrl: user.avatarUrl ?? null,
             status: user.status,
             disabled: user.disabled === true
         }));
+        const usersMappedAt = getRouteTimingNow();
+        const aiProfileDiagnostics = { metadataBackfillCount: 0 };
+        const aiProfilesStartedAt = getRouteTimingNow();
         const aiProfiles = core
-            .listAiProfiles(wid)
+            .listAiProfiles(wid, { diagnostics: aiProfileDiagnostics })
             .map((profile) => ({
             value: profile.id,
             label: profile.name,
@@ -1409,19 +2232,90 @@ export function registerAuthRoutes(deps) {
             username: profile.username,
             icon: profile.icon,
             color: profile.color,
+            avatarUrl: profile.avatarUrl ?? null,
+            avatarSourceUrl: profile.avatarSourceUrl ?? null,
             kind: 'agent',
             description: profile.description ?? null,
             role: profile.role ?? null,
             provider: profile.provider ?? null,
             model: profile.model ?? null,
             surfaceType: profile.surfaceType ?? null,
+            seatScope: profile.seatScope ?? null,
+            archivedAt: profile.archivedAt ?? null,
             createdAt: profile.createdAt,
             updatedAt: profile.updatedAt,
             lastActiveAt: profile.lastActiveAt ?? null
         }));
+        const aiProfilesLoadedAt = getRouteTimingNow();
+        const seatUsageStartedAt = getRouteTimingNow();
+        const aiProfileSeatUsage = core.countAiProfileUsage(wid);
+        const seatUsageLoadedAt = getRouteTimingNow();
         const assignees = [...workspaceUsers, ...aiProfiles];
+        const serializeStartedAt = getRouteTimingNow();
+        const serialized = serializeJsonWithTiming({ assignees, aiProfileSeatUsage }, serializeStartedAt);
+        const totalDurationMs = Math.max(0, getRouteTimingNow() - startedAt);
+        setServerTimingHeader(res, [
+            { name: 'assignee-options', durationMs: totalDurationMs },
+            { name: 'assignee-options-admin-role', durationMs: adminRoleResolvedAt - adminRoleStartedAt },
+            { name: 'assignee-options-users', durationMs: usersLoadedAt - usersStartedAt },
+            { name: 'assignee-options-users-map', durationMs: usersMappedAt - usersLoadedAt },
+            { name: 'assignee-options-ai-profiles', durationMs: aiProfilesLoadedAt - aiProfilesStartedAt },
+            { name: 'assignee-options-seat-usage', durationMs: seatUsageLoadedAt - seatUsageStartedAt },
+            { name: 'assignee-options-json', durationMs: serialized.durationMs },
+        ]);
+        logSlowBootstrapRoute({
+            route: '/api/taskforce/workspace/assignee-options',
+            workspaceId: wid,
+            traceId,
+            durationMs: totalDurationMs,
+            details: {
+                humanAssigneeCount: workspaceUsers.length,
+                workspaceUserCount: activeWorkspaceUsers.length,
+                aiProfileCount: aiProfiles.length,
+                metadataBackfillCount: aiProfileDiagnostics.metadataBackfillCount,
+                responseBytes: serialized.byteLength,
+                adminRoleMs: Math.max(0, adminRoleResolvedAt - adminRoleStartedAt),
+                listWorkspaceUsersMs: Math.max(0, usersLoadedAt - usersStartedAt),
+                workspaceUsersMapMs: Math.max(0, usersMappedAt - usersLoadedAt),
+                listAiProfilesMs: Math.max(0, aiProfilesLoadedAt - aiProfilesStartedAt),
+                countAiProfileUsageMs: Math.max(0, seatUsageLoadedAt - seatUsageStartedAt),
+                jsonSerializeMs: serialized.durationMs,
+            },
+        });
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ assignees }));
+        res.end(serialized.body);
+    });
+    // POST /api/taskforce/workspace/ai-profiles/avatar - Assign or clear an AI profile avatar image.
+    addRoute('POST', '/api/taskforce/workspace/ai-profiles/avatar', async (req, res) => {
+        if (!ensureWorkspaceAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const wid = requestWorkspaceId(req);
+        const profileId = String(body?.profileId || '').trim();
+        const avatarUrl = body?.avatarUrl === null ? null : String(body?.avatarUrl || '').trim();
+        const avatarSourceUrl = body?.avatarSourceUrl === undefined
+            ? undefined
+            : body?.avatarSourceUrl === null
+                ? null
+                : String(body?.avatarSourceUrl || '').trim();
+        if (!profileId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'profileId is required.' }));
+            return;
+        }
+        try {
+            const profile = core.updateAiProfileAvatar({ workspaceId: wid, profileId, avatarUrl, avatarSourceUrl });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, profile }));
+        }
+        catch (err) {
+            const status = err?.statusCode ?? 500;
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: err?.message ?? 'Failed to update AI profile avatar.' }));
+        }
     });
     // POST /api/taskforce/workspace/ai-profiles/merge - Merge a duplicate AI profile into another, reassigning all references.
     addRoute('POST', '/api/taskforce/workspace/ai-profiles/merge', async (req, res) => {
@@ -1450,6 +2344,41 @@ export function registerAuthRoutes(deps) {
             res.end(JSON.stringify({ error: err?.message ?? 'Merge failed.' }));
         }
     });
+    // POST /api/taskforce/workspace/ai-profiles/archive - Remove an AI profile from the active roster without deleting its history.
+    addRoute('POST', '/api/taskforce/workspace/ai-profiles/archive', async (req, res) => {
+        if (!ensureWorkspaceAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const wid = requestWorkspaceId(req);
+        const profileId = String(body.profileId || '').trim();
+        const reason = String(body.reason || '').trim() || 'manual_archive';
+        if (!profileId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'profileId is required.' }));
+            return;
+        }
+        try {
+            const profile = core.archiveAiProfile({
+                workspaceId: wid,
+                profileId,
+                archivedBy: requestUserId(req),
+                reason
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ profile }));
+        }
+        catch (err) {
+            const status = err?.statusCode ?? 500;
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: err?.message ?? 'Failed to archive AI profile.',
+                details: err?.details ?? null
+            }));
+        }
+    });
     // GET /api/taskforce/admin/users - List workspace users for team management.
     addRoute('GET', '/api/taskforce/admin/users', async (req, res) => {
         if (!ensureWorkspaceAdminRole(req)) {
@@ -1458,8 +2387,9 @@ export function registerAuthRoutes(deps) {
             return;
         }
         const wid = requestWorkspaceId(req);
+        const actorUserId = resolveAuthenticatedUserId(req);
         const gate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.team_management'
         });
@@ -1474,13 +2404,14 @@ export function registerAuthRoutes(deps) {
     });
     // POST /api/taskforce/admin/users/invite - Invite a user into a workspace.
     addRoute('POST', '/api/taskforce/admin/users/invite', async (req, res) => {
-        if (!ensureWorkspaceAdminRole(req)) {
+        const body = await parseJsonBody(req);
+        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        if (!ensureWorkspaceAdminRole(req, wid)) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
             return;
         }
-        const body = await parseJsonBody(req);
-        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        const actorUserId = resolveAuthenticatedUserId(req);
         const email = String(body?.email || '').trim().toLowerCase();
         const role = String(body?.role || 'member').trim().toLowerCase();
         const permissionMode = String(body?.permissionMode || 'read-write').trim().toLowerCase();
@@ -1490,7 +2421,7 @@ export function registerAuthRoutes(deps) {
             return;
         }
         const inviteGate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.invites'
         });
@@ -1513,8 +2444,8 @@ export function registerAuthRoutes(deps) {
             let inviteEmailError = null;
             if (inviteToken.token) {
                 const workspace = core.getWorkspaceProfile(wid);
-                const actorIdentity = core.resolveUserIdentity(requestUserId(req));
-                const inviterEmailOrLabel = String(actorIdentity?.email || requestUserId(req) || 'Taskforce').trim();
+                const actorIdentity = core.resolveUserIdentity(actorUserId);
+                const inviterEmailOrLabel = String(actorIdentity?.email || actorUserId || 'Taskforce').trim();
                 const delivery = await deliverInviteEmail(email, inviteToken.token, req, {
                     workspaceName: String(workspace?.name || wid),
                     inviterEmailOrLabel
@@ -1529,7 +2460,7 @@ export function registerAuthRoutes(deps) {
                 role,
                 permissionMode: role === 'member' ? (permissionMode === 'read-only' ? 'read-only' : 'read-write') : 'read-write',
                 inviteEmailSent
-            });
+            }, wid);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
                 success: true,
@@ -1546,13 +2477,14 @@ export function registerAuthRoutes(deps) {
     });
     // PATCH /api/taskforce/admin/users/:id/role - Update workspace role for a user.
     addRoute('PATCH', '/api/taskforce/admin/users/:id/role', async (req, res, params) => {
-        if (!ensureWorkspaceAdminRole(req)) {
+        const body = await parseJsonBody(req);
+        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        if (!ensureWorkspaceAdminRole(req, wid)) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
             return;
         }
-        const body = await parseJsonBody(req);
-        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        const actorUserId = resolveAuthenticatedUserId(req);
         const role = String(body?.role || '').trim().toLowerCase();
         if (role !== 'owner' && role !== 'admin' && role !== 'member') {
             res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -1560,7 +2492,7 @@ export function registerAuthRoutes(deps) {
             return;
         }
         const gate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.team_management'
         });
@@ -1576,7 +2508,7 @@ export function registerAuthRoutes(deps) {
                 res.end(JSON.stringify({ error: 'User membership not found.' }));
                 return;
             }
-            auditAuthAction(req, 'update-workspace-user-role', { workspaceId: wid, targetUserId: params.id, role });
+            auditAuthAction(req, 'update-workspace-user-role', { workspaceId: wid, targetUserId: params.id, role }, wid);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: true }));
         }
@@ -1588,13 +2520,14 @@ export function registerAuthRoutes(deps) {
     });
     // PATCH /api/taskforce/admin/users/:id/permission-mode - Update member permission mode.
     addRoute('PATCH', '/api/taskforce/admin/users/:id/permission-mode', async (req, res, params) => {
-        if (!ensureWorkspaceAdminRole(req)) {
+        const body = await parseJsonBody(req);
+        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        if (!ensureWorkspaceAdminRole(req, wid)) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
             return;
         }
-        const body = await parseJsonBody(req);
-        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        const actorUserId = resolveAuthenticatedUserId(req);
         const mode = String(body?.mode || '').trim().toLowerCase();
         if (mode !== 'read-only' && mode !== 'read-write') {
             res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -1602,7 +2535,7 @@ export function registerAuthRoutes(deps) {
             return;
         }
         const gate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.team_management'
         });
@@ -1618,7 +2551,7 @@ export function registerAuthRoutes(deps) {
                 res.end(JSON.stringify({ error: 'User membership not found.' }));
                 return;
             }
-            auditAuthAction(req, 'update-workspace-user-permission-mode', { workspaceId: wid, targetUserId: params.id, mode });
+            auditAuthAction(req, 'update-workspace-user-permission-mode', { workspaceId: wid, targetUserId: params.id, mode }, wid);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: true }));
         }
@@ -1630,16 +2563,17 @@ export function registerAuthRoutes(deps) {
     });
     // PATCH /api/taskforce/admin/users/:id/disable - Disable or reactivate a workspace user.
     addRoute('PATCH', '/api/taskforce/admin/users/:id/disable', async (req, res, params) => {
-        if (!ensureWorkspaceAdminRole(req)) {
+        const body = await parseJsonBody(req);
+        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        if (!ensureWorkspaceAdminRole(req, wid)) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
             return;
         }
-        const body = await parseJsonBody(req);
-        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        const actorUserId = resolveAuthenticatedUserId(req);
         const disabled = body?.disabled === true;
         const gate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.team_management'
         });
@@ -1655,7 +2589,7 @@ export function registerAuthRoutes(deps) {
                 res.end(JSON.stringify({ error: 'User membership not found.' }));
                 return;
             }
-            auditAuthAction(req, 'set-workspace-user-disabled', { workspaceId: wid, targetUserId: params.id, disabled });
+            auditAuthAction(req, 'set-workspace-user-disabled', { workspaceId: wid, targetUserId: params.id, disabled }, wid);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: true }));
         }
@@ -1667,15 +2601,16 @@ export function registerAuthRoutes(deps) {
     });
     // POST /api/taskforce/admin/users/:id/invite/revoke - Revoke invite acceptance token.
     addRoute('POST', '/api/taskforce/admin/users/:id/invite/revoke', async (req, res, params) => {
-        if (!ensureWorkspaceAdminRole(req)) {
+        const body = await parseJsonBody(req);
+        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        if (!ensureWorkspaceAdminRole(req, wid)) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
             return;
         }
-        const body = await parseJsonBody(req);
-        const wid = String(body?.workspaceId || requestWorkspaceId(req)).trim() || 'default';
+        const actorUserId = resolveAuthenticatedUserId(req);
         const gate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.team_management'
         });
@@ -1685,21 +2620,22 @@ export function registerAuthRoutes(deps) {
             return;
         }
         const revoked = core.revokeInviteAcceptanceForUser(params.id);
-        auditAuthAction(req, 'revoke-invite', { workspaceId: wid, targetUserId: params.id, revoked: revoked.revoked });
+        auditAuthAction(req, 'revoke-invite', { workspaceId: wid, targetUserId: params.id, revoked: revoked.revoked }, wid);
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ success: true, revoked: revoked.revoked }));
     });
     // DELETE /api/taskforce/admin/users/:id - Remove workspace membership.
     addRoute('DELETE', '/api/taskforce/admin/users/:id', async (req, res, params) => {
-        if (!ensureWorkspaceAdminRole(req)) {
+        const reqUrl = new URL(req.url || '/api/taskforce/admin/users/:id', 'http://localhost');
+        const wid = String(reqUrl.searchParams.get('workspaceId') || requestWorkspaceId(req)).trim() || 'default';
+        if (!ensureWorkspaceAdminRole(req, wid)) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: owner or admin role required.' }));
             return;
         }
-        const reqUrl = new URL(req.url || '/api/taskforce/admin/users/:id', 'http://localhost');
-        const wid = String(reqUrl.searchParams.get('workspaceId') || requestWorkspaceId(req)).trim() || 'default';
+        const actorUserId = resolveAuthenticatedUserId(req);
         const gate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.team_management'
         });
@@ -1715,7 +2651,7 @@ export function registerAuthRoutes(deps) {
                 res.end(JSON.stringify({ error: 'User membership not found.' }));
                 return;
             }
-            auditAuthAction(req, 'remove-workspace-user', { workspaceId: wid, targetUserId: params.id });
+            auditAuthAction(req, 'remove-workspace-user', { workspaceId: wid, targetUserId: params.id }, wid);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: true }));
         }
@@ -1733,8 +2669,9 @@ export function registerAuthRoutes(deps) {
             return;
         }
         const wid = requestWorkspaceId(req);
+        const actorUserId = resolveAuthenticatedUserId(req);
         const gate = core.evaluateFeatureAccess({
-            userId: requestUserId(req),
+            userId: actorUserId,
             workspaceId: wid,
             featureKey: 'collaboration.team_management'
         });