@adonis-agora/authkit-server 0.54.0 → 0.55.1

package/build/src/host/oidc_rp_guard.js

@@ -1,6 +1,27 @@
-import { symbols } from '@adonisjs/auth';
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { ACCOUNT_SESSION_KEY } from './middleware/account_auth.js';
+/** Memo do construtor entre instâncias — o `import()` só paga o custo uma vez. */
+let cachedUnauthorizedAccess;
+/**
+ * Captura o `E_UNAUTHORIZED_ACCESS` real do `@adonisjs/auth` sem import
+ * estático. Chamado no boot pelo {@link oidcRpGuard} (falha cedo e com uma
+ * mensagem útil se o peer não estiver instalado) e, como rede de segurança, na
+ * primeira `authenticate()` de um guard construído à mão.
+ */
+export async function loadUnauthorizedAccess() {
+    if (cachedUnauthorizedAccess)
+        return cachedUnauthorizedAccess;
+    try {
+        const auth = (await import('@adonisjs/auth'));
+        cachedUnauthorizedAccess = auth.errors.E_UNAUTHORIZED_ACCESS;
+        return cachedUnauthorizedAccess;
+    }
+    catch (error) {
+        throw new RuntimeException('oidcRpGuard() precisa de "@adonisjs/auth" instalado (é um peer opcional do ' +
+            '@adonis-agora/authkit-server, só necessário se você plugar este guard em config/auth.ts). ' +
+            'Rode `npm i @adonisjs/auth` (ou pnpm/yarn).', { cause: error });
+    }
+}
 /**
  * Guard de `@adonisjs/auth` pra Relying Parties OIDC — o app não autentica
  * ninguém (sem senha, sem remember-me); a identidade vem da sessão gravada
@@ -32,22 +53,36 @@ export class OidcRpGuard {
     #sessionKey;
     #emitter;
     #userProvider;
-    [symbols.GUARD_KNOWN_EVENTS] = {};
+    #unauthorized;
     driverName = 'oidc_rp';
     authenticationAttempted = false;
     isAuthenticated = false;
     isLoggedOut = false;
     user;
-    constructor(name, ctx, sessionKey, emitter, userProvider) {
+    constructor(name, ctx, sessionKey, emitter, userProvider, unauthorized) {
         this.#name = name;
         this.#ctx = ctx;
         this.#sessionKey = sessionKey;
         this.#emitter = emitter;
         this.#userProvider = userProvider;
+        this.#unauthorized = unauthorized ?? cachedUnauthorizedAccess;
+    }
+    /**
+     * O `E_UNAUTHORIZED_ACCESS` do framework — `status` 401 e os renderers
+     * html/json, então o handler de exceção do host trata igual ao dos guards
+     * nativos. Se o construtor ainda não foi resolvido (guard instanciado à mão,
+     * antes de qualquer `authenticate()`), cai num `RuntimeException` em vez de
+     * mentir sobre o tipo.
+     */
+    #unauthorizedError(message) {
+        const Unauthorized = this.#unauthorized ?? cachedUnauthorizedAccess;
+        if (!Unauthorized)
+            return new RuntimeException(message);
+        return new Unauthorized(message, { guardDriverName: this.driverName });
     }
     getUserOrFail() {
         if (!this.user) {
-            throw new RuntimeException('Cannot access user. Authentication has not been attempted or failed.');
+            throw this.#unauthorizedError('Cannot access user. Authentication has not been attempted or failed.');
         }
         return this.user;
     }
@@ -89,13 +124,14 @@ export class OidcRpGuard {
             return this.getUserOrFail();
         }
         this.authenticationAttempted = true;
+        this.#unauthorized ??= await loadUnauthorizedAccess();
         const userId = this.#ctx.session.get(this.#sessionKey);
         if (!userId) {
             this.#emitter.emit('oidc_rp:authentication_failed', {
                 ctx: this.#ctx,
                 guardName: this.#name,
             });
-            throw new RuntimeException('Unauthorized', { cause: 'E_UNAUTHORIZED_ACCESS' });
+            throw this.#unauthorizedError('Unauthorized');
         }
         const guardUser = await this.#userProvider.findById(userId);
         if (!guardUser) {
@@ -104,7 +140,7 @@ export class OidcRpGuard {
                 ctx: this.#ctx,
                 guardName: this.#name,
             });
