@adonis-agora/authkit-client 0.9.0

package/build/src/backchannel_logout.js

@@ -0,0 +1,114 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+/** Event type da claim `events` exigido pelo OIDC Back-Channel Logout. */
+export const BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout';
+/** Algoritmos de assinatura aceitos no logout_token (defesa contra alg-confusion). */
+const DEFAULT_ALGS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'EdDSA',
+];
+/** Erro tipado lançado quando o logout_token não satisfaz as regras do spec. */
+export class InvalidLogoutTokenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidLogoutTokenError';
+    }
+}
+/**
+ * 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 async function validateLogoutToken(token, opts) {
+    const keys = opts.keys ?? createRemoteJWKSet(new URL(opts.jwksUri ?? `${opts.issuer}/jwks`));
+    let payload;
+    try {
+        const verified = await jwtVerify(token, keys, {
+            issuer: opts.issuer,
+            audience: opts.clientId,
+            algorithms: opts.algorithms ?? DEFAULT_ALGS,
+        });
+        payload = verified.payload;
+    }
+    catch (err) {
+        throw new InvalidLogoutTokenError(`Invalid logout_token (signature/iss/aud): ${err.message}`);
+    }
+    // `iat` é obrigatório no logout_token.
+    if (typeof payload.iat !== 'number') {
+        throw new InvalidLogoutTokenError('logout_token is missing the iat claim');
+    }
+    // `nonce` é PROIBIDO no logout_token (evita confusão com id_token).
+    if ('nonce' in payload) {
+        throw new InvalidLogoutTokenError('logout_token must not contain the nonce claim');
+    }
+    // `events` deve ser objeto contendo a chave do evento de back-channel logout.
+    const events = payload.events;
+    if (typeof events !== 'object' ||
+        events === null ||
+        Array.isArray(events) ||
+        !(BACKCHANNEL_LOGOUT_EVENT in events)) {
+        throw new InvalidLogoutTokenError(`logout_token sem o evento "${BACKCHANNEL_LOGOUT_EVENT}" na claim events`);
+    }
+    const sid = typeof payload.sid === 'string' ? payload.sid : undefined;
+    const sub = typeof payload.sub === 'string' ? payload.sub : undefined;
+    // Pelo menos um de sid/sub deve estar presente.
+    if (!sid && !sub) {
+        throw new InvalidLogoutTokenError('logout_token must contain at least sid or sub');
+    }
+    return { sid, sub };
+}
+/**
+ * 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 class InMemorySessionIndex {
+    #bySid = new Map();
+    #bySub = new Map();
+    register(entry) {
+        if (entry.sid) {
+            this.#bySid.set(entry.sid, entry.sessionId);
+        }
+        const set = this.#bySub.get(entry.sub) ?? new Set();
+        set.add(entry.sessionId);
+        this.#bySub.set(entry.sub, set);
+    }
+    revokeBySid(sid) {
+        const sessionId = this.#bySid.get(sid);
+        if (!sessionId)
+            return [];
+        this.#bySid.delete(sid);
+        // Mantém os índices coerentes: remove o sessionId de qualquer bucket de sub.
+        for (const [sub, set] of this.#bySub) {
+            if (set.delete(sessionId) && set.size === 0)
+                this.#bySub.delete(sub);
+        }
+        return [sessionId];
+    }
+    revokeBySub(sub) {
+        const set = this.#bySub.get(sub);
+        if (!set)
+            return [];
+        const sessionIds = [...set];
+        this.#bySub.delete(sub);
+        // Remove as entradas de sid que apontavam p/ essas sessões.
+        for (const [sid, sessionId] of this.#bySid) {
+            if (set.has(sessionId))
+                this.#bySid.delete(sid);
+        }
+        return sessionIds;
+    }
+}

package/build/src/define_config.d.ts

@@ -0,0 +1,80 @@
+import type { Identity } from "@adonis-agora/authkit-core";
+import { resolvers, type ResolverFactory } from "./resolvers/factory.js";
+import type { SessionIndex } from "./backchannel_logout.js";
+import type { RevocationStore } from "./revocation/revocation_store.js";
+import type { ResiliencePolicy } from "./http/resilient_fetch.js";
+export { resolvers };
+/** Callback invocado quando um logout_token válido chega via Back-Channel Logout. */
+export type BackchannelLogoutCallback = (event: {
+    sid?: string;
+    sub?: string;
+}) => Promise<void> | void;
+/**
+ * Back-Channel Logout "pronto" para sessões cookie-based: passe um {@link RevocationStore}
+ * e o authkit cuida de tudo —
+ *  - deriva o `onBackchannelLogout` (grava a revogação no store);
+ *  - expõe o store p/ o `BackchannelRevocationMiddleware` enforçar em cada request.
+ *
+ * Substitui o trio model+service+middleware que o consumidor escrevia à mão.
+ */
+export interface BackchannelLogoutInput {
+    /** Store que persiste/consulta revogações (ex.: `lucidRevocationStore({ connection: 'auth' })`). */
+    store: RevocationStore;
+}
+export interface ClientConfigInput {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    resolver: ResolverFactory;
+    resolveUser?: (identity: Identity, context: {
+        accessToken?: string;
+    }) => Promise<unknown>;
+    resolveAppRoles?: (identity: Identity) => Promise<string[]>;
+    sessionKey?: string;
+    scopes?: string[];
+    globalRolesClaim?: string;
+    /**
+     * Invocado após um logout_token VÁLIDO chegar via OIDC Back-Channel Logout. O host
+     * usa o sid/sub recebido para destruir as sessões locais correspondentes.
+     *
+     * Para sessões cookie-based, prefira `backchannelLogout: { store }` — ele deriva
+     * este callback automaticamente. Se ambos forem fornecidos, os dois rodam (store primeiro).
+     */
+    onBackchannelLogout?: BackchannelLogoutCallback;
+    /** Índice sid/sub -> sessão local consultado pelo handler de back-channel logout. */
+    sessionIndex?: SessionIndex;
+    /** Back-Channel Logout "pronto" para sessões cookie-based — ver {@link BackchannelLogoutInput}. */
+    backchannelLogout?: BackchannelLogoutInput;
+    /**
+     * Política de resiliência OPCIONAL aplicada às chamadas HTTP de saída ao IdP
+     * (OIDC discovery + token endpoints). Opt-in: sem ela, o comportamento é um
+     * `fetch` puro (nenhuma mudança).
+     *
+     * Passe o resultado de `wrap(...)` de `@adonis-agora/resilience`, ex.:
+     * `resilience: wrap(timeout(2000), retry({ attempts: 3 }))`. Tipado
+     * estruturalmente — o authkit-client não importa o pacote de resiliência.
+     */
+    resilience?: ResiliencePolicy;
+}
+export interface ResolvedClientConfig {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    resolverFactory: ResolverFactory;
+    resolveUser?: (identity: Identity, context: {
+        accessToken?: string;
+    }) => Promise<unknown>;
+    resolveAppRoles?: (identity: Identity) => Promise<string[]>;
+    sessionKey: string;
+    scopes: string[];
+    globalRolesClaim: string;
+    onBackchannelLogout?: BackchannelLogoutCallback;
+    sessionIndex?: SessionIndex;
+    /** Store de revogação (cookie-based BCL); consumido pelo BackchannelRevocationMiddleware. */
+    backchannelStore?: RevocationStore;
+    /** Política de resiliência opcional p/ chamadas HTTP de saída ao IdP. Ver {@link ClientConfigInput.resilience}. */
+    resilience?: ResiliencePolicy;
+}
+export declare function defineConfig(config: ClientConfigInput): import("@adonisjs/core/types").ConfigProvider<ResolvedClientConfig>;

