@adonis-agora/authkit-server 0.48.0 → 0.49.0

package/build/index.d.ts

@@ -46,6 +46,7 @@ export type { EventsConfigInput, ResolvedEventsConfig } from './src/events/dispa
 export { inertiaRenderer } from './src/host/renderers/inertia_renderer.js';
 export type { AuthkitScreen } from './src/host/renderers/inertia_renderer.js';
 export type { InertiaRendererOptions } from './src/host/renderers/inertia_renderer.js';
+export type { AccountLoginProps, AccountSecurityProps, AccountMfaProps, AccountConfirmProps, AccountConfirmMethod, AccountEmailConfirmedProps, } from './src/host/account_screen_props.js';
 export { edgeRenderer } from './src/host/renderers/edge_renderer.js';
 export { brandFor, isFirstParty } from './src/host/branding.js';
 export type { BrandingConfig, ClientBrand } from './src/host/branding.js';
@@ -55,6 +56,20 @@ export type { AuthHostRenderer, AuthSocialConfig } from './src/define_config.js'
 export { registerAuthHost } from './src/host/register_auth_host.js';
 export type { AuthHostOptions } from './src/host/register_auth_host.js';
 export { getAdminPrefix, setAdminPrefix, normalizeAdminPrefix, getAdminApiPrefix, setAdminApiPrefix, normalizeAdminApiPrefix, } from './src/host/admin_prefix.js';
+/**
+ * Helpers de path do console de conta (`/account/*`). Um host que precisa casar
+ * um middleware ou link com uma rota do console (ex.: `GET
+ * {accountPath('security')}/export`) deriva o path daqui em vez de hardcodar,
+ * respeitando os overrides de `accountRoutes`.
+ *
+ * ⚠️ Estes helpers leem um singleton de processo que só reflete os overrides
+ * DEPOIS que `registerAuthHost` roda (é ele quem chama `setAccountPaths` com a
+ * opção `accountRoutes`, no boot). Chamados antes disso, devolvem os defaults
+ * (`/account/*`). Componha URLs em runtime (dentro de handlers/factories de
+ * middleware), não em tempo de import de módulo.
+ */
+export { accountPath, joinAccountPath, accountPrefix, } from './src/host/account_paths.js';
+export type { AccountPathsOptions, AccountPathKey } from './src/host/account_paths.js';
 export { resolveRateLimit, resolveNotifications } from './src/define_config.js';
 export type { ResolvedNotificationsConfig } from './src/define_config.js';
 export type { RateLimitConfigInput, RateLimitBucket, ResolvedRateLimitConfig, } from './src/define_config.js';

package/build/index.js

@@ -32,6 +32,19 @@ export { brandFor, isFirstParty } from './src/host/branding.js';
 export { resolveMessages, translate, DEFAULT_MESSAGES, PT_BR_MESSAGES, BUILTIN_MESSAGES, DEFAULT_LOCALE, } from './src/host/i18n.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
 export { getAdminPrefix, setAdminPrefix, normalizeAdminPrefix, getAdminApiPrefix, setAdminApiPrefix, normalizeAdminApiPrefix, } from './src/host/admin_prefix.js';
+/**
+ * Helpers de path do console de conta (`/account/*`). Um host que precisa casar
+ * um middleware ou link com uma rota do console (ex.: `GET
+ * {accountPath('security')}/export`) deriva o path daqui em vez de hardcodar,
+ * respeitando os overrides de `accountRoutes`.
+ *
+ * ⚠️ Estes helpers leem um singleton de processo que só reflete os overrides
+ * DEPOIS que `registerAuthHost` roda (é ele quem chama `setAccountPaths` com a
+ * opção `accountRoutes`, no boot). Chamados antes disso, devolvem os defaults
+ * (`/account/*`). Componha URLs em runtime (dentro de handlers/factories de
+ * middleware), não em tempo de import de módulo.
+ */
+export { accountPath, joinAccountPath, accountPrefix, } from './src/host/account_paths.js';
 export { resolveRateLimit, resolveNotifications } from './src/define_config.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 /**

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

