@adonis-agora/authkit-server 0.56.0 → 0.57.1

package/README.md

@@ -31,7 +31,7 @@ node ace add @adonis-agora/authkit-server
 # ou: pnpm add @adonis-agora/authkit-server && node ace configure @adonis-agora/authkit-server
 ```
 
-O `configure` publica `config/authkit_server.ts`, o model `app/models/auth_user.ts`,
+O `configure` publica `config/authkit.ts`, o model `app/models/auth_user.ts`,
 o controller de interactions (`app/controllers/auth_interaction_controller.ts`) e
 registra o provider.
 
@@ -89,7 +89,7 @@ Em todos os presets o controller ejetado é **casca**: a lógica vive em
 `details(ctx)`, `login(ctx, { email, password })` e `consent(ctx)`. Você edita só a parte de
 render/redirect.
 
-Quem decide se as credenciais valem é o `verifyCredentials` do `config/authkit_server.ts`
+Quem decide se as credenciais valem é o `verifyCredentials` do `config/authkit.ts`
 — é o que o `service.interactions.login` chama. O default consulta o `AuthUser` por e-mail e
 usa `verifyPassword`; sobrescreva para plugar sua própria base de usuários.
 
@@ -105,7 +105,7 @@ router.post('/auth/interaction/:uid/consent', [AuthInteractionController, 'conse
 
 ## Persistência
 
-Escolha o backend no `config/authkit_server.ts`:
+Escolha o backend no `config/authkit.ts`:
 - `adapters.redis({ connection })` — requer `@adonisjs/redis` configurado.
 - `adapters.database({ connection? })` — Lucid; rode a migração `authkit_oidc_payloads`.
 
@@ -116,7 +116,7 @@ de resolve) e as expõe de forma opt-in.
 
 ### Configuração
 
-No `config/authkit_server.ts`, use a chave `observability`:
+No `config/authkit.ts`, use a chave `observability`:
 
 ```ts
 observability: {

package/build/index.d.ts

@@ -129,7 +129,7 @@ export { resolveRegistration } from './src/define_config.js';
 export type { RegistrationConfigInput, ResolvedRegistrationConfig, } from './src/define_config.js';
 export { getAccountId, realAccountId, hasAccountSession, consoleLoginUrl, } from './src/host/console_session.js';
 export { ACCOUNT_SESSION_KEY } from './src/host/middleware/account_auth.js';
-export { rememberAccessToken, startImpersonation, impersonationState, stopImpersonation, } from './src/host/impersonation_session.js';
+export { rememberAccessToken, rememberRefreshToken, refreshAccessToken, startImpersonation, impersonationState, stopImpersonation, } from './src/host/impersonation_session.js';
 export type { StartImpersonationParams, ImpersonationState, } from './src/host/impersonation_session.js';
 export { SUDO_SESSION_KEY, SUDO_ACCOUNT_SESSION_KEY, SUDO_MODE_DEFAULTS, requireSudo, isSudoActive, markSudo, resolveEffectiveSudoMode, } from './src/host/sudo_mode.js';
 export type { SudoModeSetting, ResolvedSudoModeSetting, } from './src/host/sudo_mode.js';

package/build/index.js

@@ -91,7 +91,7 @@ export { ACCOUNT_SESSION_KEY } from './src/host/middleware/account_auth.js';
 // Session impersonation — RP-side glue that routes through the IdP's RFC 8693
 // token-exchange (the IdP validates the admin role + audits). See
 // src/host/impersonation_session.ts.
-export { rememberAccessToken, startImpersonation, impersonationState, stopImpersonation, } from './src/host/impersonation_session.js';
+export { rememberAccessToken, rememberRefreshToken, refreshAccessToken, startImpersonation, impersonationState, stopImpersonation, } from './src/host/impersonation_session.js';
 // Sudo mode — helpers for host controllers that require step-up authentication.
 export { SUDO_SESSION_KEY, SUDO_ACCOUNT_SESSION_KEY, SUDO_MODE_DEFAULTS, requireSudo, isSudoActive, markSudo, resolveEffectiveSudoMode, } from './src/host/sudo_mode.js';
 // SPI de métodos de confirmação de identidade (sudo mode).

package/build/src/define_config.d.ts

@@ -131,6 +131,19 @@ export interface MailHooks {
         unlockUrl: string;
         token: string;
     }) => Promise<void>;
