@adonis-agora/authkit-server 0.34.0

package/build/src/host/register_auth_host.js

@@ -0,0 +1,466 @@
+import { resolveRateLimit } from '../define_config.js';
+import { createAuthThrottles } from './rate_limit.js';
+import { ACCOUNT_SESSION_KEY } from './middleware/account_auth.js';
+import { accountHome } from './account_home.js';
+import { adminApiGuard } from './admin_api/admin_api_guard.js';
+import { setAdminPrefix, normalizeAdminPrefix, setAdminApiPrefix, normalizeAdminApiPrefix, } from './admin_prefix.js';
+import { resolveRuntimeSettings } from './runtime_settings.js';
+import { resolveEffectiveSessionPolicy } from './runtime_toggles.js';
+import { getAuthHostConfig } from './auth_host_config.js';
+/** Chave da sessão Adonis que registra o timestamp da última atividade (idle timeout). */
+export const ACCOUNT_LAST_SEEN_KEY = 'authkit_last_seen';
+/**
+ * Verifica o idle timeout da sessão do console de conta. Lê `idleTimeoutMinutes`
+ * da setting `session_policy` (runtime, fail-safe). Se a sessão excedeu o idle,
+ * apaga a sessão e retorna true (caller deve redirecionar ao login).
+ *
+ * Sempre atualiza `authkit_last_seen` quando o idle não foi excedido.
+ *
+ * FAIL-SAFE: qualquer erro → nunca encerra a sessão (disponibilidade > segurança).
+ */
+async function checkAndRefreshIdle(ctx) {
+    try {
+        // Fábrica canônica (searchPath-aware via a conexão do accountStore). Null =
+        // container/DB indisponível → fail-safe: nunca encerra a sessão.
+        const runtimeSettings = await resolveRuntimeSettings(ctx);
+        if (!runtimeSettings)
+            return false;
+        const policy = await resolveEffectiveSessionPolicy(runtimeSettings);
+        const idleMs = policy.idleTimeoutMinutes * 60 * 1000;
+        if (idleMs <= 0)
+            return false; // idle desligado
+        const lastSeen = ctx.session?.get(ACCOUNT_LAST_SEEN_KEY);
+        const now = Date.now();
+        if (lastSeen !== undefined && now - lastSeen > idleMs) {
+            // Idle excedido: encerra a sessão.
+            ctx.session?.forget(ACCOUNT_SESSION_KEY);
+            ctx.session?.forget(ACCOUNT_LAST_SEEN_KEY);
+            return true;
+        }
+        // Atualiza o timestamp de última atividade.
+        ctx.session?.put(ACCOUNT_LAST_SEEN_KEY, now);
+        return false;
+    }
+    catch {
+        // FAIL-SAFE: nunca encerra a sessão em caso de erro.
+        return false;
+    }
+}
+/**
+ * Constrói a URL de redirect para o login da conta, preservando o destino
+ * original como `return_to` (URL-encoded). A URL de destino é o path + query
+ * string da requisição atual (nunca o host — proteção contra open-redirect).
+ *
+ * @internal
+ */
+function buildLoginRedirect(ctx, extra) {
+    const url = ctx.request?.url?.() ?? '';
+    const qs = ctx.request?.parsedUrl?.search ?? '';
+    const dest = qs ? `${url}${qs}` : url;
+    // Só inclui return_to quando há um caminho real (não vazio, não é o próprio login).
+    if (dest && dest !== '/' && !dest.startsWith('/account/login')) {
+        const encoded = encodeURIComponent(dest);
+        const base = extra ? `/account/login?${extra}&return_to=${encoded}` : `/account/login?return_to=${encoded}`;
+        return base;
+    }
+    return extra ? `/account/login?${extra}` : '/account/login';
+}
+/**
+ * Guard inline do console de conta. Usamos uma closure (forma confiável do
+ * `.use()` do AdonisJS) em vez de `() => import(middleware)` — a forma lazy de
+ * classe NÃO era aplicada em runtime num grupo, deixando /account/tokens e
+ * /account/mfa acessíveis sem sessão.
+ */
+const accountGuard = async (ctx, next) => {
+    if (!ctx.session?.get(ACCOUNT_SESSION_KEY)) {
+        return ctx.response.redirect(buildLoginRedirect(ctx));
+    }
+    // Idle timeout: encerra e redireciona com query param de motivo.
+    const idleExpired = await checkAndRefreshIdle(ctx);
+    if (idleExpired) {
+        return ctx.response.redirect(buildLoginRedirect(ctx, 'reason=idle'));
+    }
+    return next();
+};
+/**
+ * Guard do console admin (B6). Como o `accountGuard`, é uma closure inline (forma
+ * confiável do `.use()` num grupo). Exige:
+ *   0. `config.admin.enabled` ligado (senão → 404; ver nota de flag-drift abaixo);
+ *   1. sessão de conta ativa (senão → /account/login);
+ *   2. a conta logada com pelo menos UMA das `config.admin.roles` nas roles globais
+ *      (senão → /account/tokens, evitando vazar a existência do /admin).
+ * As roles permitidas são resolvidas em runtime do `authkit.server` (config lazy).
+ */
+export const adminGuard = async (ctx, next) => {
+    const service = await ctx.containerResolver.make('authkit.server');
+    const cfg = service.config;
+    // Defesa contra flag-drift: as rotas são montadas com `admin: true` em tempo de
+    // registro, ANTES de o config resolver. Se o config tiver `admin.enabled: false`,
+    // as rotas existem mas o console deve estar desligado — 404 (não vaza a existência).
+    if (!cfg.admin.enabled) {
+        return ctx.response.notFound();
+    }
+    const accountId = ctx.session?.get(ACCOUNT_SESSION_KEY);
+    if (!accountId) {
+        // `/account/login` é sempre o login da conta — NÃO muda com o prefixo admin.
+        return ctx.response.redirect(buildLoginRedirect(ctx));
+    }
+    // Idle timeout: também protege o console admin.
+    const idleExpired = await checkAndRefreshIdle(ctx);
+    if (idleExpired) {
+        return ctx.response.redirect(buildLoginRedirect(ctx, 'reason=idle'));
+    }
+    const allowed = cfg.admin.roles;
+    const account = await cfg.accountStore.findById(accountId);
+    const roles = account?.globalRoles ?? [];
+    const isAdmin = roles.some((r) => allowed.includes(r));
+    if (!isAdmin) {
+        // Evita vazar a existência do console admin: redireciona para o accountHome
+        // (sem mostrar a URL do admin).
+        return ctx.response.redirect(accountHome(cfg));
+    }
+    return next();
+};
+const C = {
+    oidc: () => import('../controllers/oidc_callback_controller.js'),
+    interaction: () => import('./controllers/interaction_controller.js'),
+    registration: () => import('./controllers/registration_controller.js'),
+    social: () => import('./controllers/social_controller.js'),
+    patIntrospection: () => import('./controllers/pat_introspection_controller.js'),
+    accountSession: () => import('./controllers/account_session_controller.js'),
+    accountTokens: () => import('./controllers/account_tokens_controller.js'),
+    accountSecurity: () => import('./controllers/account_security_controller.js'),
+    accountApps: () => import('./controllers/account_apps_controller.js'),
+    accountMfa: () => import('./controllers/account_mfa_controller.js'),
+    accountOrgs: () => import('./controllers/account_orgs_controller.js'),
+    accountConfirm: () => import('./controllers/account_confirm_controller.js'),
+    // Console React JSON API (session-authed, under {prefix}/api/*).
+    consoleShell: () => import('./admin_console/admin_shell_controller.js'),
+    consoleOverview: () => import('./admin_console/console_overview_controller.js'),
+    consoleUsers: () => import('./admin_console/console_users_controller.js'),
+    consoleSessions: () => import('./admin_console/console_sessions_controller.js'),
+    consoleClients: () => import('./admin_console/console_clients_controller.js'),
+    consoleRoles: () => import('./admin_console/console_roles_controller.js'),
+    consoleOrgs: () => import('./admin_console/console_orgs_controller.js'),
+    consoleAudit: () => import('./admin_console/console_audit_controller.js'),
+    consoleSettings: () => import('./admin_console/console_settings_controller.js'),
+    consoleKeys: () => import('./admin_console/console_keys_controller.js'),
+    consoleImpersonation: () => import('./admin_console/console_impersonation_controller.js'),
+    apiUsers: () => import('./admin_api/api_users_controller.js'),
+    apiClients: () => import('./admin_api/api_clients_controller.js'),
+    apiMisc: () => import('./admin_api/api_misc_controller.js'),
+    apiOrgs: () => import('./admin_api/api_orgs_controller.js'),
+    apiSettings: () => import('./admin_api/api_settings_controller.js'),
+    apiKeys: () => import('./admin_api/api_keys_controller.js'),
+    // Account self-service JSON API (session-authed, under /account/api/*).
+    accountApi: () => import('./account_api/account_api_controller.js'),
+};
+/**
+ * Monta todas as rotas do host-kit do Authorization Server numa chamada.
+ * Substitui registerOidcRoutes + o hand-wiring do start/routes.ts do host.
+ */
+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.
+    // 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);
+    // Throttles opt-in (anti-brute-force). `undefined` quando rate-limit desligado.
+    const resolvedRateLimit = opts.rateLimit !== undefined
+        ? resolveRateLimit(opts.rateLimit)
+        : (hostCfg?.rateLimit ?? resolveRateLimit(undefined));
+    const throttles = createAuthThrottles(resolvedRateLimit);
+    // Helpers: aplicam o middleware de throttle quando presente; senão no-op.
+    const withLogin = (route) => {
+        if (throttles)
+            route.use([throttles.login]);
+    };
+    const withIntrospection = (route) => {
+        if (throttles)
+            route.use([throttles.introspection]);
+    };
+    // Provider OIDC (wildcard + root) — o que registerOidcRoutes fazia.
+    router.any(`${mount}/*`, [C.oidc]).as('authkit.oidc.wildcard');
+    router.any(mount, [C.oidc]).as('authkit.oidc.root');
+    // Interaction (login multi-step + consent + signup).
+    router.get('/auth/interaction/:uid', [C.interaction, 'show']);
+    router.post('/auth/interaction/:uid/identifier', [C.interaction, 'identifier']);
+    withLogin(router.post('/auth/interaction/:uid/login', [C.interaction, 'login']));
+    withLogin(router.post('/auth/interaction/:uid/mfa', [C.interaction, 'mfaVerify']));
+    // Troca de senha obrigatória quando a senha expirou (password expiration gate).
+    withLogin(router.post('/auth/interaction/:uid/password-expired', [C.interaction, 'changeExpiredPassword']));
+    // Passkey como 2º fator alternativo no login (begin/finish; challenge na sessão).
+    router.post('/auth/interaction/:uid/passkey/options', [C.interaction, 'passkeyOptions']);
+    withLogin(router.post('/auth/interaction/:uid/passkey/verify', [C.interaction, 'passkeyVerify']));
+    // Magic link (passwordless): POST emite (throttled), GET consome o token do link.
+    withLogin(router.post('/auth/interaction/:uid/magic', [C.interaction, 'magicLinkRequest']));
+    router.get('/auth/interaction/:uid/magic', [C.interaction, 'magicLinkConsume']);
+    router.post('/auth/interaction/:uid/consent', [C.interaction, 'consent']);
+    router.get('/auth/interaction/:uid/switch', [C.interaction, 'switchIdentifier']);
+    // OTP unlock: link enviado por e-mail quando o fator TOTP/recovery é travado.
+    router.get('/auth/otp-unlock/:token', [C.interaction, 'otpUnlock']);
+    router.get('/auth/interaction/:uid/signup', [C.registration, 'showSignup']);
+    withLogin(router.post('/auth/interaction/:uid/signup', [C.registration, 'signup']));
+    // Recuperação de senha (standalone).
+    router.get('/auth/forgot-password', [C.registration, 'showForgot']);
+    withLogin(router.post('/auth/forgot-password', [C.registration, 'forgot']));
+    router.get('/auth/reset-password', [C.registration, 'showReset']);
+    withLogin(router.post('/auth/reset-password', [C.registration, 'reset']));
+    // Verificação de e-mail (standalone, GET-only — consome o token do link).
+    router.get('/auth/verify-email', [C.registration, 'verifyEmail']);
+    // Login social (opt-in — do config ou opts).
+    if (social) {
+        router.get('/auth/:provider/redirect/:uid', [C.social, 'redirect']);
+        router.get('/auth/:provider/callback', [C.social, 'callback']);
+    }
+    // PAT introspection (server-to-server).
+    withIntrospection(router.post('/authkit/pat/introspect', [C.patIntrospection, 'handle']));
+    // Organizations — invitation accept (sem guard: controller lida com não-autenticado).
+    router.get('/account/orgs/invitations/:token/accept', [C.accountOrgs, 'showAcceptInvitation']);
+    router.post('/account/orgs/invitations/:token/accept', [C.accountOrgs, 'acceptInvitation']);
+    // Console de conta (login de sessão do IdP + gerência de PAT).
+    router.get('/account/login', [C.accountSession, 'show']);
+    // L6: throttle por IP no login/logout do console de conta (anti-brute-force),
+    // alinhado com as demais rotas de credencial (interaction, forgot, reset).
+    withLogin(router.post('/account/login', [C.accountSession, 'login']));
+    withLogin(router.post('/account/logout', [C.accountSession, 'logout']));
+    // Confirmação de troca de e-mail (standalone, GET-only — consome o token do link;
+    // pode ser aberta em outro dispositivo, então NÃO exige sessão).
+    router.get('/account/email/confirm', [C.accountSecurity, 'confirmEmail']);
+    // Rotas de tokens protegidas por AccountAuthMiddleware (redireciona para /account/login se não autenticado).
+    router
+        .group(() => {
+        router.get('/account/tokens', [C.accountTokens, 'index']);
+        router.post('/account/tokens', [C.accountTokens, 'store']);
+        router.post('/account/tokens/:id/revoke', [C.accountTokens, 'destroy']);
+        // Segurança da conta: trocar senha + solicitar troca de e-mail + perfil.
+        router.get('/account/security', [C.accountSecurity, 'index']);
+        router.post('/account/security/password', [C.accountSecurity, 'changePassword']);
+        router.post('/account/security/email', [C.accountSecurity, 'changeEmail']);
+        router.post('/account/security/email/cancel', [C.accountSecurity, 'cancelEmailChange']);
+        router.post('/account/security/profile', [C.accountSecurity, 'updateProfile']);
+        // LGPD/GDPR: export de dados (portabilidade) + deleção self-service (danger zone).
+        // O export carrega o throttle de login (anti-abuso) quando o rate-limit existe.
+        withLogin(router.get('/account/security/export', [C.accountSecurity, 'exportData']));
+        router.post('/account/security/delete', [C.accountSecurity, 'deleteAccount']);
+        // Trusted devices: limpa o cookie de confiança DESTE navegador.
+        router.post('/account/security/trusted-devices/revoke', [
+            C.accountSecurity,
+            'revokeTrustedDevices',
+        ]);
+        // Apps com acesso (consentimento): lista os grants da conta + revogação por client.
+        router.get('/account/apps', [C.accountApps, 'index']);
+        router.post('/account/apps/:clientId/revoke', [C.accountApps, 'revoke']);
+        // MFA / TOTP (enrollment, confirmação, disable).
+        router.get('/account/mfa', [C.accountMfa, 'index']);
+        router.post('/account/mfa/enroll', [C.accountMfa, 'enroll']);
+        router.post('/account/mfa/confirm', [C.accountMfa, 'confirm']);
+        router.post('/account/mfa/disable', [C.accountMfa, 'disable']);
+        // MFA / WebAuthn (passkeys): registro (begin/finish) + remoção.
+        router.post('/account/mfa/passkeys/options', [C.accountMfa, 'passkeyRegisterOptions']);
+        router.post('/account/mfa/passkeys/verify', [C.accountMfa, 'passkeyRegisterVerify']);
+        router.post('/account/mfa/passkeys/:id/remove', [C.accountMfa, 'passkeyRemove']);
+        // Sudo mode (confirm identity): GET exibe o formulário; POST verifica a senha.
+        router.get('/account/confirm', [C.accountConfirm, 'show']);
+        router.post('/account/confirm', [C.accountConfirm, 'confirm']);
+        router.post('/account/confirm/passkey/options', [C.accountConfirm, 'passkeyOptions']);
+        router.post('/account/confirm/passkey', [C.accountConfirm, 'passkeyConfirm']);
+        // Organizations (multi-tenancy) — sempre montadas; controller retorna 404/403 sem tabelas.
+        router.get('/account/orgs', [C.accountOrgs, 'index']);
+        router.post('/account/orgs', [C.accountOrgs, 'store']);
+        router.post('/account/orgs/deactivate', [C.accountOrgs, 'deactivate']);
+        router.post('/account/orgs/:id/activate', [C.accountOrgs, 'activate']);
+        router.post('/account/orgs/:id/leave', [C.accountOrgs, 'leave']);
+        router.post('/account/orgs/:id/invite', [C.accountOrgs, 'invite']);
+        router.post('/account/orgs/:id/members/:accountId/remove', [C.accountOrgs, 'removeMember']);
+        router.post('/account/orgs/:id/invitations/:invId/revoke', [C.accountOrgs, 'revokeInvitation']);
+        // JSON endpoints for React hooks (authkit-react).
+        router.get('/account/orgs/json', [C.accountOrgs, 'listJson']);
+        router.get('/account/orgs/invitations/json', [C.accountOrgs, 'listInvitationsJson']);
+        router.get('/account/orgs/:id/json', [C.accountOrgs, 'showJson']);
+        // ─── Account self-service JSON API (authkit-react TanStack hooks) ─────
+        // ⚠️ ORDER MATTERS: fixed-segment routes before parameterised ones.
+        // Registered INSIDE the accountGuard group → same session-auth protection.
+        // Mutating routes use CSRF (shield middleware on the host app).
+        router.get('/account/api/me', [C.accountApi, 'me']);
+        router.get('/account/api/security', [C.accountApi, 'securityOverview']);
+        router.patch('/account/api/profile', [C.accountApi, 'updateProfile']);
+        router.post('/account/api/password', [C.accountApi, 'changePassword']);
+        // Email-change: cancel BEFORE the generic post to avoid pattern collision.
+        router.post('/account/api/email-change/cancel', [C.accountApi, 'cancelEmailChange']);
+        router.post('/account/api/email-change', [C.accountApi, 'requestEmailChange']);
+        // Sessions: fixed routes BEFORE :id.
+        router.get('/account/api/sessions', [C.accountApi, 'listSessions']);
+        router.post('/account/api/sessions/revoke-others', [C.accountApi, 'revokeOtherSessions']);
+        router.post('/account/api/sessions/revoke-all', [C.accountApi, 'revokeAllSessions']);
+        router.delete('/account/api/sessions/:id', [C.accountApi, 'revokeSession']);
+        // Apps (grants).
+        router.get('/account/api/apps', [C.accountApi, 'listApps']);
+        router.delete('/account/api/apps/:clientId', [C.accountApi, 'revokeApp']);
+        // MFA + passkeys.
+        router.get('/account/api/mfa', [C.accountApi, 'mfaStatus']);
+        router.get('/account/api/passkeys', [C.accountApi, 'listPasskeys']);
+        router.delete('/account/api/passkeys/:id', [C.accountApi, 'removePasskey']);
+        // PATs.
+        router.get('/account/api/tokens', [C.accountApi, 'listTokens']);
+        router.post('/account/api/tokens', [C.accountApi, 'createToken']);
+        router.delete('/account/api/tokens/:id', [C.accountApi, 'revokeToken']);
+        // Orgs: invitations BEFORE :id (fixed segment before parameterised).
+        router.get('/account/api/orgs', [C.accountApi, 'listOrgs']);
+        router.get('/account/api/orgs/invitations', [C.accountApi, 'listOrgInvitations']);
+        router.get('/account/api/orgs/:id', [C.accountApi, 'showOrg']);
+    })
+        .use([accountGuard]);
+    // 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);
+        // Persiste no singleton de processo para que controllers e views usem o mesmo prefixo.
+        setAdminPrefix(ap);
+        router
+            .group(() => {
+            // Console admin (SPA React self-contained): todas as rotas GET servem o
+            // shell HTML; os endpoints JSON sob {prefix}/api/* são a fonte de dados da SPA.
+            // ⚠️ ORDEM IMPORTA: o AdonisJS casa rotas wildcard por ORDEM DE REGISTRO.
+            // Os assets e TODA a JSON API `/api/*` precisam ser registrados ANTES do
+            // catch-all `${ap}/*` (que serve o shell HTML), senão o catch-all engole
+            // `/api/*` e devolve HTML onde a SPA espera JSON ("Unexpected token '<'").
+            // ─── Assets estáticos do Vite build ───────────────────────────────────
+            router.get(`${ap}/assets/*`, [C.consoleShell, 'serveAsset']).as('authkit_console_assets');
+            // ─── JSON API do console (session-authed via adminGuard upstream) ─────
+            // GET {ap}/api/overview
+            router.get(`${ap}/api/overview`, [C.consoleOverview, 'handle']);
+            // Usuários.
+            router.get(`${ap}/api/users`, [C.consoleUsers, 'index']);
+            router.get(`${ap}/api/users/:id`, [C.consoleUsers, 'show']);
+            router.post(`${ap}/api/users`, [C.consoleUsers, 'store']);
+            router.patch(`${ap}/api/users/:id/roles`, [C.consoleUsers, 'updateRoles']);
+            router.post(`${ap}/api/users/:id/disable`, [C.consoleUsers, 'disable']);
+            router.post(`${ap}/api/users/:id/enable`, [C.consoleUsers, 'enable']);
+            router.post(`${ap}/api/users/:id/reset-password`, [C.consoleUsers, 'resetPassword']);
+            router.delete(`${ap}/api/users/:id`, [C.consoleUsers, 'destroy']);
+            // Sessões.
+            router.get(`${ap}/api/sessions`, [C.consoleSessions, 'index']);
+            router.post(`${ap}/api/sessions/revoke-all`, [C.consoleSessions, 'revokeAll']);
+            // Sessões por usuário (drawer do user — ANTES do catch-all para não receber HTML).
+            router.get(`${ap}/api/users/:id/sessions`, [C.consoleSessions, 'userSessions']);
+            router.post(`${ap}/api/users/:id/revoke-sessions`, [C.consoleSessions, 'userRevokeSessions']);
+            // Clients OIDC.
+            router.get(`${ap}/api/clients`, [C.consoleClients, 'index']);
+            router.post(`${ap}/api/clients`, [C.consoleClients, 'store']);
+            router.patch(`${ap}/api/clients/:id`, [C.consoleClients, 'update']);
+            router.delete(`${ap}/api/clients/:id`, [C.consoleClients, 'destroy']);
+            router.post(`${ap}/api/clients/:id/regenerate-secret`, [C.consoleClients, 'regenerateSecret']);
+            // Roles.
+            router.get(`${ap}/api/roles`, [C.consoleRoles, 'index']);
+            router.post(`${ap}/api/roles`, [C.consoleRoles, 'store']);
+            router.patch(`${ap}/api/roles/:name`, [C.consoleRoles, 'update']);
+            router.delete(`${ap}/api/roles/:name`, [C.consoleRoles, 'destroy']);
+            // Organizações (capability-gated: 404 quando store não suporta).
+            // ⚠️ Rotas fixas ANTES de parametrizadas para evitar shadowing.
+            router.get(`${ap}/api/orgs`, [C.consoleOrgs, 'index']);
+            router.post(`${ap}/api/orgs`, [C.consoleOrgs, 'store']);
+            router.get(`${ap}/api/orgs/:id`, [C.consoleOrgs, 'show']);
+            router.patch(`${ap}/api/orgs/:id`, [C.consoleOrgs, 'update']);
+            router.delete(`${ap}/api/orgs/:id`, [C.consoleOrgs, 'destroy']);
+            // Membros: PATCH (role) ANTES de DELETE para não colidir, ambos antes do catch-all.
+            router.post(`${ap}/api/orgs/:id/members`, [C.consoleOrgs, 'addMember']);
+            router.patch(`${ap}/api/orgs/:id/members/:accountId`, [C.consoleOrgs, 'updateMemberRole']);
+            router.delete(`${ap}/api/orgs/:id/members/:accountId`, [C.consoleOrgs, 'removeMember']);
+            // Convites.
+            router.post(`${ap}/api/orgs/:id/invitations`, [C.consoleOrgs, 'createInvitation']);
+            router.delete(`${ap}/api/orgs/:id/invitations/:invitationId`, [C.consoleOrgs, 'revokeInvitation']);
+            // Auditoria (capability-gated: 404 quando sink não suporta consulta).
+            router.get(`${ap}/api/audit`, [C.consoleAudit, 'index']);
+            // Settings.
+            router.get(`${ap}/api/settings`, [C.consoleSettings, 'index']);
+            router.put(`${ap}/api/settings/:key`, [C.consoleSettings, 'upsert']);
+            router.delete(`${ap}/api/settings/:key`, [C.consoleSettings, 'destroy']);
+            // Chave de assinatura managed (status + rotação ao vivo).
+            router.get(`${ap}/api/keys`, [C.consoleKeys, 'status']);
+            router.post(`${ap}/api/keys/rotate`, [C.consoleKeys, 'rotate']);
+            // Impersonation (capability-gated: 404 quando desabilitado ou sem client).
+            router.get(`${ap}/api/impersonation/:userId`, [C.consoleImpersonation, 'handle']);
+            // ─── Shell HTML — POR ÚLTIMO (catch-all) ──────────────────────────────
+            // Serve a SPA para todas as demais rotas GET do console; o roteamento
+            // client-side (hash) é tratado pela SPA. Nomes explícitos: o mesmo par
+            // controller.método em duas rotas colide no auto-naming do AdonisJS.
+            router.get(ap, [C.consoleShell, 'serve']).as('authkit_console_root');
+            router.get(`${ap}/*`, [C.consoleShell, 'serve']).as('authkit_console_shell');
+        })
+            .use([adminGuard]);
+    }
+    // Admin REST API (opt-in — R6). Superfície machine-to-machine atrás do
+    // adminApiGuard (API key). Todas as rotas levam o throttle de introspecção.
+    if (adminApiOpt) {
+        // Resolve o prefixo: `true` → '/api/authkit/v1' (default); objeto → usa prefix fornecido.
+        const rawApiPrefix = typeof adminApiOpt === 'object' && adminApiOpt.prefix
+            ? adminApiOpt.prefix
+            : '/api/authkit/v1';
+        const aap = normalizeAdminApiPrefix(rawApiPrefix);
+        // 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);
+        // Aplica o throttle de introspecção a uma rota qualquer (GET ou escrita).
+        const withApiThrottle = (route) => {
+            if (throttles)
+                route.use([throttles.introspection]);
+            return route;
+        };
+        router
+            .group(() => {
+            // Usuários.
+            withApiThrottle(router.get('/users', [C.apiUsers, 'index']));
+            withApiThrottle(router.post('/users', [C.apiUsers, 'store']));
+            withApiThrottle(router.get('/users/:id', [C.apiUsers, 'show']));
+            withApiThrottle(router.patch('/users/:id', [C.apiUsers, 'update']));
+            withApiThrottle(router.delete('/users/:id', [C.apiUsers, 'destroy']));
+            withApiThrottle(router.post('/users/:id/disable', [C.apiUsers, 'disable']));
+            withApiThrottle(router.post('/users/:id/enable', [C.apiUsers, 'enable']));
+            withApiThrottle(router.post('/users/:id/reset-password', [C.apiUsers, 'resetPassword']));
+            withApiThrottle(router.get('/users/:id/sessions', [C.apiUsers, 'sessions']));
+            withApiThrottle(router.post('/users/:id/revoke-sessions', [C.apiUsers, 'revokeSessions']));
+            // Clients OIDC.
+            withApiThrottle(router.get('/clients', [C.apiClients, 'index']));
+            withApiThrottle(router.post('/clients', [C.apiClients, 'store']));
+            withApiThrottle(router.get('/clients/:id', [C.apiClients, 'show']));
+            withApiThrottle(router.patch('/clients/:id', [C.apiClients, 'update']));
+            withApiThrottle(router.post('/clients/:id/regenerate-secret', [C.apiClients, 'regenerateSecret']));
+            withApiThrottle(router.delete('/clients/:id', [C.apiClients, 'destroy']));
+            // Organizações.
+            withApiThrottle(router.get('/organizations', [C.apiOrgs, 'index']));
+            withApiThrottle(router.post('/organizations', [C.apiOrgs, 'store']));
+            withApiThrottle(router.get('/organizations/:id', [C.apiOrgs, 'show']));
+            withApiThrottle(router.patch('/organizations/:id', [C.apiOrgs, 'update']));
+            withApiThrottle(router.delete('/organizations/:id', [C.apiOrgs, 'destroy']));
+            withApiThrottle(router.post('/organizations/:id/members', [C.apiOrgs, 'addMember']));
+            withApiThrottle(router.delete('/organizations/:id/members/:accountId', [C.apiOrgs, 'removeMember']));
+            withApiThrottle(router.patch('/organizations/:id/members/:accountId', [C.apiOrgs, 'updateMemberRole']));
+            withApiThrottle(router.post('/organizations/:id/invitations', [C.apiOrgs, 'createInvitation']));
+            withApiThrottle(router.delete('/organizations/:id/invitations/:invitationId', [C.apiOrgs, 'revokeInvitation']));
+            // Auditoria + métricas + verificação de token.
+            withApiThrottle(router.get('/audit', [C.apiMisc, 'audit']));
+            withApiThrottle(router.get('/stats', [C.apiMisc, 'stats']));
+            withApiThrottle(router.post('/tokens/verify', [C.apiMisc, 'verify']));
+            // Runtime settings CRUD.
+            withApiThrottle(router.get('/settings', [C.apiSettings, 'index']));
+            withApiThrottle(router.get('/settings/:key', [C.apiSettings, 'show']));
+            withApiThrottle(router.put('/settings/:key', [C.apiSettings, 'upsert']));
+            withApiThrottle(router.delete('/settings/:key', [C.apiSettings, 'destroy']));
+            // Chave de assinatura managed (status + rotação ao vivo).
+            withApiThrottle(router.get('/keys', [C.apiKeys, 'status']));
+            withApiThrottle(router.post('/keys/rotate', [C.apiKeys, 'rotate']));
+        })
+            .prefix(aap)
+            // Throttle por IP do grupo inteiro (M8): roda ANTES da guard, então tentativas
+            // de Bearer key inválida do mesmo IP são limitadas mesmo quando a auth falha.
+            // O `withApiThrottle` (introspection, por token) continua como camada adicional.
+            .use(throttles ? [throttles.adminIp, adminApiGuard] : [adminApiGuard]);
+    }
+}

