@lastshotlabs/bunshot 0.0.27 → 0.1.0

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

@@ -0,0 +1,1624 @@
+import { checkBreachedPassword } from '../lib/breachedPassword';
+import { getAuthCookieOptions } from '../lib/cookieOptions';
+import { consumeDeletionCancelToken, createDeletionCancelToken, } from '../lib/deletionCancelToken';
+import { consumeVerificationToken, createVerificationToken } from '../lib/emailVerification';
+import { isProd } from '../lib/env';
+import { consumeMagicLinkToken, createMagicLinkToken } from '../lib/magicLink';
+import { checkPasswordNotReused, recordPasswordChange } from '../lib/passwordHistory';
+import { consumeResetToken, createResetToken } from '../lib/resetPassword';
+import { clearCsrfToken, refreshCsrfToken } from '../middleware/csrf';
+import { userAuth } from '../middleware/userAuth';
+import { makeLoginSchema, makeRegisterSchema, resetPasswordSchema } from '../schemas/auth';
+import { ErrorResponse } from '../schemas/error';
+import { SuccessResponse } from '../schemas/success';
+import * as AuthService from '../services/auth';
+import { emitLoginSuccess } from '../services/auth';
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie';
+import { z } from 'zod';
+import { createRoute, withSecurity } from '../../../bunshot-core/src/index.js';
+import { COOKIE_REFRESH_TOKEN, COOKIE_TOKEN, HEADER_REFRESH_TOKEN, HEADER_USER_TOKEN, HttpError, createRouter, } from '../../../bunshot-core/src/index.js';
+import { getClientIp } from '../../../bunshot-core/src/index.js';
+const TokenResponse = z
+    .object({
+    token: z
+        .string()
+        .describe('JWT session token. Also set as an HttpOnly session cookie. Empty string when mfaRequired is true.'),
+    userId: z.string().describe('Unique user ID.'),
+    email: z
+        .string()
+        .optional()
+        .describe("User's email address (present when primaryField is 'email')."),
+    emailVerified: z
+        .boolean()
+        .optional()
+        .describe('Whether the email address has been verified (present when emailVerification is configured).'),
+    googleLinked: z
+        .boolean()
+        .optional()
+        .describe('Whether a Google OAuth account is linked to this user.'),
+    refreshToken: z
+        .string()
+        .optional()
+        .describe('Refresh token (present when refreshTokens is configured). Also set as an HttpOnly cookie.'),
+    mfaRequired: z
+        .boolean()
+        .optional()
+        .describe('When true, complete MFA via POST /auth/mfa/verify before accessing the API.'),
+    mfaToken: z
+        .string()
+        .optional()
+        .describe('MFA challenge token. Pass to POST /auth/mfa/verify with a TOTP or recovery code.'),
+    mfaMethods: z
+        .array(z.string())
+        .optional()
+        .describe("Available MFA methods when mfaRequired is true (e.g., 'totp', 'emailOtp', 'webauthn')."),
+    webauthnOptions: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("WebAuthn assertion options (present when mfaMethods includes 'webauthn'). Pass directly to navigator.credentials.get()."),
+})
+    .openapi('TokenResponse');
+const PasswordUpdateResponse = SuccessResponse.extend({
+    token: z.string().optional().describe('Replacement session token when sessions are reissued.'),
+}).openapi('PasswordUpdateResponse');
+const tags = ['Auth'];
+const hookCtx = (c) => ({
+    ip: getClientIp(c) !== 'unknown' ? getClientIp(c) : undefined,
+    userAgent: c.req.header('user-agent') ?? undefined,
+    requestId: c.get('requestId'),
+});
+export const createAuthRouter = ({ primaryField, emailVerification, passwordReset, rateLimit, accountDeletion, refreshTokens, stepUp, sessionPolicy, concealRegistration, magicLink, }, runtime) => {
+    const { adapter, eventBus } = runtime;
+    const getConfig = () => runtime.config;
+    const cookieOptions = (maxAge) => getAuthCookieOptions(isProd(), runtime.config, maxAge);
+    const router = createRouter();
+    const RegisterSchema = makeRegisterSchema(primaryField, runtime.config.passwordPolicy);
+    const LoginSchema = makeLoginSchema(primaryField);
+    const fieldLabel = primaryField.charAt(0).toUpperCase() + primaryField.slice(1);
+    const alreadyRegisteredMsg = `${fieldLabel} already registered`;
+    // Resolve limits with defaults
+    const loginOpts = {
+        windowMs: rateLimit?.login?.windowMs ?? 15 * 60 * 1000,
+        max: rateLimit?.login?.max ?? 10,
+    };
+    const registerOpts = {
+        windowMs: rateLimit?.register?.windowMs ?? 60 * 60 * 1000,
+        max: rateLimit?.register?.max ?? 5,
+    };
+    const verifyOpts = {
+        windowMs: rateLimit?.verifyEmail?.windowMs ?? 15 * 60 * 1000,
+        max: rateLimit?.verifyEmail?.max ?? 10,
+    };
+    const resendOpts = {
+        windowMs: rateLimit?.resendVerification?.windowMs ?? 60 * 60 * 1000,
+        max: rateLimit?.resendVerification?.max ?? 3,
+    };
+    const forgotOpts = {
+        windowMs: rateLimit?.forgotPassword?.windowMs ?? 15 * 60 * 1000,
+        max: rateLimit?.forgotPassword?.max ?? 5,
+    };
+    const resetOpts = {
+        windowMs: rateLimit?.resetPassword?.windowMs ?? 15 * 60 * 1000,
+        max: rateLimit?.resetPassword?.max ?? 10,
+    };
+    const CONCEALED_REGISTER_MESSAGE = "If this email isn't registered yet, check your inbox to complete sign-up.";
+    if (concealRegistration) {
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/register',
+            summary: 'Register a new account',
+            description: 'Creates a new user account. When concealRegistration is enabled, always returns 200 with a generic message regardless of whether the email is already registered. Rate-limited by IP.',
+            tags,
+            request: {
+                body: {
+                    content: { 'application/json': { schema: RegisterSchema } },
+                    description: 'Registration credentials.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: z.object({ message: z.string() }) } },
+                    description: 'Request received. Check your inbox to complete sign-up.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Validation error (e.g. missing field, password too short).',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many registration attempts from this IP. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`register:${ip}`, registerOpts)) {
+                eventBus.emit('security.rate_limit.exceeded', { meta: { path: c.req.path } });
+                return c.json({ error: 'Too many registration attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json');
+            const identifier = body[primaryField];
+            const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
+            const existing = await findFn(identifier);
+            if (existing) {
+                eventBus.emit('security.auth.register.concealed', { meta: { identifier } });
+                if (concealRegistration.onExistingAccount) {
+                    void concealRegistration.onExistingAccount(identifier).catch(err => {
+                        console.error('[concealRegistration] onExistingAccount error:', err instanceof Error ? err.message : String(err));
+                    });
+                }
+                return c.json({ message: CONCEALED_REGISTER_MESSAGE }, 200);
+            }
+            const breachConfig = getConfig().breachedPassword;
+            if (breachConfig) {
+                const { breached } = await checkBreachedPassword(body.password, breachConfig, undefined, runtime.eventBus);
+                if (breached && breachConfig.block !== false) {
+                    throw new HttpError(400, 'This password has appeared in a data breach. Please choose a different password.', 'BREACHED_PASSWORD');
+                }
+            }
+            const metadata = {
+                ipAddress: ip !== 'unknown' ? ip : undefined,
+                userAgent: c.req.header('user-agent') ?? undefined,
+            };
+            await AuthService.register(identifier, body.password, runtime, {
+                metadata,
+                skipSession: true,
+                hookContext: hookCtx(c),
+            });
+            return c.json({ message: CONCEALED_REGISTER_MESSAGE }, 200);
+        });
+    }
+    else {
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/register',
+            summary: 'Register a new account',
+            description: 'Creates a new user account and returns a JWT session token. The token is also set as an HttpOnly session cookie. Rate-limited by IP.',
+            tags,
+            request: {
+                body: {
+                    content: { 'application/json': { schema: RegisterSchema } },
+                    description: 'Registration credentials.',
+                },
+            },
+            responses: {
+                201: {
+                    content: { 'application/json': { schema: TokenResponse } },
+                    description: 'Account created. Returns a session token.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Validation error (e.g. missing field, password too short).',
+                },
+                409: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: alreadyRegisteredMsg,
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many registration attempts from this IP. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`register:${ip}`, registerOpts)) {
+                eventBus.emit('security.rate_limit.exceeded', { meta: { path: c.req.path } });
+                return c.json({ error: 'Too many registration attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json');
+            const identifier = body[primaryField];
+            const breachConfig = getConfig().breachedPassword;
+            if (breachConfig) {
+                const { breached } = await checkBreachedPassword(body.password, breachConfig, undefined, runtime.eventBus);
+                if (breached && breachConfig.block !== false) {
+                    throw new HttpError(400, 'This password has appeared in a data breach. Please choose a different password.', 'BREACHED_PASSWORD');
+                }
+            }
+            const metadata = {
+                ipAddress: ip !== 'unknown' ? ip : undefined,
+                userAgent: c.req.header('user-agent') ?? undefined,
+            };
+            const result = await AuthService.register(identifier, body.password, runtime, {
+                metadata,
+                hookContext: hookCtx(c),
+            });
+            setCookie(c, COOKIE_TOKEN, result.token, cookieOptions(refreshTokens ? (getConfig().refreshToken?.accessTokenExpiry ?? 900) : undefined));
+            if (result.refreshToken) {
+                setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getConfig().refreshToken?.refreshTokenExpiry ?? 2_592_000));
+            }
+            if (getConfig().csrfEnabled)
+                refreshCsrfToken(c);
+            return c.json(result, 201);
+        });
+    }
+    // verify-and-login — only mounted when concealRegistration is configured
+    // Consumes an email verification token and creates a session (login) in one step.
+    if (concealRegistration) {
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/verify-and-login',
+            summary: 'Verify email and create session',
+            description: 'Consumes a single-use email verification token, marks the account as verified, and issues a session token. Only available when concealRegistration is configured. Rate-limited by IP.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                token: z.string().describe('Single-use verification token received via email.'),
+                            }),
+                        },
+                    },
+                    description: 'Verification token.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: TokenResponse } },
+                    description: 'Email verified and session created. Returns a session token.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Invalid or expired verification token.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many verification attempts from this IP. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`verify:${ip}`, verifyOpts)) {
+                return c.json({ error: 'Too many verification attempts. Try again later.' }, 429);
+            }
+            const { token } = c.req.valid('json');
+            const entry = await consumeVerificationToken(runtime.repos.verificationToken, token);
+            if (!entry)
+                return c.json({ error: 'Invalid or expired verification token' }, 400);
+            if (adapter.setEmailVerified)
+                await adapter.setEmailVerified(entry.userId, true);
+            eventBus.emit('auth:email.verified', { userId: entry.userId, email: entry.email });
+            const metadata = {
+                ipAddress: ip !== 'unknown' ? ip : undefined,
+                userAgent: c.req.header('user-agent') ?? undefined,
+            };
+            const { createSessionForUser } = await import('../services/auth');
+            const { token: sessionToken, refreshToken, sessionId, } = await createSessionForUser(entry.userId, runtime, metadata, hookCtx(c));
+            setCookie(c, COOKIE_TOKEN, sessionToken, cookieOptions(refreshTokens ? (getConfig().refreshToken?.accessTokenExpiry ?? 900) : undefined));
+            if (refreshToken) {
+                setCookie(c, COOKIE_REFRESH_TOKEN, refreshToken, cookieOptions(getConfig().refreshToken?.refreshTokenExpiry ?? 2_592_000));
+            }
+            if (getConfig().csrfEnabled)
+                refreshCsrfToken(c);
+            emitLoginSuccess(entry.userId, sessionId, runtime);
+            const result = {
+                token: sessionToken,
+                userId: entry.userId,
+                email: entry.email,
+                emailVerified: true,
+                refreshToken,
+            };
+            return c.json(result, 200);
+        });
+    }
+    router.openapi(createRoute({
+        method: 'post',
+        path: '/auth/login',
+        summary: 'Log in',
+        description: 'Authenticates with credentials and returns a JWT session token. The token is also set as an HttpOnly session cookie. Failed attempts are rate-limited per identifier.',
+        tags,
+        request: {
+            body: {
+                content: { 'application/json': { schema: LoginSchema } },
+                description: 'Login credentials.',
+            },
+        },
+        responses: {
+            200: {
+                content: { 'application/json': { schema: TokenResponse } },
+                description: 'Authenticated. Returns a session token.',
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Invalid credentials.',
+            },
+            403: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Email not verified. Verification is required before login.',
+            },
+            423: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Account is locked due to too many failed login attempts. Wait for the lockout to expire or contact support.',
+            },
+            429: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Too many failed login attempts for this identifier. Try again later.',
+            },
+        },
+    }), async (c) => {
+        const body = c.req.valid('json');
+        const identifier = body[primaryField];
+        const limitKey = `login:${identifier}`;
+        const clientIp = getClientIp(c) ?? 'unknown';
+        if (await runtime.credentialStuffing?.isStuffingBlocked(clientIp, identifier)) {
+            eventBus.emit('security.credential_stuffing.detected', {
+                ip: clientIp,
+                meta: { identifier },
+            });
+            throw new HttpError(429, 'Too many login attempts from this source', 'CREDENTIAL_STUFFING_BLOCKED');
+        }
+        if (await runtime.rateLimit.isLimited(limitKey, loginOpts)) {
+            eventBus.emit('security.rate_limit.exceeded', { meta: { path: c.req.path } });
+            return c.json({ error: 'Too many failed login attempts. Try again later.' }, 429);
+        }
+        const metadata = {
+            ipAddress: clientIp !== 'unknown' ? clientIp : undefined,
+            userAgent: c.req.header('user-agent') ?? undefined,
+        };
+        try {
+            const result = await AuthService.login(identifier, body.password, runtime, metadata, hookCtx(c));
+            await runtime.rateLimit.bustAuthLimit(limitKey); // success — clear failure count
+            if (!result.mfaRequired) {
+                setCookie(c, COOKIE_TOKEN, result.token, cookieOptions(refreshTokens ? (getConfig().refreshToken?.accessTokenExpiry ?? 900) : undefined));
+                if (result.refreshToken) {
+                    setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getConfig().refreshToken?.refreshTokenExpiry ?? 2_592_000));
+                }
+                if (getConfig().csrfEnabled)
+                    refreshCsrfToken(c);
+            }
+            return c.json(result, 200);
+        }
+        catch (err) {
+            if (err instanceof HttpError && err.status === 401) {
+                const nowBlocked = await runtime.credentialStuffing?.trackFailedLogin(clientIp, identifier);
+                if (nowBlocked) {
+                    eventBus.emit('security.credential_stuffing.detected', {
+                        ip: clientIp,
+                        meta: { identifier },
+                    });
+                }
+            }
+            await runtime.rateLimit.trackAttempt(limitKey, loginOpts); // failure — count it
+            throw err;
+        }
+    });
+    router.use('/auth/me', userAuth);
+    router.openapi(withSecurity(createRoute({
+        method: 'get',
+        path: '/auth/me',
+        summary: 'Get current user',
+        description: "Returns the authenticated user's profile. Requires a valid session via cookie or x-user-token header.",
+        tags,
+        responses: {
+            200: {
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            userId: z.string().describe('Unique user ID.'),
+                            email: z.string().optional().describe("User's email address."),
+                            emailVerified: z
+                                .boolean()
+                                .optional()
+                                .describe('Whether the email address has been verified.'),
+                            googleLinked: z
+                                .boolean()
+                                .optional()
+                                .describe('Whether a Google OAuth account is linked.'),
+                            userMetadata: z
+                                .record(z.string(), z.unknown())
+                                .optional()
+                                .describe('User-editable metadata blob.'),
+                        }),
+                    },
+                },
+                description: "Authenticated user's profile.",
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'No valid session.',
+            },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const authUserId = c.get('authUserId');
+        const user = adapter.getUser ? await adapter.getUser(authUserId) : null;
+        const googleLinked = user?.providerIds?.some(id => id.startsWith('google:')) ?? false;
+        return c.json({
+            userId: authUserId,
+            email: user?.email,
+            emailVerified: user?.emailVerified,
+            googleLinked,
+            userMetadata: user?.userMetadata ?? {},
+        }, 200);
+    });
+    router.openapi(withSecurity(createRoute({
+        method: 'patch',
+        path: '/auth/me',
+        summary: 'Update current user profile',
+        description: "Updates the authenticated user's profile fields and/or user-editable metadata. Requires a valid session.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            displayName: z.string().optional().describe("User's display name."),
+                            firstName: z.string().optional().describe("User's first name."),
+                            lastName: z.string().optional().describe("User's last name."),
+                            userMetadata: z
+                                .record(z.string(), z.unknown())
+                                .optional()
+                                .describe('User-editable metadata blob (replaces existing).'),
+                        }),
+                    },
+                },
+                description: 'Fields to update.',
+            },
+        },
+        responses: {
+            200: {
+                content: { 'application/json': { schema: SuccessResponse } },
+                description: 'Profile updated.',
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'No valid session.',
+            },
+            501: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Auth adapter does not support profile updates.',
+            },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const authUserId = c.get('authUserId');
+        const body = c.req.valid('json');
+        if (body.userMetadata !== undefined && adapter.setUserMetadata) {
+            await adapter.setUserMetadata(authUserId, body.userMetadata);
+        }
+        const profileFields = {};
+        if ('displayName' in body)
+            profileFields.displayName = body.displayName;
+        if ('firstName' in body)
+            profileFields.firstName = body.firstName;
+        if ('lastName' in body)
+            profileFields.lastName = body.lastName;
+        if (Object.keys(profileFields).length > 0) {
+            if (!adapter.updateProfile) {
+                return c.json({ error: 'Auth adapter does not support profile updates' }, 501);
+            }
+            await adapter.updateProfile(authUserId, profileFields);
+        }
+        return c.json({ ok: true }, 200);
+    });
+    // ---------------------------------------------------------------------------
+    // Account deletion
+    // ---------------------------------------------------------------------------
+    const deleteAccountOpts = {
+        windowMs: rateLimit?.deleteAccount?.windowMs ?? 60 * 60 * 1000,
+        max: rateLimit?.deleteAccount?.max ?? 3,
+    };
+    const setPasswordOpts = {
+        windowMs: rateLimit?.setPassword?.windowMs ?? 15 * 60 * 1000,
+        max: rateLimit?.setPassword?.max ?? 5,
+    };
+    // Expanded verification schema for account deletion, step-up, and MFA disable
+    const verificationSchema = 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).'),
+    });
+    router.openapi(withSecurity(createRoute({
+        method: 'delete',
+        path: '/auth/me',
+        summary: 'Delete account',
+        description: "Permanently deletes the authenticated user's account. Requires factor verification for accounts that have a password or MFA. OAuth-only accounts may be deleted freely unless requireVerification is set. Revokes all active sessions.",
+        tags,
+        request: {
+            body: {
+                content: {
+                    'application/json': {
+                        schema: verificationSchema,
+                    },
+                },
+                description: 'Factor verification.',
+            },
+        },
+        responses: {
+            200: {
+                content: { 'application/json': { schema: SuccessResponse } },
+                description: 'Account deleted.',
+            },
+            202: {
+                content: { 'application/json': { schema: SuccessResponse } },
+                description: 'Account deletion has been scheduled.',
+            },
+            400: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Verification is required but not provided.',
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Invalid verification or no valid session.',
+            },
+            429: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Too many deletion attempts. Try again later.',
+            },
+            501: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'The configured auth adapter does not support deleteUser.',
+            },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const authUserId = c.get('authUserId');
+        const sessionId = c.get('sessionId');
+        if (await runtime.rateLimit.trackAttempt(`deleteaccount:${authUserId}`, deleteAccountOpts)) {
+            return c.json({ error: 'Too many deletion attempts. Try again later.' }, 429);
+        }
+        if (!adapter.deleteUser) {
+            return c.json({ error: 'Auth adapter does not support deleteUser' }, 501);
+        }
+        const body = c.req.valid('json');
+        const hasPassword = adapter.hasPassword ? await adapter.hasPassword(authUserId) : false;
+        const mfaMethods = getConfig().mfa && adapter.getMfaMethods ? await adapter.getMfaMethods(authUserId) : [];
+        const hasVerifiableFactor = hasPassword || mfaMethods.length > 0;
+        if (hasVerifiableFactor) {
+            // Infer method from provided credentials when not specified
+            const method = body.method ?? (body.password ? 'password' : body.code ? 'totp' : undefined);
+            if (!method) {
+                return c.json({
+                    error: 'Verification is required to delete this account. Provide method and credentials.',
+                }, 400);
+            }
+            const { verifyAnyFactor } = await import('../services/mfa');
+            const valid = await verifyAnyFactor(authUserId, sessionId, runtime, {
+                method,
+                code: body.code,
+                password: body.password,
+                reauthToken: body.reauthToken,
+                webauthnResponse: body.webauthnResponse,
+            });
+            if (!valid) {
+                return c.json({ error: 'Invalid verification' }, 401);
+            }
+        }
+        else {
+            // OAuth-only account — no verifiable factor
+            if (accountDeletion?.requireVerification) {
+                return c.json({
+                    error: 'Account deletion requires a verifiable factor. Please set a password or enable MFA first.',
+                }, 400);
+            }
+            // else: allow deletion without verification
+        }
+        // Call onBeforeDelete hook
+        if (accountDeletion?.onBeforeDelete) {
+            await accountDeletion.onBeforeDelete(authUserId);
+        }
+        // Queued deletion via BullMQ
+        if (accountDeletion?.queued) {
+            if (!runtime.queueFactory)
+                throw new Error('[bunshot-auth] accountDeletion.queued requires Redis and BullMQ');
+            const appName = runtime.config.appName;
+            const queue = runtime.queueFactory.createQueue(`${appName}:account-deletions`);
+            const delayMs = (accountDeletion.gracePeriod ?? 0) * 1000;
+            const job = await queue.add('delete-account', { userId: authUserId }, {
+                delay: delayMs,
+                attempts: 3,
+                backoff: { type: 'exponential', delay: 1000 },
+                removeOnComplete: true,
+                removeOnFail: 100,
+            });
+            await queue.close();
+            // Revoke sessions immediately so the user is logged out
+            {
+                const sr = runtime.repos.session;
+                const ss = await sr.getUserSessions(authUserId, runtime.config);
+                await Promise.all(ss.map(s => sr.deleteSession(s.sessionId, runtime.config)));
+            }
+            if (accountDeletion.gracePeriod) {
+                const cancelToken = await createDeletionCancelToken(runtime.repos.deletionCancelToken, authUserId, job.id, accountDeletion.gracePeriod);
+                eventBus.emit('auth:account.deletion.scheduled', {
+                    userId: authUserId,
+                    cancelToken,
+                    gracePeriodSeconds: accountDeletion.gracePeriod ?? 0,
+                });
+                const user = adapter.getUser ? await adapter.getUser(authUserId) : null;
+                const email = user?.email ?? '';
+                if (email) {
+                    eventBus.emit('auth:delivery.account_deletion', {
+                        userId: authUserId,
+                        email,
+                        cancelToken,
+                        gracePeriodSeconds: accountDeletion.gracePeriod ?? 0,
+                    });
+                }
+            }
+            else {
+                // No grace period — deletion is immediate via the queue (delay=0).
+                // Emit the same events as the synchronous path so listeners are notified.
+                eventBus.emit('security.auth.account.deleted', { userId: authUserId });
+                eventBus.emit('auth:user.deleted', { userId: authUserId });
+            }
+            deleteCookie(c, COOKIE_TOKEN, { path: '/' });
+            return c.json({ ok: true }, 202);
+        }
+        // Synchronous deletion (default)
+        const hooks = getConfig().hooks;
+        if (hooks.preDeleteAccount)
+            await hooks.preDeleteAccount({ userId: authUserId, ...hookCtx(c) });
+        {
+            const sr = runtime.repos.session;
+            const ss = await sr.getUserSessions(authUserId, runtime.config);
+            await Promise.all(ss.map(s => sr.deleteSession(s.sessionId, runtime.config)));
+        }
+        await adapter.deleteUser(authUserId);
+        eventBus.emit('security.auth.account.deleted', { userId: authUserId });
+        eventBus.emit('auth:user.deleted', { userId: authUserId });
+        if (accountDeletion?.onAfterDelete) {
+            await accountDeletion.onAfterDelete(authUserId);
+        }
+        if (hooks.postDeleteAccount) {
+            Promise.resolve()
+                .then(() => hooks.postDeleteAccount({ userId: authUserId, ...hookCtx(c) }))
+                .catch(e => console.error('[lifecycle] postDeleteAccount hook error:', e instanceof Error ? e.message : String(e)));
+        }
+        deleteCookie(c, COOKIE_TOKEN, { path: '/' });
+        return c.json({ ok: true }, 200);
+    });
+    router.use('/auth/set-password', userAuth);
+    router.openapi(withSecurity(createRoute({
+        method: 'post',
+        path: '/auth/set-password',
+        summary: 'Set or update password',
+        description: 'Sets or updates the password for the authenticated user. Useful for OAuth-only users who want to add a password. If the account already has a password set, `currentPassword` is required. Requires a valid session.',
+        tags,
+        request: {
+            body: {
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            password: z.string().min(8).describe('New password.'),
+                            currentPassword: z
+                                .string()
+                                .optional()
+                                .describe('Current password. Required if the account already has a password set.'),
+                        }),
+                    },
+                },
+                description: 'New password.',
+            },
+        },
+        responses: {
+            200: {
+                content: { 'application/json': { schema: PasswordUpdateResponse } },
+                description: 'Password updated successfully.',
+            },
+            400: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Validation error, or current password is required when one is already set.',
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'No valid session, or current password is incorrect.',
+            },
+            429: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Too many password change attempts. Try again later.',
+            },
+            501: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'The configured auth adapter does not support setPassword.',
+            },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        if (!adapter.setPassword) {
+            return c.json({ error: 'Auth adapter does not support setPassword' }, 501);
+        }
+        const { password, currentPassword } = c.req.valid('json');
+        const authUserId = c.get('authUserId');
+        const currentSessionId = c.get('sessionId');
+        if (await runtime.rateLimit.trackAttempt(`setpassword:${authUserId}`, setPasswordOpts)) {
+            eventBus.emit('security.rate_limit.exceeded', { meta: { path: c.req.path } });
+            return c.json({ error: 'Too many password change attempts. Try again later.' }, 429);
+        }
+        // If the user already has a password, require currentPassword to change it
+        const hasExistingPassword = adapter.hasPassword
+            ? await adapter.hasPassword(authUserId)
+            : false;
+        if (hasExistingPassword) {
+            if (!currentPassword) {
+                return c.json({ error: 'Current password is required to change an existing password.' }, 400);
+            }
+            if (!(await adapter.verifyPassword(authUserId, currentPassword))) {
+                return c.json({ error: 'Current password is incorrect.' }, 401);
+            }
+        }
+        // Breached password check
+        const breachConfig = getConfig().breachedPassword;
+        if (breachConfig) {
+            const { breached } = await checkBreachedPassword(password, breachConfig, undefined, runtime.eventBus);
+            if (breached && breachConfig.block !== false) {
+                throw new HttpError(400, 'This password has appeared in a data breach. Please choose a different password.', 'BREACHED_PASSWORD');
+            }
+        }
+        const hooks = getConfig().hooks;
+        if (hooks.prePasswordChange)
+            await hooks.prePasswordChange({ userId: authUserId });
+        const passwordHash = await Bun.password.hash(password);
+        // Password reuse check
+        const preventReuse = getConfig().passwordPolicy.preventReuse ?? 0;
+        if (preventReuse > 0) {
+            const isNew = await checkPasswordNotReused(adapter, authUserId, password, preventReuse);
+            if (!isNew) {
+                return c.json({ error: 'You cannot reuse a recent password.', code: 'PASSWORD_PREVIOUSLY_USED' }, 400);
+            }
+        }
+        await adapter.setPassword(authUserId, passwordHash);
+        if (preventReuse > 0)
+            await recordPasswordChange(adapter, authUserId, passwordHash, preventReuse);
+        eventBus.emit('security.auth.password.change', { userId: authUserId });
+        if (hooks.postPasswordChange) {
+            Promise.resolve()
+                .then(() => hooks.postPasswordChange({ userId: authUserId }))
+                .catch(e => console.error('[lifecycle] postPasswordChange hook error:', e instanceof Error ? e.message : String(e)));
+        }
+        // Session revocation policy on password change
+        const pwChangePolicy = sessionPolicy?.onPasswordChange ?? 'revoke_others';
+        if (pwChangePolicy === 'revoke_all_and_reissue') {
+            // Revoke all sessions including current, create a new session
+            {
+                const sr = runtime.repos.session;
+                const ss = await sr.getUserSessions(authUserId, runtime.config);
+                await Promise.all(ss.map(s => sr.deleteSession(s.sessionId, runtime.config)));
+            }
+            const { createSessionForUser } = await import('../services/auth');
+            const metadata = {
+                ipAddress: getClientIp(c) !== 'unknown' ? getClientIp(c) : undefined,
+                userAgent: c.req.header('user-agent') ?? undefined,
+            };
+            const newSession = await createSessionForUser(authUserId, runtime, metadata, hookCtx(c));
+            setCookie(c, COOKIE_TOKEN, newSession.token, cookieOptions(refreshTokens ? (getConfig().refreshToken?.accessTokenExpiry ?? 900) : undefined));
+            if (newSession.refreshToken) {
+                setCookie(c, COOKIE_REFRESH_TOKEN, newSession.refreshToken, cookieOptions(getConfig().refreshToken?.refreshTokenExpiry ?? 2_592_000));
+            }
+            return c.json({ ok: true, token: newSession.token }, 200);
+        }
+        else if (pwChangePolicy === 'revoke_others') {
+            {
+                const sr = runtime.repos.session;
+                const ss = await sr.getUserSessions(authUserId, runtime.config);
+                const others = ss.filter(s => s.sessionId !== currentSessionId);
+                await Promise.all(others.map(s => sr.deleteSession(s.sessionId, runtime.config)));
+            }
+        }
+        // "none" or unrecognized: no session action
+        return c.json({ ok: true }, 200);
+    });
+    router.openapi(createRoute({
+        method: 'post',
+        path: '/auth/logout',
+        summary: 'Log out',
+        description: 'Invalidates the current session and clears the session cookie. Safe to call even without an active session.',
+        tags,
+        responses: {
+            200: {
+                content: { 'application/json': { schema: SuccessResponse } },
+                description: 'Logged out. Session is invalidated and cookie is cleared.',
+            },
+        },
+    }), async (c) => {
+        const token = getCookie(c, COOKIE_TOKEN) ?? c.req.header(HEADER_USER_TOKEN) ?? null;
+        await AuthService.logout(token, runtime);
+        deleteCookie(c, COOKIE_TOKEN, { path: '/' });
+        deleteCookie(c, COOKIE_REFRESH_TOKEN, { path: '/' });
+        if (getConfig().csrfEnabled)
+            clearCsrfToken(c);
+        return c.json({ ok: true }, 200);
+    });
+    // Email verification routes — only mounted when emailVerification is configured and primaryField is "email"
+    if (emailVerification && primaryField === 'email') {
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/verify-email',
+            summary: 'Verify email address',
+            description: 'Consumes a single-use email verification token and marks the account as verified. The token is delivered via the auth:delivery.email_verification bus event. Rate-limited by IP.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                token: z.string().describe('Single-use verification token received via email.'),
+                            }),
+                        },
+                    },
+                    description: 'Verification token.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: SuccessResponse } },
+                    description: 'Email verified successfully.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Invalid or expired verification token.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many verification attempts from this IP. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`verify:${ip}`, verifyOpts)) {
+                return c.json({ error: 'Too many verification attempts. Try again later.' }, 429);
+            }
+            const { token } = c.req.valid('json');
+            const entry = await consumeVerificationToken(runtime.repos.verificationToken, token);
+            if (!entry)
+                return c.json({ error: 'Invalid or expired verification token' }, 400);
+            if (adapter.setEmailVerified)
+                await adapter.setEmailVerified(entry.userId, true);
+            eventBus.emit('auth:email.verified', { userId: entry.userId, email: entry.email });
+            if (getConfig().csrfEnabled)
+                refreshCsrfToken(c);
+            return c.json({ ok: true }, 200);
+        });
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/resend-verification',
+            summary: 'Resend verification email',
+            description: 'Authenticates with credentials and sends a new verification email. Always returns 200 for valid credentials regardless of verification status, to prevent user enumeration. Rate-limited per identifier. Does not require a session.',
+            tags,
+            request: {
+                body: {
+                    content: { 'application/json': { schema: LoginSchema } },
+                    description: 'Login credentials to identify the account.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: z.object({ message: z.string() }) } },
+                    description: 'Verification email sent, or account is already verified (indistinguishable by design).',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'No email address on file for this account.',
+                },
+                401: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Invalid credentials.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many resend attempts for this identifier. Try again later.',
+                },
+                501: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'The configured auth adapter does not support email verification.',
+                },
+            },
+        }), async (c) => {
+            if (!adapter.getEmailVerified || !adapter.getUser) {
+                return c.json({ error: 'Auth adapter does not support email verification' }, 501);
+            }
+            const body = c.req.valid('json');
+            const identifier = body[primaryField];
+            if (await runtime.rateLimit.trackAttempt(`resend:${identifier}`, resendOpts)) {
+                return c.json({ error: 'Too many resend attempts. Try again later.' }, 429);
+            }
+            const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
+            const user = await findFn(identifier);
+            // Always call Bun.password.verify to prevent timing-based user enumeration.
+            // When user is not found or has no passwordHash (OAuth-only account), verify
+            // against a dummy hash so response time is constant regardless of user existence.
+            const RESEND_DUMMY_HASH = '$argon2id$v=19$m=65536,t=2,p=1$dummysaltfortimingleak00000000000$dummyhashoutputfortimingprotection0000000';
+            const hashToVerify = user?.passwordHash ?? RESEND_DUMMY_HASH;
+            const passwordValid = await Bun.password.verify(body.password, hashToVerify);
+            if (!user || !passwordValid) {
+                return c.json({ error: 'Invalid credentials' }, 401);
+            }
+            const alreadyVerified = await adapter.getEmailVerified(user.id);
+            // Return 200 (not 400) to avoid revealing whether the account is verified —
+            // distinguishing verified vs unverified would let attackers confirm valid credentials.
+            if (alreadyVerified)
+                return c.json({ message: 'Verification email sent if not already verified' }, 200);
+            const fullUser = await adapter.getUser(user.id);
+            if (!fullUser?.email)
+                return c.json({ error: 'No email address on file' }, 400);
+            const verificationToken = await createVerificationToken(runtime.repos.verificationToken, user.id, fullUser.email, runtime.config);
+            eventBus.emit('auth:delivery.email_verification', {
+                email: fullUser.email,
+                token: verificationToken,
+                userId: user.id,
+            });
+            return c.json({ message: 'Verification email sent' }, 200);
+        });
+    }
+    // Password reset routes — only mounted when passwordReset is configured and primaryField is "email"
+    if (passwordReset && primaryField === 'email') {
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/forgot-password',
+            summary: 'Request password reset',
+            description: 'Sends a password reset email if the address is registered. Always returns 200 regardless of whether the address exists, to prevent email enumeration. Rate-limited by both IP and email address.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                email: z.string().email().describe('Email address to send the reset link to.'),
+                            }),
+                        },
+                    },
+                    description: 'Email address for the account to reset.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: z.object({ message: z.string() }) } },
+                    description: 'Request received. A reset email will be sent if the address is registered.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Validation error (e.g. not a valid email address).',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many attempts from this IP or for this email address. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            const { email } = c.req.valid('json');
+            // Rate-limit by both IP and email to prevent distributed email-bombing
+            const ipLimited = await runtime.rateLimit.trackAttempt(`forgot:ip:${ip}`, forgotOpts);
+            const emailLimited = await runtime.rateLimit.trackAttempt(`forgot:email:${email}`, forgotOpts);
+            if (ipLimited || emailLimited) {
+                return c.json({ error: 'Too many attempts. Try again later.' }, 429);
+            }
+            const user = adapter.findByEmail ? await adapter.findByEmail(email) : null;
+            // Fire-and-forget: the response does not wait for token creation or email sending,
+            // which reduces obvious timing differences between registered and unregistered emails.
+            const msg = {
+                message: 'If that email is registered, a password reset link has been sent.',
+            };
+            if (user) {
+                void (async () => {
+                    try {
+                        const token = await createResetToken(runtime.repos.resetToken, user.id, email, runtime.config);
+                        eventBus.emit('auth:delivery.password_reset', { email, token });
+                        eventBus.emit('auth:password.reset.requested', { userId: user.id, email });
+                    }
+                    catch (err) {
+                        console.error('Failed to send password reset email:', err instanceof Error ? err.message : String(err));
+                    }
+                })();
+            }
+            return c.json(msg, 200);
+        });
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/reset-password',
+            summary: 'Reset password',
+            description: 'Consumes a single-use reset token and sets a new password. All active sessions are revoked after a successful reset to invalidate any stolen JWTs. Rate-limited by IP.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                token: z.string().describe('Single-use reset token received via email.'),
+                                password: resetPasswordSchema(runtime.config.passwordPolicy).describe('New password.'),
+                            }),
+                        },
+                    },
+                    description: 'Reset token and new password.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: SuccessResponse } },
+                    description: 'Password reset. All sessions have been revoked.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Validation error, or the reset token is invalid or expired.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many reset attempts from this IP. Try again later.',
+                },
+                501: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'The configured auth adapter does not support setPassword.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`reset:${ip}`, resetOpts)) {
+                return c.json({ error: 'Too many attempts. Try again later.' }, 429);
+            }
+            const { token, password } = c.req.valid('json');
+            const breachConfig = getConfig().breachedPassword;
+            if (breachConfig) {
+                const { breached } = await checkBreachedPassword(password, breachConfig, undefined, runtime.eventBus);
+                if (breached && breachConfig.block !== false) {
+                    throw new HttpError(400, 'This password has appeared in a data breach. Please choose a different password.', 'BREACHED_PASSWORD');
+                }
+            }
+            // consumeResetToken atomically gets and deletes — prevents concurrent replay
+            const entry = await consumeResetToken(runtime.repos.resetToken, token);
+            if (!entry)
+                return c.json({ error: 'Invalid or expired reset token' }, 400);
+            if (!adapter.setPassword) {
+                return c.json({ error: 'Auth adapter does not support setPassword' }, 501);
+            }
+            const passwordHash = await Bun.password.hash(password);
+            // Password reuse check
+            const preventReuseReset = getConfig().passwordPolicy.preventReuse ?? 0;
+            if (preventReuseReset > 0) {
+                const isNew = await checkPasswordNotReused(adapter, entry.userId, password, preventReuseReset);
+                if (!isNew) {
+                    return c.json({ error: 'You cannot reuse a recent password.', code: 'PASSWORD_PREVIOUSLY_USED' }, 400);
+                }
+            }
+            const hooks = getConfig().hooks;
+            const ctx = hookCtx(c);
+            if (hooks.prePasswordChange)
+                await hooks.prePasswordChange({ userId: entry.userId, ...ctx });
+            await adapter.setPassword(entry.userId, passwordHash);
+            if (preventReuseReset > 0)
+                await recordPasswordChange(adapter, entry.userId, passwordHash, preventReuseReset);
+            // Revoke all sessions so stolen JWTs can't stay valid after a reset
+            {
+                const sr = runtime.repos.session;
+                const ss = await sr.getUserSessions(entry.userId, runtime.config);
+                await Promise.all(ss.map(s => sr.deleteSession(s.sessionId, runtime.config)));
+            }
+            eventBus.emit('security.auth.password.reset', {});
+            if (hooks.postPasswordChange) {
+                Promise.resolve()
+                    .then(() => hooks.postPasswordChange({ userId: entry.userId, ...ctx }))
+                    .catch(e => console.error('[lifecycle] postPasswordChange hook error:', e instanceof Error ? e.message : String(e)));
+            }
+            return c.json({ ok: true }, 200);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Refresh token route — only mounted when refreshTokens is configured
+    // ---------------------------------------------------------------------------
+    if (refreshTokens) {
+        const RefreshResponse = z
+            .object({
+            token: z.string().describe('New short-lived JWT access token.'),
+            userId: z.string().describe('Unique user ID.'),
+        })
+            .openapi('RefreshResponse');
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/refresh',
+            summary: 'Refresh access token',
+            description: 'Exchanges a valid refresh token for a new access token and rotated refresh token. The old refresh token remains valid for a short grace window to handle network drops. If a previously rotated token is reused after the grace window, the entire session is invalidated (token theft detection).',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                refreshToken: z
+                                    .string()
+                                    .optional()
+                                    .describe('Refresh token. Can also be sent via the refresh_token cookie or x-refresh-token header.'),
+                            }),
+                        },
+                    },
+                    description: 'Refresh token (optional if sent via cookie or header).',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: RefreshResponse } },
+                    description: 'New access and refresh tokens.',
+                },
+                401: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Invalid or expired refresh token, or session invalidated due to token theft detection.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many refresh attempts. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`refresh:ip:${ip}`, { max: 30, windowMs: 60_000 })) {
+                return c.json({ error: 'Too many refresh attempts. Try again later.' }, 429);
+            }
+            const body = c.req.valid('json');
+            const rt = body.refreshToken ??
+                getCookie(c, COOKIE_REFRESH_TOKEN) ??
+                c.req.header(HEADER_REFRESH_TOKEN) ??
+                null;
+            if (!rt) {
+                return c.json({ error: 'Refresh token is required' }, 401);
+            }
+            const result = await AuthService.refresh(rt, runtime);
+            setCookie(c, COOKIE_TOKEN, result.token, cookieOptions(getConfig().refreshToken?.accessTokenExpiry ?? 900));
+            setCookie(c, COOKIE_REFRESH_TOKEN, result.refreshToken, cookieOptions(getConfig().refreshToken?.refreshTokenExpiry ?? 2_592_000));
+            return c.json(result, 200);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Account deletion cancellation — only mounted when queued: true + gracePeriod > 0
+    // ---------------------------------------------------------------------------
+    if (accountDeletion?.queued && accountDeletion.gracePeriod) {
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/cancel-deletion',
+            summary: 'Cancel scheduled account deletion',
+            description: 'Cancels a pending queued account deletion using the cancel token delivered via the auth:delivery.account_deletion bus event. Must be called before the grace period expires.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                token: z
+                                    .string()
+                                    .describe('Cancel token received in the deletion scheduled notification.'),
+                            }),
+                        },
+                    },
+                    description: 'Cancel token.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: SuccessResponse } },
+                    description: 'Account deletion cancelled.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Invalid or expired cancel token.',
+                },
+            },
+        }), async (c) => {
+            const { token } = c.req.valid('json');
+            const entry = await consumeDeletionCancelToken(runtime.repos.deletionCancelToken, token);
+            if (!entry)
+                return c.json({ error: 'Invalid or expired cancel token' }, 400);
+            // Remove the pending BullMQ job
+            try {
+                const appName = runtime.config.appName;
+                const queue = runtime.queueFactory.createQueue(`${appName}:account-deletions`);
+                const job = await queue.getJob(entry.jobId);
+                if (job)
+                    await job.remove();
+                await queue.close();
+            }
+            catch {
+                // Job may have already executed — that's an error case but we still consumed the token
+            }
+            return c.json({ ok: true }, 200);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Step-up MFA re-authentication — only mounted when stepUp is configured
+    // ---------------------------------------------------------------------------
+    if (stepUp) {
+        const stepUpOpts = {
+            windowMs: rateLimit?.mfaVerify?.windowMs ?? 15 * 60 * 1000,
+            max: rateLimit?.mfaVerify?.max ?? 10,
+        };
+        const stepUpSchema = z.object({
+            method: z
+                .enum(['totp', 'emailOtp', 'webauthn', 'password', 'recovery'])
+                .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).'),
+        });
+        router.use('/auth/step-up', userAuth);
+        router.openapi(withSecurity(createRoute({
+            method: 'post',
+            path: '/auth/step-up',
+            summary: 'Step-up MFA re-authentication',
+            description: 'Re-authenticates the current session via TOTP, email OTP, WebAuthn, recovery code, or password to satisfy step-up requirements for sensitive operations. On success, sets mfaVerifiedAt in the session.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: stepUpSchema,
+                        },
+                    },
+                    description: 'Verification credentials for re-authentication.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: z.object({ ok: z.literal(true) }) } },
+                    description: 'Step-up authentication successful.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'No verification parameter provided.',
+                },
+                401: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Invalid credentials or no valid session.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many step-up attempts. Try again later.',
+                },
+            },
+        }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`step-up:${ip}`, stepUpOpts)) {
+                return c.json({ error: 'Too many step-up attempts. Try again later.' }, 429);
+            }
+            const userId = c.get('authUserId');
+            const sessionId = c.get('sessionId');
+            const body = c.req.valid('json');
+            const { verifyAnyFactor } = await import('../services/mfa');
+            const valid = await verifyAnyFactor(userId, sessionId, runtime, {
+                method: body.method,
+                code: body.code,
+                password: body.password,
+                reauthToken: body.reauthToken,
+                webauthnResponse: body.webauthnResponse,
+            });
+            if (!valid) {
+                eventBus.emit('security.auth.step_up.failure', { userId });
+                return c.json({ error: 'Invalid credentials' }, 401);
+            }
+            await runtime.repos.session.setMfaVerifiedAt(sessionId);
+            eventBus.emit('security.auth.step_up.success', { userId });
+            return c.json({ ok: true }, 200);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Reauth challenge — always mounted; issues challenge tokens for emailOtp / webauthn factors
+    // ---------------------------------------------------------------------------
+    const reauthChallengeOpts = {
+        windowMs: rateLimit?.mfaVerify?.windowMs ?? 15 * 60 * 1000,
+        max: rateLimit?.mfaVerify?.max ?? 10,
+    };
+    router.use('/auth/reauth/challenge', userAuth);
+    router.openapi(withSecurity(createRoute({
+        method: 'post',
+        path: '/auth/reauth/challenge',
+        summary: 'Request a reauth challenge',
+        description: 'Issues a reauth challenge token for challenge-based MFA methods (email OTP, WebAuthn). The returned reauthToken must be passed to step-up, account deletion, or MFA disable endpoints. Direct methods (TOTP, password, recovery) do not require a challenge.',
+        tags,
+        responses: {
+            200: {
+                content: {
+                    'application/json': {
+                        schema: z.object({
+                            availableMethods: z
+                                .array(z.string())
+                                .describe('All MFA methods available for this user (including direct methods like totp and password).'),
+                            reauthToken: z
+                                .string()
+                                .optional()
+                                .describe('Challenge token for emailOtp or webauthn methods. Required when using those methods.'),
+                            webauthnOptions: z
+                                .record(z.string(), z.unknown())
+                                .optional()
+                                .describe('WebAuthn authentication options (present when WebAuthn is available).'),
+                        }),
+                    },
+                },
+                description: 'Reauth challenge issued.',
+            },
+            400: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'No challenge-based MFA methods configured for this user.',
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'No valid session.',
+            },
+            429: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Too many reauth attempts. Try again later.',
+            },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const ip = getClientIp(c);
+        if (await runtime.rateLimit.trackAttempt(`reauth-challenge:${ip}`, reauthChallengeOpts)) {
+            return c.json({ error: 'Too many reauth attempts. Try again later.' }, 429);
+        }
+        const userId = c.get('authUserId');
+        const sessionId = c.get('sessionId');
+        const mfaMethods = getConfig().mfa && adapter.getMfaMethods ? await adapter.getMfaMethods(userId) : [];
+        const hasPassword = adapter.hasPassword ? await adapter.hasPassword(userId) : false;
+        // Build availableMethods — all methods the user could potentially use
+        const availableMethods = [];
+        if (mfaMethods.includes('totp'))
+            availableMethods.push('totp');
+        if (mfaMethods.includes('emailOtp'))
+            availableMethods.push('emailOtp');
+        if (mfaMethods.includes('webauthn'))
+            availableMethods.push('webauthn');
+        if (hasPassword)
+            availableMethods.push('password');
+        if (mfaMethods.length > 0)
+            availableMethods.push('recovery');
+        // Generate challenge for challenge-based methods
+        const hasEmailOtp = mfaMethods.includes('emailOtp');
+        const hasWebAuthn = mfaMethods.includes('webauthn');
+        if (!hasEmailOtp && !hasWebAuthn) {
+            return c.json({ availableMethods }, 200);
+        }
+        let emailOtpHash;
+        let webauthnChallenge;
+        let webauthnOptions;
+        if (hasEmailOtp) {
+            const emailOtpConfig = getConfig().mfa?.emailOtp ?? null;
+            if (emailOtpConfig) {
+                const { generateEmailOtpCode } = await import('../services/mfa');
+                const { code, hash } = generateEmailOtpCode(runtime);
+                emailOtpHash = hash;
+                const user = adapter.getUser ? await adapter.getUser(userId) : null;
+                if (user?.email) {
+                    eventBus.emit('auth:delivery.email_otp', { email: user.email, code });
+                }
+            }
+        }
+        if (hasWebAuthn) {
+            const { generateWebAuthnAuthenticationOptions } = await import('../services/mfa');
+            const result = await generateWebAuthnAuthenticationOptions(userId, runtime);
+            if (result) {
+                webauthnChallenge = result.challenge;
+                webauthnOptions = result.options;
+            }
+        }
+        const { createReauthChallenge } = await import('../lib/mfaChallenge');
+        const reauthToken = await createReauthChallenge(runtime.repos.mfaChallenge, userId, sessionId, { emailOtpHash, webauthnChallenge }, runtime.config);
+        return c.json({ availableMethods, reauthToken, webauthnOptions }, 200);
+    });
+    // ---------------------------------------------------------------------------
+    // Session management
+    // ---------------------------------------------------------------------------
+    const SessionInfoSchema = z
+        .object({
+        sessionId: z.string().describe('Unique session identifier (UUID).'),
+        createdAt: z.number().describe('Unix timestamp (ms) when the session was created.'),
+        lastActiveAt: z
+            .number()
+            .describe('Unix timestamp (ms) of the most recent authenticated request (updated when trackLastActive is enabled).'),
+        expiresAt: z.number().describe('Unix timestamp (ms) when the session expires.'),
+        ipAddress: z.string().optional().describe('IP address of the client at session creation.'),
+        userAgent: z
+            .string()
+            .optional()
+            .describe('User-agent string of the client at session creation.'),
+        isActive: z.boolean().describe('Whether the session is currently valid and unexpired.'),
+    })
+        .openapi('SessionInfo');
+    router.use('/auth/sessions', userAuth);
+    router.use('/auth/sessions/*', userAuth);
+    router.openapi(withSecurity(createRoute({
+        method: 'get',
+        path: '/auth/sessions',
+        summary: 'List sessions',
+        description: 'Returns all sessions for the authenticated user. Includes inactive sessions when `sessionPolicy.includeInactiveSessions` is enabled. Requires a valid session.',
+        tags,
+        responses: {
+            200: {
+                content: {
+                    'application/json': { schema: z.object({ sessions: z.array(SessionInfoSchema) }) },
+                },
+                description: 'Sessions belonging to the authenticated user.',
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'No valid session.',
+            },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get('authUserId');
+        const sessions = await runtime.repos.session.getUserSessions(userId, runtime.config);
+        return c.json({ sessions }, 200);
+    });
+    router.openapi(withSecurity(createRoute({
+        method: 'delete',
+        path: '/auth/sessions/{sessionId}',
+        summary: 'Revoke a session',
+        description: "Revokes a specific session by ID. Users can only revoke their own sessions. Useful for 'sign out of other devices' flows. Requires a valid session.",
+        tags,
+        request: {
+            params: z.object({ sessionId: z.string().describe('UUID of the session to revoke.') }),
+        },
+        responses: {
+            200: {
+                content: { 'application/json': { schema: SuccessResponse } },
+                description: 'Session revoked successfully.',
+            },
+            401: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'No valid session.',
+            },
+            404: {
+                content: { 'application/json': { schema: ErrorResponse } },
+                description: 'Session not found or does not belong to the authenticated user.',
+            },
+        },
+    }), { cookieAuth: [] }, { userToken: [] }), async (c) => {
+        const userId = c.get('authUserId');
+        const { sessionId } = c.req.valid('param');
+        const sessions = await runtime.repos.session.getUserSessions(userId, runtime.config);
+        const session = sessions.find(s => s.sessionId === sessionId);
+        if (!session)
+            return c.json({ error: 'Session not found' }, 404);
+        await runtime.repos.session.deleteSession(sessionId, runtime.config);
+        eventBus.emit('security.auth.session.revoked', { userId, sessionId });
+        return c.json({ ok: true }, 200);
+    });
+    // ---------------------------------------------------------------------------
+    // Magic link / passwordless email login — only mounted when magicLink is configured
+    // ---------------------------------------------------------------------------
+    if (magicLink) {
+        const magicLinkRequestOpts = { windowMs: 15 * 60 * 1000, max: 5 };
+        const magicLinkVerifyOpts = { windowMs: 15 * 60 * 1000, max: 10 };
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/magic-link/request',
+            summary: 'Request a magic link',
+            description: "Sends a single-use magic link to the user's inbox. Always returns 200 regardless of whether the identifier is registered (enumeration-safe). Rate-limited by IP.",
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                identifier: z
+                                    .string()
+                                    .describe('The primary identifier (email, username, or phone) to send the magic link to.'),
+                            }),
+                        },
+                    },
+                    description: 'Login identifier.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: z.object({ message: z.string() }) } },
+                    description: 'If an account exists, a sign-in link has been sent.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many magic link requests from this IP. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`magic-link-request:${ip}`, magicLinkRequestOpts)) {
+                eventBus.emit('security.rate_limit.exceeded', { meta: { path: c.req.path } });
+                return c.json({ error: 'Too many requests. Try again later.' }, 429);
+            }
+            const { identifier } = c.req.valid('json');
+            const msg = { message: 'If an account exists, a sign-in link has been sent.' };
+            // Find user — enumeration-safe: same response regardless of existence
+            const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
+            const user = await findFn(identifier);
+            if (user) {
+                void (async () => {
+                    try {
+                        const ttl = getConfig().magicLink?.ttlSeconds ?? 900;
+                        const token = await createMagicLinkToken(runtime.repos.magicLink, user.id, ttl);
+                        const link = magicLink.linkBaseUrl
+                            ? `${magicLink.linkBaseUrl}?token=${token}`
+                            : token;
+                        eventBus.emit('auth:delivery.magic_link', { identifier, token, link });
+                    }
+                    catch (err) {
+                        console.error('[magic-link] Failed to send magic link:', err instanceof Error ? err.message : String(err));
+                    }
+                })();
+            }
+            return c.json(msg, 200);
+        });
+        router.openapi(createRoute({
+            method: 'post',
+            path: '/auth/magic-link/verify',
+            summary: 'Verify a magic link token',
+            description: 'Consumes a single-use magic link token and creates a session. Rate-limited by IP.',
+            tags,
+            request: {
+                body: {
+                    content: {
+                        'application/json': {
+                            schema: z.object({
+                                token: z
+                                    .string()
+                                    .describe('Single-use magic link token received via the sign-in link.'),
+                            }),
+                        },
+                    },
+                    description: 'Magic link token.',
+                },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: TokenResponse } },
+                    description: 'Authenticated. Returns a session token.',
+                },
+                400: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Invalid or expired magic link token.',
+                },
+                403: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Account suspended.',
+                },
+                429: {
+                    content: { 'application/json': { schema: ErrorResponse } },
+                    description: 'Too many attempts from this IP. Try again later.',
+                },
+            },
+        }), async (c) => {
+            const ip = getClientIp(c);
+            if (await runtime.rateLimit.trackAttempt(`magic-link-verify:${ip}`, magicLinkVerifyOpts)) {
+                eventBus.emit('security.rate_limit.exceeded', { meta: { path: c.req.path } });
+                return c.json({ error: 'Too many attempts. Try again later.' }, 429);
+            }
+            const { token } = c.req.valid('json');
+            const userId = await consumeMagicLinkToken(runtime.repos.magicLink, token);
+            if (!userId) {
+                return c.json({ error: 'Invalid or expired magic link token' }, 400);
+            }
+            // Check suspension before issuing session
+            const { getSuspended } = await import('../lib/suspension');
+            const suspensionStatus = await getSuspended(adapter, userId);
+            if (suspensionStatus.suspended) {
+                eventBus.emit('security.auth.login.blocked', {
+                    userId,
+                    reason: 'suspended',
+                    meta: { reason: 'suspended' },
+                });
+                return c.json({ error: 'Account suspended' }, 403);
+            }
+            const metadata = {
+                ipAddress: ip !== 'unknown' ? ip : undefined,
+                userAgent: c.req.header('user-agent') ?? undefined,
+            };
+            const { createSessionForUser } = await import('../services/auth');
+            const { token: sessionToken, refreshToken, sessionId, } = await createSessionForUser(userId, runtime, metadata, hookCtx(c));
+            setCookie(c, COOKIE_TOKEN, sessionToken, cookieOptions(refreshTokens ? (getConfig().refreshToken?.accessTokenExpiry ?? 900) : undefined));
+            if (refreshToken) {
+                setCookie(c, COOKIE_REFRESH_TOKEN, refreshToken, cookieOptions(getConfig().refreshToken?.refreshTokenExpiry ?? 2_592_000));
+            }
+            if (getConfig().csrfEnabled)
+                refreshCsrfToken(c);
+            emitLoginSuccess(userId, sessionId, runtime);
+            const fullUser = adapter.getUser ? await adapter.getUser(userId) : null;
+            const result = { token: sessionToken, userId, email: fullUser?.email, refreshToken };
+            return c.json(result, 200);
+        });
+    }
+    return router;
+};