@adonis-agora/authkit-server 0.69.0 → 0.70.0

package/build/commands/import_users.js

@@ -53,7 +53,12 @@ export default class AuthkitImportUsers extends BaseCommand {
             return;
         }
         const { records, parseErrors } = parseImportFile(content);
-        const report = await importUsers(store, records, { dryRun: this.dryRun });
+        const report = await importUsers(store, records, {
+            dryRun: this.dryRun,
+            // Ponte legada do config (default ligada) — a checagem de duplicado
+            // enxerga as contas gravadas com o endereço mutilado pelo cadastro antigo.
+            legacyFallback: authkitConfig?.login?.legacyEmailFallback ?? true,
+        });
         // Erros de parsing entram no relatório agregado.
         report.errors.unshift(...parseErrors);
         if (this.dryRun) {

package/build/index.d.ts

@@ -64,6 +64,8 @@ export { deriveLockedSettingKeys, isSettingLocked, lockedSettingKeys, POLICY_ROU
 export { consoleLoginUrl, getAccountId, hasAccountSession, realAccountId, } from './src/host/console_session.js';
 export type { AuthkitCsrfOptions } from './src/host/csrf.js';
 export { authkitCsrfExceptions } from './src/host/csrf.js';
+export type { EmailIdentifierLookup, ResolvedEmailIdentifier, } from './src/host/email_identifier.js';
+export { legacyNormalizeEmailIdentifier, normalizeEmailIdentifier, resolveEmailIdentifier, } from './src/host/email_identifier.js';
 export type { ResolveGeo } from './src/host/geo.js';
 export { GEO_RESOLVE_TIMEOUT_MS, resolveGeoSafe } from './src/host/geo.js';
 export type { AuthMessages, I18nConfig } from './src/host/i18n.js';
@@ -94,7 +96,7 @@ export { sudoMethods } from './src/host/sudo/index.js';
 export { completeSudo, fail as failSudo, LAST_METHOD_SESSION_KEY, sudoContextFrom, } from './src/host/sudo/runtime.js';
 export type { SudoContext, SudoMethod, SudoMethodDescriptor, SudoRouteHelpers, } from './src/host/sudo/types.js';
 export type { ResolvedSudoModeSetting, SudoModeSetting, } from './src/host/sudo_mode.js';
-export { isSudoActive, markSudo, requireSudo, resolveEffectiveSudoMode, SUDO_ACCOUNT_SESSION_KEY, SUDO_MODE_DEFAULTS, SUDO_SESSION_KEY, } from './src/host/sudo_mode.js';
+export { isSudoActive, isSudoSatisfied, markSudo, requireSudo, resolveEffectiveSudoMode, SUDO_ACCOUNT_SESSION_KEY, SUDO_MODE_DEFAULTS, SUDO_SESSION_KEY, } from './src/host/sudo_mode.js';
 export { barChartSvg } from './src/host/svg_chart.js';
 export type { ResolvedTrustedDevicesConfig, TrustedDevicePayload, TrustedDevicesConfigInput, } from './src/host/trusted_device.js';
 export { buildTrustedDevicePayload, isTrustedDeviceValid, resolveTrustedDevices, TRUSTED_DEVICE_COOKIE, } from './src/host/trusted_device.js';

package/build/index.js

@@ -49,6 +49,7 @@ export { brandFor, isFirstParty, isFirstPartyClient } from './src/host/branding.
 export { deriveLockedSettingKeys, isSettingLocked, lockedSettingKeys, POLICY_ROUTE_OPTIONS, resetLockedSettingKeys, SettingLockedError, setLockedSettingKeys, } from './src/host/config_locks.js';
 export { consoleLoginUrl, getAccountId, hasAccountSession, realAccountId, } from './src/host/console_session.js';
 export { authkitCsrfExceptions } from './src/host/csrf.js';
+export { legacyNormalizeEmailIdentifier, normalizeEmailIdentifier, resolveEmailIdentifier, } from './src/host/email_identifier.js';
 export { GEO_RESOLVE_TIMEOUT_MS, resolveGeoSafe } from './src/host/geo.js';
 export { BUILTIN_MESSAGES, DEFAULT_LOCALE, DEFAULT_MESSAGES, PT_BR_MESSAGES, resolveMessages, translate, } from './src/host/i18n.js';
 export { ensureConsoleSession } from './src/host/idp_session_bridge.js';
@@ -90,7 +91,10 @@ export { sudoMethods } from './src/host/sudo/index.js';
 // `returnTo` montado na mão é um open redirect esperando acontecer.
 export { completeSudo, fail as failSudo, LAST_METHOD_SESSION_KEY, sudoContextFrom, } from './src/host/sudo/runtime.js';
 // Sudo mode — helpers for host controllers that require step-up authentication.
-export { isSudoActive, markSudo, requireSudo, resolveEffectiveSudoMode, SUDO_ACCOUNT_SESSION_KEY, SUDO_MODE_DEFAULTS, SUDO_SESSION_KEY, } from './src/host/sudo_mode.js';
+export { isSudoActive, 
+// A DECISÃO de sudo sem efeito na resposta — o que o host chama quando quer
+// recusar em JSON em vez de redirecionar para `/account/confirm`.
+isSudoSatisfied, markSudo, requireSudo, resolveEffectiveSudoMode, SUDO_ACCOUNT_SESSION_KEY, SUDO_MODE_DEFAULTS, SUDO_SESSION_KEY, } from './src/host/sudo_mode.js';
 export { barChartSvg } from './src/host/svg_chart.js';
 export { buildTrustedDevicePayload, isTrustedDeviceValid, resolveTrustedDevices, TRUSTED_DEVICE_COOKIE, } from './src/host/trusted_device.js';
 export { parseUserAgent } from './src/host/user_agent.js';

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

@@ -278,6 +278,26 @@ export interface MfaCapability {
     consumeRecoveryCode(accountId: string, code: string): Promise<boolean>;
     /** Desliga o MFA: limpa segredo + mfaEnabledAt + recovery codes. */
     disableMfa(accountId: string): Promise<void>;
+    /**
+     * Quantos recovery codes AINDA não foram consumidos. OPCIONAL: existe para a
+     * tela de segundo fator dizer "restam N" sem revelar os códigos (só o hash
+     * fica guardado). `null` quando o MFA não está ativo.
+     *
+     * Opcional de propósito: um store de terceiro escrito contra a versão
+     * anterior de {@link MfaCapability} continua satisfazendo o tipo, e os
+     * callers fazem capability-probe (`typeof store.countRecoveryCodes ===
+     * 'function'`) antes de chamar.
+     */
+    countRecoveryCodes?(accountId: string): Promise<number | null>;
+    /**
+     * Regenera os recovery codes de uma conta com MFA ATIVO: descarta os antigos
+     * (inclusive os não usados) e devolve os novos em claro — uma única vez, como
+     * no {@link MfaCapability.confirmTotpEnrollment}. `null` quando o MFA não
+     * está ativo (não há o que regenerar).
+     *
+     * Opcional pelo mesmo motivo de {@link MfaCapability.countRecoveryCodes}.
+     */
+    regenerateRecoveryCodes?(accountId: string): Promise<string[] | null>;
 }
 /**
  * MFA / WebAuthn (passkeys) — 2º fator alternativo ao TOTP. Como o TOTP, é uma
@@ -654,6 +674,26 @@ export declare function supportsCountByGlobalRole(store: AccountStore): store is
 };
 /** Type guard: o store implementa a capacidade de passkeys / WebAuthn. */
 export declare function supportsPasskeys(store: AccountStore): store is AccountStore & WebauthnCapability;
+/**
+ * Type guard: o store sabe REGENERAR recovery codes
+ * ({@link MfaCapability.regenerateRecoveryCodes}).
+ *
+ * Guard PRÓPRIO, separado de {@link supportsMfa}, porque o método é opcional
+ * dentro da capacidade: um store escrito antes desta versão implementa MFA
+ * inteiro e não implementa este método. Quem oferece o botão "gerar novos
+ * códigos" pergunta por aqui.
+ */
+export declare function supportsRecoveryCodeRegeneration(store: AccountStore): store is AccountStore & MfaCapability & {
+    regenerateRecoveryCodes(accountId: string): Promise<string[] | null>;
+};
+/**
+ * Type guard: o store sabe CONTAR recovery codes restantes
+ * ({@link MfaCapability.countRecoveryCodes}). Mesmo motivo do
+ * {@link supportsRecoveryCodeRegeneration} para ser um guard separado.
+ */
+export declare function supportsRecoveryCodeCount(store: AccountStore): store is AccountStore & MfaCapability & {
+    countRecoveryCodes(accountId: string): Promise<number | null>;
+};
 /** Type guard: o store implementa account linking por identidade de provider. */
 export declare function supportsProviderIdentity(store: AccountStore): store is AccountStore & ProviderIdentityCapability;
 /** Type guard: o store implementa o self-service de segurança (senha/e-mail). */

package/build/src/accounts/account_store.js

@@ -18,6 +18,26 @@ export function supportsCountByGlobalRole(store) {
 export function supportsPasskeys(store) {
     return typeof store.listPasskeys === 'function';
 }
+/**
+ * Type guard: o store sabe REGENERAR recovery codes
+ * ({@link MfaCapability.regenerateRecoveryCodes}).
+ *
+ * Guard PRÓPRIO, separado de {@link supportsMfa}, porque o método é opcional
+ * dentro da capacidade: um store escrito antes desta versão implementa MFA
+ * inteiro e não implementa este método. Quem oferece o botão "gerar novos
+ * códigos" pergunta por aqui.
+ */
+export function supportsRecoveryCodeRegeneration(store) {
+    return typeof store.regenerateRecoveryCodes === 'function';
+}
+/**
+ * Type guard: o store sabe CONTAR recovery codes restantes
+ * ({@link MfaCapability.countRecoveryCodes}). Mesmo motivo do
+ * {@link supportsRecoveryCodeRegeneration} para ser um guard separado.
+ */
+export function supportsRecoveryCodeCount(store) {
+    return typeof store.countRecoveryCodes === 'function';
+}
 /** Type guard: o store implementa account linking por identidade de provider. */
 export function supportsProviderIdentity(store) {
     return typeof store.findByProviderIdentity === 'function';

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

@@ -100,6 +100,28 @@ export function buildMfa(ctx) {
             await repo.upsert(accountId, { recoveryCodes: remaining });
             return true;
         },
+        async countRecoveryCodes(accountId) {
+            const state = await repo.read(accountId);
+            // Sem MFA ativo não há conjunto de códigos a contar — `null` diz "não se
+            // aplica", diferente de `0` ("acabaram, gere novos").
+            if (!state || !state.mfaEnabledAt)
+                return null;
+            return Array.isArray(state.recoveryCodes) ? state.recoveryCodes.length : 0;
+        },
+        async regenerateRecoveryCodes(accountId) {
+            const state = await repo.read(accountId);
+            // Só regenera sobre MFA JÁ ATIVO. Num enrollment pendente os códigos saem
+            // do `confirmTotpEnrollment`; deixar regenerar antes disso criaria um
+            // conjunto válido de credenciais de recuperação para um fator que o
+            // usuário ainda não provou possuir.
+            if (!state || !state.mfaEnabledAt)
+                return null;
+            const codes = Array.from({ length: recoveryCodeCount }, () => generateRecoveryCode());
+            // Substitui o conjunto inteiro: os antigos (inclusive os não usados)
+            // param de valer no mesmo instante — é esse o ponto de "regenerar".
+            await repo.upsert(accountId, { recoveryCodes: codes.map(sha256) });
+            return codes;
+        },
         async disableMfa(accountId) {
             // Limpa todo o estado de MFA. Inclui o anti-replay: um futuro re-enroll começa do zero.
             await repo.clear(accountId);

package/build/src/audit/audit_sink.d.ts

@@ -8,7 +8,7 @@
  * varre os `audit.record({ type: ... })` do `src/` e falha quando um evento
  * emitido não está aqui.
  */
-export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'impersonation.stopped', 'mfa.enabled', 'mfa.disabled', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'roles_catalog.updated'];
+export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'impersonation.stopped', 'mfa.enabled', 'mfa.disabled', 'mfa.recovery_codes_regenerated', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'roles_catalog.updated'];
 /** Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP. */
 export type AuditEventType = (typeof AUDIT_EVENT_TYPES)[number];
 /**

package/build/src/audit/audit_sink.js

@@ -29,6 +29,10 @@ export const AUDIT_EVENT_TYPES = [
     'impersonation.stopped',
     'mfa.enabled',
     'mfa.disabled',
+    // Os recovery codes foram TROCADOS: os antigos (inclusive os não usados)
+    // deixaram de valer no mesmo instante. Evento próprio, e não `mfa.enabled`,
+    // porque o fator não mudou — mudou o conjunto de credenciais de contorno.
+    'mfa.recovery_codes_regenerated',
     'account.locked',
     'passkey.registered',
     'passkey.removed',

package/build/src/commands/import_users.d.ts

@@ -42,10 +42,17 @@ export declare function parseImportFile(content: string): {
  *
  * Lógica PURA quanto a I/O de arquivo (recebe os registros já parseados) — fácil
  * de testar. Lança se o store não suporta import nem create.
+ *
+ * `legacyFallback` (default ligado, como no resto da lib) faz a checagem de
+ * duplicado enxergar também a conta que o cadastro antigo gravou com o endereço
+ * mutilado — importar a grafia REAL do dono dela pula como duplicado em vez de
+ * criar uma SEGUNDA conta. O comando não tem acesso ao config, então o flag
+ * chega por aqui.
  */
 export declare function importUsers(store: AccountStore, records: {
     line: number;
     record: ImportUserRecord;
 }[], options?: {
     dryRun?: boolean;
+    legacyFallback?: boolean;
 }): Promise<ImportReport>;

package/build/src/commands/import_users.js

@@ -1,4 +1,5 @@
 import { supportsAccountImport } from '../accounts/account_store.js';
+import { normalizeEmailIdentifier, resolveEmailIdentifier } from '../host/email_identifier.js';
 /**
  * Faz o parse do conteúdo do arquivo: aceita NDJSON (uma linha JSON por usuário)
  * OU um array JSON. Retorna os registros + os erros de parsing por linha. PURO
@@ -47,18 +48,29 @@ export function parseImportFile(content) {
  *
  * Lógica PURA quanto a I/O de arquivo (recebe os registros já parseados) — fácil
  * de testar. Lança se o store não suporta import nem create.
+ *
+ * `legacyFallback` (default ligado, como no resto da lib) faz a checagem de
+ * duplicado enxergar também a conta que o cadastro antigo gravou com o endereço
+ * mutilado — importar a grafia REAL do dono dela pula como duplicado em vez de
+ * criar uma SEGUNDA conta. O comando não tem acesso ao config, então o flag
+ * chega por aqui.
  */
 export async function importUsers(store, records, options = {}) {
     const report = { created: 0, skippedDuplicate: 0, errors: [] };
     const canImport = supportsAccountImport(store);
     for (const { line, record } of records) {
-        const email = record.email?.trim();
+        // MESMA normalização do cadastro/login (`trim` + `toLowerCase`) — sem ela o
+        // import gravava `Davi@Acme.com` e o login (normalizado) não achava a conta.
+        const email = normalizeEmailIdentifier(record.email);
         if (!email) {
             report.errors.push({ line, reason: 'missing email' });
             continue;
         }
-        // Duplicado: e-mail já existe → pula.
-        const existing = await store.findByEmail(email);
+        // Duplicado: e-mail já existe → pula. Enxerga também a conta gravada com o
+        // endereço mutilado (ponte legada) — empate segue criando, como no cadastro.
+        const existing = (await resolveEmailIdentifier(store, record.email, {
+            legacyFallback: options.legacyFallback,
+        })).account;
         if (existing) {
             report.skippedDuplicate++;
             continue;

package/build/src/define_config.d.ts

@@ -537,10 +537,26 @@ export interface LoginConfigInput {
      * idêntico ao de antes, e-mail idêntico). Ver `host/otp_login.ts`.
      */
     otp?: OtpLoginConfigInput;
+    /**
+     * PONTE TEMPORÁRIA: no passo de identificador, quando o e-mail normalizado
+     * (`trim` + `toLowerCase`) não acha conta nenhuma, tenta também o endereço
+     * exatamente como foi digitado e a normalização LEGADA (os defaults do
+     * validator.js que o cadastro aplicava até a v0.68 e que, no gmail, removiam
+     * pontos e sub-endereço `+tag`). Só aceita quando essas formas apontam para
+     * EXATAMENTE UMA conta — empate é tratado como "não achei".
+     *
+     * Existe para que as contas que nasceram com o endereço mutilado
+     * (`davi.carvalho96@gmail.com` gravado como `davicarvalho96@gmail.com`)
+     * continuem tendo caminho de volta. Default: `true` — desligar tranca essas
+     * contas do lado de fora. Depois de migrar os endereços gravados, desligue e,
+     * mais adiante, a ponte inteira sai da lib (ver `host/email_identifier.ts`).
+     */
+    legacyEmailFallback?: boolean;
 }
 export interface ResolvedLoginConfig {
     requireVerifiedEmail: boolean;
     otp: ResolvedOtpLoginConfig;
+    legacyEmailFallback: boolean;
 }
 export declare function resolveLogin(input?: LoginConfigInput): ResolvedLoginConfig;
 /**

package/build/src/define_config.js

@@ -137,6 +137,7 @@ export function resolveLogin(input) {
     return {
         requireVerifiedEmail: input?.requireVerifiedEmail ?? false,
         otp: resolveOtpLoginConfig(input?.otp),
+        legacyEmailFallback: input?.legacyEmailFallback ?? true,
     };
 }
 export function resolveRegistration(input) {

package/build/src/host/account_api/account_api_controller.d.ts

@@ -170,6 +170,8 @@ export default class AccountApiController {
         };
         recovery: {
             available: any;
+            remaining: number | null;
+            regenerable: boolean;
         };
     }>;
     /**

package/build/src/host/account_api/account_api_controller.js

@@ -28,7 +28,7 @@
  *   GET  /account/api/orgs/invitations     → convites pendentes
  */
 import '../augmentations.js';
-import { supportsAccountSecurity, supportsLoginMethodsPreference, supportsMagicLink, supportsOrganizations, supportsPasskeys, supportsProfile, } from '../../accounts/account_store.js';
+import { supportsAccountSecurity, supportsLoginMethodsPreference, supportsMagicLink, supportsOrganizations, supportsPasskeys, supportsProfile, supportsRecoveryCodeCount, supportsRecoveryCodeRegeneration, } from '../../accounts/account_store.js';
 import { PasswordPolicyError } from '../../password/password_manager.js';
 import { accountPath } from '../account_paths.js';
 import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
@@ -627,6 +627,16 @@ export default class AccountApiController {
                 /* fail-safe */
             }
         }
+        // Quantos recovery codes restam (capability-probed, fail-safe).
+        let recoveryRemaining = null;
+        if (supportsRecoveryCodeCount(cfg.accountStore)) {
+            try {
+                recoveryRemaining = await cfg.accountStore.countRecoveryCodes(userId);
+            }
+            catch {
+                /* fail-safe */
+            }
+        }
         return {
             enabled,
             totp: { enrolled: enabled },
@@ -639,8 +649,17 @@ export default class AccountApiController {
                     createdAt: p.createdAt ?? null,
                 })),
             },
-            // Recovery codes are shown once via the existing POST /account/mfa/confirm flow.
-            recovery: { available: enabled },
+            recovery: {
+                // Os códigos em si NUNCA voltam aqui — só no instante em que são
+                // criados (`/mfa/totp/confirm` ou `/mfa/recovery-codes`), porque é só
+                // o hash deles que fica guardado.
+                available: enabled,
+                // `remaining` é `null` quando o store não sabe contar (capacidade
+                // opcional) — diferente de `0`, que significa "acabaram, gere novos".
+                remaining: recoveryRemaining,
+                // O host só mostra o botão "gerar novos códigos" se houver como.
+                regenerable: supportsRecoveryCodeRegeneration(cfg.accountStore),
+            },
         };
     }
     // ─── GET /account/api/login-methods ─────────────────────────────────────

