@adonis-agora/authkit-server 0.49.0 → 0.50.0

package/build/host/views/login.edge

@@ -193,6 +193,24 @@
       {{-- Passwordless: confirmação de magic link enviado (anti-enumeração). --}}
       @if(magicLinkSent)
         <p class="mt-4 rounded-lg bg-green-50 px-3 py-2 text-sm text-green-700">{{ t('login.magic_link_sent') }}</p>
+
+        {{-- Login por OTP: campo de código digitável (mesmo e-mail carrega link E código). --}}
+        @if(otpEnabled)
+          <form method="POST" action="/auth/interaction/{{ uid }}/otp-verify" class="mt-4">
+            <input type="hidden" name="_csrf" value="{{ csrfToken }}">
+            <label for="otp-code" class="block text-sm font-medium text-gray-700">{{ t('login.otp_label') }}</label>
+            <input id="otp-code" name="code" type="text" inputmode="numeric" autocomplete="one-time-code"
+              pattern="[0-9]*" placeholder="{{ t('login.otp_placeholder') }}"
+              class="mt-2 w-full rounded-lg border border-gray-300 px-3 py-2.5 text-center text-lg tracking-[0.4em] font-mono focus:border-gray-900 focus:ring-gray-900" />
+            @if(otpError)
+              <p class="mt-2 text-sm text-red-600">{{ otpError }}</p>
+            @end
+            <button type="submit"
+              class="mt-4 w-full rounded-lg bg-gray-900 py-2.5 text-sm font-semibold text-white transition hover:opacity-90">
+              {{ t('login.otp_submit') }}
+            </button>
+          </form>
+        @end
       @end
 
       {{-- Passwordless: "me envie um link de login" (mesma sessão/e-mail; não pede senha). --}}

package/build/index.d.ts

@@ -23,8 +23,9 @@ export { lucidAccountStore, appKeyEncrypter } from './src/accounts/lucid_account
 export { lucidStores } from './src/accounts/lucid_stores.js';
 export type { LucidStoresModels, LucidStoresOptions, LucidStoresResult, } from './src/accounts/lucid_stores.js';
 export type { LucidAccountStoreOptions, AccountSecretEncrypter, } from './src/accounts/lucid_account_store.js';
-export type { AccountStore, CoreAccountStore, AdminCapability, MfaCapability, WebauthnCapability, ProviderIdentityCapability, ProviderIdentitySummary, AccountSecurityCapability, AccountStatusCapability, ProfileCapability, MagicLinkCapability, EmailVerificationStatusCapability, AccountDeletionCapability, AccountImportCapability, ImportAccountInput, AuthAccount, CreateAccountInput, LinkProviderIdentityInput, ListAccountsParams, Paginated, PasskeySummary, } from './src/accounts/account_store.js';
-export { supportsMfa, supportsPasskeys, supportsProviderIdentity, supportsAccountSecurity, supportsAccountStatus, supportsProfile, supportsMagicLink, supportsEmailVerificationStatus, supportsAccountDeletion, supportsAccountImport, } from './src/accounts/account_store.js';
+export type { AccountStore, CoreAccountStore, AdminCapability, MfaCapability, WebauthnCapability, ProviderIdentityCapability, ProviderIdentitySummary, AccountSecurityCapability, AccountStatusCapability, ProfileCapability, MagicLinkCapability, OtpLoginCapability, OtpLoginVerifyResult, EmailVerificationStatusCapability, AccountDeletionCapability, AccountImportCapability, ImportAccountInput, AuthAccount, CreateAccountInput, LinkProviderIdentityInput, ListAccountsParams, Paginated, PasskeySummary, } from './src/accounts/account_store.js';
+export { supportsMfa, supportsPasskeys, supportsProviderIdentity, supportsAccountSecurity, supportsAccountStatus, supportsProfile, supportsMagicLink, supportsOtpLogin, supportsEmailVerificationStatus, supportsAccountDeletion, supportsAccountImport, } from './src/accounts/account_store.js';
+export { type OtpLoginConfigInput, type ResolvedOtpLoginConfig, type OtpVerifyOutcome, resolveOtpLoginConfig, generateOtpCode, evaluateLoginOtp, OTP_LOGIN_DEFAULTS, } from './src/host/otp_login.js';
 export { PasswordManager, PasswordPolicyError, } from './src/password/password_manager.js';
 export type { PasswordConfigInput, LegacyPasswordVerifier, PasswordVerifyResult, } from './src/password/password_manager.js';
 export { checkPasswordPolicy, policyViolationParams, DEFAULT_PWNED_TIMEOUT_MS, } from './src/password/policy.js';