package/build/src/define_config.js

@@ -0,0 +1,41 @@
+import { configProvider } from "@adonisjs/core";
+import { resolvers } from "./resolvers/factory.js";
+export { resolvers };
+export function defineConfig(config) {
+    return configProvider.create(async () => {
+        const store = config.backchannelLogout?.store;
+        // Compõe o callback de back-channel: o store grava a revogação; o callback do
+        // usuário (se houver) roda depois. Mantém retrocompat com `onBackchannelLogout`.
+        const userHook = config.onBackchannelLogout;
+        const onBackchannelLogout = store || userHook
+            ? async (event) => {
+                if (store)
+                    await store.revoke(event);
+                if (userHook)
+                    await userHook(event);
+            }
+            : undefined;
+        return {
+            issuer: config.issuer,
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
+            redirectUri: config.redirectUri,
+            resolverFactory: config.resolver,
+            resolveUser: config.resolveUser,
+            resolveAppRoles: config.resolveAppRoles,
+            sessionKey: config.sessionKey ?? "authkit",
+            scopes: config.scopes ?? [
+                "openid",
+                "profile",
+                "email",
+                "offline_access",
+                "roles",
+            ],
+            globalRolesClaim: config.globalRolesClaim ?? "roles",
+            onBackchannelLogout,
+            sessionIndex: config.sessionIndex,
+            backchannelStore: store,
+            resilience: config.resilience,
+        };
+    });
+}

