@adonis-agora/authkit-server 0.34.0

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

@@ -0,0 +1,81 @@
+import { type MetricsRecorder } from '@adonis-agora/authkit-core';
+import type { ResolvedServerConfig } from '../define_config.js';
+import { buildProvider, type SessionTtlHolder, type TokenTtlHolder } from './build_provider.js';
+import { type InteractionActions } from './interaction_actions.js';
+import { type ManagedKeyInfo } from '../keys/keystore.js';
+import type { KeystoreManager } from '../keys/keystore_manager.js';
+export declare class OidcService {
+    #private;
+    get provider(): ReturnType<typeof buildProvider>;
+    get callback(): (req: any, res: any) => void;
+    get interactions(): InteractionActions;
+    /** Pathname do issuer sem barra final (ex.: `/oidc`). Vazio quando montado na raiz. */
+    readonly mountPath: string;
+    readonly recorder: MetricsRecorder;
+    /** Holder mutável dos TTLs de sessão OIDC (lido sincronamente pelo oidc-provider). */
+    readonly sessionTtlHolder: SessionTtlHolder;
+    /** Holder mutável dos TTLs de access/id/refresh tokens (lido sincronamente pelo oidc-provider). */
+    readonly tokenTtlHolder: TokenTtlHolder;
+    get config(): ResolvedServerConfig;
+    /** @internal Loader de JWKS do cofre (usado por reloadKeys). */
+    get jwksLoader(): (() => Promise<{
+        keys: Record<string, any>[];
+    }>) | undefined;
+    /** @internal Token barato de mudança do cofre (usado pelo poll de reload). */
+    get keystoreHead(): (() => Promise<string | null>) | undefined;
+    constructor(config: ResolvedServerConfig, appKey: string, recorder?: MetricsRecorder, deps?: {
+        /** Relê o keystore do cofre e devolve o JWKS (sem `iat`). Ausente → reloadKeys é no-op. */
+        jwksLoader?: () => Promise<{
+            keys: Record<string, any>[];
+        }>;
+        /** Token barato de mudança do cofre (kid/etag/mtime) p/ o poll. */
+        keystoreHead?: () => Promise<string | null>;
+        /** Fábrica do KeystoreManager (necessária para rotateKeys e keystoreAgeDays). */
+        keystoreManager?: () => Promise<KeystoreManager>;
+    });
+    /**
+     * Recarrega as chaves de assinatura AO VIVO: relê o keystore do cofre e reconstrói
+     * o provider com o JWKS novo, trocando a instância atomicamente (#buildAndWire faz
+     * build-em-locais → assign no fim). No-op quando não há `jwksLoader` (source:'jwks'
+     * inline ou managed sem store).
+     *
+     * Serializado por mutex (#reloadChain): chamadas concorrentes são enfileiradas em
+     * vez de executar em paralelo, evitando builds sobrepostos.
+     */
+    reloadKeys(): Promise<void>;
+    /** Idade (dias) da chave de assinatura corrente, ou null (sem keystore gerenciável). */
+    keystoreAgeDays(): Promise<number | null>;
+    /** Lista as chaves managed (kid/alg/idade/ativa), ou [] se não há keystore gerenciável. */
+    listManagedKeys(): Promise<ManagedKeyInfo[]>;
+    /**
+     * Rotaciona a chave de assinatura e aplica ao vivo (rotate → reloadKeys → audit
+     * keys.rotated). Lança quando não há keystore gerenciável. Usado pelo scheduler e
+     * pelo endpoint admin "rotacionar agora".
+     *
+     * Serializado por mutex (#rotateChain): chamadas concorrentes são enfileiradas para
+     * que duas rotações nunca se sobreponham em processo (evita perda silenciosa de escrita).
+     * Cada caller recebe o resultado da SUA própria rotação.
+     */
+    rotateKeys(keep: number, retire?: boolean): Promise<{
+        newKid: string;
+        retiredKids: string[];
+        keptKids: string[];
+    }>;
+    /**
+     * Invalida o cache de clients DINÂMICOS do oidc-provider (a `dynamicClients`
+     * QuickLRU em `instance(provider)`). DEVE ser chamado após qualquer escrita
+     * (create/update/delete) no model `Client` via adapter, pelo console admin.
+     *
+     * NOTA sobre o porquê: o oidc-provider v9 cacheia clients carregados do adapter
+     * numa LRU CUJA CHAVE É O HASH (sha256) DO PAYLOAD persistido — não o client_id.
+     * Por isso uma alteração de metadata já é "auto-invalidante": `Client.find` relê o
+     * adapter, hasheia o payload NOVO, dá cache-miss e reconstrói o client. Mesmo assim
+     * limpamos a LRU explicitamente para (a) tornar o efeito imediato e determinístico
+     * (sem depender de pressão de LRU para expulsar a entrada antiga, agora inalcançável)
+     * e (b) liberar a entrada órfã na hora. É o caminho de invalidação suportado: a LRU
+     * é um detalhe interno acessível via o helper `weak_cache` do próprio provider.
+     */
+    evictDynamicClientCache(): Promise<void>;
+    /** Verifica client_id + client_secret contra os clients da config (p/ endpoints custom como introspecção de PAT). */
+    verifyClientCredentials(clientId: string, clientSecret: string): boolean;
+}

