@adonis-agora/authkit-server 0.76.0 → 0.77.0

package/build/src/host/controllers/interaction_controller.js

@@ -3,6 +3,9 @@ import { supportsLoginMethodsPreference, supportsMagicLink, supportsOtpLogin, su
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { guardBotProtection, resolveEffectiveBotProtection } from '../bot_protection.js';
 import { brandFor, isFirstParty } from '../branding.js';
+import { isCustomLoginMethodId } from '../custom_login.js';
+import { completeCustomLoginSession } from '../custom_login_completion.js';
+import { beginCustomMfa, clearMfaFlow, customMfaViewProps, getMfaFlow, initializeMfaFlow, recordVerifiedMfaFactor, resolveCustomMfaMethods, verifyCustomMfa, } from '../custom_mfa.js';
 import { sendMagicLinkEmail, sendOtpUnlockEmail } from '../default_mailer.js';
 import { normalizeEmailIdentifier } from '../email_identifier.js';
 import { translate } from '../i18n.js';
@@ -51,6 +54,8 @@ const MFA_PENDING_KEY = 'authkit_mfa_pending';
  * começou e o `amr` do id_token perdia o primeiro fator (ver `mfaCompletion`).
  */
 const MFA_PRIMARY_KEY = 'authkit_mfa_primary';
+/** Written only after trusted custom authentication reaches the MFA gate. */
+const MFA_CUSTOM_PRIMARY_KEY = 'authkit_mfa_custom_primary';
 /** Desafio WebAuthn pendente (autenticação) guardado entre begin/finish no login. */
 const PASSKEY_AUTH_CHALLENGE_KEY = 'authkit_passkey_auth_challenge';
 /**
@@ -64,6 +69,72 @@ function forgetLoginEmail(ctx) {
     ctx.session.forget(SESSION_KEY);
 }
 export default class AuthInteractionController {
+    /** Shared completion for trusted host authentication; primary proof is the host's responsibility. */
+    async completeCustomLogin(ctx, input) {
+        if (!isCustomLoginMethodId(input.method))
+            throw new Error('Invalid custom login method');
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        if (!render)
+            throw new Error('AuthKit login renderer is not configured');
+        const details = await service.interactions.details(ctx);
+        if (details.uid !== ctx.request.param('uid') || details.prompt.name !== 'login') {
+            throw new Error('Invalid login interaction');
+        }
+        const account = await cfg.accountStore.findById(input.accountId);
+        if (!account)
+            throw new Error('Unknown account');
+        const settings = await resolveRuntimeSettingsOrNoop(ctx);
+        const brand = brandFor(cfg.branding, details.params.client_id, details.params.audience);
+        const fail = (key) => render(ctx, 'login', {
+            uid: details.uid,
+            csrfToken: ctx.request.csrfToken,
+            brand,
+            error: translate(cfg.messages, key),
+        });
+        if (await isEmailUnverifiedBlock(cfg, account.id, settings))
+            return fail('errors.email_unverified');
+        const status = await assertLoginAllowed(cfg, account.id, {
+            email: account.email,
+            ip: ctx.request.ip(),
+            clientId: details.params.client_id,
+            settings,
+            passwordless: input.passwordless === true,
+        });
+        if (!status.allowed)
+            return fail(accountStatusErrorKey(status.reason));
+        const maintenance = await resolveEffectiveMaintenanceMode(settings);
+        if (maintenance.enabled &&
+            !(cfg.admin?.roles ?? ['ADMIN']).some((role) => (account.globalRoles ?? []).includes(role))) {
+            return render(ctx, 'maintenance', {
+                uid: details.uid,
+                csrfToken: ctx.request.csrfToken,
+                brand,
+                message: maintenance.message ?? translate(cfg.messages, 'maintenance.default_message'),
+            });
+        }
+        const gate = await this.secondFactorGate(ctx, cfg, account.id, details, input.method, input.factorId, input.remember, input.passwordless === true);
+        if (gate.kind === 'challenge') {
+            ctx.session.put(MFA_CUSTOM_PRIMARY_KEY, {
+                method: input.method,
+                accountId: account.id,
+                uid: details.uid,
+                remember: input.remember === true,
+            });
+            return gate.response;
+        }
+        await notifyLoginSuccess(ctx, cfg, {
+            accountId: account.id,
+            email: account.email,
+            ip: ctx.request.ip(),
+            clientId: details.params.client_id ?? null,
+            metadata: { method: input.method },
+            trustedDevice: gate.kind === 'trusted',
+        });
+        forgetLoginEmail(ctx);
+        return completeCustomLoginSession(ctx, account.id, { amr: [input.method] }, input.remember === true);
+    }
     /**
      * Métodos de login efetivos (com os pins do `cfg.authMethods`) para QUALQUER render do
      * passo login. Sem isto, os re-renders (erro de senha, magic link enviado, lockout…) mandam
@@ -481,13 +552,225 @@ export default class AuthInteractionController {
      * 2º fator: lê o accountId pendente da sessão e aceita um código TOTP (`code`)
      * OU um recovery code (`recoveryCode`). Em caso de sucesso finaliza a interaction.
      */
+    async renderMfaChallenge(ctx, cfg, props) {
+        const flow = getMfaFlow(ctx);
+        const custom = flow ? await customMfaViewProps(ctx) : {};
+        const used = new Set(flow ? [flow.primaryFactorId, ...flow.completed.map((entry) => entry.factorId)] : []);
+        return cfg.render(ctx, 'mfa-challenge', {
+            ...props,
+            ...custom,
+            ...(used.has('totp') ? { totpAvailable: false } : {}),
+            ...(used.has('webauthn') ? { passkeyAvailable: false } : {}),
+        });
+    }
+    async configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless = primary !== 'pwd') {
+        const requiredFactors = cfg.mfa?.requiredFactors ?? 2;
+        const mfaRequired = this.acrRequiresMfa(cfg, details) || cfg.mfa?.requiredFactors !== undefined;
+        const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
+        const enrolledTotp = mfa.totp ?? mfa.enabled;
+        const enrolledPasskey = await this.hasPasskeys(cfg, accountId);
+        ctx.session.put(MFA_PENDING_KEY, accountId);
+        ctx.session.put(MFA_PRIMARY_KEY, primary);
+        const rememberValue = ctx.request.input('remember');
+        initializeMfaFlow(ctx, {
+            uid: details.uid,
+            accountId,
+            primaryMethod: primary,
+            primaryFactorId,
+            passwordless,
+            requiredFactors,
+            remember: rememberRequested ??
+                (rememberValue === true || ['on', '1', 'true'].includes(String(rememberValue))),
+        });
+        const flow = getMfaFlow(ctx);
+        const custom = await resolveCustomMfaMethods(ctx, accountId, details.uid, primary, flow.challengeId);
+        const totpAvailable = Boolean(enrolledTotp && primaryFactorId !== 'totp');
+        const passkeyAvailable = Boolean(enrolledPasskey && primaryFactorId !== 'webauthn');
+        const groups = new Set(custom.map((method) => method.factorId).filter((group) => group !== primaryFactorId));
+        if (totpAvailable)
+            groups.add('totp');
+        if (passkeyAvailable)
+            groups.add('webauthn');
+        const enrolled = Boolean(enrolledTotp || enrolledPasskey || custom.length);
+        if (!enrolled && !mfaRequired) {
+            clearMfaFlow(ctx);
+            ctx.session.forget(MFA_PENDING_KEY);
+            ctx.session.forget(MFA_PRIMARY_KEY);
+            return { kind: 'none' };
+        }
+        const brand = brandFor(cfg.branding, details.params.client_id, details.params.audience);
+        if (groups.size < requiredFactors - 1) {
+            clearMfaFlow(ctx);
+            ctx.session.forget(MFA_PENDING_KEY);
+            ctx.session.forget(MFA_PRIMARY_KEY);
+            return {
+                kind: 'challenge',
+                response: await this.renderMfaChallenge(ctx, cfg, {
+                    uid: details.uid,
+                    csrfToken: ctx.request.csrfToken,
+                    brand,
+                    noEnrollment: true,
+                    totpAvailable: false,
+                    passkeyAvailable: false,
+                    error: translate(cfg.messages, 'mfa_challenge.required_no_enrollment'),
+                }),
+            };
+        }
+        // Custom enrollment does not expose a revocation timestamp; never bypass it with a legacy trusted-device cookie.
+        if (cfg.trustedDevices.enabled &&
+            !mfaRequired &&
+            !custom.length &&
+            requiredFactors === 2 &&
+            (await this.checkTrustedDevice(ctx, accountId, mfa.enabledAt ?? null))) {
+            clearMfaFlow(ctx);
+            ctx.session.forget(MFA_PENDING_KEY);
+            ctx.session.forget(MFA_PRIMARY_KEY);
+            return { kind: 'trusted' };
+        }
+        return {
+            kind: 'challenge',
+            response: await this.renderMfaChallenge(ctx, cfg, {
+                uid: details.uid,
+                csrfToken: ctx.request.csrfToken,
+                brand,
+                totpAvailable,
+                passkeyAvailable,
+                trustedDevicesEnabled: cfg.trustedDevices.enabled && !custom.length,
+                trustedDeviceDays: cfg.trustedDevices.days,
+            }),
+        };
+    }
+    async customMfaBegin(ctx) {
+        await beginCustomMfa(ctx, String(ctx.request.param('method')));
+        const service = await ctx.containerResolver.make('authkit.server');
+        const flow = getMfaFlow(ctx);
+        return this.renderMfaChallenge(ctx, service.config, {
+            uid: flow.uid,
+            csrfToken: ctx.request.csrfToken,
+            totpAvailable: await this.hasTotp(service.config, flow.accountId),
+            passkeyAvailable: await this.hasPasskeys(service.config, flow.accountId),
+            brand: brandFor(service.config.branding, undefined),
+        });
+    }
+    async customMfaVerify(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const details = await service.interactions.details(ctx);
+        const method = String(ctx.request.param('method'));
+        let ok;
+        try {
+            ok = await verifyCustomMfa(ctx, method);
+        }
+        catch (error) {
+            await service.config.audit?.record({
+                type: 'login.failure',
+                accountId: getMfaFlow(ctx)?.accountId ?? null,
+                metadata: { stage: 'mfa', method },
+            });
+            throw error;
+        }
+        const flow = getMfaFlow(ctx);
+        if (!ok) {
+            await service.config.audit?.record({
+                type: 'login.failure',
+                accountId: flow?.accountId ?? null,
+                metadata: { stage: 'mfa', method },
+            });
+            if (!flow)
+                return ctx.response.redirect(`/auth/interaction/${ctx.request.param('uid')}`);
+            return this.renderMfaChallenge(ctx, service.config, {
+                uid: flow.uid,
+                csrfToken: ctx.request.csrfToken,
+                error: translate(service.config.messages, 'errors.invalid_code'),
+                totpAvailable: await this.hasTotp(service.config, flow.accountId),
+                passkeyAvailable: await this.hasPasskeys(service.config, flow.accountId),
+                brand: brandFor(service.config.branding, undefined),
+            });
+        }
+        if (!flow)
+            throw new Error('Missing MFA flow');
+        const descriptors = await resolveCustomMfaMethods(ctx, flow.accountId, flow.uid, flow.primaryMethod, flow.challengeId);
+        const descriptor = descriptors.find((item) => item.id === method);
+        if (!descriptor)
+            throw new Error('MFA method is no longer enabled');
+        return this.finishVerifiedMfa(ctx, service.config, details, method, descriptor.factorId);
+    }
+    async finishVerifiedMfa(ctx, cfg, details, method, factorId) {
+        const flow = getMfaFlow(ctx);
+        if (!flow)
+            throw new Error('Missing MFA flow');
+        const liveDetails = await (await ctx.containerResolver.make('authkit.server')).interactions.details(ctx);
+        if (liveDetails.uid !== flow.uid || liveDetails.prompt.name !== 'login') {
+            this.takeMfaPending(ctx);
+            clearMfaFlow(ctx);
+            return ctx.response.redirect(`/auth/interaction/${ctx.request.param('uid')}`);
+        }
+        const progress = recordVerifiedMfaFactor(ctx, method, factorId);
+        if (!progress.complete)
+            return this.renderMfaChallenge(ctx, cfg, {
+                uid: flow.uid,
+                csrfToken: ctx.request.csrfToken,
+                totpAvailable: await this.hasTotp(cfg, flow.accountId),
+                passkeyAvailable: await this.hasPasskeys(cfg, flow.accountId),
+                brand: brandFor(cfg.branding, undefined),
+            });
+        const settings = await resolveRuntimeSettingsOrNoop(ctx);
+        const account = await cfg.accountStore.findById(flow.accountId);
+        const status = account
+            ? await assertLoginAllowed(cfg, account.id, {
+                email: account.email,
+                ip: ctx.request.ip?.() ?? null,
+                settings,
+                passwordless: flow.passwordless === true,
+            })
+            : { allowed: false, reason: 'disabled' };
+        this.takeMfaPending(ctx);
+        clearMfaFlow(ctx);
+        if (!account ||
+            !status.allowed ||
+            (await isEmailUnverifiedBlock(cfg, flow.accountId, settings))) {
+            return cfg.render(ctx, 'login', {
+                uid: flow.uid,
+                csrfToken: ctx.request.csrfToken,
+                error: translate(cfg.messages, !status.allowed ? accountStatusErrorKey(status.reason) : 'errors.email_unverified'),
+                brand: brandFor(cfg.branding, undefined),
+            });
+        }
+        const maintenance = await resolveEffectiveMaintenanceMode(settings);
+        if (maintenance.enabled &&
+            !(cfg.admin?.roles ?? ['ADMIN']).some((role) => (account.globalRoles ?? []).includes(role))) {
+            return cfg.render(ctx, 'maintenance', {
+                uid: flow.uid,
+                csrfToken: ctx.request.csrfToken,
+                message: maintenance.message ?? translate(cfg.messages, 'maintenance.default_message'),
+                brand: brandFor(cfg.branding, undefined),
+                adminLoginAllowed: true,
+            });
+        }
+        forgetLoginEmail(ctx);
+        await notifyLoginSuccess(ctx, cfg, {
+            accountId: account.id,
+            email: account.email,
+            metadata: { mfa: flow.completed.map((entry) => entry.method) },
+        });
+        const stepUp = this.acrRequiresMfa(cfg, details) ? { acr: cfg.stepUp?.mfaAcr } : {};
+        return completeCustomLoginSession(ctx, account.id, {
+            ...stepUp,
+            amr: [flow.primaryMethod, 'mfa', ...flow.completed.map((entry) => entry.method)],
+        }, flow.remember === true);
+    }
     async mfaVerify(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;
-        const render = cfg.render;
         const details = await service.interactions.details(ctx);
         const brand = brandFor(cfg.branding, details.params.client_id, details.params.audience);
         const accountId = ctx.session.get(MFA_PENDING_KEY);
+        if (cfg.mfa && !getMfaFlow(ctx))
+            return ctx.response.redirect(`/auth/interaction/${ctx.request.param('uid')}`);
+        if (cfg.mfa && (details.uid !== ctx.request.param('uid') || details.prompt.name !== 'login')) {
+            this.takeMfaPending(ctx);
+            clearMfaFlow(ctx);
+            return ctx.response.redirect(`/auth/interaction/${ctx.request.param('uid')}`);
+        }
         const ip = ctx.request.ip?.() ?? null;
         const clientId = details.params.client_id ?? null;
         if (!accountId) {
@@ -501,7 +784,7 @@ export default class AuthInteractionController {
         const otpLockout = createOtpLockout(otpLockoutCfg, ctx.logger);
         // Verifica se o fator OTP está travado ANTES de tentar verificar.
         if (otpLockoutCfg.enabled && (await otpLockout.isLocked(accountId))) {
-            return render(ctx, 'mfa-challenge', {
+            return this.renderMfaChallenge(ctx, cfg, {
                 uid: ctx.request.param('uid'),
                 csrfToken: ctx.request.csrfToken,
                 error: translate(cfg.messages, 'errors.otp_locked'),
@@ -535,7 +818,7 @@ export default class AuthInteractionController {
             if (nowLocked) {
                 // Emite e-mail de desbloqueio (best-effort, fail-safe).
                 await this.sendOtpUnlockEmailIfAble(ctx, cfg, accountId, otpLockoutCfg.unlockTtlHours);
-                return render(ctx, 'mfa-challenge', {
+                return this.renderMfaChallenge(ctx, cfg, {
                     uid: ctx.request.param('uid'),
                     csrfToken: ctx.request.csrfToken,
                     error: translate(cfg.messages, 'errors.otp_locked'),
@@ -547,7 +830,7 @@ export default class AuthInteractionController {
                     otpLocked: true,
                 });
             }
-            return render(ctx, 'mfa-challenge', {
+            return this.renderMfaChallenge(ctx, cfg, {
                 uid: ctx.request.param('uid'),
                 csrfToken: ctx.request.csrfToken,
                 error: translate(cfg.messages, 'errors.invalid_code'),
@@ -560,10 +843,12 @@ export default class AuthInteractionController {
         }
         // Código correto: zera o contador de falhas OTP.
         await otpLockout.clearFailures(accountId);
+        if (cfg.mfa)
+            return this.finishVerifiedMfa(ctx, cfg, details, usedRecovery ? 'recovery' : 'totp', 'totp');
         // Sucesso no 2º fator: opcionalmente confia neste dispositivo (checkbox).
         await this.maybeTrustDevice(ctx, cfg, accountId);
         // Finaliza a interaction para o accountId pendente.
-        const { primary } = this.takeMfaPending(ctx);
+        const { primary, customRemember } = this.takeMfaPending(ctx);
         forgetLoginEmail(ctx);
         await notifyLoginSuccess(ctx, cfg, {
             accountId,
@@ -571,9 +856,13 @@ export default class AuthInteractionController {
             clientId,
             metadata: { mfa: usedRecovery ? 'recovery' : 'totp' },
         });
-        // Um 2º fator foi de fato verificado: amr = [primário, 'mfa', método]. Com
-        // step-up (mfaAcr solicitado nesta requisição), carimba também o acr.
-        await service.interactions.completeLogin(ctx, accountId, this.mfaCompletion(cfg, details, primary, usedRecovery ? 'recovery' : 'totp'));
+        const extra = this.mfaCompletion(cfg, details, primary, usedRecovery ? 'recovery' : 'totp');
+        if (customRemember !== undefined) {
+            await completeCustomLoginSession(ctx, accountId, extra, customRemember);
+        }
+        else {
+            await service.interactions.completeLogin(ctx, accountId, extra);
+        }
     }
     /**
      * true se o authorize request exige MFA via acr_values (contém o mfaAcr da
@@ -619,9 +908,25 @@ export default class AuthInteractionController {
      */
     takeMfaPending(ctx) {
         const raw = ctx.session.get(MFA_PRIMARY_KEY);
+        const custom = ctx.session.get(MFA_CUSTOM_PRIMARY_KEY);
+        const accountId = ctx.session.get(MFA_PENDING_KEY);
         ctx.session.forget(MFA_PENDING_KEY);
         ctx.session.forget(MFA_PRIMARY_KEY);
-        return { primary: raw === 'pwd' || raw === 'email' ? raw : undefined };
+        ctx.session.forget(MFA_CUSTOM_PRIMARY_KEY);
+        if (raw === 'pwd' || raw === 'email')
+            return { primary: raw };
+        const boundCustom = custom !== null &&
+            typeof custom === 'object' &&
+            'method' in custom &&
+            custom.method === raw &&
+            'accountId' in custom &&
+            custom.accountId === accountId &&
+            'uid' in custom &&
+            custom.uid === ctx.request.param('uid');
+        return {
+            ...(boundCustom ? { customRemember: 'remember' in custom && custom.remember === true } : {}),
+            primary: boundCustom && typeof raw === 'string' && isCustomLoginMethodId(raw) ? raw : undefined,
+        };
     }
     /**
      * Gate do segundo fator, compartilhado pelos caminhos de login: senha, link
@@ -645,7 +950,11 @@ export default class AuthInteractionController {
      *  - caso geral → `challenge`, com o accountId em `MFA_PENDING_KEY` e o fator
      *    primário (`primary`) em `MFA_PRIMARY_KEY`.
      */
-    async secondFactorGate(ctx, cfg, accountId, details, primary) {
+    async secondFactorGate(ctx, cfg, accountId, details, primary, primaryFactorId = primary, rememberRequested, passwordless = primary !== 'pwd') {
+        ctx.session.forget(MFA_CUSTOM_PRIMARY_KEY);
+        clearMfaFlow(ctx);
+        if (cfg.mfa)
+            return this.configuredMfaGate(ctx, cfg, accountId, details, primary, primaryFactorId, rememberRequested, passwordless);
         const mfaRequired = this.acrRequiresMfa(cfg, details);
         const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
         // Passkey disponível como alternativa ao TOTP se o store suporta E a conta
@@ -658,13 +967,12 @@ export default class AuthInteractionController {
         const hasFactor = passkeyAvailable || totpAvailable;
         if (!hasFactor && !mfaRequired)
             return { kind: 'none' };
-        const render = cfg.render;
         const brand = brandFor(cfg.branding, details.params.client_id, details.params.audience);
         const uid = ctx.request.param('uid');
         if (!hasFactor) {
             return {
                 kind: 'challenge',
-                response: await render(ctx, 'mfa-challenge', {
+                response: await this.renderMfaChallenge(ctx, cfg, {
                     uid,
                     csrfToken: ctx.request.csrfToken,
                     brand,
@@ -685,7 +993,7 @@ export default class AuthInteractionController {
         ctx.session.put(MFA_PRIMARY_KEY, primary);
         return {
             kind: 'challenge',
-            response: await render(ctx, 'mfa-challenge', {
+            response: await this.renderMfaChallenge(ctx, cfg, {
                 uid,
                 csrfToken: ctx.request.csrfToken,
                 brand,
@@ -1234,8 +1542,15 @@ export default class AuthInteractionController {
     async passkeyVerify(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;
-        const render = cfg.render;
         const details = await service.interactions.details(ctx);
+        if (cfg.mfa && (details.uid !== ctx.request.param('uid') || details.prompt.name !== 'login')) {
+            this.takeMfaPending(ctx);
+            clearMfaFlow(ctx);
+            return ctx.response.redirect(`/auth/interaction/${ctx.request.param('uid')}`);
+        }
+        if (cfg.mfa && ctx.session.get(MFA_PENDING_KEY) && !getMfaFlow(ctx)) {
+            return ctx.response.redirect(`/auth/interaction/${ctx.request.param('uid')}`);
+        }
         const brand = brandFor(cfg.branding, details.params.client_id, details.params.audience);
         let accountId = await this.resolvePasskeyAccountId(ctx, cfg);
         const challenge = ctx.session.get(PASSKEY_AUTH_CHALLENGE_KEY);
@@ -1300,7 +1615,7 @@ export default class AuthInteractionController {
                     clientId,
                     metadata: { stage: 'mfa', method: 'webauthn', reason: 'method_disabled_by_user' },
                 });
-                return render(ctx, 'mfa-challenge', {
+                return this.renderMfaChallenge(ctx, cfg, {
                     uid: ctx.request.param('uid'),
                     csrfToken: ctx.request.csrfToken,
                     error: translate(cfg.messages, 'mfa_challenge.passkey_error'),
@@ -1319,7 +1634,7 @@ export default class AuthInteractionController {
                 clientId,
                 metadata: { stage: 'mfa', method: 'webauthn' },
             });
-            return render(ctx, 'mfa-challenge', {
+            return this.renderMfaChallenge(ctx, cfg, {
                 uid: ctx.request.param('uid'),
                 csrfToken: ctx.request.csrfToken,
                 error: translate(cfg.messages, 'mfa_challenge.passkey_error'),
@@ -1342,7 +1657,7 @@ export default class AuthInteractionController {
                 clientId,
                 metadata: { stage: 'mfa', method: 'webauthn', reason: 'unverified' },
             });
-            return render(ctx, 'mfa-challenge', {
+            return this.renderMfaChallenge(ctx, cfg, {
                 uid: ctx.request.param('uid'),
                 csrfToken: ctx.request.csrfToken,
                 error: translate(cfg.messages, 'errors.email_unverified'),
@@ -1373,7 +1688,7 @@ export default class AuthInteractionController {
             passwordless: true,
         });
         if (!passkeyStatusGate.allowed) {
-            return render(ctx, 'mfa-challenge', {
+            return this.renderMfaChallenge(ctx, cfg, {
                 uid: ctx.request.param('uid'),
                 csrfToken: ctx.request.csrfToken,
                 error: translate(cfg.messages, accountStatusErrorKey(passkeyStatusGate.reason)),
@@ -1384,12 +1699,22 @@ export default class AuthInteractionController {
                 trustedDeviceDays: cfg.trustedDevices.days,
             });
         }
+        if (cfg.mfa && ctx.session.get(MFA_PENDING_KEY)) {
+            if (!getMfaFlow(ctx))
+                return ctx.response.redirect(`/auth/interaction/${ctx.request.param('uid')}`);
+            return this.finishVerifiedMfa(ctx, cfg, details, 'webauthn', 'webauthn');
+        }
+        if (cfg.mfa) {
+            const gate = await this.secondFactorGate(ctx, cfg, accountId, details, 'webauthn');
+            if (gate.kind === 'challenge')
+                return gate.response;
+        }
         // Passkey OK: opcionalmente confia neste dispositivo (checkbox no challenge).
         await this.maybeTrustDevice(ctx, cfg, accountId);
         // Passkey como 2º fator (havia desafio pendente) ou passkey-first (não havia)?
         // Lido ANTES de esquecer: é o que decide o amr abaixo.
         const wasSecondFactor = ctx.session.get(MFA_PENDING_KEY) === accountId;
-        const { primary } = this.takeMfaPending(ctx);
+        const { primary, customRemember } = this.takeMfaPending(ctx);
         forgetLoginEmail(ctx);
         await notifyLoginSuccess(ctx, cfg, {
             accountId,
@@ -1397,12 +1722,15 @@ export default class AuthInteractionController {
             clientId,
             metadata: { mfa: 'webauthn' },
         });
-        // 2º fator: amr = [primário, 'mfa', 'webauthn'] (+ acr no step-up), igual ao
-        // TOTP. Passkey-first: a passkey É o login (amr `['webauthn']`); o step-up
-        // carimba acr/amr quando solicitado.
-        await service.interactions.completeLogin(ctx, accountId, wasSecondFactor
+        const extra = wasSecondFactor
             ? this.mfaCompletion(cfg, details, primary, 'webauthn')
-            : (this.stepUpExtra(cfg, details, 'webauthn') ?? { amr: ['webauthn'] }));
+            : (this.stepUpExtra(cfg, details, 'webauthn') ?? { amr: ['webauthn'] });
+        if (customRemember !== undefined) {
+            await completeCustomLoginSession(ctx, accountId, extra, customRemember);
+        }
+        else {
+            await service.interactions.completeLogin(ctx, accountId, extra);
+        }
     }
     /**
      * GET /auth/interaction/:uid/switch

package/build/src/host/custom_login.d.ts

@@ -0,0 +1,36 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/** A verified identity, obtained from trusted host logic rather than request.accountId. */
+export interface CustomLoginIdentity {
+    accountId: string;
+    /** Host-validated remember-me choice, subject to the runtime session policy. */
+    remember?: boolean;
+}
+/** Host-defined primary authentication. AuthKit owns policies, MFA and session completion. */
+export interface CustomLoginMethod {
+    /** Credential group, used to prevent repeating it as an additional MFA factor. */
+    readonly factorId?: string;
+    /** Set true only for proofs that do not authenticate with the account password. */
+    readonly passwordless?: boolean;
+    /** Optional challenge initiation; response shape, validation and delivery are host-owned. */
+    begin?(ctx: HttpContext): Promise<unknown>;
+    /** Validate/consume the primary proof, bound to this interaction. Null denies login. */
+    authenticate(ctx: HttpContext): Promise<CustomLoginIdentity | null>;
+}
+/** Constructors are resolved through the request container, including @inject dependencies. */
+export type CustomLoginMethodConstructor = new (...args: never[]) => CustomLoginMethod;
+export type CustomLoginMethodBinding = CustomLoginMethodConstructor | CustomLoginMethod;
+export type CustomLoginMethods = Readonly<Record<string, CustomLoginMethodBinding>>;
+export declare function isCustomLoginMethodId(method: string): boolean;
+/** Start a registered method's optional challenge within a valid OIDC login interaction. */
+export declare function beginCustomLogin(ctx: HttpContext, method: string): Promise<unknown>;
+/** Verify using a registered class/instance, then pass through the shared login gates. */
+export declare function authenticateCustomLogin(ctx: HttpContext, method: string): Promise<unknown>;
+/**
+ * Trusted host escape hatch for arbitrary flows. Call ONLY after validating a primary proof.
+ * Never forward an account ID supplied by the browser. Prefer a registered CustomLoginMethod.
+ */
+export declare function completeCustomLogin(ctx: HttpContext, input: CustomLoginIdentity & {
+    method: string;
+    factorId?: string;
+    passwordless?: boolean;
+}): Promise<unknown>;

package/build/src/host/custom_login.js

@@ -0,0 +1,76 @@
+import { Exception } from '@adonisjs/core/exceptions';
+import AuthInteractionController from './controllers/interaction_controller.js';
+export function isCustomLoginMethodId(method) {
+    return (/^[a-z][a-z0-9:_-]{0,63}$/.test(method) &&
+        !['pwd', 'email', 'mfa', 'totp', 'webauthn', 'recovery'].includes(method));
+}
+function failure(message, code, status = 422) {
+    return new Exception(message, { code, status });
+}
+async function resolveMethod(ctx, method) {
+    if (!isCustomLoginMethodId(method))
+        throw failure('Invalid custom login method', 'E_CUSTOM_LOGIN_METHOD');
+    const service = await ctx.containerResolver.make('authkit.server');
+    const details = await service.interactions.details(ctx);
+    if (details.uid !== ctx.request.param('uid') || details.prompt.name !== 'login') {
+        throw failure('Invalid login interaction', 'E_CUSTOM_LOGIN_INTERACTION');
+    }
+    const registry = service.config.customLoginMethods;
+    if (!registry || !Object.hasOwn(registry, method)) {
+        throw failure('Unknown custom login method', 'E_CUSTOM_LOGIN_METHOD');
+    }
+    const binding = registry[method];
+    return typeof binding === 'function' ? ctx.containerResolver.make(binding) : binding;
+}
+/** Start a registered method's optional challenge within a valid OIDC login interaction. */
+export async function beginCustomLogin(ctx, method) {
+    const handler = await resolveMethod(ctx, method);
+    if (!handler.begin)
+        throw failure('This method has no challenge initiation', 'E_CUSTOM_LOGIN_BEGIN');
+    return handler.begin(ctx);
+}
+/** Verify using a registered class/instance, then pass through the shared login gates. */
+export async function authenticateCustomLogin(ctx, method) {
+    const handler = await resolveMethod(ctx, method);
+    let identity;
+    try {
+        identity = await handler.authenticate(ctx);
+    }
+    catch (error) {
+        await recordFailure(ctx, method, 'method_error');
+        throw error;
+    }
+    if (!identity || typeof identity.accountId !== 'string' || !identity.accountId.trim()) {
+        await recordFailure(ctx, method, 'invalid_proof');
+        throw failure('Authentication failed', 'E_CUSTOM_LOGIN_FAILED');
+    }
+    return completeCustomLogin(ctx, {
+        ...identity,
+        method,
+        factorId: handler.factorId,
+        passwordless: handler.passwordless === true,
+    });
+}
+/**
+ * Trusted host escape hatch for arbitrary flows. Call ONLY after validating a primary proof.
+ * Never forward an account ID supplied by the browser. Prefer a registered CustomLoginMethod.
+ */
+export function completeCustomLogin(ctx, input) {
+    return new AuthInteractionController().completeCustomLogin(ctx, input);
+}
+async function recordFailure(ctx, method, reason) {
+    const service = await ctx.containerResolver.make('authkit.server');
+    const details = await service.interactions.details(ctx);
+    try {
+        await service.config.audit?.record({
+            type: 'login.failure',
+            accountId: null,
+            ip: ctx.request.ip(),
+            clientId: details.params.client_id ?? null,
+            metadata: { method, reason },
+        });
+    }
+    catch {
+        ctx.logger.warn('AuthKit custom login failure audit could not be recorded');
+    }
+}

package/build/src/host/custom_login_completion.d.ts

@@ -0,0 +1,4 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { CompleteLoginExtra } from '../provider/interaction_actions.js';
+/** Shared by direct custom completion and its TOTP/passkey continuation. */
+export declare function completeCustomLoginSession(ctx: HttpContext, accountId: string, extra: CompleteLoginExtra, rememberRequested?: boolean): Promise<unknown>;