@@ -0,0 +1,163 @@
+/**
+ * Tipos de props das telas do console de conta (`/account/*`) — a FONTE ÚNICA da
+ * verdade sobre o shape que cada página React recebe.
+ *
+ * ── Por que esses tipos existem ──────────────────────────────────────────────
+ * Um host que cria as telas do console em React próprio (via `inertiaRenderer`,
+ * em vez das views Edge built-in) precisa tipar o componente da página. Antes
+ * disso, o único "contrato" era o DOCBLOCK do `inertiaRenderer`, copiado à mão —
+ * frágil: um docblock desatualizado já enganou um host. Agora o shape vem daqui,
+ * e os CONTROLLERS REAIS (`account_session_controller`, `account_security_-
+ * controller`, `account_mfa_controller`, `account_confirm_controller`) satisfazem
+ * (`satisfies Omit<…, 'messages'>`) exatamente estes tipos ao chamar `render()`.
+ * Se o payload de um controller divergir do tipo — campo a mais, a menos, tipo
+ * trocado — o `tsc` do pacote quebra. Esse é o objetivo: um único ponto muda, e
+ * o compilador força o outro a acompanhar.
+ *
+ * ── Sobre a prop `messages` ──────────────────────────────────────────────────
+ * `messages` (catálogo i18n) é injetada pelo `inertiaRenderer` como shared prop,
+ * NÃO pelos controllers. Por isso ela faz parte destes tipos (é o que a página
+ * React recebe), mas os controllers satisfazem `Omit<…, 'messages'>` — eles nunca
+ * passam `messages` no literal do `render()`.
+ */
+import type { PasskeySummary } from '../accounts/account_store.js';
+import type { AuthMessages } from './i18n.js';
+import type { SudoMethodDescriptor } from './sudo/types.js';
+/**
+ * Props da tela `account/login` (tela de login do console de conta).
+ *
+ * - `csrfToken`: token para o campo `_csrf` do formulário.
+ * - `returnTo`: caminho interno de destino pós-login (já validado pelo servidor —
+ *   só caminhos internos) ou `null`. Quando presente, o formulário deve incluir
+ *   `<input type="hidden" name="return_to" value={returnTo} />`; o servidor
+ *   revalida no POST.
+ * - `error`: mensagem de erro de autenticação localizada (credenciais inválidas,
+ *   conta bloqueada/desabilitada). Ausente quando não há erro.
+ * - `messages`: catálogo i18n (injetado pelo renderer).
+ */
+export interface AccountLoginProps {
+    csrfToken: string;
+    returnTo: string | null;
+    error?: string;
+    messages: AuthMessages;
+}
+/**
+ * Props da tela `account/security` (perfil, senha, e-mail, sessões, export,
+ * danger-zone). Todas as flags de `*Supported` degradam a UI quando o store não
+ * suporta a capacidade correspondente.
+ *
+ * - `supported`: `false` quando o store não suporta o self-service de segurança.
+ * - `profileSupported`: `true` quando dá para editar nome/avatar (`updateProfile`).
+ * - `avatarUploadSupported`: `true` quando algum backend (drive OU media) armazena o upload.
+ * - `email` / `name` / `avatarUrl`: valores atuais da conta (`''` se ausentes).
+ * - `passwordChanged` / `emailChangeRequested` / `emailChanged` / `profileUpdated`
+ *   / `error` / `trustedDevicesRevoked` / `deleteError`: flashes localizados ou `null`.
+ * - `trustedDevicesEnabled`: recurso de dispositivos confiáveis ligado.
+ * - `sessionsSupported`: `true` quando o adapter OIDC enumera as sessões ativas.
+ * - `sessions`: sessões ativas da própria conta (vazio quando não suportado).
+ *   `loginTs` é ISO ou `''`.
+ * - `exportSupported`: sempre `true` (portabilidade/LGPD para a conta logada).
+ * - `deletionSupported`: `true` quando o store suporta hard delete.
+ * - `messages`: catálogo i18n (injetado pelo renderer).
+ */
+export interface AccountSecurityProps {
+    csrfToken: string;
+    supported: boolean;
+    profileSupported: boolean;
+    avatarUploadSupported: boolean;
+    email: string;
+    name: string;
+    avatarUrl: string;
+    passwordChanged: string | null;
+    emailChangeRequested: string | null;
+    emailChanged: string | null;
+    profileUpdated: string | null;
+    error: string | null;
+    trustedDevicesEnabled: boolean;
+    trustedDevicesRevoked: string | null;
+    sessionsSupported: boolean;
+    sessions: Array<{
+        loginTs: string;
+        browser: string;
+        os: string;
+        ip: string;
+        location: string;
+    }>;
+    exportSupported: boolean;
+    deletionSupported: boolean;
+    deleteError: string | null;
+    messages: AuthMessages;
+}
+/**
+ * Props da tela `account/mfa` (TOTP + passkeys). As props VARIAM por action, e é
+ * por isso que as específicas de passo são opcionais:
+ *
+ * - `index` manda o estado base + a lista de passkeys (`passkeysSupported` /
+ *   `passkeys`).
+ * - `enroll` (após `POST /mfa/enroll`) acrescenta o passo do QR: `enrolling: true`,
+ *   `secret` (base32 para entrada manual) e `qrDataUrl` (data-URL do `otpauth://`).
+ * - `confirm` com código inválido reexibe `enrolling: true` + `error`, com
+ *   `secret`/`qrDataUrl` `null` (o segredo pendente NÃO é regenerado).
+ *
+ * - `enabled`: `true` quando o TOTP já está confirmado.
+ * - `recoveryCodes`: códigos recém-gerados (exibidos UMA vez) ou `null`.
+ * - `messages`: catálogo i18n (injetado pelo renderer).
+ */
+export interface AccountMfaProps {
+    csrfToken: string;
+    enabled: boolean;
+    recoveryCodes: string[] | null;
+    /** Presente em `index`: `true` quando o store persiste credenciais WebAuthn. */
+    passkeysSupported?: boolean;
+    /** Presente em `index`: passkeys cadastradas (vazio quando não suportado). */
+    passkeys?: PasskeySummary[];
+    /** Passo de enroll/confirm: `true` mostra QR/segredo + campo de código. */
+    enrolling?: boolean;
+    /** Segredo TOTP (base32) no passo de enroll; `null` na reexibição do confirm. */
+    secret?: string | null;
+    /** QR do `otpauth://` como data-URL no passo de enroll; `null` na reexibição. */
+    qrDataUrl?: string | null;
+    /** Erro localizado (ex.: código TOTP inválido no confirm). */
+    error?: string;
+    messages: AuthMessages;
+}
+/**
+ * Um método de sudo, como a tela `account/confirm` o recebe: o descritor do SPI
+ * (`SudoMethodDescriptor`) acrescido do `id` estável do método. A tela renderiza
+ * por `kind` (`form`/`action`/`redirect`/`webauthn`); `endpoint` é o POST de
+ * verificação (para `webauthn`, as options ficam em `${endpoint}/options`).
+ */
+export type AccountConfirmMethod = {
+    id: string;
+} & SudoMethodDescriptor;
+/**
+ * Props da tela `account/confirm` (sudo — confirmar identidade).
+ *
+ * - `csrfToken`: token para o POST de cada método.
+ * - `returnTo`: caminho interno de destino após confirmar (validado) ou `null`.
+ * - `error`: flash de erro da última tentativa ou `null`.
+ * - `notice`: flash informativo (ex.: "link de confirmação enviado") ou `null`.
+ * - `methods`: métodos de sudo disponíveis para a conta (ver {@link AccountConfirmMethod}).
+ * - `preferredId`: `id` do último método usado (destaque na UI) ou `null`.
+ * - `messages`: catálogo i18n (injetado pelo renderer).
+ */
+export interface AccountConfirmProps {
+    csrfToken: string;
+    returnTo: string | null;
+    error: string | null;
+    notice: string | null;
+    methods: AccountConfirmMethod[];
+    preferredId: string | null;
+    messages: AuthMessages;
+}
+/**
+ * Props da tela `account/email-confirmed` (terminal do link de troca de e-mail).
+ *
+ * - `ok`: `true` quando o token era válido e o novo e-mail foi aplicado; `false`
+ *   para token inválido/expirado ou store sem suporte.
+ * - `messages`: catálogo i18n (injetado pelo renderer).
+ */
+export interface AccountEmailConfirmedProps {
+    ok: boolean;
+    messages: AuthMessages;
+}

