@lastshotlabs/bunshot 0.0.27 → 0.0.28

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

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+const passwordSchema = (policy) => {
+    const minLen = policy.minLength ?? 8;
+    let schema = z.string().min(minLen, `Password must be at least ${minLen} characters`);
+    if (policy.requireLetter !== false) {
+        schema = schema.regex(/[a-zA-Z]/, 'Password must contain at least one letter');
+    }
+    if (policy.requireDigit !== false) {
+        schema = schema.regex(/\d/, 'Password must contain at least one digit');
+    }
+    if (policy.requireSpecial) {
+        schema = schema.regex(/[^a-zA-Z0-9]/, 'Password must contain at least one special character');
+    }
+    return schema;
+};
+export const makeRegisterSchema = (primaryField, policy) => z.object({
+    [primaryField]: primaryField === 'email' ? z.string().email().max(256) : z.string().min(3).max(256),
+    password: passwordSchema(policy).max(128),
+});
+export const makeLoginSchema = (primaryField) => z.object({
+    [primaryField]: primaryField === 'email' ? z.string().email().max(256) : z.string().min(1).max(256),
+    password: z.string().min(1).max(128),
+});
+export const resetPasswordSchema = (policy) => passwordSchema(policy);

package/dist/packages/bunshot-auth/src/schemas/error.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/**
+ * Canonical error response schema shared across all auth routes.
+ *
+ * M2M and SCIM routes intentionally use spec-compliant error shapes
+ * (RFC 6749 and SCIM RFC 7644 respectively) and do not use this schema.
+ */
+export declare const ErrorResponse: z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$strip>;

package/dist/packages/bunshot-auth/src/schemas/error.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/**
+ * Canonical error response schema shared across all auth routes.
+ *
+ * M2M and SCIM routes intentionally use spec-compliant error shapes
+ * (RFC 6749 and SCIM RFC 7644 respectively) and do not use this schema.
+ */
+export const ErrorResponse = z
+    .object({ error: z.string().describe('Human-readable error message.') })
+    .openapi('ErrorResponse');

package/dist/packages/bunshot-auth/src/schemas/success.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/**
+ * Canonical generic success response for auth routes.
+ *
+ * Use this for acknowledgement-style successes. Routes with domain data
+ * should extend this shape or return their domain object directly.
+ */
+export declare const SuccessResponse: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;

package/dist/packages/bunshot-auth/src/schemas/success.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/**
+ * Canonical generic success response for auth routes.
+ *
+ * Use this for acknowledgement-style successes. Routes with domain data
+ * should extend this shape or return their domain object directly.
+ */
+export const SuccessResponse = z
+    .object({ ok: z.literal(true).describe('Operation completed successfully.') })
+    .openapi('AuthSuccessResponse');

package/dist/packages/bunshot-auth/src/services/auth.d.ts

