@adonis-agora/authkit-server 0.54.0 → 0.55.0

package/build/src/define_config.d.ts

@@ -6,9 +6,11 @@ import type { AuditSink } from './audit/audit_sink.js';
 import { type EventsConfigInput } from './events/dispatcher.js';
 import { type BotProtectionConfigInput, type ResolvedBotProtectionConfig } from './host/bot_protection.js';
 import type { BrandingConfig } from './host/branding.js';
+import { type PolicyRouteOption } from './host/config_locks.js';
 import type { ResolveGeo } from './host/geo.js';
 import { type AuthMessages, type I18nConfig } from './host/i18n.js';
 import { type OtpLoginConfigInput, type ResolvedOtpLoginConfig } from './host/otp_login.js';
+import type { AuthHostOptions } from './host/register_auth_host.js';
 import type { SudoMethod } from './host/sudo/types.js';
 import { type ResolvedTrustedDevicesConfig, type TrustedDevicesConfigInput } from './host/trusted_device.js';
 import type { PatStore } from './pat/pat_store.js';
@@ -58,7 +60,13 @@ export interface MailHooks {
     /**
      * Envia o link de CONFIRMAÇÃO DE IDENTIDADE (sudo). Distinto de
      * `onMagicLink`: aquele autentica, este só concede sudo a quem já está
-     * logado. Sem este hook, `sudoMethods.magicLink()` fica indisponível.
+     * logado.
+     *
+     * OPCIONAL, como todo hook de e-mail daqui: sem ele o próprio host-kit envia
+     * pelo mailer default (`@adonisjs/mail`), com branding e i18n. Antes a
+     * ausência deste hook tornava `sudoMethods.magicLink()` INDISPONÍVEL, e num
+     * host passwordless isso fechava o deadlock de sudo — o único método sem
+     * credencial prévia dependia de alguém ter escrito um hook.
      */
     onSudoLink?: (data: {
         email: string;
@@ -154,6 +162,20 @@ export interface MailHooks {
         address: string;
         name?: string;
     };
+    /**
+     * Escape hatch: origem (`scheme://host[:port]`) usada para montar os links
+     * EMAILADOS (reset de senha, magic link, desbloqueio OTP, convites de
+     * organização, verificação/troca de e-mail, avisos de segurança), no lugar
+     * do `issuer` resolvido.
+     *
+     * Por default (campo ausente) os links usam `new URL(issuer).origin` — NUNCA
+     * `request.host()` / `X-Forwarded-Host`, que são client-supplied e abrem
+     * "password-reset poisoning" (ver `host/origin.ts`). Use este campo apenas
+     * quando o mesmo issuer é servido legitimamente sob MÚLTIPLOS hostnames
+     * públicos e os links devem seguir um hostname fixo diferente do issuer —
+     * o comportamento normal (issuer único) não precisa disto.
+     */
+    origin?: string;
 }
 /** Bucket de rate-limit: pontos (requests) permitidos por janela de duração. */
 export interface RateLimitBucket {
@@ -529,6 +551,30 @@ export interface AdminConfigInput {
     enabled: boolean;
     /** Roles globais que dão acesso ao /admin. Default: ['ADMIN']. */
     roles?: string[];
+    /**
+     * Interruptor de impersonation. Governa as DUAS superfícies:
+     *
+     *   1. o grant RFC 8693 `urn:ietf:params:oauth:grant-type:token-exchange`
+     *      registrado no provider OIDC (`src/provider/oidc_service.ts`) — é por
+     *      ele que um admin troca o próprio access token pelo de outra conta;
+     *   2. o painel de impersonation do console admin
+     *      (`GET {prefix}/api/impersonation/:userId`).
+     *
+     * `false` desliga as duas: o grant deixa de existir no provider (o token
+     * endpoint passa a responder `unsupported_grant_type`) e o painel responde
+     * 404. É um kill switch de verdade, não só um esconde-UI.
+     *
+     * Default: **`true`** — back-compat. O grant sempre foi registrado
+     * incondicionalmente e há hosts que o consomem a partir do PRÓPRIO /admin,
+     * sem montar o console desta lib; um default `false` os quebraria em runtime,
+     * em silêncio. Virar o default para `false` (secure-by-default) é decisão de
+     * major.
+     *
+     * Declarar esta chave também TRAVA a setting de runtime `admin_impersonation`
+     * (ver `src/host/config_locks.ts`): o arquivo passa a mandar e a UI/Admin API
+     * não altera mais o valor.
+     */
+    impersonation?: boolean;
 }
 export interface ResolvedAdminConfig {
     enabled: boolean;
@@ -681,6 +727,33 @@ export interface AuthServerConfigInput {
     patStore?: PatStore;
     /** Caminho base onde o host-kit monta as rotas OIDC. Default: '/oidc'. */
     mountPath?: string;
+    /**
+     * Montagem AUTOMÁTICA das rotas do host-kit, sem `registerAuthHost` no
+     * `start/routes.ts`.
+     *
+     * - ausente (default) → NÃO auto-monta. O app chama `registerAuthHost(router)`
+     *   no `start/routes.ts`, como sempre (back-compat).
+     * - `true` → o provider monta as rotas no boot chamando `registerAuthHost` —
+     *   literalmente a mesma função, não uma segunda implementação.
+     * - objeto → auto-monta usando estes valores como DEFAULTS estruturais.
+     * - `false` → não auto-monta, explicitamente (o kill switch documentado).
+     *
+     * ⚠️ Auto-montar E chamar `registerAuthHost` no `start/routes.ts` é duplo
+     * registro: a chamada manual LANÇA com a instrução de qual dos dois remover
+     * (duas rotas com o mesmo nome derrubam o boot do AdonisJS).
+     *
+     * ⚠️ A auto-montagem roda no `boot()` do provider, ANTES do `start/routes.ts`
+     * — as rotas do authkit ficam registradas primeiro, e os wildcards
+     * (`${mountPath}/*`, `${adminPrefix}/*`) casam antes de rotas do app com
+     * padrão sobreposto. Quem precisa da ordem inversa continua chamando
+     * `registerAuthHost` na posição que quiser.
+     *
+     * As chaves de POLÍTICA aqui dentro (`social`, `rateLimit`, `sudoMethods`,
+     * `admin`, `adminApi`) são redundantes: elas já vêm dos campos de topo do
+     * config e são travadas por eles. Use este objeto para o ESTRUTURAL —
+     * `accountRoutes`, `account`, `accountLoginUrl`, `mountPath`.
+     */
+    routes?: boolean | AuthHostOptions;
     /**
      * Destino default da área da conta: pós-login do console (sem `return_to`),
      * confirmações de e-mail e fallback de redirects. Default: '/account/security'.
@@ -721,16 +794,21 @@ export interface AuthServerConfigInput {
      * Métodos de confirmação de identidade (sudo mode). A ordem do array é a
      * ordem de exibição; o último método usado com sucesso é promovido ao topo.
      *
-     * Ausente → a lista que `registerAuthHost` MONTOU (que por sua vez cai em
-     * `[password(), passkey()]` sem `AuthHostOptions.sudoMethods`, o
-     * comportamento histórico). É a mesma resposta que os handlers dão nesse
-     * caso — "vale o que tem rota" —, e é o que impede a tela de oferecer um
-     * método sem endpoint ou de esconder um que funciona.
+     * Ausente → a lista que `registerAuthHost` MONTOU, DERIVADA contra este
+     * config: `[password, passkey]` num host com senha (o comportamento
+     * histórico) e `[passkey, magicLink]` num host que declarou
+     * `authMethods: { password: false }` — que de outra forma não teria um único
+     * método satisfazível. É a mesma resposta que os handlers dão nesse caso —
+     * "vale o que tem rota, menos o que este host não consegue satisfazer" —, e é
+     * o que impede a tela de oferecer um método sem endpoint ou de esconder um que
+     * funciona. Ver `derivedSudoMethods` em `host/sudo/runtime.ts`.
      *
-     * Host passwordless (autentica por OIDC/magic link) DEVE incluir ao menos um
+     * DECLARAR esta lista DESLIGA a derivação: ela SUBSTITUI os defaults e vale ao
+     * pé da letra. Um host passwordless que a declare PRECISA incluir ao menos um
      * método que não exija credencial previamente cadastrada — `oidcStepUp()` ou
      * `magicLink()` — senão o usuário fica sem caminho para exportar/excluir os
-     * próprios dados.
+     * próprios dados, e é isso que o aviso de boot de
+     * `host/sudo/satisfiability.ts` denuncia.
      */
     sudo?: {
         methods?: SudoMethod[];
@@ -1000,6 +1078,13 @@ export interface ResolvedServerConfig {
     };
     /** Keys de `auth_settings` travadas por terem sido definidas no defineConfig. */
     lockedSettingKeys: string[];
+    /** Auto-montagem das rotas do host-kit. Ver {@link AuthServerConfigInput.routes}. */
+    routes?: boolean | AuthHostOptions;
+    /**
+     * Opções de POLÍTICA de `registerAuthHost` travadas por terem sido definidas
+     * no defineConfig (config vence sobre o argumento). Ver `deriveLockedRouteOptions`.
+     */
+    lockedRouteOptions: PolicyRouteOption[];
     /** Integração opt-in com `@adonisjs/auth` (ausente = não integrado; comportamento de sempre). */
     adonisAuth?: {
         guard: string;

package/build/src/define_config.js

@@ -2,10 +2,11 @@ import { configProvider } from '@adonisjs/core';
 import { adapters } from './adapters/factory.js';
 import { composeAuditSink, resolveEvents } from './events/dispatcher.js';
 import { resolveBotProtection, } from './host/bot_protection.js';
-import { deriveLockedSettingKeys } from './host/config_locks.js';
+import { deriveLockedRouteOptions, deriveLockedSettingKeys, } from './host/config_locks.js';
 import { resolveMessages } from './host/i18n.js';
 import { resolveOtpLoginConfig, } from './host/otp_login.js';
 import { edgeRenderer } from './host/renderers/edge_renderer.js';
+import { warnUnsatisfiableSudoConfig } from './host/sudo/satisfiability.js';
 import { resolveTrustedDevices, } from './host/trusted_device.js';
 import { generateJwks } from './keys/jwks_manager.js';
 import { KeystoreCodec } from './keys/keystore_codec.js';
@@ -158,7 +159,9 @@ export function resolveAdmin(input) {
     return {
         enabled: input?.enabled ?? false,
         roles: input?.roles && input.roles.length > 0 ? input.roles : ['ADMIN'],
-        impersonation: false,
+        // Default `true`: preserva o comportamento histórico (grant sempre
+        // registrado). Ver o docblock de `AdminConfigInput.impersonation`.
+        impersonation: input?.impersonation !== false,
     };
 }
 /** Lê API keys de `AUTHKIT_ADMIN_API_KEY` (uma ou várias, separadas por vírgula). */
@@ -294,6 +297,25 @@ export function defineConfig(config) {
         else {
             jwks = { keys: jwksConfig.keys ?? [] };
         }
+        // BACKSTOP DE SUDO. Um host cujo `sudo.methods` não tem um único método
+        // satisfazível por conta sem senha fica bricado para TODA operação sob
+        // `requireSudo` — e hoje isso só se descobre quando um usuário não consegue
+        // excluir a própria conta. Aqui é o único ponto do pacote onde `sudo.methods`,
+        // `authMethods` e `passwordless` estão os três resolvidos e juntos, e este
+        // callback roda no boot (`configProvider.resolve` no `boot()` do provider),
+        // antes de qualquer request. Ver `host/sudo/satisfiability.ts` para as quatro
+        // condições e para o porquê de ser WARN e não THROW.
+        //
+        // LIMITE CONHECIDO: só vê a lista que passou pelo CONFIG. Um host que declare
+        // a lista APENAS no argumento `registerAuthHost(router, { sudoMethods })` não
+        // é coberto — o registro de rotas acontece fora daqui e o `authMethods` não
+        // chega lá. É o caso do ator informado (quem escreveu a lista à mão), não o
+        // do host que herdou os defaults, que é quem o aviso existe para pegar.
+        warnUnsatisfiableSudoConfig({
+            methods: config.sudo?.methods,
+            passwordPinnedOff: config.authMethods?.password === false,
+            passwordlessSignup: config.passwordless?.signup === true,
+        });
         // #9: mfaIssuer efetivo — top-level do defineConfig vence; senão o do lucidAccountStore; senão default.
         const effectiveMfaIssuer = config.mfaIssuer ??
             config.accountStore?.__mfaIssuer ??
@@ -389,6 +411,10 @@ export function defineConfig(config) {
             // Keys de auth_settings travadas porque foram definidas no defineConfig:
             // config vence e a UI/Admin API não pode alterá-las (ver host/config_locks.ts).
             lockedSettingKeys: deriveLockedSettingKeys(config),
+            routes: config.routes,
+            // Mesma regra do `lockedSettingKeys`, outro eixo: config × argumento de
+            // `registerAuthHost` (ver host/config_locks.ts).
+            lockedRouteOptions: deriveLockedRouteOptions(config),
             // Opt-in: ausente = authkit nunca toca `ctx.auth` (comportamento de sempre).
             adonisAuth: config.adonisAuth,
         };

package/build/src/host/account_api/account_api_controller.js

@@ -38,6 +38,7 @@ import { AvatarUploadError, isAvatarUploadSupported, storeAvatar } from '../avat
 import { sendEmailChangeConfirmationEmail, sendEmailChangeNoticeEmail } from '../default_mailer.js';
 import { translate } from '../i18n.js';
 import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
+import { authkitOrigin } from '../origin.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 import { resolveEffectiveEmailChange, resolveEffectivePasswordHistory, } from '../runtime_toggles.js';
 import { dispatchSecurityNotice } from '../security_notice_service.js';
@@ -331,7 +332,7 @@ export default class AccountApiController {
                 kind: 'password_changed',
                 ip: ctx.request.ip?.() ?? null,
                 timestamp: new Date().toISOString(),
-            }, cfg.mail, cfg.audit);
+            }, cfg.mail, cfg.audit, cfg);
         }
         return { ok: true };
     }
@@ -389,7 +390,7 @@ export default class AccountApiController {
             email: newEmail,
             ip: ctx.request.ip?.() ?? null,
         });
-        const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
+        const origin = authkitOrigin(cfg);
         const confirmUrl = `${origin}${accountPath('emailConfirm')}?token=${encodeURIComponent(issued.token)}`;
         if (cfg.mail?.onEmailChangeConfirm) {
             await cfg.mail.onEmailChangeConfirm({
@@ -414,7 +415,7 @@ export default class AccountApiController {
                 await cfg.mail.onEmailChangeNotice({ email: account.email, newEmail });
             }
             else {
-                await sendEmailChangeNoticeEmail(ctx, { email: account.email, newEmail });
+                await sendEmailChangeNoticeEmail(ctx, cfg, { email: account.email, newEmail });
             }
         }
         return { ok: true, email: newEmail };
@@ -692,7 +693,7 @@ export default class AccountApiController {
                 kind: 'passkey_removed',
                 ip: ctx.request.ip?.() ?? null,
                 timestamp: new Date().toISOString(),
-            }, cfg.mail, cfg.audit);
+            }, cfg.mail, cfg.audit, cfg);
         }
         return { ok: true, removed: credentialId };
     }

