@adonis-agora/authkit-server 0.69.0 → 0.71.0

package/build/src/commands/normalize_emails.js

@@ -0,0 +1,129 @@
+import { supportsAccountEmailRewrite } from '../accounts/account_store.js';
+import { normalizeEmailIdentifier } from '../host/email_identifier.js';
+import { ADMIN_LIST_DEFAULT_SIZE } from '../pagination.js';
+/** Comparação por code unit — mesma ordem em qualquer máquina, sem depender do ICU. */
+function byCodeUnit(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/**
+ * Migração dos endereços GRAVADOS para a forma normalizada da identidade
+ * (`normalizeEmailIdentifier`: `trim` + `toLowerCase`).
+ *
+ * POR QUE ELA EXISTE: até a v0.68 o cadastro gravava o endereço mutilado pelo
+ * `.normalizeEmail()` do VineJS (no gmail, sem pontos e sem `+tag`), e import,
+ * convite e provider social gravavam a grafia crua, com maiúsculas. O login
+ * busca UMA forma só — a normalizada. Uma conta gravada em qualquer outra grafia
+ * fica INALCANÇÁVEL, e, por o login ser à prova de enumeração, sem nenhuma
+ * mensagem de erro. Esta migração é o que reencontra essas contas.
+ *
+ * Em modo RELATÓRIO (default) não escreve nada: varre, calcula e devolve o que
+ * mudaria. Com `apply`, grava — RECUSANDO-SE a tocar em qualquer conta envolvida
+ * numa colisão (duas contas que colapsam no mesmo endereço). Nunca funde contas,
+ * nunca escolhe vencedor: as colididas saem listadas para decisão humana.
+ *
+ * A varredura acontece INTEIRA antes de qualquer escrita, de propósito: a
+ * listagem é ordenada por e-mail, e reescrever endereços no meio da paginação
+ * moveria linhas entre páginas — contas seriam puladas sem nenhum sinal.
+ *
+ * Lógica PURA quanto a CLI (recebe o store, devolve o relatório) — testável sem
+ * ace e sem banco.
+ */
+export async function normalizeAccountEmails(store, options = {}) {
+    const pageSize = options.pageSize ?? ADMIN_LIST_DEFAULT_SIZE;
+    const report = {
+        scanned: 0,
+        alreadyNormalized: 0,
+        changes: [],
+        applied: 0,
+        collisions: [],
+        skippedByCollision: 0,
+        unusable: [],
+    };
+    // 1) Varredura completa. Guarda só id + e-mail (strings), agrupados pela forma
+    //    normalizada — é o agrupamento que revela as colisões.
+    const buckets = new Map();
+    for (let page = 1;; page++) {
+        const { data, total } = await store.listAccounts({ page, size: pageSize });
+        if (!data.length)
+            break;
+        for (const account of data) {
+            report.scanned++;
+            const normalized = normalizeEmailIdentifier(account.email);
+            const bucket = buckets.get(normalized);
+            if (bucket)
+                bucket.push({ accountId: account.id, email: account.email });
+            else
+                buckets.set(normalized, [{ accountId: account.id, email: account.email }]);
+        }
+        if (report.scanned >= total)
+            break;
+    }
+    // 2) Classificação: colisão, mudança ou já normalizada.
+    const pending = [];
+    for (const [normalized, accounts] of buckets) {
+        // `normalized` vazio (coluna nula/vazia/só espaços) não é migrável. Sai
+        // LISTADO, não somado às "já normalizadas": o relatório não pode dar
+        // atestado de saúde para a linha que ele deliberadamente deixou para trás.
+        // ANTES da checagem de colisão: duas linhas em branco caem no mesmo balde
+        // `""` e sairiam como "colisão no endereço ''", que não descreve nada.
+        if (!normalized) {
+            report.unusable.push(...accounts);
+            continue;
+        }
+        if (accounts.length > 1) {
+            // Duas contas distintas no mesmo endereço normalizado. NENHUMA é tocada —
+            // nem a que já está normalizada, porque a decisão (fundir? renomear? qual
+            // delas é a pessoa?) é humana e envolve as duas.
+            report.collisions.push({ email: normalized, accounts });
+            report.skippedByCollision += accounts.length;
+            continue;
+        }
+        const [account] = accounts;
+        if (account.email === normalized) {
+            report.alreadyNormalized++;
+            continue;
+        }
+        pending.push({
+            accountId: account.accountId,
+            from: account.email,
+            to: normalized,
+            applied: false,
+        });
+    }
+    // Ordem estável (por endereço gravado) para o relatório ser diffável entre
+    // runs. Comparação por code unit, NÃO `localeCompare`: a ordem desta depende
+    // do ICU da máquina, e aí "diffável" valeria só dentro de um host.
+    pending.sort((a, b) => byCodeUnit(a.from, b.from));
+    report.collisions.sort((a, b) => byCodeUnit(a.email, b.email));
+    // `unusable` também: sem isto a lista sairia na ordem da varredura, que é a
+    // ordem do store — a mesma garantia não valeria para ela.
+    report.unusable.sort((a, b) => byCodeUnit(a.accountId, b.accountId));
+    report.changes = pending;
+    if (!options.apply)
+        return report;
+    // 3) Escrita. Capacidade probada: um store sem ela não tem como regravar o
+    //    endereço, e inventar um caminho por fora do store não é da lib.
+    if (!supportsAccountEmailRewrite(store)) {
+        throw new Error('accountStore não implementa rewriteAccountEmail: a migração não tem como gravar (relatório segue funcionando).');
+    }
+    for (const change of pending) {
+        try {
+            const ok = await store.rewriteAccountEmail(change.accountId, change.to);
+            if (ok) {
+                change.applied = true;
+                report.applied++;
+            }
+            else {
+                // O store recusou: conta sumiu ou o endereço passou a ser de OUTRA conta
+                // entre a varredura e a escrita (colisão que nasceu no meio do caminho).
+                change.error = 'o store recusou a regravação (conta inexistente ou endereço já tomado)';
+            }
+        }
+        catch (error) {
+            change.error = error.message;
+        }
+    }
+    return report;
+}

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;
+    }>;
+}

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