@@ -0,0 +1,39 @@
+import type { SessionMetadata } from '../lib/session';
+import type { HookContext } from '../config/authConfig';
+import type { AuthRuntimeContext } from '../runtime';
+export interface AuthResult {
+    token: string;
+    userId: string;
+    email?: string;
+    emailVerified?: boolean;
+    googleLinked?: boolean;
+    refreshToken?: string;
+    mfaRequired?: boolean;
+    mfaToken?: string;
+    mfaMethods?: string[];
+    webauthnOptions?: Record<string, unknown>;
+}
+export declare const runPreLoginHook: (identifier: string, runtime: AuthRuntimeContext, hookContext?: HookContext) => Promise<void>;
+export declare const emitLoginSuccess: (userId: string, sessionId: string, runtime: AuthRuntimeContext) => void;
+/** Create a session for a user (used internally and by MFA verify). */
+export declare const createSessionForUser: (userId: string, runtime: AuthRuntimeContext, metadata?: SessionMetadata, hookContext?: HookContext) => Promise<{
+    token: string;
+    refreshToken?: string;
+    sessionId: string;
+}>;
+export interface RegisterOptions {
+    metadata?: SessionMetadata;
+    /** When true, skip session creation. Returns { userId } without a token. */
+    skipSession?: boolean;
+    hookContext?: HookContext;
+}
+export declare const register: (identifier: string, password: string, runtime: AuthRuntimeContext, metadataOrOptions?: SessionMetadata | RegisterOptions) => Promise<AuthResult>;
+export declare const login: (identifier: string, password: string, runtime: AuthRuntimeContext, metadata?: SessionMetadata, hookContext?: HookContext) => Promise<AuthResult>;
+export declare const refresh: (refreshTokenValue: string, runtime: AuthRuntimeContext) => Promise<{
+    token: string;
+    refreshToken: string;
+    userId: string;
+}>;
+export declare const deleteAccount: (userId: string, runtime: AuthRuntimeContext, password?: string) => Promise<void>;
+export declare const logout: (token: string | null, runtime: AuthRuntimeContext) => Promise<void>;
+export declare const passkeyLogin: (passkeyToken: string, assertionResponse: any, runtime: AuthRuntimeContext, metadata?: SessionMetadata, hookContext?: HookContext) => Promise<AuthResult>;

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

