@adonis-agora/authkit-client 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davi de Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @adonis-agora/authkit-client
+
+Adapter consumidor OpenID Connect para AdonisJS — integra um app como client do
+Authorization Server (`@adonis-agora/authkit-server`), validando o ID token localmente por JWKS.
+
+## Instalação
+```bash
+node ace add @adonis-agora/authkit-client
+# ou: pnpm add @adonis-agora/authkit-client && node ace configure @adonis-agora/authkit-client
+```
+O `configure` publica `config/authkit_client.ts`, o controller `app/controllers/oidc_session_controller.ts`
+(login/callback/logout) e registra o provider + o middleware `authkit_middleware`.
+
+## Rotas de sessão
+```ts
+// start/routes.ts
+import OidcSessionController from '#controllers/oidc_session_controller'
+router.get('/auth/login', [OidcSessionController, 'login'])
+router.get('/auth/callback', [OidcSessionController, 'callback'])
+router.post('/auth/logout', [OidcSessionController, 'logout'])
+```
+`AUTHKIT_REDIRECT_URI` deve apontar para a rota de callback.
+
+## Uso por request
+`ctx.auth` é populado pelo `authkit_middleware`:
+```ts
+const identity = await ctx.auth.getIdentity()   // claims OIDC validadas (ou null)
+const user = await ctx.auth.getUser()            // model do app (via resolveUser)
+ctx.auth.hasGlobalRole('ADMIN')                  // síncrono, das claims
+await ctx.auth.hasAppRole('COORDINATOR')         // via resolveAppRoles
+```
+
+## Resolução de sessão
+`resolvers.jwt({ tokenSource })` valida o **ID token** (JWT) por JWKS:
+- `tokenSource: 'session'` (default) — lê o token set do `@adonisjs/session`.
+- `tokenSource: 'bearer'` — lê do header `Authorization` (SPA/API).
+
+## Topologias de banco
+A identidade (`ctx.auth.identity`) sempre vem do **token validado** e independe da
+topologia de banco. O que muda é como `resolveUser` obtém o model do app.
+
+### Mesmo banco + schemas
+O app lê um model Lucid local mapeado pra `auth.users` (FK cross-schema):
+```ts
+// config/authkit_client.ts
+resolveUser: async (identity) => {
+  // FK cross-schema: app.users.auth_user_id -> auth.users.id
+  return AppUser.query().where('authUserId', identity.userId).firstOrFail()
+},
+resolveAppRoles: async (identity) => {
+  const u = await AppUser.findByOrFail('authUserId', identity.userId)
+  return u.related('roles').query().then((rs) => rs.map((r) => r.name))
+},
+```
+
+### Bancos separados
+Sem FK cross-schema possível. Como o IdP emite um **ID token "gordo"**
+(email/name/roles nas claims), o caminho recomendado é claims-only:
+```ts
+import { identityToUser } from '@adonis-agora/authkit-client'
+
+resolveUser: identityToUser, // { id, email, name?, avatarUrl?, globalRoles }
+```
+Pra dados além do que o token carrega, use o resolver de userinfo (busca no
+endpoint `${issuer}/me` com o access token; faz fallback pra claims sem token):
+```ts
+import { createUserinfoResolver } from '@adonis-agora/authkit-client'
+
+resolveUser: createUserinfoResolver({ issuer: env.get('AUTHKIT_ISSUER') }),
+// ou: createUserinfoResolver({ userinfoEndpoint: 'https://idp/me' })
+```
+Em ambos os casos, `resolveAppRoles` **sempre consulta o banco do próprio app**:
+```ts
+resolveAppRoles: async (identity) => {
+  const roles = await AppRole.query().where('authUserId', identity.userId)
+  return roles.map((r) => r.name)
+},
+```
+
+## Ordem de middleware (importante)
+O middleware do `@adonisjs/session` DEVE rodar ANTES do `authkit_middleware` no stack `router`
+(o resolver lê o token da session). Garanta essa ordem em `start/kernel.ts`.
+
+## Observabilidade (opcional)
+O `Authenticator` registra métricas de resolução (`authkit.resolve.duration` e
+`authkit.resolve.errors`) quando um `MetricsRecorder` é injetado. As métricas são emitidas via
+OpenTelemetry **quando** `@opentelemetry/api` está instalado; sem ele a agregação é no-op.
+O comportamento por request não muda — observabilidade é puramente aditiva.

