@adonis-agora/authkit-server 0.71.0 → 0.72.0

package/build/host/views/mfa-challenge.edge

@@ -17,8 +17,11 @@
       @end
 
       {{-- Step-up sem MFA enrolado: bloqueia o login e instrui a configurar o MFA;
-           não renderiza o campo de código (não há 2º fator a desafiar). --}}
-      @if(!noEnrollment)
+           não renderiza o campo de código (não há 2º fator a desafiar).
+           `totpAvailable === false` = a conta só tem passkey, sem app autenticador
+           confirmado: pedir um código de 6 dígitos seria pedir o impossível. Ausente
+           (stores que não reportam o estado) mantém o campo visível. --}}
+      @if(!noEnrollment && totpAvailable !== false)
         <div class="mt-6">
           <label for="code" class="mb-1 block text-sm font-medium text-gray-700">{{ t('mfa_challenge.code_label') }}</label>
           <input id="code" name="code" inputmode="numeric" autocomplete="one-time-code"
@@ -56,7 +59,9 @@
       <p id="passkey-error" class="mt-3 hidden text-sm text-red-600">{{ t('mfa_challenge.passkey_error') }}</p>
     @end
 
-    @if(!noEnrollment)
+    {{-- Códigos de recuperação só existem junto com o TOTP (são gerados no
+         enrollment); sem ele, a seção não tem o que receber. --}}
+    @if(!noEnrollment && totpAvailable !== false)
       <details class="mt-6 text-sm text-gray-600">
         <summary class="cursor-pointer hover:underline">{{ t('mfa_challenge.recovery_summary') }}</summary>
         <form method="POST" action="/auth/interaction/{{ uid }}/mfa" class="mt-3">

package/build/src/accounts/account_store.d.ts

