@adonis-agora/authkit-client 0.15.0 → 0.16.0

package/build/providers/authkit_client_provider.d.ts

@@ -2,6 +2,7 @@ import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
 import { Authenticator } from '../src/authenticator.js';
 import type { ResolvedClientConfig } from '../src/define_config.js';
+import type { TokenSet } from '../src/types.js';
 /** Deps injetáveis (relógio/fetch) para testar `maybeRefresh` sem rede/tempo real. */
 export interface RefreshDeps {
     now?: () => number;
@@ -23,6 +24,9 @@ export declare class AuthkitClientManager {
      * renovado — incluindo o refresh_token ROTACIONADO — de volta na sessão. Preserva
      * o id_token / refresh_token anteriores quando o IdP não os reemite.
      *
+     * Preserva TAMBÉM o `impersonationBinding`: renovar o token do alvo não muda a
+     * sessão, então não pode invalidar o vínculo e trancar o ator na impersonação.
+     *
      * Best-effort: qualquer falha (token revogado, IdP fora) é silenciosa — o resolver
      * lida com a sessão expirada no fluxo normal. Chamado pelo middleware por request.
      */
@@ -43,10 +47,64 @@ export declare class AuthkitClientManager {
      * do chamador (ex.: Bouncer) ANTES de chamar este método.
      */
     impersonate(ctx: HttpContext, requestedSubject: string): Promise<void>;
-    /** Encerra a impersonação restaurando o token set original. Retorna false se não havia impersonação. */
+    /**
+     * Encerra a impersonação restaurando o token set do ator — SE a sessão que pede
+     * ainda for aquela para a qual a credencial foi guardada.
+     *
+     * A credencial parqueada é um refresh token vivo; sem essa conferência o restore
+     * a entrega a quem estiver de posse do cookie jar depois (logout do ator + login
+     * de outra identidade). A prova é o `impersonationBinding`: um nonce escrito ao
+     * mesmo tempo dentro do token set ATIVO e do registro parqueado. Só `impersonate()`
+     * o escreve e só o `maybeRefresh` o propaga — qualquer troca de identidade
+     * reescreve o slot da sessão e o vínculo some.
+     *
+     * As conferências ÓBVIAS não servem, e é por isso que o vínculo existe:
+     *  - `sub === sub do ator`: durante uma impersonação legítima a sessão é a do
+     *    ALVO, então isso nunca é verdade — trancaria o ator dentro da impersonação;
+     *  - "o token parqueado é de um admin?": sempre verdade; o atacante não alega
+     *    ser o ator, ele pede a credencial do ator;
+     *  - gate por papel: o ator impersonando carrega os papéis do ALVO nesse momento.
+     *
+     * Recusa é FAIL-CLOSED: a credencial órfã é DESCARTADA (nunca devolvida) e o
+     * token set da sessão também cai — uma recusa não é uma tentativa a repetir, e
+     * ninguém fica preso impersonando.
+     *
+     * LIMITE HONESTO: quem controla o cookie jar DURANTE uma impersonação ativa é
+     * indistinguível do ator — é literalmente a mesma sessão, e o vínculo viaja nela.
+     * Isso é o modelo de sessão, não esta conferência. O que fecha é a janela em que
+     * a credencial sobrevive à sessão que a guardou.
+     *
+     * @returns `true` só quando o ator foi restaurado.
+     */
     stopImpersonating(ctx: HttpContext): Promise<boolean>;
-    /** Indica se a request corrente está impersonando (p/ exibir banner na UI). */
+    /**
+     * Indica se a request corrente está impersonando (p/ exibir banner na UI). Exige o
+     * mesmo vínculo do `stopImpersonating` — uma credencial órfã de outra sessão não
+     * faz o banner aparecer para quem não está impersonando ninguém.
+     */
     isImpersonating(ctx: HttpContext): boolean;
+    /**
+     * Encerra a sessão do AuthKit: remove o token set E qualquer credencial de
+     * impersonação parqueada. Todo caminho da lib que derruba a sessão passa por aqui
+     * — logout RP-initiated (`registerOidcClient`) e revogação back-channel.
+     *
+     * Existe porque um `session.forget(sessionKey)` solto deixava o refresh token do
+     * ATOR parqueado no browser depois de uma revogação central — o mecanismo que o
+     * operador usa justamente para matar a sessão.
+     */
+    endSession(ctx: HttpContext): void;
+    /**
+     * Instala o token set de um login recém-concluído, descartando o que sobrou da
+     * sessão anterior no mesmo cookie jar.
+     *
+     * O `stopImpersonating` já recusa uma credencial órfã — o token set novo nasce sem
+     * `impersonationBinding`, então o vínculo não fecha. Mas recusar é só não DEVOLVER:
+     * sem esta limpeza o refresh token do ator continua serializado no cookie de sessão
+     * de outra identidade até a sessão expirar. Não devolver e não guardar são coisas
+     * diferentes, e a segunda é a que mantém a invariante — a credencial parqueada nunca
+     * sobrevive à sessão que a parqueou.
+     */
+    startSession(ctx: HttpContext, tokenSet: TokenSet): void;
     createAuthenticator(ctx: HttpContext): Promise<Authenticator>;
 }
 declare module '@adonisjs/core/types' {

package/build/providers/authkit_client_provider.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { Authenticator } from '../src/authenticator.js';
@@ -5,6 +6,17 @@ import { validateLogoutToken } from '../src/backchannel_logout.js';
 import { exchangeToken, refreshTokens } from '../src/oidc_login.js';
 /** Margem (ms) antes do `expiresAt` em que o access token é renovado proativamente. */
 const REFRESH_SKEW_MS = 60_000;
+/** Aceita só o formato COM vínculo; o formato legado (TokenSet cru) vira `null`. */
+function readParked(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const candidate = value;
+    if (typeof candidate.binding !== 'string' || !candidate.binding)
+        return null;
+    if (!candidate.tokenSet || typeof candidate.tokenSet !== 'object')
+        return null;
+    return candidate;
+}
 export class AuthkitClientManager {
     config;
     #resolverCache;
@@ -40,6 +52,9 @@ export class AuthkitClientManager {
      * renovado — incluindo o refresh_token ROTACIONADO — de volta na sessão. Preserva
      * o id_token / refresh_token anteriores quando o IdP não os reemite.
      *
+     * Preserva TAMBÉM o `impersonationBinding`: renovar o token do alvo não muda a
+     * sessão, então não pode invalidar o vínculo e trancar o ator na impersonação.
+     *
      * Best-effort: qualquer falha (token revogado, IdP fora) é silenciosa — o resolver
      * lida com a sessão expirada no fluxo normal. Chamado pelo middleware por request.
      */
@@ -68,6 +83,7 @@ export class AuthkitClientManager {
                 accessToken: next.accessToken,
                 refreshToken: next.refreshToken ?? tokenSet.refreshToken,
                 expiresAt: next.expiresAt,
+                impersonationBinding: tokenSet.impersonationBinding,
             });
         }
         catch {
@@ -140,24 +156,113 @@ export class AuthkitClientManager {
             requestedSubject,
             resilience: this.config.resilience,
         });
-        session.put(this.#impersonatorKey, current);
-        session.put(this.config.sessionKey, impersonated);
+        // Vínculo: o mesmo nonce nos dois lados. O lado ATIVO mora dentro do token set
+        // da sessão, o único slot que todo caminho de fim-de-sessão já limpa.
+        const binding = randomUUID();
+        session.put(this.#impersonatorKey, {
+            tokenSet: current,
+            binding,
+        });
+        session.put(this.config.sessionKey, { ...impersonated, impersonationBinding: binding });
     }
-    /** Encerra a impersonação restaurando o token set original. Retorna false se não havia impersonação. */
+    /**
+     * Encerra a impersonação restaurando o token set do ator — SE a sessão que pede
+     * ainda for aquela para a qual a credencial foi guardada.
+     *
+     * A credencial parqueada é um refresh token vivo; sem essa conferência o restore
+     * a entrega a quem estiver de posse do cookie jar depois (logout do ator + login
+     * de outra identidade). A prova é o `impersonationBinding`: um nonce escrito ao
+     * mesmo tempo dentro do token set ATIVO e do registro parqueado. Só `impersonate()`
+     * o escreve e só o `maybeRefresh` o propaga — qualquer troca de identidade
+     * reescreve o slot da sessão e o vínculo some.
+     *
+     * As conferências ÓBVIAS não servem, e é por isso que o vínculo existe:
+     *  - `sub === sub do ator`: durante uma impersonação legítima a sessão é a do
+     *    ALVO, então isso nunca é verdade — trancaria o ator dentro da impersonação;
+     *  - "o token parqueado é de um admin?": sempre verdade; o atacante não alega
+     *    ser o ator, ele pede a credencial do ator;
+     *  - gate por papel: o ator impersonando carrega os papéis do ALVO nesse momento.
+     *
+     * Recusa é FAIL-CLOSED: a credencial órfã é DESCARTADA (nunca devolvida) e o
+     * token set da sessão também cai — uma recusa não é uma tentativa a repetir, e
+     * ninguém fica preso impersonando.
+     *
+     * LIMITE HONESTO: quem controla o cookie jar DURANTE uma impersonação ativa é
+     * indistinguível do ator — é literalmente a mesma sessão, e o vínculo viaja nela.
+     * Isso é o modelo de sessão, não esta conferência. O que fecha é a janela em que
+     * a credencial sobrevive à sessão que a guardou.
+     *
+     * @returns `true` só quando o ator foi restaurado.
+     */
     async stopImpersonating(ctx) {
         const session = ctx.session;
         if (!session)
             return false;
-        const original = session.get(this.#impersonatorKey);
-        if (!original)
+        const raw = session.get(this.#impersonatorKey);
+        if (raw === undefined || raw === null)
+            return false;
+        const parked = readParked(raw);
+        const live = session.get(this.config.sessionKey);
+        // `parked === null` cobre o formato pré-0.15 (TokenSet cru, sem vínculo nenhum):
+        // é justamente a credencial que não dá pra atribuir. Recusada como qualquer outra.
+        if (!parked || !live?.impersonationBinding || live.impersonationBinding !== parked.binding) {
+            session.forget(this.#impersonatorKey);
+            session.forget(this.config.sessionKey);
             return false;
+        }
+        const { impersonationBinding: _binding, ...original } = parked.tokenSet;
         session.put(this.config.sessionKey, original);
         session.forget(this.#impersonatorKey);
         return true;
     }
-    /** Indica se a request corrente está impersonando (p/ exibir banner na UI). */
+    /**
+     * Indica se a request corrente está impersonando (p/ exibir banner na UI). Exige o
+     * mesmo vínculo do `stopImpersonating` — uma credencial órfã de outra sessão não
+     * faz o banner aparecer para quem não está impersonando ninguém.
+     */
     isImpersonating(ctx) {
-        return Boolean(ctx.session?.get(this.#impersonatorKey));
+        const session = ctx.session;
+        if (!session)
+            return false;
+        const parked = readParked(session.get(this.#impersonatorKey));
+        if (!parked)
+            return false;
+        const live = session.get(this.config.sessionKey);
+        return live?.impersonationBinding === parked.binding;
+    }
+    /**
+     * Encerra a sessão do AuthKit: remove o token set E qualquer credencial de
+     * impersonação parqueada. Todo caminho da lib que derruba a sessão passa por aqui
+     * — logout RP-initiated (`registerOidcClient`) e revogação back-channel.
+     *
+     * Existe porque um `session.forget(sessionKey)` solto deixava o refresh token do
+     * ATOR parqueado no browser depois de uma revogação central — o mecanismo que o
+     * operador usa justamente para matar a sessão.
+     */
+    endSession(ctx) {
+        const session = ctx.session;
+        if (!session)
+            return;
+        session.forget(this.config.sessionKey);
+        session.forget(this.#impersonatorKey);
+    }
+    /**
+     * Instala o token set de um login recém-concluído, descartando o que sobrou da
+     * sessão anterior no mesmo cookie jar.
+     *
+     * O `stopImpersonating` já recusa uma credencial órfã — o token set novo nasce sem
+     * `impersonationBinding`, então o vínculo não fecha. Mas recusar é só não DEVOLVER:
+     * sem esta limpeza o refresh token do ator continua serializado no cookie de sessão
+     * de outra identidade até a sessão expirar. Não devolver e não guardar são coisas
+     * diferentes, e a segunda é a que mantém a invariante — a credencial parqueada nunca
+     * sobrevive à sessão que a parqueou.
+     */
+    startSession(ctx, tokenSet) {
+        const session = ctx.session;
+        if (!session)
+            return;
+        session.forget(this.#impersonatorKey);
+        session.put(this.config.sessionKey, tokenSet);
     }
     async createAuthenticator(ctx) {
         const resolver = await this.#getResolver();

package/build/src/middleware/backchannel_revocation_middleware.js

@@ -17,7 +17,6 @@ export default class BackchannelRevocationMiddleware {
         const store = manager.clientConfig.backchannelStore;
         if (!store)
             return next();
-        const sessionKey = manager.clientConfig.sessionKey;
         const idToken = manager.getIdToken(ctx);
         if (idToken) {
             const claims = decodeJwtPayload(idToken);
@@ -25,8 +24,9 @@ export default class BackchannelRevocationMiddleware {
             const sub = typeof claims?.sub === 'string' ? claims.sub : undefined;
             const authTime = typeof claims?.iat === 'number' ? claims.iat : undefined;
             if ((sid || sub) && (await store.isRevoked({ sid, sub, authTime }))) {
-                // session é augmentado por @adonisjs/session no app host; na lib usamos cast.
-                ctx.session?.forget(sessionKey);
+                // endSession, não `forget(sessionKey)`: uma revogação central não pode deixar
+                // a credencial de impersonação (refresh token do ATOR) parqueada no browser.
+                manager.endSession(ctx);
             }
         }
         return next();

package/build/src/register_oidc_client.js

@@ -63,7 +63,9 @@ export function registerOidcClient(router, options = {}) {
             code,
             codeVerifier: pkce.verifier,
         });
-        ctx.session?.put(cfg.sessionKey, tokenSet);
+        // startSession, não `put(sessionKey)`: um login novo no mesmo cookie jar não pode
+        // herdar a credencial de impersonação parqueada pela sessão anterior.
+        manager.startSession(ctx, tokenSet);
         ctx.session?.forget(pkceKey);
         const authenticator = await manager.createAuthenticator(ctx);
         const identity = await authenticator.getIdentity();
@@ -81,7 +83,9 @@ export function registerOidcClient(router, options = {}) {
         const manager = await ctx.containerResolver.make('authkit.client');
         const cfg = manager.clientConfig;
         const idToken = manager.getIdToken(ctx);
-        ctx.session?.forget(cfg.sessionKey);
+        // Leva junto a credencial de impersonação parqueada — era este logout que a
+        // deixava para trás, viva, para a próxima identidade do mesmo cookie jar.
+        manager.endSession(ctx);
         const postLogoutRedirectUri = typeof options.postLogoutRedirect === 'function'
             ? options.postLogoutRedirect(ctx)
             : (options.postLogoutRedirect ?? `${new URL(cfg.redirectUri).origin}/`);

package/build/src/types.d.ts

@@ -3,4 +3,13 @@ export interface TokenSet {
     accessToken: string;
     refreshToken?: string;
     expiresAt?: number;
+    /**
+     * Nonce opaco que amarra ESTE token set à credencial de impersonação parqueada
+     * em `${sessionKey}_impersonator`. Escrito só por `impersonate()`; preservado
+     * pelo `maybeRefresh`; conferido pelo `stopImpersonating()`. Qualquer outra
+     * escrita no slot da sessão (login novo, logout+login) nasce sem ele — que é
+     * exatamente o sinal de que a sessão deixou de ser aquela p/ a qual a
+     * credencial foi guardada. Não é segredo de autenticação: é um vínculo.
+     */
+    impersonationBinding?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "AdonisJS OIDC/OAuth2 relying-party (client) toolkit: session-based authentication against an OpenID Connect identity provider, with JWT/PAT user resolvers and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",