package/build/commands/configure.d.ts

@@ -0,0 +1,2 @@
+import type Configure from '@adonisjs/core/commands/configure';
+export declare function configure(command: Configure): Promise<void>;

package/build/commands/configure.js

@@ -0,0 +1,17 @@
+import { stubsRoot } from '../stubs/main.js';
+export async function configure(command) {
+    const codemods = await command.createCodemods();
+    await codemods.makeUsingStub(stubsRoot, 'config/authkit_client.stub', {});
+    await codemods.makeUsingStub(stubsRoot, 'controllers/oidc_session_controller.stub', {});
+    await codemods.updateRcFile((rc) => rc.addProvider('@adonis-agora/authkit-client/authkit_client_provider'));
+    await codemods.registerMiddleware('router', [{ path: '@adonis-agora/authkit-client/authkit_middleware' }]);
+    await codemods.defineEnvValidations({
+        leadingComment: 'Variáveis do @adonis-agora/authkit-client (OIDC client)',
+        variables: {
+            AUTHKIT_ISSUER: `Env.schema.string({ format: 'url', tld: false })`,
+            AUTHKIT_CLIENT_ID: `Env.schema.string()`,
+            AUTHKIT_CLIENT_SECRET: `Env.schema.string.optional()`,
+            AUTHKIT_REDIRECT_URI: `Env.schema.string({ format: 'url', tld: false })`,
+        },
+    });
+}

package/build/index.d.ts

@@ -0,0 +1,28 @@
+export { defineConfig, resolvers } from "./src/define_config.js";
+export { Authenticator } from "./src/authenticator.js";
+export { identityToUser, createUserinfoResolver, } from "./src/user_resolvers.js";
+export type { ClaimsUser, ResolveUserContext, UserinfoResolverOptions, } from "./src/user_resolvers.js";
+export { buildAuthorizeUrl, buildEndSessionUrl, exchangeCode, exchangeToken, refreshTokens, generatePkce, } from "./src/oidc_login.js";
+export type { EndSessionParams, RefreshParams } from "./src/oidc_login.js";
+export { discoverEndpoints, conventionEndpoints } from "./src/discovery.js";
+export type { OidcEndpoints, DiscoverOptions } from "./src/discovery.js";
+export { resilientFetch } from "./src/http/resilient_fetch.js";
+export type { ResiliencePolicy } from "./src/http/resilient_fetch.js";
+export { AuthkitClientManager } from "./providers/authkit_client_provider.js";
+export type { ResolvedClientConfig, ClientConfigInput, BackchannelLogoutCallback, BackchannelLogoutInput, } from "./src/define_config.js";
+export { lucidRevocationStore, DEFAULT_REVOCATION_TABLE, } from "./src/revocation/revocation_store.js";
+export type { RevocationStore, LucidRevocationStoreOptions, } from "./src/revocation/revocation_store.js";
+export { default as BackchannelRevocationMiddleware } from "./src/middleware/backchannel_revocation_middleware.js";
+export { lucidMirror } from "./src/lucid_mirror.js";
+export type { LucidMirrorOptions } from "./src/lucid_mirror.js";
+export { registerOidcClient } from "./src/register_oidc_client.js";
+export type { RegisterOidcClientOptions, PostLoginRedirects, } from "./src/register_oidc_client.js";
+export { validateLogoutToken, InvalidLogoutTokenError, InMemorySessionIndex, BACKCHANNEL_LOGOUT_EVENT, } from "./src/backchannel_logout.js";
+export type { ValidateLogoutTokenOptions, ValidatedLogoutToken, SessionIndex, SessionIndexEntry, } from "./src/backchannel_logout.js";
+export { generateDpopKeyPair, createDpopProof, dpopJwkThumbprint, } from "./src/dpop.js";
+export type { DpopKeyPair, CreateDpopProofInput } from "./src/dpop.js";
+export { verifyJwtAccessToken, clearJwksCache, } from "./src/verify_access_token.js";
+export type { VerifyJwtAccessTokenOptions, JwtAccessTokenClaims, } from "./src/verify_access_token.js";
+export type { TokenSet } from "./src/types.js";
+export type { Identity } from "@adonis-agora/authkit-core";
+export { configure } from "./commands/configure.js";

