@adonis-agora/authkit-server 0.55.2 → 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/durable/account_deletion_workflow.d.ts

@@ -8,13 +8,15 @@ export interface AccountDeleteWorkflowInput {
     actor: DeletionActor;
 }
 /**
- * Forma mínima do `ctx` durável que o corpo usa (um `ctx.step` checkpointado e
- * idempotente). Tipada estruturalmente para NÃO acoplar o build do authkit ao
- * pacote `@adonis-agora/durable` (peer OPCIONAL): o app passa o `engine.register`
- * real e o ctx satisfaz esta interface em runtime.
+ * Forma mínima do `ctx` durável que o corpo usa (um `ctx.localStep` checkpointado
+ * e idempotente — executado IN-PROCESS, nunca dispatchado a um worker remoto;
+ * distinto do `ctx.step` do engine, que é SEMPRE dispatchado a um handler
+ * registrado por nome). Tipada estruturalmente para NÃO acoplar o build do
+ * authkit ao pacote `@adonis-agora/durable` (peer OPCIONAL): o app passa o
+ * `engine.register` real e o ctx satisfaz esta interface em runtime.
  */
 export interface DurableStepCtx {
-    step<T>(name: string, fn: (...args: any[]) => Promise<T>, options?: unknown): Promise<T>;
+    localStep<T>(name: string, fn: (...args: any[]) => Promise<T>, options?: unknown): Promise<T>;
 }
 /** A assinatura do corpo do workflow (compatível com `engine.register`). */
 export type WorkflowBody = (ctx: DurableStepCtx, input: AccountDeleteWorkflowInput) => Promise<unknown>;