package/build/src/host/account_screen_props.js

@@ -0,0 +1,23 @@
+/**
+ * Tipos de props das telas do console de conta (`/account/*`) — a FONTE ÚNICA da
+ * verdade sobre o shape que cada página React recebe.
+ *
+ * ── Por que esses tipos existem ──────────────────────────────────────────────
+ * Um host que cria as telas do console em React próprio (via `inertiaRenderer`,
+ * em vez das views Edge built-in) precisa tipar o componente da página. Antes
+ * disso, o único "contrato" era o DOCBLOCK do `inertiaRenderer`, copiado à mão —
+ * frágil: um docblock desatualizado já enganou um host. Agora o shape vem daqui,
+ * e os CONTROLLERS REAIS (`account_session_controller`, `account_security_-
+ * controller`, `account_mfa_controller`, `account_confirm_controller`) satisfazem
+ * (`satisfies Omit<…, 'messages'>`) exatamente estes tipos ao chamar `render()`.
+ * Se o payload de um controller divergir do tipo — campo a mais, a menos, tipo
+ * trocado — o `tsc` do pacote quebra. Esse é o objetivo: um único ponto muda, e
+ * o compilador força o outro a acompanhar.
+ *
+ * ── Sobre a prop `messages` ──────────────────────────────────────────────────
+ * `messages` (catálogo i18n) é injetada pelo `inertiaRenderer` como shared prop,
+ * NÃO pelos controllers. Por isso ela faz parte destes tipos (é o que a página
+ * React recebe), mas os controllers satisfazem `Omit<…, 'messages'>` — eles nunca
+ * passam `messages` no literal do `render()`.
+ */
+export {};