package/build/index.js

@@ -0,0 +1,15 @@
+export { defineConfig, resolvers } from "./src/define_config.js";
+export { Authenticator } from "./src/authenticator.js";
+export { identityToUser, createUserinfoResolver, } from "./src/user_resolvers.js";
+export { buildAuthorizeUrl, buildEndSessionUrl, exchangeCode, exchangeToken, refreshTokens, generatePkce, } from "./src/oidc_login.js";
+export { discoverEndpoints, conventionEndpoints } from "./src/discovery.js";
+export { resilientFetch } from "./src/http/resilient_fetch.js";
+export { AuthkitClientManager } from "./providers/authkit_client_provider.js";
+export { lucidRevocationStore, DEFAULT_REVOCATION_TABLE, } from "./src/revocation/revocation_store.js";
+export { default as BackchannelRevocationMiddleware } from "./src/middleware/backchannel_revocation_middleware.js";
+export { lucidMirror } from "./src/lucid_mirror.js";
+export { registerOidcClient } from "./src/register_oidc_client.js";
+export { validateLogoutToken, InvalidLogoutTokenError, InMemorySessionIndex, BACKCHANNEL_LOGOUT_EVENT, } from "./src/backchannel_logout.js";
+export { generateDpopKeyPair, createDpopProof, dpopJwkThumbprint, } from "./src/dpop.js";
+export { verifyJwtAccessToken, clearJwksCache, } from "./src/verify_access_token.js";
+export { configure } from "./commands/configure.js";

package/build/providers/authkit_client_provider.d.ts

@@ -0,0 +1,61 @@
+import type { ApplicationService } from "@adonisjs/core/types";
+import type { HttpContext } from "@adonisjs/core/http";
+import { Authenticator } from "../src/authenticator.js";
+import type { ResolvedClientConfig } from "../src/define_config.js";
+/** Deps injetáveis (relógio/fetch) para testar `maybeRefresh` sem rede/tempo real. */
+export interface RefreshDeps {
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+}
+export declare class AuthkitClientManager {
+    #private;
+    private config;
+    constructor(config: ResolvedClientConfig);
+    get clientConfig(): ResolvedClientConfig;
+    /**
+     * Lê o id_token armazenado no token set da sessão. Usado pelo logout federado
+     * (RP-initiated) como `id_token_hint` ao redirecionar para `end_session_endpoint`.
+     */
+    getIdToken(ctx: HttpContext): string | undefined;
+    /**
+     * Renova o TokenSet da sessão proativamente se o access token estiver perto de
+     * expirar (dentro de REFRESH_SKEW_MS) e houver refresh_token. Persiste o TokenSet
+     * 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.
+     *
+     * 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.
+     */
+    maybeRefresh(ctx: HttpContext, deps?: RefreshDeps): Promise<void>;
+    /**
+     * Recebe o POST `application/x-www-form-urlencoded` de OIDC Back-Channel Logout. Lê o
+     * `logout_token` do body, valida (assinatura + regras do spec), consulta o SessionIndex
+     * (se houver) e invoca `onBackchannelLogout` p/ o host destruir as sessões locais.
+     *
+     * Retorna 200 em sucesso e 400 `{ error: 'invalid_request' }` em validação inválida.
+     * Sempre seta `Cache-Control: no-store` (exigência do spec).
+     */
+    handleBackchannelLogout(ctx: HttpContext): Promise<unknown>;
+    /**
+     * Impersona `requestedSubject` via token-exchange (RFC 8693): guarda o token set
+     * atual e o substitui pelo do alvo. Encapsula o malabarismo de session keys que o
+     * consumidor fazia à mão. A AUTORIZAÇÃO (quem pode impersonar quem) é responsabilidade
+     * 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. */
+    stopImpersonating(ctx: HttpContext): Promise<boolean>;
+    /** Indica se a request corrente está impersonando (p/ exibir banner na UI). */
+    isImpersonating(ctx: HttpContext): boolean;
+    createAuthenticator(ctx: HttpContext): Promise<Authenticator>;
+}
+declare module "@adonisjs/core/types" {
+    interface ContainerBindings {
+        "authkit.client": AuthkitClientManager;
+    }
+}
+export default class AuthkitClientProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    register(): void;
+}