@@ -250,10 +250,18 @@ export interface MfaCapability {
      * mecanismo de "trusted devices": um cookie de confiança emitido ANTES desse
      * instante é considerado inválido (re-enrolar MFA revoga a confiança). Pode ser
      * `null`/ausente quando o MFA não está ativo ou o store não rastreia o instante.
+     *
+     * `totp` diz se há um app autenticador CONFIRMADO (segredo + códigos de
+     * recuperação). É diferente de `enabled`: registrar uma passkey também liga o
+     * MFA, e remover a última passkey não o desliga — então `enabled` sozinho não
+     * responde "existe um segundo fator que esta pessoa consegue apresentar?".
+     * Quem decide mostrar (ou não) o desafio precisa de `totp`; stores antigos que
+     * o omitem continuam funcionando, só não distinguem os dois casos.
      */
     getMfaState(accountId: string): Promise<{
         enabled: boolean;
         enabledAt?: number | null;
+        totp?: boolean;
     }>;
     /**
      * Inicia o enrollment TOTP: gera um segredo PENDENTE (mfaEnabledAt continua

package/build/src/accounts/lucid_store/mfa.js

@@ -25,7 +25,15 @@ export function buildMfa(ctx) {
             const state = await repo.read(accountId);
             // `enabledAt` (epoch ms) habilita o trusted-device check: um cookie de
             // confiança emitido ANTES deste instante é inválido (re-enrolar revoga).
-            return { enabled: !!state?.mfaEnabledAt, enabledAt: state?.mfaEnabledAt ?? null };
+            // `totp` é o fator REALMENTE utilizável: segredo confirmado + códigos de
+            // recuperação gravados. `enabled` também liga ao registrar passkey (ver
+            // `webauthn.ts`) e não desliga ao remover a última — sozinho, não diz se
+            // sobrou algum fator para desafiar.
+            return {
+                enabled: !!state?.mfaEnabledAt,
+                enabledAt: state?.mfaEnabledAt ?? null,
+                totp: !!(state?.mfaEnabledAt && state?.totpSecret && state?.recoveryCodes),
+            };
         },
         async startTotpEnrollment(accountId) {
             // O email/QR vem do model principal; só o ESTADO de MFA vive em auth_mfa.

package/build/src/host/controllers/interaction_controller.d.ts

@@ -41,6 +41,34 @@ export default class AuthInteractionController {
      * Retorna `undefined` quando não há step-up — completeLogin usa o default.
      */
     private stepUpExtra;
+    /**
+     * Gate do segundo fator, compartilhado pelos caminhos de login: senha, link
+     * mágico, código por e-mail e troca forçada de senha. Antes disto só o login
+     * por senha passava pelo MFA — link e código completavam a interaction direto,
+     * então uma conta com TOTP ou passkey entrava apresentando só o e-mail e o
+     * segundo fator virava enfeite.
+     *
+     * A pergunta que o gate responde é "existe um fator que esta pessoa consegue
+     * apresentar AGORA?", e não `mfa.enabled` — que liga ao registrar uma passkey
+     * e não desliga ao remover a última. Fator utilizável = TOTP confirmado
+     * (`mfa.totp`) OU ao menos uma passkey registrada. Pela regra antiga, quem
+     * registrava uma passkey e depois a removia ficava preso num desafio TOTP que
+     * não tinha como responder.
+     *
+     *  - sem fator e sem step-up → `none`, o login segue;
+     *  - step-up (acr) exigindo MFA numa conta sem fator → `challenge` com a
+     *    instrução de enrolar (não há o que desafiar);
+     *  - fator presente, trusted-device válido e sem step-up → `trusted`; quem
+     *    chamou decide como finalizar, porque o amr muda conforme o caminho;
+     *  - caso geral → `challenge`, com o accountId em `MFA_PENDING_KEY`.
+     */
+    private secondFactorGate;
+    /**
+     * true se a conta tem um app autenticador CONFIRMADO. Stores que não reportam
+     * `totp` (a chave é opcional em {@link MfaCapability}) caem no `enabled`, o
+     * comportamento antigo.
+     */
+    private hasTotp;
     /** true se o store suporta passkeys E a conta tem ao menos uma registrada. */
     private hasPasskeys;
     /**

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

@@ -405,55 +405,24 @@ export default class AuthInteractionController {
             }
             // Admin: prossegue normalmente (sem bloqueio).
         }
-        // Step-up auth (acr_values): o client pode EXIGIR MFA nesta requisição
-        // solicitando o `mfaAcr` em acr_values, mesmo que a conta tenha MFA opcional.
-        const mfaRequired = this.acrRequiresMfa(cfg, details);
-        // MFA gate: força o 2º fator se a conta tem TOTP ativo OU se o client exige MFA
-        // via acr. Não finaliza a interaction agora — guarda o accountId pendente.
-        const mfa = (await cfg.accountStore.getMfaState?.(acc.id)) ?? { enabled: false };
-        if (mfa.enabled || mfaRequired) {
-            if (mfaRequired && !mfa.enabled) {
-                // Client exige MFA mas a conta não tem MFA enrolado: bloqueia este login
-                // com a instrução de configurar MFA no console (não há 2º fator a desafiar).
-                return render(ctx, 'mfa-challenge', {
-                    uid: ctx.request.param('uid'),
-                    csrfToken: ctx.request.csrfToken,
-                    brand,
-                    passkeyAvailable: false,
-                    error: translate(cfg.messages, 'mfa_challenge.required_no_enrollment'),
-                    noEnrollment: true,
-                });
-            }
-            // Trusted device: se o mecanismo está ligado, a conta JÁ tem MFA enrolado e
-            // o request NÃO é um step-up (que sempre força o MFA), um cookie de confiança
-            // válido para ESTA conta pula o 2º fator. amr fica `['pwd']` (sem acr de MFA).
-            if (cfg.trustedDevices.enabled && mfa.enabled && !mfaRequired) {
-                const trusted = await this.checkTrustedDevice(ctx, acc.id, mfa.enabledAt ?? null);
-                if (trusted) {
-                    await service.interactions.completeLogin(ctx, acc.id, { amr: ['pwd'] });
-                    await notifyLoginSuccess(ctx, cfg, {
-                        accountId: acc.id,
-                        email,
-                        ip,
-                        clientId,
-                        trustedDevice: true,
-                    });
-                    forgetLoginEmail(ctx);
-                    return;
-                }
-            }
-            ctx.session.put(MFA_PENDING_KEY, acc.id);
-            // Passkey disponível como alternativa ao TOTP se o store suporta E a conta
-            // tem ao menos uma credencial registrada.
-            const passkeyAvailable = await this.hasPasskeys(cfg, acc.id);
-            return render(ctx, 'mfa-challenge', {
-                uid: ctx.request.param('uid'),
-                csrfToken: ctx.request.csrfToken,
-                brand,
-                passkeyAvailable,
-                trustedDevicesEnabled: cfg.trustedDevices.enabled,
-                trustedDeviceDays: cfg.trustedDevices.days,
+        // Gate do 2º fator — a MESMA regra dos três caminhos de login (ver
+        // `secondFactorGate`). Quando desafia, não finaliza a interaction: guarda o
+        // accountId pendente e devolve a tela.
+        const gate = await this.secondFactorGate(ctx, cfg, acc.id, details);
+        if (gate.kind === 'challenge')
+            return gate.response;
+        if (gate.kind === 'trusted') {
+            // Dispositivo confiável: pula o 2º fator. amr fica `['pwd']` (sem acr de MFA).
+            await service.interactions.completeLogin(ctx, acc.id, { amr: ['pwd'] });
+            await notifyLoginSuccess(ctx, cfg, {
+                accountId: acc.id,
+                email,
+                ip,
+                clientId,
+                trustedDevice: true,
             });
+            forgetLoginEmail(ctx);
+            return;
         }
         // Sem MFA: finaliza a interaction (escreve o 303 de volta para o client).
         // Resolve session_policy para remember-me e single-session.
@@ -531,6 +500,7 @@ export default class AuthInteractionController {
                 error: translate(cfg.messages, 'errors.otp_locked'),
                 brand,
                 passkeyAvailable: await this.hasPasskeys(cfg, accountId),
+                totpAvailable: await this.hasTotp(cfg, accountId),
                 trustedDevicesEnabled: cfg.trustedDevices.enabled,
                 trustedDeviceDays: cfg.trustedDevices.days,
                 otpLocked: true,
@@ -564,6 +534,7 @@ export default class AuthInteractionController {
                     error: translate(cfg.messages, 'errors.otp_locked'),
                     brand,
                     passkeyAvailable: await this.hasPasskeys(cfg, accountId),
+                    totpAvailable: await this.hasTotp(cfg, accountId),
                     trustedDevicesEnabled: cfg.trustedDevices.enabled,
                     trustedDeviceDays: cfg.trustedDevices.days,
                     otpLocked: true,
@@ -575,6 +546,7 @@ export default class AuthInteractionController {
                 error: translate(cfg.messages, 'errors.invalid_code'),
                 brand,
                 passkeyAvailable: await this.hasPasskeys(cfg, accountId),
+                totpAvailable: await this.hasTotp(cfg, accountId),
                 trustedDevicesEnabled: cfg.trustedDevices.enabled,
                 trustedDeviceDays: cfg.trustedDevices.days,
             });
@@ -619,6 +591,84 @@ export default class AuthInteractionController {
             return undefined;
         return { acr: cfg.stepUp.mfaAcr, amr: ['mfa', method] };
     }
+    /**
+     * Gate do segundo fator, compartilhado pelos caminhos de login: senha, link
+     * mágico, código por e-mail e troca forçada de senha. Antes disto só o login
+     * por senha passava pelo MFA — link e código completavam a interaction direto,
+     * então uma conta com TOTP ou passkey entrava apresentando só o e-mail e o
+     * segundo fator virava enfeite.
+     *
+     * A pergunta que o gate responde é "existe um fator que esta pessoa consegue
+     * apresentar AGORA?", e não `mfa.enabled` — que liga ao registrar uma passkey
+     * e não desliga ao remover a última. Fator utilizável = TOTP confirmado
+     * (`mfa.totp`) OU ao menos uma passkey registrada. Pela regra antiga, quem
+     * registrava uma passkey e depois a removia ficava preso num desafio TOTP que
+     * não tinha como responder.
+     *
+     *  - sem fator e sem step-up → `none`, o login segue;
+     *  - step-up (acr) exigindo MFA numa conta sem fator → `challenge` com a
+     *    instrução de enrolar (não há o que desafiar);
+     *  - fator presente, trusted-device válido e sem step-up → `trusted`; quem
+     *    chamou decide como finalizar, porque o amr muda conforme o caminho;
+     *  - caso geral → `challenge`, com o accountId em `MFA_PENDING_KEY`.
+     */
+    async secondFactorGate(ctx, cfg, accountId, details) {
+        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
+        // tem ao menos uma credencial registrada.
+        const passkeyAvailable = await this.hasPasskeys(cfg, accountId);
+        // Store que não reporta `totp` (a chave é opcional) cai no `enabled` — o
+        // comportamento antigo. Nunca o contrário: assumir "sem TOTP" por omissão
+        // deixaria de desafiar quem tem o fator.
+        const totpAvailable = mfa.totp ?? !!mfa.enabled;
+        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', {
+                    uid,
+                    csrfToken: ctx.request.csrfToken,
+                    brand,
+                    passkeyAvailable: false,
+                    error: translate(cfg.messages, 'mfa_challenge.required_no_enrollment'),
+                    noEnrollment: true,
+                }),
+            };
+        }
+        if (cfg.trustedDevices.enabled && !mfaRequired) {
+            const trusted = await this.checkTrustedDevice(ctx, accountId, mfa.enabledAt ?? null);
+            if (trusted)
+                return { kind: 'trusted' };
+        }
+        ctx.session.put(MFA_PENDING_KEY, accountId);
+        return {
+            kind: 'challenge',
+            response: await render(ctx, 'mfa-challenge', {
+                uid,
+                csrfToken: ctx.request.csrfToken,
+                brand,
+                passkeyAvailable,
+                totpAvailable,
+                trustedDevicesEnabled: cfg.trustedDevices.enabled,
+                trustedDeviceDays: cfg.trustedDevices.days,
+            }),
+        };
+    }
+    /**
+     * true se a conta tem um app autenticador CONFIRMADO. Stores que não reportam
+     * `totp` (a chave é opcional em {@link MfaCapability}) caem no `enabled`, o
+     * comportamento antigo.
+     */
+    async hasTotp(cfg, accountId) {
+        const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
+        return mfa.totp ?? !!mfa.enabled;
+    }
     /** true se o store suporta passkeys E a conta tem ao menos uma registrada. */
     async hasPasskeys(cfg, accountId) {
         if (!supportsPasskeys(cfg.accountStore))
@@ -920,12 +970,21 @@ export default class AuthInteractionController {
                 error: translate(cfg.messages, accountStatusErrorKey(magicLinkStatusGate.reason)),
             });
         }
