@adonis-agora/authkit-server 0.56.0 → 0.57.0

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/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/package.json

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