@@ -0,0 +1,286 @@
+/**
+ * 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 QRCode from 'qrcode';
+import { supportsMfa, supportsPasskeys, supportsRecoveryCodeRegeneration, } from '../../accounts/account_store.js';
+import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
+import { translate } from '../i18n.js';
+import { PASSKEY_REG_CHALLENGE_KEY } from '../passkey_registration_challenge.js';
+import { resolveRuntimeSettings } from '../runtime_settings.js';
+import { dispatchSecurityNotice } from '../security_notice_service.js';
+import { isSudoSatisfied } from '../sudo_mode.js';
+/** Erro JSON padrão — mesmo envelope do `account_api_controller`. */
+function apiErr(code, message) {
+    return { error: { code, message } };
+}
+export default class AccountMfaApiController {
+    // ─── POST /account/api/mfa/totp/enroll ──────────────────────────────────
+    /**
+     * 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).
+     */
+    async enrollTotp(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        const started = await c.store.startTotpEnrollment(c.userId);
+        if (!started) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('enroll_failed', 'Could not start TOTP enrollment.'));
+        }
+        const qrDataUrl = await QRCode.toDataURL(started.otpauthUri);
+        return { secret: started.secret, otpauthUri: started.otpauthUri, qrDataUrl };
+    }
+    // ─── POST /account/api/mfa/totp/confirm ─────────────────────────────────
+    /**
+     * 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).
+     */
+    async confirmTotp(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        const code = String(ctx.request.input('code', '') ?? '').trim();
+        const result = await c.store.confirmTotpEnrollment(c.userId, code);
+        if (!result.ok) {
+            // NÃO regenera o segredo pendente: o usuário já escaneou o QR, e um
+            // segredo novo invalidaria o app autenticador dele. Mesma decisão do
+            // console — a tela pede outro código sobre o MESMO segredo.
+            return ctx.response
+                .status(422)
+                .send(apiErr('invalid_code', translate(c.cfg.messages, 'errors.invalid_code')));
+        }
+        await c.cfg.audit?.record({
+            type: 'mfa.enabled',
+            accountId: c.userId,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { method: 'totp' },
+        });
+        await this.#notice(ctx, c, 'mfa_enabled');
+        return { ok: true, enabled: true, recoveryCodes: result.recoveryCodes ?? [] };
+    }
+    // ─── POST /account/api/mfa/totp/disable ─────────────────────────────────
+    /** Desliga o MFA (TOTP + recovery codes). Exige sudo, como o console. */
+    async disableTotp(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        await c.store.disableMfa(c.userId);
+        await c.cfg.audit?.record({
+            type: 'mfa.disabled',
+            accountId: c.userId,
+            ip: ctx.request.ip?.() ?? null,
+        });
+        await this.#notice(ctx, c, 'mfa_disabled');
+        return { ok: true, enabled: false };
+    }
+    // ─── POST /account/api/mfa/recovery-codes ───────────────────────────────
+    /**
+     * 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.
+     */
+    async regenerateRecoveryCodes(ctx) {
+        const c = await this.#mfaContext(ctx);
+        if (!c)
+            return;
+        if (!supportsRecoveryCodeRegeneration(c.store)) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', 'Recovery code regeneration not supported.'));
+        }
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        const codes = await c.store.regenerateRecoveryCodes(c.userId);
+        if (!codes) {
+            // Sem MFA ativo não há conjunto a regenerar — enrolar é o caminho.
+            return ctx.response.status(422).send(apiErr('mfa_not_enabled', 'MFA is not enabled.'));
+        }
+        await c.cfg.audit?.record({
+            type: 'mfa.recovery_codes_regenerated',
+            accountId: c.userId,
+            ip: ctx.request.ip?.() ?? null,
+        });
+        return { ok: true, recoveryCodes: codes };
+    }
+    // ─── POST /account/api/mfa/passkeys/options ─────────────────────────────
+    /**
+     * 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.
+     */
+    async passkeyRegisterOptions(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        if (!supportsPasskeys(cfg.accountStore)) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', translate(cfg.messages, 'errors.passkeys_unavailable')));
+        }
+        const generated = await cfg.accountStore.generatePasskeyRegistrationOptions?.(userId);
+        if (!generated) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', translate(cfg.messages, 'errors.passkeys_unavailable')));
+        }
+        ctx.session.put(PASSKEY_REG_CHALLENGE_KEY, generated.challenge);
+        return generated.options;
+    }
+    // ─── POST /account/api/mfa/passkeys/verify ──────────────────────────────
+    /**
+     * 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.
+     */
+    async passkeyRegisterVerify(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        if (!supportsPasskeys(cfg.accountStore)) {
+            return ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', translate(cfg.messages, 'errors.passkeys_unavailable')));
+        }
+        if (!(await this.#requireSudoJson(ctx)))
+            return;
+        const challenge = ctx.session.get(PASSKEY_REG_CHALLENGE_KEY);
+        if (!challenge) {
+            return ctx.response
+                .status(400)
+                .send(apiErr('challenge_expired', translate(cfg.messages, 'errors.challenge_expired')));
+        }
+        const body = ctx.request.input('response', ctx.request.body());
+        const ok = (await cfg.accountStore.verifyPasskeyRegistration?.(userId, body, challenge)) ?? false;
+        // Queima o desafio em QUALQUER desfecho: um attestation recusado não pode
+        // ser retentado contra o mesmo challenge.
+        ctx.session.forget(PASSKEY_REG_CHALLENGE_KEY);
+        if (!ok) {
+            return ctx.response
+                .status(400)
+                .send(apiErr('invalid_response', translate(cfg.messages, 'errors.invalid_code')));
+        }
+        const ip = ctx.request.ip?.() ?? null;
+        await cfg.audit?.record({
+            type: 'mfa.enabled',
+            accountId: userId,
+            ip,
+            metadata: { method: 'webauthn' },
+        });
+        await cfg.audit?.record({ type: 'passkey.registered', accountId: userId, ip });
+        const account = await cfg.accountStore.findById(userId);
+        if (account) {
+            const ts = new Date().toISOString();
+            for (const kind of ['passkey_added', 'mfa_enabled']) {
+                await dispatchSecurityNotice(ctx, { account: { id: userId, email: account.email }, kind, ip, timestamp: ts }, cfg.mail, cfg.audit, cfg);
+            }
+        }
+        return { ok: true };
+    }
+    // ─── Internos ───────────────────────────────────────────────────────────
+    /**
+     * Resolve config + store com MFA + a conta da sessão. Quando o pré-requisito
+     * falha, JÁ RESPONDE e devolve `null`.
+     */
+    async #mfaContext(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const store = cfg.accountStore;
+        if (!supportsMfa(store)) {
+            ctx.response
+                .status(422)
+                .send(apiErr('capability_unsupported', 'MFA not supported by the account store.'));
+            return null;
+        }
+        const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        if (!userId) {
+            ctx.response.unauthorized(apiErr('unauthorized', 'Not authenticated.'));
+            return null;
+        }
+        return { cfg, store, userId };
+    }
+    /**
+     * Gate de sudo em versão JSON. A DECISÃO é a mesmíssima do console —
+     * `isSudoSatisfied`, de onde o `requireSudo` do form também tira a dele
+     * (mesma setting, mesma janela de graça, mesma vinculação à conta, mesmo
+     * fail-safe) —, só a RECUSA muda de forma: `403 sudo_required` em vez do
+     * redirect para `/account/confirm`.
+     *
+     * Chama a decisão, e não o `requireSudo`, porque aquele ESCREVE na resposta
+     * ao recusar (`response.redirect`): sobrepor um 403 depois deixaria um
+     * `Location` pendurado numa resposta que não é redirect. Devolve `false`
+     * quando já respondeu.
+     */
+    async #requireSudoJson(ctx) {
+        const settings = await resolveRuntimeSettings(ctx);
+        if (await isSudoSatisfied(ctx, settings))
+            return true;
+        ctx.response.status(403).send(apiErr('sudo_required', 'Identity confirmation required.'));
+        return false;
+    }
+    /** Notificação de segurança best-effort (nunca derruba a operação). */
+    async #notice(ctx, c, kind) {
+        const account = await c.cfg.accountStore.findById(c.userId);
+        if (!account)
+            return;
+        await dispatchSecurityNotice(ctx, {
+            account: { id: c.userId, email: account.email },
+            kind: kind,
+            ip: ctx.request.ip?.() ?? null,
+            timestamp: new Date().toISOString(),
+        }, c.cfg.mail, c.cfg.audit, c.cfg);
+    }
+}