@@ -0,0 +1,378 @@
+import { createVerificationToken } from '../lib/emailVerification';
+import { signToken, verifyToken } from '../lib/jwt';
+import { createMfaChallenge } from '../lib/mfaChallenge';
+import { getSuspended } from '../lib/suspension';
+import { generateEmailOtpCode, generateWebAuthnAuthenticationOptions } from '../services/mfa';
+import { HttpError } from '../../../bunshot-core/src/index.js';
+export const runPreLoginHook = async (identifier, runtime, hookContext) => {
+    const hooks = runtime.config.hooks;
+    if (hooks.preLogin)
+        await hooks.preLogin({ identifier, ...hookContext });
+};
+export const emitLoginSuccess = (userId, sessionId, runtime) => {
+    runtime.eventBus.emit('security.auth.login.success', { userId });
+    runtime.eventBus.emit('auth:login', { userId, sessionId });
+};
+async function createSessionWithRefreshToken(userId, sessionId, runtime, metadata, hookContext) {
+    const { config, eventBus } = runtime;
+    const hooks = config.hooks;
+    // Fire postLogin before signing the token so customClaims can be injected
+    let customClaims;
+    if (hooks.postLogin) {
+        try {
+            const result = await hooks.postLogin({ userId, sessionId, ...hookContext });
+            if (result && typeof result === 'object' && result.customClaims) {
+                customClaims = result.customClaims;
+            }
+        }
+        catch (e) {
+            console.error('[lifecycle] postLogin hook error:', e instanceof Error ? e.message : String(e));
+        }
+    }
+    const rtConfig = config.refreshToken;
+    // When refresh tokens are disabled the JWT is the sole credential, so it must carry an explicit
+    // expiry. Tie it to the configured session absolute timeout so the two stay in sync; fall back
+    // to 604 800 s (7 days) to preserve the historic default for deployments that haven't set
+    // absoluteTimeout. Operators who want shorter-lived tokens should configure absoluteTimeout.
+    const expirySeconds = rtConfig
+        ? (rtConfig.accessTokenExpiry ?? 900)
+        : (config.sessionPolicy?.absoluteTimeout ?? 604800);
+    // Strip JOSE-managed claims and the code-owned identity claims from customClaims so
+    // that a postLogin hook returning { exp: 0 } or { sub: "attacker" } cannot override them.
+    // The setter methods (setExpirationTime, setIssuedAt, setIssuer, setAudience) always win
+    // at the jose level, but stripping here keeps the payload object trustworthy before signing.
+    const RESERVED_CLAIMS = new Set(['exp', 'iat', 'nbf', 'iss', 'aud', 'jti', 'sub', 'sid']);
+    const safeClaims = customClaims
+        ? Object.fromEntries(Object.entries(customClaims).filter(([k]) => !RESERVED_CLAIMS.has(k)))
+        : undefined;
+    const claims = { sub: userId, sid: sessionId, ...safeClaims };
+    const token = await signToken(claims, expirySeconds, config, runtime.signing);
+    const sessionRepo = runtime.repos.session;
+    await sessionRepo.atomicCreateSession(userId, token, sessionId, config.maxSessions, metadata, config);
+    let refreshToken;
+    if (rtConfig) {
+        refreshToken = crypto.randomUUID();
+        await sessionRepo.setRefreshToken(sessionId, refreshToken, config);
+    }
+    eventBus.emit('security.auth.session.created', { userId, sessionId });
+    return { token, refreshToken, sessionId };
+}
+/** Create a session for a user (used internally and by MFA verify). */
+export const createSessionForUser = async (userId, runtime, metadata, hookContext) => {
+    const sessionId = crypto.randomUUID();
+    return createSessionWithRefreshToken(userId, sessionId, runtime, metadata, hookContext);
+};
+export const register = async (identifier, password, runtime, metadataOrOptions) => {
+    // Accept both old-style SessionMetadata and new RegisterOptions
+    let metadata;
+    let skipSession = false;
+    let hookContext;
+    if (metadataOrOptions &&
+        ('skipSession' in metadataOrOptions ||
+            'metadata' in metadataOrOptions ||
+            'hookContext' in metadataOrOptions)) {
+        const opts = metadataOrOptions;
+        metadata = opts.metadata;
+        skipSession = opts.skipSession ?? false;
+        hookContext = opts.hookContext;
+    }
+    else {
+        metadata = metadataOrOptions;
+    }
+    const { config, adapter, eventBus } = runtime;
+    const hooks = config.hooks;
+    if (hooks.preRegister)
+        await hooks.preRegister({ identifier, ...hookContext });
+    try {
+        const hashed = await Bun.password.hash(password);
+        const user = await adapter.create(identifier, hashed);
+        const role = config.defaultRole;
+        if (role)
+            await adapter.setRoles(user.id, [role]);
+        let token = '';
+        let refreshToken;
+        if (!skipSession) {
+            const sessionId = crypto.randomUUID();
+            const session = await createSessionWithRefreshToken(user.id, sessionId, runtime, metadata, hookContext);
+            token = session.token;
+            refreshToken = session.refreshToken;
+        }
+        const evConfig = config.emailVerification;
+        if (evConfig && config.primaryField === 'email') {
+            try {
+                const verificationToken = await createVerificationToken(runtime.repos.verificationToken, user.id, identifier, config);
+                eventBus.emit('auth:delivery.email_verification', {
+                    email: identifier,
+                    token: verificationToken,
+                    userId: user.id,
+                });
+                eventBus.emit('auth:delivery.welcome', { email: identifier, identifier });
+            }
+            catch (e) {
+                console.error('[email-verification] Failed to send verification email:', e instanceof Error ? e.message : String(e));
+            }
+        }
+        eventBus.emit('security.auth.register.success', { userId: user.id });
+        eventBus.emit('auth:user.created', { userId: user.id, email: identifier });
+        if (hooks.postRegister) {
+            Promise.resolve()
+                .then(() => hooks.postRegister({ userId: user.id, identifier, ...hookContext }))
+                .catch(e => console.error('[lifecycle] postRegister hook error:', e instanceof Error ? e.message : String(e)));
+        }
+        return { token, userId: user.id, email: identifier, refreshToken };
+    }
+    catch (err) {
+        eventBus.emit('security.auth.register.failure', {});
+        throw err;
+    }
+};
+// Pre-computed dummy hash so non-existent-user login takes the same time as wrong-password login
+const DUMMY_HASH = await Bun.password.hash('dummy-timing-safe-placeholder');
+export const login = async (identifier, password, runtime, metadata, hookContext) => {
+    const { config, adapter, eventBus } = runtime;
+    await runPreLoginHook(identifier, runtime, hookContext);
+    const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
+    const user = await findFn(identifier);
+    // Always verify against a hash to prevent timing-based user enumeration.
+    // Lockout check is intentionally AFTER bcrypt to prevent timing leaks —
+    // locked accounts must take the same bcrypt time as non-existent users.
+    const hashToVerify = user?.passwordHash ?? DUMMY_HASH;
+    const passwordValid = await Bun.password.verify(password, hashToVerify);
+    // Check lockout after bcrypt so locked and non-existent users are indistinguishable by timing
+    const lockoutSvc = runtime.lockout;
+    if (user && lockoutSvc && (await lockoutSvc.isAccountLocked(user.id))) {
+        eventBus.emit('security.auth.login.blocked', {
+            userId: user.id,
+            reason: 'lockout',
+            meta: { reason: 'account_locked' },
+        });
+        throw new HttpError(423, 'Account is locked due to too many failed login attempts', 'ACCOUNT_LOCKED');
+    }
+    if (!user || !passwordValid) {
+        eventBus.emit('security.auth.login.failure', { identifier, meta: { identifier } });
+        // Track failed attempts for lockout (only when user exists — can't lock unknown accounts)
+        if (user && lockoutSvc) {
+            const count = await lockoutSvc.recordFailedAttempt(user.id);
+            if (count >= lockoutSvc.config.maxAttempts) {
+                await lockoutSvc.lockAccount(user.id);
+                eventBus.emit('security.auth.account.locked', {
+                    userId: user.id,
+                    meta: { identifier, attempts: count },
+                });
+                if (lockoutSvc.config.onLocked) {
+                    Promise.resolve()
+                        .then(() => lockoutSvc.config.onLocked(user.id, identifier))
+                        .catch(() => {
+                        /* swallow — notification must never crash login */
+                    });
+                }
+            }
+        }
+        throw new HttpError(401, 'Invalid credentials');
+    }
+    // Check suspension
+    const suspensionStatus = await getSuspended(adapter, user.id);
+    if (suspensionStatus.suspended) {
+        eventBus.emit('security.auth.login.blocked', {
+            reason: 'suspended',
+            meta: { reason: 'suspended' },
+        });
+        throw new HttpError(403, 'Account suspended', 'ACCOUNT_SUSPENDED');
+    }
+    // Check email verification before MFA to avoid leaking MFA status to unverified users
+    const fullUser = adapter.getUser ? await adapter.getUser(user.id) : null;
+    const googleLinked = fullUser?.providerIds?.some(id => id.startsWith('google:')) ?? false;
+    const evConfig = config.emailVerification;
+    if (evConfig && config.primaryField === 'email' && adapter.getEmailVerified) {
+        const verified = await adapter.getEmailVerified(user.id);
+        if (evConfig.required && !verified) {
+            throw new HttpError(403, 'Email not verified');
+        }
+    }
+    // Check MFA — if enabled, return challenge token instead of session
+    if (config.mfa && adapter.isMfaEnabled && (await adapter.isMfaEnabled(user.id))) {
+        const methods = adapter.getMfaMethods ? await adapter.getMfaMethods(user.id) : ['totp'];
+        // Auto-send email OTP if enabled
+        let emailOtpHash;
+        const emailOtpConfig = config.mfa?.emailOtp ?? null;
+        if (methods.includes('emailOtp') && emailOtpConfig) {
+            const { code, hash } = generateEmailOtpCode(runtime);
+            emailOtpHash = hash;
+            const email = fullUser?.email;
+            if (email)
+                eventBus.emit('auth:delivery.email_otp', { email, code });
+        }
+        // Generate WebAuthn authentication options if enabled
+        let webauthnChallenge;
+        let webauthnOptions;
+        const webauthnConfig = config.mfa?.webauthn ?? null;
+        if (methods.includes('webauthn') && webauthnConfig && adapter.getWebAuthnCredentials) {
+            const result = await generateWebAuthnAuthenticationOptions(user.id, runtime);
+            if (result) {
+                webauthnChallenge = result.challenge;
+                webauthnOptions = result.options;
+            }
+        }
+        const mfaToken = await createMfaChallenge(runtime.repos.mfaChallenge, user.id, { emailOtpHash, webauthnChallenge }, config);
+        return {
+            token: '',
+            userId: user.id,
+            mfaRequired: true,
+            mfaToken,
+            mfaMethods: methods,
+            webauthnOptions,
+        };
+    }
+    const sessionId = crypto.randomUUID();
+    const { token, refreshToken } = await createSessionWithRefreshToken(user.id, sessionId, runtime, metadata, hookContext);
+    // Reset failure counter on successful login (opt-out via resetOnSuccess: false)
+    if (lockoutSvc && lockoutSvc.config.resetOnSuccess !== false) {
+        await lockoutSvc.resetFailureCount(user.id);
+    }
+    emitLoginSuccess(user.id, sessionId, runtime);
+    if (evConfig && config.primaryField === 'email' && adapter.getEmailVerified) {
+        const verified = await adapter.getEmailVerified(user.id);
+        return {
+            token,
+            userId: user.id,
+            email: fullUser?.email,
+            emailVerified: verified,
+            googleLinked,
+            refreshToken,
+        };
+    }
+    return { token, userId: user.id, email: fullUser?.email, googleLinked, refreshToken };
+};
+export const refresh = async (refreshTokenValue, runtime) => {
+    const sessionRepo = runtime.repos.session;
+    const result = await sessionRepo.getSessionByRefreshToken(refreshTokenValue, runtime.config);
+    if (!result) {
+        throw new HttpError(401, 'Invalid or expired refresh token');
+    }
+    const { sessionId, userId } = result;
+    // Always rotate: generate new refresh + access tokens.
+    // Refresh tokens are stored as hashes — we can never return a stored plaintext token.
+    // Even in the grace window case (old token used after rotation), we issue fresh tokens.
+    // This is safe because the old token's hash was found in the prev slot, not the current slot,
+    // so the session is valid and the client just missed the previous rotation response.
+    const newRT = crypto.randomUUID();
+    const newAccessToken = await signToken({ sub: userId, sid: sessionId }, runtime.config.refreshToken?.accessTokenExpiry ?? 900, runtime.config, runtime.signing);
+    await sessionRepo.rotateRefreshToken(sessionId, newRT, newAccessToken, runtime.config);
+    await sessionRepo.updateSessionLastActive(sessionId, runtime.config);
+    return { token: newAccessToken, refreshToken: newRT, userId };
+};
+export const deleteAccount = async (userId, runtime, password) => {
+    const { adapter, config, eventBus } = runtime;
+    const hooks = config.hooks;
+    if (hooks.preDeleteAccount)
+        await hooks.preDeleteAccount({ userId });
+    if (!adapter.deleteUser) {
+        throw new HttpError(501, 'Auth adapter does not support deleteUser');
+    }
+    // Verify password for credential accounts
+    if (password) {
+        const user = adapter.getUser ? await adapter.getUser(userId) : null;
+        const email = user?.email;
+        if (email) {
+            const findFn = adapter.findByIdentifier ?? adapter.findByEmail.bind(adapter);
+            const found = await findFn(email);
+            if (found && !(await Bun.password.verify(password, found.passwordHash))) {
+                throw new HttpError(401, 'Invalid password');
+            }
+        }
+    }
+    else if (adapter.hasPassword && (await adapter.hasPassword(userId))) {
+        throw new HttpError(400, 'Password is required to delete a credential account');
+    }
+    // Revoke all sessions
+    const sessionRepo = runtime.repos.session;
+    const sessions = await sessionRepo.getUserSessions(userId, config);
+    await Promise.all(sessions.map(s => sessionRepo.deleteSession(s.sessionId, config)));
+    // Delete the user
+    await adapter.deleteUser(userId);
+    eventBus.emit('security.auth.account.deleted', { userId });
+    eventBus.emit('auth:user.deleted', { userId });
+    if (hooks.postDeleteAccount) {
+        Promise.resolve()
+            .then(() => hooks.postDeleteAccount({ userId }))
+            .catch(e => console.error('[lifecycle] postDeleteAccount hook error:', e instanceof Error ? e.message : String(e)));
+    }
+};
+export const logout = async (token, runtime) => {
+    if (token) {
+        const payload = await verifyToken(token, runtime.config, runtime.signing);
+        const sessionId = payload.sid;
+        const userId = payload.sub;
+        if (sessionId) {
+            await runtime.repos.session.deleteSession(sessionId, runtime.config);
+            runtime.eventBus.emit('security.auth.logout', { sessionId, userId });
+            if (userId) {
+                runtime.eventBus.emit('auth:logout', { userId, sessionId });
+            }
+        }
+    }
+};
+export const passkeyLogin = async (passkeyToken, assertionResponse, runtime, metadata, hookContext) => {
+    const { adapter, config, eventBus } = runtime;
+    if (!adapter.findUserByWebAuthnCredentialId || !adapter.getWebAuthnCredentials) {
+        throw new HttpError(501, 'Auth adapter does not support passkey login');
+    }
+    const { consumePasskeyLoginChallenge } = await import('../lib/mfaChallenge');
+    const challengeData = await consumePasskeyLoginChallenge(runtime.repos.mfaChallenge, passkeyToken);
+    if (!challengeData) {
+        throw new HttpError(401, 'Invalid or expired passkey token');
+    }
+    const credentialId = assertionResponse?.id;
+    if (!credentialId ||
+        typeof credentialId !== 'string' ||
+        credentialId.length === 0 ||
+        credentialId.length > 2048) {
+        throw new HttpError(401, 'Invalid assertion response');
+    }
+    const userId = await adapter.findUserByWebAuthnCredentialId(credentialId);
+    if (!userId) {
+        throw new HttpError(401, 'Invalid credentials');
+    }
+    const { verifyWebAuthn } = await import('../services/mfa');
+    const verified = await verifyWebAuthn(userId, assertionResponse, challengeData.webauthnChallenge, runtime);
+    if (!verified) {
+        throw new HttpError(401, 'WebAuthn verification failed');
+    }
+    const fullUser = adapter.getUser ? await adapter.getUser(userId) : null;
+    await runPreLoginHook(fullUser?.email ?? userId, runtime, hookContext);
+    // Check suspension
+    const suspensionStatus = await getSuspended(adapter, userId);
+    if (suspensionStatus.suspended) {
+        throw new HttpError(403, 'Account suspended', 'ACCOUNT_SUSPENDED');
+    }
+    // passkeyMfaBypass=true (default): passkey with userVerification=required satisfies both factors
+    const mfaBypass = config.mfa?.webauthn?.passkeyMfaBypass ?? true;
+    if (!mfaBypass && config.mfa && adapter.isMfaEnabled && (await adapter.isMfaEnabled(userId))) {
+        const methods = adapter.getMfaMethods ? await adapter.getMfaMethods(userId) : ['totp'];
+        let emailOtpHash;
+        const emailOtpConfig = config.mfa?.emailOtp ?? null;
+        if (methods.includes('emailOtp') && emailOtpConfig) {
+            const { generateEmailOtpCode } = await import('../services/mfa');
+            const { code, hash } = generateEmailOtpCode(runtime);
+            emailOtpHash = hash;
+            const fullUser = adapter.getUser ? await adapter.getUser(userId) : null;
+            if (fullUser?.email)
+                eventBus.emit('auth:delivery.email_otp', { email: fullUser.email, code });
+        }
+        let webauthnChallenge2;
+        let webauthnOptions;
+        if (methods.includes('webauthn') && (config.mfa?.webauthn ?? null)) {
+            const { generateWebAuthnAuthenticationOptions } = await import('../services/mfa');
+            const result = await generateWebAuthnAuthenticationOptions(userId, runtime);
+            if (result) {
+                webauthnChallenge2 = result.challenge;
+                webauthnOptions = result.options;
+            }
+        }
+        const mfaToken = await createMfaChallenge(runtime.repos.mfaChallenge, userId, { emailOtpHash, webauthnChallenge: webauthnChallenge2 }, config);
+        return { token: '', userId, mfaRequired: true, mfaToken, mfaMethods: methods, webauthnOptions };
+    }
+    const { token, refreshToken, sessionId } = await createSessionForUser(userId, runtime, metadata, hookContext);
+    emitLoginSuccess(userId, sessionId, runtime);
+    return { token, userId, email: fullUser?.email, refreshToken };
+};

