@adonis-agora/authkit-server 0.61.4 → 0.63.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/audit/audit_sink.d.ts

@@ -8,7 +8,7 @@
  * varre os `audit.record({ type: ... })` do `src/` e falha quando um evento
  * emitido não está aqui.
  */
-export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'mfa.enabled', 'mfa.disabled', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'roles_catalog.updated'];
+export declare const AUDIT_EVENT_TYPES: readonly ['login.success', 'login.failure', 'signup', 'password_reset.issued', 'password_reset.consumed', 'pat.issued', 'pat.revoked', 'pat.used', 'impersonation', 'impersonation.panel_viewed', 'impersonation.stopped', 'mfa.enabled', 'mfa.disabled', 'account.locked', 'passkey.registered', 'passkey.removed', 'email_verification.issued', 'email_verification.consumed', 'client.created', 'client.updated', 'client.deleted', 'session.revoked_all', 'password.changed', 'password.rehashed', 'email.change_requested', 'email.changed', 'login.new_ip_notified', 'login.new_device', 'login.otp_sent', 'login.otp_verified', 'login.otp_failed', 'login.otp_invalidated', 'bot_protection.rejected', 'grant.revoked_by_user', 'user.created', 'user.password_reset_sent', 'user.disabled', 'user.enabled', 'user.deleted', 'profile.updated', 'account.deleted', 'account.exported', 'keys.rotated', 'organization.created', 'organization.updated', 'organization.deleted', 'organization.member_added', 'organization.member_removed', 'organization.member_role_changed', 'organization.member_role_updated', 'organization.switched', 'organization.deactivated', 'organization.invitation_sent', 'organization.invitation_accepted', 'organization.invitation_revoked', 'email_change.requested', 'email_change.confirmed', 'email_change.cancelled', 'security_notice.sent', 'settings.updated', 'maintenance.enabled', 'maintenance.disabled', 'trusted_device.revoked', 'password.expired_change_forced', 'otp.locked', 'otp.unlocked', 'otp.unlock_failed', 'sudo.confirmed', 'session.single_enforced', 'account.expired_login_blocked', 'account.expiration_warned', 'login.magic_link_sent', 'session.revoked', 'account.signed_out_all', 'client.secret_regenerated', 'roles_catalog.updated'];
 /** Tipos de eventos de auditoria relevantes para segurança emitidos pelo IdP. */
 export type AuditEventType = (typeof AUDIT_EVENT_TYPES)[number];
 /**

package/build/src/audit/audit_sink.js

@@ -24,6 +24,9 @@ export const AUDIT_EVENT_TYPES = [
     // acontecer. Manter os dois separados é o que impede a trilha de auditoria de
     // afirmar uma impersonação que só foi consultada.
     'impersonation.panel_viewed',
+    // Uma impersonation foi encerrada no RP (`stopImpersonation`, com o
+    // `impersonationId` no metadata). Fecha o par aberto pelo `impersonation`.
+    'impersonation.stopped',
     'mfa.enabled',
     'mfa.disabled',
     'account.locked',

package/build/src/host/admin_api/dto.d.ts

@@ -48,7 +48,7 @@ export declare function grantDto(grant: AdminGrant): {
 };
 export declare function auditDto(event: StoredAuditEvent): {
     id: string;
-    type: "account.deleted" | "account.expiration_warned" | "account.expired_login_blocked" | "account.exported" | "account.locked" | "account.signed_out_all" | "bot_protection.rejected" | "client.created" | "client.deleted" | "client.secret_regenerated" | "client.updated" | "email.change_requested" | "email.changed" | "email_change.cancelled" | "email_change.confirmed" | "email_change.requested" | "email_verification.consumed" | "email_verification.issued" | "grant.revoked_by_user" | "impersonation" | "impersonation.panel_viewed" | "keys.rotated" | "login.failure" | "login.magic_link_sent" | "login.new_device" | "login.new_ip_notified" | "login.otp_failed" | "login.otp_invalidated" | "login.otp_sent" | "login.otp_verified" | "login.success" | "maintenance.disabled" | "maintenance.enabled" | "mfa.disabled" | "mfa.enabled" | "organization.created" | "organization.deactivated" | "organization.deleted" | "organization.invitation_accepted" | "organization.invitation_revoked" | "organization.invitation_sent" | "organization.member_added" | "organization.member_removed" | "organization.member_role_changed" | "organization.member_role_updated" | "organization.switched" | "organization.updated" | "otp.locked" | "otp.unlock_failed" | "otp.unlocked" | "passkey.registered" | "passkey.removed" | "password.changed" | "password.expired_change_forced" | "password.rehashed" | "password_reset.consumed" | "password_reset.issued" | "pat.issued" | "pat.revoked" | "pat.used" | "profile.updated" | "roles_catalog.updated" | "security_notice.sent" | "session.revoked" | "session.revoked_all" | "session.single_enforced" | "settings.updated" | "signup" | "sudo.confirmed" | "trusted_device.revoked" | "user.created" | "user.deleted" | "user.disabled" | "user.enabled" | "user.password_reset_sent";
+    type: "account.deleted" | "account.expiration_warned" | "account.expired_login_blocked" | "account.exported" | "account.locked" | "account.signed_out_all" | "bot_protection.rejected" | "client.created" | "client.deleted" | "client.secret_regenerated" | "client.updated" | "email.change_requested" | "email.changed" | "email_change.cancelled" | "email_change.confirmed" | "email_change.requested" | "email_verification.consumed" | "email_verification.issued" | "grant.revoked_by_user" | "impersonation" | "impersonation.panel_viewed" | "impersonation.stopped" | "keys.rotated" | "login.failure" | "login.magic_link_sent" | "login.new_device" | "login.new_ip_notified" | "login.otp_failed" | "login.otp_invalidated" | "login.otp_sent" | "login.otp_verified" | "login.success" | "maintenance.disabled" | "maintenance.enabled" | "mfa.disabled" | "mfa.enabled" | "organization.created" | "organization.deactivated" | "organization.deleted" | "organization.invitation_accepted" | "organization.invitation_revoked" | "organization.invitation_sent" | "organization.member_added" | "organization.member_removed" | "organization.member_role_changed" | "organization.member_role_updated" | "organization.switched" | "organization.updated" | "otp.locked" | "otp.unlock_failed" | "otp.unlocked" | "passkey.registered" | "passkey.removed" | "password.changed" | "password.expired_change_forced" | "password.rehashed" | "password_reset.consumed" | "password_reset.issued" | "pat.issued" | "pat.revoked" | "pat.used" | "profile.updated" | "roles_catalog.updated" | "security_notice.sent" | "session.revoked" | "session.revoked_all" | "session.single_enforced" | "settings.updated" | "signup" | "sudo.confirmed" | "trusted_device.revoked" | "user.created" | "user.deleted" | "user.disabled" | "user.enabled" | "user.password_reset_sent";
     accountId: string | null;
     email: string | null;
     clientId: string | null;

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

@@ -1,4 +1,5 @@
 import type { HttpContext } from '@adonisjs/core/http';
+import type { AuditSink } from '../audit/audit_sink.js';
 /**
  * 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
@@ -25,6 +26,18 @@ export interface StartImpersonationParams {
     tokenEndpoint?: string;
     scope?: string;
     fetchImpl?: typeof fetch;
+    /**
+     * Vida máxima da impersonation em SEGUNDOS, contada do start. Quando
+     * definido, `impersonationState().active` passa a `false` após o prazo
+     * (expiração preguiçosa — nenhum timer roda; a leitura decide) e o stop
+     * continua restaurando o admin normalmente.
+     *
+     * OPCIONAL e ausente por default: sem ele a impersonation dura até o stop
+     * explícito / logout / fim da sessão (comportamento histórico — um default
+     * com prazo faria a impersonation "parar sozinha" para quem não configurou
+     * nada). Deve ser > 0.
+     */
+    maxAge?: number;
 }
 export interface ImpersonationState {
     active: boolean;
@@ -32,6 +45,52 @@ export interface ImpersonationState {
     targetId?: string;
     /** O admin real (impersonator), quando `active`. */
     impersonatorId?: string;
+    /** Id único desta impersonation (gerado no start). */
+    impersonationId?: string;
+    /** Epoch ms do start. */
+    startedAt?: number;
+    /** Epoch ms da expiração — só quando `maxAge` foi configurado. */
+    expiresAt?: number;
+    /**
+     * `act.sub` devolvido pelo token-exchange (o ator PROVADO pelo IdP, que
+     * deve coincidir com `impersonatorId`).
+     */
+    actSub?: string;
+    /**
+     * `expires_in` (segundos) do token trocado — INFORMATIVO: é a vida do token
+     * do lado do IdP, NÃO impõe expiração na sessão (só `maxAge` faz isso).
+     */
+    exchangeExpiresIn?: number;
+}
+/** Metadados aproveitados da resposta do token-exchange (só o que não é segredo). */
+export interface TokenExchangeResult {
+    /** `expires_in` (s) do token trocado, quando o IdP informa. */
+    expiresIn?: number;
+    /** `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
@@ -53,20 +112,54 @@ export declare function refreshAccessToken(ctx: HttpContext, params: Pick<StartI
  * impersonator (= `account_user_id` atual), regenera a sessão (anti-fixation) e
  * seta `account_user_id = targetId`.
  *
+ * Além da troca de identidade, registra a impersonation: um id único
+ * (`impersonationId`), o instante do start e — só com `maxAge` configurado —
+ * a expiração, mais os metadados não-secretos do exchange (`actSub`,
+ * `exchangeExpiresIn`). Devolve o estado criado (o mesmo shape de
+ * `impersonationState`).
+ *
  * - Se o exchange falhar, LANÇA e NÃO troca NADA na sessão.
- * - Recusa (lança) se já houver impersonation ativa (pare a atual antes).
+ * - Recusa (lança) se já houver impersonation ativa (pare a atual antes) —
+ *   inclusive expirada pelo prazo: expirar só apaga o `active` da leitura,
+ *   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<void>;
+export declare function startImpersonation(ctx: HttpContext, params: StartImpersonationParams): Promise<ImpersonationState>;
 /**
  * Estado da impersonation pra UI (ex.: banner). `active` quando há um impersonator
- * guardado na sessão.
+ * guardado na sessão E a impersonation não expirou (expiração preguiçosa: com
+ * `maxAge` configurado no start, passado o prazo a leitura devolve
+ * `active: false` — mas os dados seguem na sessão até o `stopImpersonation`
+ * explícito, que continua restaurando o admin normalmente).
+ *
+ * O shape evita keys com valor `undefined` (construção condicional): `{ active:
+ * false }` puro quando nunca houve impersonation.
  */
 export declare function impersonationState(ctx: HttpContext): ImpersonationState;
+/** Opções do `stopImpersonation`. */
+export interface StopImpersonationOptions {
+    /**
+     * Sink para auditar o encerramento (`impersonation.stopped`, com o
+     * `impersonationId`). Sem ele, o stop só mexe na sessão — o start segue
+     * auditado pelo IdP, mas o fim da impersonation não aparece na trilha.
+     */
+    audit?: AuditSink;
+    /** IP a registrar no evento de auditoria (o helper não lê o request). */
+    ip?: string | null;
+}
 /**
- * Encerra a impersonation: restaura `account_user_id = impersonator`, remove a
- * key de impersonation e regenera a sessão (anti-fixation). No-op quando não há
- * impersonation ativa.
+ * Encerra a impersonation: restaura `account_user_id = impersonator`, remove
+ * TODAS as keys de sessão de impersonation (id, tempos, prova do exchange) e
+ * regenera a sessão (anti-fixation). Devolve o estado encerrado (com o
+ * `impersonationId`, mesmo que já expirado pelo prazo) ou `null` quando não
+ * havia nenhuma ativa (no-op — sem audit, sem regenerate).
  *
  * O `admin_access_token` (a credencial do ADMIN usada como `subject_token` do
  * token-exchange) é PRESERVADO: ele é do admin — não do alvo — e o admin segue
@@ -75,4 +168,4 @@ export declare function impersonationState(ctx: HttpContext): ImpersonationState
  * session). O token segue curto (TTL do access token do RP) e o logout do app
  * (`ctx.session.clear()` em `AuthRpController.logout`) continua limpando tudo.
  */
-export declare function stopImpersonation(ctx: HttpContext): Promise<void>;
+export declare function stopImpersonation(ctx: HttpContext, options?: StopImpersonationOptions): Promise<ImpersonationState | null>;

package/build/src/host/impersonation_session.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { ACCOUNT_SESSION_KEY } from './account_session_key.js';
 /**
  * Ergonômico de SESSÃO de browser no RP para "personificar" (impersonate) um
@@ -22,6 +23,16 @@ const ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
  * implementação, leia via `impersonationState`.
  */
 const IMPERSONATOR_SESSION_KEY = 'impersonator_user_id';
+/**
+ * Keys de sessão do registro da impersonation (id + tempos + prova do
+ * exchange). Internas pelo mesmo motivo da key do impersonator: o contrato
+ * público é `impersonationState` / o retorno de `startImpersonation`.
+ */
+const IMPERSONATION_ID_SESSION_KEY = 'impersonation_id';
+const IMPERSONATION_STARTED_AT_SESSION_KEY = 'impersonation_started_at';
+const IMPERSONATION_EXPIRES_AT_SESSION_KEY = 'impersonation_expires_at';
+const IMPERSONATION_ACT_SESSION_KEY = 'impersonation_act_sub';
+const IMPERSONATION_EXCHANGE_EXPIRES_IN_SESSION_KEY = 'impersonation_exchange_expires_in';
 /**
  * Key de sessão que guarda o access token do admin, necessário como
  * `subject_token` do token-exchange. Interna: NÃO exporte o literal.
@@ -53,12 +64,55 @@ 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
  * adicioná-la inverteria a direção do grafo de pacotes (server = IdP toolkit). São
  * ~12 linhas; testável via `fetchImpl`. Lança se o IdP não responder 2xx (é o
  * gatekeeper: não-admin / token expirado ⇒ erro ⇒ a sessão não é tocada).
+ *
+ * Em sucesso devolve os metadados NÃO-secretos da resposta (`expires_in` e
+ * `act.sub`) — o access token trocado é DESCARTADO de propósito: é uma
+ * credencial bearer do alvo e nada no fluxo o consome depois do start
+ * (o app age como o alvo via troca de sessão, não via bearer). NUNCA guarde
+ * esse token na sessão. O parse do corpo é tolerante: IdP que responde 2xx
+ * sem JSON válido ainda conta como exchange OK, só sem metadados.
  */
 async function requestTokenExchange(params, subjectToken) {
     const body = new URLSearchParams({
@@ -79,9 +133,26 @@ 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 {
+        const data = (await res.json());
+        if (typeof data?.expires_in === 'number' && Number.isFinite(data.expires_in)) {
+            result.expiresIn = data.expires_in;
+        }
+        const act = data?.act;
+        if (act && typeof act.sub === 'string' && act.sub.length > 0) {
+            result.actSub = act.sub;
+        }
+    }
+    catch {
+        // Corpo fora do JSON esperado: exchange valeu, metadados ficam ausentes.
     }
+    return result;
 }
 /**
  * Renova o access token do admin via refresh grant (RFC 6749 §6), usando o
@@ -126,45 +197,81 @@ export async function refreshAccessToken(ctx, params) {
  * impersonator (= `account_user_id` atual), regenera a sessão (anti-fixation) e
  * seta `account_user_id = targetId`.
  *
+ * Além da troca de identidade, registra a impersonation: um id único
+ * (`impersonationId`), o instante do start e — só com `maxAge` configurado —
+ * a expiração, mais os metadados não-secretos do exchange (`actSub`,
+ * `exchangeExpiresIn`). Devolve o estado criado (o mesmo shape de
+ * `impersonationState`).
+ *
  * - Se o exchange falhar, LANÇA e NÃO troca NADA na sessão.
- * - Recusa (lança) se já houver impersonation ativa (pare a atual antes).
+ * - Recusa (lança) se já houver impersonation ativa (pare a atual antes) —
+ *   inclusive expirada pelo prazo: expirar só apaga o `active` da leitura,
+ *   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 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.
+    let exchange;
     try {
-        await requestTokenExchange(params, adminAccessToken);
+        exchange = 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))
+        // 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);
-        await requestTokenExchange(params, refreshed.accessToken);
+        exchange = 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();
+    const impersonationId = randomUUID();
+    const startedAt = Date.now();
+    const expiresAt = params.maxAge !== undefined ? startedAt + params.maxAge * 1000 : undefined;
     // ESCALAÇÃO DE PRIVILÉGIO (fechada por vinculação): trocar a conta aqui NÃO
     // pode carregar junto o sudo que o admin confirmou sobre a PRÓPRIA conta —
     // senão ele entraria personificando já com a graça aberta sobre a conta
@@ -173,24 +280,61 @@ export async function startImpersonation(ctx, params) {
     // `isSudoActive` a recusa sozinho assim que `ACCOUNT_SESSION_KEY` muda. A
     // garantia é estrutural — vale para qualquer troca de conta futura, sem
     // depender de um `forget` lembrado em cada nova transição.
+    ctx.session.put(IMPERSONATION_ID_SESSION_KEY, impersonationId);
+    ctx.session.put(IMPERSONATION_STARTED_AT_SESSION_KEY, startedAt);
+    if (expiresAt !== undefined)
+        ctx.session.put(IMPERSONATION_EXPIRES_AT_SESSION_KEY, expiresAt);
+    if (exchange.actSub)
+        ctx.session.put(IMPERSONATION_ACT_SESSION_KEY, exchange.actSub);
+    if (exchange.expiresIn !== undefined) {
+        ctx.session.put(IMPERSONATION_EXCHANGE_EXPIRES_IN_SESSION_KEY, exchange.expiresIn);
+    }
     ctx.session.put(IMPERSONATOR_SESSION_KEY, impersonatorId);
     ctx.session.put(ACCOUNT_SESSION_KEY, params.targetId);
+    return impersonationState(ctx);
 }
 /**
  * Estado da impersonation pra UI (ex.: banner). `active` quando há um impersonator
- * guardado na sessão.
+ * guardado na sessão E a impersonation não expirou (expiração preguiçosa: com
+ * `maxAge` configurado no start, passado o prazo a leitura devolve
+ * `active: false` — mas os dados seguem na sessão até o `stopImpersonation`
+ * explícito, que continua restaurando o admin normalmente).
+ *
+ * O shape evita keys com valor `undefined` (construção condicional): `{ active:
+ * false }` puro quando nunca houve impersonation.
  */
 export function impersonationState(ctx) {
     const impersonatorId = ctx.session.get(IMPERSONATOR_SESSION_KEY);
     if (!impersonatorId)
         return { active: false };
     const targetId = ctx.session.get(ACCOUNT_SESSION_KEY);
-    return { active: true, targetId, impersonatorId };
+    const state = { active: true, targetId, impersonatorId };
+    const impersonationId = ctx.session.get(IMPERSONATION_ID_SESSION_KEY);
+    if (impersonationId)
+        state.impersonationId = impersonationId;
+    const startedAt = ctx.session.get(IMPERSONATION_STARTED_AT_SESSION_KEY);
+    if (typeof startedAt === 'number')
+        state.startedAt = startedAt;
+    const expiresAt = ctx.session.get(IMPERSONATION_EXPIRES_AT_SESSION_KEY);
+    if (typeof expiresAt === 'number')
+        state.expiresAt = expiresAt;
+    const actSub = ctx.session.get(IMPERSONATION_ACT_SESSION_KEY);
+    if (actSub)
+        state.actSub = actSub;
+    const exchangeExpiresIn = ctx.session.get(IMPERSONATION_EXCHANGE_EXPIRES_IN_SESSION_KEY);
+    if (typeof exchangeExpiresIn === 'number')
+        state.exchangeExpiresIn = exchangeExpiresIn;
+    if (state.expiresAt !== undefined && Date.now() > state.expiresAt) {
+        state.active = false;
+    }
+    return state;
 }
 /**
- * Encerra a impersonation: restaura `account_user_id = impersonator`, remove a
- * key de impersonation e regenera a sessão (anti-fixation). No-op quando não há
- * impersonation ativa.
+ * Encerra a impersonation: restaura `account_user_id = impersonator`, remove
+ * TODAS as keys de sessão de impersonation (id, tempos, prova do exchange) e
+ * regenera a sessão (anti-fixation). Devolve o estado encerrado (com o
+ * `impersonationId`, mesmo que já expirado pelo prazo) ou `null` quando não
+ * havia nenhuma ativa (no-op — sem audit, sem regenerate).
  *
  * O `admin_access_token` (a credencial do ADMIN usada como `subject_token` do
  * token-exchange) é PRESERVADO: ele é do admin — não do alvo — e o admin segue
@@ -199,10 +343,10 @@ export function impersonationState(ctx) {
  * session). O token segue curto (TTL do access token do RP) e o logout do app
  * (`ctx.session.clear()` em `AuthRpController.logout`) continua limpando tudo.
  */
-export async function stopImpersonation(ctx) {
-    const impersonatorId = ctx.session.get(IMPERSONATOR_SESSION_KEY);
-    if (!impersonatorId)
-        return;
+export async function stopImpersonation(ctx, options) {
+    const stopped = impersonationState(ctx);
+    if (!stopped.impersonatorId)
+        return null;
     await ctx.session.regenerate();
     // Simétrico ao `startImpersonation`: o sudo obtido ENQUANTO personificava
     // ficaria valendo sobre a conta do admin ao voltar. A vinculação corta isso —
@@ -211,6 +355,24 @@ export async function stopImpersonation(ctx) {
     // Nota: se o admin tinha sudo sobre a própria conta ANTES de personificar e a
     // graça ainda não venceu, ele volta valendo. Correto e intencional: é a
     // confirmação dele, sobre a conta dele, dentro da janela dele.
-    ctx.session.put(ACCOUNT_SESSION_KEY, impersonatorId);
+    ctx.session.put(ACCOUNT_SESSION_KEY, stopped.impersonatorId);
     ctx.session.forget(IMPERSONATOR_SESSION_KEY);
+    ctx.session.forget(IMPERSONATION_ID_SESSION_KEY);
+    ctx.session.forget(IMPERSONATION_STARTED_AT_SESSION_KEY);
+    ctx.session.forget(IMPERSONATION_EXPIRES_AT_SESSION_KEY);
+    ctx.session.forget(IMPERSONATION_ACT_SESSION_KEY);
+    ctx.session.forget(IMPERSONATION_EXCHANGE_EXPIRES_IN_SESSION_KEY);
+    await options?.audit?.record({
+        type: 'impersonation.stopped',
+        accountId: stopped.targetId ?? null,
+        actorId: stopped.impersonatorId,
+        ip: options?.ip ?? null,
+        metadata: {
+            impersonationId: stopped.impersonationId ?? null,
+            startedAt: stopped.startedAt ?? null,
+            stoppedAt: Date.now(),
+            expired: !stopped.active,
+        },
+    });
+    return stopped;
 }

package/package.json

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