package/build/src/host/renderers/edge_renderer.d.ts

@@ -0,0 +1,12 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Função low-level que renderiza uma view Edge built-in da lib sem criar um
+ * closure. Usada internamente pelo `edgeRenderer()` e pelo `inertiaRenderer()`
+ * como fallback silencioso para views não listadas no allowlist (incluindo todas
+ * as telas `admin/*`).
+ *
+ * @internal Exportada para reuso — não faz parte da API pública do seam.
+ */
+export declare function renderEdgeView(ctx: HttpContext, view: string, props: Record<string, unknown>): Promise<unknown>;
+/** Renderer do seam para hosts Edge. As views são donas-da-lib (disco `authkit::`). */
+export declare function edgeRenderer(): (ctx: HttpContext, view: string, props: Record<string, unknown>) => Promise<unknown>;

package/build/src/host/renderers/edge_renderer.js

@@ -0,0 +1,38 @@
+import { DEFAULT_MESSAGES, translate } from '../i18n.js';
+/**
+ * Resolve o catálogo de mensagens ativo a partir do `authkit.server` (config
+ * resolvida com o locale do host). Defensivo: se o container/serviço não estiver
+ * disponível (ex.: teste unitário do renderer com ctx mockado), cai no default
+ * pt-BR embutido — as views continuam renderizando.
+ */
+async function resolveMessagesFromCtx(ctx) {
+    try {
+        const service = await ctx.containerResolver?.make?.('authkit.server');
+        const messages = service?.config?.messages;
+        if (messages)
+            return messages;
+    }
+    catch {
+        // sem container/serviço — usa o default
+    }
+    return { ...DEFAULT_MESSAGES };
+}
+/**
+ * Função low-level que renderiza uma view Edge built-in da lib sem criar um
+ * closure. Usada internamente pelo `edgeRenderer()` e pelo `inertiaRenderer()`
+ * como fallback silencioso para views não listadas no allowlist (incluindo todas
+ * as telas `admin/*`).
+ *
+ * @internal Exportada para reuso — não faz parte da API pública do seam.
+ */
+export async function renderEdgeView(ctx, view, props) {
+    const messages = await resolveMessagesFromCtx(ctx);
+    const t = (key, params) => translate(messages, key, params);
+    return ctx.view.render(`authkit::${view}`, { ...props, t, messages });
+}
+/** Renderer do seam para hosts Edge. As views são donas-da-lib (disco `authkit::`). */
+export function edgeRenderer() {
+    return async (ctx, view, props) => {
+        return renderEdgeView(ctx, view, props);
+    };
+}