+        // Conta com segundo fator não termina o login só com o e-mail.
+        const magicGate = await this.secondFactorGate(ctx, cfg, acc.id, await service.interactions.details(ctx));
+        if (magicGate.kind === 'challenge')
+            return magicGate.response;
         await notifyLoginSuccess(ctx, cfg, {
             accountId: acc.id,
             email: acc.email,
             ip,
             clientId: clientId ?? null,
             metadata: { method: 'magic_link' },
+            // `trusted` = o gate já validou o cookie de confiança nesta request; dizer
+            // isso aqui poupa `notifyLoginSuccess` de reler o mesmo cookie para decidir
+            // se é dispositivo novo. O amr continua `['email']`: o fator primário foi o
+            // e-mail, a confiança só dispensou o segundo.
+            trustedDevice: magicGate.kind === 'trusted',
         });
         forgetLoginEmail(ctx);
         await service.interactions.completeLogin(ctx, acc.id, { amr: ['email'] });
@@ -1033,12 +1092,17 @@ export default class AuthInteractionController {
                 ip,
                 clientId,
             });
+            // Conta com segundo fator não termina o login só com o código do e-mail.
+            const otpGate = await this.secondFactorGate(ctx, cfg, result.account.id, await service.interactions.details(ctx));
+            if (otpGate.kind === 'challenge')
+                return otpGate.response;
             await notifyLoginSuccess(ctx, cfg, {
                 accountId: result.account.id,
                 email: result.account.email,
                 ip,
                 clientId: clientId ?? null,
                 metadata: { method: 'otp' },
+                trustedDevice: otpGate.kind === 'trusted',
             });
             forgetLoginEmail(ctx);
             return service.interactions.completeLogin(ctx, result.account.id, { amr: ['email'] });
