@lastshotlabs/bunshot 0.0.27 → 0.0.28

package/dist/packages/bunshot-auth/src/routes/oauth.js

@@ -0,0 +1,1727 @@
+import { getAuthCookieOptions } from '../lib/cookieOptions';
+import { isProd } from '../lib/env';
+import { generateCodeVerifier, generateState } from '../lib/oauth';
+import { consumeOAuthCode, storeOAuthCode } from '../lib/oauthCode';
+import { consumeReauthConfirmation, storeReauthConfirmation } from '../lib/oauthReauth';
+import { refreshCsrfToken } from '../middleware/csrf';
+import { userAuth } from '../middleware/userAuth';
+import { ErrorResponse as OAuthErrorResponse } from '../schemas/error';
+import { createSessionForUser, emitLoginSuccess, runPreLoginHook } from '../services/auth';
+import { decodeIdToken } from 'arctic';
+import { setCookie } from 'hono/cookie';
+import { z } from 'zod';
+import { createRoute, withSecurity } from '../../../bunshot-core/src/index.js';
+import { createRouter } from '../../../bunshot-core/src/index.js';
+import { HttpError } from '../../../bunshot-core/src/index.js';
+import { COOKIE_REFRESH_TOKEN, COOKIE_TOKEN } from '../../../bunshot-core/src/index.js';
+import { getClientIp } from '../../../bunshot-core/src/index.js';
+const hookCtx = (c) => ({
+    ip: getClientIp(c) !== 'unknown' ? getClientIp(c) : undefined,
+    userAgent: c.req.header('user-agent') ?? undefined,
+    requestId: c.get('requestId'),
+});
+const tags = ['OAuth'];
+// `postLoginRedirect` is always sourced from server-side config (passed into
+// `createOAuthRouter` at startup) and is never derived from user-supplied input
+// or OAuth callback query parameters. No runtime allowlist validation is required
+// because the value is not attacker-controlled. The `auth.oauth.allowedRedirectUrls`
+// config is available for consuming apps that want to enforce an explicit allowlist
+// at the framework level if they ever pass a dynamic value here.
+const finishOAuth = async (c, runtime, provider, providerId, profile, postLoginRedirect) => {
+    const { adapter, eventBus, config } = runtime;
+    if (!adapter.findOrCreateByProvider) {
+        return c.json({ error: 'Auth adapter does not support social login' }, 500);
+    }
+    const identifier = profile.email ?? providerId;
+    const ctx = hookCtx(c);
+    try {
+        // Fire preLogin before the adapter so OAuth users are subject to the same
+        // access control as email/password users (fixes: #30).
+        // preLogin runs for all OAuth sign-ins (new and returning) — a single hook
+        // covers the allowlist case. preRegister is intentionally omitted: by the
+        // time we know if user.created is true, the record already exists, so it
+        // cannot gate registration. preLogin is the correct and sufficient gate.
+        await runPreLoginHook(identifier, runtime, ctx);
+        const user = await adapter.findOrCreateByProvider(provider, providerId, profile);
+        if (user.created) {
+            const role = config.defaultRole;
+            if (role && adapter.setRoles)
+                await adapter.setRoles(user.id, [role]);
+        }
+        const metadata = {
+            ipAddress: getClientIp(c),
+            userAgent: c.req.header('user-agent') ?? undefined,
+        };
+        const session = await createSessionForUser(user.id, runtime, metadata, ctx);
+        const { token, refreshToken: refreshTokenValue, sessionId } = session;
+        emitLoginSuccess(user.id, sessionId, runtime);
+        // Store a one-time authorization code instead of exposing the token in the redirect URL.
+        // The client exchanges this code via POST /auth/oauth/exchange to get the session token.
+        const code = await storeOAuthCode(runtime.repos.oauthCode, {
+            token,
+            userId: user.id,
+            email: profile.email,
+            refreshToken: refreshTokenValue,
+        }, runtime.dataEncryptionKeys);
+        try {
+            const url = new URL(postLoginRedirect);
+            url.searchParams.set('code', code);
+            if (profile.email)
+                url.searchParams.set('user', profile.email);
+            return c.redirect(url.toString());
+        }
+        catch {
+            // Relative path fallback
+            const sep = postLoginRedirect.includes('?') ? '&' : '?';
+            const userParam = profile.email ? `&user=${encodeURIComponent(profile.email)}` : '';
+            return c.redirect(`${postLoginRedirect}${sep}code=${code}${userParam}`);
+        }
+    }
+    catch (err) {
+        const message = err instanceof HttpError ? err.message : 'Authentication failed';
+        const sep = postLoginRedirect.includes('?') ? '&' : '?';
+        return c.redirect(`${postLoginRedirect}${sep}error=${encodeURIComponent(message)}`);
+    }
+};
+export const createOAuthRouter = (providers, postLoginRedirect, runtime, rateLimit) => {
+    const { adapter, eventBus } = runtime;
+    const oauthUnlinkOpts = {
+        windowMs: rateLimit?.oauthUnlink?.windowMs ?? 60 * 60 * 1000,
+        max: rateLimit?.oauthUnlink?.max ?? 5,
+    };
+    const getConfig = () => runtime.config;
+    const unlinkVerificationSchema = z.object({
+        method: z
+            .enum(['totp', 'emailOtp', 'webauthn', 'password', 'recovery'])
+            .optional()
+            .describe('Verification method to use.'),
+        code: z.string().optional().describe('TOTP code, email OTP code, or recovery code.'),
+        password: z.string().optional().describe('Account password.'),
+        reauthToken: z
+            .string()
+            .optional()
+            .describe('Reauth challenge token (required for emailOtp and webauthn methods).'),
+        webauthnResponse: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('WebAuthn assertion response (required for webauthn method).'),
+    });
+    async function verifyUnlinkFactor(userId, sessionId, body) {
+        const hasPassword = adapter.hasPassword ? await adapter.hasPassword(userId) : false;
+        const mfaMethods = getConfig().mfa && adapter.getMfaMethods ? await adapter.getMfaMethods(userId) : [];
+        if (!hasPassword && mfaMethods.length === 0)
+            return null;
+        const method = body.method ?? (body.password ? 'password' : body.code ? 'totp' : undefined);
+        if (!method) {
+            return {
+                error: 'Verification is required to unlink this provider. Provide method and credentials.',
+                status: 400,
+            };
+        }
+        const { verifyAnyFactor } = await import('../services/mfa');
+        const valid = await verifyAnyFactor(userId, sessionId, runtime, {
+            method,
+            code: body.code,
+            password: body.password,
+            reauthToken: body.reauthToken,
+            webauthnResponse: body.webauthnResponse,
+        });
+        if (!valid)
+            return { error: 'Invalid verification', status: 401 };
+        return null;
+    }
+    const cookieOptions = (maxAge) => getAuthCookieOptions(isProd(), runtime.config, maxAge);
+    const oauthProviders = runtime.oauth.providers;
+    const oauthStateStore = runtime.oauth.stateStore;
+    const router = createRouter();
+    const storeOAuthState = (state, codeVerifier, linkUserId) => oauthStateStore.store(state, codeVerifier, linkUserId);
+    const consumeOAuthState = (state) => oauthStateStore.consume(state);
+    const getGoogle = () => {
+        if (!oauthProviders.google)
+            throw new Error('Google OAuth not configured');
+        return oauthProviders.google;
+    };
+    const getApple = () => {
+        if (!oauthProviders.apple)
+            throw new Error('Apple OAuth not configured');
+        return oauthProviders.apple;
+    };
+    const getMicrosoft = () => {
+        if (!oauthProviders.microsoft)
+            throw new Error('Microsoft Entra ID OAuth not configured');
+        return oauthProviders.microsoft;
+    };
+    const getGitHub = () => {
+        if (!oauthProviders.github)
+            throw new Error('GitHub OAuth not configured');
+        return oauthProviders.github;
+    };
+    const getLinkedIn = () => {
+        if (!oauthProviders.linkedin)
+            throw new Error('LinkedIn OAuth not configured');
+        return oauthProviders.linkedin;
+    };
+    const getTwitter = () => {
+        if (!oauthProviders.twitter)
+            throw new Error('Twitter OAuth not configured');
+        return oauthProviders.twitter;
+    };
+    const getGitLab = () => {
+        if (!oauthProviders.gitlab)
+            throw new Error('GitLab OAuth not configured');
+        return oauthProviders.gitlab;
+    };
+    const getSlack = () => {
+        if (!oauthProviders.slack)
+            throw new Error('Slack OAuth not configured');
+        return oauthProviders.slack;
+    };
+    const getBitbucket = () => {
+        if (!oauthProviders.bitbucket)
+            throw new Error('Bitbucket OAuth not configured');
+        return oauthProviders.bitbucket;
+    };
+    // ─── Google ───────────────────────────────────────────────────────────────
+    if (providers.includes('google')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/google',
+            summary: 'Initiate Google OAuth',
+            description: "Redirects the user to Google's consent screen to begin the OAuth login flow. After the user authorizes, Google redirects back to `/auth/google/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Google's OAuth consent screen." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            const codeVerifier = generateCodeVerifier();
+            await storeOAuthState(state, codeVerifier);
+            const url = getGoogle().createAuthorizationURL(state, codeVerifier, [
+                'openid',
+                'profile',
+                'email',
+            ]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/google/callback',
+            summary: 'Google OAuth callback',
+            description: 'Handles the redirect from Google after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from Google.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored?.codeVerifier)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getGoogle().validateAuthorizationCode(code, stored.codeVerifier);
+            const info = (await fetch('https://openidconnect.googleapis.com/v1/userinfo', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'google', info.sub);
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'google' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=google`);
+            }
+            return finishOAuth(c, runtime, 'google', info.sub, { email: info.email, name: info.name, avatarUrl: info.picture }, postLoginRedirect);
+        });
+        router.use('/auth/google/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/google/link',
+            summary: 'Link Google account',
+            description: "Initiates an OAuth flow to link a Google account to the authenticated user. Requires a valid session. Redirects to Google's consent screen.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Google's OAuth consent screen." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            const codeVerifier = generateCodeVerifier();
+            await storeOAuthState(state, codeVerifier, c.get('authUserId'));
+            const url = getGoogle().createAuthorizationURL(state, codeVerifier, [
+                'openid',
+                'profile',
+                'email',
+            ]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/google/link',
+            summary: 'Unlink Google account',
+            description: 'Removes the linked Google OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'Google account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'google');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'google' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── Apple ────────────────────────────────────────────────────────────────
+    if (providers.includes('apple')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/apple',
+            summary: 'Initiate Apple OAuth',
+            description: "Redirects the user to Apple's sign-in page to begin the OAuth login flow. After the user authorizes, Apple posts back to `/auth/apple/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Apple's OAuth sign-in page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state);
+            const url = getApple().createAuthorizationURL(state, ['name', 'email']);
+            return c.redirect(url.toString());
+        });
+        // Apple sends a POST with form data to the callback URL
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/apple/callback',
+            summary: 'Apple OAuth callback',
+            description: 'Handles the POST redirect from Apple after user authorization. Apple sends form-encoded data containing the authorization code and state. Validates the OAuth state, exchanges the code for tokens, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const form = await c.req.formData();
+            const code = form.get('code');
+            const state = form.get('state');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getApple().validateAuthorizationCode(code);
+            const claims = decodeIdToken(tokens.idToken());
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'apple', claims.sub);
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'apple' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=apple`);
+            }
+            // Apple only sends name on the very first sign-in
+            const userJSON = form.get('user');
+            const userInfo = userJSON
+                ? JSON.parse(userJSON)
+                : {};
+            const name = userInfo.name
+                ? `${userInfo.name.firstName ?? ''} ${userInfo.name.lastName ?? ''}`.trim() || undefined
+                : undefined;
+            return finishOAuth(c, runtime, 'apple', claims.sub, { email: claims.email, name }, postLoginRedirect);
+        });
+        router.use('/auth/apple/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/apple/link',
+            summary: 'Link Apple account',
+            description: "Initiates an OAuth flow to link an Apple account to the authenticated user. Requires a valid session. Redirects to Apple's sign-in page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Apple's OAuth sign-in page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state, undefined, c.get('authUserId'));
+            const url = getApple().createAuthorizationURL(state, ['name', 'email']);
+            return c.redirect(url.toString());
+        });
+    }
+    // ─── Microsoft ──────────────────────────────────────────────────────────
+    if (providers.includes('microsoft')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/microsoft',
+            summary: 'Initiate Microsoft OAuth',
+            description: "Redirects the user to Microsoft's sign-in page to begin the OAuth login flow. After the user authorizes, Microsoft redirects back to `/auth/microsoft/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Microsoft's OAuth sign-in page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            const codeVerifier = generateCodeVerifier();
+            await storeOAuthState(state, codeVerifier);
+            const url = getMicrosoft().createAuthorizationURL(state, codeVerifier, [
+                'openid',
+                'profile',
+                'email',
+            ]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/microsoft/callback',
+            summary: 'Microsoft OAuth callback',
+            description: 'Handles the redirect from Microsoft after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from Microsoft.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored?.codeVerifier)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getMicrosoft().validateAuthorizationCode(code, stored.codeVerifier);
+            const info = (await fetch('https://graph.microsoft.com/v1.0/me', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'microsoft', info.id);
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'microsoft' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=microsoft`);
+            }
+            return finishOAuth(c, runtime, 'microsoft', info.id, { email: info.mail ?? info.userPrincipalName, name: info.displayName }, postLoginRedirect);
+        });
+        router.use('/auth/microsoft/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/microsoft/link',
+            summary: 'Link Microsoft account',
+            description: "Initiates an OAuth flow to link a Microsoft account to the authenticated user. Requires a valid session. Redirects to Microsoft's sign-in page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Microsoft's OAuth sign-in page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            const codeVerifier = generateCodeVerifier();
+            await storeOAuthState(state, codeVerifier, c.get('authUserId'));
+            const url = getMicrosoft().createAuthorizationURL(state, codeVerifier, [
+                'openid',
+                'profile',
+                'email',
+            ]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/microsoft/link',
+            summary: 'Unlink Microsoft account',
+            description: 'Removes the linked Microsoft OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'Microsoft account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'microsoft');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'microsoft' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── GitHub ────────────────────────────────────────────────────────────
+    if (providers.includes('github')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/github',
+            summary: 'Initiate GitHub OAuth',
+            description: "Redirects the user to GitHub's authorization page to begin the OAuth login flow. After the user authorizes, GitHub redirects back to `/auth/github/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to GitHub's OAuth authorization page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state);
+            const url = getGitHub().createAuthorizationURL(state, ['read:user', 'user:email']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/github/callback',
+            summary: 'GitHub OAuth callback',
+            description: 'Handles the redirect from GitHub after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from GitHub.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getGitHub().validateAuthorizationCode(code);
+            const headers = {
+                Authorization: `Bearer ${tokens.accessToken()}`,
+                'User-Agent': 'bunshot',
+            };
+            const info = (await fetch('https://api.github.com/user', { headers }).then(r => r.json()));
+            // GitHub may not return email on /user if it's private — fetch from /user/emails
+            let email = info.email;
+            if (!email) {
+                const emails = (await fetch('https://api.github.com/user/emails', { headers }).then(r => r.json()));
+                email =
+                    emails.find(e => e.primary && e.verified)?.email ?? emails.find(e => e.verified)?.email;
+            }
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'github', String(info.id));
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'github' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=github`);
+            }
+            return finishOAuth(c, runtime, 'github', String(info.id), { email, name: info.name, avatarUrl: info.avatar_url }, postLoginRedirect);
+        });
+        router.use('/auth/github/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/github/link',
+            summary: 'Link GitHub account',
+            description: "Initiates an OAuth flow to link a GitHub account to the authenticated user. Requires a valid session. Redirects to GitHub's authorization page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to GitHub's OAuth authorization page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state, undefined, c.get('authUserId'));
+            const url = getGitHub().createAuthorizationURL(state, ['read:user', 'user:email']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/github/link',
+            summary: 'Unlink GitHub account',
+            description: 'Removes the linked GitHub OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'GitHub account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'github');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'github' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── LinkedIn ────────────────────────────────────────────────────────────
+    if (providers.includes('linkedin')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/linkedin',
+            summary: 'Initiate LinkedIn OAuth',
+            description: "Redirects the user to LinkedIn's authorization page to begin the OAuth login flow. After the user authorizes, LinkedIn redirects back to `/auth/linkedin/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to LinkedIn's OAuth authorization page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state);
+            const url = getLinkedIn().createAuthorizationURL(state, ['openid', 'profile', 'email']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/linkedin/callback',
+            summary: 'LinkedIn OAuth callback',
+            description: 'Handles the redirect from LinkedIn after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from LinkedIn.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getLinkedIn().validateAuthorizationCode(code);
+            const info = (await fetch('https://api.linkedin.com/v2/userinfo', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'linkedin', info.sub);
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'linkedin' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=linkedin`);
+            }
+            return finishOAuth(c, runtime, 'linkedin', info.sub, { email: info.email, name: info.name, avatarUrl: info.picture }, postLoginRedirect);
+        });
+        router.use('/auth/linkedin/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/linkedin/link',
+            summary: 'Link LinkedIn account',
+            description: "Initiates an OAuth flow to link a LinkedIn account to the authenticated user. Requires a valid session. Redirects to LinkedIn's authorization page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to LinkedIn's OAuth authorization page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state, undefined, c.get('authUserId'));
+            const url = getLinkedIn().createAuthorizationURL(state, ['openid', 'profile', 'email']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/linkedin/link',
+            summary: 'Unlink LinkedIn account',
+            description: 'Removes the linked LinkedIn OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'LinkedIn account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'linkedin');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'linkedin' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── Twitter/X ───────────────────────────────────────────────────────────
+    if (providers.includes('twitter')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/twitter',
+            summary: 'Initiate Twitter/X OAuth',
+            description: "Redirects the user to Twitter/X's authorization page to begin the OAuth login flow. After the user authorizes, Twitter redirects back to `/auth/twitter/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Twitter/X's OAuth authorization page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            const codeVerifier = generateCodeVerifier();
+            await storeOAuthState(state, codeVerifier);
+            const url = getTwitter().createAuthorizationURL(state, codeVerifier, [
+                'tweet.read',
+                'users.read',
+            ]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/twitter/callback',
+            summary: 'Twitter/X OAuth callback',
+            description: 'Handles the redirect from Twitter/X after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from Twitter/X.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored?.codeVerifier)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getTwitter().validateAuthorizationCode(code, stored.codeVerifier);
+            const info = (await fetch('https://api.twitter.com/2/users/me?user.fields=name,profile_image_url', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            const user = info.data;
+            if (!user?.id)
+                return c.json({ error: 'Failed to retrieve Twitter user info' }, 400);
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'twitter', user.id);
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'twitter' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=twitter`);
+            }
+            return finishOAuth(c, runtime, 'twitter', user.id, { name: user.name, avatarUrl: user.profile_image_url }, postLoginRedirect);
+        });
+        router.use('/auth/twitter/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/twitter/link',
+            summary: 'Link Twitter/X account',
+            description: "Initiates an OAuth flow to link a Twitter/X account to the authenticated user. Requires a valid session. Redirects to Twitter/X's authorization page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Twitter/X's OAuth authorization page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            const codeVerifier = generateCodeVerifier();
+            await storeOAuthState(state, codeVerifier, c.get('authUserId'));
+            const url = getTwitter().createAuthorizationURL(state, codeVerifier, [
+                'tweet.read',
+                'users.read',
+            ]);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/twitter/link',
+            summary: 'Unlink Twitter/X account',
+            description: 'Removes the linked Twitter/X OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'Twitter/X account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'twitter');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'twitter' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── GitLab ──────────────────────────────────────────────────────────────
+    if (providers.includes('gitlab')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/gitlab',
+            summary: 'Initiate GitLab OAuth',
+            description: "Redirects the user to GitLab's authorization page to begin the OAuth login flow. After the user authorizes, GitLab redirects back to `/auth/gitlab/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to GitLab's OAuth authorization page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state);
+            const url = getGitLab().createAuthorizationURL(state, ['read_user']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/gitlab/callback',
+            summary: 'GitLab OAuth callback',
+            description: 'Handles the redirect from GitLab after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from GitLab.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getGitLab().validateAuthorizationCode(code);
+            const info = (await fetch('https://gitlab.com/api/v4/user', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'gitlab', String(info.id));
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'gitlab' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=gitlab`);
+            }
+            return finishOAuth(c, runtime, 'gitlab', String(info.id), { email: info.email, name: info.name, avatarUrl: info.avatar_url }, postLoginRedirect);
+        });
+        router.use('/auth/gitlab/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/gitlab/link',
+            summary: 'Link GitLab account',
+            description: "Initiates an OAuth flow to link a GitLab account to the authenticated user. Requires a valid session. Redirects to GitLab's authorization page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to GitLab's OAuth authorization page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state, undefined, c.get('authUserId'));
+            const url = getGitLab().createAuthorizationURL(state, ['read_user']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/gitlab/link',
+            summary: 'Unlink GitLab account',
+            description: 'Removes the linked GitLab OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'GitLab account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'gitlab');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'gitlab' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── Slack ───────────────────────────────────────────────────────────────
+    if (providers.includes('slack')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/slack',
+            summary: 'Initiate Slack OAuth',
+            description: "Redirects the user to Slack's authorization page to begin the OAuth login flow. After the user authorizes, Slack redirects back to `/auth/slack/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Slack's OAuth authorization page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state);
+            const url = getSlack().createAuthorizationURL(state, ['openid', 'profile', 'email']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/slack/callback',
+            summary: 'Slack OAuth callback',
+            description: 'Handles the redirect from Slack after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from Slack.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getSlack().validateAuthorizationCode(code);
+            const info = (await fetch('https://slack.com/api/openid.connect.userInfo', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'slack', info.sub);
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'slack' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=slack`);
+            }
+            return finishOAuth(c, runtime, 'slack', info.sub, { email: info.email, name: info.name, avatarUrl: info.picture }, postLoginRedirect);
+        });
+        router.use('/auth/slack/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/slack/link',
+            summary: 'Link Slack account',
+            description: "Initiates an OAuth flow to link a Slack account to the authenticated user. Requires a valid session. Redirects to Slack's authorization page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Slack's OAuth authorization page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state, undefined, c.get('authUserId'));
+            const url = getSlack().createAuthorizationURL(state, ['openid', 'profile', 'email']);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/slack/link',
+            summary: 'Unlink Slack account',
+            description: 'Removes the linked Slack OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'Slack account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'slack');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'slack' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── Bitbucket ───────────────────────────────────────────────────────────
+    if (providers.includes('bitbucket')) {
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/bitbucket',
+            summary: 'Initiate Bitbucket OAuth',
+            description: "Redirects the user to Bitbucket's authorization page to begin the OAuth login flow. After the user authorizes, Bitbucket redirects back to `/auth/bitbucket/callback`.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Bitbucket's OAuth authorization page." },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'OAuth provider not configured.',
+                },
+            },
+        }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state);
+            const url = getBitbucket().createAuthorizationURL(state);
+            return c.redirect(url.toString());
+        });
+        router.openapi(createRoute({
+            method: 'get',
+            path: '/auth/bitbucket/callback',
+            summary: 'Bitbucket OAuth callback',
+            description: 'Handles the redirect from Bitbucket after user authorization. Validates the OAuth state and code, then creates or finds the user account. Sets a session cookie and redirects to the configured post-login URL.',
+            tags,
+            request: {
+                query: z.object({
+                    code: z.string().describe('Authorization code from Bitbucket.'),
+                    state: z.string().describe('OAuth state parameter for CSRF protection.'),
+                }),
+            },
+            responses: {
+                302: { description: 'Redirect to the post-login URL with session token.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid callback parameters or expired state.',
+                },
+            },
+        }), async (c) => {
+            const { code, state } = c.req.valid('query');
+            if (!code || !state)
+                return c.json({ error: 'Invalid callback' }, 400);
+            const stored = await consumeOAuthState(state);
+            if (!stored)
+                return c.json({ error: 'Invalid or expired state' }, 400);
+            const tokens = await getBitbucket().validateAuthorizationCode(code);
+            const info = (await fetch('https://api.bitbucket.org/2.0/user', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            // Bitbucket may not expose email on /user — fetch from /user/emails
+            const emails = (await fetch('https://api.bitbucket.org/2.0/user/emails', {
+                headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+            }).then(r => r.json()));
+            const email = emails.values?.find(e => e.is_primary && e.is_confirmed)?.email ??
+                emails.values?.find(e => e.is_confirmed)?.email;
+            if (stored.linkUserId) {
+                if (!adapter.linkProvider)
+                    return c.json({ error: 'Auth adapter does not support linkProvider' }, 500);
+                await adapter.linkProvider(stored.linkUserId, 'bitbucket', info.account_id);
+                eventBus.emit('security.auth.oauth.linked', {
+                    userId: stored.linkUserId,
+                    meta: { provider: 'bitbucket' },
+                });
+                const sep = postLoginRedirect.includes('?') ? '&' : '?';
+                return c.redirect(`${postLoginRedirect}${sep}linked=bitbucket`);
+            }
+            return finishOAuth(c, runtime, 'bitbucket', info.account_id, { email, name: info.display_name, avatarUrl: info.links?.avatar?.href }, postLoginRedirect);
+        });
+        router.use('/auth/bitbucket/link', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'get',
+            path: '/auth/bitbucket/link',
+            summary: 'Link Bitbucket account',
+            description: "Initiates an OAuth flow to link a Bitbucket account to the authenticated user. Requires a valid session. Redirects to Bitbucket's authorization page.",
+            tags,
+            responses: {
+                302: { description: "Redirect to Bitbucket's OAuth authorization page." },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const state = generateState();
+            await storeOAuthState(state, undefined, c.get('authUserId'));
+            const url = getBitbucket().createAuthorizationURL(state);
+            return c.redirect(url.toString());
+        });
+        router.openapi(withSecurity(createRoute({
+            method: 'delete',
+            path: '/auth/bitbucket/link',
+            summary: 'Unlink Bitbucket account',
+            description: 'Removes the linked Bitbucket OAuth account from the authenticated user. Requires a valid session and factor verification when the account has a password or MFA enabled.',
+            tags,
+            request: {
+                body: {
+                    required: false,
+                    content: { 'application/json': { schema: unlinkVerificationSchema } },
+                    description: 'Factor verification (required when the account has a password or MFA enabled).',
+                },
+            },
+            responses: {
+                204: { description: 'Bitbucket account unlinked successfully.' },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Verification is required but not provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'No valid session or invalid verification.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Too many unlink attempts. Try again later.',
+                },
+                500: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Auth adapter does not support unlinkProvider.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            if (!adapter.unlinkProvider) {
+                return c.json({ error: 'Auth adapter does not support unlinkProvider' }, 500);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            if (await runtime.rateLimit.trackAttempt(`oauth-unlink:${userId}`, oauthUnlinkOpts)) {
+                return c.json({ error: 'Too many unlink attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json') ?? {};
+            const unlinkErr = await verifyUnlinkFactor(userId, sessionId, body);
+            if (unlinkErr)
+                return c.json({ error: unlinkErr.error }, unlinkErr.status);
+            await adapter.unlinkProvider(userId, 'bitbucket');
+            eventBus.emit('security.auth.oauth.unlinked', { userId, meta: { provider: 'bitbucket' } });
+            return c.body(null, 204);
+        });
+    }
+    // ─── OAuth Re-auth ──────────────────────────────────────────────────────
+    // Per-provider re-auth routes — only mounted when reauth is enabled in config.
+    // Allows forcing the user to re-authenticate with their OAuth provider before
+    // sensitive operations (e.g. account deletion, MFA changes).
+    if (getConfig().oauthReauth?.enabled ?? false) {
+        for (const provider of providers) {
+            // Skip Apple — Apple does not support prompt= parameter for re-auth
+            if (provider === 'apple')
+                continue;
+            router.use(`/auth/${provider}/reauth`, userAuth);
+            router.openapi(withSecurity(createRoute({
+                method: 'get',
+                path: `/auth/${provider}/reauth`,
+                summary: `Initiate ${provider} OAuth re-authentication`,
+                description: `Forces the authenticated user to re-authenticate with ${provider} before a sensitive operation. Requires a valid session. Redirects to the provider with \`prompt=${getConfig().oauthReauth?.promptType ?? 'login'}\`.`,
+                tags,
+                request: {
+                    query: z.object({
+                        purpose: z
+                            .string()
+                            .describe('Reason for re-auth (e.g. delete_account, change_password).'),
+                        returnUrl: z
+                            .string()
+                            .optional()
+                            .describe('URL to redirect to after successful re-auth. Must be a relative path.'),
+                    }),
+                },
+                responses: {
+                    302: { description: 'Redirect to provider re-auth page.' },
+                    400: {
+                        content: { 'application/json': { schema: OAuthErrorResponse } },
+                        description: 'Provider not linked to this account.',
+                    },
+                    401: {
+                        content: { 'application/json': { schema: OAuthErrorResponse } },
+                        description: 'No valid session.',
+                    },
+                    500: {
+                        content: { 'application/json': { schema: OAuthErrorResponse } },
+                        description: 'OAuth provider not configured.',
+                    },
+                },
+            }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+                const userId = c.get('authUserId');
+                const sessionId = c.get('sessionId');
+                const { purpose, returnUrl } = c.req.valid('query');
+                // Verify user has this provider linked
+                const user = adapter.getUser ? await adapter.getUser(userId) : null;
+                const providerKey = `${provider}:`;
+                const hasProvider = user?.providerIds?.some(id => id.startsWith(providerKey));
+                if (!hasProvider) {
+                    return c.json({ error: `No ${provider} account linked to this user` }, 400);
+                }
+                const state = generateState();
+                const codeVerifier = provider === 'google' || provider === 'microsoft' ? generateCodeVerifier() : undefined;
+                // Encode re-auth context into the OAuth state's linkUserId field using a
+                // "reauth:" prefix, so the callback can recover it after consuming the state.
+                // Format: "reauth:userId:sessionId:purpose[:returnUrl]"
+                await storeOAuthState(state, codeVerifier, `reauth:${userId}:${sessionId}:${encodeURIComponent(purpose)}${returnUrl ? `:${encodeURIComponent(returnUrl)}` : ''}`);
+                const promptType = getConfig().oauthReauth?.promptType ?? 'login';
+                let url;
+                if (provider === 'google') {
+                    url = getGoogle().createAuthorizationURL(state, codeVerifier, [
+                        'openid',
+                        'profile',
+                        'email',
+                    ]);
+                }
+                else if (provider === 'microsoft') {
+                    url = getMicrosoft().createAuthorizationURL(state, codeVerifier, [
+                        'openid',
+                        'profile',
+                        'email',
+                    ]);
+                }
+                else {
+                    // GitHub
+                    url = getGitHub().createAuthorizationURL(state, ['read:user', 'user:email']);
+                }
+                url.searchParams.set('prompt', promptType);
+                return c.redirect(url.toString());
+            });
+            router.openapi(createRoute({
+                method: 'get',
+                path: `/auth/${provider}/reauth/callback`,
+                summary: `${provider} OAuth re-auth callback`,
+                description: `Handles the redirect from ${provider} after re-authentication. Verifies the provider account matches the linked account, then issues a short-lived confirmation code for the client to exchange.`,
+                tags,
+                request: {
+                    query: z.object({
+                        code: z.string().describe('Authorization code from provider.'),
+                        state: z.string().describe('OAuth state parameter.'),
+                    }),
+                },
+                responses: {
+                    302: { description: 'Redirect with confirmation code (or error).' },
+                    400: {
+                        content: { 'application/json': { schema: OAuthErrorResponse } },
+                        description: 'Invalid state, expired session, or provider account mismatch.',
+                    },
+                },
+            }), async (c) => {
+                const { code, state } = c.req.valid('query');
+                if (!code || !state)
+                    return c.json({ error: 'Invalid callback' }, 400);
+                const stored = await consumeOAuthState(state);
+                if (!stored?.linkUserId?.startsWith('reauth:')) {
+                    return c.json({ error: 'Invalid or expired state' }, 400);
+                }
+                // Parse reauth info encoded in linkUserId: "reauth:userId:sessionId:purpose[:returnUrl]"
+                // userId and sessionId are UUID-safe (no colons); purpose and returnUrl are encodeURIComponent'd.
+                const parts = stored.linkUserId.slice('reauth:'.length).split(':');
+                if (parts.length < 3)
+                    return c.json({ error: 'Invalid or expired state' }, 400);
+                const [userId, sessionId, encodedPurpose, encodedReturnUrl] = parts;
+                const purpose = decodeURIComponent(encodedPurpose);
+                const returnUrl = encodedReturnUrl ? decodeURIComponent(encodedReturnUrl) : undefined;
+                // Exchange code for tokens and get the provider user ID
+                let providerUserId;
+                try {
+                    if (provider === 'google') {
+                        const tokens = await getGoogle().validateAuthorizationCode(code, stored.codeVerifier);
+                        const info = (await fetch('https://openidconnect.googleapis.com/v1/userinfo', {
+                            headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+                        }).then(r => r.json()));
+                        providerUserId = info.sub;
+                    }
+                    else if (provider === 'microsoft') {
+                        const tokens = await getMicrosoft().validateAuthorizationCode(code, stored.codeVerifier);
+                        const info = (await fetch('https://graph.microsoft.com/v1.0/me', {
+                            headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+                        }).then(r => r.json()));
+                        providerUserId = info.id;
+                    }
+                    else {
+                        // GitHub
+                        const tokens = await getGitHub().validateAuthorizationCode(code);
+                        const info = (await fetch('https://api.github.com/user', {
+                            headers: {
+                                Authorization: `Bearer ${tokens.accessToken()}`,
+                                'User-Agent': 'bunshot',
+                            },
+                        }).then(r => r.json()));
+                        providerUserId = String(info.id);
+                    }
+                }
+                catch {
+                    return c.json({ error: 'Failed to verify provider identity' }, 400);
+                }
+                // Verify the provider account matches what is linked to this user
+                const user = adapter.getUser ? await adapter.getUser(userId) : null;
+                const expectedKey = `${provider}:${providerUserId}`;
+                const isLinked = user?.providerIds?.includes(expectedKey);
+                if (!isLinked) {
+                    eventBus.emit('security.auth.oauth.reauthed', {
+                        userId,
+                        sessionId,
+                        meta: { provider, purpose, mismatch: true },
+                    });
+                    return c.json({ error: 'Provider account mismatch' }, 400);
+                }
+                // Issue a confirmation code
+                const confirmationCode = await storeReauthConfirmation(runtime.repos.oauthReauth, {
+                    userId,
+                    purpose,
+                });
+                eventBus.emit('security.auth.oauth.reauthed', {
+                    userId,
+                    sessionId,
+                    meta: { provider, purpose },
+                });
+                // Redirect with confirmation code — validate returnUrl against open redirect
+                const isSafeRedirect = (url) => url.startsWith('/') && !url.startsWith('//') && !url.includes('://');
+                const redirectBase = returnUrl && isSafeRedirect(returnUrl) ? returnUrl : '/';
+                try {
+                    const url = new URL(redirectBase, 'http://localhost');
+                    url.searchParams.set('reauth_code', confirmationCode);
+                    // Use relative redirect for relative paths
+                    return c.redirect(`${url.pathname}${url.search}`);
+                }
+                catch {
+                    // Fallback also uses the already-validated redirectBase
+                    const sep = redirectBase.includes('?') ? '&' : '?';
+                    return c.redirect(`${redirectBase}${sep}reauth_code=${encodeURIComponent(confirmationCode)}`);
+                }
+            });
+        }
+    }
+    // ─── Code Exchange ─────────────────────────────────────────────────────
+    router.openapi(createRoute({
+        method: 'post',
+        path: '/auth/oauth/exchange',
+        summary: 'Exchange OAuth authorization code for session token',
+        description: 'Exchanges a one-time authorization code (received from the OAuth redirect) for a session token. The code is single-use and expires after 60 seconds. Sets session cookies for browser clients; returns the token in the JSON response for mobile/SPA clients.',
+        tags,
+        request: {
+            body: {
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            code: z.string().describe('One-time authorization code from the OAuth redirect.'),
+                        }),
+                    },
+                },
+            },
+        },
+        responses: {
+            200: {
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            token: z.string().describe('Session JWT.'),
+                            userId: z.string().describe('Authenticated user ID.'),
+                            email: z.string().optional().describe('User email if available.'),
+                            refreshToken: z
+                                .string()
+                                .optional()
+                                .describe('Refresh token if refresh tokens are configured.'),
+                        }),
+                    },
+                },
+                description: 'Session token and user info.',
+            },
+            400: {
+                content: { 'application/json': { schema: OAuthErrorResponse } },
+                description: 'Missing code parameter.',
+            },
+            401: {
+                content: { 'application/json': { schema: OAuthErrorResponse } },
+                description: 'Invalid, expired, or already-used code.',
+            },
+            429: {
+                content: { 'application/json': { schema: OAuthErrorResponse } },
+                description: 'Rate limit exceeded.',
+            },
+        },
+    }), async (c) => {
+        // Rate limit by IP to prevent brute-forcing codes within the 60s TTL
+        const ip = getClientIp(c);
+        const limited = await runtime.rateLimit.trackAttempt(`oauth-exchange:ip:${ip}`, {
+            max: 20,
+            windowMs: 60_000,
+        });
+        if (limited) {
+            return c.json({ error: 'Too many requests' }, 429);
+        }
+        const { code } = c.req.valid('json');
+        if (!code)
+            return c.json({ error: 'Missing code' }, 400);
+        const payload = await consumeOAuthCode(runtime.repos.oauthCode, code, runtime.dataEncryptionKeys);
+        if (!payload)
+            return c.json({ error: 'Invalid or expired code' }, 401);
+        // Set session cookies for browser clients
+        const rtConfig = getConfig().refreshToken;
+        setCookie(c, COOKIE_TOKEN, payload.token, cookieOptions(rtConfig ? (rtConfig.accessTokenExpiry ?? 900) : undefined));
+        if (payload.refreshToken && rtConfig) {
+            setCookie(c, COOKIE_REFRESH_TOKEN, payload.refreshToken, cookieOptions(rtConfig.refreshTokenExpiry ?? 2_592_000));
+        }
+        if (getConfig().csrfEnabled)
+            refreshCsrfToken(c);
+        return c.json({
+            token: payload.token,
+            userId: payload.userId,
+            email: payload.email,
+            refreshToken: payload.refreshToken,
+        }, 200);
+    });
+    // ─── Re-auth Confirmation Exchange ──────────────────────────────────────
+    if (getConfig().oauthReauth?.enabled ?? false) {
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/oauth/reauth/exchange',
+            summary: 'Exchange OAuth re-auth confirmation code for step-up proof',
+            description: 'Exchanges a one-time re-auth confirmation code (received from the re-auth callback redirect) for a step-up proof. The code is single-use and expires after 5 minutes. Returns confirmation that the user successfully re-authenticated with their OAuth provider.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                code: z
+                                    .string()
+                                    .describe('One-time re-auth confirmation code from the redirect.'),
+                            }),
+                        },
+                    },
+                },
+            },
+            responses: {
+                200: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                reauthConfirmed: z.literal(true).describe('Always true on success.'),
+                                purpose: z.string().describe('The purpose the re-auth was requested for.'),
+                                userId: z.string().describe('The re-authenticated user ID.'),
+                            }),
+                        },
+                    },
+                    description: 'Re-auth confirmed.',
+                },
+                400: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Missing code parameter.',
+                },
+                401: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Invalid, expired, or already-used code.',
+                },
+                429: {
+                    content: { 'application/json': { schema: OAuthErrorResponse } },
+                    description: 'Rate limit exceeded.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            const limited = await runtime.rateLimit.trackAttempt(`oauth-reauth-exchange:ip:${ip}`, {
+                max: 20,
+                windowMs: 60_000,
+            });
+            if (limited) {
+                return c.json({ error: 'Too many requests' }, 429);
+            }
+            const { code } = c.req.valid('json');
+            if (!code)
+                return c.json({ error: 'Missing code' }, 400);
+            const payload = await consumeReauthConfirmation(runtime.repos.oauthReauth, code);
+            if (!payload)
+                return c.json({ error: 'Invalid or expired code' }, 401);
+            return c.json({
+                reauthConfirmed: true,
+                purpose: payload.purpose,
+                userId: payload.userId,
+            }, 200);
+        });
+    }
+    return router;
+};