package/dist/{services → packages/bunshot-auth/src/services}/mfa.d.ts

@@ -1,15 +1,16 @@
+import type { AuthRuntimeContext } from '../runtime';
 export interface MfaSetupResult {
     secret: string;
     uri: string;
 }
-export declare const setupMfa: (userId: string) => Promise<MfaSetupResult>;
-export declare const verifySetup: (userId: string, code: string) => Promise<string[]>;
-export declare const verifyTotp: (userId: string, code: string) => Promise<boolean>;
-export declare const verifyRecoveryCode: (userId: string, code: string) => Promise<boolean>;
-export declare const disableMfa: (userId: string, code: string) => Promise<void>;
-export declare const regenerateRecoveryCodes: (userId: string, code: string) => Promise<string[]>;
+export declare const setupMfa: (userId: string, runtime: AuthRuntimeContext) => Promise<MfaSetupResult>;
+export declare const verifySetup: (userId: string, code: string, runtime: AuthRuntimeContext) => Promise<string[]>;
+export declare const verifyTotp: (userId: string, code: string, runtime: AuthRuntimeContext) => Promise<boolean>;
+export declare const verifyRecoveryCode: (userId: string, code: string, runtime: AuthRuntimeContext) => Promise<boolean>;
+export declare const disableMfa: (userId: string, code: string, runtime: AuthRuntimeContext) => Promise<void>;
+export declare const regenerateRecoveryCodes: (userId: string, code: string, runtime: AuthRuntimeContext) => Promise<string[]>;
 /** Generate a cryptographically random numeric OTP code. Returns { code, hash }. */