package/build/providers/authkit_client_provider.js

@@ -0,0 +1,187 @@
+import { configProvider } from "@adonisjs/core";
+import { RuntimeException } from "@adonisjs/core/exceptions";
+import { Authenticator } from "../src/authenticator.js";
+import { refreshTokens, exchangeToken } from "../src/oidc_login.js";
+import { validateLogoutToken } from "../src/backchannel_logout.js";
+/** Margem (ms) antes do `expiresAt` em que o access token é renovado proativamente. */
+const REFRESH_SKEW_MS = 60_000;
+export class AuthkitClientManager {
+    config;
+    #resolverCache;
+    constructor(config) {
+        this.config = config;
+    }
+    async #getResolver() {
+        if (!this.#resolverCache) {
+            this.#resolverCache = await this.config.resolverFactory.resolver({
+                issuer: this.config.issuer,
+                clientId: this.config.clientId,
+                clientSecret: this.config.clientSecret,
+                sessionKey: this.config.sessionKey,
+                globalRolesClaim: this.config.globalRolesClaim,
+            });
+        }
+        return this.#resolverCache;
+    }
+    get clientConfig() {
+        return this.config;
+    }
+    /**
+     * Lê o id_token armazenado no token set da sessão. Usado pelo logout federado
+     * (RP-initiated) como `id_token_hint` ao redirecionar para `end_session_endpoint`.
+     */
+    getIdToken(ctx) {
+        const tokenSet = ctx.session?.get(this.config.sessionKey);
+        return tokenSet?.idToken || undefined;
+    }
+    /**
+     * Renova o TokenSet da sessão proativamente se o access token estiver perto de
+     * expirar (dentro de REFRESH_SKEW_MS) e houver refresh_token. Persiste o TokenSet
+     * 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.
+     *
+     * 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.
+     */
+    async maybeRefresh(ctx, deps = {}) {
+        const session = ctx.session;
+        if (!session)
+            return;
+        const tokenSet = session.get(this.config.sessionKey);
+        if (!tokenSet?.refreshToken)
+            return;
+        const now = deps.now ?? Date.now;
+        // Sem expiresAt conhecido, não renova proativamente (evita refresh a cada request).
+        if (!tokenSet.expiresAt || tokenSet.expiresAt - now() > REFRESH_SKEW_MS)
+            return;
+        try {
+            const next = await refreshTokens({
+                issuer: this.config.issuer,
+                clientId: this.config.clientId,
+                clientSecret: this.config.clientSecret,
+                refreshToken: tokenSet.refreshToken,
+                fetchImpl: deps.fetchImpl,
+                resilience: this.config.resilience,
+            });
+            session.put(this.config.sessionKey, {
+                idToken: next.idToken || tokenSet.idToken,
+                accessToken: next.accessToken,
+                refreshToken: next.refreshToken ?? tokenSet.refreshToken,
+                expiresAt: next.expiresAt,
+            });
+        }
+        catch {
+            // Renovação falhou — deixa o TokenSet como está; o resolver decide a sessão.
+        }
+    }
+    /**
+     * Recebe o POST `application/x-www-form-urlencoded` de OIDC Back-Channel Logout. Lê o
+     * `logout_token` do body, valida (assinatura + regras do spec), consulta o SessionIndex
+     * (se houver) e invoca `onBackchannelLogout` p/ o host destruir as sessões locais.
+     *
+     * Retorna 200 em sucesso e 400 `{ error: 'invalid_request' }` em validação inválida.
+     * Sempre seta `Cache-Control: no-store` (exigência do spec).
+     */
+    async handleBackchannelLogout(ctx) {
+        const { request, response } = ctx;
+        response.header("Cache-Control", "no-store");
+        const token = request.input("logout_token");
+        if (!token || typeof token !== "string") {
+            return response.badRequest({ error: "invalid_request" });
+        }
+        let validated;
+        try {
+            validated = await validateLogoutToken(token, {
+                issuer: this.config.issuer,
+                clientId: this.config.clientId,
+            });
+        }
+        catch {
+            return response.badRequest({ error: "invalid_request" });
+        }
+        // Atualiza o índice local (se configurado) — revoga as sessões mapeadas.
+        const index = this.config.sessionIndex;
+        if (index) {
+            if (validated.sid)
+                await index.revokeBySid(validated.sid);
+            else if (validated.sub)
+                await index.revokeBySub(validated.sub);
+        }
+        // Delega ao host a destruição efetiva das sessões locais.
+        await this.config.onBackchannelLogout?.({
+            sid: validated.sid,
+            sub: validated.sub,
+        });
+        return {};
+    }
+    /** Chave de sessão onde o token set ORIGINAL fica guardado durante a impersonação. */
+    get #impersonatorKey() {
+        return `${this.config.sessionKey}_impersonator`;
+    }
+    /**
+     * Impersona `requestedSubject` via token-exchange (RFC 8693): guarda o token set
+     * atual e o substitui pelo do alvo. Encapsula o malabarismo de session keys que o
+     * consumidor fazia à mão. A AUTORIZAÇÃO (quem pode impersonar quem) é responsabilidade
+     * do chamador (ex.: Bouncer) ANTES de chamar este método.
+     */
+    async impersonate(ctx, requestedSubject) {
+        const session = ctx.session;
+        const current = session?.get(this.config.sessionKey);
+        if (!current?.accessToken) {
+            throw new Error("Sem sessão ativa para impersonar a partir dela");
+        }
+        const impersonated = await exchangeToken({
+            issuer: this.config.issuer,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            subjectToken: current.accessToken,
+            requestedSubject,
+            resilience: this.config.resilience,
+        });
+        session.put(this.#impersonatorKey, current);
+        session.put(this.config.sessionKey, impersonated);
+    }
+    /** Encerra a impersonação restaurando o token set original. Retorna false se não havia impersonação. */
+    async stopImpersonating(ctx) {
+        const session = ctx.session;
+        const original = session?.get(this.#impersonatorKey);
+        if (!original)
+            return false;
+        session.put(this.config.sessionKey, original);
+        session.forget(this.#impersonatorKey);
+        return true;
+    }
+    /** Indica se a request corrente está impersonando (p/ exibir banner na UI). */
+    isImpersonating(ctx) {
+        return Boolean(ctx.session?.get(this.#impersonatorKey));
+    }
+    async createAuthenticator(ctx) {
+        const resolver = await this.#getResolver();
+        const sessionKey = this.config.sessionKey;
+        return new Authenticator(ctx, {
+            resolver,
+            resolveUser: this.config.resolveUser,
+            resolveAppRoles: this.config.resolveAppRoles,
+            getAccessToken: () => {
+                const tokenSet = ctx.session?.get(sessionKey);
+                return tokenSet?.accessToken;
+            },
+        });
+    }
+}
+export default class AuthkitClientProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    register() {
+        this.app.container.singleton("authkit.client", async () => {
+            const value = this.app.config.get("authkit_client");
+            const config = (await configProvider.resolve(this.app, value));
+            if (!config) {
+                throw new RuntimeException('Config inválido em "config/authkit_client.ts". Use defineConfig de @adonis-agora/authkit-client.');
+            }
+            return new AuthkitClientManager(config);
+        });
+    }
+}

package/build/src/authenticator.d.ts

@@ -0,0 +1,41 @@
+import type { HttpContext } from "@adonisjs/core/http";
+import type { Identity, SessionResolver } from "@adonis-agora/authkit-core";
+import { type MetricsRecorder } from "@adonis-agora/authkit-core";
+/** Contexto opcional repassado a `resolveUser` (extensão backward-compatible). */
+export interface ResolveUserContext {
+    accessToken?: string;
+}
+export interface AuthenticatorDeps {
+    resolver: SessionResolver;
+    resolveUser?: (identity: Identity, context: ResolveUserContext) => Promise<unknown>;
+    resolveAppRoles?: (identity: Identity) => Promise<string[]>;
+    /** lê o access token do token set da sessão (opcional; usado por resolvers userinfo) */
+    getAccessToken?: () => string | null | undefined;
+}
+export declare class Authenticator {
+    #private;
+    private ctx;
+    private deps;
+    constructor(ctx: HttpContext, deps: AuthenticatorDeps, recorder?: MetricsRecorder);
+    getIdentity(): Promise<Identity | null>;
+    get identity(): Identity | null;
+    authenticate(): Promise<Identity>;
+    check(): Promise<boolean>;
+    hasGlobalRole(role: string): boolean;
+    hasAppRole(role: string): Promise<boolean>;
+    getUser(): Promise<unknown>;
+    /** Resolve (e cacheia) os app roles da identidade corrente. [] sem identidade/resolver. */
+    getAppRoles(): Promise<string[]>;
+    /**
+     * Monta o objeto pronto para compartilhar com o frontend (ex.: Inertia share),
+     * casando com o `AuthSharedProps` que o `@adonis-agora/authkit-react` consome.
+     * `abilities` é a união de app roles + global roles (conveniente p/ policies/CASL).
+     * Retorna `null` quando não há sessão.
+     */
+    toSharedProps(): Promise<{
+        user: unknown;
+        globalRoles: string[];
+        appRoles: string[];
+        abilities: string[];
+    } | null>;
+}

package/build/src/authenticator.js

@@ -0,0 +1,105 @@
+import { AUTHKIT_METRICS, NoopRecorder, } from "@adonis-agora/authkit-core";
+import { populateContext } from "./observability/context_bridge.js";
+export class Authenticator {
+    ctx;
+    deps;
+    #identity = null;
+    #resolved = false;
+    #user;
+    #userResolved = false;
+    #appRoles = null;
+    #recorder;
+    constructor(ctx, deps, recorder = new NoopRecorder()) {
+        this.ctx = ctx;
+        this.deps = deps;
+        this.#recorder = recorder;
+    }
+    async getIdentity() {
+        if (!this.#resolved) {
+            const start = Date.now();
+            try {
+                this.#identity = await this.deps.resolver.resolve(this.ctx);
+            }
+            catch (error) {
+                this.#recorder.increment(AUTHKIT_METRICS.resolveErrors);
+                throw error;
+            }
+            finally {
+                this.#recorder.record(AUTHKIT_METRICS.resolveDuration, Date.now() - start);
+            }
+            this.#resolved = true;
+            // Ponte estrutural: popula o contexto do Agora quando há sessão de fato
+            // (best-effort, no-op sem o slot `@agora/context:set`). Apenas no caminho
+            // de sucesso — não força resolução para requests anônimas.
+            if (this.#identity)
+                populateContext(this.#identity);
+        }
+        return this.#identity;
+    }
+    get identity() {
+        return this.#identity;
+    }
+    async authenticate() {
+        const identity = await this.getIdentity();
+        if (!identity)
+            throw new Error("Not authenticated");
+        return identity;
+    }
+    async check() {
+        return (await this.getIdentity()) !== null;
+    }
+    hasGlobalRole(role) {
+        return this.#identity?.globalRoles.includes(role) ?? false;
+    }
+    async hasAppRole(role) {
+        const identity = await this.getIdentity();
+        if (!identity || !this.deps.resolveAppRoles)
+            return false;
+        if (this.#appRoles === null)
+            this.#appRoles = await this.deps.resolveAppRoles(identity);
+        return this.#appRoles.includes(role);
+    }
+    async getUser() {
+        if (this.#userResolved)
+            return this.#user;
+        const identity = await this.getIdentity();
+        if (identity && this.deps.resolveUser) {
+            const accessToken = this.deps.getAccessToken?.() ?? undefined;
+            this.#user = await this.deps.resolveUser(identity, { accessToken });
+        }
+        else {
+            this.#user = null;
+        }
+        this.#userResolved = true;
+        return this.#user;
+    }
+    /** Resolve (e cacheia) os app roles da identidade corrente. [] sem identidade/resolver. */
+    async getAppRoles() {
+        const identity = await this.getIdentity();
+        if (!identity || !this.deps.resolveAppRoles)
+            return [];
+        if (this.#appRoles === null)
+            this.#appRoles = await this.deps.resolveAppRoles(identity);
+        return this.#appRoles;
+    }
+    /**
+     * Monta o objeto pronto para compartilhar com o frontend (ex.: Inertia share),
+     * casando com o `AuthSharedProps` que o `@adonis-agora/authkit-react` consome.
+     * `abilities` é a união de app roles + global roles (conveniente p/ policies/CASL).
+     * Retorna `null` quando não há sessão.
+     */
+    async toSharedProps() {
+        const identity = await this.getIdentity();
+        if (!identity)
+            return null;
+        const user = await this.getUser();
+        const globalRoles = identity.globalRoles ?? [];
+        const appRoles = await this.getAppRoles();
+        return {
+            user,
+            globalRoles,
+            appRoles,
+            abilities: [...appRoles, ...globalRoles],
+        };
+    }
+}

package/build/src/backchannel_logout.d.ts

@@ -0,0 +1,77 @@
+import { type JWTVerifyGetKey } from 'jose';
+/** Event type da claim `events` exigido pelo OIDC Back-Channel Logout. */
+export declare const BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+/** Erro tipado lançado quando o logout_token não satisfaz as regras do spec. */
+export declare class InvalidLogoutTokenError extends Error {
+    constructor(message: string);
+}
+export interface ValidateLogoutTokenOptions {
+    /** Issuer esperado (deve bater com a claim `iss`). */
+    issuer: string;
+    /** clientId do RP; deve estar contido na claim `aud`. */
+    clientId: string;
+    /**
+     * `jwks_uri` do IdP. Usado para montar um remote JWKS quando `keys` não é
+     * fornecido. Default: `${issuer}/jwks` (rota padrão do oidc-provider).
+     */
+    jwksUri?: string;
+    /**
+     * Função de chave já resolvida (ex.: `createRemoteJWKSet` ou `createLocalJWKSet`).
+     * Tem precedência sobre `jwksUri`; útil em testes para injetar uma chave local.
+     */
+    keys?: JWTVerifyGetKey;
+    /** Algoritmos aceitos. Default: assimétricos. */
+    algorithms?: string[];
+}
+/** Resultado da validação: as claims relevantes p/ localizar a sessão local. */
+export interface ValidatedLogoutToken {
+    sid?: string;
+    sub?: string;
+}
+/**
+ * Valida um `logout_token` (JWT) recebido no Back-Channel Logout, conforme
+ * https://openid.net/specs/openid-connect-backchannel-1_0.html#Validation.
+ *
+ * Verifica a assinatura contra o JWKS do IdP e aplica as regras do spec:
+ * - `iss` bate com o issuer configurado, `aud` inclui o clientId, `iat` presente;
+ * - claim `events` é um objeto contendo a chave do evento de back-channel logout;
+ * - possui ao menos `sid` ou `sub`;
+ * - NÃO contém a claim `nonce` (proibida no logout_token).
+ *
+ * Lança {@link InvalidLogoutTokenError} em qualquer violação.
+ */
+export declare function validateLogoutToken(token: string, opts: ValidateLogoutTokenOptions): Promise<ValidatedLogoutToken>;
+/** Registro de uma sessão local indexada por sid/sub do OP. */
+export interface SessionIndexEntry {
+    sid?: string;
+    sub: string;
+    sessionId: string;
+}
+/**
+ * Mapeia `sid`/`sub` do OP para os ids de sessão locais do RP. É a peça central do
+ * Back-Channel Logout: ao receber um logout_token, o handler consulta este índice
+ * para descobrir QUAIS sessões locais destruir.
+ *
+ * A implementação default ({@link InMemorySessionIndex}) é em memória — adequada para
+ * testes e instâncias únicas. Em PRODUÇÃO, hosts com múltiplas instâncias devem
+ * implementar esta interface sobre um store compartilhado (Redis/DB), já que o POST
+ * de logout pode chegar em uma instância diferente da que criou a sessão.
+ */
+export interface SessionIndex {
+    /** Registra o vínculo OP(sid/sub) -> sessão local. Chamado após o login. */
+    register(entry: SessionIndexEntry): Promise<void> | void;
+    /** Remove e retorna os sessionIds vinculados ao sid (sessão SSO específica). */
+    revokeBySid(sid: string): Promise<string[]> | string[];
+    /** Remove e retorna TODOS os sessionIds vinculados ao sub (todas as sessões do usuário). */
+    revokeBySub(sub: string): Promise<string[]> | string[];
+}
+/**
+ * Implementação default em memória do {@link SessionIndex}. Mantém o mapeamento
+ * sid -> sessionId e sub -> Set<sessionId>. NÃO use em produção multi-instância.
+ */
+export declare class InMemorySessionIndex implements SessionIndex {
+    #private;
+    register(entry: SessionIndexEntry): void;
+    revokeBySid(sid: string): string[];
+    revokeBySub(sub: string): string[];
+}