@@ -35,9 +37,9 @@ export interface AccountDeletionWorkflowDeps {
  * ```
  *
  * O corpo é FORWARD-ONLY (sem compensação — nunca des-deleta): cada etapa do
- * cascade é um `ctx.step` checkpointado, com retry por-etapa e resumabilidade. A
+ * cascade é um `ctx.localStep` checkpointado, com retry por-etapa e resumabilidade. A
  * linha da conta é a ÚLTIMA etapa. Todos os efeitos colaterais ficam DENTRO de
- * `ctx.step` (corpo determinístico: nada de Date.now()/random no corpo). A
+ * `ctx.localStep` (corpo determinístico: nada de Date.now()/random no corpo). A
  * idempotência por `accountId` é feita pelo run-id no enqueue (ver
  * `enqueueAccountDeletion`).
  */

package/build/src/host/durable/account_deletion_workflow.js

@@ -30,9 +30,9 @@ function emptyResult() {
  * ```
  *
  * O corpo é FORWARD-ONLY (sem compensação — nunca des-deleta): cada etapa do
- * cascade é um `ctx.step` checkpointado, com retry por-etapa e resumabilidade. A
+ * cascade é um `ctx.localStep` checkpointado, com retry por-etapa e resumabilidade. A
  * linha da conta é a ÚLTIMA etapa. Todos os efeitos colaterais ficam DENTRO de
- * `ctx.step` (corpo determinístico: nada de Date.now()/random no corpo). A
+ * `ctx.localStep` (corpo determinístico: nada de Date.now()/random no corpo). A
  * idempotência por `accountId` é feita pelo run-id no enqueue (ver
  * `enqueueAccountDeletion`).
  */
@@ -42,7 +42,7 @@ export function defineAccountDeletionWorkflow(deps) {
         // Snapshot da conta ANTES de destruir (e-mail + avatar) — capturado num step
         // para ser determinístico no replay. Se a conta não existe (ou já foi
         // deletada num run anterior), encerra como no-op.
-        const snapshot = await ctx.step('snapshot', async () => {
+        const snapshot = await ctx.localStep('snapshot', async () => {
             const cfg = (await deps.oidc()).config;
             return snapshotAccount(cfg, accountId);
         });
@@ -50,36 +50,36 @@ export function defineAccountDeletionWorkflow(deps) {
             return emptyResult();
         const result = emptyResult();
         // 1) Audit `account.deleted` ANTES de qualquer destruição.
-        await ctx.step('audit.deleted', async () => {
+        await ctx.localStep('audit.deleted', async () => {
             const cfg = (await deps.oidc()).config;
             await auditDeleted(cfg, snapshot, actor);
         });
         // 2) Sessões + grants (cascateia os tokens do oidc-provider).
-        const revoke = await ctx.step('revoke.sessions', async () => revokeSessions(await deps.oidc(), accountId));
+        const revoke = await ctx.localStep('revoke.sessions', async () => revokeSessions(await deps.oidc(), accountId));
         result.sessions = revoke.sessions;
         result.grants = revoke.grants;
         result.accessTokens = revoke.accessTokens;
         result.refreshTokens = revoke.refreshTokens;
         // 3) Personal Access Tokens.
-        result.pats = (await ctx.step('revoke.pats', async () => revokePats((await deps.oidc()).config, accountId))).pats;
+        result.pats = (await ctx.localStep('revoke.pats', async () => revokePats((await deps.oidc()).config, accountId))).pats;
         // 4) Passkeys / credenciais WebAuthn.
-        result.passkeys = (await ctx.step('remove.passkeys', async () => removePasskeys((await deps.oidc()).config, accountId))).passkeys;
+        result.passkeys = (await ctx.localStep('remove.passkeys', async () => removePasskeys((await deps.oidc()).config, accountId))).passkeys;
         // 5) MFA / TOTP.
-        await ctx.step('disable.mfa', async () => {
+        await ctx.localStep('disable.mfa', async () => {
             await disableMfa((await deps.oidc()).config, accountId);
         });
         // 6) Identidades de provider linkadas.
-        result.providerIdentities = (await ctx.step('unlink.providers', async () => unlinkProviders((await deps.oidc()).config, accountId))).providerIdentities;
+        result.providerIdentities = (await ctx.localStep('unlink.providers', async () => unlinkProviders((await deps.oidc()).config, accountId))).providerIdentities;
         // 6b) Organizations.
-        const orgResult = await ctx.step('remove.orgs', async () => removeFromOrgs((await deps.oidc()).config, accountId));
+        const orgResult = await ctx.localStep('remove.orgs', async () => removeFromOrgs((await deps.oidc()).config, accountId));
         result.orgMemberships = orgResult.orgMemberships;
         result.orgInvitations = orgResult.orgInvitations;
         // 7) Avatar no drive.
-        result.avatarDeleted = (await ctx.step('delete.avatar', async () => deleteAccountAvatar((await deps.oidc()).config, accountId, snapshot.avatarUrl))).avatarDeleted;
+        result.avatarDeleted = (await ctx.localStep('delete.avatar', async () => deleteAccountAvatar((await deps.oidc()).config, accountId, snapshot.avatarUrl))).avatarDeleted;
         // 8) Anonimiza o histórico de audit.
-        result.auditAnonymized = (await ctx.step('anonymize.audit', async () => anonymizeAudit((await deps.oidc()).config, accountId))).auditAnonymized;
+        result.auditAnonymized = (await ctx.localStep('anonymize.audit', async () => anonymizeAudit((await deps.oidc()).config, accountId))).auditAnonymized;
         // 9) Deleta a linha da conta (ÚLTIMA etapa, forward-only).
-        result.ok = (await ctx.step('delete.account', async () => deleteAccountRow((await deps.oidc()).config, accountId))).ok;
+        result.ok = (await ctx.localStep('delete.account', async () => deleteAccountRow((await deps.oidc()).config, accountId))).ok;
         return result;
     };
     return { name: ACCOUNT_DELETE_WORKFLOW, version: '1', body };

package/build/src/host/durable/account_export_workflow.d.ts

@@ -50,7 +50,7 @@ export interface AccountExportWorkflowDeps {
 /**
  * Define a REGISTRAÇÃO do workflow durável `authkit.account.export`.
  *
- * Etapas (todas efeitos colaterais dentro de `ctx.step`, corpo determinístico):
+ * Etapas (todas efeitos colaterais dentro de `ctx.localStep`, corpo determinístico):
  *   1. `collect`  — reúne o payload (reusa {@link AccountExportService.collect});
  *   2. `audit`    — registra `account.exported`;
  *   3. `persist`  — serializa + grava o artefato no drive;

package/build/src/host/durable/account_export_workflow.js

@@ -45,7 +45,7 @@ const noopDeliver = async () => { };
 /**
  * Define a REGISTRAÇÃO do workflow durável `authkit.account.export`.
  *
- * Etapas (todas efeitos colaterais dentro de `ctx.step`, corpo determinístico):
+ * Etapas (todas efeitos colaterais dentro de `ctx.localStep`, corpo determinístico):
  *   1. `collect`  — reúne o payload (reusa {@link AccountExportService.collect});
  *   2. `audit`    — registra `account.exported`;
  *   3. `persist`  — serializa + grava o artefato no drive;
@@ -61,14 +61,14 @@ export function defineAccountExportWorkflow(deps) {
         const { accountId } = input;
         const runId = ctx.runId ?? accountId;
         // 1) Coleta o payload (reusa a coleta inline do AccountExportService).
-        const payload = await ctx.step('collect', async () => {
+        const payload = await ctx.localStep('collect', async () => {
             const oidc = await deps.oidc();
             return new AccountExportService(oidc).collect(accountId);
         });
         if (!payload)
             return { ok: false, artifactKey: null, bytes: 0 };
         // 2) Audita o export (account.exported).
-        await ctx.step('audit', async () => {
+        await ctx.localStep('audit', async () => {
             const cfg = (await deps.oidc()).config;
             await cfg.audit?.record({
                 type: 'account.exported',
@@ -78,12 +78,12 @@ export function defineAccountExportWorkflow(deps) {
         });
         // 3) Serializa + persiste o artefato.
         const json = JSON.stringify(payload, null, 2);
-        const artifactKey = await ctx.step('persist', async () => {
+        const artifactKey = await ctx.localStep('persist', async () => {
             const oidc = await deps.oidc();
             return persist({ accountId, runId, json, oidc });
         });
         // 4) Entrega ao titular (signal + e-mail, pluggable).
-        await ctx.step('deliver', async () => {
+        await ctx.localStep('deliver', async () => {
             const oidc = await deps.oidc();
             await deliver({ accountId, runId, artifactKey, oidc });
         });

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();