-            throw new RuntimeException('Unauthorized', { cause: 'E_UNAUTHORIZED_ACCESS' });
+            throw this.#unauthorizedError('Unauthorized');
         }
         this.user = guardUser.getOriginal();
         this.isAuthenticated = true;
@@ -115,13 +151,22 @@ export class OidcRpGuard {
         });
         return this.user;
     }
+    /**
+     * `authenticate()` sem lançar — mas SÓ para falha de autenticação. Igual ao
+     * `SessionGuard` nativo: engole apenas `E_UNAUTHORIZED_ACCESS` e relança o
+     * resto. Um `catch` cego aqui transformava uma queda do banco dentro de
+     * `provider.findById` em "não logado" para todo mundo, sem nada nos logs.
+     */
     async check() {
         try {
             await this.authenticate();
             return true;
         }
-        catch {
-            return false;
+        catch (error) {
+            const Unauthorized = this.#unauthorized ?? cachedUnauthorizedAccess;
+            if (Unauthorized && error instanceof Unauthorized)
+                return false;
+            throw error;
         }
     }
     async authenticateAsClient(user) {
@@ -139,6 +184,7 @@ export function oidcRpGuard(config) {
         async resolver(name, app) {
             const emitter = await app.container.make('emitter');
             const sessionKey = config.sessionKey ?? ACCOUNT_SESSION_KEY;
+            const unauthorized = await loadUnauthorizedAccess();
             let userProvider;
             if (typeof config.provider.resolver === 'function') {
                 userProvider = await config.provider.resolver(app);
@@ -147,7 +193,7 @@ export function oidcRpGuard(config) {
                 userProvider = config.provider;
             }
             return (ctx) => {
-                return new OidcRpGuard(name, ctx, sessionKey, emitter, userProvider);
+                return new OidcRpGuard(name, ctx, sessionKey, emitter, userProvider, unauthorized);
             };
         },
     };

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

@@ -0,0 +1,21 @@
+import type { ResolvedServerConfig } from '../define_config.js';
+/**
+ * The canonical public origin for links we EMAIL (password reset, magic link,
+ * OTP unlock, org invitations, email verification/change, security notices).
+ *
+ * Never derive these from `request.host()` / `request.protocol()` (which reads
+ * `X-Forwarded-Proto` under a trusting proxy config): both are client-supplied.
+ * An attacker who can reach the server directly (common when the app sits
+ * behind a load balancer that does not pin `Host`) can submit a password-reset
+ * or magic-link request for a victim's address with a `Host` of their choosing,
+ * and the victim's genuine email ends up pointing at attacker-controlled
+ * infrastructure. This is classic password-reset poisoning.
+ *
+ * Defaults to the origin (`scheme://host[:port]`, no trailing slash, mount
+ * path stripped) of the resolved `issuer` — the one canonical origin this
+ * library already has. Hosts that legitimately serve the same issuer under
+ * multiple public hostnames (and therefore want emailed links to follow the
+ * request instead of normalizing to a single hostname) can opt out via the
+ * `mail.origin` config escape hatch.
+ */
+export declare function authkitOrigin(cfg: ResolvedServerConfig): string;

package/build/src/host/origin.js

@@ -0,0 +1,22 @@
+/**
+ * The canonical public origin for links we EMAIL (password reset, magic link,
+ * OTP unlock, org invitations, email verification/change, security notices).
+ *
+ * Never derive these from `request.host()` / `request.protocol()` (which reads
+ * `X-Forwarded-Proto` under a trusting proxy config): both are client-supplied.
+ * An attacker who can reach the server directly (common when the app sits
+ * behind a load balancer that does not pin `Host`) can submit a password-reset
+ * or magic-link request for a victim's address with a `Host` of their choosing,
+ * and the victim's genuine email ends up pointing at attacker-controlled
+ * infrastructure. This is classic password-reset poisoning.
+ *
+ * Defaults to the origin (`scheme://host[:port]`, no trailing slash, mount
+ * path stripped) of the resolved `issuer` — the one canonical origin this
+ * library already has. Hosts that legitimately serve the same issuer under
+ * multiple public hostnames (and therefore want emailed links to follow the
+ * request instead of normalizing to a single hostname) can opt out via the
+ * `mail.origin` config escape hatch.
+ */
+export function authkitOrigin(cfg) {
+    return cfg.mail?.origin ?? new URL(cfg.issuer).origin;
+}

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

@@ -1,6 +1,7 @@
 import type { Router } from '@adonisjs/core/http';
 import type { AuthSocialConfig, RateLimitConfigInput } from '../define_config.js';
-import { type AccountPathsOptions } from './account_paths.js';
+import { type AccountPathKey, type AccountPathsOptions } from './account_paths.js';
+import type { PolicyRouteOption } from './config_locks.js';
 import type { SudoMethod } from './sudo/types.js';
 /** Chave da sessão Adonis que registra o timestamp da última atividade (idle timeout). */
 export declare const ACCOUNT_LAST_SEEN_KEY = "authkit_last_seen";
@@ -108,7 +109,14 @@ export interface AuthHostOptions {
      * fechada, mas é a promessa do SPI pela metade; `magicLink()` em particular
      * não teria como ser alcançado em runtime.
      *
-     * Ausente → `[password(), passkey()]`.
+     * Ausente → `[password(), passkey(), magicLink()]`, e o config resolvido
+     * decide quais deles a tela OFERECE: host com senha recebe
+     * `[password, passkey]` (o histórico, byte a byte) e host que declarou
+     * `authMethods: { password: false }` recebe `[passkey, magicLink]` — sem isso
+     * ele não teria um único método satisfazível. Ver `derivedSudoMethods` em
+     * `sudo/runtime.ts`.
+     *
+     * Passar a opção desliga essa derivação: a lista é do host, ao pé da letra.
      */
     sudoMethods?: SudoMethod[];
     /**
@@ -203,8 +211,101 @@ export interface AccountScreensOptions {
     /** Apps com acesso / grants de consentimento OIDC (`/account/apps*`). */
     apps?: boolean;
 }
+/**
+ * Mapa RESOLVIDO das rotas montadas, devolvido por `registerAuthHost`.
+ *
+ * Existe porque os overrides de path (`accountRoutes`) chegavam ao servidor
+ * (via `accountPath()`) mas NÃO ao frontend: o layout React e os formulários do
+ * host tinham de repetir os mesmos paths à mão, e um override era meio-recurso —
+ * certo no servidor, errado na UI. Entregue este mapa ao frontend (uma shared
+ * prop do Inertia, um `<script type="application/json">`, um endpoint) em vez de
+ * hardcodar `href`s.
+ *
+ * @example
+ * const authkitRoutes = registerAuthHost(router)
+ * router.get('/', ({ inertia }) => inertia.render('home', { authkitRoutes }))
+ */
+export interface AuthHostRouteMap {
+    /** Onde o provider OIDC foi montado (o wildcard é `${mountPath}/*`). */
+    mountPath: string;
+    /** Console de conta: prefixo, base da JSON API e o path de CADA tela. */
+    account: {
+        /** Prefixo base resolvido (default `/account`). */
+        prefix: string;
+        /** Base da JSON API do console de conta (default `/account/api`). */
+        api: string;
+        /** Path completo de cada tela navegável (`security` → `/account/security`). */
+        paths: Record<AccountPathKey, string>;
+        /** Destino do redirect de "faça login" em vigor. */
+        loginUrl: string;
+        /** Quais telas foram efetivamente montadas. */
+        screens: Record<keyof AccountScreensOptions, boolean>;
+    };
+    /** Console admin: prefixo resolvido, ou `null` quando não foi montado. */
+    admin: {
+        prefix: string;
+    } | null;
+    /** Admin REST API: prefixo resolvido, ou `null` quando não foi montada. */
+    adminApi: {
+        prefix: string;
+    } | null;
+    /** Nomes das rotas nomeadas (as demais herdam o auto-naming do AdonisJS). */
+    names: Record<string, string>;
+    /** Ids dos métodos de sudo cujas rotas foram montadas, na ordem de montagem. */
+    sudoMethods: string[];
+    /**
+     * Opções de POLÍTICA passadas como argumento que foram IGNORADAS porque o
+     * `defineConfig` as declarou (config vence). Vazio no caso normal. Cada uma
+     * também sai como `console.warn` no boot — ver a regra de precedência abaixo.
+     */
+    overriddenByConfig: PolicyRouteOption[];
+}
 /**
  * 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 declare function registerAuthHost(router: Router, opts?: AuthHostOptions): AuthHostRouteMap;
+/**
+ * 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 declare function registerAuthHost(router: Router, opts?: AuthHostOptions): void;
+export declare function autoMountAuthHost(router: Router): AuthHostRouteMap;

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