@@ -1225,6 +1289,7 @@ export default class AuthInteractionController {
                 error: translate(cfg.messages, 'mfa_challenge.passkey_error'),
                 brand,
                 passkeyAvailable: await this.hasPasskeys(cfg, accountId),
+                totpAvailable: await this.hasTotp(cfg, accountId),
                 trustedDevicesEnabled: cfg.trustedDevices.enabled,
                 trustedDeviceDays: cfg.trustedDevices.days,
             });
@@ -1247,6 +1312,7 @@ export default class AuthInteractionController {
                 error: translate(cfg.messages, 'errors.email_unverified'),
                 brand,
                 passkeyAvailable: await this.hasPasskeys(cfg, accountId),
+                totpAvailable: await this.hasTotp(cfg, accountId),
                 trustedDevicesEnabled: cfg.trustedDevices.enabled,
                 trustedDeviceDays: cfg.trustedDevices.days,
             });
@@ -1277,6 +1343,7 @@ export default class AuthInteractionController {
                 error: translate(cfg.messages, accountStatusErrorKey(passkeyStatusGate.reason)),
                 brand,
                 passkeyAvailable: await this.hasPasskeys(cfg, accountId),
+                totpAvailable: await this.hasTotp(cfg, accountId),
                 trustedDevicesEnabled: cfg.trustedDevices.enabled,
                 trustedDeviceDays: cfg.trustedDevices.days,
             });