+    /**
+     * Disparado pelo `authkit:expire-scan` quando uma conta está prestes a ser
+     * desativada por inatividade. Substitui o e-mail default de aviso quando
+     * fornecido. Best-effort, fire-and-forget; deduplicado pela janela de
+     * `warnDays` da setting `account_expiration`, então cada conta recebe no
+     * máximo um aviso por janela.
+     */
+    onAccountExpirationWarning?: (data: {
+        /** E-mail da conta que será desativada. */
+        email: string;
+        /** Dias restantes até a desativação. */
+        expiresInDays: number;
+    }) => Promise<void>;
     /**
      * Disparado após um evento de segurança (senha alterada, MFA habilitado/desabilitado,
      * passkey adicionada/removida, e-mail alterado). Substitui o e-mail default quando
@@ -888,15 +901,21 @@ export interface AuthServerConfigInput {
      */
     accessTokens?: AccessTokensConfig;
     /**
-     * Console admin do IdP (B6). Default: desligado. Quando ligado, o host também
-     * deve passar `admin: true` em {@link AuthHostOptions} no registro de rotas
-     * (a montagem das rotas acontece antes do config resolver).
+     * Console admin do IdP (B6). Default: desligado.
+     *
+     * Declarar esta chave TRAVA o liga/desliga: `registerAuthHost(router, { admin })`
+     * passa a ser ignorado (ver `deriveLockedRouteOptions`). Não repita o
+     * `enabled` no `start/routes.ts` — no máximo passe `admin: { prefix }`, que é
+     * estrutural e continua valendo.
      */
     admin?: AdminConfigInput;
     /**
-     * Admin REST API (R6). Default: desligada. Quando ligada, o host também deve
-     * passar `adminApi: true` em {@link AuthHostOptions} no registro de rotas (a
-     * montagem das rotas acontece antes do config resolver). Autenticação por API key.
+     * Admin REST API (R6). Default: desligada. Autenticação por API key.
+     *
+     * Declarar esta chave TRAVA o liga/desliga: `registerAuthHost(router, { adminApi })`
+     * passa a ser ignorado (ver `deriveLockedRouteOptions`). Não repita o
+     * `enabled` no `start/routes.ts` — no máximo passe `adminApi: { prefix }`, que
+     * é estrutural e continua valendo.
      */
     adminApi?: AdminApiConfigInput;
     /**
@@ -913,8 +932,16 @@ export interface AuthServerConfigInput {
      */
     resolveGeo?: ResolveGeo;
     /**
-     * Gestão automática do schema das tabelas do authkit (`authkit_oidc_payloads`,
-     * `auth_settings`, `auth_password_history` e as três de organizations).
+     * Gestão automática do schema das OITO tabelas do authkit:
+     * `authkit_oidc_payloads`, `auth_settings`, `auth_password_history`,
+     * `auth_mfa`, `auth_session_revocations` e as três de organizations
+     * (`auth_organizations`, `auth_organization_members`,
+     * `auth_organization_invitations`). Ver `TABLES` em `schema/ensure.ts` — a
+     * lista aqui existe para o leitor, mas quem manda é aquele array.
+     *
+     * FORA desta gestão: `authkit_keystore`, criada sob demanda pelo
+     * `LucidKeystoreVault` na primeira escrita, e as tabelas do MODEL do host
+     * (`auth_users` etc.), que são migrations do app.
      *
      * - `autoManage` (default `true`): no boot, cria as tabelas que faltam e
      *   adiciona colunas novas (aditivo — nunca dropa nem altera tipos).

package/build/src/doctor/checks.d.ts

@@ -138,9 +138,11 @@ export declare function checkEmailChange(input: DoctorInput): Finding | null;
  */
 export declare function checkSecurityNotifications(input: DoctorInput): Finding | null;
 /**
- * Verifica a capability de histórico de senhas.
- * - Informa se a tabela `auth_password_history` está presente.
- * - Avisa quando pepper está configurado como string (não array) — rotation recomendada.
+ * Verifica o pepper de senha (`accountStore.password.pepper`).
+ * - Silencioso quando não há pepper configurado.
+ * - Reporta o pepper como string e sugere a forma `[novo, antigo]`, que permite
+ *   rotação sem downtime (lazy re-hash no verify).
+ * - Reporta quantos peppers a rotação tem quando já é array.
  */
 export declare function checkPasswordPepper(input: DoctorInput): Finding | null;
 /**

package/build/src/doctor/checks.js

@@ -573,9 +573,11 @@ export function checkSecurityNotifications(input) {
     return null; // Silencioso quando tudo está ok (não-obrigatório).
 }
 /**
- * Verifica a capability de histórico de senhas.
- * - Informa se a tabela `auth_password_history` está presente.
- * - Avisa quando pepper está configurado como string (não array) — rotation recomendada.
+ * Verifica o pepper de senha (`accountStore.password.pepper`).
+ * - Silencioso quando não há pepper configurado.
+ * - Reporta o pepper como string e sugere a forma `[novo, antigo]`, que permite
+ *   rotação sem downtime (lazy re-hash no verify).
+ * - Reporta quantos peppers a rotação tem quando já é array.
  */
 export function checkPasswordPepper(input) {
     const store = input.authkitConfig?.accountStore;

package/build/src/host/config_locks.js

@@ -94,7 +94,7 @@ export class SettingLockedError extends Error {
     code = 'E_SETTING_LOCKED';
     key;
     constructor(key) {
-        super(`A setting "${key}" foi definida via defineConfig() e está travada — não pode ser alterada em runtime (console/Admin API). Remova-a do defineConfig para liberar a edição pela UI.`);
+        super(`The setting "${key}" is declared in defineConfig() and is therefore locked — it cannot be changed at runtime through the console or the Admin API. Remove it from defineConfig to hand the key back to the UI.`);
         this.name = 'SettingLockedError';
         this.key = key;
     }

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

@@ -4,10 +4,16 @@ import type { HttpContext } from '@adonisjs/core/http';
  * após o login). Necessário porque o token-exchange exige o access token do admin
  * como `subject_token`, e o RP normalmente descarta os tokens após o login.
  *
- * Access tokens são curtos: se expirar, `startImpersonation` falha e o admin
- * re-loga (aceitável; refresh fica pra depois — YAGNI).
+ * Access tokens são curtos: se expirar, `startImpersonation` renova via refresh
+ * token (`rememberRefreshToken`) e tenta de novo — o admin não precisa relogar.
  */
 export declare function rememberAccessToken(ctx: HttpContext, accessToken: string): void;
+/**
+ * Guarda o refresh token do admin (do scope `offline_access`), usado para
+ * renovar o access token expirado antes do token-exchange. Chame no callback
+ * OIDC do RP junto com `rememberAccessToken`.
+ */
+export declare function rememberRefreshToken(ctx: HttpContext, refreshToken: string): void;
 export interface StartImpersonationParams {
     /** Id do usuário-alvo a personificar. */
     targetId: string;
@@ -27,6 +33,20 @@ export interface ImpersonationState {
     /** O admin real (impersonator), quando `active`. */
     impersonatorId?: string;
 }
+/**
+ * Renova o access token do admin via refresh grant (RFC 6749 §6), usando o
+ * refresh token guardado por `rememberRefreshToken`. Retorna o novo access
+ * token (e o refresh token rotacionado, se o IdP emitir outro), ou null se não
+ * houver refresh token / o refresh falhar.
+ *
+ * O IdP deste pacote roda `refresh_token` grant por default
+ * (`build_provider.ts`: `grant_types: ['authorization_code', 'refresh_token']`),
+ * então o refresh é válido na configuração padrão.
+ */
+export declare function refreshAccessToken(ctx: HttpContext, params: Pick<StartImpersonationParams, 'issuer' | 'clientId' | 'clientSecret' | 'tokenEndpoint' | 'fetchImpl'>): Promise<{
+    accessToken: string;
+    refreshToken?: string;
+} | null>;
 /**
  * Inicia a impersonation: lê o access token do admin da sessão, chama o
  * token-exchange (o IdP valida a role admin e audita) e SÓ em sucesso guarda o

package/build/src/host/impersonation_session.js

@@ -27,17 +27,32 @@ const IMPERSONATOR_SESSION_KEY = 'impersonator_user_id';
  * `subject_token` do token-exchange. Interna: NÃO exporte o literal.
  */
 const ADMIN_ACCESS_TOKEN_SESSION_KEY = 'admin_access_token';
+/**
+ * Key de sessão que guarda o refresh token do admin (do `offline_access`),
+ * usado para renovar o access token expirado antes do token-exchange. Interna:
+ * NÃO exporte o literal.
+ */
+const ADMIN_REFRESH_TOKEN_SESSION_KEY = 'admin_refresh_token';
+const REFRESH_TOKEN_GRANT = 'refresh_token';
 /**
  * Guarda o access token do admin na sessão (chame no callback OIDC do RP, logo
  * após o login). Necessário porque o token-exchange exige o access token do admin
  * como `subject_token`, e o RP normalmente descarta os tokens após o login.
  *
- * Access tokens são curtos: se expirar, `startImpersonation` falha e o admin
- * re-loga (aceitável; refresh fica pra depois — YAGNI).
+ * Access tokens são curtos: se expirar, `startImpersonation` renova via refresh
+ * token (`rememberRefreshToken`) e tenta de novo — o admin não precisa relogar.
  */
 export function rememberAccessToken(ctx, accessToken) {
     ctx.session.put(ADMIN_ACCESS_TOKEN_SESSION_KEY, accessToken);
 }
+/**
+ * Guarda o refresh token do admin (do scope `offline_access`), usado para
+ * renovar o access token expirado antes do token-exchange. Chame no callback
+ * OIDC do RP junto com `rememberAccessToken`.
+ */
+export function rememberRefreshToken(ctx, refreshToken) {
+    ctx.session.put(ADMIN_REFRESH_TOKEN_SESSION_KEY, refreshToken);
+}
 /**
  * POST inline do RFC 8693 token-exchange. Inline (em vez de depender de
  * `@adonis-agora/authkit-client`) porque o client NÃO é dependência do server e
@@ -68,6 +83,43 @@ async function requestTokenExchange(params, subjectToken) {
         throw new Error(`Token exchange failed: ${res.status}`);
     }
 }
+/**
+ * Renova o access token do admin via refresh grant (RFC 6749 §6), usando o
+ * refresh token guardado por `rememberRefreshToken`. Retorna o novo access
+ * token (e o refresh token rotacionado, se o IdP emitir outro), ou null se não
+ * houver refresh token / o refresh falhar.
+ *
+ * O IdP deste pacote roda `refresh_token` grant por default
+ * (`build_provider.ts`: `grant_types: ['authorization_code', 'refresh_token']`),
+ * então o refresh é válido na configuração padrão.
+ */
+export async function refreshAccessToken(ctx, params) {
+    const refreshToken = ctx.session.get(ADMIN_REFRESH_TOKEN_SESSION_KEY);
+    if (!refreshToken)
+        return null;
+    const body = new URLSearchParams({
+        grant_type: REFRESH_TOKEN_GRANT,
+        refresh_token: refreshToken,
+        client_id: params.clientId,
+    });
+    if (params.clientSecret)
+        body.set('client_secret', params.clientSecret);
+    const fetchImpl = params.fetchImpl ?? fetch;
+    const res = await fetchImpl(params.tokenEndpoint ?? `${params.issuer}/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    if (!data.access_token)
+        return null;
+    const result = { accessToken: data.access_token };
+    if (data.refresh_token)
+        result.refreshToken = data.refresh_token;
+    return result;
+}
 /**
  * Inicia a impersonation: lê o access token do admin da sessão, chama o
  * token-exchange (o IdP valida a role admin e audita) e SÓ em sucesso guarda o
@@ -94,7 +146,22 @@ export async function startImpersonation(ctx, params) {
     }
     // O IdP é o gatekeeper: lança se o admin não puder personificar. Chamado ANTES
     // de qualquer mutação de sessão — em caso de erro nada é trocado.
-    await requestTokenExchange(params, adminAccessToken);
+    try {
+        await requestTokenExchange(params, adminAccessToken);
+    }
+    catch (err) {
+        // Access token expirado (4xx do exchange): renova via refresh token e tenta
+        // de novo. Sem refresh token / refresh falho → propaga o erro original.
+        if (!(err instanceof Error) || !/exchange failed: 4\d\d/.test(err.message))
+            throw err;
+        const refreshed = await refreshAccessToken(ctx, params);
+        if (!refreshed)
+            throw err;
+        rememberAccessToken(ctx, refreshed.accessToken);
+        if (refreshed.refreshToken)
+            rememberRefreshToken(ctx, refreshed.refreshToken);
+        await requestTokenExchange(params, refreshed.accessToken);
+    }
     // Anti-fixation: rotaciona o id da sessão (mantém os dados) antes de gravar a
     // nova identidade. Mesmo padrão do consumidor real no RP.
     await ctx.session.regenerate();

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

@@ -39,14 +39,23 @@ export interface AuthHostOptions {
      * Login social opt-in; quando presente, monta as rotas sociais (usam ctx.ally).
      * Necessário aqui (e não só no config) porque a decisão de montar as rotas é
      * tomada em tempo de registro, antes do config (lazy) resolver.
+     *
+     * POLÍTICA: se o `defineConfig` declarou `social`, ele vence e este argumento
+     * é IGNORADO (com `console.warn` + entrada em `overriddenByConfig`). NÃO
+     * espelhe o config aqui — omitir a chave já herda dele. Use este argumento só
+     * quando o config NÃO declara `social`.
      */
     social?: AuthSocialConfig;
     /**
      * Rate-limiting (anti-brute-force) das rotas sensíveis. Necessário aqui (e não
      * só no config) porque a aplicação do throttle acontece em tempo de registro de
-     * rota. Ligado por default (mesma resolução do config). Espelhe o `rateLimit` de
-     * config/authkit.ts. Se `@adonisjs/limiter` não estiver configurado no host
-     * (config/limiter.ts), o throttle vira no-op (fail-safe).
+     * rota. Ligado por default (mesma resolução do config). Se `@adonisjs/limiter`
+     * não estiver configurado no host (config/limiter.ts), o throttle vira no-op
+     * (fail-safe).
+     *
+     * POLÍTICA: se o `defineConfig` declarou `rateLimit`, ele vence e este
+     * argumento é IGNORADO (com `console.warn` + entrada em `overriddenByConfig`).
+     * NÃO espelhe o config aqui — omitir a chave já herda dele.
      */
     rateLimit?: RateLimitConfigInput;
     /**
@@ -60,7 +69,12 @@ export interface AuthHostOptions {
      *
      * Necessário aqui (e não só no config) porque a decisão de montar as rotas é
      * tomada em tempo de registro, antes do config (lazy) resolver.
-     * Espelhe o `admin.enabled` de config/authkit.ts.
+     *
+     * DOIS EIXOS: o LIGA/DESLIGA é POLÍTICA — se o `defineConfig` declarou
+     * `admin`, ele vence e o `true`/`false` daqui é IGNORADO (com `console.warn`
+     * + entrada em `overriddenByConfig`). O PREFIXO é ESTRUTURAL e o argumento
+     * sempre vence. Ou seja: com `admin` no config, passe no máximo
+     * `{ prefix: '...' }` aqui — nunca espelhe o `enabled`.
      *
      * @example
      * // Prefixo padrão
@@ -82,7 +96,11 @@ export interface AuthHostOptions {
      *
      * Necessário aqui (e não só no config) porque a decisão de montar as rotas é
      * tomada em tempo de registro, antes do config (lazy) resolver.
-     * Espelhe o `adminApi.enabled` de config/authkit.ts.
+     *
+     * DOIS EIXOS, como `admin`: o LIGA/DESLIGA é POLÍTICA (o `defineConfig`
+     * vence e o argumento é IGNORADO, com `console.warn`), o PREFIXO é
+     * ESTRUTURAL (o argumento vence). Com `adminApi` no config, passe no máximo
+     * `{ prefix: '...' }` aqui.
      *
      * @example
      * // Prefixo padrão (back-compat)
@@ -98,7 +116,10 @@ export interface AuthHostOptions {
      * Métodos de sudo cujas rotas devem ser montadas. Necessário aqui (e não só
      * no config) porque a decisão de MONTAR rotas acontece em tempo de registro,
      * antes de o config lazy resolver — mesma razão de `social`/`admin`/`rateLimit`.
-     * Espelhe o `sudo.methods` de config/authkit.ts.
+     *
+     * POLÍTICA: se o `defineConfig` declarou `sudo.methods`, ele vence e este
+     * argumento é IGNORADO (com `console.warn` + entrada em `overriddenByConfig`).
+     * NÃO espelhe o config aqui — omitir a chave já herda dele.
      *
      * SUBSTITUI os defaults, não acrescenta: a lista é do host. Quem quer manter
      * senha/passkey ao lado do método novo os inclui explicitamente

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.56.0",
+  "version": "0.57.1",
   "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",
-  "homepage": "https://github.com/DavideCarvalho/adonis-authkit/tree/main/packages/authkit-server#readme",
+  "homepage": "https://github.com/DavideCarvalho/adonis-agora-authkit/tree/main/packages/authkit-server#readme",
   "repository": {
     "type": "git",
     "url": "https://github.com/DavideCarvalho/adonis-agora-authkit.git",
     "directory": "packages/authkit-server"
   },
   "bugs": {
-    "url": "https://github.com/DavideCarvalho/adonis-authkit/issues"
+    "url": "https://github.com/DavideCarvalho/adonis-agora-authkit/issues"
   },
   "keywords": [
     "adonisjs",
@@ -108,7 +108,7 @@
     "oidc-provider": "9.11.3",
     "otplib": "12.0.1",
     "qrcode": "1.5.4",
-    "@adonis-agora/authkit-core": "0.7.0"
+    "@adonis-agora/authkit-core": "0.7.1"
   },
   "devDependencies": {
     "@adonis-agora/durable": "0.22.0",
@@ -150,7 +150,7 @@
     "react-error-boundary": "6.1.2",
     "nuqs": "2.9.5",
     "recharts": "3.10.1",
-    "@adonis-agora/authkit-react": "0.18.0"
+    "@adonis-agora/authkit-react": "0.18.1"
   },
   "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/src/password',{recursive:true});fs.copyFileSync('src/password/common_passwords.txt','build/src/password/common_passwords.txt')\"",