@adonis-agora/authkit-server 0.53.0 → 0.55.0

package/build/src/host/register_auth_host.js

@@ -1,28 +1,43 @@
 import { resolveRateLimit } from '../define_config.js';
 import { accountHome } from './account_home.js';
 import { getAccountLoginUrl, setAccountLoginUrl } from './account_login_url.js';
-import { accountPath, joinAccountPath, setAccountPaths, } from './account_paths.js';
+import { accountPath, accountPathsMap, accountPrefix, joinAccountPath, setAccountPaths, } from './account_paths.js';
 import { resolveAccountRoles } from './account_roles.js';
 import { adminApiGuard } from './admin_api/admin_api_guard.js';
 import { normalizeAdminApiPrefix, normalizeAdminPrefix, setAdminApiPrefix, setAdminPrefix, } from './admin_prefix.js';
-import { getAuthHostConfig } from './auth_host_config.js';
+import { getAuthHostConfig, markAuthHostAutoMounted, wasAuthHostAutoMounted, } from './auth_host_config.js';
 import { ACCOUNT_SESSION_KEY } from './middleware/account_auth.js';
 import { createAuthThrottles } from './rate_limit.js';
 import { resolveRuntimeSettings } from './runtime_settings.js';
 import { resolveEffectiveSessionPolicy } from './runtime_toggles.js';
+import { magicLink as sudoMagicLink } from './sudo/methods/magic_link.js';
 import { passkey as sudoPasskey } from './sudo/methods/passkey.js';
 import { password as sudoPassword } from './sudo/methods/password.js';
 import { completeSudo, fail, guardSudoRoutes, setMountedSudoMethods, sudoContextFrom, } from './sudo/runtime.js';
 /**
- * Métodos de sudo montados quando o host não passa `sudoMethods` —
- * comportamento histórico (senha + passkey).
+ * Métodos de sudo cujas ROTAS são montadas quando o host não passa
+ * `sudoMethods`.
  *
- * PONTO ÚNICO. A tela não tem mais uma cópia desta lista: sem
- * `config.sudo.methods`, `configuredSudoMethods` cai no que FOI MONTADO, ou
- * seja, no resultado do `??` abaixo. Duas listas de default é como os dois
- * lados divergiam.
+ * `magicLink()` entra aqui, e a lista deixou de ser o histórico
+ * `[password, passkey]`, porque os dois históricos exigem uma credencial
+ * PREVIAMENTE CADASTRADA. Num host passwordless não existe nenhuma: o usuário
+ * não tem senha, não tem passkey — e cadastrar passkey exige sudo. Deadlock
+ * fechado, e era o DEFAULT. O `oidcStepUp` não pode entrar (exige uma URL do
+ * host), então o magic link de sudo é o único método sem credencial prévia que
+ * a lib consegue montar sozinha.
+ *
+ * MONTAR NÃO É OFERECER. Esta lista decide apenas quais ENDPOINTS existem; o
+ * que a tela oferece e o que os handlers aceitam é derivado do config resolvido,
+ * em `sudo/runtime.ts` (`derivedSudoMethods`) — um host COM senha continua
+ * recebendo exatamente `[password, passkey]`, e o endpoint do magic link fica
+ * montado mas inerte. Não é possível decidir a oferta aqui: a montagem acontece
+ * antes de o config (lazy) resolver, e `authMethods` vive no config.
+ *
+ * PONTO ÚNICO. A tela não tem uma cópia desta lista: sem `config.sudo.methods`,
+ * `configuredSudoMethods` cai no que FOI MONTADO (derivado). Duas listas de
+ * default é como os dois lados divergiam.
  */
