@adonis-agora/authkit-server 0.62.0 → 0.64.0

package/build/index.d.ts

@@ -69,8 +69,8 @@ export type { AuthMessages, I18nConfig } from './src/host/i18n.js';
 export { BUILTIN_MESSAGES, DEFAULT_LOCALE, DEFAULT_MESSAGES, PT_BR_MESSAGES, resolveMessages, translate, } from './src/host/i18n.js';
 export type { ImpersonationClientLike, ImpersonationPanel } from './src/host/impersonation.js';
 export { buildImpersonationPanel } from './src/host/impersonation.js';
-export type { ImpersonationState, StartImpersonationParams, } from './src/host/impersonation_session.js';
-export { impersonationState, refreshAccessToken, rememberAccessToken, rememberRefreshToken, startImpersonation, stopImpersonation, } from './src/host/impersonation_session.js';
+export type { ImpersonationStartErrorCode, ImpersonationState, StartImpersonationParams, StopImpersonationOptions, TokenExchangeResult, } from './src/host/impersonation_session.js';
+export { ImpersonationStartError, impersonationState, refreshAccessToken, rememberAccessToken, rememberRefreshToken, startImpersonation, stopImpersonation, } from './src/host/impersonation_session.js';
 export type { KeysStatus as ServerKeysStatus } from './src/host/key_rotation_actions.js';
 export { buildKeysStatus, rotateNow } from './src/host/key_rotation_actions.js';
 export type { OidcRpGuardEvents, OidcRpGuardOptions } from './src/host/oidc_rp_guard.js';

package/build/index.js

@@ -54,7 +54,7 @@ export { buildImpersonationPanel } from './src/host/impersonation.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 { impersonationState, refreshAccessToken, rememberAccessToken, rememberRefreshToken, startImpersonation, stopImpersonation, } from './src/host/impersonation_session.js';
+export { ImpersonationStartError, impersonationState, refreshAccessToken, rememberAccessToken, rememberRefreshToken, startImpersonation, stopImpersonation, } from './src/host/impersonation_session.js';
 // Key rotation actions — shared between the Admin REST API controller and the SDK embedded driver.
 export { buildKeysStatus, rotateNow } from './src/host/key_rotation_actions.js';
 // @adonisjs/auth integration (opt-in) — guard pra Relying Parties OIDC.

package/build/src/adapters/factory.d.ts

@@ -4,6 +4,24 @@ export type OidcAdapterClass = new (name: string) => OidcAdapter;
 export interface AdapterFactory {
     resolver(app: ApplicationService): Promise<OidcAdapterClass>;
 }