package/build/index.js

@@ -14,7 +14,9 @@ export { resolveTrustedDevices, isTrustedDeviceValid, buildTrustedDevicePayload,
 export { resolveBotProtection, botProtectionApplies, extractBotToken, verifyBotProtection, guardBotProtection, DEFAULT_BOT_TOKEN_FIELDS, } from './src/host/bot_protection.js';
 export { lucidAccountStore, appKeyEncrypter } from './src/accounts/lucid_account_store.js';
 export { lucidStores } from './src/accounts/lucid_stores.js';
-export { supportsMfa, supportsPasskeys, supportsProviderIdentity, supportsAccountSecurity, supportsAccountStatus, supportsProfile, supportsMagicLink, supportsEmailVerificationStatus, supportsAccountDeletion, supportsAccountImport, } from './src/accounts/account_store.js';
+export { supportsMfa, supportsPasskeys, supportsProviderIdentity, supportsAccountSecurity, supportsAccountStatus, supportsProfile, supportsMagicLink, supportsOtpLogin, supportsEmailVerificationStatus, supportsAccountDeletion, supportsAccountImport, } from './src/accounts/account_store.js';
+// Login por OTP (código digitável): config + helpers puros.
+export { resolveOtpLoginConfig, generateOtpCode, evaluateLoginOtp, OTP_LOGIN_DEFAULTS, } from './src/host/otp_login.js';
 // Gerência de senha: lazy rehash + legacy verifier, política e checagem de vazamento.
 export { PasswordManager, PasswordPolicyError, } from './src/password/password_manager.js';
 export { checkPasswordPolicy, policyViolationParams, DEFAULT_PWNED_TIMEOUT_MS, } from './src/password/policy.js';

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

@@ -421,6 +421,62 @@ export interface MagicLinkCapability {
      */
     consumeMagicLinkToken(token: string): Promise<AuthAccount | null>;
 }
+/** Resultado tipado da verificação de um código OTP de login. */
+export type OtpLoginVerifyResult = {
+    status: 'ok';
+    account: AuthAccount;
+}
+/** Código errado, tentativa contabilizada (ainda NÃO travado). */
+ | {
+    status: 'invalid';
+}
+/** Tentativas esgotadas → código invalidado (o link continua válido). */
+ | {
+    status: 'locked';
+}
+/** TTL do código expirou. */
+ | {
+    status: 'expired';
+}
+/** Nenhum código pendente para esta interaction/conta. */
+ | {
+    status: 'no_code';
+};
+/**
+ * Login por OTP (código digitável) — extensão do magic link. CAPACIDADE
+ * opcional: quando ausente (ou `login.otp.enabled` desligado) o comportamento é
+ * exatamente o de antes (só magic link).
+ *
+ * O store default (Lucid) CO-LOCALIZA o código com o magic link no MESMO slot
+ * (`passwordResetToken`, prefixo `ml2:`), de modo que consumir um mata o outro
+ * (single-use conjunto) e o contador de tentativas fica PERSISTIDO junto do
+ * código (lockout fail-closed, sem depender de limiter). Ver `host/otp_login.ts`
+ * para a decisão de armazenamento completa.
+ */
+export interface OtpLoginCapability {
+    /**
+     * Emite o magic link E um código OTP de uma vez (mesmo disparo/e-mail). O
+     * `token` retornado vai na URL do link; o `code` (dígitos) vai no corpo do
+     * e-mail. Retorna null se a conta não existe (o controller sempre responde
+     * "enviado", anti-enumeração). O código fica atrelado ao `uid` da interaction.
+     */
+    issueMagicLinkWithCode(email: string, uid: string, opts: {
+        digits: number;
+        ttlMinutes: number;
+    }): Promise<{
+        token: string;
+        code: string;
+        account: AuthAccount;
+    } | null>;
+    /**
+     * Verifica um código para a interaction `uid`. Em sucesso consome o código E o
+     * magic link (single-use conjunto). Falha incrementa o contador persistido; ao
+     * esgotar `maxAttempts` invalida o código mantendo o link válido.
+     */
+    verifyLoginCode(email: string, uid: string, code: string, opts: {
+        maxAttempts: number;
+    }): Promise<OtpLoginVerifyResult>;
+}
 /** DTO público de uma organização. */
 export interface OrgSummary {
     id: string;
@@ -543,7 +599,7 @@ export type AccountStore = CoreAccountStore & {
      * blocos `Partial<...>` de capacidades probáveis.
      */
     readonly connectionName?: string;
-} & Partial<MfaCapability & WebauthnCapability & ProviderIdentityCapability & AccountSecurityCapability & AccountStatusCapability & ProfileCapability & MagicLinkCapability & EmailVerificationStatusCapability & AccountDeletionCapability & AccountImportCapability & OrganizationsCapability & PasswordHistoryCapability & PasswordExpirationCapability>;
+} & Partial<MfaCapability & WebauthnCapability & ProviderIdentityCapability & AccountSecurityCapability & AccountStatusCapability & ProfileCapability & MagicLinkCapability & OtpLoginCapability & EmailVerificationStatusCapability & AccountDeletionCapability & AccountImportCapability & OrganizationsCapability & PasswordHistoryCapability & PasswordExpirationCapability>;
 /** Type guard: o store implementa a capacidade de MFA / TOTP. */
 export declare function supportsMfa(store: AccountStore): store is AccountStore & MfaCapability;
 /**
@@ -566,6 +622,8 @@ export declare function supportsAccountStatus(store: AccountStore): store is Acc
 export declare function supportsProfile(store: AccountStore): store is AccountStore & ProfileCapability;
 /** Type guard: o store implementa login por magic link (passwordless). */
 export declare function supportsMagicLink(store: AccountStore): store is AccountStore & MagicLinkCapability;
+/** Type guard: o store implementa o login por OTP (código digitável). */
+export declare function supportsOtpLogin(store: AccountStore): store is AccountStore & OtpLoginCapability;
 /** Type guard: o store consegue dizer se o e-mail de uma conta está verificado. */
 export declare function supportsEmailVerificationStatus(store: AccountStore): store is AccountStore & EmailVerificationStatusCapability;
 /** Type guard: o store implementa a deleção (hard delete) da conta. */

package/build/src/accounts/account_store.js

@@ -38,6 +38,11 @@ export function supportsProfile(store) {
 export function supportsMagicLink(store) {
     return typeof store.issueMagicLinkToken === 'function';
 }
+/** Type guard: o store implementa o login por OTP (código digitável). */
+export function supportsOtpLogin(store) {
+    return (typeof store.issueMagicLinkWithCode === 'function' &&
+        typeof store.verifyLoginCode === 'function');
+}
 /** Type guard: o store consegue dizer se o e-mail de uma conta está verificado. */
 export function supportsEmailVerificationStatus(store) {
     return typeof store.isEmailVerified === 'function';

package/build/src/accounts/lucid_store/core.d.ts

@@ -1,4 +1,4 @@
-import type { AccountImportCapability, AccountSecurityCapability, CoreAccountStore, MagicLinkCapability } from '../account_store.js';
+import type { AccountImportCapability, AccountSecurityCapability, CoreAccountStore, MagicLinkCapability, OtpLoginCapability } from '../account_store.js';
 import type { LucidStoreContext } from './shared.js';
 /**
  * Núcleo SEMPRE presente do {@link CoreAccountStore} sobre um model Lucid:
@@ -6,4 +6,4 @@ import type { LucidStoreContext } from './shared.js';
  * (listagem paginada + roles globais) e o self-service de segurança
  * ({@link AccountSecurityCapability}: trocar senha/e-mail).
  */
-export declare function buildCore(ctx: LucidStoreContext): CoreAccountStore & AccountSecurityCapability & MagicLinkCapability & AccountImportCapability;
+export declare function buildCore(ctx: LucidStoreContext): CoreAccountStore & AccountSecurityCapability & MagicLinkCapability & OtpLoginCapability & AccountImportCapability;

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

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { Scrypt } from '@adonisjs/core/hash/drivers/scrypt';
 import { DateTime } from 'luxon';
+import { OTP_LOGIN_PREFIX, decodeOtpToken, encodeOtpToken, evaluateLoginOtp, generateOtpCode, hashLoginOtp, linkTokenFromOtpUrl, } from '../../host/otp_login.js';
 import { hasColumn } from './status_profile.js';
 /** Prefixo do token de troca de e-mail (reaproveita a coluna emailVerificationToken). */
 const EMAIL_CHANGE_PREFIX = 'ec:';
@@ -131,9 +132,9 @@ export function buildCore(ctx) {
             return { token, account: toAccount(row) };
         },
         async consumePasswordResetToken(token, newPassword) {
-            // Magic links (`ml:`) NÃO são tokens de reset de senha — só o fluxo de
-            // consumeMagicLinkToken pode consumi-los (não trocam senha).
-            if (token.startsWith(MAGIC_LINK_PREFIX))
+            // Magic links (`ml:` e `ml2:` com OTP) NÃO são tokens de reset de senha —
+            // só o fluxo de consumeMagicLinkToken pode consumi-los (não trocam senha).
+            if (token.startsWith(MAGIC_LINK_PREFIX) || token.startsWith(OTP_LOGIN_PREFIX))
                 return false;
             const row = await Model.query().where('passwordResetToken', token).first();
             if (!row)
@@ -167,7 +168,29 @@ export function buildCore(ctx) {
             return { token, account: toAccount(row) };
         },
         async consumeMagicLinkToken(token) {
-            if (!token || !token.startsWith(MAGIC_LINK_PREFIX))
+            if (!token)
+                return null;
+            // Magic link com OTP ativo: o slot guarda `ml2:<linkToken>:<...>` mas a URL
+            // carrega só `ml2:<linkToken>`. Busca pelo prefixo do link (linkToken é hex
+            // validado — sem metacaractere de LIKE) e consome o slot inteiro (mata o
+            // código junto — single-use conjunto).
+            if (token.startsWith(OTP_LOGIN_PREFIX)) {
+                const linkToken = linkTokenFromOtpUrl(token);
+                if (!linkToken)
+                    return null;
+                const row = await Model.query()
+                    .where('passwordResetToken', 'like', `${OTP_LOGIN_PREFIX}${linkToken}:%`)
+                    .first();
+                if (!row)
+                    return null;
+                if (!row.passwordResetExpiresAt || row.passwordResetExpiresAt < DateTime.now())
+                    return null;
+                row.passwordResetToken = null;
+                row.passwordResetExpiresAt = null;
+                await row.save();
+                return toAccount(row);
+            }
+            if (!token.startsWith(MAGIC_LINK_PREFIX))
                 return null;
             const row = await Model.query().where('passwordResetToken', token).first();
             if (!row)
@@ -180,6 +203,84 @@ export function buildCore(ctx) {
             await row.save();
             return toAccount(row);
         },
+        // ----- Login por OTP (código digitável — extensão do magic link) -----
+        async issueMagicLinkWithCode(email, uid, opts) {
+            const row = await Model.query().where('email', email).first();
+            if (!row)
+                return null;
+            const linkToken = randomBytes(32).toString('hex');
+            const code = generateOtpCode(opts.digits);
+            const codeHash = hashLoginOtp(uid, code);
+            const codeExpMs = DateTime.now().plus({ minutes: opts.ttlMinutes }).toMillis();
+            // Slot `ml2:` — código + link juntos, contador em 0. Ver host/otp_login.ts.
+            row.passwordResetToken = encodeOtpToken({ linkToken, codeHash, codeExpMs, attempts: 0 });
+            // O LINK herda a validade padrão do magic link (15 min); o CÓDIGO carrega o
+            // próprio `codeExpMs` (mais curto) embutido no slot.
+            row.passwordResetExpiresAt = DateTime.now().plus({ minutes: 15 });
+            await row.save();
+            return { token: `${OTP_LOGIN_PREFIX}${linkToken}`, code, account: toAccount(row) };
+        },
+        async verifyLoginCode(email, uid, code, opts) {
+            // ── Atomicidade do contador de lockout (barreira PRIMÁRIA, fail-closed) ──
+            // O contador de tentativas vive DENTRO do slot `ml2:` e é a única barreira
+            // contra brute-force do código curto (o throttle de rota é camada EXTRA e
+            // pode estar ausente). Um read-modify-write ingênuo (first→avaliar→save) é
+            // derrotável por concorrência: N requests leem o MESMO contador, todos
+            // gravam `attempts+1` (last-write-wins) e o lockout nunca dispara — pior,
+            // como a COMPARAÇÃO do código acontece após a leitura, N requests
+            // concorrentes conseguem N comparações contra o MESMO valor do contador,
+            // varrendo o espaço de 10^6 dentro do TTL.
+            //
+            // Correção: serializa o read-compare-write numa TRANSAÇÃO com row-lock
+            // (`forUpdate`). Cada tentativa lê o estado JÁ commitado pela anterior, o
+            // contador avança 1-a-1 e — porque a comparação vive DENTRO da seção
+            // crítica — o total de comparações contra um mesmo código fica limitado a
+            // `maxAttempts` (garantia DURA, não probabilística). No Postgres o lock é
+            // por linha; no sqlite a própria transação serializa. Os demais caminhos
+            // que tocam o slot (`consumeMagicLinkToken`, sucesso do OTP) só gravam
+            // `null` (terminal) — não regridem contador — e ainda serializam atrás
+            // deste lock (todo UPDATE trava a linha), então não podem ressuscitar um
+            // slot já consumido nem apagar um incremento.
+            const trx = await Model.query().client.transaction();
+            try {
+                const row = await Model.query({ client: trx }).where('email', email).forUpdate().first();
+                if (!row) {
+                    await trx.commit();
+                    return { status: 'no_code' };
+                }
+                const parsed = decodeOtpToken(row.passwordResetToken);
+                const evaluation = evaluateLoginOtp({
+                    parsed,
+                    uid,
+                    code,
+                    nowMs: DateTime.now().toMillis(),
+                    maxAttempts: opts.maxAttempts,
+                });
+                // Efeito de persistência: `undefined` = não escreve; `null` = limpa o slot
+                // (sucesso, mata o link junto); string = novo slot (contador++/invalidação).
+                // A escrita ocorre DENTRO da mesma transação/lock da leitura.
+                if (evaluation.nextToken === null) {
+                    row.useTransaction(trx);
+                    row.passwordResetToken = null;
+                    row.passwordResetExpiresAt = null;
+                    await row.save();
+                }
+                else if (typeof evaluation.nextToken === 'string') {
+                    // Contador/invalidação: preserva a validade do LINK (só o código muda).
+                    row.useTransaction(trx);
+                    row.passwordResetToken = evaluation.nextToken;
+                    await row.save();
+                }
+                await trx.commit();
+                if (evaluation.result === 'ok')
+                    return { status: 'ok', account: toAccount(row) };
+                return { status: evaluation.result };
+            }
+            catch (error) {
+                await trx.rollback();
+                throw error;
+            }
+        },
         async issueEmailVerificationToken(email) {
             const row = await Model.query().where('email', email).first();
             if (!row)

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

@@ -1,7 +1,7 @@
 /**
  * Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP.
  */
-export type AuditEventType = 'login.success' | 'login.failure' | 'signup' | 'password_reset.issued' | 'password_reset.consumed' | 'pat.issued' | 'pat.revoked' | 'pat.used' | 'impersonation' | 'impersonation.started' | 'mfa.enabled' | 'mfa.disabled' | 'account.locked' | 'passkey.registered' | 'passkey.removed' | 'email_verification.issued' | 'email_verification.consumed' | 'client.created' | 'client.updated' | 'client.deleted' | 'session.revoked_all' | 'password.changed' | 'password.rehashed' | 'email.change_requested' | 'email.changed' | 'login.new_ip_notified' | 'login.new_device' | 'bot_protection.rejected' | 'grant.revoked_by_user' | 'user.created' | 'user.password_reset_sent' | 'user.disabled' | 'user.enabled' | 'user.deleted' | 'profile.updated' | 'account.deleted' | 'account.exported' | 'keys.rotated' | 'organization.created' | 'organization.updated' | 'organization.deleted' | 'organization.member_added' | 'organization.member_removed' | 'organization.member_role_changed' | 'organization.member_role_updated' | 'organization.switched' | 'organization.deactivated' | 'organization.invitation_sent' | 'organization.invitation_accepted' | 'organization.invitation_revoked' | 'email_change.requested' | 'email_change.confirmed' | 'email_change.cancelled' | 'security_notice.sent' | 'settings.updated' | 'maintenance.enabled' | 'maintenance.disabled' | 'trusted_device.revoked' | 'password.expired_change_forced' | 'otp.locked' | 'otp.unlocked' | 'otp.unlock_failed' | 'sudo.confirmed' | 'session.single_enforced' | 'account.expired_login_blocked' | 'account.expiration_warned';
+export type AuditEventType = 'login.success' | 'login.failure' | 'signup' | 'password_reset.issued' | 'password_reset.consumed' | 'pat.issued' | 'pat.revoked' | 'pat.used' | 'impersonation' | 'impersonation.started' | 'mfa.enabled' | 'mfa.disabled' | 'account.locked' | 'passkey.registered' | 'passkey.removed' | 'email_verification.issued' | 'email_verification.consumed' | 'client.created' | 'client.updated' | 'client.deleted' | 'session.revoked_all' | 'password.changed' | 'password.rehashed' | 'email.change_requested' | 'email.changed' | 'login.new_ip_notified' | 'login.new_device' | 'login.otp_sent' | 'login.otp_verified' | 'login.otp_failed' | 'login.otp_invalidated' | 'bot_protection.rejected' | 'grant.revoked_by_user' | 'user.created' | 'user.password_reset_sent' | 'user.disabled' | 'user.enabled' | 'user.deleted' | 'profile.updated' | 'account.deleted' | 'account.exported' | 'keys.rotated' | 'organization.created' | 'organization.updated' | 'organization.deleted' | 'organization.member_added' | 'organization.member_removed' | 'organization.member_role_changed' | 'organization.member_role_updated' | 'organization.switched' | 'organization.deactivated' | 'organization.invitation_sent' | 'organization.invitation_accepted' | 'organization.invitation_revoked' | 'email_change.requested' | 'email_change.confirmed' | 'email_change.cancelled' | 'security_notice.sent' | 'settings.updated' | 'maintenance.enabled' | 'maintenance.disabled' | 'trusted_device.revoked' | 'password.expired_change_forced' | 'otp.locked' | 'otp.unlocked' | 'otp.unlock_failed' | 'sudo.confirmed' | 'session.single_enforced' | 'account.expired_login_blocked' | 'account.expiration_warned';
 /**
  * Evento de auditoria a registrar. O timestamp é definido pelo sink (não aqui).
  */

package/build/src/define_config.d.ts

@@ -8,6 +8,7 @@ import { type BotProtectionConfigInput, type ResolvedBotProtectionConfig } from
 import type { BrandingConfig } from './host/branding.js';
 import type { ResolveGeo } from './host/geo.js';
 import { type AuthMessages, type I18nConfig } from './host/i18n.js';
+import { type OtpLoginConfigInput, type ResolvedOtpLoginConfig } from './host/otp_login.js';
 import type { SudoMethod } from './host/sudo/types.js';
 import { type ResolvedTrustedDevicesConfig, type TrustedDevicesConfigInput } from './host/trusted_device.js';
 import type { PatStore } from './pat/pat_store.js';
@@ -40,6 +41,12 @@ export interface MailHooks {
         email: string;
         magicUrl: string;
         token: string;
+        /**
+         * Código OTP de login, presente APENAS quando `login.otp.enabled` está
+         * ligado. O host pode montar o próprio e-mail com link E código. Ausente no
+         * fluxo só-magic-link (back-compat).
+         */
+        code?: string;
     }) => Promise<void>;
     /**
      * Envia o link de CONFIRMAÇÃO DE IDENTIDADE (sudo). Distinto de
@@ -191,6 +198,13 @@ export interface ResolvedRateLimitConfig {
      * afrouxar — o ponto é separar a CONTAGEM, não o teto.
      */
     sudo: RateLimitBucket;
+    /**
+     * Bucket da verificação de código OTP de login (`/auth/interaction/:uid/otp-verify`),
+     * keyed por IP. MAIS APERTADO que o login (5/min vs 10/min): um código de 6
+     * dígitos é adivinhável, então o teto por IP é a primeira barreira anti-brute
+     * force ANTES do lockout por interaction (contador persistido no slot do código).
+     */
+    otpLogin: RateLimitBucket;
     store?: string;
 }
 export declare function resolveRateLimit(input?: RateLimitConfigInput): ResolvedRateLimitConfig;
@@ -440,9 +454,17 @@ export declare function resolveAuthMethodsConfig(input?: AuthMethodsConfigInput)
 export interface LoginConfigInput {
     /** Exige e-mail verificado para autenticar (senha/magic link/passkey-first). Default: false. */
     requireVerifiedEmail?: boolean;
+    /**
+     * Login por OTP (código digitável) — extensão do magic link. Quando ligado, o
+     * MESMO e-mail passa a carregar link E código, os dois completando a mesma
+     * interaction. Default: **desligado** (opt-in; sem a config o comportamento é
+     * idêntico ao de antes, e-mail idêntico). Ver `host/otp_login.ts`.
+     */
+    otp?: OtpLoginConfigInput;
 }
 export interface ResolvedLoginConfig {
     requireVerifiedEmail: boolean;
+    otp: ResolvedOtpLoginConfig;
 }
 export declare function resolveLogin(input?: LoginConfigInput): ResolvedLoginConfig;
 /**

package/build/src/define_config.js

@@ -4,6 +4,7 @@ import { composeAuditSink, resolveEvents } from './events/dispatcher.js';
 import { resolveBotProtection, } from './host/bot_protection.js';
 import { deriveLockedSettingKeys } from './host/config_locks.js';
 import { resolveMessages } from './host/i18n.js';
+import { resolveOtpLoginConfig, } from './host/otp_login.js';
 import { edgeRenderer } from './host/renderers/edge_renderer.js';
 import { resolveTrustedDevices, } from './host/trusted_device.js';
 import { generateJwks } from './keys/jwks_manager.js';
@@ -17,6 +18,8 @@ const RATE_LIMIT_DEFAULTS = {
     adminIp: { points: 30, duration: '1 min' },
     // Mesmos limites do login, bucket separado — ver `ResolvedRateLimitConfig.sudo`.
     sudo: { points: 10, duration: '1 min' },
+    // Mais apertado que o login — verificação de código adivinhável.
+    otpLogin: { points: 5, duration: '1 min' },
 };
 export function resolveRateLimit(input) {
     const enabled = input?.enabled ?? true;
@@ -26,6 +29,7 @@ export function resolveRateLimit(input) {
         introspection: RATE_LIMIT_DEFAULTS.introspection,
         adminIp: RATE_LIMIT_DEFAULTS.adminIp,
         sudo: RATE_LIMIT_DEFAULTS.sudo,
+        otpLogin: RATE_LIMIT_DEFAULTS.otpLogin,
         store: input?.store,
     };
 }
@@ -119,6 +123,7 @@ export function resolveAuthMethodsConfig(input) {
 export function resolveLogin(input) {
     return {
         requireVerifiedEmail: input?.requireVerifiedEmail ?? false,
+        otp: resolveOtpLoginConfig(input?.otp),
     };
 }
 export function resolveRegistration(input) {

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;

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

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

@@ -30,6 +30,12 @@ export interface AuthThrottles {
      * orçamentos não poderem se consumir.
      */
     sudo: ThrottleMiddleware;
+    /**
+     * Throttle da verificação de código OTP de login, keyed por IP em bucket
+     * PRÓPRIO (`authkit_otp_login`) e mais apertado que o `login`. Primeira barreira
+     * anti-brute-force do código adivinhável, ANTES do lockout por interaction.
+     */
+    otpLogin: ThrottleMiddleware;
 }
 /**
  * Service do `@adonisjs/limiter` resolvido de forma preguiçosa. Tipado como `any`

package/build/src/host/rate_limit.js

@@ -96,5 +96,8 @@ export function createAuthThrottles(config) {
         // mesmo vindo do mesmo IP. Sem `usingKey` próprio de propósito: inventar uma
         // key aqui seria mudar o EIXO da contagem, e o eixo certo continua sendo o IP.
         sudo: buildThrottle('authkit_sudo', config.sudo, config.store),
+        // Verificação de código OTP: keyed por IP (default), bucket próprio e mais
+        // apertado que o login. O namespace do nome mantém a contagem separada.
+        otpLogin: buildThrottle('authkit_otp_login', config.otpLogin, config.store),
     };
 }

package/build/src/host/register_auth_host.js

@@ -256,6 +256,11 @@ export function registerAuthHost(router, opts = {}) {
         if (throttles)
             route.use([throttles.sudo]);
     };
+    // Bucket PRÓPRIO da verificação de código OTP: mais apertado que o login, por IP.
+    const withOtpLogin = (route) => {
+        if (throttles)
+            route.use([throttles.otpLogin]);
+    };
     // ─── Assets estáticos do host-kit (públicos, sem autenticação) ─────────────
     // Bundle do @simplewebauthn/browser servido pelo próprio app, no lugar do
     // import de CDN público que as views de login/MFA/confirm faziam.
@@ -286,6 +291,9 @@ export function registerAuthHost(router, opts = {}) {
     // Magic link (passwordless): POST emite (throttled), GET consome o token do link.
     withLogin(router.post('/auth/interaction/:uid/magic', [C.interaction, 'magicLinkRequest']));
     router.get('/auth/interaction/:uid/magic', [C.interaction, 'magicLinkConsume']);
+    // Login por OTP (código digitável): verifica o código no bucket dedicado
+    // `authkit_otp_login` (por IP, mais apertado que o login).
+    withOtpLogin(router.post('/auth/interaction/:uid/otp-verify', [C.interaction, 'otpVerify']));
     router.post('/auth/interaction/:uid/consent', [C.interaction, 'consent']);
     router.get('/auth/interaction/:uid/switch', [C.interaction, 'switchIdentifier']);
     // OTP unlock: link enviado por e-mail quando o fator TOTP/recovery é travado.

package/package.json

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