package/build/src/discovery.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OIDC Discovery (RFC 8414 / OpenID Connect Discovery 1.0).
+ *
+ * Os helpers de fluxo deste pacote historicamente assumiam as rotas do
+ * oidc-provider (`/auth`, `/token`, `/jwks`…) — convenção do authkit-server.
+ * IdPs de terceiros (Keycloak, Auth0, Okta, Entra…) usam caminhos próprios,
+ * publicados em `{issuer}/.well-known/openid-configuration`.
+ *
+ * `discoverEndpoints()` resolve os endpoints reais do IdP (com cache por
+ * issuer) e cai na convenção do oidc-provider quando o documento não está
+ * disponível — então authkit-server continua funcionando offline/sem rede.
+ *
+ * ```ts
+ * const endpoints = await discoverEndpoints(issuer)
+ * const url = buildAuthorizeUrl({ issuer, authorizationEndpoint: endpoints.authorizationEndpoint, ... })
+ * const tokens = await exchangeCode({ issuer, tokenEndpoint: endpoints.tokenEndpoint, ... })
+ * ```
+ */
+import { type ResiliencePolicy } from "./http/resilient_fetch.js";
+export interface OidcEndpoints {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    jwksUri: string;
+    endSessionEndpoint?: string;
+    userinfoEndpoint?: string;
+    introspectionEndpoint?: string;
+}
+/**
+ * Convenção do oidc-provider (authkit-server) — usada como fallback quando o
+ * documento de discovery não está acessível.
+ */
+export declare function conventionEndpoints(issuer: string): OidcEndpoints;
+export interface DiscoverOptions {
+    /** Overrides manuais — precedem o documento de discovery, campo a campo. */
+    overrides?: Partial<OidcEndpoints>;
+    /** TTL do cache por issuer. Default: 15 min. */
+    cacheTtlMs?: number;
+    fetchImpl?: typeof fetch;
+    /**
+     * Política de resiliência OPCIONAL p/ a chamada de discovery. Sem ela, é um
+     * `fetch` puro (nenhuma mudança de comportamento).
+     */
+    resilience?: ResiliencePolicy;
+}
+/**
+ * Resolve os endpoints do IdP via `/.well-known/openid-configuration`.
+ *
+ * - Resultado cacheado por issuer (TTL 15 min) — seguro de chamar por request.
+ * - Falha de rede/404 → fallback silencioso para a convenção do oidc-provider
+ *   (o cache também guarda o fallback, evitando refetch em loop).
+ * - `overrides` sempre vencem, campo a campo.
+ */
+export declare function discoverEndpoints(issuer: string, options?: DiscoverOptions): Promise<OidcEndpoints>;
+/** Limpa o cache de discovery (testes). */
+export declare function __clearDiscoveryCacheForTests(): void;

package/build/src/discovery.js