package/build/src/host/admin_api/admin_users_service.js

@@ -3,6 +3,7 @@ import { supportsAccountDeletion, supportsAccountStatus, supportsCountByGlobalRo
 import { PasswordPolicyError } from '../../password/password_manager.js';
 import { AccountDeletionService } from '../account_deletion_service.js';
 import { sendPasswordResetEmail } from '../default_mailer.js';
+import { authkitOrigin } from '../origin.js';
 import { resolveEffectiveRolesCatalog } from '../runtime_toggles.js';
 /**
  * Lógica de gestão de usuários compartilhada entre o console admin (B6, HTML) e a
@@ -292,7 +293,7 @@ export class AdminUsersService {
         const issued = await this.cfg.accountStore.issuePasswordResetToken(email);
         if (!issued)
             return;
-        const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
+        const origin = authkitOrigin(this.cfg);
         const resetUrl = `${origin}/auth/reset-password?token=${encodeURIComponent(issued.token)}`;
         if (this.cfg.mail?.onPasswordReset) {
             await this.cfg.mail.onPasswordReset({

package/build/src/host/admin_api/api_orgs_controller.js

@@ -1,5 +1,6 @@
 import '../augmentations.js';
 import { orgAddMemberValidator, orgCreateValidator, orgInvitationValidator, orgMemberRoleValidator, orgUpdateValidator, } from '../admin_validators.js';
+import { authkitOrigin } from '../origin.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 import { AdminOrgsService } from './admin_orgs_service.js';
 import { apiError, orgDetailDto, orgDto, orgInvitationDto } from './dto.js';
@@ -158,7 +159,7 @@ export default class ApiOrgsController {
         const svc = new AdminOrgsService(cfg);
         const orgId = ctx.request.param('id');
         const { email, role } = await ctx.request.validateUsing(orgInvitationValidator);
-        const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
+        const origin = authkitOrigin(cfg);
         const result = await svc.createInvitation(orgId, { email, role: role ?? 'member' }, actor, origin, await resolveRuntimeSettings(ctx));
         if (!result.ok) {
             if (result.reason === 'not_supported')

package/build/src/host/admin_console/console_impersonation_controller.d.ts

@@ -7,7 +7,21 @@ import type { HttpContext } from '@adonisjs/core/http';
  *
  * Retorna os parâmetros RFC 8693 (token exchange) para o admin assumir a
  * identidade de um usuário-alvo. 404 quando impersonation está desabilitado na
- * config ou quando nenhum client tem o grant token-exchange habilitado.
+ * config, quando a setting de runtime `admin_impersonation` desliga o painel, ou
+ * quando nenhum client tem o grant token-exchange habilitado.
+ *
+ * DUAS CAMADAS, PROPOSITALMENTE ASSIMÉTRICAS:
+ *
+ *   1. `config.admin.impersonation` decide se a CAPACIDADE existe. É decisão de
+ *      boot: é ela que registra (ou não) o grant RFC 8693 no provider OIDC. Uma
+ *      setting de runtime não desregistra rota que nunca foi registrada.
+ *   2. a setting `admin_impersonation` decide se o CONSOLE OFERECE o painel.
+ *      É decisão de runtime, mudável sem redeploy.
+ *
+ * A setting só APERTA, nunca AFROUXA — o gate de config é checado ANTES dela, e
+ * declarar `admin.impersonation` no `defineConfig` TRAVA a key (ver
+ * `host/config_locks.ts`), de forma que `getSetting` devolve null e o resolver
+ * cai no valor do config. Config > runtime, a mesma precedência do resto da lib.
  */
 export default class ConsoleImpersonationController {
     handle(ctx: HttpContext): Promise<void | {

package/build/src/host/admin_console/console_impersonation_controller.js

@@ -2,6 +2,8 @@ import '../augmentations.js';
 import { apiError } from '../admin_api/dto.js';
 import { buildImpersonationPanel } from '../impersonation.js';
 import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
+import { resolveRuntimeSettingsOrNoop } from '../runtime_settings.js';
+import { resolveEffectiveAdminImpersonation } from '../runtime_toggles.js';
 /**
  * Endpoint JSON do painel de impersonation do console admin React.
  *
@@ -9,16 +11,38 @@ import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
  *
  * Retorna os parâmetros RFC 8693 (token exchange) para o admin assumir a
  * identidade de um usuário-alvo. 404 quando impersonation está desabilitado na
- * config ou quando nenhum client tem o grant token-exchange habilitado.
+ * config, quando a setting de runtime `admin_impersonation` desliga o painel, ou
+ * quando nenhum client tem o grant token-exchange habilitado.
+ *
+ * DUAS CAMADAS, PROPOSITALMENTE ASSIMÉTRICAS:
+ *
+ *   1. `config.admin.impersonation` decide se a CAPACIDADE existe. É decisão de
+ *      boot: é ela que registra (ou não) o grant RFC 8693 no provider OIDC. Uma
+ *      setting de runtime não desregistra rota que nunca foi registrada.
+ *   2. a setting `admin_impersonation` decide se o CONSOLE OFERECE o painel.
+ *      É decisão de runtime, mudável sem redeploy.
+ *
+ * A setting só APERTA, nunca AFROUXA — o gate de config é checado ANTES dela, e
+ * declarar `admin.impersonation` no `defineConfig` TRAVA a key (ver
+ * `host/config_locks.ts`), de forma que `getSetting` devolve null e o resolver
+ * cai no valor do config. Config > runtime, a mesma precedência do resto da lib.
  */
 export default class ConsoleImpersonationController {
     async handle(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;
-        // Impersonation precisa estar explicitamente habilitado no config.
+        // Camada 1 — o kill switch de config. Sem ele o grant token-exchange nem
+        // existe no provider; devolver os parâmetros do painel seria mentir.
         if (!cfg.admin.impersonation) {
             return ctx.response.notFound(apiError('capability_unsupported', 'Impersonation não está habilitado nesta instalação.'));
         }
+        // Camada 2 — a política de runtime. Fail-safe: sem tabela `auth_settings`
+        // (ou com a key travada por config) o resolver cai no valor do config.
+        const runtimeSettings = await resolveRuntimeSettingsOrNoop(ctx);
+        const effective = await resolveEffectiveAdminImpersonation(runtimeSettings, cfg.admin.impersonation);
+        if (!effective.enabled) {
+            return ctx.response.notFound(apiError('capability_unsupported', 'O painel de impersonation está desligado pela setting de runtime `admin_impersonation`.'));
+        }
         const targetId = ctx.request.param('userId');
         const account = await cfg.accountStore.findById(targetId);
         if (!account) {

package/build/src/host/admin_console/console_orgs_controller.js

@@ -3,6 +3,7 @@ import { AdminOrgsService } from '../admin_api/admin_orgs_service.js';
 import { apiError, orgDetailDto, orgDto } from '../admin_api/dto.js';
 import { orgAddMemberValidator, orgCreateValidator, orgInvitationValidator, orgMemberRoleValidator, orgUpdateValidator, } from '../admin_validators.js';
 import { ACCOUNT_SESSION_KEY } from '../middleware/account_auth.js';
+import { authkitOrigin } from '../origin.js';
 import { resolveRuntimeSettings } from '../runtime_settings.js';
 /**
  * Endpoints JSON de organizações do console admin React.
@@ -201,7 +202,8 @@ export default class ConsoleOrgsController {
         }
         const orgId = ctx.request.param('id');
         const { email, role } = await ctx.request.validateUsing(orgInvitationValidator);
-        const origin = `${ctx.request.protocol()}://${ctx.request.host()}`;
+        const service = await ctx.containerResolver.make('authkit.server');
+        const origin = authkitOrigin(service.config);
         const result = await svc.createInvitation(orgId, { email, role: role ?? 'member' }, this.actor(ctx), origin, await this.settings(ctx));
         if ('ok' in result && result.ok === false) {
             if (result.reason === 'not_found') {

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

@@ -96,16 +96,16 @@ export declare const adminUserUpdateValidator: import("@vinejs/vine").VineValida
     avatarUrl: import("@vinejs/vine/schema/base/literal").OptionalModifier<import("@vinejs/vine/schema/base/literal").NullableModifier<import("@vinejs/vine").VineString>>;
 }, {
     name?: string | null | undefined;
-    globalRoles?: string[] | null | undefined;
     avatarUrl?: string | null | undefined;
+    globalRoles?: string[] | null | undefined;
 }, {
     name?: string | null | undefined;
-    globalRoles?: string[] | undefined;
     avatarUrl?: string | null | undefined;
+    globalRoles?: string[] | undefined;
 }, {
     name?: string | null | undefined;
-    globalRoles?: string[] | undefined;
     avatarUrl?: string | null | undefined;
+    globalRoles?: string[] | undefined;
 }>, Record<string, any> | undefined>;
 /** Substituição de roles globais no console (PATCH /users/:id/roles). */
 export declare const adminUserRolesValidator: import("@vinejs/vine").VineValidator<import("@vinejs/vine").VineObject<{

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

@@ -1,4 +1,7 @@
 import type { AuthSocialConfig, ResolvedRateLimitConfig } from '../define_config.js';
+import type { PolicyRouteOption } from './config_locks.js';
+import type { AuthHostOptions } from './register_auth_host.js';
+import type { SudoMethod } from './sudo/types.js';
 /**
  * Bits de routing do config resolvido que o `registerAuthHost` precisa em tempo de
  * REGISTRO de rota (síncrono). Stash feito no `boot()` do provider — que roda ANTES
@@ -13,10 +16,37 @@ export interface AuthHostRuntimeConfig {
     rateLimit: ResolvedRateLimitConfig;
     adminEnabled: boolean;
     adminApiEnabled: boolean;
+    /**
+     * `config.sudo.methods` — a lista que a TELA oferece e que os handlers
+     * ACEITAM. Presente aqui para que `registerAuthHost` MONTE exatamente ela,
+     * em vez de exigir que o host repita a lista no `start/routes.ts`.
+     */
+    sudoMethods?: SudoMethod[];
+    /**
+     * Defaults ESTRUTURAIS declarados em `config.routes` (prefixo do console de
+     * conta, telas montadas, destino de login). Argumentos de `registerAuthHost`
+     * continuam vencendo sobre estes — ver a regra de precedência no docblock de
+     * `registerAuthHost`.
+     */
+    routes?: AuthHostOptions;
+    /**
+     * Opções de POLÍTICA travadas por terem sido declaradas no `defineConfig`.
+     * Ver `deriveLockedRouteOptions`.
+     */
+    lockedRouteOptions?: PolicyRouteOption[];
 }
 /** Stash dos bits de routing (chamado no boot do provider). */
 export declare function setAuthHostConfig(config: AuthHostRuntimeConfig): void;
 /** Lê os bits de routing stashados; undefined se o boot ainda não rodou (fallback p/ opts/defaults). */
 export declare function getAuthHostConfig(): AuthHostRuntimeConfig | undefined;
+/**
+ * Registra que o provider já montou as rotas automaticamente (`config.routes`).
+ * A partir daí uma chamada manual a `registerAuthHost` é um DUPLO REGISTRO —
+ * duas rotas com o mesmo nome derrubam o boot do AdonisJS —, então ela lança
+ * com a instrução de qual dos dois caminhos remover.
+ */
+export declare function markAuthHostAutoMounted(): void;
+/** O provider já auto-montou as rotas neste processo? */
+export declare function wasAuthHostAutoMounted(): boolean;
 /** Limpa o stash — uso em testes. */
 export declare function resetAuthHostConfig(): void;

package/build/src/host/auth_host_config.js

@@ -1,4 +1,5 @@
 let stashed;
+let autoMounted = false;
 /** Stash dos bits de routing (chamado no boot do provider). */
 export function setAuthHostConfig(config) {
     stashed = config;
@@ -7,7 +8,21 @@ export function setAuthHostConfig(config) {
 export function getAuthHostConfig() {
     return stashed;
 }
+/**
+ * Registra que o provider já montou as rotas automaticamente (`config.routes`).
+ * A partir daí uma chamada manual a `registerAuthHost` é um DUPLO REGISTRO —
+ * duas rotas com o mesmo nome derrubam o boot do AdonisJS —, então ela lança
+ * com a instrução de qual dos dois caminhos remover.
+ */
+export function markAuthHostAutoMounted() {
+    autoMounted = true;
+}
+/** O provider já auto-montou as rotas neste processo? */
+export function wasAuthHostAutoMounted() {
+    return autoMounted;
+}
 /** Limpa o stash — uso em testes. */
 export function resetAuthHostConfig() {
     stashed = undefined;
+    autoMounted = false;
 }

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

@@ -22,6 +22,35 @@
  * travam (UI sempre controla).
  */
 export declare function deriveLockedSettingKeys(config: Record<string, any>): string[];
+/**
+ * Opções de rota que são POLÍTICA (decidem o que é PERMITIDO), e não estrutura
+ * (onde as rotas moram). Ver `AuthHostOptions` e o docblock de
+ * `registerAuthHost`.
+ */
+export declare const POLICY_ROUTE_OPTIONS: readonly ["social", "rateLimit", "sudoMethods", "admin", "adminApi"];
+/** Uma opção de política de `AuthHostOptions`. */
+export type PolicyRouteOption = (typeof POLICY_ROUTE_OPTIONS)[number];
+/**
+ * Deriva as opções de rota TRAVADAS a partir dos campos EXPLICITAMENTE presentes
+ * no input do `defineConfig` — a MESMA regra de {@link deriveLockedSettingKeys}
+ * ("declarou no arquivo → o arquivo manda"), aplicada ao outro eixo: config vs.
+ * argumento de `registerAuthHost` (em vez de config vs. runtime setting).
+ *
+ * Travada significa: `registerAuthHost(router, { <key>: ... })` NÃO altera o
+ * comportamento; o valor do config vence e a divergência é reportada
+ * (`AuthHostRouteMap.overriddenByConfig` + `console.warn` no boot).
+ *
+ * O motivo de existir: sem isso, `start/routes.ts` pode AFROUXAR o que o config
+ * declarou — desligar o rate-limit, montar login social que o config não
+ * declara, trocar a lista de métodos de sudo — e o `config/authkit.ts` deixa de
+ * ser auditável (seria preciso ler o routes.ts de cada app para saber o que
+ * está valendo).
+ *
+ * Só trava o que o config DECLARA. Um campo ausente do config nunca trava: o
+ * argumento continua livre (back-compat com quem só configura pelo routes.ts) —
+ * exatamente como `authMethods` só trava os métodos que ele lista.
+ */
+export declare function deriveLockedRouteOptions(config: Record<string, any>): PolicyRouteOption[];
 /** Erro lançado ao tentar gravar/remover uma setting travada via `defineConfig`. */
 export declare class SettingLockedError extends Error {
     readonly code = "E_SETTING_LOCKED";

package/build/src/host/config_locks.js

@@ -43,6 +43,52 @@ export function deriveLockedSettingKeys(config) {
     add(config.ttl !== undefined, SETTING_KEYS.TOKEN_TTL);
     return locked;
 }
+/**
+ * Opções de rota que são POLÍTICA (decidem o que é PERMITIDO), e não estrutura
+ * (onde as rotas moram). Ver `AuthHostOptions` e o docblock de
+ * `registerAuthHost`.
+ */
+export const POLICY_ROUTE_OPTIONS = [
+    'social',
+    'rateLimit',
+    'sudoMethods',
+    'admin',
+    'adminApi',
+];
+/**
+ * Deriva as opções de rota TRAVADAS a partir dos campos EXPLICITAMENTE presentes
+ * no input do `defineConfig` — a MESMA regra de {@link deriveLockedSettingKeys}
+ * ("declarou no arquivo → o arquivo manda"), aplicada ao outro eixo: config vs.
+ * argumento de `registerAuthHost` (em vez de config vs. runtime setting).
+ *
+ * Travada significa: `registerAuthHost(router, { <key>: ... })` NÃO altera o
+ * comportamento; o valor do config vence e a divergência é reportada
+ * (`AuthHostRouteMap.overriddenByConfig` + `console.warn` no boot).
+ *
+ * O motivo de existir: sem isso, `start/routes.ts` pode AFROUXAR o que o config
+ * declarou — desligar o rate-limit, montar login social que o config não
+ * declara, trocar a lista de métodos de sudo — e o `config/authkit.ts` deixa de
+ * ser auditável (seria preciso ler o routes.ts de cada app para saber o que
+ * está valendo).
+ *
+ * Só trava o que o config DECLARA. Um campo ausente do config nunca trava: o
+ * argumento continua livre (back-compat com quem só configura pelo routes.ts) —
+ * exatamente como `authMethods` só trava os métodos que ele lista.
+ */
+export function deriveLockedRouteOptions(config) {
+    const locked = [];
+    if (config.social !== undefined)
+        locked.push('social');
+    if (config.rateLimit !== undefined)
+        locked.push('rateLimit');
+    if (config.sudo?.methods !== undefined)
+        locked.push('sudoMethods');
+    if (config.admin !== undefined)
+        locked.push('admin');
+    if (config.adminApi !== undefined)
+        locked.push('adminApi');
+    return locked;
+}
 /** Erro lançado ao tentar gravar/remover uma setting travada via `defineConfig`. */
 export class SettingLockedError extends Error {
     code = 'E_SETTING_LOCKED';

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

@@ -9,10 +9,46 @@ import type { HttpContext } from '@adonisjs/core/http';
  * sessão mudar.
  */
 /**
- * Retorna o id da conta logada no console (ou `null` quando não há
- * sessão).
+ * Retorna o id da conta que o request está representando no console (ou `null`
+ * quando não há sessão).
+ *
+ * ATENÇÃO: com impersonation ativa isto é a conta PERSONIFICADA, não o admin
+ * que a personificou. É o comportamento certo para "como qual conta este
+ * request está agindo?" e é a entrada ERRADA para uma checagem de
+ * permissão/role — para isso use `realAccountId`.
  */
 export declare function getAccountId(ctx: HttpContext): string | null;
+/**
+ * Retorna o id do HUMANO real por trás do request — o id que uma decisão de
+ * autorização deve usar.
+ *
+ * ```
+ * impersonation ativa  → o id do impersonator (o admin real)
+ * sem impersonation    → o id da conta logada
+ * sem sessão           → null
+ * ```
+ *
+ * USE ESTE em qualquer checagem de permissão/role ("esta pessoa é admin?",
+ * "esta pessoa pode aprovar isto?"). Use `getAccountId` só para responder
+ * "como qual conta este request está agindo?" (queries com escopo no alvo,
+ * UI, banner de impersonation).
+ *
+ * POR QUE ISSO EXISTE. Durante uma impersonation, `getAccountId` devolve a
+ * conta PERSONIFICADA — é o comportamento correto dele e o resto do app
+ * depende disso. Mas ele é, por isso mesmo, a entrada ERRADA para um role
+ * check: perguntar "o `getAccountId` é admin?" com impersonation ativa
+ * pergunta sobre o usuário personificado e, quando ele por acaso for admin,
+ * entrega os privilégios do admin a quem está sendo personificado — e, no
+ * sentido inverso, faz o admin real perder o próprio acesso. `realAccountId`
+ * ignora a troca de conta e responde sempre sobre quem está de fato dirigindo
+ * a sessão.
+ *
+ * @example
+ * // gate de /admin: a pessoa por trás do request é admin?
+ * const id = realAccountId(ctx)
+ * if (!id || !(await authz.hasRole(id, 'admin'))) throw new Error('forbidden')
+ */
+export declare function realAccountId(ctx: HttpContext): string | null;
 /**
  * `true` quando o request carrega uma sessão de conta do console.
  */