package/build/src/host/renderers/inertia_renderer.d.ts

@@ -0,0 +1,70 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Opções do renderer Inertia/React.
+ */
+export interface InertiaRendererOptions {
+    /**
+     * Prefixo das páginas no diretório `inertia/pages/` do host.
+     * Ex.: `'authkit'` → a view `login` mapeia para `inertia/pages/authkit/login.tsx`.
+     */
+    prefix: string;
+    /**
+     * Lista de nomes de view que o host criou como páginas React (allowlist).
+     *
+     * Quando fornecida, **somente** as views listadas passam pelo Inertia; qualquer
+     * outra view (não listada, ou prefixada com `admin/`) recai silenciosamente no
+     * renderer Edge built-in da lib — sem erro 500.
+     *
+     * ### ⚠️ Atenção: sem `views`, qualquer tela nova da lib quebra hosts SSR
+     *
+     * Se `views` for omitido, o comportamento legado é preservado (todas as views
+     * são enviadas ao Inertia) para compatibilidade retroativa. Nesse modo, qualquer
+     * tela nova adicionada pela lib gerará um erro SSR no host ("Cannot read
+     * properties of undefined (reading 'default')") porque o host não terá criado a
+     * página React correspondente. **Recomenda-se sempre fornecer `views`** com
+     * exatamente as páginas que o scaffold (`node ace configure`) gerou.
+     *
+     * A ordem do array é irrelevante — `views` é tratado como um *conjunto*
+     * (allowlist). Os nomes têm autocomplete via {@link AuthkitScreen}.
+     *
+     * @example
+     * // Gera `inertia/pages/authkit/<view>.tsx` para cada nome listado.
+     * render: inertiaRenderer({
+     *   prefix: 'authkit',
+     *   views: [
+     *     'login', 'consent', 'signup', 'forgot', 'reset',
+     *     'verify-email', 'mfa-challenge',
+     *     'account/login', 'account/tokens', 'account/mfa',
+     *   ],
+     * })
+     */
+    views?: AuthkitScreen[];
+}
+/**
+ * Nomes das telas conhecidas da lib — dá autocomplete no array `views`.
+ * O `(string & {})` mantém o tipo aberto: telas custom (ou de versões mais
+ * novas da lib) continuam aceitas sem erro de compilação.
+ */
+export type AuthkitScreen = 'login' | 'signup' | 'consent' | 'forgot' | 'reset' | 'verify-email' | 'mfa-challenge' | 'otp-unlock' | 'maintenance' | 'account/login' | 'account/tokens' | 'account/mfa' | 'account/security' | 'account/apps' | 'account/orgs' | 'account/confirm' | 'account/email-confirmed' | (string & {});
+/**
+ * Renderer do seam para hosts Inertia/React.
+ *
+ * As páginas React vivem no host em `inertia/pages/<prefix>/<view>`.
+ * (O console admin não passa por aqui: é a SPA self-contained da lib,
+ * servida pelo shell controller.)
+ *
+ * Quando `views` é fornecido (allowlist), apenas as views listadas vão ao Inertia;
+ * qualquer outra view recai no Edge renderer built-in sem erro.
+ *
+ * ---
+ *
+ * ### Props da tela `account/login`
+ *
+ * | Prop        | Tipo                | Descrição |
+ * |-------------|---------------------|-----------|
+ * | `csrfToken` | `string`            | Token CSRF para o campo `_csrf` do formulário. |
+ * | `returnTo`  | `string \| null`    | Caminho interno de destino pós-login (já validado pelo servidor — só caminhos internos). Quando presente, o formulário deve incluir `<input type="hidden" name="return_to" value={returnTo} />`. O servidor revalida o valor no POST; hosts com tela custom precisam propagar esse hidden input. |
+ * | `error`     | `string \| undefined` | Mensagem de erro de autenticação localizada (credenciais inválidas, conta bloqueada, etc.). |
+ * | `messages`  | `AuthMessages`      | Catálogo de mensagens i18n. |
+ */
+export declare function inertiaRenderer(opts: InertiaRendererOptions): (ctx: HttpContext, view: string, props: Record<string, unknown>) => Promise<any>;