@@ -0,0 +1,90 @@
+/**
+ * OIDC Discovery (RFC 8414 / OpenID Connect Discovery 1.0).
+ *
+ * Os helpers de fluxo deste pacote historicamente assumiam as rotas do
+ * oidc-provider (`/auth`, `/token`, `/jwks`…) — convenção do authkit-server.
+ * IdPs de terceiros (Keycloak, Auth0, Okta, Entra…) usam caminhos próprios,
+ * publicados em `{issuer}/.well-known/openid-configuration`.
+ *
+ * `discoverEndpoints()` resolve os endpoints reais do IdP (com cache por
+ * issuer) e cai na convenção do oidc-provider quando o documento não está
+ * disponível — então authkit-server continua funcionando offline/sem rede.
+ *
+ * ```ts
+ * const endpoints = await discoverEndpoints(issuer)
+ * const url = buildAuthorizeUrl({ issuer, authorizationEndpoint: endpoints.authorizationEndpoint, ... })
+ * const tokens = await exchangeCode({ issuer, tokenEndpoint: endpoints.tokenEndpoint, ... })
+ * ```
+ */
+import { resilientFetch, } from "./http/resilient_fetch.js";
+/**
+ * Convenção do oidc-provider (authkit-server) — usada como fallback quando o
+ * documento de discovery não está acessível.
+ */
+export function conventionEndpoints(issuer) {
+    const base = issuer.replace(/\/$/, "");
+    return {
+        authorizationEndpoint: `${base}/auth`,
+        tokenEndpoint: `${base}/token`,
+        jwksUri: `${base}/jwks`,
+        endSessionEndpoint: `${base}/session/end`,
+        userinfoEndpoint: `${base}/me`,
+        introspectionEndpoint: `${base}/token/introspection`,
+    };
+}
+const DEFAULT_TTL_MS = 15 * 60_000;
+const cache = new Map();
+/**
+ * Resolve os endpoints do IdP via `/.well-known/openid-configuration`.
+ *
+ * - Resultado cacheado por issuer (TTL 15 min) — seguro de chamar por request.
+ * - Falha de rede/404 → fallback silencioso para a convenção do oidc-provider
+ *   (o cache também guarda o fallback, evitando refetch em loop).
+ * - `overrides` sempre vencem, campo a campo.
+ */
+export async function discoverEndpoints(issuer, options = {}) {
+    const base = issuer.replace(/\/$/, "");
+    const ttl = options.cacheTtlMs ?? DEFAULT_TTL_MS;
+    const cached = cache.get(base);
+    let endpoints;
+    if (cached && Date.now() - cached.fetchedAt < ttl) {
+        endpoints = cached.endpoints;
+    }
+    else {
+        endpoints = await fetchDiscovery(base, options.fetchImpl ?? fetch, options.resilience);
+        cache.set(base, { endpoints, fetchedAt: Date.now() });
+    }
+    if (!options.overrides)
+        return endpoints;
+    const merged = { ...endpoints };
+    for (const [key, value] of Object.entries(options.overrides)) {
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    return merged;
+}
+async function fetchDiscovery(base, fetchImpl, resilience) {
+    const fallback = conventionEndpoints(base);
+    try {
+        const res = await resilientFetch(`${base}/.well-known/openid-configuration`, { headers: { accept: "application/json" } }, resilience, fetchImpl);
+        if (!res.ok)
+            return fallback;
+        const doc = (await res.json());
+        const str = (v) => typeof v === "string" && v ? v : undefined;
+        return {
+            authorizationEndpoint: str(doc.authorization_endpoint) ?? fallback.authorizationEndpoint,
+            tokenEndpoint: str(doc.token_endpoint) ?? fallback.tokenEndpoint,
+            jwksUri: str(doc.jwks_uri) ?? fallback.jwksUri,
+            endSessionEndpoint: str(doc.end_session_endpoint) ?? fallback.endSessionEndpoint,
+            userinfoEndpoint: str(doc.userinfo_endpoint) ?? fallback.userinfoEndpoint,
+            introspectionEndpoint: str(doc.introspection_endpoint) ?? fallback.introspectionEndpoint,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Limpa o cache de discovery (testes). */
+export function __clearDiscoveryCacheForTests() {
+    cache.clear();
+}

package/build/src/dpop.d.ts

@@ -0,0 +1,50 @@
+import { type JWK, type KeyLike } from 'jose';
+/**
+ * Par de chaves DPoP (RFC 9449). `privateKey`/`publicKey` são KeyLike do jose,
+ * usáveis direto em {@link createDpopProof}. As versões JWK são exportáveis para
+ * persistir/restaurar o par entre requests (ex.: sessão do client).
+ */
+export interface DpopKeyPair {
+    privateKey: KeyLike;
+    publicKey: KeyLike;
+    /** JWK pública (vai no header `jwk` da prova). */
+    publicJwk: JWK;
+    /** JWK privada — guarde com cuidado (só o client a possui). */
+    privateJwk: JWK;
+}
+/**
+ * Gera um par de chaves DPoP ES256 (P-256), exportável como JWK. ES256 é o alg
+ * recomendado pelo RFC 9449 e o que o oidc-provider do authkit-server aceita.
+ */
+export declare function generateDpopKeyPair(): Promise<DpopKeyPair>;
+export interface CreateDpopProofInput {
+    /** Par de chaves DPoP (de {@link generateDpopKeyPair}). */
+    key: DpopKeyPair;
+    /** HTTP method da request alvo (ex.: 'POST'). Vira a claim `htm`. */
+    htm: string;
+    /** HTTP URI alvo SEM query/fragment (ex.: 'https://auth/token'). Vira `htu`. */
+    htu: string;
+    /** Nonce do servidor (DPoP-Nonce), quando exigido. */
+    nonce?: string;
+    /**
+     * Access token quando a prova acompanha uma request a um recurso protegido:
+     * adiciona a claim `ath` = base64url(sha256(accessToken)) (RFC 9449 §4.2).
+     */
+    accessToken?: string;
+}
+/**
+ * Cria uma prova DPoP (JWT) conforme RFC 9449.
+ *
+ *   - header: `typ: 'dpop+jwt'`, `alg: 'ES256'`, `jwk` = chave PÚBLICA.
+ *   - claims: `jti` (único), `htm`, `htu`, `iat`; `ath` quando `accessToken` é dado;
+ *     `nonce` quando dado.
+ *
+ * O resultado vai no header HTTP `DPoP` da request.
+ */
+export declare function createDpopProof(input: CreateDpopProofInput): Promise<string>;
+/**
+ * Calcula o JWK thumbprint (jkt) da chave pública DPoP — o valor que o AS coloca
+ * em `cnf.jkt` ao emitir tokens sender-constrained. Útil para o client conferir
+ * o binding do token recebido.
+ */
+export declare function dpopJwkThumbprint(key: DpopKeyPair): Promise<string>;

package/build/src/dpop.js

@@ -0,0 +1,48 @@
+import { SignJWT, exportJWK, generateKeyPair, calculateJwkThumbprint, base64url, } from 'jose';
+import { createHash, randomUUID } from 'node:crypto';
+/**
+ * Gera um par de chaves DPoP ES256 (P-256), exportável como JWK. ES256 é o alg
+ * recomendado pelo RFC 9449 e o que o oidc-provider do authkit-server aceita.
+ */
+export async function generateDpopKeyPair() {
+    const { privateKey, publicKey } = await generateKeyPair('ES256', { extractable: true });
+    const [publicJwk, privateJwk] = await Promise.all([exportJWK(publicKey), exportJWK(privateKey)]);
+    return { privateKey, publicKey, publicJwk, privateJwk };
+}
+/** ath = base64url( SHA-256( ASCII(access_token) ) ). */
+function accessTokenHash(accessToken) {
+    return base64url.encode(createHash('sha256').update(accessToken, 'ascii').digest());
+}
+/**
+ * Cria uma prova DPoP (JWT) conforme RFC 9449.
+ *
+ *   - header: `typ: 'dpop+jwt'`, `alg: 'ES256'`, `jwk` = chave PÚBLICA.
+ *   - claims: `jti` (único), `htm`, `htu`, `iat`; `ath` quando `accessToken` é dado;
+ *     `nonce` quando dado.
+ *
+ * O resultado vai no header HTTP `DPoP` da request.
+ */
+export async function createDpopProof(input) {
+    const { key, htm, htu, nonce, accessToken } = input;
+    const payload = {
+        jti: randomUUID(),
+        htm: htm.toUpperCase(),
+        htu,
+    };
+    if (accessToken)
+        payload.ath = accessTokenHash(accessToken);
+    if (nonce)
+        payload.nonce = nonce;
+    return new SignJWT(payload)
+        .setProtectedHeader({ typ: 'dpop+jwt', alg: 'ES256', jwk: key.publicJwk })
+        .setIssuedAt()
+        .sign(key.privateKey);
+}
+/**
+ * Calcula o JWK thumbprint (jkt) da chave pública DPoP — o valor que o AS coloca
+ * em `cnf.jkt` ao emitir tokens sender-constrained. Útil para o client conferir
+ * o binding do token recebido.
+ */
+export async function dpopJwkThumbprint(key) {
+    return calculateJwkThumbprint(key.publicJwk, 'sha256');
+}

package/build/src/http/resilient_fetch.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Helper interno para as chamadas HTTP de saída do authkit-client (OIDC
+ * discovery, JWKS e token endpoints).
+ *
+ * Por padrão é um passthrough puro de `fetch` — ZERO mudança de comportamento.
+ * Quando uma {@link ResiliencePolicy} é fornecida (via config do client), a
+ * chamada `fetch` roda dentro de `policy.execute(() => fetch(...))`, ganhando
+ * timeout/retry/circuit-breaker conforme a política composta.
+ *
+ * A política é tipada ESTRUTURALMENTE de propósito: o authkit-client NÃO importa
+ * `@adonis-agora/resilience` em runtime. O consumidor passa o resultado de
+ * `wrap(...)` (de @adonis-agora/resilience) e o duck-typing casa com a interface.
+ */
+/**
+ * Forma estrutural de uma política de resiliência composta — exatamente o que
+ * `wrap(...)` de `@adonis-agora/resilience` retorna. Tipada aqui para evitar um
+ * hard-import do pacote de resiliência.
+ */
+export interface ResiliencePolicy {
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * `fetch` envolvido por uma política de resiliência OPCIONAL.
+ *
+ * - Sem `policy`: chama `fetch(input, init)` diretamente (passthrough).
+ * - Com `policy`: roda `policy.execute(() => fetch(input, init))`.
+ *
+ * `fetchImpl` permite injetar um fetch fake nos testes.
+ */
+export declare function resilientFetch(input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1], policy?: ResiliencePolicy, fetchImpl?: typeof fetch): Promise<Response>;

package/build/src/http/resilient_fetch.js

@@ -0,0 +1,26 @@
+/**
+ * Helper interno para as chamadas HTTP de saída do authkit-client (OIDC
+ * discovery, JWKS e token endpoints).
+ *
+ * Por padrão é um passthrough puro de `fetch` — ZERO mudança de comportamento.
+ * Quando uma {@link ResiliencePolicy} é fornecida (via config do client), a
+ * chamada `fetch` roda dentro de `policy.execute(() => fetch(...))`, ganhando
+ * timeout/retry/circuit-breaker conforme a política composta.
+ *
+ * A política é tipada ESTRUTURALMENTE de propósito: o authkit-client NÃO importa
+ * `@adonis-agora/resilience` em runtime. O consumidor passa o resultado de
+ * `wrap(...)` (de @adonis-agora/resilience) e o duck-typing casa com a interface.
+ */
+/**
+ * `fetch` envolvido por uma política de resiliência OPCIONAL.
+ *
+ * - Sem `policy`: chama `fetch(input, init)` diretamente (passthrough).
+ * - Com `policy`: roda `policy.execute(() => fetch(input, init))`.
+ *
+ * `fetchImpl` permite injetar um fetch fake nos testes.
+ */
+export function resilientFetch(input, init, policy, fetchImpl = fetch) {
+    if (!policy)
+        return fetchImpl(input, init);
+    return policy.execute(() => fetchImpl(input, init));
+}

package/build/src/lucid_mirror.d.ts

@@ -0,0 +1,38 @@
+import type { Identity } from '@adonis-agora/authkit-core';
+/** Model Lucid mínimo que o mirror precisa (só `updateOrCreate`). */
+interface LucidModelLike {
+    updateOrCreate(search: Record<string, unknown>, payload: Record<string, unknown>): Promise<any>;
+}
+export interface LucidMirrorOptions {
+    /**
+     * Campos a sincronizar das claims do id_token a cada login (além do id). Default:
+     * `{ email }`. Ex.: `(i) => ({ email: i.email, fullName: i.profile?.name ?? null })`.
+     */
+    sync?: (identity: Identity) => Record<string, unknown>;
+    /** Relações Lucid a pré-carregar no usuário resolvido (ex.: `['roles']`). */
+    preload?: string[];
+    /**
+     * Injeta `identity.globalRoles` numa propriedade NÃO persistida do usuário (p/ policies).
+     * `true` → `globalRoles`; string → nome custom da propriedade.
+     */
+    injectGlobalRoles?: boolean | string;
+    /** Coluna que casa com `identity.userId`. Default: `id`. */
+    idColumn?: string;
+}
+/**
+ * Factory do padrão "espelho local" de `resolveUser`: faz `updateOrCreate` do usuário
+ * de domínio a partir das claims do id_token, opcionalmente pré-carrega relações e
+ * injeta os papéis globais. Substitui o `resolveUser` que cada app reescrevia.
+ *
+ * ```ts
+ * resolveUser: lucidMirror(AppUser, {
+ *   sync: (i) => ({ email: i.email, fullName: i.profile?.name ?? null }),
+ *   preload: ['roles'],
+ *   injectGlobalRoles: true,
+ * })
+ * ```
+ *
+ * Escape hatch: continue passando uma função própria em `resolveUser` quando precisar.
+ */
+export declare function lucidMirror(Model: LucidModelLike, options?: LucidMirrorOptions): (identity: Identity) => Promise<unknown>;
+export {};

package/build/src/lucid_mirror.js

@@ -0,0 +1,32 @@
+/**
+ * Factory do padrão "espelho local" de `resolveUser`: faz `updateOrCreate` do usuário
+ * de domínio a partir das claims do id_token, opcionalmente pré-carrega relações e
+ * injeta os papéis globais. Substitui o `resolveUser` que cada app reescrevia.
+ *
+ * ```ts
+ * resolveUser: lucidMirror(AppUser, {
+ *   sync: (i) => ({ email: i.email, fullName: i.profile?.name ?? null }),
+ *   preload: ['roles'],
+ *   injectGlobalRoles: true,
+ * })
+ * ```
+ *
+ * Escape hatch: continue passando uma função própria em `resolveUser` quando precisar.
+ */
+export function lucidMirror(Model, options = {}) {
+    const idColumn = options.idColumn ?? 'id';
+    return async (identity) => {
+        const synced = options.sync ? options.sync(identity) : { email: identity.email };
+        const user = await Model.updateOrCreate({ [idColumn]: identity.userId }, { [idColumn]: identity.userId, ...synced });
+        if (options.preload) {
+            for (const relation of options.preload) {
+                await user.load(relation);
+            }
+        }
+        if (options.injectGlobalRoles) {
+            const prop = typeof options.injectGlobalRoles === 'string' ? options.injectGlobalRoles : 'globalRoles';
+            user[prop] = identity.globalRoles ?? [];
+        }
+        return user;
+    };
+}

package/build/src/middleware/auth_middleware.d.ts

@@ -0,0 +1,29 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+export interface AuthMiddlewareOptions {
+    /**
+     * Papéis aceitos. Passa se o usuário tiver QUALQUER um deles como role global
+     * (claim do IdP) OU como app role (`resolveAppRoles`). Vazio/ausente → só exige login.
+     */
+    roles?: string[];
+    /** Para onde redirecionar quando não autenticado. Default: `/auth/login`. */
+    redirectTo?: string;
+    /** Para onde redirecionar quando autenticado mas sem o papel exigido. Default: `/unauthorized`. */
+    unauthorizedRedirect?: string;
+}
+/**
+ * Middleware de autenticação pronto do AuthKit: exige sessão válida (`ctx.auth.check()`)
+ * e, opcionalmente, papéis (global OU app). Substitui o middleware de auth que cada
+ * consumidor reescrevia à mão.
+ *
+ * ```ts
+ * // start/kernel.ts
+ * export const middleware = router.named({
+ *   auth: () => import('@adonis-agora/authkit-client/auth_middleware'),
+ * })
+ * // uso: .use(middleware.auth({ roles: ['ADVISOR'], redirectTo: '/auth/login' }))
+ * ```
+ */
+export default class AuthkitAuthMiddleware {
+    handle(ctx: HttpContext, next: NextFn, options?: AuthMiddlewareOptions): Promise<any>;
+}