@adonis-agora/authkit-server 0.50.0 → 0.51.0

package/build/host/views/login.edge

@@ -190,14 +190,19 @@
         @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)
+        @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') }}"

package/build/src/define_config.d.ts

@@ -47,6 +47,13 @@ export interface MailHooks {
          * 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

package/build/src/host/controllers/interaction_controller.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';
@@ -612,6 +613,10 @@ export default class AuthInteractionController {
         // 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 ip = ctx.request.ip?.() ?? null;
             const clientId = details.params.client_id ?? null;
@@ -644,10 +649,10 @@ export default class AuthInteractionController {
                 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, code });
+                    await cfg.mail.onMagicLink({ email, magicUrl, token: issued.token, code, channel });
                 }
                 else {
-                    await sendMagicLinkEmail(ctx, { email, magicUrl, code });
+                    await sendMagicLinkEmail(ctx, { email, magicUrl, code, channel });
                 }
             }
         }
@@ -662,6 +667,10 @@ export default class AuthInteractionController {
             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),
         });
     }
     /**
@@ -748,6 +757,9 @@ export default class AuthInteractionController {
         }
         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,
         });
@@ -762,6 +774,7 @@ export default class AuthInteractionController {
             brand,
             magicLinkSent: true,
             otpEnabled: true,
+            magicChannel: magicChannelProp(channel),
             otpError: translate(cfg.messages, messageKey),
         });
         if (result.status === 'ok') {

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

@@ -63,6 +63,7 @@ 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

package/build/src/host/default_mailer.js

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

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

@@ -24,10 +24,17 @@ interface EmailTemplateInput {
     heading: string;
     /** Parágrafo de introdução (texto puro, será escapado). */
     intro: string;
-    /** Rótulo do botão de CTA. */
-    ctaLabel: string;
-    /** URL do CTA. */
-    ctaUrl: string;
+    /**
+     * Rótulo do botão de CTA. Opcional junto de `ctaUrl`: e-mails "só código"
+     * (login por OTP com `channel: 'code'`) não têm botão nem link.
+     */
+    ctaLabel?: string;
+    /**
+     * URL do CTA. Quando ausente, o e-mail é renderizado SEM botão e SEM o
+     * fallback de link (usado no e-mail "só código"). Todos os callers históricos
+     * passam este campo — byte-parity preservado.
+     */
+    ctaUrl?: string;
     /** Linha auxiliar abaixo do botão (ex.: validade do link). */
     footnote?: string;
     /** Texto que precede o link de fallback (i18n). Default em inglês. */

package/build/src/host/email_templates.js

@@ -51,11 +51,13 @@ export function renderTransactionalEmail(input) {
 <tr><td style="padding:32px 28px 8px;">
 <h1 style="margin:0 0 12px;font-size:20px;line-height:1.3;color:#111827;">${esc(input.heading)}</h1>
 <p style="margin:0 0 24px;font-size:15px;line-height:1.6;color:#374151;">${esc(input.intro)}</p>
-${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>
+${codeBlock}${input.ctaUrl
+        ? `<table role="presentation" cellpadding="0" cellspacing="0"><tr><td style="border-radius:8px;background:${esc(accent)};">
+<a href="${esc(input.ctaUrl)}" style="display:inline-block;padding:12px 24px;font-size:15px;font-weight:600;color:#ffffff;text-decoration:none;border-radius:8px;">${esc(input.ctaLabel ?? '')}</a>
+</td></tr></table>`
+        : ''}
 ${input.footnote ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(input.footnote)}</p>` : ''}
-<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(linkFallback)}<br><a href="${esc(input.ctaUrl)}" style="color:${esc(accent)};word-break:break-all;">${esc(input.ctaUrl)}</a></p>
+${input.ctaUrl ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b7280;">${esc(linkFallback)}<br><a href="${esc(input.ctaUrl)}" style="color:${esc(accent)};word-break:break-all;">${esc(input.ctaUrl)}</a></p>` : ''}
 </td></tr>
 <tr><td style="padding:24px 28px 28px;border-top:1px solid #f3f4f6;">
 <p style="margin:0;font-size:12px;line-height:1.5;color:#9ca3af;">${esc(company)} ${year}</p>
@@ -70,8 +72,7 @@ ${input.footnote ? `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;col
         '',
         input.intro,
         ...(input.code ? ['', `${codeLabel} ${input.code}`] : []),
-        '',
-        `${input.ctaLabel}: ${input.ctaUrl}`,
+        ...(input.ctaUrl ? ['', `${input.ctaLabel}: ${input.ctaUrl}`] : []),
         ...(input.footnote ? ['', input.footnote] : []),
         '',
         `— ${company}`,

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

@@ -518,6 +518,9 @@ export declare const DEFAULT_MESSAGES: {
     'mail.magic_link.cta': string;
     'mail.magic_link.fallback': string;
     'mail.magic_link.code_label': string;
+    'mail.magic_link.code_subject': string;
+    'mail.magic_link.code_intro': string;
+    'mail.magic_link.code_only_label': string;
     'mail.new_login.subject': string;
     'mail.new_login.heading': string;
     'mail.new_login.intro': string;
@@ -1219,6 +1222,9 @@ export declare const PT_BR_MESSAGES: {
     'mail.magic_link.cta': string;
     'mail.magic_link.fallback': string;
     'mail.magic_link.code_label': string;
+    'mail.magic_link.code_subject': string;
+    'mail.magic_link.code_intro': string;
+    'mail.magic_link.code_only_label': string;
     'mail.new_login.subject': string;
     'mail.new_login.heading': string;
     'mail.new_login.intro': string;

package/build/src/host/i18n.js

@@ -558,6 +558,10 @@ export const DEFAULT_MESSAGES = {
     'mail.magic_link.cta': 'Sign in',
     'mail.magic_link.fallback': 'If you did not request this, you can ignore this email.',
     'mail.magic_link.code_label': 'Or enter this code to sign in:',
+    // E-mail "só código" (login choose-first com channel: 'code'): sem botão/link.
+    'mail.magic_link.code_subject': 'Your login code',
+    'mail.magic_link.code_intro': 'Use the code below to sign in. It expires shortly and can be used once.',
+    'mail.magic_link.code_only_label': 'Enter this code to sign in:',
     'mail.new_login.subject': 'New login to your account',
     'mail.new_login.heading': 'New login detected',
     'mail.new_login.intro': 'We detected a new login to your account.',
@@ -1335,6 +1339,10 @@ export const PT_BR_MESSAGES = {
     'mail.magic_link.cta': 'Entrar',
     'mail.magic_link.fallback': 'Se você não solicitou isso, pode ignorar este e-mail.',
     'mail.magic_link.code_label': 'Ou digite este código para entrar:',
+    // E-mail "só código" (login choose-first com channel: 'code'): sem botão/link.
+    'mail.magic_link.code_subject': 'Seu código de login',
+    'mail.magic_link.code_intro': 'Use o código abaixo para entrar. Ele expira em instantes e serve para um único acesso.',
+    'mail.magic_link.code_only_label': 'Digite este código para entrar:',
     'mail.new_login.subject': 'Novo login na sua conta',
     'mail.new_login.heading': 'Novo login detectado',
     'mail.new_login.intro': 'Detectamos um novo login na sua conta.',

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

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

package/build/src/host/login_channel.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.50.0",
+  "version": "0.51.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",