@adonis-agora/authkit-server 0.54.0 → 0.55.1

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.

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

@@ -18,8 +18,17 @@ export declare function sudoContextFrom(ctx: HttpContext): Promise<SudoContext>;
  * Registra a lista montada. Chamado UMA vez por `registerAuthHost`, e
  * SUBSTITUI (não acumula): registrar o host de novo é redefinir o que existe,
  * não somar ao que existia.
+ *
+ * `fromDefaults` distingue "esta é a lista de defaults da LIB" de "esta é a
+ * lista que o HOST escreveu" (argumento de `registerAuthHost` ou
+ * `config.sudo.methods`). A distinção existe porque a derivação do deadlock
+ * (`derivedSudoMethods`) só pode mexer na primeira: mexer na segunda seria
+ * mudar, sem pedir, o que um host declarou explicitamente — e a promessa de
+ * `sudoMethods` é que ele SUBSTITUI os defaults.
  */
-export declare function setMountedSudoMethods(methods: SudoMethod[]): void;
+export declare function setMountedSudoMethods(methods: SudoMethod[], opts?: {
+    fromDefaults?: boolean;
+}): void;
 /** Um método com este id teve rotas montadas? Usado só para avisar de drift. */
 export declare function isSudoMethodMounted(methodId: string): boolean;
 /**
@@ -33,6 +42,29 @@ export declare function isSudoMethodMounted(methodId: string): boolean;
  * circular se os métodos importassem de volta o controller.
  */
 export declare function explicitSudoMethods(cfg: ResolvedServerConfig): SudoMethod[] | null;
+/**
+ * O DEFAULT da lib, resolvido contra o config — o conserto do deadlock.
+ *
+ * `registerAuthHost` monta `[password, passkey, magicLink]` sem saber nada do
+ * config (a montagem acontece antes de o config lazy resolver). Aqui o config
+ * está resolvido, e é aqui que se decide qual metade vale:
+ *
+ * - host COM senha → `[password, passkey]`, o histórico byte a byte. O endpoint
+ *   do magic link fica montado e inerte: quem quiser oferecê-lo declara
+ *   `config.sudo.methods` — e agora isso FUNCIONA, porque a rota existe (era
+ *   metade da promessa de 0.46 que ficava faltando).
+ * - host que declarou `authMethods: { password: false }` → `[passkey, magicLink]`.
+ *   Sai o campo de senha, que nesse deployment é uma opção que não pode dar
+ *   certo, e entra o único método que uma conta sem credencial prévia consegue
+ *   satisfazer (ver `CREDENTIAL_FREE_SUDO_METHOD_IDS` em `sudo/satisfiability.ts`).
+ *
+ * SÓ MEXE NA LISTA DE DEFAULTS (`mountedFromDefaults`). Lista escrita pelo host
+ * passa intacta — inclusive quando isso o deixa em deadlock, caso em que o aviso
+ * de boot (`define_config.ts`) é quem fala. Adivinhar a intenção de uma lista
+ * explícita seria pior: é a lista dele, e a promessa documentada é que ela
+ * SUBSTITUI os defaults.
+ */
+export declare function derivedSudoMethods(cfg: ResolvedServerConfig): SudoMethod[];
 /**
  * O método `methodId` está habilitado para ESTE host?
  *
@@ -41,9 +73,11 @@ export declare function explicitSudoMethods(cfg: ResolvedServerConfig): SudoMeth
  * continuaria vivo e concedendo sudo — uma config que aparenta restringir e não
  * restringe é pior que nenhuma config.
  *
- * Sem configuração explícita nada foi restringido: vale o que tem rota montada.
- * Isso é deliberado — a lista de defaults não é a fonte de verdade do que está
- * montado, e tratá-la como tal derrubaria um método customizado do host.
+ * Sem configuração explícita nada foi restringido: vale o que tem rota montada,
+ * MENOS o que a derivação do default tirou (ver `isDefaultSudoMethodDerivedOut`).
+ * Continua não sendo a lista de defaults a fonte de verdade do que está montado —
+ * tratá-la como tal derrubaria um método customizado do host —, e a derivação só
+ * remove ids que a própria lib pôs na lista.
  */
 export declare function isSudoMethodEnabled(cfg: ResolvedServerConfig, methodId: string): boolean;
 /**
@@ -64,6 +98,12 @@ export declare function isSudoMethodEnabled(cfg: ResolvedServerConfig, methodId:
  * fica estruturalmente impossível no caso sem config: é literalmente a mesma
  * lista. O aviso de flag-drift do controller passa a valer só para o caso que
  * sobra — config explícita divergindo do que foi montado.
+ *
+ * "A lista montada" é a lista montada DERIVADA (`derivedSudoMethods`), e os
+ * handlers aplicam a MESMA derivação pela mesma função — o drift continua
+ * impossível. A derivação existe porque a montagem não conhece o config: ela é
+ * quem tira o campo de senha de um host que declarou não ter senha, e quem
+ * mantém o default histórico intacto para quem tem.
  */
 export declare function configuredSudoMethods(cfg: ResolvedServerConfig): SudoMethod[];
 /**

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

@@ -40,13 +40,28 @@ export async function sudoContextFrom(ctx) {
  * ver `configuredSudoMethods`.
  */
 const mountedSudoMethods = [];
