@adonis-agora/authkit-server 0.49.0 → 0.51.0

package/build/host/views/login.edge

@@ -190,9 +190,32 @@
         @end
       @end
 
-      {{-- Passwordless: confirmação de magic link enviado (anti-enumeração). --}}
+      {{-- Passwordless: confirmação de magic link enviado (anti-enumeração).
+           `magicChannel` (choose-first) escolhe a sub-view: 'code' = só o campo de
+           código, 'link' = só o aviso de link, 'both'/ausente = ambos (histórico). --}}
       @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>
+        @if(magicChannel !== 'code')
+          <p class="mt-4 rounded-lg bg-green-50 px-3 py-2 text-sm text-green-700">{{ t('login.magic_link_sent') }}</p>
+        @end
+
+        {{-- Login por OTP: campo de código digitável (mesmo e-mail carrega link E código). --}}
+        @if(otpEnabled && magicChannel !== 'link')
+          <form method="POST" action="/auth/interaction/{{ uid }}/otp-verify" class="mt-4">
+            <input type="hidden" name="_csrf" value="{{ csrfToken }}">
+            <input type="hidden" name="channel" value="code">
+            <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,19 @@ 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;
+        /**
+         * Canal escolhido no seletor "choose-first": `'code'` = o host deveria
+         * renderizar SÓ o código, `'link'` = SÓ o link. Ausente = ambos (histórico).
+         * Puramente de superfície — os dois tokens continuam emitidos co-locados;
+         * hosts existentes simplesmente ignoram este campo (back-compat).
+         */
+        channel?: 'code' | 'link';
     }) => Promise<void>;
     /**
      * Envia o link de CONFIRMAÇÃO DE IDENTIDADE (sudo). Distinto de
@@ -191,6 +205,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 +461,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';
@@ -7,6 +7,7 @@ import { sendMagicLinkEmail } from '../default_mailer.js';
 import { sendOtpUnlockEmail } from '../default_mailer.js';
 import { translate } from '../i18n.js';
 import { attemptPasswordLogin, isEmailUnverifiedBlock } from '../login_attempt.js';
+import { magicChannelProp, normalizeLoginChannel } from '../login_channel.js';
 import { notifyLoginSuccess } from '../login_notify.js';
 import { createOtpLockout, generateOtpUnlockToken, rawToDbOtpUnlockToken, resolveEffectiveOtpLockout, } from '../otp_lockout.js';
 import { RuntimeSettings, resolveRuntimeSettings } from '../runtime_settings.js';
@@ -609,23 +610,49 @@ 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);
+        // Seletor "choose-first": o host pode POSTar `channel=code|link` para pedir que
+        // o e-mail e a tela mostrem SÓ aquele método. Ausente/ inválido = both (histórico).
+        // NÃO condiciona a emissão de token — os dois continuam saindo co-locados.
+        const channel = normalizeLoginChannel(ctx.request.input('channel'));
         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, channel });
                 }
                 else {
-                    await sendMagicLinkEmail(ctx, { email, magicUrl });
+                    await sendMagicLinkEmail(ctx, { email, magicUrl, code, channel });
                 }
             }
         }
@@ -639,6 +666,11 @@ export default class AuthInteractionController {
             account: null,
             brand,
             magicLinkSent: true,
+            otpEnabled,
+            // Prop da tela: qual sub-view do estado `magicLinkSent` mostrar —
+            // 'code' (só o campo de código), 'link' (só o aviso de link) ou 'both'
+            // (ambos, quando o host não escolheu canal). Back-compat: ausente = 'both'.
+            magicChannel: magicChannelProp(channel),
         });
     }
     /**
@@ -700,6 +732,117 @@ 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);
+        // Mantém a sub-view do seletor no re-render de erro (o form de código pode
+        // POSTar `channel=code`). Ausente = both (histórico).
+        const channel = normalizeLoginChannel(ctx.request.input('channel'));
+        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,
+            magicChannel: magicChannelProp(channel),
+            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,8 @@ export declare function sendNewDeviceLoginEmail(ctx: HttpContext, data: {
 export declare function sendMagicLinkEmail(ctx: HttpContext, data: {
     email: string;
     magicUrl: string;
+    code?: string;
+    channel?: 'code' | 'link';
 }): Promise<void>;
 /**
  * Envia o e-mail de aviso de segurança ao e-mail ATUAL quando uma troca de