@adonis-agora/authkit-server 0.45.0 → 0.47.0

package/build/src/host/register_auth_host.js

@@ -8,6 +8,20 @@ import { setAdminPrefix, normalizeAdminPrefix, setAdminApiPrefix, normalizeAdmin
 import { resolveRuntimeSettings } from './runtime_settings.js';
 import { resolveEffectiveSessionPolicy } from './runtime_toggles.js';
 import { getAuthHostConfig } from './auth_host_config.js';
+import { setAccountLoginUrl, getAccountLoginUrl } from './account_login_url.js';
+import { completeSudo, fail, guardSudoRoutes, sudoContextFrom, setMountedSudoMethods, } from './sudo/runtime.js';
+import { password as sudoPassword } from './sudo/methods/password.js';
+import { passkey as sudoPasskey } from './sudo/methods/passkey.js';
+/**
+ * Métodos de sudo montados quando o host não passa `sudoMethods` —
+ * comportamento histórico (senha + passkey).
+ *
+ * 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.
+ */
+const SUDO_METHOD_DEFAULTS = [sudoPassword(), sudoPasskey()];
 /** Chave da sessão Adonis que registra o timestamp da última atividade (idle timeout). */
 export const ACCOUNT_LAST_SEEN_KEY = 'authkit_last_seen';
 /**
@@ -55,16 +69,26 @@ async function checkAndRefreshIdle(ctx) {
  * @internal
  */
 function buildLoginRedirect(ctx, extra) {
+    // Destino configurável (`accountLoginUrl`): default `/account/login`, mas um
+    // host que desmontou a tela de login (`account: { login: false }`) aponta para
+    // a própria rota de login dele (ex.: `/login`). Ver `account_login_url.ts`.
+    const loginUrl = getAccountLoginUrl();
     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')) {
+    if (dest && dest !== '/' && !dest.startsWith(loginUrl)) {
         const encoded = encodeURIComponent(dest);
-        const base = extra ? `/account/login?${extra}&return_to=${encoded}` : `/account/login?return_to=${encoded}`;
+        const sep = loginUrl.includes('?') ? '&' : '?';
+        const base = extra
+            ? `${loginUrl}${sep}${extra}&return_to=${encoded}`
+            : `${loginUrl}${sep}return_to=${encoded}`;
         return base;
     }
-    return extra ? `/account/login?${extra}` : '/account/login';
+    if (!extra)
+        return loginUrl;
+    const sep = loginUrl.includes('?') ? '&' : '?';
+    return `${loginUrl}${sep}${extra}`;
 }
 /**
  * Guard inline do console de conta. Usamos uma closure (forma confiável do
@@ -87,9 +111,11 @@ const accountGuard = async (ctx, 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);
+ *   1. sessão de conta ativa (senão → `accountLoginUrl`, default /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).
+ *      (senão → `accountHome(cfg)`, default /account/security — NÃO revela a
+ *      existência do /admin, e cai numa tela que o host controla via `accountHome`;
+ *      se a tela default estiver desmontada, aponte `config.accountHome` para uma montada).
  * As roles permitidas são resolvidas em runtime do `authkit.server` (config lazy).
  */
 export const adminGuard = async (ctx, next) => {
@@ -138,6 +164,7 @@ const C = {
     accountMfa: () => import('./controllers/account_mfa_controller.js'),
     accountOrgs: () => import('./controllers/account_orgs_controller.js'),
     accountConfirm: () => import('./controllers/account_confirm_controller.js'),
+    webauthnAsset: () => import('./controllers/webauthn_asset_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'),
@@ -174,6 +201,29 @@ export function registerAuthHost(router, opts = {}) {
     const social = opts.social ?? hostCfg?.social;
     const adminOpt = opts.admin ?? (hostCfg?.adminEnabled ? true : undefined);
     const adminApiOpt = opts.adminApi ?? (hostCfg?.adminApiEnabled ? true : undefined);
+    // 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 fica o
+    // default `/account/login` do singleton — back-compat).
+    if (opts.accountLoginUrl !== undefined) {
+        setAccountLoginUrl(opts.accountLoginUrl);
+    }
+    // Montagem por tela do console de conta. `undefined` → tudo montado;
+    // `false` → nada; objeto → cada flag ausente default `true`.
+    const accountOpt = opts.account;
+    const mountScreen = (key) => {
+        if (accountOpt === false)
+            return false;
+        if (accountOpt && typeof accountOpt === 'object')
+            return accountOpt[key] !== false;
+        return true;
+    };
+    const mountLogin = mountScreen('login');
+    const mountTokens = mountScreen('tokens');
+    const mountOrgs = mountScreen('orgs');
+    const mountSecurity = mountScreen('security');
+    const mountMfa = mountScreen('mfa');
+    const mountApps = mountScreen('apps');
     // Throttles opt-in (anti-brute-force). `undefined` quando rate-limit desligado.
     const resolvedRateLimit = opts.rateLimit !== undefined
         ? resolveRateLimit(opts.rateLimit)
@@ -188,6 +238,25 @@ export function registerAuthHost(router, opts = {}) {
         if (throttles)
             route.use([throttles.introspection]);
     };
+    // Bucket PRÓPRIO das rotas de sudo. Antes elas levavam o `withLogin`, o que
+    // funcionava mas somava dois orçamentos que medem coisas diferentes: login é
+    // um anônimo adivinhando credenciais, sudo é um usuário JÁ autenticado
+    // reprovando a própria identidade. Ver `ResolvedRateLimitConfig.sudo`.
+    const withSudo = (route) => {
+        if (throttles)
+            route.use([throttles.sudo]);
+    };
+    // ─── Assets estáticos do host-kit (públicos, sem autenticação) ─────────────
+    // Bundle do @simplewebauthn/browser servido pelo próprio app, no lugar do
+    // import de CDN público que as views de login/MFA/confirm faziam.
+    //
+    // Path FIXO e no topo, de propósito:
+    //  • não pode viver sob o prefixo do console admin (`admin` é opt-in) —
+    //    login.edge e mfa-challenge.edge precisam do script em qualquer host;
+    //  • sem guard, porque é carregado NA tela de login, antes de haver sessão;
+    //  • registrado ANTES do wildcard `${mount}/*` para que nenhum mountPath
+    //    agressivo (ex.: '/') consiga engolir o asset e quebrar o login.
+    router.get('/authkit/assets/webauthn.js', [C.webauthnAsset]).as('authkit.assets.webauthn');
     // 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');
@@ -225,68 +294,126 @@ export function registerAuthHost(router, opts = {}) {
     // 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']);
+    // Parte da tela `orgs`: desmontada junto (sem multi-tenancy, não há convite a aceitar).
+    if (mountOrgs) {
+        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']));
+    // Tela `login` desmontável: hosts passwordless delegam ao OIDC próprio e
+    // apontam `accountLoginUrl` para a rota de login deles.
+    if (mountLogin) {
+        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']);
+    // pode ser aberta em outro dispositivo, então NÃO exige sessão). Parte da tela
+    // `security` (o terminal do fluxo de troca de e-mail).
+    if (mountSecurity) {
+        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.
+        // Personal Access Tokens (tela `tokens`).
+        if (mountTokens) {
+            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 (tela `security`).
+        if (mountSecurity) {
+            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 (tela `apps`).
+        if (mountApps) {
+            router.get('/account/apps', [C.accountApps, 'index']);
+            router.post('/account/apps/:clientId/revoke', [C.accountApps, 'revoke']);
+        }
+        // MFA — TOTP + passkeys (tela `mfa`).
+        if (mountMfa) {
+            // 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): o GET lista os métodos; cada método
+        // registra suas próprias rotas de verificação (SPI `SudoMethod`).
         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']);
+        // Rotas próprias dos métodos de sudo — DENTRO do grupo com `accountGuard`.
+        // O guard não é só "tem sessão": ele roda `checkAndRefreshIdle`, que apaga
+        // a sessão vencida por idle e refresca `authkit_last_seen`. Fora do grupo,
+        // uma sessão já vencida (ainda não colhida) podia postar a senha correta e
+        // receber `markSudo` — e as rotas de sudo não refrescavam o last-seen.
+        // Nenhum método built-in é alcançável por GET vindo de e-mail: o token de
+        // sudo por magic link vive na PRÓPRIA sessão, então o usuário precisa
+        // estar logado no mesmo navegador de qualquer forma. Um método que
+        // genuinamente não puder ficar sob o guard precisa de uma decisão
+        // explícita, não de mover todos para fora.
+        const helpers = {
+            contextFrom: sudoContextFrom,
+            completeSudo,
+            fail,
+        };
+        const sudoMethodsToMount = opts?.sudoMethods ?? 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
+            // não tenha checado nada por dentro. Ver o docblock lá.
+            //
+            // `withSudo` vai junto: TODA rota de um método de sudo leva o throttle
+            // do bucket de SUDO (no-op sem rate-limit). Não é adorno — o POST que
+            // emite o magic link de sudo dispara um e-mail por chamada, e o
+            // `accountGuard` sozinho só exige uma sessão viva, que o abusador tem.
+            // Aplicar aqui, no wrapper, cobre também os métodos customizados, que
+            // não teriam como pedir throttle pelo `SudoRouteHelpers`.
+            //
+            // Bucket próprio, não o de login: mesmos limites, contagem separada —
+            // errar a senha na tela de confirmação não pode gastar o orçamento de
+            // login do IP, nem vice-versa.
+            method.register?.(guardSudoRoutes(router, method.id, helpers, withSudo), helpers);
+        }
+        // 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);
+        // Organizations (multi-tenancy) — tela `orgs`. Montadas por default;
+        // controller retorna 404/403 sem tabelas (capability-probed).
+        if (mountOrgs) {
+            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.

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

@@ -1,4 +1,5 @@
 import { DEFAULT_MESSAGES, translate } from '../i18n.js';
+import { getAccountLoginUrl } from '../account_login_url.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
@@ -28,7 +29,11 @@ async function resolveMessagesFromCtx(ctx) {
 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 });
+    // `loginUrl` como prop global: as views que linkam "faça login" (ex.: `otp-unlock`)
+    // usam o destino configurável (`accountLoginUrl`) em vez do `/account/login` fixo,
+    // que pode estar desmontado. Props explícitas ainda têm precedência (spread depois).
+    const loginUrl = getAccountLoginUrl();
+    return ctx.view.render(`authkit::${view}`, { loginUrl, ...props, t, messages });
 }
 /** Renderer do seam para hosts Edge. As views são donas-da-lib (disco `authkit::`). */
 export function edgeRenderer() {

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

@@ -66,5 +66,60 @@ export type AuthkitScreen = 'login' | 'signup' | 'consent' | 'forgot' | 'reset'
  * | `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. |
+ *
+ * ### Props da tela `account/security`
+ *
+ * | Prop                    | Tipo                | Descrição |
+ * |-------------------------|---------------------|-----------|
+ * | `csrfToken`             | `string`            | Token CSRF para os formulários da tela. |
+ * | `supported`             | `boolean`           | `false` quando o store não suporta o self-service de segurança (troca de senha/e-mail) — a tela deve degradar. |
+ * | `profileSupported`      | `boolean`           | `true` quando o store suporta editar nome/avatar (`updateProfile`). |
+ * | `avatarUploadSupported` | `boolean`           | `true` quando algum backend (drive OU media) pode armazenar o upload de avatar. |
+ * | `email`                 | `string`            | E-mail atual da conta (`''` se ausente). |
+ * | `name`                  | `string`            | Nome atual da conta (`''` se ausente). |
+ * | `avatarUrl`             | `string`            | URL do avatar atual (`''` se ausente). |
+ * | `passwordChanged`       | `string \| null`    | Flash de sucesso da troca de senha (mensagem localizada) ou `null`. |
+ * | `emailChangeRequested`  | `string \| null`    | Flash: link de confirmação de troca de e-mail enviado (ou cancelamento) ou `null`. |
+ * | `emailChanged`          | `string \| null`    | Flash: troca de e-mail concluída ou `null`. |
+ * | `profileUpdated`        | `string \| null`    | Flash: perfil atualizado ou `null`. |
+ * | `error`                 | `string \| null`    | Flash de erro de segurança (senha inválida, e-mail em uso, política violada) ou `null`. |
+ * | `trustedDevicesEnabled` | `boolean`           | `true` quando o recurso de dispositivos confiáveis está ligado. |
+ * | `trustedDevicesRevoked` | `string \| null`    | Flash: confiança deste navegador revogada ou `null`. |
+ * | `sessionsSupported`     | `boolean`           | `true` quando o adapter OIDC enumera as sessões ativas da conta. |
+ * | `sessions`              | `Array<{ loginTs: string; browser: string; os: string; ip: string; location: string }>` | Sessões ativas da própria conta (vazio quando não suportado). `loginTs` é ISO ou `''`. |
+ * | `exportSupported`       | `boolean`           | Sempre `true` — export de dados (portabilidade/LGPD) disponível para a conta logada. |
+ * | `deletionSupported`     | `boolean`           | `true` quando o store suporta hard delete (danger zone). |
+ * | `deleteError`           | `string \| null`    | Flash de erro da confirmação de deleção ou `null`. |
+ * | `messages`              | `AuthMessages`      | Catálogo de mensagens i18n. |
+ *
+ * ### Props da tela `account/mfa`
+ *
+ * | Prop                | Tipo                | Descrição |
+ * |---------------------|---------------------|-----------|
+ * | `csrfToken`         | `string`            | Token CSRF para os formulários de enroll/confirm/disable e passkeys. |
+ * | `enabled`           | `boolean`           | `true` quando o TOTP já está confirmado (habilitado) para a conta. |
+ * | `recoveryCodes`     | `string[] \| null`  | Códigos de recuperação recém-gerados (exibidos UMA vez após enroll/confirm) ou `null`. |
+ * | `passkeysSupported` | `boolean`           | `true` quando o store persiste credenciais WebAuthn (passkeys). |
+ * | `passkeys`          | `Array<{ id: string; label?: string; createdAt: string }>` | Passkeys cadastradas (vazio quando não suportado). `id` é base64url; `createdAt` é ISO. |
+ * | `messages`          | `AuthMessages`      | Catálogo de mensagens i18n. |
+ *
+ * ### Props da tela `account/confirm` (sudo — confirmar identidade)
+ *
+ * | Prop          | Tipo                | Descrição |
+ * |---------------|---------------------|-----------|
+ * | `csrfToken`   | `string`            | Token CSRF para o POST de cada método. |
+ * | `returnTo`    | `string \| null`    | Caminho interno de destino após confirmar (validado pelo servidor) ou `null`. |
+ * | `error`       | `string \| null`    | Flash de erro da última tentativa de confirmação ou `null`. |
+ * | `notice`      | `string \| null`    | Flash informativo (ex.: "link de confirmação enviado") ou `null`. |
+ * | `methods`     | `Array<{ id: string; labelKey: string; kind: 'form' \| 'action' \| 'redirect' \| 'webauthn'; endpoint: string; fields?: Array<{ name: string; type: 'password' \| 'text'; labelKey: string }> }>` | Métodos de sudo disponíveis para a conta. A tela renderiza por `kind`; `endpoint` é o POST de verificação (`webauthn` pede options em `${endpoint}/options`). |
+ * | `preferredId` | `string \| null`    | `id` do último método usado (destaque na UI) ou `null`. |
+ * | `messages`    | `AuthMessages`      | Catálogo de mensagens i18n. |
+ *
+ * ### Props da tela `account/email-confirmed` (terminal do link de troca de e-mail)
+ *
+ * | Prop       | Tipo           | Descrição |
+ * |------------|----------------|-----------|
+ * | `ok`       | `boolean`      | `true` quando o token era válido e o novo e-mail foi aplicado; `false` para token inválido/expirado ou store sem suporte. A tela mostra sucesso ou falha conforme o valor. |
+ * | `messages` | `AuthMessages` | Catálogo de mensagens i18n. |
  */
 export declare function inertiaRenderer(opts: InertiaRendererOptions): (ctx: HttpContext, view: string, props: Record<string, unknown>) => Promise<any>;

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

@@ -37,6 +37,61 @@ async function resolveMessagesFromCtx(ctx) {
  * | `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. |
+ *
+ * ### Props da tela `account/security`
+ *
+ * | Prop                    | Tipo                | Descrição |
+ * |-------------------------|---------------------|-----------|
+ * | `csrfToken`             | `string`            | Token CSRF para os formulários da tela. |
+ * | `supported`             | `boolean`           | `false` quando o store não suporta o self-service de segurança (troca de senha/e-mail) — a tela deve degradar. |
+ * | `profileSupported`      | `boolean`           | `true` quando o store suporta editar nome/avatar (`updateProfile`). |
+ * | `avatarUploadSupported` | `boolean`           | `true` quando algum backend (drive OU media) pode armazenar o upload de avatar. |
+ * | `email`                 | `string`            | E-mail atual da conta (`''` se ausente). |
+ * | `name`                  | `string`            | Nome atual da conta (`''` se ausente). |
+ * | `avatarUrl`             | `string`            | URL do avatar atual (`''` se ausente). |
+ * | `passwordChanged`       | `string \| null`    | Flash de sucesso da troca de senha (mensagem localizada) ou `null`. |
+ * | `emailChangeRequested`  | `string \| null`    | Flash: link de confirmação de troca de e-mail enviado (ou cancelamento) ou `null`. |
+ * | `emailChanged`          | `string \| null`    | Flash: troca de e-mail concluída ou `null`. |
+ * | `profileUpdated`        | `string \| null`    | Flash: perfil atualizado ou `null`. |
+ * | `error`                 | `string \| null`    | Flash de erro de segurança (senha inválida, e-mail em uso, política violada) ou `null`. |
+ * | `trustedDevicesEnabled` | `boolean`           | `true` quando o recurso de dispositivos confiáveis está ligado. |
+ * | `trustedDevicesRevoked` | `string \| null`    | Flash: confiança deste navegador revogada ou `null`. |
+ * | `sessionsSupported`     | `boolean`           | `true` quando o adapter OIDC enumera as sessões ativas da conta. |
+ * | `sessions`              | `Array<{ loginTs: string; browser: string; os: string; ip: string; location: string }>` | Sessões ativas da própria conta (vazio quando não suportado). `loginTs` é ISO ou `''`. |
+ * | `exportSupported`       | `boolean`           | Sempre `true` — export de dados (portabilidade/LGPD) disponível para a conta logada. |
+ * | `deletionSupported`     | `boolean`           | `true` quando o store suporta hard delete (danger zone). |
+ * | `deleteError`           | `string \| null`    | Flash de erro da confirmação de deleção ou `null`. |
+ * | `messages`              | `AuthMessages`      | Catálogo de mensagens i18n. |
+ *
+ * ### Props da tela `account/mfa`
+ *
+ * | Prop                | Tipo                | Descrição |
+ * |---------------------|---------------------|-----------|
+ * | `csrfToken`         | `string`            | Token CSRF para os formulários de enroll/confirm/disable e passkeys. |
+ * | `enabled`           | `boolean`           | `true` quando o TOTP já está confirmado (habilitado) para a conta. |
+ * | `recoveryCodes`     | `string[] \| null`  | Códigos de recuperação recém-gerados (exibidos UMA vez após enroll/confirm) ou `null`. |
+ * | `passkeysSupported` | `boolean`           | `true` quando o store persiste credenciais WebAuthn (passkeys). |
+ * | `passkeys`          | `Array<{ id: string; label?: string; createdAt: string }>` | Passkeys cadastradas (vazio quando não suportado). `id` é base64url; `createdAt` é ISO. |
+ * | `messages`          | `AuthMessages`      | Catálogo de mensagens i18n. |
+ *
+ * ### Props da tela `account/confirm` (sudo — confirmar identidade)
+ *
+ * | Prop          | Tipo                | Descrição |
+ * |---------------|---------------------|-----------|
+ * | `csrfToken`   | `string`            | Token CSRF para o POST de cada método. |
+ * | `returnTo`    | `string \| null`    | Caminho interno de destino após confirmar (validado pelo servidor) ou `null`. |
+ * | `error`       | `string \| null`    | Flash de erro da última tentativa de confirmação ou `null`. |
+ * | `notice`      | `string \| null`    | Flash informativo (ex.: "link de confirmação enviado") ou `null`. |
+ * | `methods`     | `Array<{ id: string; labelKey: string; kind: 'form' \| 'action' \| 'redirect' \| 'webauthn'; endpoint: string; fields?: Array<{ name: string; type: 'password' \| 'text'; labelKey: string }> }>` | Métodos de sudo disponíveis para a conta. A tela renderiza por `kind`; `endpoint` é o POST de verificação (`webauthn` pede options em `${endpoint}/options`). |
+ * | `preferredId` | `string \| null`    | `id` do último método usado (destaque na UI) ou `null`. |
+ * | `messages`    | `AuthMessages`      | Catálogo de mensagens i18n. |
+ *
+ * ### Props da tela `account/email-confirmed` (terminal do link de troca de e-mail)
+ *
+ * | Prop       | Tipo           | Descrição |
+ * |------------|----------------|-----------|
+ * | `ok`       | `boolean`      | `true` quando o token era válido e o novo e-mail foi aplicado; `false` para token inválido/expirado ou store sem suporte. A tela mostra sucesso ou falha conforme o valor. |
+ * | `messages` | `AuthMessages` | Catálogo de mensagens i18n. |
  */
 export function inertiaRenderer(opts) {
     const allowed = opts.views ? new Set(opts.views) : null;

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

@@ -0,0 +1,47 @@
+import { password } from './methods/password.js';
+import { passkey } from './methods/passkey.js';
+import { oidcStepUp } from './methods/oidc_step_up.js';
+import { magicLink } from './methods/magic_link.js';
+/**
+ * Métodos de confirmação de identidade (sudo mode), no mesmo padrão de factory
+ * usado em `stores.*` e `retrievers.*` das libs irmãs.
+ *
+ * A lista vai em DOIS lugares, e eles precisam casar:
+ *
+ * - `config/authkit.ts` → `sudo.methods` decide o que a TELA oferece e o que os
+ *   handlers ACEITAM;
+ * - `registerAuthHost(router, { sudoMethods })` decide o que tem ROTA montada.
+ *
+ * São dois porque a montagem de rotas acontece antes de o config (lazy)
+ * resolver — mesma razão de `social`/`admin`/`rateLimit`. Divergiram, a tela
+ * loga um aviso de flag-drift e o endpoint faltante dá 404.
+ *
+ * SEM `config.sudo.methods` não há como divergir: a tela cai na própria lista
+ * montada por `registerAuthHost`, a mesma que os handlers aceitam.
+ *
+ * ```ts
+ * defineConfig({
+ *   sudo: {
+ *     methods: [
+ *       sudoMethods.oidcStepUp({ url: '/auth/step-up' }),
+ *       sudoMethods.magicLink(),
+ *       sudoMethods.passkey(),
+ *       sudoMethods.password(),
+ *     ],
+ *   },
+ * })
+ * ```
+ */
+export declare const sudoMethods: {
+    password: typeof password;
+    passkey: typeof passkey;
+    oidcStepUp: typeof oidcStepUp;
+    magicLink: typeof magicLink;
+};
+export type { SudoMethod, SudoContext, SudoMethodDescriptor, SudoRouteHelpers } from './types.js';
+/**
+ * Montagem do `SudoContext` a partir do `HttpContext`. Reexportado aqui por
+ * simetria com `sudoMethods` e os tipos: quem escreve um método (ou a rota de
+ * callback do `oidcStepUp`) precisa dos três.
+ */
+export { sudoContextFrom } from './runtime.js';

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

@@ -0,0 +1,41 @@
+import { password } from './methods/password.js';
+import { passkey } from './methods/passkey.js';
+import { oidcStepUp } from './methods/oidc_step_up.js';
+import { magicLink } from './methods/magic_link.js';
+/**
+ * Métodos de confirmação de identidade (sudo mode), no mesmo padrão de factory
+ * usado em `stores.*` e `retrievers.*` das libs irmãs.
+ *
+ * A lista vai em DOIS lugares, e eles precisam casar:
+ *
+ * - `config/authkit.ts` → `sudo.methods` decide o que a TELA oferece e o que os
+ *   handlers ACEITAM;
+ * - `registerAuthHost(router, { sudoMethods })` decide o que tem ROTA montada.
+ *
+ * São dois porque a montagem de rotas acontece antes de o config (lazy)
+ * resolver — mesma razão de `social`/`admin`/`rateLimit`. Divergiram, a tela
+ * loga um aviso de flag-drift e o endpoint faltante dá 404.
+ *
+ * SEM `config.sudo.methods` não há como divergir: a tela cai na própria lista
+ * montada por `registerAuthHost`, a mesma que os handlers aceitam.
+ *
+ * ```ts
+ * defineConfig({
+ *   sudo: {
+ *     methods: [
+ *       sudoMethods.oidcStepUp({ url: '/auth/step-up' }),
+ *       sudoMethods.magicLink(),
+ *       sudoMethods.passkey(),
+ *       sudoMethods.password(),
+ *     ],
+ *   },
+ * })
+ * ```
+ */
+export const sudoMethods = { password, passkey, oidcStepUp, magicLink };
+/**
+ * Montagem do `SudoContext` a partir do `HttpContext`. Reexportado aqui por
+ * simetria com `sudoMethods` e os tipos: quem escreve um método (ou a rota de
+ * callback do `oidcStepUp`) precisa dos três.
+ */
+export { sudoContextFrom } from './runtime.js';

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

@@ -0,0 +1,43 @@
+import type { SudoContext, SudoMethod } from '../types.js';
+/** Token de sudo pendente, guardado na sessão que o pediu. */
+export declare const SUDO_LINK_SESSION_KEY = "authkit_sudo_link";
+/** Mesma janela dos magic links de login. */
+export declare const SUDO_LINK_TTL_MS: number;
+/**
+ * Emite um token de sudo e guarda o HASH na sessão que pediu.
+ *
+ * O TOKEN É PRÓPRIO, DE ESCOPO SUDO — nunca o token de login
+ * (`issueMagicLinkToken`/`consumeMagicLinkToken` do `AccountStore`). Aquele é
+ * credencial de AUTENTICAÇÃO: reusá-lo faria de um link de sudo vazado uma
+ * sessão completa.
+ *
+ * | propriedade | valor | razão |
+ * |---|---|---|
+ * | geração | `randomBytes(32)` hex | entropia de credencial |
+ * | armazenamento | HASH na sessão que pediu | não guarda o segredo em claro |
+ * | escopo | só marca sudo | nunca autentica |
+ * | validade | 5 min | mesma janela dos magic links de login |
+ * | uso | único (apagado no consumo) | replay |
+ * | navegador | só o mesmo (vive na sessão) | step-up é reprova de QUEM ESTÁ ALI |
+ * | conta | vinculado ao `accountId` emissor | sessão sobrevive à troca de conta |
+ *
+ * O "só mesmo navegador" é propriedade desejada aqui, diferente do magic link
+ * de login, onde é limitação conhecida.
+ *
+ * Exportada (em vez de membro `__` do método) para ser testável sem furar a
+ * API pública do `SudoMethod`.
+ */
+export declare function issueSudoLinkToken(c: SudoContext): string;
+/**
+ * Consome o token: single-use, vinculado à conta emissora, expira em 5 min,
+ * comparação em tempo constante.
+ */
+export declare function verifySudoLinkToken(c: SudoContext, token: string): boolean;
+/**
+ * Confirmação por link enviado ao e-mail da conta.
+ *
+ * Depende do hook `mail.onSudoLink`, DISTINTO de `mail.onMagicLink` justamente
+ * para que o host não confunda um link que autentica com um que só concede
+ * sudo a quem já está logado. Sem o hook, o método fica indisponível.
+ */
+export declare function magicLink(): SudoMethod;