@@ -1373,20 +1440,10 @@ export default class AuthInteractionController {
         });
         // Senha trocada: limpa o step e finaliza o login.
         ctx.session.forget(PASSWORD_EXPIRED_KEY);
-        // Verifica se precisa de MFA mesmo após a troca.
-        const mfa = (await cfg.accountStore.getMfaState?.(accountId)) ?? { enabled: false };
-        if (mfa.enabled) {
-            ctx.session.put(MFA_PENDING_KEY, accountId);
-            const passkeyAvailable = await this.hasPasskeys(cfg, accountId);
-            return render(ctx, 'mfa-challenge', {
-                uid: ctx.request.param('uid'),
-                csrfToken: ctx.request.csrfToken,
-                brand,
-                passkeyAvailable,
-                trustedDevicesEnabled: cfg.trustedDevices.enabled,
-                trustedDeviceDays: cfg.trustedDevices.days,
-            });
-        }
+        // Verifica se precisa de MFA mesmo após a troca — mesma regra do resto.
+        const expiredGate = await this.secondFactorGate(ctx, cfg, accountId, details);
+        if (expiredGate.kind === 'challenge')
+            return expiredGate.response;
         await service.interactions.completeLogin(ctx, accountId);
         const account = await cfg.accountStore.findById(accountId);
         await notifyLoginSuccess(ctx, cfg, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "AdonisJS OIDC/OAuth2 provider (Identity Provider) toolkit: ejectable auth server with sessions, rate-limiting, MFA/TOTP, audit log, federated logout and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",