package/build/src/provider/oidc_service.js

@@ -0,0 +1,254 @@
+import { timingSafeEqual } from 'node:crypto';
+import { NoopRecorder } from '@adonis-agora/authkit-core';
+import Koa from 'koa';
+import mount from 'koa-mount';
+import { wireProviderEvents } from '../observability/wire_provider_events.js';
+import { buildProvider } from './build_provider.js';
+import { createInteractionActions } from './interaction_actions.js';
+import { registerTokenExchange } from './token_exchange.js';
+import { readActiveOrgFromKoaCtx } from '../host/active_org_cookie.js';
+import { isFirstParty } from '../host/branding.js';
+import { signingKeyAgeDays, listKeyInfos } from '../keys/keystore.js';
+export class OidcService {
+    #provider;
+    #callback;
+    #interactions;
+    #appKey;
+    get provider() { return this.#provider; }
+    get callback() { return this.#callback; }
+    get interactions() { return this.#interactions; }
+    /** Pathname do issuer sem barra final (ex.: `/oidc`). Vazio quando montado na raiz. */
+    mountPath;
+    recorder;
+    /** Holder mutável dos TTLs de sessão OIDC (lido sincronamente pelo oidc-provider). */
+    sessionTtlHolder;
+    /** Holder mutável dos TTLs de access/id/refresh tokens (lido sincronamente pelo oidc-provider). */
+    tokenTtlHolder;
+    #clients;
+    #config;
+    /** Closures de acesso ao cofre de chaves (injetadas pelo provider para hot-reload). */
+    #deps;
+    /** Mutex de serialização de reloadKeys: encadeia execuções para nunca sobrepor builds. */
+    #reloadChain = Promise.resolve();
+    /** Mutex de serialização de rotateKeys: evita que duas rotações concorrentes se sobreponham. */
+    #rotateChain = Promise.resolve();
+    get config() {
+        return this.#config;
+    }
+    /** @internal Loader de JWKS do cofre (usado por reloadKeys). */
+    get jwksLoader() {
+        return this.#deps.jwksLoader;
+    }
+    /** @internal Token barato de mudança do cofre (usado pelo poll de reload). */
+    get keystoreHead() {
+        return this.#deps.keystoreHead;
+    }
+    constructor(config, appKey, recorder = new NoopRecorder(), deps = {}) {
+        this.#config = config;
+        this.#clients = config.clients ?? [];
+        this.#appKey = appKey;
+        this.recorder = recorder;
+        this.#deps = deps;
+        // Inicializa o holder de TTL com os valores do config estático.
+        // Será atualizado em runtime quando a setting `session_policy` for salva/apagada.
+        const configSessionSec = config.ttl.session;
+        this.sessionTtlHolder = {
+            rememberSec: Math.max(1, configSessionSec),
+            transientSec: Math.max(1, configSessionSec),
+        };
+        // Inicializa o holder de TTL de tokens com os valores do config estático.
+        // Será atualizado em runtime quando a setting `token_ttl` for salva/apagada.
+        this.tokenTtlHolder = {
+            accessTokenSec: Math.max(1, config.ttl.accessToken),
+            idTokenSec: Math.max(1, config.ttl.idToken),
+            refreshTokenSec: Math.max(1, config.ttl.refreshToken),
+        };
+        // mountPath é estável (o issuer nunca muda): deriva diretamente de config.issuer
+        // para que #buildAndWire possa ser chamado sem precisar reconstituir o mountPath.
+        this.mountPath = new URL(config.issuer).pathname.replace(/\/+$/, '');
+        this.#buildAndWire(config.jwks);
+    }
+    #buildAndWire(jwks) {
+        const config = this.#config;
+        const provider = buildProvider({ ...config, jwks }, {
+            appKey: this.#appKey,
+            findAccount: async (ctx, sub) => {
+                const user = await config.findAccount(sub);
+                if (!user)
+                    return undefined;
+                // Lê a org ativa do cookie de sessão (se organizations estiver disponível).
+                const activeOrg = readActiveOrgFromKoaCtx(ctx);
+                // GATE de least-privilege: roles globais e claims de org só são emitidas para
+                // clients FIRST-PARTY (`branding.firstParty`). Capturamos o clientId aqui (fora
+                // do closure `claims()`, pois o `ctx` da request vive neste escopo). Um client
+                // third-party NUNCA recebe roles/org — mesmo solicitando `scope=roles`.
+                const clientId = ctx?.oidc?.client?.clientId;
+                const firstParty = config.branding
+                    ? isFirstParty(config.branding, clientId)
+                    : false;
+                return {
+                    accountId: user.id,
+                    claims: async (_use, _scope) => {
+                        const base = {
+                            sub: user.id,
+                            email: user.email,
+                            email_verified: true,
+                            name: user.name,
+                            picture: user.avatarUrl,
+                        };
+                        // roles/org_* são dados de autorização interna: só para first-party.
+                        if (firstParty) {
+                            base[config.globalRolesClaim] = user.globalRoles ?? [];
+                            // Emite claims de org somente quando há uma org ativa na sessão.
+                            if (activeOrg) {
+                                base['org_id'] = activeOrg.orgId;
+                                base['org_slug'] = activeOrg.orgSlug;
+                                base['org_role'] = activeOrg.orgRole;
+                            }
+                        }
+                        return base;
+                    },
+                };
+            },
+        }, this.sessionTtlHolder, this.tokenTtlHolder);
+        wireProviderEvents(provider, this.recorder);
+        registerTokenExchange(provider, {
+            findAccount: config.findAccount,
+            globalRolesClaim: config.globalRolesClaim,
+            // Resource indicators (RFC 8707) suportados: o `audience` default + cada
+            // resource declarado. Usado para validar `audience`/`resource` no pedido de
+            // token-exchange — alvos fora desta lista são rejeitados (invalid_target).
+            supportedResources: [
+                config.accessTokens.audience,
+                ...Object.keys(config.accessTokens.resources),
+            ],
+            audit: config.audit,
+        });
+        // Quando o issuer tem um path (ex.: http://host/oidc), o provider precisa ser
+        // MONTADO sob esse path via koa-mount. Isso faz o oidc-provider gerar URLs de
+        // discovery e redirects de resume/interaction CORRETAMENTE prefixados (ex.:
+        // /oidc/auth, /oidc/jwks). Apenas remover o prefixo de req.url (abordagem antiga)
+        // fazia o provider se enxergar na raiz e anunciar URLs sem o /oidc.
+        // Para issuer na raiz, o mountPath é vazio e usamos o callback Node direto.
+        let callback;
+        if (this.mountPath && this.mountPath !== '/') {
+            const koa = new Koa();
+            // O app externo PRECISA herdar as Keygrip keys do provider. Sob koa-mount as
+            // requisições do provider rodam no contexto do app EXTERNO, então `ctx.cookies`
+            // usa as keys deste app. Sem isso, os cookies (_interaction, _session) seriam
+            // assinados/lidos de forma inconsistente entre o fluxo via mount (authorize) e as
+            // chamadas diretas `interactionDetails`/`interactionFinished` (que usam o contexto
+            // do provider), quebrando o "interaction session id cookie not found".
+            koa.keys = provider.keys;
+            koa.proxy = provider.proxy;
+            koa.use(mount(this.mountPath, provider));
+            callback = koa.callback();
+        }
+        else {
+            callback = provider.callback();
+        }
+        const interactions = createInteractionActions(provider, { verifyCredentials: config.verifyCredentials });
+        // Atribuição atômica no final: um throw antes deste ponto não corrompe o estado.
+        this.#provider = provider;
+        this.#callback = callback;
+        this.#interactions = interactions;
+    }
+    /**
+     * Recarrega as chaves de assinatura AO VIVO: relê o keystore do cofre e reconstrói
+     * o provider com o JWKS novo, trocando a instância atomicamente (#buildAndWire faz
+     * build-em-locais → assign no fim). No-op quando não há `jwksLoader` (source:'jwks'
+     * inline ou managed sem store).
+     *
+     * Serializado por mutex (#reloadChain): chamadas concorrentes são enfileiradas em
+     * vez de executar em paralelo, evitando builds sobrepostos.
+     */
+    async reloadKeys() {
+        const run = async () => {
+            const loader = this.#deps.jwksLoader;
+            if (!loader)
+                return;
+            const jwks = await loader();
+            this.#buildAndWire(jwks);
+        };
+        this.#reloadChain = this.#reloadChain.then(run, run);
+        return this.#reloadChain;
+    }
+    /** Idade (dias) da chave de assinatura corrente, ou null (sem keystore gerenciável). */
+    async keystoreAgeDays() {
+        const build = this.#deps.keystoreManager;
+        if (!build)
+            return null;
+        const m = await build();
+        return signingKeyAgeDays(await m.read());
+    }
+    /** Lista as chaves managed (kid/alg/idade/ativa), ou [] se não há keystore gerenciável. */
+    async listManagedKeys() {
+        const build = this.#deps.keystoreManager;
+        if (!build)
+            return [];
+        const m = await build();
+        return listKeyInfos(await m.read());
+    }
+    /**
+     * Rotaciona a chave de assinatura e aplica ao vivo (rotate → reloadKeys → audit
+     * keys.rotated). Lança quando não há keystore gerenciável. Usado pelo scheduler e
+     * pelo endpoint admin "rotacionar agora".
+     *
+     * Serializado por mutex (#rotateChain): chamadas concorrentes são enfileiradas para
+     * que duas rotações nunca se sobreponham em processo (evita perda silenciosa de escrita).
+     * Cada caller recebe o resultado da SUA própria rotação.
+     */
+    async rotateKeys(keep, retire = false) {
+        const run = async () => {
+            const build = this.#deps.keystoreManager;
+            if (!build)
+                throw new Error('AuthKit: rotação indisponível (jwks não é managed+store).');
+            const m = await build();
+            const { newKid, retiredKids, store } = await m.rotate(keep, retire);
+            await this.reloadKeys();
+            const keptKids = store.keys.map((k) => k.kid);
+            await this.#config.audit?.record({ type: 'keys.rotated', metadata: { newKid, retiredKids, keptKids, retire } }).catch(() => { });
+            return { newKid, retiredKids, keptKids };
+        };
+        // serializa: encadeia após a rotação em voo; cada caller recebe o resultado da SUA rotação
+        const result = this.#rotateChain.then(run, run);
+        this.#rotateChain = result.catch(() => { }); // a cadeia segue mesmo se uma rotação falhar
+        return result;
+    }
+    /**
+     * Invalida o cache de clients DINÂMICOS do oidc-provider (a `dynamicClients`
+     * QuickLRU em `instance(provider)`). DEVE ser chamado após qualquer escrita
+     * (create/update/delete) no model `Client` via adapter, pelo console admin.
+     *
+     * NOTA sobre o porquê: o oidc-provider v9 cacheia clients carregados do adapter
+     * numa LRU CUJA CHAVE É O HASH (sha256) DO PAYLOAD persistido — não o client_id.
+     * Por isso uma alteração de metadata já é "auto-invalidante": `Client.find` relê o
+     * adapter, hasheia o payload NOVO, dá cache-miss e reconstrói o client. Mesmo assim
+     * limpamos a LRU explicitamente para (a) tornar o efeito imediato e determinístico
+     * (sem depender de pressão de LRU para expulsar a entrada antiga, agora inalcançável)
+     * e (b) liberar a entrada órfã na hora. É o caminho de invalidação suportado: a LRU
+     * é um detalhe interno acessível via o helper `weak_cache` do próprio provider.
+     */
+    async evictDynamicClientCache() {
+        try {
+            const wc = await import('oidc-provider/lib/helpers/weak_cache.js');
+            const get = wc.default ?? wc.get;
+            const int = get(this.provider);
+            int?.dynamicClients?.clear?.();
+        }
+        catch {
+            // Estrutura interna mudou numa versão futura do oidc-provider: a invalidação por
+            // hash-de-conteúdo (acima) continua garantindo correção; só perdemos a expulsão
+            // imediata da entrada órfã. Best-effort — não propaga erro pro caminho da request.
+        }
+    }
+    /** Verifica client_id + client_secret contra os clients da config (p/ endpoints custom como introspecção de PAT). */
+    verifyClientCredentials(clientId, clientSecret) {
+        const client = this.#clients.find((c) => c.clientId === clientId);
+        if (!client || !client.clientSecret)
+            return false;
+        const a = Buffer.from(client.clientSecret);
+        const b = Buffer.from(clientSecret);
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+}

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

@@ -0,0 +1,18 @@
+/** Service do `@adonisjs/lock` (any de propósito — peer opt-in). */
+type LockService = any;
+/**
+ * Cria um executor single-flight: roda `fn` SÓ se conseguir o lock de imediato
+ * (sem esperar) — garante que apenas UMA instância execute a rotação agendada.
+ * Sem `@adonisjs/lock` instalado, assume single-instance e roda `fn` direto
+ * (no-lock). Mirror do padrão peer-lazy (limiter/drive). Libera no `finally`.
+ */
+export interface SingleFlightOptions {
+    key: string;
+    ttlMs: number;
+    /** Carrega o service do lock (default: import lazy de `@adonisjs/lock/services/main`). */
+    loadLock?: () => Promise<LockService | null>;
+    /** Store do lock (db/redis); default deixa o service usar o default do host. */
+    store?: string;
+}
+export declare function makeSingleFlightLock(opts: SingleFlightOptions): (fn: () => Promise<void>) => Promise<void>;
+export {};

package/build/src/provider/single_flight_lock.js

@@ -0,0 +1,31 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+async function defaultLoadLock() {
+    const spec = '@adonisjs/lock/services/main';
+    return import(__rewriteRelativeImportExtension(spec))
+        .then((m) => m.default ?? null)
+        .catch(() => null);
+}
+export function makeSingleFlightLock(opts) {
+    const load = opts.loadLock ?? defaultLoadLock;
+    return async (fn) => {
+        const svc = await load();
+        if (!svc)
+            return fn(); // no-lock (single-instance)
+        const lock = (opts.store ? svc.use(opts.store) : svc.use()).createLock(opts.key, opts.ttlMs);
+        if (!(await lock.acquireImmediately()))
+            return; // outra instância tem o lock
+        try {
+            await fn();
+        }
+        finally {
+            await lock.release().catch(() => { });
+        }
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { AuditSink } from '../audit/audit_sink.js';
+export interface TokenExchangeAccount {
+    id: string;
+    email?: string;
+    name?: string;
+    globalRoles?: string[];
+}
+export interface TokenExchangeDeps {
+    findAccount: (sub: string) => Promise<TokenExchangeAccount | null>;
+    globalRolesClaim: string;
+    adminRole?: string;
+    /**
+     * Resource indicators (RFC 8707) suportados pelo provider. Quando o pedido traz
+     * `audience`/`resource`, validamos contra esta lista; um alvo não suportado é
+     * rejeitado (conservador). Vazio/ausente => nenhum resource é aceito no pedido.
+     */
+    supportedResources?: string[];
+    /** Sink de auditoria (best-effort). Quando presente, registra `impersonation`. */
+    audit?: AuditSink;
+}
+export declare function registerTokenExchange(provider: any, deps: TokenExchangeDeps): void;

package/build/src/provider/token_exchange.js

@@ -0,0 +1,124 @@
+import { errors } from 'oidc-provider';
+const TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+const ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+/**
+ * Interseção entre os scopes pedidos e os scopes permitidos do client (allowlist).
+ * Preserva a ordem do pedido. Nunca excede a allowlist do client.
+ */
+function intersectScopes(requested, allowed) {
+    const out = [];
+    for (const s of requested.split(' ')) {
+        const t = s.trim();
+        if (t && allowed.has(t) && !out.includes(t))
+            out.push(t);
+    }
+    return out.join(' ');
+}
+export function registerTokenExchange(provider, deps) {
+    const adminRole = deps.adminRole ?? 'ADMIN';
+    const supportedResources = new Set(deps.supportedResources ?? []);
+    const handler = async (ctx) => {
+        const { params, client } = ctx.oidc;
+        if (params.subject_token_type !== ACCESS_TOKEN_TYPE) {
+            throw new errors.InvalidRequest('unsupported subject_token_type');
+        }
+        if (!params.subject_token) {
+            throw new errors.InvalidRequest('subject_token is required');
+        }
+        const subjectAt = await provider.AccessToken.find(params.subject_token);
+        if (!subjectAt || subjectAt.isExpired) {
+            throw new errors.InvalidGrant('subject_token invalid or expired');
+        }
+        // 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) {
+            throw new errors.InvalidGrant('subject_token was not issued to this client');
+        }
+        const actor = await deps.findAccount(subjectAt.accountId);
+        if (!actor || !(actor.globalRoles ?? []).includes(adminRole)) {
+            throw new errors.InvalidGrant('actor not permitted to impersonate');
+        }
+        const targetId = params.requested_subject;
+        if (!targetId) {
+            throw new errors.InvalidRequest('requested_subject is required');
+        }
+        const target = await deps.findAccount(targetId);
+        if (!target) {
+            throw new errors.InvalidGrant('requested_subject not found');
+        }
+        // audience/resource: se o pedido vier com um alvo, ele PRECISA estar entre os
+        // resource indicators suportados. Caso contrário rejeitamos (conservador) —
+        // nunca embutimos audiência arbitrária no token emitido.
+        const requestedTargets = [params.audience, params.resource].filter((v) => typeof v === 'string' && v.length > 0);
+        for (const tgt of requestedTargets) {
+            if (!supportedResources.has(tgt)) {
+                throw new errors.InvalidTarget('requested audience/resource is not supported');
+            }
+        }
+        // scope: nunca exceder os scopes permitidos do client autenticado. Quando o
+        // client DECLARA `scope` (allowlist), o pedido é reduzido à INTERSEÇÃO com ela.
+        // Quando o client NÃO declara `scope` (metadata ausente nesta lib = "não
+        // configurado", não "nenhum scope"), preservamos o comportamento atual: usa o
+        // `scope` pedido, ou o default mínimo se o pedido vier vazio.
+        const clientScopes = new Set(String(client?.scope ?? '')
+            .split(' ')
+            .map((s) => s.trim())
+            .filter(Boolean));
+        const DEFAULT_SCOPE = 'openid profile email';
+        let scope;
+        if (clientScopes.size) {
+            // Client com allowlist explícita: interseção (pedido) ou a própria allowlist.
+            scope = params.scope
+                ? intersectScopes(params.scope, clientScopes)
+                : [...clientScopes].join(' ');
+            // Pedido explícito sem nenhuma interseção → erro claro, não token de scope vazio.
+            if (params.scope && !scope) {
+                throw new errors.InvalidScope('requested scope is not allowed for this client', params.scope);
+            }
+        }
+        else {
+            // 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();
+        const idToken = new provider.IdToken({
+            sub: target.id,
+            email: target.email,
+            email_verified: true,
+            name: target.name,
+            [deps.globalRolesClaim]: target.globalRoles ?? [],
+        }, { ctx });
+        idToken.scope = scope;
+        idToken.set('act', { sub: actor.id });
+        const idTokenJwt = await idToken.issue({ use: 'idtoken' });
+        await deps.audit?.record({
+            type: 'impersonation',
+            actorId: actor.id,
+            accountId: target.id,
+            email: target.email ?? null,
+            clientId: client?.clientId ?? null,
+            ip: ctx.req?.socket?.remoteAddress ?? null,
+            metadata: { scope },
+        });
+        ctx.body = {
+            access_token: accessToken,
+            issued_token_type: ACCESS_TOKEN_TYPE,
+            token_type: at.tokenType ?? 'Bearer',
+            expires_in: at.expiration ?? 3600,
+            id_token: idTokenJwt,
+            scope,
+        };
+    };
+    provider.registerGrantType(TOKEN_EXCHANGE, handler, [
+        'subject_token',
+        'subject_token_type',
+        'requested_subject',
+        'requested_token_type',
+        'scope',
+        'audience',
+        'resource',
+        'actor_token',
+        'actor_token_type',
+    ], ['audience', 'resource']);
+}

package/build/src/register_routes.d.ts

@@ -0,0 +1,16 @@
+import type { Router } from '@adonisjs/core/http';
+/**
+ * Registra a rota catch-all que delega ao handler do oidc-provider.
+ * O issuer do consumidor deve terminar em `mountPath` (default `/oidc`),
+ * pois o oidc-provider roteia internamente sob o issuer.
+ * Uso: registerOidcRoutes(router) no start/routes.ts do auth-service.
+ *
+ * Observabilidade (opt-in):
+ * - `metrics: true` monta `GET /authkit/metrics` (snapshot JSON).
+ * - `dashboard: true` monta `GET /authkit/dashboard` (HTML embutido).
+ */
+export declare function registerOidcRoutes(router: Router, options?: {
+    mountPath?: string;
+    metrics?: boolean;
+    dashboard?: boolean;
+}): void;

package/build/src/register_routes.js

@@ -0,0 +1,21 @@
+import OidcCallbackController from './controllers/oidc_callback_controller.js';
+import MetricsController from './observability/metrics_controller.js';
+/**
+ * Registra a rota catch-all que delega ao handler do oidc-provider.
+ * O issuer do consumidor deve terminar em `mountPath` (default `/oidc`),
+ * pois o oidc-provider roteia internamente sob o issuer.
+ * Uso: registerOidcRoutes(router) no start/routes.ts do auth-service.
+ *
+ * Observabilidade (opt-in):
+ * - `metrics: true` monta `GET /authkit/metrics` (snapshot JSON).
+ * - `dashboard: true` monta `GET /authkit/dashboard` (HTML embutido).
+ */
+export function registerOidcRoutes(router, options = {}) {
+    const mount = options.mountPath ?? '/oidc';
+    router.any(`${mount}/*`, [OidcCallbackController]).as('authkit.oidc.wildcard');
+    router.any(mount, [OidcCallbackController]).as('authkit.oidc.root');
+    if (options.metrics)
+        router.get('/authkit/metrics', [MetricsController, 'json']);
+    if (options.dashboard)
+        router.get('/authkit/dashboard', [MetricsController, 'dashboard']);
+}

package/build/src/schema/ensure.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Schema das tabelas que o PRÓPRIO authkit possui (nomes fixos). As tabelas
+ * do host (users, webauthn credentials, provider identities, PATs, audit)
+ * ficam de fora de propósito: nome e shape são decisão do host.
+ *
+ * `ensureAuthkitSchema()` é ADITIVO e idempotente:
+ *  - cria as tabelas que faltam;
+ *  - adiciona colunas novas em tabelas existentes (ALTER ADD);
+ *  - nunca dropa nada nem altera tipo de coluna existente.
+ *
+ * Roda automaticamente no boot quando `schema.autoManage` está ligado
+ * (default), ou manualmente dentro de uma migration do host:
+ *
+ * ```ts
+ * // database/migrations/xxxx_authkit_schema.ts
+ * import { BaseSchema } from '@adonisjs/lucid/schema'
+ * import { ensureAuthkitSchema } from '@adonis-agora/authkit-server'
+ *
+ * export default class extends BaseSchema {
+ *   async up() {
+ *     await ensureAuthkitSchema(this.db)
+ *   }
+ * }
+ * ```
+ */
+export interface EnsureSchemaOptions {
+    /** Conexão Lucid a usar. Default: conexão primária. */
+    connection?: string;
+}
+export interface EnsureSchemaReport {
+    /** Tabelas criadas do zero nesta execução. */
+    created: string[];
+    /** Colunas adicionadas em tabelas já existentes: tabela → colunas. */
+    altered: Record<string, string[]>;
+}
+/**
+ * Garante que as tabelas do authkit existem e têm todas as colunas que esta
+ * versão da lib espera. Aditivo e idempotente — seguro de rodar em todo boot
+ * e dentro de migrations.
+ */
+export declare function ensureAuthkitSchema(db: any, options?: EnsureSchemaOptions): Promise<EnsureSchemaReport>;