@adonis-agora/authkit-server 0.48.0 → 0.50.0

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

@@ -37,7 +37,7 @@ export default class AccountConfirmController {
                 ctx.logger?.warn({ method: m.id }, `authkit: método de sudo "${m.id}" está em config.sudo.methods mas não teve rotas montadas por registerAuthHost — a tela vai oferecer uma opção cujo endpoint não existe`);
             }
         }
-        return c.cfg.render(ctx, 'account/confirm', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             returnTo: c.returnTo,
             error: ctx.session.flashMessages.get('confirmError') ?? null,
@@ -47,6 +47,7 @@ export default class AccountConfirmController {
             notice: ctx.session.flashMessages.get('confirmNotice') ?? null,
             methods,
             preferredId: ctx.session.get(LAST_METHOD_SESSION_KEY) ?? null,
-        });
+        };
+        return c.cfg.render(ctx, 'account/confirm', props);
     }
 }

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

@@ -40,13 +40,14 @@ export default class AccountMfaController {
         // Passkeys disponíveis quando o store as suporta (model de credenciais wired).
         const passkeysSupported = supportsPasskeys(cfg.accountStore);
         const passkeys = passkeysSupported ? await cfg.accountStore.listPasskeys(userId) : [];
-        return render(ctx, 'account/mfa', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             enabled: state.enabled,
             recoveryCodes: recoveryCodes ?? null,
             passkeysSupported,
             passkeys,
-        });
+        };
+        return render(ctx, 'account/mfa', props);
     }
     /**
      * POST /account/mfa/passkeys/options — gera as opções de registro de passkey
@@ -178,14 +179,15 @@ export default class AccountMfaController {
         }
         // QR renderizado server-side como data-URL e passado como prop.
         const qrDataUrl = await QRCode.toDataURL(started.otpauthUri);
-        return render(ctx, 'account/mfa', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             enabled: false,
             enrolling: true,
             secret: started.secret,
             qrDataUrl,
             recoveryCodes: null,
-        });
+        };
+        return render(ctx, 'account/mfa', props);
     }
     /** POST /account/mfa/confirm — confirma o código; sucesso = ativa e mostra recovery codes. */
     async confirm(ctx) {
@@ -199,7 +201,7 @@ export default class AccountMfaController {
             // Reenvia o passo de confirmação com erro SEM regenerar o segredo pendente
             // (o usuário já escaneou o QR; um novo segredo invalidaria o app autenticador).
             // Mostra só o campo de código para nova tentativa.
-            return render(ctx, 'account/mfa', {
+            const props = {
                 csrfToken: ctx.request.csrfToken,
                 enabled: false,
                 enrolling: true,
@@ -207,7 +209,8 @@ export default class AccountMfaController {
                 qrDataUrl: null,
                 error: translate(cfg.messages, 'errors.invalid_code'),
                 recoveryCodes: null,
-            });
+            };
+            return render(ctx, 'account/mfa', props);
         }
         await cfg.audit?.record({
             type: 'mfa.enabled',

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

@@ -65,7 +65,7 @@ export default class AccountSecurityController {
         const ownSessions = sessionsSupported
             ? await enrichSessionsWithContext(cfg, userId, await adminSessions.listSessions(userId))
             : [];
-        return render(ctx, 'account/security', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             supported: supportsAccountSecurity(cfg.accountStore),
             profileSupported: supportsProfile(cfg.accountStore),
@@ -94,7 +94,8 @@ export default class AccountSecurityController {
             // Deleção de conta (LGPD): só quando o store suporta hard delete.
             deletionSupported: supportsAccountDeletion(cfg.accountStore),
             deleteError: ctx.session.flashMessages.get('deleteError') ?? null,
-        });
+        };
+        return render(ctx, 'account/security', props);
     }
     /**
      * GET /account/security/export — baixa um JSON com os dados da conta logada

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

@@ -48,7 +48,11 @@ export default class AccountSessionController {
         // Lê e valida o return_to da query-string — descarta valores inválidos (open-redirect).
         const rawReturnTo = ctx.request.qs?.()?.return_to ?? ctx.request.input?.('return_to');
         const returnTo = validateReturnTo(rawReturnTo);
-        return render(ctx, 'account/login', { csrfToken: ctx.request.csrfToken, returnTo });
+        const props = {
+            csrfToken: ctx.request.csrfToken,
+            returnTo,
+        };
+        return render(ctx, 'account/login', props);
     }
     async login(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
@@ -74,7 +78,7 @@ export default class AccountSessionController {
             settings: settings ?? undefined,
         });
         if (!result.ok) {
-            return render(ctx, 'account/login', {
+            const props = {
                 csrfToken: ctx.request.csrfToken,
                 returnTo,
                 error: result.locked
@@ -84,7 +88,8 @@ export default class AccountSessionController {
                     : result.disabled
                         ? translate(cfg.messages, 'errors.account_disabled')
                         : translate(cfg.messages, 'errors.invalid_credentials'),
-            });
+            };
+            return render(ctx, 'account/login', props);
         }
         const acc = result.account;
         // M5 (session fixation): regenera a sessão IMEDIATAMENTE após autenticar e

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

@@ -70,6 +70,17 @@ export default class AuthInteractionController {
      * inválido/expirado volta ao início do login.
      */
     magicLinkConsume(ctx: HttpContext): Promise<any>;
+    /**
+     * POST /auth/interaction/:uid/otp-verify
+     *
+     * Verifica o CÓDIGO OTP de login (o mesmo e-mail carrega link E código). Roda
+     * atrás do throttle dedicado `authkit_otp_login` (por IP, mais apertado que o
+     * login). A ordem das checagens de segurança — lockout (contador persistido no
+     * slot) → TTL → comparação constant-time — vive no store (`verifyLoginCode` →
+     * `evaluateLoginOtp`). Em sucesso, completa a MESMA interaction que o link
+     * completaria (amr `['email']`), consumindo código E link (single-use conjunto).
+     */
+    otpVerify(ctx: HttpContext): Promise<any>;
     /**
      * POST /auth/interaction/:uid/passkey/options
      *

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

@@ -1,5 +1,5 @@
 import '../augmentations.js';
-import { supportsMagicLink, supportsPasskeys } from '../../accounts/account_store.js';
+import { supportsMagicLink, supportsOtpLogin, supportsPasskeys, } from '../../accounts/account_store.js';
 import { AdminSessionsService } from '../admin_sessions_service.js';
 import { guardBotProtection, resolveEffectiveBotProtection } from '../bot_protection.js';
 import { brandFor, isFirstParty } from '../branding.js';
@@ -609,23 +609,45 @@ export default class AuthInteractionController {
         const brand = brandFor(cfg.branding, details.params.client_id, details.params.audience);
         const email = ctx.session.get(SESSION_KEY);
         const uid = ctx.request.param('uid');
+        // Login por OTP: liga o campo de código na tela "link enviado" quando a config
+        // está ligada E o store suporta a capacidade.
+        const otpEnabled = cfg.login.otp.enabled && supportsOtpLogin(cfg.accountStore);
         if (cfg.passwordless.magicLink && supportsMagicLink(cfg.accountStore) && email) {
-            const issued = await cfg.accountStore.issueMagicLinkToken(email);
+            const ip = ctx.request.ip?.() ?? null;
+            const clientId = details.params.client_id ?? null;
+            // Com OTP ligado, emite link E código no MESMO disparo (issueMagicLinkWithCode);
+            // senão, o magic link puro de sempre.
+            const issued = otpEnabled
+                ? await cfg.accountStore.issueMagicLinkWithCode(email, uid, {
+                    digits: cfg.login.otp.digits,
+                    ttlMinutes: cfg.login.otp.ttlMinutes,
+                })
+                : await cfg.accountStore.issueMagicLinkToken(email);
             if (issued) {
+                const code = 'code' in issued ? issued.code : undefined;
                 await cfg.audit?.record({
                     type: 'login.magic_link_sent',
                     accountId: issued.account.id,
                     email,
-                    ip: ctx.request.ip?.() ?? null,
-                    clientId: details.params.client_id ?? null,
+                    ip,
+                    clientId,
                 });
+                if (code) {
+                    await cfg.audit?.record({
+                        type: 'login.otp_sent',
+                        accountId: issued.account.id,
+                        email,
+                        ip,
+                        clientId,
+                    });
+                }
                 const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
                 const magicUrl = `${origin}/auth/interaction/${uid}/magic?token=${encodeURIComponent(issued.token)}`;
                 if (cfg.mail?.onMagicLink) {
-                    await cfg.mail.onMagicLink({ email, magicUrl, token: issued.token });
+                    await cfg.mail.onMagicLink({ email, magicUrl, token: issued.token, code });
                 }
                 else {
-                    await sendMagicLinkEmail(ctx, { email, magicUrl });
+                    await sendMagicLinkEmail(ctx, { email, magicUrl, code });
                 }
             }
         }
@@ -639,6 +661,7 @@ export default class AuthInteractionController {
             account: null,
             brand,
             magicLinkSent: true,
+            otpEnabled,
         });
     }
     /**
@@ -700,6 +723,113 @@ export default class AuthInteractionController {
         ctx.session.forget(SESSION_KEY);
         await service.interactions.completeLogin(ctx, acc.id, { amr: ['email'] });
     }
+    /**
+     * POST /auth/interaction/:uid/otp-verify
+     *
+     * Verifica o CÓDIGO OTP de login (o mesmo e-mail carrega link E código). Roda
+     * atrás do throttle dedicado `authkit_otp_login` (por IP, mais apertado que o
+     * login). A ordem das checagens de segurança — lockout (contador persistido no
+     * slot) → TTL → comparação constant-time — vive no store (`verifyLoginCode` →
+     * `evaluateLoginOtp`). Em sucesso, completa a MESMA interaction que o link
+     * completaria (amr `['email']`), consumindo código E link (single-use conjunto).
+     */
+    async otpVerify(ctx) {
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        const uid = ctx.request.param('uid');
+        const ip = ctx.request.ip?.() ?? null;
+        const clientId = (await service.interactions.details(ctx)).params.client_id;
+        const email = ctx.session.get(SESSION_KEY);
+        // Guardas: OTP desligado, store sem suporte ou sem e-mail na sessão → volta ao login.
+        const otpEnabled = cfg.login.otp.enabled && supportsOtpLogin(cfg.accountStore);
+        if (!otpEnabled || !email) {
+            return ctx.response.redirect(`/auth/interaction/${uid}`);
+        }
+        const code = String(ctx.request.input('code', '') ?? '').trim();
+        const brand = brandFor(cfg.branding, clientId ?? undefined, undefined);
+        const result = await cfg.accountStore.verifyLoginCode(email, uid, code, {
+            maxAttempts: cfg.login.otp.maxAttempts,
+        });
+        // Re-render da tela "link enviado" com o campo de código + erro localizado.
+        const renderOtpError = async (messageKey) => render(ctx, 'login', {
+            ...(await this.#loginMethods(ctx, cfg)),
+            uid,
+            csrfToken: ctx.request.csrfToken,
+            step: 'password',
+            email,
+            account: null,
+            brand,
+            magicLinkSent: true,
+            otpEnabled: true,
+            otpError: translate(cfg.messages, messageKey),
+        });
+        if (result.status === 'ok') {
+            // E-mail não verificado (LGPD): mesmo com código válido, não materializa a
+            // sessão se a política exige verificação. Espelha o magicLinkConsume.
+            const runtimeSettings = await getRuntimeSettings(ctx);
+            if (await isEmailUnverifiedBlock(cfg, result.account.id, runtimeSettings)) {
+                await cfg.audit?.record({
+                    type: 'login.failure',
+                    accountId: result.account.id,
+                    email: result.account.email,
+                    ip,
+                    clientId,
+                    metadata: { stage: 'otp', reason: 'unverified' },
+                });
+                return render(ctx, 'login', {
+                    ...(await this.#loginMethods(ctx, cfg)),
+                    uid,
+                    csrfToken: ctx.request.csrfToken,
+                    step: 'password',
+                    email: result.account.email,
+                    account: null,
+                    brand,
+                    error: translate(cfg.messages, 'errors.email_unverified'),
+                });
+            }
+            await cfg.audit?.record({
+                type: 'login.otp_verified',
+                accountId: result.account.id,
+                email: result.account.email,
+                ip,
+                clientId,
+            });
+            await notifyLoginSuccess(ctx, cfg, {
+                accountId: result.account.id,
+                email: result.account.email,
+                ip,
+                clientId: clientId ?? null,
+                metadata: { method: 'otp' },
+            });
+            ctx.session.forget(SESSION_KEY);
+            return service.interactions.completeLogin(ctx, result.account.id, { amr: ['email'] });
+        }
+        if (result.status === 'locked') {
+            // 5ª falha (ou já travado): código invalidado, o LINK continua válido.
+            await cfg.audit?.record({ type: 'login.otp_invalidated', email, ip, clientId });
+            return renderOtpError('login.otp_locked');
+        }
+        if (result.status === 'expired') {
+            await cfg.audit?.record({
+                type: 'login.otp_failed',
+                email,
+                ip,
+                clientId,
+                metadata: { reason: 'expired' },
+            });
+            return renderOtpError('login.otp_expired');
+        }
+        // 'invalid' (tentativa contabilizada) ou 'no_code'.
+        await cfg.audit?.record({
+            type: 'login.otp_failed',
+            email,
+            ip,
+            clientId,
+            metadata: { reason: result.status },
+        });
+        return renderOtpError('login.otp_invalid');
+    }
     /**
      * POST /auth/interaction/:uid/passkey/options
      *

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

@@ -62,6 +62,7 @@ export declare function sendNewDeviceLoginEmail(ctx: HttpContext, data: {
 export declare function sendMagicLinkEmail(ctx: HttpContext, data: {
     email: string;
     magicUrl: string;
+    code?: string;
 }): Promise<void>;
 /**
  * Envia o e-mail de aviso de segurança ao e-mail ATUAL quando uma troca de

package/build/src/host/default_mailer.js

@@ -259,6 +259,9 @@ export async function sendMagicLinkEmail(ctx, data) {
             ctaLabel: translate(t, 'mail.magic_link.cta'),
             ctaUrl: data.magicUrl,
             footnote: translate(t, 'mail.magic_link.fallback'),
+            // Login por OTP: quando o código é fornecido, renderiza-o em destaque.
+            code: data.code,
+            codeLabel: translate(t, 'mail.magic_link.code_label'),
         });
         const sent = await sendEmail(ctx, data.email, content);
         if (!sent) {

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

@@ -34,6 +34,14 @@ interface EmailTemplateInput {
     linkFallback?: string;
     /** Locale do documento HTML (atributo `lang`). Default: 'en'. */
     locale?: string;
+    /**
+     * Código OTP de login (dígitos). Quando presente, é renderizado em destaque
+     * (grande, monoespaçado) acima do CTA, com um rótulo. Usado pelo login por OTP
+     * (o mesmo e-mail carrega link E código). Ausente = e-mail idêntico ao de antes.
+     */
+    code?: string;
+    /** Rótulo acima do código (i18n). Default em inglês. */
+    codeLabel?: string;
 }
 export declare function renderTransactionalEmail(input: EmailTemplateInput): EmailContent;
 export {};

package/build/src/host/email_templates.js

@@ -24,6 +24,16 @@ export function renderTransactionalEmail(input) {
     const lang = input.locale || 'en';
     const linkFallback = input.linkFallback ||
         'If the button does not work, copy and paste this link into your browser:';
+    const codeLabel = input.codeLabel || 'Or enter this code:';
+    // Bloco do código OTP (grande/monoespaçado), renderizado só quando há código.
+    // Termina em '\n' quando presente para manter o <table> seguinte em linha própria;
+    // vazio quando ausente (sem linha em branco extra — byte-parity com o e-mail
+    // pré-OTP).
+    const codeBlock = input.code
+        ? `<p style="margin:0 0 8px;font-size:13px;line-height:1.5;color:#6b7280;">${esc(codeLabel)}</p>
+<p style="margin:0 0 24px;font-size:32px;font-weight:700;letter-spacing:6px;font-family:'SFMono-Regular',Consolas,'Liberation Mono',Menlo,monospace;color:#111827;">${esc(input.code)}</p>
+`
+        : '';
     const html = `<!doctype html>
 <html lang="${esc(lang)}">
 <head>
@@ -41,7 +51,7 @@ export function renderTransactionalEmail(input) {
 <tr><td style="padding:32px 28px 8px;">
 <h1 style="margin:0 0 12px;font-size:20px;line-height:1.3;color:#111827;">${esc(input.heading)}</h1>
 <p style="margin:0 0 24px;font-size:15px;line-height:1.6;color:#374151;">${esc(input.intro)}</p>
-<table role="presentation" cellpadding="0" cellspacing="0"><tr><td style="border-radius:8px;background:${esc(accent)};">
+${codeBlock}<table role="presentation" cellpadding="0" cellspacing="0"><tr><td style="border-radius:8px;background:${esc(accent)};">
 <a href="${esc(input.ctaUrl)}" style="display:inline-block;padding:12px 24px;font-size:15px;font-weight:600;color:#ffffff;text-decoration:none;border-radius:8px;">${esc(input.ctaLabel)}</a>
 </td></tr></table>
 ${input.footnote ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(input.footnote)}</p>` : ''}
@@ -59,6 +69,7 @@ ${input.footnote ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;col
         input.heading,
         '',
         input.intro,
+        ...(input.code ? ['', `${codeLabel} ${input.code}`] : []),
         '',
         `${input.ctaLabel}: ${input.ctaUrl}`,
         ...(input.footnote ? ['', input.footnote] : []),

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

@@ -50,6 +50,12 @@ export declare const DEFAULT_MESSAGES: {
     'login.magic_link_sent': string;
     'signup.magic_link_sent': string;
     'login.passkey_button': string;
+    'login.otp_label': string;
+    'login.otp_placeholder': string;
+    'login.otp_submit': string;
+    'login.otp_invalid': string;
+    'login.otp_expired': string;
+    'login.otp_locked': string;
     'signup.page_title': string;
     'signup.title': string;
     'signup.intro': string;
@@ -511,6 +517,7 @@ export declare const DEFAULT_MESSAGES: {
     'mail.magic_link.intro': string;
     'mail.magic_link.cta': string;
     'mail.magic_link.fallback': string;
+    'mail.magic_link.code_label': string;
     'mail.new_login.subject': string;
     'mail.new_login.heading': string;
     'mail.new_login.intro': string;
@@ -744,6 +751,12 @@ export declare const PT_BR_MESSAGES: {
     'login.magic_link_sent': string;
     'signup.magic_link_sent': string;
     'login.passkey_button': string;
+    'login.otp_label': string;
+    'login.otp_placeholder': string;
+    'login.otp_submit': string;
+    'login.otp_invalid': string;
+    'login.otp_expired': string;
+    'login.otp_locked': string;
     'signup.page_title': string;
     'signup.title': string;
     'signup.intro': string;
@@ -1205,6 +1218,7 @@ export declare const PT_BR_MESSAGES: {
     'mail.magic_link.intro': string;
     'mail.magic_link.cta': string;
     'mail.magic_link.fallback': string;
+    'mail.magic_link.code_label': string;
     'mail.new_login.subject': string;
     'mail.new_login.heading': string;
     'mail.new_login.intro': string;

package/build/src/host/i18n.js

@@ -41,6 +41,13 @@ export const DEFAULT_MESSAGES = {
     'login.magic_link_sent': 'If the account exists, we sent you a login link.',
     'signup.magic_link_sent': 'Check your email — we sent you a link to finish creating your account.',
     'login.passkey_button': 'Sign in with a passkey',
+    // Login por OTP (código digitável).
+    'login.otp_label': 'Enter the login code from the email',
+    'login.otp_placeholder': '000000',
+    'login.otp_submit': 'Sign in with the code',
+    'login.otp_invalid': 'Invalid code. Please try again.',
+    'login.otp_expired': 'This code has expired. Use the login link or request a new one.',
+    'login.otp_locked': 'Too many attempts. The code was disabled — use the login link instead.',
     // Tela de cadastro (signup).
     'signup.page_title': 'Create account',
     'signup.title': 'Create account',
@@ -550,6 +557,7 @@ export const DEFAULT_MESSAGES = {
     'mail.magic_link.intro': 'Click the button below to sign in. The link expires shortly and can be used once.',
     'mail.magic_link.cta': 'Sign in',
     'mail.magic_link.fallback': 'If you did not request this, you can ignore this email.',
+    'mail.magic_link.code_label': 'Or enter this code to sign in:',
     'mail.new_login.subject': 'New login to your account',
     'mail.new_login.heading': 'New login detected',
     'mail.new_login.intro': 'We detected a new login to your account.',
@@ -814,6 +822,13 @@ export const PT_BR_MESSAGES = {
     'login.magic_link_sent': 'Se a conta existir, enviamos um link de login.',
     'signup.magic_link_sent': 'Enviamos um link para o seu e-mail. Abra-o para concluir o cadastro.',
     'login.passkey_button': 'Entrar com passkey',
+    // Login por OTP (código digitável).
+    'login.otp_label': 'Digite o código de login do e-mail',
+    'login.otp_placeholder': '000000',
+    'login.otp_submit': 'Entrar com o código',
+    'login.otp_invalid': 'Código inválido. Tente novamente.',
+    'login.otp_expired': 'Este código expirou. Use o link de login ou peça um novo.',
+    'login.otp_locked': 'Tentativas demais. O código foi desativado — use o link de login.',
     // Tela de cadastro (signup).
     'signup.page_title': 'Criar conta',
     'signup.title': 'Criar conta',
@@ -1319,6 +1334,7 @@ export const PT_BR_MESSAGES = {
     'mail.magic_link.intro': 'Clique no botão abaixo para entrar. O link expira em breve e pode ser usado uma vez.',
     'mail.magic_link.cta': 'Entrar',
     'mail.magic_link.fallback': 'Se você não solicitou isso, pode ignorar este e-mail.',
+    'mail.magic_link.code_label': 'Ou digite este código para entrar:',
     'mail.new_login.subject': 'Novo login na sua conta',
     'mail.new_login.heading': 'Novo login detectado',
     'mail.new_login.intro': 'Detectamos um novo login na sua conta.',

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

@@ -0,0 +1,155 @@
+/**
+ * Login por OTP (código digitável) — helpers puros + máquina de estados da
+ * verificação.
+ *
+ * ── Por que este módulo existe (e o porquê da decisão de armazenamento) ───────
+ * O host passwordless já tem magic link (token de 256 bits, IMPOSSÍVEL de
+ * adivinhar). O código de 6 dígitos é ADIVINHÁVEL: exige lockout dedicado +
+ * throttle — segurança que não se reimplementa por host. O mesmo e-mail passa a
+ * carregar LINK e CÓDIGO; os dois completam a MESMA interaction OIDC.
+ *
+ * ── Decisão de armazenamento (investigação registrada no código) ─────────────
+ * O SPEC ranqueia três opções e manda a investigação decidir. Resultado:
+ *
+ *   1. (preferida no spec) Guardar `otpHash`/`otpExpiresAt`/`otpAttempts` no
+ *      REGISTRO DA INTERACTION do oidc-provider — **INVIÁVEL**. O modelo
+ *      `Interaction` do oidc-provider só persiste os campos listados em
+ *      `IN_PAYLOAD` (`base_model.js` filtra o payload por
+ *      `IN_PAYLOAD.includes(key)` no construtor; `save()` chama
+ *      `getValueAndPayload`). Campos custom de topo são DESCARTADOS ao persistir.
+ *      O único slot livre persistido é `lastSubmission`, dono do mecanismo
+ *      `mergeWithLastSubmission` — sequestrá-lo é frágil. Ver
+ *      `node_modules/oidc-provider/lib/models/interaction.js:57` e
+ *      `.../base_model.js:34`.
+ *
+ *   2. (ESCOLHIDA) Formato composto no slot já existente do token de magic link
+ *      (`passwordResetToken`, hoje `ml:<token>`). Passa a `ml2:<...>` quando o
+ *      OTP está ligado. Esta opção resolve os TRÊS requisitos duros de uma vez:
+ *        • **Single-use conjunto** — código e link vivem no MESMO slot da MESMA
+ *          linha: consumir qualquer um limpa o slot → o outro morre junto, sem
+ *          coordenação entre stores.
+ *        • **Contador de tentativas persistido SEM limiter** — o contador vive
+ *          DENTRO do slot. O lockout é imposto pelo próprio contador persistido
+ *          (fail-CLOSED: não depende do `@adonisjs/limiter`), ao contrário do
+ *          `otp_lockout.ts`, que vira no-op sem limiter — perigoso para um código
+ *          curto. O throttle de rota (`authkit_otp_login`) é camada EXTRA por IP.
+ *        • **TTL herdado** — a coluna `passwordResetExpiresAt` já dá validade ao
+ *          link; o código carrega o próprio `codeExpMs` embutido (mais curto).
+ *
+ *   3. Coluna nova via ensure-schema — desnecessária (a opção 2 não exige
+ *      migração), então descartada.
+ *
+ * ── Formato do slot (`ml2:`) ─────────────────────────────────────────────────
+ *   Armazenado:  `ml2:<linkToken>:<codeHash>:<codeExpMs>:<attempts>`
+ *   Na URL:      `ml2:<linkToken>`  (SÓ o token do link — o código, o hash e o
+ *                contador NUNCA saem no e-mail/URL, então o atacante não tem como
+ *                zerar o contador manipulando o que ele recebe).
+ *
+ *   • `linkToken` — 32 bytes hex; é o token do magic link (mesma força de antes).
+ *   • `codeHash`  — `sha256(<uid>:<code>)` em hex, ou VAZIO quando o código foi
+ *                   invalidado por lockout (o link continua válido e localizável).
+ *                   Atrelar ao `uid` da interaction honra o escopo "por
+ *                   interaction" do spec: um código emitido numa interaction não
+ *                   verifica em outra, mesmo para o mesmo e-mail.
+ *   • `codeExpMs` — epoch ms de expiração DO CÓDIGO (TTL curto, default 10 min).
+ *   • `attempts`  — contador server-side de tentativas erradas (começa em 0).
+ *
+ * Segurança do contador: como o link e o código compartilham o slot mas o
+ * LOCKOUT do código NÃO pode matar o link (spec), a invalidação por lockout zera
+ * o `codeHash` (mantendo `linkToken`) em vez de limpar o slot inteiro.
+ */
+/** Config de entrada do login por OTP (`login.otp` no config/authkit.ts). */
+export interface OtpLoginConfigInput {
+    /** Liga o login por código. Default: **false** (opt-in, back-compat total). */
+    enabled?: boolean;
+    /** Número de dígitos do código. Default: 6. Faixa aceita: 4–10. */
+    digits?: number;
+    /** Validade do código em minutos. Default: 10. Mínimo: 1. */
+    ttlMinutes?: number;
+    /** Tentativas erradas antes de invalidar o código. Default: 5. Mínimo: 1. */
+    maxAttempts?: number;
+}
+export interface ResolvedOtpLoginConfig {
+    enabled: boolean;
+    digits: number;
+    ttlMinutes: number;
+    maxAttempts: number;
+}
+export declare const OTP_LOGIN_DEFAULTS: ResolvedOtpLoginConfig;
+/** Resolve/normaliza a config `login.otp` com os defaults e limites de sanidade. */
+export declare function resolveOtpLoginConfig(input?: OtpLoginConfigInput): ResolvedOtpLoginConfig;
+/**
+ * Gera um código numérico de `digits` dígitos, zero-padded, SEM viés de módulo.
+ *
+ * Usa `crypto.randomInt(0, 10 ** digits)` — o `randomInt` do Node faz rejection
+ * sampling internamente, então a distribuição é uniforme (nada de `% 10`, que
+ * enviesaria os dígitos baixos). Para `digits=6` o teto é 1_000_000, bem abaixo
+ * do limite de `randomInt` (2**48).
+ */
+export declare function generateOtpCode(digits: number): string;
+/**
+ * Hash do código atrelado ao `uid` da interaction: `sha256(<uid>:<code>)` em hex.
+ * Atrelar ao uid escopa o código à interaction que o emitiu.
+ */
+export declare function hashLoginOtp(uid: string, code: string): string;
+/**
+ * Comparação constant-time de dois digests hex de MESMO tamanho.
+ *
+ * `timingSafeEqual` exige buffers de tamanho igual — comprimentos diferentes
+ * lançam. Por isso a guarda de tamanho vem antes (retorno `false` sem vazar
+ * timing útil: o atacante não controla o tamanho do digest server-side, que é
+ * sempre 64 hex de um sha256).
+ */
+export declare function safeEqualHex(a: string, b: string): boolean;
+/** Prefixo do slot `passwordResetToken` quando o login por OTP está ativo. */
+export declare const OTP_LOGIN_PREFIX = "ml2:";
+/** Estado decodificado do slot `ml2:`. */
+export interface ParsedOtpToken {
+    linkToken: string;
+    /** `sha256(<uid>:<code>)` hex; vazio quando o código foi invalidado (lockout). */
+    codeHash: string;
+    codeExpMs: number;
+    attempts: number;
+}
+/** Serializa o estado do OTP no formato de slot `ml2:...`. */
+export declare function encodeOtpToken(state: ParsedOtpToken): string;
+/**
+ * Decodifica o valor ARMAZENADO no slot (`ml2:<linkToken>:<codeHash>:<exp>:<att>`).
+ * Retorna `null` se não for um slot `ml2:` bem-formado.
+ */
+export declare function decodeOtpToken(value: string | null | undefined): ParsedOtpToken | null;
+/**
+ * Extrai o `linkToken` de uma URL de magic link `ml2:<linkToken>` (a forma que
+ * vai no e-mail, SEM o estado do código). Retorna `null` se não casar o formato
+ * ou se o token não for hex de 64 (guarda contra LIKE injection na busca).
+ */
+export declare function linkTokenFromOtpUrl(urlToken: string): string | null;
+export type OtpVerifyOutcome = 'ok' | 'invalid' | 'locked' | 'expired' | 'no_code';
+export interface OtpVerifyEvaluation {
+    result: OtpVerifyOutcome;
+    /**
+     * O que persistir no slot `passwordResetToken` como efeito:
+     *   • `undefined` — não escrever (nada mudou: expired/no_code/locked-já-travado).
+     *   • `null`      — LIMPAR o slot (sucesso: mata o link junto — single-use conjunto).
+     *   • string      — novo valor `ml2:` (falha: contador++ ou código invalidado).
+     */
+    nextToken?: string | null;
+}
+/**
+ * Avalia UMA tentativa de código, na ORDEM travada pelo spec:
+ *   lockout (contador/estado do código) → TTL do código → comparação constant-time.
+ *
+ * O throttle de rota e a validade da interaction são resolvidos ANTES, no
+ * controller. Aqui mora só a lógica que precisa do estado persistido do código.
+ *
+ * IMPORTANTE (prova de mutação): a checagem de LOCKOUT é a primeira guarda. Se
+ * removida, um atacante que já esgotou as tentativas volta a poder chutar — o
+ * teste `remove-lockout` cobre exatamente isso.
+ */
+export declare function evaluateLoginOtp(input: {
+    parsed: ParsedOtpToken | null;
+    uid: string;
+    code: string;
+    nowMs: number;
+    maxAttempts: number;
+}): OtpVerifyEvaluation;