-export declare const generateEmailOtpCode: (length?: number) => {
+export declare const generateEmailOtpCode: (runtime: AuthRuntimeContext, length?: number) => {
     code: string;
     hash: string;
 };
@@ -19,12 +20,12 @@ export declare const verifyEmailOtp: (emailOtpHash: string, code: string) => boo
  * Initiate email OTP setup: sends a verification code to the user's email.
  * Returns a setup challenge token that must be confirmed via confirmEmailOtp.
  */
-export declare const initiateEmailOtp: (userId: string) => Promise<string>;
+export declare const initiateEmailOtp: (userId: string, runtime: AuthRuntimeContext) => Promise<string>;
 /**
  * Confirm email OTP setup: verifies the code sent during initiateEmailOtp.
  * Enables email OTP as an MFA method. Returns recovery codes if MFA was not previously active.
  */
-export declare const confirmEmailOtp: (userId: string, setupToken: string, code: string) => Promise<string[] | null>;
+export declare const confirmEmailOtp: (userId: string, setupToken: string, code: string, runtime: AuthRuntimeContext) => Promise<string[] | null>;
 /**
  * Disable email OTP for a user.
  * If TOTP is also enabled, requires a TOTP code. Otherwise requires password.
@@ -32,9 +33,9 @@ export declare const confirmEmailOtp: (userId: string, setupToken: string, code:
 export declare const disableEmailOtp: (userId: string, params: {
     code?: string;
     password?: string;
-}) => Promise<void>;
+}, runtime: AuthRuntimeContext) => Promise<void>;
 /** Get the MFA methods enabled for a user. */
-export declare const getMfaMethods: (userId: string) => Promise<string[]>;
+export declare const getMfaMethods: (userId: string, runtime: AuthRuntimeContext) => Promise<string[]>;
 /**
  * Eager startup check — call at route mount time to fail fast if the peer dependency is missing.
  */
@@ -43,7 +44,7 @@ export declare const assertWebAuthnDependency: () => Promise<void>;
  * Generate WebAuthn authentication options for the login MFA flow.
  * Called from auth.ts login when the user has "webauthn" in their methods.
  */
-export declare const generateWebAuthnAuthenticationOptions: (userId: string) => Promise<{
+export declare const generateWebAuthnAuthenticationOptions: (userId: string, runtime: AuthRuntimeContext) => Promise<{
     challenge: string;
     options: Record<string, unknown>;
 } | null>;
@@ -51,7 +52,7 @@ export declare const generateWebAuthnAuthenticationOptions: (userId: string) =>
  * Initiate WebAuthn registration: generates registration options for the client.
  * Returns options + a registration challenge token.
  */
-export declare const initiateWebAuthnRegistration: (userId: string) => Promise<{
+export declare const initiateWebAuthnRegistration: (userId: string, runtime: AuthRuntimeContext) => Promise<{
     options: Record<string, unknown>;
     registrationToken: string;
 }>;
@@ -59,14 +60,14 @@ export declare const initiateWebAuthnRegistration: (userId: string) => Promise<{
  * Complete WebAuthn registration: verifies attestation and stores the credential.
  * Returns recovery codes if this is the first MFA method.
  */
-export declare const completeWebAuthnRegistration: (userId: string, registrationToken: string, attestationResponse: any, name?: string) => Promise<{
+export declare const completeWebAuthnRegistration: (userId: string, registrationToken: string, attestationResponse: any, runtime: AuthRuntimeContext, name?: string) => Promise<{
     credentialId: string;
     recoveryCodes: string[] | null;
 }>;
 /**
  * Verify a WebAuthn authentication assertion during login MFA.
  */
-export declare const verifyWebAuthn: (userId: string, assertionResponse: any, expectedChallenge: string) => Promise<boolean>;
+export declare const verifyWebAuthn: (userId: string, assertionResponse: any, expectedChallenge: string, runtime: AuthRuntimeContext) => Promise<boolean>;
 /**
  * Remove a single WebAuthn credential.
  * Only requires identity verification when removing the last credential of the last MFA method.
@@ -74,11 +75,34 @@ export declare const verifyWebAuthn: (userId: string, assertionResponse: any, ex
 export declare const removeWebAuthnCredential: (userId: string, credentialId: string, params: {
     code?: string;
     password?: string;
-}) => Promise<void>;
+}, runtime: AuthRuntimeContext) => Promise<void>;
 /**
  * Disable WebAuthn entirely: removes all credentials and the method.
  */
 export declare const disableWebAuthn: (userId: string, params: {
     code?: string;
     password?: string;
-}) => Promise<void>;
+}, runtime: AuthRuntimeContext) => Promise<void>;
+/**
+ * Verify any supported authentication factor for a given user + session.
+ * Used by step-up, account deletion, and MFA disable flows.
+ *
+ * - "totp": TOTP code
+ * - "recovery": recovery code (only when method is explicitly "recovery")
+ * - "password": account password
+ * - "emailOtp": email OTP via reauth challenge token
+ * - "webauthn": WebAuthn assertion via reauth challenge token
+ *
+ * Hard boundaries:
+ *  - "recovery" is ONLY checked when method is explicitly "recovery"
+ *  - emailOtp / webauthn consume a reauth challenge bound to sessionId
+ *
+ * Returns false (never throws) when required params are missing.
+ */
+export declare function verifyAnyFactor(userId: string, sessionId: string, runtime: AuthRuntimeContext, params: {
+    method?: 'totp' | 'emailOtp' | 'webauthn' | 'password' | 'recovery';
+    code?: string;
+    password?: string;
+    reauthToken?: string;
+    webauthnResponse?: object;
+}): Promise<boolean>;