@adonis-agora/authkit-server 0.48.0 → 0.50.0

package/build/src/host/otp_login.js

@@ -0,0 +1,206 @@
+/**
+ * Login por OTP (código digitável) — helpers puros + máquina de estados da
+ * verificação.
+ *
+ * ── Por que este módulo existe (e o porquê da decisão de armazenamento) ───────
+ * O host passwordless já tem magic link (token de 256 bits, IMPOSSÍVEL de
+ * adivinhar). O código de 6 dígitos é ADIVINHÁVEL: exige lockout dedicado +
+ * throttle — segurança que não se reimplementa por host. O mesmo e-mail passa a
+ * carregar LINK e CÓDIGO; os dois completam a MESMA interaction OIDC.
+ *
+ * ── Decisão de armazenamento (investigação registrada no código) ─────────────
+ * O SPEC ranqueia três opções e manda a investigação decidir. Resultado:
+ *
+ *   1. (preferida no spec) Guardar `otpHash`/`otpExpiresAt`/`otpAttempts` no
+ *      REGISTRO DA INTERACTION do oidc-provider — **INVIÁVEL**. O modelo
+ *      `Interaction` do oidc-provider só persiste os campos listados em
+ *      `IN_PAYLOAD` (`base_model.js` filtra o payload por
+ *      `IN_PAYLOAD.includes(key)` no construtor; `save()` chama
+ *      `getValueAndPayload`). Campos custom de topo são DESCARTADOS ao persistir.
+ *      O único slot livre persistido é `lastSubmission`, dono do mecanismo
+ *      `mergeWithLastSubmission` — sequestrá-lo é frágil. Ver
+ *      `node_modules/oidc-provider/lib/models/interaction.js:57` e
+ *      `.../base_model.js:34`.
+ *
+ *   2. (ESCOLHIDA) Formato composto no slot já existente do token de magic link
+ *      (`passwordResetToken`, hoje `ml:<token>`). Passa a `ml2:<...>` quando o
+ *      OTP está ligado. Esta opção resolve os TRÊS requisitos duros de uma vez:
+ *        • **Single-use conjunto** — código e link vivem no MESMO slot da MESMA
+ *          linha: consumir qualquer um limpa o slot → o outro morre junto, sem
+ *          coordenação entre stores.
+ *        • **Contador de tentativas persistido SEM limiter** — o contador vive
+ *          DENTRO do slot. O lockout é imposto pelo próprio contador persistido
+ *          (fail-CLOSED: não depende do `@adonisjs/limiter`), ao contrário do
+ *          `otp_lockout.ts`, que vira no-op sem limiter — perigoso para um código
+ *          curto. O throttle de rota (`authkit_otp_login`) é camada EXTRA por IP.
+ *        • **TTL herdado** — a coluna `passwordResetExpiresAt` já dá validade ao
+ *          link; o código carrega o próprio `codeExpMs` embutido (mais curto).
+ *
+ *   3. Coluna nova via ensure-schema — desnecessária (a opção 2 não exige
+ *      migração), então descartada.
+ *
+ * ── Formato do slot (`ml2:`) ─────────────────────────────────────────────────
+ *   Armazenado:  `ml2:<linkToken>:<codeHash>:<codeExpMs>:<attempts>`
+ *   Na URL:      `ml2:<linkToken>`  (SÓ o token do link — o código, o hash e o
+ *                contador NUNCA saem no e-mail/URL, então o atacante não tem como
+ *                zerar o contador manipulando o que ele recebe).
+ *
+ *   • `linkToken` — 32 bytes hex; é o token do magic link (mesma força de antes).
+ *   • `codeHash`  — `sha256(<uid>:<code>)` em hex, ou VAZIO quando o código foi
+ *                   invalidado por lockout (o link continua válido e localizável).
+ *                   Atrelar ao `uid` da interaction honra o escopo "por
+ *                   interaction" do spec: um código emitido numa interaction não
+ *                   verifica em outra, mesmo para o mesmo e-mail.
+ *   • `codeExpMs` — epoch ms de expiração DO CÓDIGO (TTL curto, default 10 min).
+ *   • `attempts`  — contador server-side de tentativas erradas (começa em 0).
+ *
+ * Segurança do contador: como o link e o código compartilham o slot mas o
+ * LOCKOUT do código NÃO pode matar o link (spec), a invalidação por lockout zera
+ * o `codeHash` (mantendo `linkToken`) em vez de limpar o slot inteiro.
+ */
+import { createHash, randomInt, timingSafeEqual } from 'node:crypto';
+export const OTP_LOGIN_DEFAULTS = {
+    enabled: false,
+    digits: 6,
+    ttlMinutes: 10,
+    maxAttempts: 5,
+};
+/** Resolve/normaliza a config `login.otp` com os defaults e limites de sanidade. */
+export function resolveOtpLoginConfig(input) {
+    const digitsRaw = input?.digits;
+    const digits = typeof digitsRaw === 'number' && digitsRaw >= 4 && digitsRaw <= 10
+        ? Math.floor(digitsRaw)
+        : OTP_LOGIN_DEFAULTS.digits;
+    const ttlRaw = input?.ttlMinutes;
+    const ttlMinutes = typeof ttlRaw === 'number' && ttlRaw >= 1 ? Math.floor(ttlRaw) : OTP_LOGIN_DEFAULTS.ttlMinutes;
+    const maxRaw = input?.maxAttempts;
+    const maxAttempts = typeof maxRaw === 'number' && maxRaw >= 1 ? Math.floor(maxRaw) : OTP_LOGIN_DEFAULTS.maxAttempts;
+    return {
+        enabled: input?.enabled ?? OTP_LOGIN_DEFAULTS.enabled,
+        digits,
+        ttlMinutes,
+        maxAttempts,
+    };
+}
+// ---------------------------------------------------------------------------
+// Geração e hashing do código
+// ---------------------------------------------------------------------------
+/**
+ * Gera um código numérico de `digits` dígitos, zero-padded, SEM viés de módulo.
+ *
+ * Usa `crypto.randomInt(0, 10 ** digits)` — o `randomInt` do Node faz rejection
+ * sampling internamente, então a distribuição é uniforme (nada de `% 10`, que
+ * enviesaria os dígitos baixos). Para `digits=6` o teto é 1_000_000, bem abaixo
+ * do limite de `randomInt` (2**48).
+ */
+export function generateOtpCode(digits) {
+    const max = 10 ** digits;
+    const n = randomInt(0, max);
+    return String(n).padStart(digits, '0');
+}
+/**
+ * Hash do código atrelado ao `uid` da interaction: `sha256(<uid>:<code>)` em hex.
+ * Atrelar ao uid escopa o código à interaction que o emitiu.
+ */
+export function hashLoginOtp(uid, code) {
+    return createHash('sha256').update(`${uid}:${code}`).digest('hex');
+}
+/**
+ * Comparação constant-time de dois digests hex de MESMO tamanho.
+ *
+ * `timingSafeEqual` exige buffers de tamanho igual — comprimentos diferentes
+ * lançam. Por isso a guarda de tamanho vem antes (retorno `false` sem vazar
+ * timing útil: o atacante não controla o tamanho do digest server-side, que é
+ * sempre 64 hex de um sha256).
+ */
+export function safeEqualHex(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return false;
+    const bufA = Buffer.from(a, 'hex');
+    const bufB = Buffer.from(b, 'hex');
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+// ---------------------------------------------------------------------------
+// Codec do slot composto `ml2:`
+// ---------------------------------------------------------------------------
+/** Prefixo do slot `passwordResetToken` quando o login por OTP está ativo. */
+export const OTP_LOGIN_PREFIX = 'ml2:';
+/** Só hex minúsculo (64 chars = sha256). Guard contra metacaracteres de LIKE. */
+const HEX_64 = /^[0-9a-f]{64}$/;
+/** Serializa o estado do OTP no formato de slot `ml2:...`. */
+export function encodeOtpToken(state) {
+    return `${OTP_LOGIN_PREFIX}${state.linkToken}:${state.codeHash}:${state.codeExpMs}:${state.attempts}`;
+}
+/**
+ * Decodifica o valor ARMAZENADO no slot (`ml2:<linkToken>:<codeHash>:<exp>:<att>`).
+ * Retorna `null` se não for um slot `ml2:` bem-formado.
+ */
+export function decodeOtpToken(value) {
+    if (!value || !value.startsWith(OTP_LOGIN_PREFIX))
+        return null;
+    const rest = value.slice(OTP_LOGIN_PREFIX.length);
+    const parts = rest.split(':');
+    if (parts.length !== 4)
+        return null;
+    const [linkToken, codeHash, expStr, attStr] = parts;
+    if (!HEX_64.test(linkToken))
+        return null;
+    if (codeHash !== '' && !HEX_64.test(codeHash))
+        return null;
+    const codeExpMs = Number(expStr);
+    const attempts = Number(attStr);
+    if (!Number.isFinite(codeExpMs) || !Number.isInteger(attempts) || attempts < 0)
+        return null;
+    return { linkToken, codeHash, codeExpMs, attempts };
+}
+/**
+ * Extrai o `linkToken` de uma URL de magic link `ml2:<linkToken>` (a forma que
+ * vai no e-mail, SEM o estado do código). Retorna `null` se não casar o formato
+ * ou se o token não for hex de 64 (guarda contra LIKE injection na busca).
+ */
+export function linkTokenFromOtpUrl(urlToken) {
+    if (!urlToken.startsWith(OTP_LOGIN_PREFIX))
+        return null;
+    const linkToken = urlToken.slice(OTP_LOGIN_PREFIX.length);
+    return HEX_64.test(linkToken) ? linkToken : null;
+}
+/**
+ * Avalia UMA tentativa de código, na ORDEM travada pelo spec:
+ *   lockout (contador/estado do código) → TTL do código → comparação constant-time.
+ *
+ * O throttle de rota e a validade da interaction são resolvidos ANTES, no
+ * controller. Aqui mora só a lógica que precisa do estado persistido do código.
+ *
+ * IMPORTANTE (prova de mutação): a checagem de LOCKOUT é a primeira guarda. Se
+ * removida, um atacante que já esgotou as tentativas volta a poder chutar — o
+ * teste `remove-lockout` cobre exatamente isso.
+ */
+export function evaluateLoginOtp(input) {
+    const { parsed, uid, code, nowMs, maxAttempts } = input;
+    // Sem código pendente (slot vazio, `ml:` legado ou token de reset).
+    if (!parsed)
+        return { result: 'no_code' };
+    // LOCKOUT: código já invalidado (hash vazio) OU tentativas esgotadas.
+    // Fail-CLOSED — imposto pelo contador PERSISTIDO, sem depender de limiter.
+    if (parsed.codeHash === '' || parsed.attempts >= maxAttempts) {
+        return { result: 'locked' };
+    }
+    // TTL do código (mais curto que o do link).
+    if (parsed.codeExpMs < nowMs)
+        return { result: 'expired' };
+    // Comparação constant-time do hash atrelado ao uid.
+    const candidate = hashLoginOtp(uid, code);
+    if (safeEqualHex(candidate, parsed.codeHash)) {
+        // Sucesso: limpa o slot → mata o magic link junto (single-use conjunto).
+        return { result: 'ok', nextToken: null };
+    }
+    // Falha: incrementa o contador.
+    const attempts = parsed.attempts + 1;
+    if (attempts >= maxAttempts) {
+        // Última tentativa: INVALIDA o código (zera o hash) mas PRESERVA o link.
+        return { result: 'locked', nextToken: encodeOtpToken({ ...parsed, codeHash: '', attempts }) };
+    }
+    return { result: 'invalid', nextToken: encodeOtpToken({ ...parsed, attempts }) };
+}

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

@@ -30,6 +30,12 @@ export interface AuthThrottles {
      * orçamentos não poderem se consumir.
      */
     sudo: ThrottleMiddleware;
+    /**
+     * Throttle da verificação de código OTP de login, keyed por IP em bucket
+     * PRÓPRIO (`authkit_otp_login`) e mais apertado que o `login`. Primeira barreira
+     * anti-brute-force do código adivinhável, ANTES do lockout por interaction.
+     */
+    otpLogin: ThrottleMiddleware;
 }
 /**
  * Service do `@adonisjs/limiter` resolvido de forma preguiçosa. Tipado como `any`

package/build/src/host/rate_limit.js

@@ -96,5 +96,8 @@ export function createAuthThrottles(config) {
         // mesmo vindo do mesmo IP. Sem `usingKey` próprio de propósito: inventar uma
         // key aqui seria mudar o EIXO da contagem, e o eixo certo continua sendo o IP.
         sudo: buildThrottle('authkit_sudo', config.sudo, config.store),
+        // Verificação de código OTP: keyed por IP (default), bucket próprio e mais
+        // apertado que o login. O namespace do nome mantém a contagem separada.
+        otpLogin: buildThrottle('authkit_otp_login', config.otpLogin, config.store),
     };
 }

package/build/src/host/register_auth_host.js

@@ -256,6 +256,11 @@ export function registerAuthHost(router, opts = {}) {
         if (throttles)
             route.use([throttles.sudo]);
     };
+    // Bucket PRÓPRIO da verificação de código OTP: mais apertado que o login, por IP.
+    const withOtpLogin = (route) => {
+        if (throttles)
+            route.use([throttles.otpLogin]);
+    };
     // ─── 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.
@@ -286,6 +291,9 @@ export function registerAuthHost(router, opts = {}) {
     // 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']);
+    // Login por OTP (código digitável): verifica o código no bucket dedicado
+    // `authkit_otp_login` (por IP, mais apertado que o login).
+    withOtpLogin(router.post('/auth/interaction/:uid/otp-verify', [C.interaction, 'otpVerify']));
     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.

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.50.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')\"",