-const SUDO_METHOD_DEFAULTS = [sudoPassword(), sudoPasskey()];
+const SUDO_METHOD_DEFAULTS = [sudoPassword(), sudoPasskey(), sudoMagicLink()];
 /** Chave da sessão Adonis que registra o timestamp da última atividade (idle timeout). */
 export const ACCOUNT_LAST_SEEN_KEY = 'authkit_last_seen';
 /**
@@ -190,37 +205,123 @@ const C = {
 /**
  * Monta todas as rotas do host-kit do Authorization Server numa chamada.
  * Substitui registerOidcRoutes + o hand-wiring do start/routes.ts do host.
+ *
+ * ── A REGRA DE PRECEDÊNCIA (config × argumento) ─────────────────────────────
+ *
+ * 1. **Argumento omitido HERDA do config.** `registerAuthHost(router)` é
+ *    totalmente config-driven; `registerAuthHost(router, { mountPath: '/sso' })`
+ *    troca o mountPath e herda TODO o resto. Omitir uma chave significa "usa o
+ *    config", nunca "usa nada" — é o que dispensa repetir `sudo.methods` no
+ *    `start/routes.ts`.
+ *
+ * 2. **Chaves ESTRUTURAIS: o argumento vence.** `mountPath`, os prefixos
+ *    (`admin.prefix`, `adminApi.prefix`, `accountRoutes.prefix`), os segmentos
+ *    de tela, `account` (quais telas montar) e `accountLoginUrl`. São decisões
+ *    do ponto de chamada por natureza, e a forma de função é estritamente mais
+ *    expressiva (dá para montar duas vezes sob dois prefixos — nenhum config
+ *    expressa isso).
+ *
+ * 3. **Chaves de POLÍTICA: o config vence, e trava.** `social`, `rateLimit`,
+ *    `sudoMethods` e o liga/desliga de `admin`/`adminApi` decidem o que é
+ *    PERMITIDO. Quando o `defineConfig` as declara, o argumento NÃO as altera —
+ *    senão o `config/authkit.ts` deixa de ser auditável e seria preciso ler o
+ *    `start/routes.ts` de cada app para saber o que está valendo. Mesma regra
+ *    (e mesma derivação) de `defineConfig({ authMethods })`, que já fixa os
+ *    métodos de login contra o runtime. Ver `deriveLockedRouteOptions`.
+ *    A divergência NÃO é silenciosa: sai um `console.warn` nomeando a chave e
+ *    a chave aparece em `AuthHostRouteMap.overriddenByConfig`.
+ *
+ * Devolve o {@link AuthHostRouteMap} resolvido — entregue-o ao frontend em vez
+ * de hardcodar `href`s.
  */
 export function registerAuthHost(router, opts = {}) {
     // Config resolvido (stashado no boot do provider) — fonte única; `opts` só faz
-    // OVERRIDE. Elimina o drift: o consumidor pode chamar `registerAuthHost(router)`
-    // e mountPath/social/rateLimit/admin/adminApi vêm do config/authkit.ts.
+    // OVERRIDE das chaves ESTRUTURAIS. Elimina o drift: o consumidor pode chamar
+    // `registerAuthHost(router)` e tudo vem do config/authkit.ts.
     // Fallback p/ defaults quando o stash não está disponível (ex.: testes sem boot).
     const hostCfg = getAuthHostConfig();
-    const mount = opts.mountPath ?? hostCfg?.mountPath ?? '/oidc';
-    // social: opt explícito > config. admin/adminApi: opt explícito > (config.enabled → monta).
-    const social = opts.social ?? hostCfg?.social;
-    const adminOpt = opts.admin ?? (hostCfg?.adminEnabled ? true : undefined);
-    const adminApiOpt = opts.adminApi ?? (hostCfg?.adminApiEnabled ? true : undefined);
+    // `config.routes` já montou tudo no boot do provider. Registrar de novo
+    // duplicaria CADA rota — e duas rotas com o mesmo nome derrubam o boot do
+    // AdonisJS com um `RuntimeException` que não diz de onde veio. Falha aqui,
+    // alto e com a saída explícita.
+    if (wasAuthHostAutoMounted()) {
+        throw new Error('authkit: registerAuthHost() foi chamado depois de `routes` no config/authkit.ts já ter montado as rotas automaticamente — o duplo registro derruba o boot ("route name already exists"). Escolha UM dos dois: remova a chamada do start/routes.ts, ou ponha `routes: false` no defineConfig e configure tudo pela chamada.');
+    }
+    // Defaults ESTRUTURAIS declarados em `config.routes` — o argumento ainda vence.
+    const routesCfg = hostCfg?.routes;
+    // Chaves de POLÍTICA travadas pelo defineConfig (ver o item 3 acima).
+    const locked = new Set(hostCfg?.lockedRouteOptions ?? []);
+    const overriddenByConfig = [];
+    /**
+     * Uma chave de política travada IGNORA o argumento e reporta. Não silencia:
+     * um argumento sem efeito que ninguém percebe é como o drift começa.
+     */
+    const isLocked = (key, passed) => {
+        if (!locked.has(key))
+            return false;
+        if (passed) {
+            overriddenByConfig.push(key);
+            console.warn(`authkit: registerAuthHost(router, { ${key} }) foi IGNORADO — "${key}" é uma opção de política e está definida no defineConfig(), que vence (o config precisa ser auditável sem ler o start/routes.ts). Remova-a da chamada, ou remova-a do config para controlá-la aqui.`);
+        }
+        return true;
+    };
+    const mount = opts.mountPath ?? routesCfg?.mountPath ?? hostCfg?.mountPath ?? '/oidc';
+    // social — POLÍTICA: decide se existe um caminho de autenticação a mais.
+    const social = isLocked('social', opts.social !== undefined)
+        ? hostCfg?.social
+        : (opts.social ?? routesCfg?.social ?? hostCfg?.social);
+    // admin/adminApi — o LIGA/DESLIGA é política (config vence); o PREFIXO é
+    // estrutural (o argumento vence). Por isso os dois eixos são resolvidos
+    // separadamente em vez de a opção inteira ser um bloco só.
+    const enableFrom = (v) => v === undefined ? undefined : v !== false;
+    const prefixFrom = (...vs) => {
+        for (const v of vs)
+            if (typeof v === 'object' && v?.prefix)
+                return v.prefix;
+        return undefined;
+    };
+    // `{ prefix: '/painel' }` mexe SÓ no eixo estrutural: só há divergência a
+    // reportar quando a intenção de liga/desliga do argumento CONTRADIZ o config.
+    const contradicts = (arg, configEnabled) => {
+        const intent = enableFrom(arg);
+        return intent !== undefined && intent !== (configEnabled ?? false);
+    };
+    const adminEnabled = isLocked('admin', contradicts(opts.admin, hostCfg?.adminEnabled))
+        ? (hostCfg?.adminEnabled ?? false)
+        : (enableFrom(opts.admin) ?? enableFrom(routesCfg?.admin) ?? hostCfg?.adminEnabled ?? false);
+    const adminPrefixOpt = prefixFrom(opts.admin, routesCfg?.admin);
+    const adminOpt = adminEnabled ? { prefix: adminPrefixOpt } : undefined;
+    const adminApiEnabled = isLocked('adminApi', contradicts(opts.adminApi, hostCfg?.adminApiEnabled))
+        ? (hostCfg?.adminApiEnabled ?? false)
+        : (enableFrom(opts.adminApi) ??
+            enableFrom(routesCfg?.adminApi) ??
+            hostCfg?.adminApiEnabled ??
+            false);
+    const adminApiPrefixOpt = prefixFrom(opts.adminApi, routesCfg?.adminApi);
+    const adminApiOpt = adminApiEnabled
+        ? { prefix: adminApiPrefixOpt }
+        : undefined;
     // Prefixo/segmentos configuráveis do console de conta — persiste no singleton
     // de processo ANTES de qualquer construção de rota/closure, para que o registro
     // de rotas, os guards, os controllers, os e-mails e as views leiam o mesmo
     // valor. Top-level de propósito (vale mesmo com `account: false`): as rotas de
     // sudo e a JSON API respeitam o prefixo. Ausente → default `/account/*`
     // (back-compat). Ver `account_paths.ts`.
-    if (opts.accountRoutes !== undefined) {
-        setAccountPaths(opts.accountRoutes);
+    const accountRoutesOpt = opts.accountRoutes ?? routesCfg?.accountRoutes;
+    if (accountRoutesOpt !== undefined) {
+        setAccountPaths(accountRoutesOpt);
     }
     // Destino do redirect de "faça login" — persiste no singleton de processo para
     // que os guards (closures de tempo de registro), o middleware, os controllers e
     // as views leiam o mesmo valor. Só quando a opção foi passada (senão deriva de
     // `accountPath('login')` — back-compat).
-    if (opts.accountLoginUrl !== undefined) {
-        setAccountLoginUrl(opts.accountLoginUrl);
+    const accountLoginUrlOpt = opts.accountLoginUrl ?? routesCfg?.accountLoginUrl;
+    if (accountLoginUrlOpt !== undefined) {
+        setAccountLoginUrl(accountLoginUrlOpt);
     }
     // Montagem por tela do console de conta. `undefined` → tudo montado;
     // `false` → nada; objeto → cada flag ausente default `true`.
-    const accountOpt = opts.account;
+    const accountOpt = opts.account ?? routesCfg?.account;
     const mountScreen = (key) => {
         if (accountOpt === false)
             return false;
@@ -234,10 +335,21 @@ export function registerAuthHost(router, opts = {}) {
     const mountSecurity = mountScreen('security');
     const mountMfa = mountScreen('mfa');
     const mountApps = mountScreen('apps');
+    // Ids dos métodos de sudo efetivamente montados — preenchido dentro do grupo
+    // do console de conta (a callback do `.group()` roda de forma síncrona) e
+    // devolvido no `AuthHostRouteMap`.
+    let mountedSudoIds = [];
     // Throttles opt-in (anti-brute-force). `undefined` quando rate-limit desligado.
-    const resolvedRateLimit = opts.rateLimit !== undefined
-        ? resolveRateLimit(opts.rateLimit)
-        : (hostCfg?.rateLimit ?? resolveRateLimit(undefined));
+    // POLÍTICA: `rateLimit: { enabled: false }` num routes.ts desligaria a proteção
+    // anti-brute-force que o config ligou — e o config.rateLimit JÁ trava a setting
+    // de runtime homônima (`deriveLockedSettingKeys`). Travar aqui só fecha o
+    // terceiro caminho para o mesmo valor.
+    const rateLimitOpt = opts.rateLimit ?? routesCfg?.rateLimit;
+    const resolvedRateLimit = isLocked('rateLimit', opts.rateLimit !== undefined)
+        ? (hostCfg?.rateLimit ?? resolveRateLimit(undefined))
+        : rateLimitOpt !== undefined
+            ? resolveRateLimit(rateLimitOpt)
+            : (hostCfg?.rateLimit ?? resolveRateLimit(undefined));
     const throttles = createAuthThrottles(resolvedRateLimit);
     // Helpers: aplicam o middleware de throttle quando presente; senão no-op.
     const withLogin = (route) => {
@@ -413,7 +525,16 @@ export function registerAuthHost(router, opts = {}) {
             completeSudo,
             fail,
         };
-        const sudoMethodsToMount = opts?.sudoMethods ?? SUDO_METHOD_DEFAULTS;
+        // POLÍTICA. `config.sudo.methods` já decide o que a tela OFERECE e o que
+        // os handlers ACEITAM (`isSudoMethodEnabled`); agora decide também o que é
+        // MONTADO. Era a única das três decisões que ficava fora do config, e era
+        // exatamente por isso que o host tinha de manter a lista em DOIS lugares —
+        // divergiram, a tela oferecia um método sem endpoint (404) e escondia um
+        // que funcionava.
+        const sudoMethodsDeclared = isLocked('sudoMethods', opts.sudoMethods !== undefined)
+            ? hostCfg?.sudoMethods
+            : (opts.sudoMethods ?? routesCfg?.sudoMethods ?? hostCfg?.sudoMethods);
+        const sudoMethodsToMount = sudoMethodsDeclared ?? SUDO_METHOD_DEFAULTS;
         for (const method of sudoMethodsToMount) {
             // `guardSudoRoutes` embrulha os handlers que o método registrar, para
             // que `config.sudo.methods` os desabilite de fato mesmo que o método
@@ -434,7 +555,16 @@ export function registerAuthHost(router, opts = {}) {
         // A lista montada é a fonte de verdade dos DOIS lados quando o host não
         // configura `config.sudo.methods`: a tela oferece exatamente isto, e os
         // handlers aceitam exatamente isto.
-        setMountedSudoMethods(sudoMethodsToMount);
+        //
+        // O segundo argumento diz se a lista é a da LIB ou a do HOST, e a
+        // distinção é o que mantém o conserto do deadlock inofensivo: só a lista
+        // de defaults é derivada do config (`derivedSudoMethods`). Uma lista que o
+        // host escreveu — no argumento ou no `config.sudo.methods` — vale ao pé da
+        // letra, em qualquer direção, porque foi ele quem a escreveu.
+        setMountedSudoMethods(sudoMethodsToMount, {
+            fromDefaults: sudoMethodsDeclared === undefined,
+        });
+        mountedSudoIds = sudoMethodsToMount.map((m) => m.id);
         // Organizations (multi-tenancy) — tela `orgs`. Montadas por default;
         // controller retorna 404/403 sem tabelas (capability-probed).
         if (mountOrgs) {
@@ -489,11 +619,16 @@ export function registerAuthHost(router, opts = {}) {
         router.get(`${apiBase}/orgs/:id`, [C.accountApi, 'showOrg']);
     })
         .use([accountGuard]);
+    // Prefixos resolvidos dos consoles — `null` quando o grupo não foi montado.
+    // Compõem o `AuthHostRouteMap` devolvido no fim.
+    let resolvedAdminPrefix = null;
+    let resolvedAdminApiPrefix = null;
     // Console admin (do config.admin.enabled ou opts). Protegido pelo adminGuard (sessão + role global).
     if (adminOpt) {
         // Resolve o prefixo: `true` → '/admin' (default); objeto → usa prefix fornecido.
         const rawPrefix = typeof adminOpt === 'object' && adminOpt.prefix ? adminOpt.prefix : '/admin';
         const ap = normalizeAdminPrefix(rawPrefix);
+        resolvedAdminPrefix = ap;
         // Persiste no singleton de processo para que controllers e views usem o mesmo prefixo.
         setAdminPrefix(ap);
         router
@@ -586,6 +721,7 @@ export function registerAuthHost(router, opts = {}) {
             ? adminApiOpt.prefix
             : '/api/authkit/v1';
         const aap = normalizeAdminApiPrefix(rawApiPrefix);
+        resolvedAdminApiPrefix = aap;
         // Persiste no singleton de processo para que o SDK remoto e outros consumidores
         // usem o mesmo prefixo sem precisar receber a opção.
         setAdminApiPrefix(aap);
@@ -648,4 +784,64 @@ export function registerAuthHost(router, opts = {}) {
             // O `withApiThrottle` (introspection, por token) continua como camada adicional.
             .use(throttles ? [throttles.adminIp, adminApiGuard] : [adminApiGuard]);
     }
+    // ─── Mapa resolvido (R4) ───────────────────────────────────────────────────
+    // Lido DEPOIS de todo o registro: `accountPath()`/`accountPrefix()` já
+    // refletem o `accountRoutes` aplicado no topo, e os prefixos de console já
+    // foram normalizados. É este objeto que o host entrega ao frontend em vez de
+    // hardcodar `href`s — o que faltava para um override de path ser um recurso
+    // inteiro, e não só metade (certo no servidor, errado na UI).
+    return {
+        mountPath: mount,
+        account: {
+            prefix: accountPrefix(),
+            api: apiBase,
+            paths: accountPathsMap(),
+            loginUrl: getAccountLoginUrl(),
+            screens: {
+                login: mountLogin,
+                tokens: mountTokens,
+                orgs: mountOrgs,
+                security: mountSecurity,
+                mfa: mountMfa,
+                apps: mountApps,
+            },
+        },
+        admin: resolvedAdminPrefix ? { prefix: resolvedAdminPrefix } : null,
+        adminApi: resolvedAdminApiPrefix ? { prefix: resolvedAdminApiPrefix } : null,
+        names: {
+            webauthnAsset: 'authkit.assets.webauthn',
+            oidcWildcard: 'authkit.oidc.wildcard',
+            oidcRoot: 'authkit.oidc.root',
+            ...(resolvedAdminPrefix
+                ? {
+                    consoleAssets: 'authkit_console_assets',
+                    consoleRoot: 'authkit_console_root',
+                    consoleShell: 'authkit_console_shell',
+                }
+                : {}),
+        },
+        sudoMethods: mountedSudoIds,
+        overriddenByConfig,
+    };
+}
+/**
+ * Auto-montagem a partir de `config.routes` (R1). Chamada UMA vez pelo
+ * `boot()` do provider.
+ *
+ * O CAMINHO AUTOMÁTICO É O CAMINHO MANUAL: chama literalmente
+ * `registerAuthHost`, sem nenhuma segunda implementação. Toda a resolução
+ * (herança do config, precedência política × estrutural, mapa de retorno) é a
+ * mesma — duas implementações de um comportamento sempre divergem.
+ *
+ * Não recebe opções: os defaults ESTRUTURAIS vêm de `config.routes` pelo stash
+ * (`AuthHostRuntimeConfig.routes`), pelo mesmo caminho que uma chamada manual
+ * os leria.
+ *
+ * @internal
+ */
+export function autoMountAuthHost(router) {
+    const map = registerAuthHost(router);
+    // Depois, nunca antes: `registerAuthHost` LANÇA quando já houve auto-mount.
+    markAuthHostAutoMounted();
+    return map;
 }

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

@@ -179,3 +179,19 @@ export declare class RuntimeSettings implements SettingsCapability {
  * ```
  */
 export declare function resolveRuntimeSettings(ctx: HttpContext): Promise<RuntimeSettings | null>;
+/**
+ * Variante NON-NULL de {@link resolveRuntimeSettings}: quando a resolução falha
+ * (DB ausente, serviço não registrado), devolve um {@link RuntimeSettings} no-op
+ * cujo probe de tabela lança — logo `hasTable()` vira false e TODA leitura
+ * retorna null, fazendo os resolvers caírem no config estático.
+ *
+ * Use esta quando o chamador precisa passar um `SettingsCapability` non-null
+ * adiante (é o caso dos gates de login, que só rodam as checagens de expiração
+ * quando recebem `settings`). Use {@link resolveRuntimeSettings} quando o `null`
+ * carrega semântica própria (ex.: responder `capability_unsupported`).
+ *
+ * Vive AQUI, e não em um controller, porque é sobre runtime settings — o
+ * `interaction_controller` e o `social_controller` a compartilham; uma segunda
+ * cópia da degradação no-op é como as duas divergem.
+ */
+export declare function resolveRuntimeSettingsOrNoop(ctx: HttpContext): Promise<RuntimeSettings>;

package/build/src/host/runtime_settings.js

@@ -305,3 +305,27 @@ export async function resolveRuntimeSettings(ctx) {
         return null;
     }
 }
+/**
+ * Variante NON-NULL de {@link resolveRuntimeSettings}: quando a resolução falha
+ * (DB ausente, serviço não registrado), devolve um {@link RuntimeSettings} no-op
+ * cujo probe de tabela lança — logo `hasTable()` vira false e TODA leitura
+ * retorna null, fazendo os resolvers caírem no config estático.
+ *
+ * Use esta quando o chamador precisa passar um `SettingsCapability` non-null
+ * adiante (é o caso dos gates de login, que só rodam as checagens de expiração
+ * quando recebem `settings`). Use {@link resolveRuntimeSettings} quando o `null`
+ * carrega semântica própria (ex.: responder `capability_unsupported`).
+ *
+ * Vive AQUI, e não em um controller, porque é sobre runtime settings — o
+ * `interaction_controller` e o `social_controller` a compartilham; uma segunda
+ * cópia da degradação no-op é como as duas divergem.
+ */
+export async function resolveRuntimeSettingsOrNoop(ctx) {
+    const rs = await resolveRuntimeSettings(ctx);
+    return (rs ??
+        new RuntimeSettings({
+            table: () => {
+                throw new Error('no-op');
+            },
+        }));
+}

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

@@ -659,6 +659,12 @@ export declare function resolveEffectiveTokenTtl(settings: SettingsCapability, c
  *
  * Controla se o painel de impersonation (RFC 8693 token exchange) é exibido no
  * console admin. FALLBACK: campo ausente cai em `config.admin.impersonation`.
+ *
+ * ESCOPO — governa o PAINEL, não o GRANT. Registrar o grant RFC 8693 no provider
+ * OIDC é decisão de boot de `config.admin.impersonation`; uma setting de runtime
+ * não desregistra rota que nunca foi registrada. Consumida por
+ * `host/admin_console/console_impersonation_controller.ts`, que checa o gate de
+ * config ANTES desta setting — logo o runtime só APERTA, nunca AFROUXA.
  */
 export interface AdminImpersonationSetting {
     enabled?: boolean;
@@ -672,6 +678,10 @@ export interface ResolvedAdminImpersonationSetting {
  *
  * Precedência: setting BD → configDefault → lib default (false).
  * FAIL-SAFE: qualquer erro → configDefault.
+ *
+ * Quando `admin.impersonation` foi declarado no `defineConfig`, a key fica
+ * travada e `settings.getSetting` devolve null (ver `host/config_locks.ts`) —
+ * então este resolver cai no `configDefault` sozinho. Config > runtime.
  */
 export declare function resolveEffectiveAdminImpersonation(settings: SettingsCapability, configDefault?: boolean): Promise<ResolvedAdminImpersonationSetting>;
 /**

package/build/src/host/runtime_toggles.js

@@ -633,6 +633,10 @@ export async function resolveEffectiveTokenTtl(settings, configDefault = {}) {
  *
  * Precedência: setting BD → configDefault → lib default (false).
  * FAIL-SAFE: qualquer erro → configDefault.
+ *
+ * Quando `admin.impersonation` foi declarado no `defineConfig`, a key fica
+ * travada e `settings.getSetting` devolve null (ver `host/config_locks.ts`) —
+ * então este resolver cai no `configDefault` sozinho. Config > runtime.
  */
 export async function resolveEffectiveAdminImpersonation(settings, configDefault = false) {
     const defaults = { enabled: configDefault };

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

@@ -8,7 +8,7 @@
  */
 import type { HttpContext } from '@adonisjs/core/http';
 import type { AuditSink } from '../audit/audit_sink.js';
-import type { MailHooks } from '../define_config.js';
+import type { MailHooks, ResolvedServerConfig } from '../define_config.js';
 import type { SecurityNotificationKind } from './runtime_toggles.js';
 /**
  * Contexto para disparo de uma notificação de segurança.
@@ -32,5 +32,7 @@ export interface SecurityNoticeContext {
  * @param notice      Contexto da notificação
  * @param mailHooks   Hooks de mail do config (opcional)
  * @param audit       Sink de auditoria (opcional)
+ * @param cfg         Config resolvido — só usado para derivar o origin do link
+ *                    do e-mail default (`authkitOrigin`); nunca do `request.host()`.
  */
-export declare function dispatchSecurityNotice(ctx: HttpContext, notice: SecurityNoticeContext, mailHooks: Pick<MailHooks, 'onSecurityNotice'> | undefined, audit: AuditSink | undefined): Promise<void>;
+export declare function dispatchSecurityNotice(ctx: HttpContext, notice: SecurityNoticeContext, mailHooks: Pick<MailHooks, 'onSecurityNotice'> | undefined, audit: AuditSink | undefined, cfg: ResolvedServerConfig): Promise<void>;

package/build/src/host/security_notice_service.js

@@ -17,8 +17,10 @@ import { resolveEffectiveSecurityNotifications } from './runtime_toggles.js';
  * @param notice      Contexto da notificação
  * @param mailHooks   Hooks de mail do config (opcional)
  * @param audit       Sink de auditoria (opcional)
+ * @param cfg         Config resolvido — só usado para derivar o origin do link
+ *                    do e-mail default (`authkitOrigin`); nunca do `request.host()`.
  */
-export async function dispatchSecurityNotice(ctx, notice, mailHooks, audit) {
+export async function dispatchSecurityNotice(ctx, notice, mailHooks, audit, cfg) {
     try {
         // Resolve settings em runtime (fail-safe: sem tabela → defaults habilitados).
         let enabled = true;
@@ -59,7 +61,7 @@ export async function dispatchSecurityNotice(ctx, notice, mailHooks, audit) {
             await mailHooks.onSecurityNotice(noticeData);
         }
         else {
-            await sendSecurityNoticeEmail(ctx, {
+            await sendSecurityNoticeEmail(ctx, cfg, {
                 email: notice.account.email,
                 kind: notice.kind,
                 timestamp,

package/build/src/host/sudo/index.d.ts

@@ -19,6 +19,14 @@ import { password } from './methods/password.js';
  * SEM `config.sudo.methods` não há como divergir: a tela cai na própria lista
  * montada por `registerAuthHost`, a mesma que os handlers aceitam.
  *
+ * E é essa mesma separação que define o que é DEFAULT. `registerAuthHost` monta
+ * `[password, passkey, magicLink]` sem conhecer o config; o config resolvido
+ * decide quais deles valem (`derivedSudoMethods`, em `runtime.ts`): host com
+ * senha fica com `[password, passkey]` (o histórico), host que declarou
+ * `authMethods: { password: false }` fica com `[passkey, magicLink]`. A regra é
+ * UMA função, consultada pelos dois lados — montar não é oferecer, e continuar
+ * não havendo como divergir.
+ *
  * ```ts
  * defineConfig({
  *   sudo: {

package/build/src/host/sudo/index.js

@@ -19,6 +19,14 @@ import { password } from './methods/password.js';
  * SEM `config.sudo.methods` não há como divergir: a tela cai na própria lista
  * montada por `registerAuthHost`, a mesma que os handlers aceitam.
  *
+ * E é essa mesma separação que define o que é DEFAULT. `registerAuthHost` monta
+ * `[password, passkey, magicLink]` sem conhecer o config; o config resolvido
+ * decide quais deles valem (`derivedSudoMethods`, em `runtime.ts`): host com
+ * senha fica com `[password, passkey]` (o histórico), host que declarou
+ * `authMethods: { password: false }` fica com `[passkey, magicLink]`. A regra é
+ * UMA função, consultada pelos dois lados — montar não é oferecer, e continuar
+ * não havendo como divergir.
+ *
  * ```ts
  * defineConfig({
  *   sudo: {

package/build/src/host/sudo/methods/magic_link.d.ts

@@ -36,8 +36,22 @@ export declare function verifySudoLinkToken(c: SudoContext, token: string): bool
 /**
  * Confirmação por link enviado ao e-mail da conta.
  *
- * Depende do hook `mail.onSudoLink`, DISTINTO de `mail.onMagicLink` justamente
- * para que o host não confunda um link que autentica com um que só concede
- * sudo a quem já está logado. Sem o hook, o método fica indisponível.
+ * O hook `mail.onSudoLink` é DISTINTO de `mail.onMagicLink` justamente para que
+ * o host não confunda um link que autentica com um que só concede sudo a quem já
+ * está logado — e continua tendo PRIORIDADE quando declarado.
+ *
+ * SEM O HOOK O MÉTODO SEGUE DISPONÍVEL: o próprio host-kit envia o e-mail pelo
+ * mailer default (`sendSudoLinkEmail`), exatamente como já faz com reset de
+ * senha, verificação de e-mail e o magic link de login. Antes o método se
+ * declarava indisponível sem hook, e num host passwordless isso FECHAVA o
+ * deadlock — sem senha, sem passkey e sem hook não sobrava nenhum método
+ * satisfazível na tela `/account/confirm`, e o usuário ficava trancado fora de
+ * exportar/excluir os próprios dados, do MFA, dos PATs e da troca de e-mail,
+ * inclusive fora do cadastro de passkey que destravaria o resto. Exigir um hook
+ * escrito à mão para que o único método sem credencial prévia funcione é
+ * transformar uma saída de emergência em opt-in.
+ *
+ * A única exigência que resta é a que não tem substituto: a conta precisa ter
+ * e-mail.
  */
 export declare function magicLink(): SudoMethod;

package/build/src/host/sudo/methods/magic_link.js

@@ -1,5 +1,6 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { accountPath } from '../../account_paths.js';
+import { sendSudoLinkEmail } from '../../default_mailer.js';
 import { translate } from '../../i18n.js';
 import { isSudoMethodEnabled } from '../runtime.js';
 /** Token de sudo pendente, guardado na sessão que o pediu. */
@@ -90,17 +91,29 @@ function requestOrigin(ctx) {
 /**
  * Confirmação por link enviado ao e-mail da conta.
  *
- * Depende do hook `mail.onSudoLink`, DISTINTO de `mail.onMagicLink` justamente
- * para que o host não confunda um link que autentica com um que só concede
- * sudo a quem já está logado. Sem o hook, o método fica indisponível.
+ * O hook `mail.onSudoLink` é DISTINTO de `mail.onMagicLink` justamente para que
+ * o host não confunda um link que autentica com um que só concede sudo a quem já
+ * está logado — e continua tendo PRIORIDADE quando declarado.
+ *
+ * SEM O HOOK O MÉTODO SEGUE DISPONÍVEL: o próprio host-kit envia o e-mail pelo
+ * mailer default (`sendSudoLinkEmail`), exatamente como já faz com reset de
+ * senha, verificação de e-mail e o magic link de login. Antes o método se
+ * declarava indisponível sem hook, e num host passwordless isso FECHAVA o
+ * deadlock — sem senha, sem passkey e sem hook não sobrava nenhum método
+ * satisfazível na tela `/account/confirm`, e o usuário ficava trancado fora de
+ * exportar/excluir os próprios dados, do MFA, dos PATs e da troca de e-mail,
+ * inclusive fora do cadastro de passkey que destravaria o resto. Exigir um hook
+ * escrito à mão para que o único método sem credencial prévia funcione é
+ * transformar uma saída de emergência em opt-in.
+ *
+ * A única exigência que resta é a que não tem substituto: a conta precisa ter
+ * e-mail.
  */
 export function magicLink() {
     return {
         id: 'magic-link',
         async isAvailable(c) {
-            if (!c.account?.email)
-                return false;
-            return typeof c.cfg?.mail?.onSudoLink === 'function';
+            return Boolean(c.account?.email);
         },
         async describe() {
             return {
@@ -122,20 +135,31 @@ export function magicLink() {
                 // e sem e-mail não há para onde mandar o link.
                 if (!c.account?.email)
                     return h.fail(c, 'account.confirm.error');
-                // Checado ANTES de emitir: um token emitido sem ninguém para entregá-lo
-                // é lixo na sessão, e a `isAvailable` já prometeu que sem hook o método
-                // não existe.
-                const onSudoLink = c.cfg?.mail?.onSudoLink;
-                if (typeof onSudoLink !== 'function')
-                    return h.fail(c, 'account.confirm.error');
                 const qs = c.returnTo ? `?return_to=${encodeURIComponent(c.returnTo)}` : '';
                 const token = issueSudoLinkToken(c);
                 const path = `${accountPath('confirm')}/magic-link/${token}${qs}`;
                 const origin = requestOrigin(ctx);
+                const sudoUrl = origin ? `${origin}${path}` : path;
+                // ENTREGA. Hook do host quando declarado; senão o mailer default do
+                // host-kit (mesma precedência de todo e-mail da lib). O que NÃO é
+                // opcional é haver uma entrega: um método de sudo que só funciona se o
+                // host escrever um hook não serve de saída de emergência para o host
+                // passwordless, que é justamente quem depende dele.
+                const onSudoLink = c.cfg?.mail?.onSudoLink;
+                let delivered = false;
                 try {
-                    await onSudoLink({ email: c.account.email, sudoUrl: origin ? `${origin}${path}` : path });
+                    if (typeof onSudoLink === 'function') {
+                        await onSudoLink({ email: c.account.email, sudoUrl });
+                        delivered = true;
+                    }
+                    else {
+                        delivered = await sendSudoLinkEmail(ctx, { email: c.account.email, sudoUrl });
+                    }
                 }
                 catch {
+                    delivered = false;
+                }
+                if (!delivered) {
                     // O envio falhou: apaga o pendente. Não é risco de segurança (o
                     // segredo não chegou a lugar nenhum), mas deixá-lo lá invalidaria
                     // silenciosamente um token anterior ainda válido do usuário.