@adonis-agora/authkit-server 0.74.0 → 0.75.0

package/build/src/define_config.d.ts

@@ -622,11 +622,19 @@ export interface AdminConfigInput {
      * não altera mais o valor.
      */
     impersonation?: boolean;
+    /**
+     * Permite impersonar uma conta que também tem um dos `roles` de admin. Com
+     * `false`, o token-exchange recusa alvo admin (`invalid_grant`): um admin não
+     * assume a identidade de outro. Default: **`true`** (back-compat; virar o
+     * default é decisão de major, mesma regra de `impersonation`).
+     */
+    impersonateAdmins?: boolean;
 }
 export interface ResolvedAdminConfig {
     enabled: boolean;
     roles: string[];
     impersonation: boolean;
+    impersonateAdmins: boolean;
 }
 export declare function resolveAdmin(input?: AdminConfigInput): ResolvedAdminConfig;
 /**

package/build/src/define_config.js

@@ -174,6 +174,7 @@ export function resolveAdmin(input) {
         // Default `true`: preserva o comportamento histórico (grant sempre
         // registrado). Ver o docblock de `AdminConfigInput.impersonation`.
         impersonation: input?.impersonation !== false,
+        impersonateAdmins: input?.impersonateAdmins !== false,
     };
 }
 /** Lê API keys de `AUTHKIT_ADMIN_API_KEY` (uma ou várias, separadas por vírgula). */

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

@@ -18,6 +18,13 @@ export interface VerifiedAccessToken {
     exp: number | null;
     /** Id do token (`jti`), quando conhecido. */
     jti: string | null;
+    /**
+     * Quem está AGINDO quando o token é de impersonation (RFC 8693 `act.sub`, o
+     * admin que trocou o próprio token pelo do `sub`). `null` num token comum.
+     * É o que deixa o resource server tratar a request como impersonation
+     * (`impersonationState`/`realAccountId`) em vez de confundi-la com o alvo.
+     */
+    actor: string | null;
 }
 /**
  * Estratégia de verificação de access token plugável no `oidcBearerGuard`.

package/build/src/host/access_token_verifier.js

@@ -10,6 +10,11 @@ function rejectedJwt(error) {
         !(error instanceof joseErrors.JWKSTimeout) &&
         !(error instanceof joseErrors.JWKSInvalid));
 }
+/** `act.sub` (RFC 8693 §4.1) de um payload/`extra`/introspecção, ou `null`. */
+function actorOf(source) {
+    const act = source?.act;
+    return typeof act?.sub === 'string' && act.sub ? act.sub : null;
+}
 /** `header.payload.signature` em base64url — o formato compacto de um JWS. */
 const JWS_COMPACT = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
 function looksLikeJwt(token) {
@@ -44,6 +49,7 @@ function fromJwtPayload(payload) {
         audience: toAudience(payload.aud),
         exp: typeof payload.exp === 'number' ? payload.exp : null,
         jti: typeof payload.jti === 'string' ? payload.jti : null,
+        actor: actorOf(payload),
     };
 }
 /**
@@ -121,6 +127,7 @@ export function inProcessAccessTokenVerifier(resolveIssuer) {
                 audience: toAudience(at.aud),
                 exp: typeof at.exp === 'number' ? at.exp : null,
                 jti: typeof at.jti === 'string' ? at.jti : null,
+                actor: actorOf(at.extra),
             };
         },
         async issue(accountId, options = {}) {
@@ -212,6 +219,7 @@ export function remoteAccessTokenVerifier(options) {
             audience: toAudience(body.aud),
             exp: typeof body.exp === 'number' ? body.exp : null,
             jti: typeof body.jti === 'string' ? body.jti : null,
+            actor: actorOf(body),
         };
     };
     return {

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

@@ -7,3 +7,20 @@ export declare function clearBearerAccountId(ctx: object): void;
  * `oidcBearerGuard` autenticou (ainda) a request.
  */
 export declare function bearerAccountId(ctx: object): string | null;
