@adonis-agora/authkit-server 0.49.0 → 0.51.0

package/build/src/host/default_mailer.js

@@ -249,17 +249,41 @@ export async function sendMagicLinkEmail(ctx, data) {
     try {
         const brand = resolveBrand(ctx);
         const { messages: t, locale } = resolveMailMessages(ctx);
-        const content = renderTransactionalEmail({
-            brand,
-            locale,
-            linkFallback: translate(t, 'mail.common.link_fallback'),
-            subject: translate(t, 'mail.magic_link.subject'),
-            heading: translate(t, 'mail.magic_link.heading'),
-            intro: translate(t, 'mail.magic_link.intro'),
-            ctaLabel: translate(t, 'mail.magic_link.cta'),
-            ctaUrl: data.magicUrl,
-            footnote: translate(t, 'mail.magic_link.fallback'),
-        });
+        // Login choose-first: o `channel` decide o que o e-mail SURFA (os dois tokens
+        // continuam emitidos co-locados a montante — isto é só renderização).
+        //  - 'code'  → e-mail SÓ com o código (sem botão/link), quando há código;
+        //  - 'link'  → e-mail SÓ com o link (código suprimido);
+        //  - ausente → ambos (comportamento histórico — back-compat).
+        // Degradação limpa: `channel: 'code'` sem código emitido (OTP desligado) cai
+        // no e-mail de link — não dá pra mostrar um código inexistente.
+        const codeOnly = data.channel === 'code' && !!data.code;
+        const linkOnly = data.channel === 'link';
+        const content = codeOnly
+            ? renderTransactionalEmail({
+                brand,
+                locale,
+                subject: translate(t, 'mail.magic_link.code_subject'),
+                heading: translate(t, 'mail.magic_link.heading'),
+                intro: translate(t, 'mail.magic_link.code_intro'),
+                footnote: translate(t, 'mail.magic_link.fallback'),
+                // Sem `ctaUrl`: e-mail sem botão nem fallback de link — só o código.
+                code: data.code,
+                codeLabel: translate(t, 'mail.magic_link.code_only_label'),
+            })
+            : renderTransactionalEmail({
+                brand,
+                locale,
+                linkFallback: translate(t, 'mail.common.link_fallback'),
+                subject: translate(t, 'mail.magic_link.subject'),
+                heading: translate(t, 'mail.magic_link.heading'),
+                intro: translate(t, 'mail.magic_link.intro'),
+                ctaLabel: translate(t, 'mail.magic_link.cta'),
+                ctaUrl: data.magicUrl,
+                footnote: translate(t, 'mail.magic_link.fallback'),
+                // Código em destaque quando presente — suprimido no canal 'link'.
+                code: linkOnly ? undefined : data.code,
+                codeLabel: translate(t, 'mail.magic_link.code_label'),
+            });
         const sent = await sendEmail(ctx, data.email, content);
         if (!sent) {
             ctx.logger.info({ magicUrl: data.magicUrl, email: data.email }, 'authkit: magic link de login (dev — @adonisjs/mail ausente)');

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

@@ -24,16 +24,31 @@ interface EmailTemplateInput {
     heading: string;
     /** Parágrafo de introdução (texto puro, será escapado). */
     intro: string;
-    /** Rótulo do botão de CTA. */
-    ctaLabel: string;
-    /** URL do CTA. */
-    ctaUrl: string;
+    /**
+     * Rótulo do botão de CTA. Opcional junto de `ctaUrl`: e-mails "só código"
+     * (login por OTP com `channel: 'code'`) não têm botão nem link.
+     */
+    ctaLabel?: string;
+    /**
+     * URL do CTA. Quando ausente, o e-mail é renderizado SEM botão e SEM o
+     * fallback de link (usado no e-mail "só código"). Todos os callers históricos
+     * passam este campo — byte-parity preservado.
+     */
+    ctaUrl?: string;
     /** Linha auxiliar abaixo do botão (ex.: validade do link). */
     footnote?: string;
     /** Texto que precede o link de fallback (i18n). Default em inglês. */
     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,11 +51,13 @@ 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)};">
-<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>
+${codeBlock}${input.ctaUrl
+        ? `<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>` : ''}
-<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(linkFallback)}<br><a href="${esc(input.ctaUrl)}" style="color:${esc(accent)};word-break:break-all;">${esc(input.ctaUrl)}</a></p>
+${input.ctaUrl ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(linkFallback)}<br><a href="${esc(input.ctaUrl)}" style="color:${esc(accent)};word-break:break-all;">${esc(input.ctaUrl)}</a></p>` : ''}
 </td></tr>
 <tr><td style="padding:24px 28px 28px;border-top:1px solid #f3f4f6;">
 <p style="margin:0;font-size:12px;line-height:1.5;color:#9ca3af;">${esc(company)} ${year}</p>
@@ -59,8 +71,8 @@ ${input.footnote ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;col
         input.heading,
         '',
         input.intro,
-        '',
-        `${input.ctaLabel}: ${input.ctaUrl}`,
+        ...(input.code ? ['', `${codeLabel} ${input.code}`] : []),
+        ...(input.ctaUrl ? ['', `${input.ctaLabel}: ${input.ctaUrl}`] : []),
         ...(input.footnote ? ['', input.footnote] : []),
         '',
         `— ${company}`,

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,10 @@ 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.magic_link.code_subject': string;
+    'mail.magic_link.code_intro': string;
+    'mail.magic_link.code_only_label': string;
     'mail.new_login.subject': string;
     'mail.new_login.heading': string;
     'mail.new_login.intro': string;
@@ -744,6 +754,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 +1221,10 @@ 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.magic_link.code_subject': string;
+    'mail.magic_link.code_intro': string;
+    'mail.magic_link.code_only_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,11 @@ 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:',
+    // E-mail "só código" (login choose-first com channel: 'code'): sem botão/link.
+    'mail.magic_link.code_subject': 'Your login code',
+    'mail.magic_link.code_intro': 'Use the code below to sign in. It expires shortly and can be used once.',
+    'mail.magic_link.code_only_label': '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 +826,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 +1338,11 @@ 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:',
+    // E-mail "só código" (login choose-first com channel: 'code'): sem botão/link.
+    'mail.magic_link.code_subject': 'Seu código de login',
+    'mail.magic_link.code_intro': 'Use o código abaixo para entrar. Ele expira em instantes e serve para um único acesso.',
+    'mail.magic_link.code_only_label': '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/login_channel.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canal de login escolhido no seletor "choose-first" (modelo GitHub): o usuário
+ * decide PRIMEIRO como quer entrar e só então o método é executado.
+ *
+ * IMPORTANTE — o `channel` é puramente de SUPERFÍCIE: NÃO condiciona a emissão de
+ * token nem toca no codec `ml2:` / lockout / single-use-conjunto. A lib continua
+ * emitindo link E código co-locados (quando `login.otp.enabled`); o `channel` só
+ * decide o que o E-MAIL renderiza e qual sub-view a TELA mostra no estado
+ * `magicLinkSent`. Ausente/ inválido = comportamento histórico ("both").
+ */
+/** Método escolhido no seletor. `passkey` é slot documentado (ainda não emitido). */
+export type LoginChannel = 'code' | 'link';
+/**
+ * Valor da prop de render que a tela usa para escolher a sub-view do estado
+ * `magicLinkSent`: `'code'` = só campo de código, `'link'` = só aviso de link,
+ * `'both'` = ambos (comportamento histórico, quando o host não manda `channel`).
+ */
+export type MagicChannelProp = 'code' | 'link' | 'both';
+/**
+ * Lê e valida o campo `channel` do body do POST `/magic`. Só `'code'` e `'link'`
+ * são aceitos; qualquer outro valor (ausente, vazio, lixo) vira `undefined`, que
+ * a lib trata como "both" — garantindo back-compat total com hosts que ainda
+ * POSTam sem o campo.
+ */
+export declare function normalizeLoginChannel(raw: unknown): LoginChannel | undefined;
+/**
+ * Mapeia o `channel` do body para a prop de render `magicChannel`. Ausente
+ * (`undefined`) → `'both'`: a tela mostra as duas sub-views, como hoje.
+ */
+export declare function magicChannelProp(channel: LoginChannel | undefined): MagicChannelProp;

package/build/src/host/login_channel.js

@@ -0,0 +1,26 @@
+/**
+ * Canal de login escolhido no seletor "choose-first" (modelo GitHub): o usuário
+ * decide PRIMEIRO como quer entrar e só então o método é executado.
+ *
+ * IMPORTANTE — o `channel` é puramente de SUPERFÍCIE: NÃO condiciona a emissão de
+ * token nem toca no codec `ml2:` / lockout / single-use-conjunto. A lib continua
+ * emitindo link E código co-locados (quando `login.otp.enabled`); o `channel` só
+ * decide o que o E-MAIL renderiza e qual sub-view a TELA mostra no estado
+ * `magicLinkSent`. Ausente/ inválido = comportamento histórico ("both").
+ */
+/**
+ * Lê e valida o campo `channel` do body do POST `/magic`. Só `'code'` e `'link'`
+ * são aceitos; qualquer outro valor (ausente, vazio, lixo) vira `undefined`, que
+ * a lib trata como "both" — garantindo back-compat total com hosts que ainda
+ * POSTam sem o campo.
+ */
+export function normalizeLoginChannel(raw) {
+    return raw === 'code' || raw === 'link' ? raw : undefined;
+}
+/**
+ * Mapeia o `channel` do body para a prop de render `magicChannel`. Ausente
+ * (`undefined`) → `'both'`: a tela mostra as duas sub-views, como hoje.
+ */
+export function magicChannelProp(channel) {
+    return channel ?? 'both';
+}

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;

package/build/src/host/otp_login.js

@@ -0,0 +1,206 @@
+/**
+ * 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.
+ */
+import { createHash, randomInt, timingSafeEqual } from 'node:crypto';
+export const OTP_LOGIN_DEFAULTS = {
+    enabled: false,
+    digits: 6,
+    ttlMinutes: 10,
+    maxAttempts: 5,
+};
+/** Resolve/normaliza a config `login.otp` com os defaults e limites de sanidade. */
+export function resolveOtpLoginConfig(input) {
+    const digitsRaw = input?.digits;
+    const digits = typeof digitsRaw === 'number' && digitsRaw >= 4 && digitsRaw <= 10
+        ? Math.floor(digitsRaw)
+        : OTP_LOGIN_DEFAULTS.digits;
+    const ttlRaw = input?.ttlMinutes;
+    const ttlMinutes = typeof ttlRaw === 'number' && ttlRaw >= 1 ? Math.floor(ttlRaw) : OTP_LOGIN_DEFAULTS.ttlMinutes;
+    const maxRaw = input?.maxAttempts;
+    const maxAttempts = typeof maxRaw === 'number' && maxRaw >= 1 ? Math.floor(maxRaw) : OTP_LOGIN_DEFAULTS.maxAttempts;
+    return {
+        enabled: input?.enabled ?? OTP_LOGIN_DEFAULTS.enabled,
+        digits,
+        ttlMinutes,
+        maxAttempts,
+    };
+}
+// ---------------------------------------------------------------------------
+// Geração e hashing do código
+// ---------------------------------------------------------------------------
+/**
+ * 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 function generateOtpCode(digits) {
+    const max = 10 ** digits;
+    const n = randomInt(0, max);
+    return String(n).padStart(digits, '0');
+}
+/**
+ * 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 function hashLoginOtp(uid, code) {
+    return createHash('sha256').update(`${uid}:${code}`).digest('hex');
+}
+/**
+ * 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 function safeEqualHex(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return false;
+    const bufA = Buffer.from(a, 'hex');
+    const bufB = Buffer.from(b, 'hex');
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+// ---------------------------------------------------------------------------
+// Codec do slot composto `ml2:`
+// ---------------------------------------------------------------------------
+/** Prefixo do slot `passwordResetToken` quando o login por OTP está ativo. */
+export const OTP_LOGIN_PREFIX = 'ml2:';
+/** Só hex minúsculo (64 chars = sha256). Guard contra metacaracteres de LIKE. */
+const HEX_64 = /^[0-9a-f]{64}$/;
+/** Serializa o estado do OTP no formato de slot `ml2:...`. */
+export function encodeOtpToken(state) {
+    return `${OTP_LOGIN_PREFIX}${state.linkToken}:${state.codeHash}:${state.codeExpMs}:${state.attempts}`;
+}
+/**
+ * Decodifica o valor ARMAZENADO no slot (`ml2:<linkToken>:<codeHash>:<exp>:<att>`).
+ * Retorna `null` se não for um slot `ml2:` bem-formado.
+ */
+export function decodeOtpToken(value) {
+    if (!value || !value.startsWith(OTP_LOGIN_PREFIX))
+        return null;
+    const rest = value.slice(OTP_LOGIN_PREFIX.length);
+    const parts = rest.split(':');
+    if (parts.length !== 4)
+        return null;
+    const [linkToken, codeHash, expStr, attStr] = parts;
+    if (!HEX_64.test(linkToken))
+        return null;
+    if (codeHash !== '' && !HEX_64.test(codeHash))
+        return null;
+    const codeExpMs = Number(expStr);
+    const attempts = Number(attStr);
+    if (!Number.isFinite(codeExpMs) || !Number.isInteger(attempts) || attempts < 0)
+        return null;
+    return { linkToken, codeHash, codeExpMs, attempts };
+}
+/**
+ * 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 function linkTokenFromOtpUrl(urlToken) {
+    if (!urlToken.startsWith(OTP_LOGIN_PREFIX))
+        return null;
+    const linkToken = urlToken.slice(OTP_LOGIN_PREFIX.length);
+    return HEX_64.test(linkToken) ? linkToken : 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 function evaluateLoginOtp(input) {
+    const { parsed, uid, code, nowMs, maxAttempts } = input;
+    // Sem código pendente (slot vazio, `ml:` legado ou token de reset).
+    if (!parsed)
+        return { result: 'no_code' };
+    // LOCKOUT: código já invalidado (hash vazio) OU tentativas esgotadas.
+    // Fail-CLOSED — imposto pelo contador PERSISTIDO, sem depender de limiter.
+    if (parsed.codeHash === '' || parsed.attempts >= maxAttempts) {
+        return { result: 'locked' };
+    }
+    // TTL do código (mais curto que o do link).
+    if (parsed.codeExpMs < nowMs)
+        return { result: 'expired' };
+    // Comparação constant-time do hash atrelado ao uid.
+    const candidate = hashLoginOtp(uid, code);
+    if (safeEqualHex(candidate, parsed.codeHash)) {
+        // Sucesso: limpa o slot → mata o magic link junto (single-use conjunto).
+        return { result: 'ok', nextToken: null };
+    }
+    // Falha: incrementa o contador.
+    const attempts = parsed.attempts + 1;
+    if (attempts >= maxAttempts) {
+        // Última tentativa: INVALIDA o código (zera o hash) mas PRESERVA o link.
+        return { result: 'locked', nextToken: encodeOtpToken({ ...parsed, codeHash: '', attempts }) };
+    }
+    return { result: 'invalid', nextToken: encodeOtpToken({ ...parsed, attempts }) };
+}