package/build/src/host/account_api/account_mfa_api_controller.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Account Self-Service JSON API — SEGUNDO FATOR (TOTP + passkeys)
+ *
+ * Espelho JSON do `AccountMfaController`, para o host que desenha a própria
+ * tela de "segundo fator" e não pode navegar o browser no meio do fluxo.
+ *
+ * Mapa de rotas (sob o `accountGuard`; mutantes sob o CSRF do shield do host):
+ *   POST /account/api/mfa/totp/enroll       → inicia o enrolamento (sudo)
+ *   POST /account/api/mfa/totp/confirm      → confirma com o código (throttled)
+ *   POST /account/api/mfa/totp/disable      → desliga o MFA (sudo)
+ *   POST /account/api/mfa/recovery-codes    → regenera os códigos (sudo)
+ *   POST /account/api/mfa/passkeys/options  → options da cerimônia de registro
+ *   POST /account/api/mfa/passkeys/verify   → verifica o attestation (sudo)
+ *
+ * Paridade de gates com o console HTML, endpoint a endpoint:
+ *
+ *   | ação             | console HTML | aqui             |
+ *   | ---------------- | ------------ | ---------------- |
+ *   | enroll           | sudo         | sudo → 403 JSON  |
+ *   | confirm          | sem sudo     | sem sudo         |
+ *   | disable          | sudo         | sudo → 403 JSON  |
+ *   | passkey options  | sem sudo     | sem sudo         |
+ *   | passkey verify   | sudo         | sudo → 403 JSON  |
+ *   | recovery codes   | (não existe) | sudo → 403 JSON  |
+ *
+ * A única diferença é a FORMA da recusa: `requireSudo` devolve um redirect para
+ * `/account/confirm`, que numa SPA chega como uma página HTML onde ela esperava
+ * JSON. Aqui a recusa vira `403 { error: { code: 'sudo_required' } }` e a tela
+ * do host manda o usuário confirmar identidade por conta própria. Mesma
+ * política, resposta legível por máquina.
+ *
+ * `confirm` NÃO exige sudo — porque o `enroll` que criou o segredo pendente já
+ * exigiu, e pedir de novo no passo seguinte quebraria o enrolamento de quem
+ * demorou a digitar o código. É exatamente o que o console faz. O que o console
+ * não tem, e aqui existe, é o THROTTLE: o código de 6 dígitos é adivinhável, e
+ * a rota carrega o bucket de sudo (por IP) — mais apertado que o form, nunca
+ * mais frouxo.
+ *
+ * Os dois caminhos (clássico e JSON) COMPARTILHAM o slot do desafio WebAuthn
+ * (`PASSKEY_REG_CHALLENGE_KEY`), então um `options` pedido num deles pode ser
+ * finalizado pelo outro e nunca existem dois desafios vivos na mesma sessão.
+ */
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+export default class AccountMfaApiController {
+    #private;
+    /**
+     * Inicia o enrolamento TOTP: segredo pendente + `otpauth://` URI + o QR já
+     * renderizado como data-URL (o console renderiza server-side; aqui a tela do
+     * host recebe pronto e decide se mostra o QR, o segredo, ou os dois).
+     */
+    enrollTotp(ctx: HttpContext): Promise<void | {
+        secret: string;
+        otpauthUri: string;
+        qrDataUrl: string;
+    }>;
+    /**
+     * Confirma o enrolamento com o código do app autenticador. Sucesso ativa o
+     * MFA e devolve os recovery codes — UMA vez, como no console (lá eles vão num
+     * flash; aqui, no corpo da resposta, que é o equivalente headless).
+     */
+    confirmTotp(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        enabled: boolean;
+        recoveryCodes: string[];
+    }>;
+    /** Desliga o MFA (TOTP + recovery codes). Exige sudo, como o console. */
+    disableTotp(ctx: HttpContext): Promise<{
+        ok: boolean;
+        enabled: boolean;
+    } | undefined>;
+    /**
+     * Regenera os recovery codes de uma conta com MFA ATIVO e devolve os novos —
+     * uma única vez. Exige sudo: o resultado é um conjunto de credenciais que
+     * contorna o segundo fator, então vale o mesmo gate do `enroll`/`disable`.
+     *
+     * Capability-probed: stores que não implementam
+     * `regenerateRecoveryCodes` respondem 422 em vez de 500.
+     */
+    regenerateRecoveryCodes(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+        recoveryCodes: string[];
+    }>;
+    /**
+     * Options da cerimônia de REGISTRO de passkey, guardando o desafio na sessão.
+     * Sem sudo, igual ao endpoint clássico: quem paga o gate é o `verify`, que é
+     * onde a credencial passa a existir.
+     */
+    passkeyRegisterOptions(ctx: HttpContext): Promise<any>;
+    /**
+     * Verifica o attestation contra o desafio da sessão e persiste a credencial.
+     *
+     * O endpoint clássico responde 302 numa navegação e `{ok:true}` num fetch;
+     * este responde SEMPRE JSON — inclusive na recusa de sudo, que lá é um
+     * redirect. É a diferença que faz a cerimônia caber numa SPA: o browser não
+     * pode navegar entre `startRegistration()` e a verificação.
+     */
+    passkeyRegisterVerify(ctx: HttpContext): Promise<void | {
+        ok: boolean;
+    }>;
+}