package/build/src/host/controllers/account_confirm_controller.js

@@ -37,7 +37,7 @@ export default class AccountConfirmController {
                 ctx.logger?.warn({ method: m.id }, `authkit: método de sudo "${m.id}" está em config.sudo.methods mas não teve rotas montadas por registerAuthHost — a tela vai oferecer uma opção cujo endpoint não existe`);
             }
         }
-        return c.cfg.render(ctx, 'account/confirm', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             returnTo: c.returnTo,
             error: ctx.session.flashMessages.get('confirmError') ?? null,
@@ -47,6 +47,7 @@ export default class AccountConfirmController {
             notice: ctx.session.flashMessages.get('confirmNotice') ?? null,
             methods,
             preferredId: ctx.session.get(LAST_METHOD_SESSION_KEY) ?? null,
-        });
+        };
+        return c.cfg.render(ctx, 'account/confirm', props);
     }
 }

package/build/src/host/controllers/account_mfa_controller.js

@@ -40,13 +40,14 @@ export default class AccountMfaController {
         // Passkeys disponíveis quando o store as suporta (model de credenciais wired).
         const passkeysSupported = supportsPasskeys(cfg.accountStore);
         const passkeys = passkeysSupported ? await cfg.accountStore.listPasskeys(userId) : [];
-        return render(ctx, 'account/mfa', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             enabled: state.enabled,
             recoveryCodes: recoveryCodes ?? null,
             passkeysSupported,
             passkeys,
-        });
+        };
+        return render(ctx, 'account/mfa', props);
     }
     /**
      * POST /account/mfa/passkeys/options — gera as opções de registro de passkey
@@ -178,14 +179,15 @@ export default class AccountMfaController {
         }
         // QR renderizado server-side como data-URL e passado como prop.
         const qrDataUrl = await QRCode.toDataURL(started.otpauthUri);
-        return render(ctx, 'account/mfa', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             enabled: false,
             enrolling: true,
             secret: started.secret,
             qrDataUrl,
             recoveryCodes: null,
-        });
+        };
+        return render(ctx, 'account/mfa', props);
     }
     /** POST /account/mfa/confirm — confirma o código; sucesso = ativa e mostra recovery codes. */
     async confirm(ctx) {
@@ -199,7 +201,7 @@ export default class AccountMfaController {
             // Reenvia o passo de confirmação com erro SEM regenerar o segredo pendente
             // (o usuário já escaneou o QR; um novo segredo invalidaria o app autenticador).
             // Mostra só o campo de código para nova tentativa.
-            return render(ctx, 'account/mfa', {
+            const props = {
                 csrfToken: ctx.request.csrfToken,
                 enabled: false,
                 enrolling: true,
@@ -207,7 +209,8 @@ export default class AccountMfaController {
                 qrDataUrl: null,
                 error: translate(cfg.messages, 'errors.invalid_code'),
                 recoveryCodes: null,
-            });
+            };
+            return render(ctx, 'account/mfa', props);
         }
         await cfg.audit?.record({
             type: 'mfa.enabled',

package/build/src/host/controllers/account_security_controller.js

@@ -65,7 +65,7 @@ export default class AccountSecurityController {
         const ownSessions = sessionsSupported
             ? await enrichSessionsWithContext(cfg, userId, await adminSessions.listSessions(userId))
             : [];
-        return render(ctx, 'account/security', {
+        const props = {
             csrfToken: ctx.request.csrfToken,
             supported: supportsAccountSecurity(cfg.accountStore),
             profileSupported: supportsProfile(cfg.accountStore),
@@ -94,7 +94,8 @@ export default class AccountSecurityController {
             // Deleção de conta (LGPD): só quando o store suporta hard delete.
             deletionSupported: supportsAccountDeletion(cfg.accountStore),
             deleteError: ctx.session.flashMessages.get('deleteError') ?? null,
-        });
+        };
+        return render(ctx, 'account/security', props);
     }
     /**
      * GET /account/security/export — baixa um JSON com os dados da conta logada

package/build/src/host/controllers/account_session_controller.js

@@ -48,7 +48,11 @@ export default class AccountSessionController {
         // Lê e valida o return_to da query-string — descarta valores inválidos (open-redirect).
         const rawReturnTo = ctx.request.qs?.()?.return_to ?? ctx.request.input?.('return_to');
         const returnTo = validateReturnTo(rawReturnTo);
-        return render(ctx, 'account/login', { csrfToken: ctx.request.csrfToken, returnTo });
+        const props = {
+            csrfToken: ctx.request.csrfToken,
+            returnTo,
+        };
+        return render(ctx, 'account/login', props);
     }
     async login(ctx) {
         const service = await ctx.containerResolver.make('authkit.server');
@@ -74,7 +78,7 @@ export default class AccountSessionController {
             settings: settings ?? undefined,
         });
         if (!result.ok) {
-            return render(ctx, 'account/login', {
+            const props = {
                 csrfToken: ctx.request.csrfToken,
                 returnTo,
                 error: result.locked
@@ -84,7 +88,8 @@ export default class AccountSessionController {
                     : result.disabled
                         ? translate(cfg.messages, 'errors.account_disabled')
                         : translate(cfg.messages, 'errors.invalid_credentials'),
-            });
+            };
+            return render(ctx, 'account/login', props);
         }
         const acc = result.account;
         // M5 (session fixation): regenera a sessão IMEDIATAMENTE após autenticar e

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

@@ -58,76 +58,33 @@ export type AuthkitScreen = 'login' | 'signup' | 'consent' | 'forgot' | 'reset'
  *
  * ---
  *
- * ### Props da tela `account/login`
+ * ### Props das telas de conta — tipos exportados (fonte única)
  *
- * | 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. |
+ * Um host que escreve as telas do console em React tipa cada página com os tipos
+ * de props exportados do pacote, em vez de copiar o shape à mão deste docblock —
+ * que já ficou desatualizado no passado. Cada tipo é a FONTE ÚNICA da verdade: os
+ * controllers satisfazem (`satisfies Omit<…, 'messages'>`) exatamente o mesmo
+ * tipo ao chamar `render()`, então divergência quebra o `tsc` do pacote. Ver
+ * `src/host/account_screen_props.ts`.
  *
- * ### Props da tela `account/security`
+ * | Tela                      | Tipo exportado             |
+ * |---------------------------|----------------------------|
+ * | `account/login`           | {@link AccountLoginProps}          |
+ * | `account/security`        | {@link AccountSecurityProps}       |
+ * | `account/mfa`             | {@link AccountMfaProps}            |
+ * | `account/confirm`         | {@link AccountConfirmProps}        |
+ * | `account/email-confirmed` | {@link AccountEmailConfirmedProps} |
  *
- * | 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. |
+ * A prop `messages` (catálogo i18n {@link AuthMessages}) é injetada por este
+ * renderer como shared prop e faz parte de todos esses tipos — os controllers,
+ * que não a passam, satisfazem `Omit<…, 'messages'>`.
  *
- * ### Props da tela `account/mfa`
+ * ```tsx
+ * import type { AccountSecurityProps } from '@adonis-agora/authkit-server'
  *
- * As props variam por action: `index` manda o estado base; `enroll` acrescenta
- * `enrolling`/`secret`/`qrDataUrl` (passo do QR); `confirm` com código inválido
- * reenvia `enrolling: true` + `error` (sem regenerar o segredo).
- *
- * | 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. Presente em `index`. |
- * | `enrolling`         | `boolean \| undefined` | `true` no passo de enrollment (após `POST /mfa/enroll` e na reexibição do `confirm` com código inválido) — a tela mostra o QR/segredo e o campo de código. Ausente em `index`. |
- * | `secret`            | `string \| null \| undefined` | Segredo TOTP em texto (base32) para entrada manual, exibido no passo de enroll. `null` na reexibição do `confirm` (o segredo pendente NÃO é regenerado). Ausente em `index`. |
- * | `qrDataUrl`         | `string \| null \| undefined` | QR code do `otpauth://` como data-URL (`<img src>`), no passo de enroll. `null` na reexibição do `confirm`. Ausente em `index`. |
- * | `error`             | `string \| undefined` | Mensagem de erro localizada (ex.: código TOTP inválido no `confirm`). Ausente quando não há erro. |
- * | `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 default function Security(props: AccountSecurityProps) {
+ *   return <form action="/account/security/password" method="post">…</form>
+ * }
+ * ```
  */
 export declare function inertiaRenderer(opts: InertiaRendererOptions): (ctx: HttpContext, view: string, props: Record<string, unknown>) => Promise<any>;

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

@@ -29,77 +29,34 @@ async function resolveMessagesFromCtx(ctx) {
  *
  * ---
  *
- * ### Props da tela `account/login`
+ * ### Props das telas de conta — tipos exportados (fonte única)
  *
- * | 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. |
+ * Um host que escreve as telas do console em React tipa cada página com os tipos
+ * de props exportados do pacote, em vez de copiar o shape à mão deste docblock —
+ * que já ficou desatualizado no passado. Cada tipo é a FONTE ÚNICA da verdade: os
+ * controllers satisfazem (`satisfies Omit<…, 'messages'>`) exatamente o mesmo
+ * tipo ao chamar `render()`, então divergência quebra o `tsc` do pacote. Ver
+ * `src/host/account_screen_props.ts`.
  *
- * ### Props da tela `account/security`
+ * | Tela                      | Tipo exportado             |
+ * |---------------------------|----------------------------|
+ * | `account/login`           | {@link AccountLoginProps}          |
+ * | `account/security`        | {@link AccountSecurityProps}       |
+ * | `account/mfa`             | {@link AccountMfaProps}            |
+ * | `account/confirm`         | {@link AccountConfirmProps}        |
+ * | `account/email-confirmed` | {@link AccountEmailConfirmedProps} |
  *
- * | 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. |
+ * A prop `messages` (catálogo i18n {@link AuthMessages}) é injetada por este
+ * renderer como shared prop e faz parte de todos esses tipos — os controllers,
+ * que não a passam, satisfazem `Omit<…, 'messages'>`.
  *
- * ### Props da tela `account/mfa`
+ * ```tsx
+ * import type { AccountSecurityProps } from '@adonis-agora/authkit-server'
  *
- * As props variam por action: `index` manda o estado base; `enroll` acrescenta
- * `enrolling`/`secret`/`qrDataUrl` (passo do QR); `confirm` com código inválido
- * reenvia `enrolling: true` + `error` (sem regenerar o segredo).
- *
- * | 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. Presente em `index`. |
- * | `enrolling`         | `boolean \| undefined` | `true` no passo de enrollment (após `POST /mfa/enroll` e na reexibição do `confirm` com código inválido) — a tela mostra o QR/segredo e o campo de código. Ausente em `index`. |
- * | `secret`            | `string \| null \| undefined` | Segredo TOTP em texto (base32) para entrada manual, exibido no passo de enroll. `null` na reexibição do `confirm` (o segredo pendente NÃO é regenerado). Ausente em `index`. |
- * | `qrDataUrl`         | `string \| null \| undefined` | QR code do `otpauth://` como data-URL (`<img src>`), no passo de enroll. `null` na reexibição do `confirm`. Ausente em `index`. |
- * | `error`             | `string \| undefined` | Mensagem de erro localizada (ex.: código TOTP inválido no `confirm`). Ausente quando não há erro. |
- * | `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 default function Security(props: AccountSecurityProps) {
+ *   return <form action="/account/security/password" method="post">…</form>
+ * }
+ * ```
  */
 export function inertiaRenderer(opts) {
     const allowed = opts.views ? new Set(opts.views) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "AdonisJS OIDC/OAuth2 provider (Identity Provider) toolkit: ejectable auth server with sessions, rate-limiting, MFA/TOTP, audit log, federated logout and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
@@ -148,7 +148,7 @@
     "react-error-boundary": "6.1.2",
     "nuqs": "2.8.9",
     "recharts": "3.8.1",
-    "@adonis-agora/authkit-react": "0.16.0"
+    "@adonis-agora/authkit-react": "0.17.0"
   },
   "scripts": {
     "build": "node scripts/build_host_css.mjs && node scripts/build_webauthn.mjs && node scripts/build_ui.mjs && node -e \"const fs=require('node:fs');for(const d of ['build/stubs','build/host/views'])fs.rmSync(d,{recursive:true,force:true})\" && tsc && node -e \"require('node:fs').cpSync('src/host/assets','build/src/host/assets',{recursive:true})\" && node -e \"require('node:fs').cpSync('stubs','build/stubs',{recursive:true,filter:(s)=>!s.endsWith('.ts')})\" && node -e \"const fs=require('node:fs');if(fs.existsSync('assets'))fs.cpSync('assets','build/assets',{recursive:true})\" && node -e \"require('node:fs').cpSync('src/host/views','build/host/views',{recursive:true})\" && node -e \"const fs=require('node:fs');fs.mkdirSync('build/host/ui',{recursive:true});fs.readdirSync('src/host/ui').filter(f=>f.endsWith('.html')).forEach(f=>fs.copyFileSync('src/host/ui/'+f,'build/host/ui/'+f))\" && node -e \"require('node:fs').copyFileSync('commands/commands.json','build/commands/commands.json')\" && node -e \"const fs=require('node:fs');fs.mkdirSync('build/password',{recursive:true});fs.copyFileSync('src/password/common_passwords.txt','build/password/common_passwords.txt')\"",