+/**
+ * Impersonation carregada pelo access token bearer desta request: o ator
+ * (`act.sub`, o admin) e a expiração do token. Gravada pelo `oidcBearerGuard`
+ * só quando o token é de impersonation; lida por `impersonationState` e
+ * `realAccountId` quando não há sessão.
+ */
+export interface BearerImpersonation {
+    actorId: string;
+    /** Epoch em segundos do `exp` do token, quando conhecido. */
+    exp: number | null;
+    /** `jti` do token trocado, quando conhecido (correlaciona com a auditoria). */
+    jti: string | null;
+}
+/** Registra que o token bearer desta request é de impersonation. */
+export declare function setBearerImpersonation(ctx: object, value: BearerImpersonation): void;
+/** Impersonation do token bearer desta request, ou `null`. */
+export declare function bearerImpersonation(ctx: object): BearerImpersonation | null;

package/build/src/host/bearer_account.js

@@ -11,6 +11,7 @@
  * barrel) depende dele.
  */
 const bearerAccounts = new WeakMap();
+const bearerImpersonations = new WeakMap();
 /** Registra a conta autenticada via bearer nesta request. */
 export function setBearerAccountId(ctx, accountId) {
     bearerAccounts.set(ctx, accountId);
@@ -18,6 +19,7 @@ export function setBearerAccountId(ctx, accountId) {
 /** Esquece a conta bearer desta request (falha de autenticação). */
 export function clearBearerAccountId(ctx) {
     bearerAccounts.delete(ctx);
+    bearerImpersonations.delete(ctx);
 }
 /**
  * Id da conta autenticada via bearer nesta request, ou `null` quando nenhum
@@ -26,3 +28,11 @@ export function clearBearerAccountId(ctx) {
 export function bearerAccountId(ctx) {
     return bearerAccounts.get(ctx) ?? null;
 }
+/** Registra que o token bearer desta request é de impersonation. */
+export function setBearerImpersonation(ctx, value) {
+    bearerImpersonations.set(ctx, value);
+}
+/** Impersonation do token bearer desta request, ou `null`. */
+export function bearerImpersonation(ctx) {
+    return bearerImpersonations.get(ctx) ?? null;
+}

package/build/src/host/console_session.js

@@ -65,11 +65,9 @@ export function getAccountId(ctx) {
  * if (!id || !(await authz.hasRole(id, 'admin'))) throw new Error('forbidden')
  */
 export function realAccountId(ctx) {
-    // Sem sessão não há impersonation: mesma tolerância do `getAccountId` (que usa
-    // `ctx.session?.`), pois `impersonationState` assume uma sessão presente. Resta
-    // a identidade bearer (se o `oidcBearerGuard` autenticou a request).
-    if (!ctx.session)
-        return bearerAccountId(ctx);
+    // `impersonationState` cobre as duas fontes: a sessão do console e o access
+    // token bearer trocado (`act`, ex.: app nativo) — nos dois, o humano real é o
+    // impersonator. Sem impersonation, a conta da sessão ou do bearer.
     return impersonationState(ctx).impersonatorId ?? getAccountId(ctx);
 }
 /**

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

@@ -61,6 +61,11 @@ export interface ImpersonationState {
      * do lado do IdP, NÃO impõe expiração na sessão (só `maxAge` faz isso).
      */
     exchangeExpiresIn?: number;
+    /**
+     * De onde veio a impersonation: `session` (console/web, keys de sessão) ou
+     * `bearer` (access token trocado com `act`, ex.: app nativo). Só quando `active`.
+     */
+    source?: 'session' | 'bearer';
 }
 /** Metadados aproveitados da resposta do token-exchange (só o que não é segredo). */
 export interface TokenExchangeResult {

package/build/src/host/impersonation_session.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { ACCOUNT_SESSION_KEY } from './account_session_key.js';
+import { bearerAccountId, bearerImpersonation } from './bearer_account.js';
 /**
  * Ergonômico de SESSÃO de browser no RP para "personificar" (impersonate) um
  * usuário e navegar como ele — roteado pelo token-exchange RFC 8693 que o IdP já
@@ -304,11 +305,16 @@ export async function startImpersonation(ctx, params) {
  * false }` puro quando nunca houve impersonation.
  */
 export function impersonationState(ctx) {
-    const impersonatorId = ctx.session.get(IMPERSONATOR_SESSION_KEY);
-    if (!impersonatorId)
-        return { active: false };
+    const impersonatorId = ctx.session?.get(IMPERSONATOR_SESSION_KEY);
+    if (!impersonatorId) {
+        // Sessão de console logada manda (mesma regra do `getAccountId`): o bearer só
+        // conta quando a request não tem conta na sessão.
+        if (ctx.session?.get(ACCOUNT_SESSION_KEY))
+            return { active: false };
+        return bearerImpersonationState(ctx);
+    }
     const targetId = ctx.session.get(ACCOUNT_SESSION_KEY);
-    const state = { active: true, targetId, impersonatorId };
+    const state = { active: true, targetId, impersonatorId, source: 'session' };
     const impersonationId = ctx.session.get(IMPERSONATION_ID_SESSION_KEY);
     if (impersonationId)
         state.impersonationId = impersonationId;
@@ -329,6 +335,33 @@ export function impersonationState(ctx) {
     }
     return state;
 }
+/**
+ * Impersonation pelo ACCESS TOKEN (sem sessão): o `oidcBearerGuard` autenticou
+ * um token trocado que carrega `act`. O alvo é o `sub` do token; o impersonator,
+ * o `act.sub`; a expiração, o `exp` do token (o token trocado não tem refresh).
+ * Só existe depois que o guard bearer rodou na request, como o `getAccountId`.
+ */
+function bearerImpersonationState(ctx) {
+    const bearer = bearerImpersonation(ctx);
+    const targetId = bearerAccountId(ctx);
+    if (!bearer || !targetId)
+        return { active: false };
+    const state = {
+        active: true,
+        targetId,
+        impersonatorId: bearer.actorId,
+        actSub: bearer.actorId,
+        source: 'bearer',
+    };
+    if (bearer.jti)
+        state.impersonationId = bearer.jti;
+    if (bearer.exp !== null) {
+        state.expiresAt = bearer.exp * 1000;
+        if (Date.now() > state.expiresAt)
+            state.active = false;
+    }
+    return state;
+}
 /**
  * Encerra a impersonation: restaura `account_user_id = impersonator`, remove
  * TODAS as keys de sessão de impersonation (id, tempos, prova do exchange) e

package/build/src/host/oidc_bearer_guard.js

@@ -1,6 +1,6 @@
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { inProcessAccessTokenVerifier, remoteAccessTokenVerifier, } from './access_token_verifier.js';
-import { clearBearerAccountId, setBearerAccountId } from './bearer_account.js';
+import { clearBearerAccountId, setBearerAccountId, setBearerImpersonation, } from './bearer_account.js';
 import { cachedUnauthorizedAccessConstructor, loadUnauthorizedAccess, } from './oidc_rp_guard.js';
 /**
  * Driver do `E_UNAUTHORIZED_ACCESS` lançado pelo guard. `access_tokens` é o
@@ -144,10 +144,19 @@ export class OidcBearerGuard {
         const guardUser = await this.#userProvider.findById(token.sub);
         if (!guardUser)
             throw this.#fail('invalid_token');
+        // Token de impersonation: o ator (o admin) também tem que existir AGORA. Conta
+        // apagada/desativada depois da troca derruba o acesso na próxima request, sem
+        // esperar o `exp` do token.
+        if (token.actor && !(await this.#userProvider.findById(token.actor))) {
+            throw this.#fail('invalid_token');
+        }
         this.user = guardUser.getOriginal();
         this.accessToken = token;
         this.isAuthenticated = true;
         setBearerAccountId(this.#ctx, String(guardUser.getId()));
+        if (token.actor) {
+            setBearerImpersonation(this.#ctx, { actorId: token.actor, exp: token.exp, jti: token.jti });
+        }
         this.#emitter.emit('oidc_bearer:authentication_succeeded', {
             ctx: this.#ctx,
             guardName: this.#name,

package/build/src/provider/build_provider.js

@@ -5,6 +5,7 @@ import { assertClientMetadata } from '../host/client_metadata.js';
 import { createDeviceSources } from './device_sources.js';
 import { createLogoutSources } from './logout_sources.js';
 import { registrationPolicyMiddleware } from './registration_policy.js';
+import { impersonationExtraClaims } from './token_exchange.js';
 /** Atualiza o holder mutável do TTL de sessão com os valores da setting. */
 export function updateSessionTtlHolder(holder, policy) {
     holder.rememberSec = Math.max(1, Math.floor(policy.rememberDays * 86400));
@@ -118,6 +119,10 @@ export function buildProvider(config, options, sessionTtlHolder, tokenTtlHolder)
         }
         : {};
     const provider = new oidc.Provider(config.issuer, {
+        // O ator (`act`, RFC 8693) dos access tokens de impersonation — ver
+        // `impersonationExtraClaims` em `token_exchange.ts`. Sem isto o token trocado
+        // não se distingue de um token do próprio alvo no resource server.
+        extraTokenClaims: async (_ctx, token) => impersonationExtraClaims(token),
         // 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

package/build/src/provider/oidc_service.js

@@ -181,6 +181,7 @@ export class OidcService {
                 // conta que acabou de desabilitar, recebendo tokens plenamente funcionais.
                 accountStore: config.accountStore,
                 audit: config.audit,
+                impersonateAdmins: config.admin.impersonateAdmins,
             });
         }
         // Quando o issuer tem um path (ex.: http://host/oidc), o provider precisa ser

package/build/src/provider/token_exchange.d.ts

@@ -56,5 +56,31 @@ export interface TokenExchangeDeps {
      * regra de todo o resto da lib — nunca quebra hosts com um store mínimo).
      */
     accountStore?: AccountStore;
+    /**
+     * Permite impersonar uma conta que TAMBÉM tem um dos `adminRoles`. Default
+     * `true` (back-compat). Com `false`, alvo admin vira `invalid_grant`: um admin
+     * não assume a identidade (e os tokens) de outro admin.
+     */
+    impersonateAdmins?: boolean;
 }
+/**
+ * Propriedade (não persistida) onde a troca marca o ator ANTES do `save()`. O
+ * `extraTokenClaims` do provider (`build_provider.ts`) a transforma em
+ * `extra.act` — é o único jeito de pôr claims no `extra` de um token opaco: o
+ * oidc-provider SOBRESCREVE `extra` com o retorno desse hook ao salvar.
+ */
+export declare const IMPERSONATION_ACTOR_PROP = "authkitImpersonationActor";
+/** `extraTokenClaims` do provider: `{ act }` para token de impersonation, nada para o resto. */
+export declare function impersonationExtraClaims(token: unknown): {
+    act: {
+        sub: string;
+    };
+} | undefined;
+/**
+ * O ator de um access token de impersonation: o `act` (RFC 8693 §4.1) gravado
+ * no `extra` do token trocado. `null` quando o token não é de impersonation.
+ */
+export declare function impersonationActorOf(token: {
+    extra?: unknown;
+} | null | undefined): string | null;
 export declare function registerTokenExchange(provider: any, deps: TokenExchangeDeps): void;

package/build/src/provider/token_exchange.js

@@ -2,6 +2,26 @@ import { errors } from 'oidc-provider';
 import { assertAccountEnabled } from '../host/login_attempt.js';
 const TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
 const ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+/**
+ * Propriedade (não persistida) onde a troca marca o ator ANTES do `save()`. O
+ * `extraTokenClaims` do provider (`build_provider.ts`) a transforma em
+ * `extra.act` — é o único jeito de pôr claims no `extra` de um token opaco: o
+ * oidc-provider SOBRESCREVE `extra` com o retorno desse hook ao salvar.
+ */
+export const IMPERSONATION_ACTOR_PROP = 'authkitImpersonationActor';
+/** `extraTokenClaims` do provider: `{ act }` para token de impersonation, nada para o resto. */
+export function impersonationExtraClaims(token) {
+    const actor = token?.[IMPERSONATION_ACTOR_PROP];
+    return typeof actor === 'string' && actor ? { act: { sub: actor } } : undefined;
+}
+/**
+ * O ator de um access token de impersonation: o `act` (RFC 8693 §4.1) gravado
+ * no `extra` do token trocado. `null` quando o token não é de impersonation.
+ */
+export function impersonationActorOf(token) {
+    const act = token?.extra?.act;
+    return typeof act?.sub === 'string' && act.sub ? act.sub : null;
+}
 /**
  * Interseção entre os scopes pedidos e os scopes permitidos do client (allowlist).
  * Preserva a ordem do pedido. Nunca excede a allowlist do client.
@@ -30,6 +50,12 @@ export function registerTokenExchange(provider, deps) {
         if (!subjectAt || subjectAt.isExpired) {
             throw new errors.InvalidGrant('subject_token invalid or expired');
         }
+        // Sem impersonation encadeada: um token que JÁ é de impersonation não vira
+        // subject de outra troca (o "ator" seria a conta personificada, e a trilha
+        // perderia quem de fato está agindo).
+        if (impersonationActorOf(subjectAt)) {
+            throw new errors.InvalidGrant('subject_token is already an impersonation token');
+        }
         // O subject_token DEVE ter sido emitido para o MESMO client autenticado: senão
         // um client B poderia trocar um AT emitido para o client A (cross-client).
         if (subjectAt.clientId !== client?.clientId) {
@@ -62,6 +88,9 @@ export function registerTokenExchange(provider, deps) {
         if (!target) {
             throw new errors.InvalidGrant('requested_subject not found');
         }
+        if (target.id === actor.id) {
+            throw new errors.InvalidGrant('requested_subject must be another account');
+        }
         // Status do alvo (disabled/expirado): mesmo gate de `attemptPasswordLogin`.
         // Sem isso, impersonar um alvo desabilitado mintava tokens funcionais para
         // uma identidade que o admin acreditava ter revogado. `accountStore` é
@@ -107,8 +136,6 @@ export function registerTokenExchange(provider, deps) {
             // Client sem allowlist declarada: comportamento atual preservado.
             scope = params.scope || DEFAULT_SCOPE;
         }
-        const at = new provider.AccessToken({ accountId: target.id, client, scope });
-        const accessToken = await at.save();
         // Token exchange is not tied to a browser session, so there is no active org
         // context here — roles are resolved for the impersonated target with clientId only.
         const roles = deps.resolveTokenRoles
@@ -117,6 +144,17 @@ export function registerTokenExchange(provider, deps) {
                 activeOrg: null,
             })
             : (target.globalRoles ?? []);
+        if (deps.impersonateAdmins === false && roles.some((r) => adminRoles.includes(r))) {
+            throw new errors.InvalidGrant('requested_subject is not impersonable');
+        }
+        // O ACCESS token (não só o id_token) carrega o ator: é o que o resource server
+        // vê a cada request (`oidcBearerGuard` → `impersonationState`/`realAccountId`).
+        // Sem isso, o token trocado era indistinguível de um token do próprio alvo, e
+        // toda regra "negado durante impersonation" deixava passar o app nativo.
+        // `extra` sai no JWT (formato jwt) e na introspecção (RFC 7662).
+        const at = new provider.AccessToken({ accountId: target.id, client, scope });
+        at[IMPERSONATION_ACTOR_PROP] = actor.id;
+        const accessToken = await at.save();
         const idToken = new provider.IdToken({
             sub: target.id,
             email: target.email,
@@ -134,7 +172,7 @@ export function registerTokenExchange(provider, deps) {
             email: target.email ?? null,
             clientId: client?.clientId ?? null,
             ip: ctx.req?.socket?.remoteAddress ?? null,
-            metadata: { scope },
+            metadata: { scope, jti: at.jti ?? null },
         });
         ctx.body = {
             access_token: accessToken,
@@ -143,6 +181,9 @@ export function registerTokenExchange(provider, deps) {
             expires_in: at.expiration ?? 3600,
             id_token: idTokenJwt,
             scope,
+            // RFC 8693 §4.1: o ator também no corpo da resposta (o `actSub` que o
+            // `requestTokenExchange` do host lê — antes ficava sempre vazio).
+            act: { sub: actor.id },
         };
     };
     provider.registerGrantType(TOKEN_EXCHANGE, handler, [

package/package.json

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