+/**
+ * Modelos do oidc-provider de vida curta, amarrados ao ciclo da sessão de
+ * login (nomes exatos que o provider passa ao adapter). Perder qualquer um
+ * deles custa no máximo um relogin — nunca um outage — então são os
+ * candidatos ao adapter da `session:` (Redis). Todo modelo fora daqui
+ * (`Client` em particular — sem ele nem a tela de login abre) fica no
+ * adapter default (durável).
+ */
+export declare const SESSION_SCOPED_MODELS: ReadonlySet<string>;
+/**
+ * Escolhe a classe de adapter pro nome do modelo: session-scoped vai pra
+ * `sessionClass`, o resto pra `defaultClass`. Pura (sem I/O) de propósito —
+ * o dispatcher do provider (`build_provider.ts`) e os serviços que instanciam
+ * adapter na mão (`AdminSessionsService`, account API) usam a MESMA regra.
+ * Sem `session.adapter` configurado as duas classes são a mesma (back-compat:
+ * tudo continua onde está hoje).
+ */
+export declare function pickModelAdapterClass(model: string, defaultClass: OidcAdapterClass, sessionClass: OidcAdapterClass): OidcAdapterClass;
 export interface RedisAdapterConfig {
     /** nome da conexão do @adonisjs/redis */
     connection: string;

package/build/src/adapters/factory.js

@@ -1,5 +1,40 @@
 import { DatabaseAdapter } from './database_adapter.js';
 import { RedisAdapter } from './redis_adapter.js';
+/**
+ * Modelos do oidc-provider de vida curta, amarrados ao ciclo da sessão de
+ * login (nomes exatos que o provider passa ao adapter). Perder qualquer um
+ * deles custa no máximo um relogin — nunca um outage — então são os
+ * candidatos ao adapter da `session:` (Redis). Todo modelo fora daqui
+ * (`Client` em particular — sem ele nem a tela de login abre) fica no
+ * adapter default (durável).
+ */
+export const SESSION_SCOPED_MODELS = new Set([
+    'Session',
+    'Interaction',
+    'Grant',
+    'AccessToken',
+    'RefreshToken',
+    'AuthorizationCode',
+    'DeviceCode',
+    'PushedAuthorizationRequest',
+    'BackchannelAuthenticationRequest',
+    'ClientCredentials',
+    'ReplayDetection',
+    // `RegistrationAccessToken`/`InitialAccessToken` ficam FORA de propósito:
+    // gerenciam o `Client` (rotação/reconfiguração) e precisam morar junto dele
+    // no backend durável — senão um flush do Redis orfana o gerenciamento.
+]);
+/**
+ * Escolhe a classe de adapter pro nome do modelo: session-scoped vai pra
+ * `sessionClass`, o resto pra `defaultClass`. Pura (sem I/O) de propósito —
+ * o dispatcher do provider (`build_provider.ts`) e os serviços que instanciam
+ * adapter na mão (`AdminSessionsService`, account API) usam a MESMA regra.
+ * Sem `session.adapter` configurado as duas classes são a mesma (back-compat:
+ * tudo continua onde está hoje).
+ */
+export function pickModelAdapterClass(model, defaultClass, sessionClass) {
+    return SESSION_SCOPED_MODELS.has(model) ? sessionClass : defaultClass;
+}
 export const adapters = {
     /**
      * Factory para o adapter Redis. O consumidor precisa ter o @adonisjs/redis

package/build/src/define_config.d.ts

@@ -706,6 +706,30 @@ export interface ResolvedInteractionRecoveryConfig {
 export interface AuthServerConfigInput {
     issuer: string;
     adapter: AdapterFactory;
+    /**
+     * Override do adapter pros modelos de vida curta (sessão e órbita dela —
+     * ver `SESSION_SCOPED_MODELS` em `adapters/factory.ts`). O `adapter` de cima
+     * continua sendo o default de TUDO (back-compat: sem `session`, nada muda);
+     * com `session.adapter`, os modelos session-scoped passam a usar ele e o
+     * resto (`Client` em particular) fica no `adapter`.
+     *
+     * O split recomendado: sessão no Redis (efêmero, TTL nativo, mesmo destino
+     * da sessão do app) e o resto no banco (durável — sem o `Client` nem a tela
+     * de login abre). Mesma connection Redis pros dois níveis de sessão é a
+     * recomendação (prefixos já namespaciam; destinos diferentes criam
+     * meio-logado e dois domínios de falha no logout), mas a lib não trava isso.
+     *
+     * ```ts
+     * defineConfig({
+     *   adapter: adapters.database({ connection: 'auth' }),
+     *   session: { adapter: adapters.redis({ connection: 'main' }) },
+     *   // ...
+     * })
+     * ```
+     */
+    session?: {
+        adapter?: AdapterFactory;
+    };
     /**
      * Clientes OIDC pré-carregados no provider ao subir. Útil para testes e
      * migrações pontuais. Para uso em produção, gerencie clients via console admin
@@ -1041,6 +1065,11 @@ export interface AuthServerConfigInput {
 export interface ResolvedServerConfig {
     issuer: string;
     AdapterClass: OidcAdapterClass;
+    /**
+     * Adapter dos modelos session-scoped (`SESSION_SCOPED_MODELS`). Sem
+     * `session.adapter` no input é a MESMA classe do `AdapterClass`.
+     */
+    SessionAdapterClass: OidcAdapterClass;
     clients: ClientConfig[];
     jwks: {
         keys: Record<string, any>[];

package/build/src/define_config.js

@@ -243,6 +243,11 @@ export function jwksAutoFallbackWarning(storePath) {
 export function defineConfig(config) {
     return configProvider.create(async (app) => {
         const AdapterClass = await config.adapter.resolver(app);
+        // `session.adapter` ausente ⇒ mesma classe do default (back-compat: o
+        // dispatcher vira identidade e tudo continua no adapter único de hoje).
+        const SessionAdapterClass = config.session?.adapter
+            ? await config.session.adapter.resolver(app)
+            : AdapterClass;
         // `jwks: 'auto'` → resolve env-aware: AUTHKIT_JWKS inline, senão managed em arquivo.
         const jwksConfig = config.jwks === 'auto'
             ? process.env.AUTHKIT_JWKS
@@ -323,6 +328,7 @@ export function defineConfig(config) {
         return {
             issuer: config.issuer,
             AdapterClass,
+            SessionAdapterClass,
             clients: config.clients ?? [],
             jwks: jwks,
             jwksConfig,

package/build/src/host/account_api/account_api_controller.js

@@ -495,9 +495,10 @@ export default class AccountApiController {
         if (!target) {
             return ctx.response.notFound(apiErr('not_found', 'Session not found.'));
         }
-        // Revoga via adapter diretamente.
-        const AdapterClass = service.config.AdapterClass;
-        const sessionAdapter = new AdapterClass('Session');
+        // Revoga via adapter diretamente (o da sessão — `Session` é
+        // session-scoped e pode viver em backend distinto do default).
+        const SessionAdapterClass = service.config.SessionAdapterClass ?? service.config.AdapterClass;
+        const sessionAdapter = new SessionAdapterClass('Session');
         await sessionAdapter.destroy(sessionId);
         await cfg.audit?.record({
             type: 'session.revoked',

package/build/src/host/admin_clients_service.js

@@ -19,8 +19,9 @@ export class AdminClientsService {
     #adapter;
     constructor(oidc) {
         this.oidc = oidc;
-        // O AdapterClass é o MESMO que o provider usa; instanciamos o model 'Client'
-        // para ler/gravar os mesmos artefatos que o oidc-provider persiste.
+        // `Client` NÃO é session-scoped: fica sempre no `AdapterClass` (default),
+        // os mesmos artefatos que o oidc-provider persiste — mesmo com `session:`
+        // configurado, clients continuam no backend durável.
         this.#adapter = new oidc.config.AdapterClass('Client');
     }
     /** Indica se o adapter suporta enumeração (capacidade opcional). */

package/build/src/host/admin_sessions_service.js

@@ -1,8 +1,10 @@
 import { getBootedApp } from '../../services/booted_app.js';
+import { pickModelAdapterClass } from '../adapters/factory.js';
 /**
- * Serviço de inspeção/revogação das SESSÕES e GRANTS ativos de uma conta,
- * persistidos pelo oidc-provider via o MESMO `AdapterClass` (mesmo padrão do
- * {@link AdminClientsService}). Encapsula:
+ * Serviço de inspeção/revogação das SESSÕES e GRANTS ativos de uma conta.
+ * Lê/escreve via `pickModelAdapterClass` (a MESMA regra do provider): com
+ * `session:` configurado, Session/Grant/tokens saem do adapter da sessão, não
+ * do default. Encapsula:
  *   - a enumeração via a capacidade opcional `list` do adapter (degrada quando
  *     ausente, igual ao CRUD de clients);
  *   - a destruição das sessões + grants da conta. Destruir um grant CASCATEIA a
@@ -16,16 +18,21 @@ import { getBootedApp } from '../../services/booted_app.js';
 const GLOBAL_SESSION_LIMIT = 500;
 export class AdminSessionsService {
     #AdapterClass;
+    #SessionAdapterClass;
     #accountStore;
     /** Conexão Lucid das tabelas authkit (schema `auth`) — onde vive auth_session_revocations. */
     #schemaConnection;
     constructor(oidc) {
         this.#AdapterClass = oidc.config.AdapterClass;
+        // `Session`/`Grant`/tokens vivem no adapter da sessão quando `session:`
+        // está configurado (default: o mesmo do `AdapterClass`). `??` cobre
+        // configs resolvidas por versões antigas do `defineConfig`.
+        this.#SessionAdapterClass = oidc.config.SessionAdapterClass ?? oidc.config.AdapterClass;
         this.#accountStore = oidc.config.accountStore;
         this.#schemaConnection = oidc.config.schema?.connection;
     }
     #adapter(model) {
-        return new this.#AdapterClass(model);
+        return new (pickModelAdapterClass(model, this.#AdapterClass, this.#SessionAdapterClass))(model);
     }
     /**
      * Grava uma revogação por `sub` na tabela compartilhada `auth_session_revocations`,

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

@@ -69,6 +69,29 @@ export interface TokenExchangeResult {
     /** `act.sub` (ator provado pelo IdP), quando o IdP informa. */
     actSub?: string;
 }
+/**
+ * Códigos de falha do `startImpersonation` — o controller mapeia cada um numa
+ * mensagem amigável (sem vazar segredo), em vez de um genérico único que
+ * obriga adivinhar entre "token expirado", "sem refresh" e "IdP recusou".
+ */
+export type ImpersonationStartErrorCode = 'already_active' | 'invalid_max_age' | 'no_admin_access_token' | 'no_account_session' | 'no_refresh_token' | 'refresh_rejected' | 'exchange_rejected';
+/**
+ * Erro do `startImpersonation` com `code` machine-readable. `status` é o HTTP
+ * do token/refresh endpoint; `idpError` é o campo `error` do corpo
+ * (`invalid_grant`, `invalid_request`, …) — um código de allowlist, NUNCA
+ * tokens nem `error_description` (pode ecoar segredos). `cause` encadeia o
+ * erro original (ex.: o 400 do exchange que motivou a tentativa de refresh).
+ */
+export declare class ImpersonationStartError extends Error {
+    readonly code: ImpersonationStartErrorCode;
+    readonly status?: number;
+    readonly idpError?: string;
+    constructor(code: ImpersonationStartErrorCode, message: string, options?: {
+        status?: number;
+        idpError?: string;
+        cause?: unknown;
+    });
+}
 /**
  * Renova o access token do admin via refresh grant (RFC 6749 §6), usando o
  * refresh token guardado por `rememberRefreshToken`. Retorna o novo access
@@ -101,6 +124,12 @@ export declare function refreshAccessToken(ctx: HttpContext, params: Pick<StartI
  *   encerrar continua explícito via `stopImpersonation`.
  * - Recusa (lança) se não houver access token do admin na sessão.
  * - Recusa (lança) `maxAge` não-positivo (fail-fast de misconfiguração).
+ *
+ * Toda falha é um `ImpersonationStartError` com `code` (`already_active`,
+ * `invalid_max_age`, `no_admin_access_token`, `no_account_session`,
+ * `no_refresh_token`, `refresh_rejected`, `exchange_rejected`) — o controller
+ * traduz cada um numa mensagem amigável. `status`/`idpError` carregam o HTTP
+ * e o `error` do IdP (códigos seguros, sem segredos) para o log server-side.
  */
 export declare function startImpersonation(ctx: HttpContext, params: StartImpersonationParams): Promise<ImpersonationState>;
 /**

package/build/src/host/impersonation_session.js

@@ -64,6 +64,42 @@ export function rememberAccessToken(ctx, accessToken) {
 export function rememberRefreshToken(ctx, refreshToken) {
     ctx.session.put(ADMIN_REFRESH_TOKEN_SESSION_KEY, refreshToken);
 }
+/**
+ * Erro do `startImpersonation` com `code` machine-readable. `status` é o HTTP
+ * do token/refresh endpoint; `idpError` é o campo `error` do corpo
+ * (`invalid_grant`, `invalid_request`, …) — um código de allowlist, NUNCA
+ * tokens nem `error_description` (pode ecoar segredos). `cause` encadeia o
+ * erro original (ex.: o 400 do exchange que motivou a tentativa de refresh).
+ */
+export class ImpersonationStartError extends Error {
+    code;
+    status;
+    idpError;
+    constructor(code, message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'ImpersonationStartError';
+        this.code = code;
+        if (options?.status !== undefined)
+            this.status = options.status;
+        if (options?.idpError !== undefined)
+            this.idpError = options.idpError;
+    }
+}
+/**
+ * Extrai o campo `error` do corpo de uma resposta de erro do token endpoint
+ * (`invalid_grant`, …). Tolerante: corpo ausente/fora de JSON/sem `error`
+ * string ⇒ `undefined`. Só o código — nunca `error_description` (pode ecoar
+ * segredos) nem o corpo cru.
+ */
+async function readIdpErrorCode(res) {
+    try {
+        const data = (await res.json());
+        return typeof data?.error === 'string' && data.error.length > 0 ? data.error : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * 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
@@ -97,8 +133,10 @@ async function requestTokenExchange(params, subjectToken) {
         body: body.toString(),
     });
     if (!res.ok) {
-        // NUNCA logamos tokens nem o corpo (pode ecoar segredos). Só o status.
-        throw new Error(`Token exchange failed: ${res.status}`);
+        // NUNCA logamos tokens nem o corpo (pode ecoar segredos). Só o status +
+        // o código `error` do IdP (allowlist como `invalid_grant`).
+        const idpError = await readIdpErrorCode(res);
+        throw new ImpersonationStartError('exchange_rejected', `Token exchange failed: ${res.status}${idpError ? ` (${idpError})` : ''}`, { status: res.status, idpError });
     }
     const result = {};
     try {
@@ -171,23 +209,29 @@ export async function refreshAccessToken(ctx, params) {
  *   encerrar continua explícito via `stopImpersonation`.
  * - Recusa (lança) se não houver access token do admin na sessão.
  * - Recusa (lança) `maxAge` não-positivo (fail-fast de misconfiguração).
+ *
+ * Toda falha é um `ImpersonationStartError` com `code` (`already_active`,
+ * `invalid_max_age`, `no_admin_access_token`, `no_account_session`,
+ * `no_refresh_token`, `refresh_rejected`, `exchange_rejected`) — o controller
+ * traduz cada um numa mensagem amigável. `status`/`idpError` carregam o HTTP
+ * e o `error` do IdP (códigos seguros, sem segredos) para o log server-side.
  */
 export async function startImpersonation(ctx, params) {
     if (ctx.session.get(IMPERSONATOR_SESSION_KEY)) {
-        throw new Error('Impersonation already active; stop the current one before starting another');
+        throw new ImpersonationStartError('already_active', 'Impersonation already active; stop the current one before starting another');
     }
     if (params.maxAge !== undefined && !(params.maxAge > 0)) {
-        throw new Error('Invalid maxAge: must be a positive number of seconds');
+        throw new ImpersonationStartError('invalid_max_age', 'Invalid maxAge: must be a positive number of seconds');
     }
     const adminAccessToken = ctx.session.get(ADMIN_ACCESS_TOKEN_SESSION_KEY);
     if (!adminAccessToken) {
-        throw new Error('No admin access token in session; call rememberAccessToken after login');
+        throw new ImpersonationStartError('no_admin_access_token', 'No admin access token in session; call rememberAccessToken after login');
     }
     const impersonatorId = ctx.session.get(ACCOUNT_SESSION_KEY);
     if (!impersonatorId) {
         // Não há admin logado para impersonar como — sem identidade para restaurar
         // depois. Recusa antes de qualquer chamada/mutação.
-        throw new Error('No account session; log in as the admin before impersonating');
+        throw new ImpersonationStartError('no_account_session', 'No account session; log in as the admin before impersonating');
     }
     // 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.
@@ -197,12 +241,26 @@ export async function startImpersonation(ctx, params) {
     }
     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))
+        // de novo. Sem refresh token / refresh falho → erro TIPADO (o controller
+        // distingue "entre de novo" de "IdP recusou"), com o 4xx original em `cause`.
+        const status = err instanceof ImpersonationStartError ? err.status : undefined;
+        const isExpiredToken = err instanceof Error && status !== undefined && status >= 400 && status < 500;
+        if (!isExpiredToken)
             throw err;
+        const hasRefreshToken = Boolean(ctx.session.get(ADMIN_REFRESH_TOKEN_SESSION_KEY));
+        if (!hasRefreshToken) {
+            throw new ImpersonationStartError('no_refresh_token', `Admin access token expired (Token exchange failed: ${status}${err instanceof ImpersonationStartError && err.idpError ? ` (${err.idpError})` : ''}) and no refresh token in session; log in again`, {
+                status,
+                ...(err instanceof ImpersonationStartError && err.idpError
+                    ? { idpError: err.idpError }
+                    : {}),
+                cause: err,
+            });
+        }
         const refreshed = await refreshAccessToken(ctx, params);
-        if (!refreshed)
-            throw err;
+        if (!refreshed) {
+            throw new ImpersonationStartError('refresh_rejected', 'Admin access token expired and refresh token was rejected; log in again', { status, cause: err });
+        }
         rememberAccessToken(ctx, refreshed.accessToken);
         if (refreshed.refreshToken)
             rememberRefreshToken(ctx, refreshed.refreshToken);

package/build/src/provider/build_provider.js

@@ -1,4 +1,5 @@
 import * as oidc from 'oidc-provider';
+import { pickModelAdapterClass } from '../adapters/factory.js';
 import { createDeviceSources } from './device_sources.js';
 import { createLogoutSources } from './logout_sources.js';
 /** Atualiza o holder mutável do TTL de sessão com os valores da setting. */
@@ -92,7 +93,12 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
         }
         : {};
     const provider = new oidc.Provider(config.issuer, {
-        adapter: config.AdapterClass,
+        // Dispatcher por modelo (suportado pelo oidc-provider: `Adapter` aceita
+        // função `(name) => adapter` além de classe). Session-scoped vai pro
+        // `SessionAdapterClass`, o resto pro `AdapterClass` — mesma regra de
+        // `pickModelAdapterClass`, usada também pelos serviços que instanciam
+        // adapter na mão. Sem `session.adapter`, as duas classes são a mesma.
+        adapter: ((name) => new (pickModelAdapterClass(name, config.AdapterClass, config.SessionAdapterClass))(name)),
         clients: config.clients.map((c) => ({
             client_id: c.clientId,
             client_secret: c.clientSecret,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "0.62.0",
+  "version": "0.64.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",