+/**
+ * A lista montada é a de DEFAULTS da lib (e não uma escrita pelo host)?
+ *
+ * Só a lista de defaults é derivada do config (`derivedSudoMethods`). Uma lista
+ * que o host escreveu vale ao pé da letra — ver o docblock de `setMountedSudoMethods`.
+ */
+let mountedFromDefaults = false;
 /**
  * Registra a lista montada. Chamado UMA vez por `registerAuthHost`, e
  * SUBSTITUI (não acumula): registrar o host de novo é redefinir o que existe,
  * não somar ao que existia.
+ *
+ * `fromDefaults` distingue "esta é a lista de defaults da LIB" de "esta é a
+ * lista que o HOST escreveu" (argumento de `registerAuthHost` ou
+ * `config.sudo.methods`). A distinção existe porque a derivação do deadlock
+ * (`derivedSudoMethods`) só pode mexer na primeira: mexer na segunda seria
+ * mudar, sem pedir, o que um host declarou explicitamente — e a promessa de
+ * `sudoMethods` é que ele SUBSTITUI os defaults.
  */
-export function setMountedSudoMethods(methods) {
+export function setMountedSudoMethods(methods, opts = {}) {
     mountedSudoMethods.splice(0, mountedSudoMethods.length, ...methods);
+    mountedFromDefaults = opts.fromDefaults === true;
 }
 /** Um método com este id teve rotas montadas? Usado só para avisar de drift. */
 export function isSudoMethodMounted(methodId) {
@@ -66,6 +81,67 @@ export function explicitSudoMethods(cfg) {
     const configured = cfg?.sudo?.methods;
     return Array.isArray(configured) && configured.length ? configured : null;
 }
+/**
+ * O host declarou, PELO CONFIG, que este deployment não tem senha usável?
+ *
+ * `authMethods: { password: false }` é pin de config e é autoritativo — tem
+ * prioridade sobre o runtime setting e o console admin mostra o toggle travado.
+ * Quem declara isso está dizendo que ninguém entra por senha; contas criadas
+ * pelo signup passwordless nem têm senha (a coluna leva um hash aleatório
+ * inutilizável, indistinguível de um hash real de dentro do pacote).
+ *
+ * NÃO usa `passwordless.*`: aquelas flags LIGAM vias alternativas de login sem
+ * desligar a senha, então um host com `passwordless.magicLink: true` pode
+ * perfeitamente ter usuários que conhecem a própria senha. Só o pin em `false`
+ * é uma afirmação sobre o deployment inteiro.
+ */
+function isPasswordlessHost(cfg) {
+    return cfg?.authMethods?.password === false;
+}
+/**
+ * O DEFAULT da lib, resolvido contra o config — o conserto do deadlock.
+ *
+ * `registerAuthHost` monta `[password, passkey, magicLink]` sem saber nada do
+ * config (a montagem acontece antes de o config lazy resolver). Aqui o config
+ * está resolvido, e é aqui que se decide qual metade vale:
+ *
+ * - host COM senha → `[password, passkey]`, o histórico byte a byte. O endpoint
+ *   do magic link fica montado e inerte: quem quiser oferecê-lo declara
+ *   `config.sudo.methods` — e agora isso FUNCIONA, porque a rota existe (era
+ *   metade da promessa de 0.46 que ficava faltando).
+ * - host que declarou `authMethods: { password: false }` → `[passkey, magicLink]`.
+ *   Sai o campo de senha, que nesse deployment é uma opção que não pode dar
+ *   certo, e entra o único método que uma conta sem credencial prévia consegue
+ *   satisfazer (ver `CREDENTIAL_FREE_SUDO_METHOD_IDS` em `sudo/satisfiability.ts`).
+ *
+ * SÓ MEXE NA LISTA DE DEFAULTS (`mountedFromDefaults`). Lista escrita pelo host
+ * passa intacta — inclusive quando isso o deixa em deadlock, caso em que o aviso
+ * de boot (`define_config.ts`) é quem fala. Adivinhar a intenção de uma lista
+ * explícita seria pior: é a lista dele, e a promessa documentada é que ela
+ * SUBSTITUI os defaults.
+ */
+export function derivedSudoMethods(cfg) {
+    return mountedSudoMethods.filter((m) => !isDefaultSudoMethodDerivedOut(cfg, m?.id));
+}
+/**
+ * Este id foi DERIVADO PARA FORA da lista de defaults neste host?
+ *
+ * Ponto único da regra, consultado pelos DOIS lados (a tela, via
+ * `configuredSudoMethods`, e os handlers, via `isSudoMethodEnabled`) — é o que
+ * torna o drift entre eles estruturalmente impossível também no caso derivado.
+ *
+ * Nunca responde `true` para uma lista de host, nem para um id que não seja um
+ * dos dois built-in do default. Ou seja: só REMOVE, e só remove o que a própria
+ * lib pôs lá.
+ */
+function isDefaultSudoMethodDerivedOut(cfg, methodId) {
+    if (!mountedFromDefaults)
+        return false;
+    // Host passwordless: cai a senha (não há senha usável neste deployment).
+    // Host com senha: cai o magic link (posture histórica preservada — o default
+    // não passa a oferecer um step-up por e-mail a quem nunca pediu).
+    return isPasswordlessHost(cfg) ? methodId === 'password' : methodId === 'magic-link';
+}
 /**
  * O método `methodId` está habilitado para ESTE host?
  *
@@ -74,14 +150,16 @@ export function explicitSudoMethods(cfg) {
  * continuaria vivo e concedendo sudo — uma config que aparenta restringir e não
  * restringe é pior que nenhuma config.
  *
- * Sem configuração explícita nada foi restringido: vale o que tem rota montada.
- * Isso é deliberado — a lista de defaults não é a fonte de verdade do que está
- * montado, e tratá-la como tal derrubaria um método customizado do host.
+ * Sem configuração explícita nada foi restringido: vale o que tem rota montada,
+ * MENOS o que a derivação do default tirou (ver `isDefaultSudoMethodDerivedOut`).
+ * Continua não sendo a lista de defaults a fonte de verdade do que está montado —
+ * tratá-la como tal derrubaria um método customizado do host —, e a derivação só
+ * remove ids que a própria lib pôs na lista.
  */
 export function isSudoMethodEnabled(cfg, methodId) {
     const explicit = explicitSudoMethods(cfg);
     if (explicit === null)
-        return true;
+        return !isDefaultSudoMethodDerivedOut(cfg, methodId);
     return explicit.some((m) => m?.id === methodId);
 }
 /**
@@ -102,9 +180,15 @@ export function isSudoMethodEnabled(cfg, methodId) {
  * fica estruturalmente impossível no caso sem config: é literalmente a mesma
  * lista. O aviso de flag-drift do controller passa a valer só para o caso que
  * sobra — config explícita divergindo do que foi montado.
+ *
+ * "A lista montada" é a lista montada DERIVADA (`derivedSudoMethods`), e os
+ * handlers aplicam a MESMA derivação pela mesma função — o drift continua
+ * impossível. A derivação existe porque a montagem não conhece o config: ela é
+ * quem tira o campo de senha de um host que declarou não ter senha, e quem
+ * mantém o default histórico intacto para quem tem.
  */
 export function configuredSudoMethods(cfg) {
-    return explicitSudoMethods(cfg) ?? mountedSudoMethods;
+    return explicitSudoMethods(cfg) ?? derivedSudoMethods(cfg);
 }
 /**
  * Verbos HTTP com a forma `(pattern, handler, ...)` — o handler é o SEGUNDO

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

@@ -0,0 +1,62 @@
+/**
+ * "Este host consegue satisfazer o próprio sudo?" — a pergunta que ninguém
+ * fazia, e cuja resposta "não" trancava o usuário fora de exportar/excluir os
+ * próprios dados.
+ *
+ * MÓDULO FOLHA DE PROPÓSITO: importa só TIPOS. `define_config.ts` precisa
+ * chamar o aviso de boot daqui, e `sudo/runtime.ts` precisa da mesma lista de
+ * ids — importar `runtime.ts` de dentro do `define_config` fecharia um ciclo
+ * (`runtime` → controllers → ... → `define_config`) cuja ordem de avaliação é
+ * exatamente o tipo de coisa que quebra em produção e não em teste.
+ */
+import type { SudoMethod } from './types.js';
+/**
+ * Métodos built-in que uma conta SEM senha e SEM passkey consegue satisfazer —
+ * os únicos que quebram o deadlock do host passwordless.
+ *
+ * `oidc-step-up` não exige nada previamente cadastrado (é o `prompt=login` do
+ * próprio protocolo); `magic-link` exige apenas que a conta tenha e-mail, e a
+ * ENTREGA tem fallback para o mailer default do host-kit, então nem hook é
+ * obrigatório. Os outros dois built-in — `password` e `passkey` — exigem, por
+ * definição, uma credencial que o usuário teria de ter cadastrado ANTES, e é
+ * essa a pré-condição que um host passwordless não satisfaz.
+ */
+export declare const CREDENTIAL_FREE_SUDO_METHOD_IDS: readonly string[];
+/**
+ * Avisa, NO BOOT, quando a configuração de sudo deste host não tem um único
+ * método que uma conta sem senha possa satisfazer.
+ *
+ * QUANDO DISPARA (as quatro condições, todas necessárias):
+ *
+ * 1. O host declarou `sudo.methods` EXPLICITAMENTE. Sem declaração vale o
+ *    default derivado, que já resolve o caso passwordless — não há o que avisar.
+ * 2. O deployment tem contas sem senha usável: `authMethods.password === false`
+ *    (ninguém entra por senha) ou `passwordless.signup === true` (o cadastro
+ *    público cria contas com um hash aleatório inutilizável).
+ * 3. Nenhum dos métodos declarados é credential-free.
+ * 4. TODOS os métodos declarados são built-in deste pacote — ou seja, o pacote
+ *    consegue de fato PROVAR que a lista exige credencial prévia.
+ *
+ * WARN, NÃO THROW. Recusar o boot seria transformar um upgrade de patch/minor
+ * numa aplicação que não sobe, em produção, por uma condição que é
+ * DEGRADAÇÃO — a tela de confirmação fica sem opções, o que já falha fechado — e
+ * não uma brecha. Pior: a remediação nem sempre é uma linha de config
+ * (`oidcStepUp` exige uma rota e um callback no host), então o app ficaria fora
+ * do ar até alguém escrever código. E a detecção é, por construção, incompleta
+ * (item 4): um throw baseado numa heurística derruba host correto. O irmão
+ * `adonis-agent` recusa montar quando a superfície PROVADAMENTE não funciona;
+ * aqui não há prova — há forte suspeita, e o lugar disso é um aviso alto.
+ *
+ * @returns a mensagem emitida, ou `null` quando não havia nada a avisar (para
+ * teste; o efeito de verdade é o `console.warn`).
+ */
+export declare function warnUnsatisfiableSudoConfig(input: {
+    /** `config.sudo.methods` — a lista que o host declarou, se declarou. */
+    methods?: SudoMethod[];
+    /** `authMethods.password` pinado em `false`? */
+    passwordPinnedOff: boolean;
+    /** `passwordless.signup` ligado? */
+    passwordlessSignup: boolean;
+    /** Injeção para teste. Default: `console.warn`. */
+    warn?: (message: string) => void;
+}): string | null;

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

@@ -0,0 +1,89 @@
+/**
+ * "Este host consegue satisfazer o próprio sudo?" — a pergunta que ninguém
+ * fazia, e cuja resposta "não" trancava o usuário fora de exportar/excluir os
+ * próprios dados.
+ *
+ * MÓDULO FOLHA DE PROPÓSITO: importa só TIPOS. `define_config.ts` precisa
+ * chamar o aviso de boot daqui, e `sudo/runtime.ts` precisa da mesma lista de
+ * ids — importar `runtime.ts` de dentro do `define_config` fecharia um ciclo
+ * (`runtime` → controllers → ... → `define_config`) cuja ordem de avaliação é
+ * exatamente o tipo de coisa que quebra em produção e não em teste.
+ */
+/**
+ * Métodos built-in que uma conta SEM senha e SEM passkey consegue satisfazer —
+ * os únicos que quebram o deadlock do host passwordless.
+ *
+ * `oidc-step-up` não exige nada previamente cadastrado (é o `prompt=login` do
+ * próprio protocolo); `magic-link` exige apenas que a conta tenha e-mail, e a
+ * ENTREGA tem fallback para o mailer default do host-kit, então nem hook é
+ * obrigatório. Os outros dois built-in — `password` e `passkey` — exigem, por
+ * definição, uma credencial que o usuário teria de ter cadastrado ANTES, e é
+ * essa a pré-condição que um host passwordless não satisfaz.
+ */
+export const CREDENTIAL_FREE_SUDO_METHOD_IDS = ['oidc-step-up', 'magic-link'];
+/**
+ * Ids dos métodos que ESTE pacote implementa.
+ *
+ * Serve para o aviso abaixo se CALAR diante de um método customizado: de um
+ * método do SPI o pacote não tem como saber se ele exige credencial prévia, e um
+ * aviso de boot que grita para uma configuração correta é um aviso que o host
+ * aprende a ignorar — justamente o que não pode acontecer com este.
+ */
+const BUILTIN_SUDO_METHOD_IDS = [
+    'password',
+    'passkey',
+    'oidc-step-up',
+    'magic-link',
+];
+/**
+ * Avisa, NO BOOT, quando a configuração de sudo deste host não tem um único
+ * método que uma conta sem senha possa satisfazer.
+ *
+ * QUANDO DISPARA (as quatro condições, todas necessárias):
+ *
+ * 1. O host declarou `sudo.methods` EXPLICITAMENTE. Sem declaração vale o
+ *    default derivado, que já resolve o caso passwordless — não há o que avisar.
+ * 2. O deployment tem contas sem senha usável: `authMethods.password === false`
+ *    (ninguém entra por senha) ou `passwordless.signup === true` (o cadastro
+ *    público cria contas com um hash aleatório inutilizável).
+ * 3. Nenhum dos métodos declarados é credential-free.
+ * 4. TODOS os métodos declarados são built-in deste pacote — ou seja, o pacote
+ *    consegue de fato PROVAR que a lista exige credencial prévia.
+ *
+ * WARN, NÃO THROW. Recusar o boot seria transformar um upgrade de patch/minor
+ * numa aplicação que não sobe, em produção, por uma condição que é
+ * DEGRADAÇÃO — a tela de confirmação fica sem opções, o que já falha fechado — e
+ * não uma brecha. Pior: a remediação nem sempre é uma linha de config
+ * (`oidcStepUp` exige uma rota e um callback no host), então o app ficaria fora
+ * do ar até alguém escrever código. E a detecção é, por construção, incompleta
+ * (item 4): um throw baseado numa heurística derruba host correto. O irmão
+ * `adonis-agent` recusa montar quando a superfície PROVADAMENTE não funciona;
+ * aqui não há prova — há forte suspeita, e o lugar disso é um aviso alto.
+ *
+ * @returns a mensagem emitida, ou `null` quando não havia nada a avisar (para
+ * teste; o efeito de verdade é o `console.warn`).
+ */
+export function warnUnsatisfiableSudoConfig(input) {
+    const declared = Array.isArray(input.methods) ? input.methods : [];
+    if (!declared.length)
+        return null;
+    if (!input.passwordPinnedOff && !input.passwordlessSignup)
+        return null;
+    const ids = declared.map((m) => m?.id).filter((id) => typeof id === 'string');
+    if (ids.length !== declared.length)
+        return null; // lista malformada: não é este o aviso
+    if (ids.some((id) => CREDENTIAL_FREE_SUDO_METHOD_IDS.includes(id)))
+        return null;
+    if (!ids.every((id) => BUILTIN_SUDO_METHOD_IDS.includes(id)))
+        return null;
+    const trigger = input.passwordPinnedOff
+        ? 'authMethods: { password: false }'
+        : 'passwordless: { signup: true }';
+    const message = [
+        `authkit: sudo mode SEM SAÍDA para contas sem senha. Este host declarou \`${trigger}\`, então existem contas sem senha usável — mas \`sudo.methods\` só lista [${ids.join(', ')}], e todos exigem uma credencial cadastrada ANTES.`,
+        'Consequência: essas contas ficam trancadas fora de TODA operação sob `requireSudo` — exportar/excluir dados (LGPD), MFA, Personal Access Tokens, troca de e-mail — inclusive fora do cadastro de passkey, que é o que destravaria o resto.',
+        'Saída: acrescente `sudoMethods.oidcStepUp({ url: "/auth/step-up" })` (reautenticação no seu IdP) ou `sudoMethods.magicLink()` (link de confirmação por e-mail, enviado pelo mailer do app quando não há hook `mail.onSudoLink`) à lista de `sudo.methods`.',
+    ].join(' ');
+    (input.warn ?? console.warn)(message);
+    return message;
+}