@adonis-agora/authkit-server 0.75.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
@@ -180,6 +251,7 @@ export default class AuthInteractionController {
                 params: details.params,
                 csrfToken: ctx.request.csrfToken,
                 brand,
+                ...(await consentSubject(service, details, cfg.messages)),
             });
         }
         const email = ctx.session.get(SESSION_KEY);
@@ -480,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) {
@@ -500,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'),
@@ -534,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'),
@@ -546,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'),
@@ -559,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,
@@ -570,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
@@ -618,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
@@ -644,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
@@ -657,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,
@@ -684,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,
@@ -1233,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);
@@ -1299,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'),
@@ -1318,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'),
@@ -1341,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'),
@@ -1372,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)),
@@ -1383,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,
@@ -1396,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
@@ -1564,3 +1893,30 @@ export default class AuthInteractionController {
         }
     }
 }
+/**
+ * Quem pede o acesso e o quê, para a tela de consent: o nome que o client registrou (um cliente
+ * MCP registra o seu, ex.: "Claude Code") e os escopos pedidos, com o rótulo de cada um. O nome
+ * vem de fora (registro dinâmico aberto) — `clientNameHtml` sai escapado para o `{{{ }}}`.
+ */
+async function consentSubject(service, details, messages) {
+    const clientId = String(details.params?.client_id ?? '');
+    const client = clientId ? await service.provider.Client.find(clientId).catch(() => null) : null;
+    const clientName = client?.clientName || clientId;
+    const requested = String(details.params?.scope ?? '')
+        .split(' ')
+        .filter((scope) => scope !== '' && scope !== 'openid');
+    const scopes = requested.map((scope) => {
+        const key = `consent.scope.${scope}`;
+        const label = translate(messages, key);
+        return { id: scope, label: label === key ? scope : label };
+    });
+    return { clientName, clientNameHtml: escapeHtml(clientName), scopes };
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}

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

@@ -1,29 +1,19 @@
-/**
- * Helper de exceções de CSRF para as rotas machine-to-machine do AuthKit.
- *
- * Os endpoints do IdP (token/introspection/PAT) e o back-channel logout são
- * server-to-server (sem browser/token XSRF). Em vez de cada app reescrever a
- * checagem de URL no `config/shield.ts`, use este helper:
- *
- * ```ts
- * // config/shield.ts
- * import { authkitCsrfExceptions } from '@adonis-agora/authkit-server'
- * csrf: {
- *   enabled: true,
- *   exceptRoutes: (ctx) => authkitCsrfExceptions(ctx.request.url(), { mountPath: '/oidc' })
- *     || ctx.request.url().includes('/api'),
- * }
- * ```
- */
 export interface AuthkitCsrfOptions {
     /** mountPath do IdP (mesmo de defineConfig/registerAuthHost). Default: `/oidc`. */
     mountPath?: string;
     /** Inclui a rota de back-channel logout do CLIENT (default: `/auth/backchannel-logout`). */
     backchannelLogoutPath?: string | false;
+    /**
+     * Prefixo de `personalAgents`: isenta os endpoints OAuth que os agentes chamam
+     * (`{prefix}/oauth/*`). Default: o prefixo do config quando `personalAgents`
+     * está ligado; nada quando não está. `false` desliga. A tela de
+     * consentimento (`{prefix}/consent`) continua protegida.
+     */
+    personalAgentsPrefix?: string | false;
 }
 /**
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
  * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
- * rota de back-channel logout do client.
+ * rota de back-channel logout do client e os endpoints OAuth de personal agents.
  */
 export declare function authkitCsrfExceptions(url: string, options?: AuthkitCsrfOptions): boolean;

package/build/src/host/csrf.js

@@ -1,14 +1,40 @@
+/**
+ * Helper de exceções de CSRF para as rotas machine-to-machine do AuthKit.
+ *
+ * Os endpoints do IdP (token/introspection/PAT) e o back-channel logout são
+ * server-to-server (sem browser/token XSRF). Em vez de cada app reescrever a
+ * checagem de URL no `config/shield.ts`, use este helper:
+ *
+ * ```ts
+ * // config/shield.ts
+ * import { authkitCsrfExceptions } from '@adonis-agora/authkit-server'
+ * csrf: {
+ *   enabled: true,
+ *   exceptRoutes: (ctx) => authkitCsrfExceptions(ctx.request.url(), { mountPath: '/oidc' })
+ *     || ctx.request.url().includes('/api'),
+ * }
+ * ```
+ */
+import { normalizePersonalAgentsPrefix } from '../agents/config.js';
+import { getAuthHostConfig } from './auth_host_config.js';
 /**
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
  * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
- * rota de back-channel logout do client.
+ * rota de back-channel logout do client e os endpoints OAuth de personal agents.
  */
 export function authkitCsrfExceptions(url, options = {}) {
     const mountPath = options.mountPath ?? '/oidc';
     const backchannel = options.backchannelLogoutPath === false
         ? null
         : (options.backchannelLogoutPath ?? '/auth/backchannel-logout');
+    const agentsPrefix = options.personalAgentsPrefix === false
+        ? undefined
+        : options.personalAgentsPrefix !== undefined
+            ? normalizePersonalAgentsPrefix(options.personalAgentsPrefix)
+            : getAuthHostConfig()?.personalAgents?.prefix;
+    const agentsOAuth = agentsPrefix ? `${agentsPrefix}/oauth/` : null;
     return (url.includes(mountPath) ||
         url.includes('/authkit/pat') ||
-        (backchannel !== null && url === backchannel));
+        (backchannel !== null && url === backchannel) ||
+        (agentsOAuth !== null && url.startsWith(agentsOAuth)));
 }