@dudousxd/adonis-authkit-server 0.1.0

package/build/src/mixins/with_webauthn_credential.d.ts

@@ -0,0 +1,37 @@
+import { BaseModel } from '@adonisjs/lucid/orm';
+import type { NormalizeConstructor } from '@adonisjs/core/types/helpers';
+import { DateTime } from 'luxon';
+/**
+ * Instância composta pelo mixin {@link withWebauthnCredential}. Representa uma
+ * credencial WebAuthn / passkey ligada a uma conta (`accountId`). Uma conta pode
+ * ter várias credenciais (vários dispositivos/authenticators).
+ *
+ * O `id` é o credential id (base64url) devolvido pelo authenticator — é a chave
+ * primária. `publicKey` é a chave pública COSE em base64url (texto). `counter` é
+ * o contador do signature counter (anti-replay), atualizado a cada autenticação.
+ */
+export interface WebauthnCredentialRow {
+    /** Conta dona desta credencial (→ auth.users). */
+    accountId: string;
+    /** Chave pública COSE em base64url (texto). */
+    publicKey: string;
+    /** Signature counter (anti-replay); atualizado a cada autenticação. */
+    counter: number;
+    /** Transports reportados (ex.: ['internal','hybrid']); null = desconhecido. */
+    transports: string[] | null;
+    /** Rótulo legível opcional (ex.: nome do dispositivo). */
+    label: string | null;
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}
+export type WebauthnCredentialClass<Model extends NormalizeConstructor<typeof BaseModel>> = Model & {
+    new (...args: any[]): WebauthnCredentialRow;
+};
+/**
+ * Mixin de credenciais WebAuthn / passkey. Adiciona as colunas
+ * `account_id`, `public_key`, `counter`, `transports`, `label` + timestamps ao
+ * model. Segue o mesmo padrão de {@link withProviderIdentity}: o host compõe um
+ * model dedicado (`compose(BaseModel, withWebauthnCredential())`) e passa para o
+ * `lucidAccountStore` via a opção `webauthnCredentialModel`.
+ */
+export declare function withWebauthnCredential(): <Model extends NormalizeConstructor<typeof BaseModel>>(superclass: Model) => WebauthnCredentialClass<Model>;

package/build/src/mixins/with_webauthn_credential.js

@@ -0,0 +1,49 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { column } from '@adonisjs/lucid/orm';
+/**
+ * Mixin de credenciais WebAuthn / passkey. Adiciona as colunas
+ * `account_id`, `public_key`, `counter`, `transports`, `label` + timestamps ao
+ * model. Segue o mesmo padrão de {@link withProviderIdentity}: o host compõe um
+ * model dedicado (`compose(BaseModel, withWebauthnCredential())`) e passa para o
+ * `lucidAccountStore` via a opção `webauthnCredentialModel`.
+ */
+export function withWebauthnCredential() {
+    return (superclass) => {
+        class WebauthnCredentialMixin extends superclass {
+        }
+        __decorate([
+            column()
+        ], WebauthnCredentialMixin.prototype, "accountId", void 0);
+        __decorate([
+            column()
+        ], WebauthnCredentialMixin.prototype, "publicKey", void 0);
+        __decorate([
+            column()
+        ], WebauthnCredentialMixin.prototype, "counter", void 0);
+        __decorate([
+            column({
+                prepare: (value) => (value && value.length ? JSON.stringify(value) : null),
+                consume: (value) => {
+                    if (value === null || value === undefined)
+                        return null;
+                    return Array.isArray(value) ? value : JSON.parse(value);
+                },
+            })
+        ], WebauthnCredentialMixin.prototype, "transports", void 0);
+        __decorate([
+            column()
+        ], WebauthnCredentialMixin.prototype, "label", void 0);
+        __decorate([
+            column.dateTime({ autoCreate: true })
+        ], WebauthnCredentialMixin.prototype, "createdAt", void 0);
+        __decorate([
+            column.dateTime({ autoCreate: true, autoUpdate: true })
+        ], WebauthnCredentialMixin.prototype, "updatedAt", void 0);
+        return WebauthnCredentialMixin;
+    };
+}

package/build/src/observability/metrics_controller.d.ts

@@ -0,0 +1,5 @@
+import type { HttpContext } from '@adonisjs/core/http';
+export default class MetricsController {
+    json(ctx: HttpContext): Promise<any>;
+    dashboard(ctx: HttpContext): Promise<void>;
+}

package/build/src/observability/metrics_controller.js

@@ -0,0 +1,24 @@
+function renderDashboardHtml(snapshot) {
+    const counters = Object.entries(snapshot.counters)
+        .map(([k, v]) => `<tr><td>${k}</td><td>${v}</td></tr>`)
+        .join('');
+    const histograms = Object.entries(snapshot.histograms)
+        .map(([k, h]) => `<tr><td>${k}</td><td>${h.count}</td><td>${h.sum}</td><td>${h.min}</td><td>${h.max}</td></tr>`)
+        .join('');
+    return `<!doctype html><html lang="pt-br"><head><meta charset="utf-8"><meta http-equiv="refresh" content="5"><title>AuthKit — Métricas</title>
+<style>body{font-family:system-ui,sans-serif;margin:2rem;color:#111}h1{font-size:1.2rem}table{border-collapse:collapse;margin:1rem 0;width:100%}th,td{border:1px solid #ddd;padding:.4rem .6rem;text-align:left;font-size:.9rem}th{background:#f5f5f5}</style>
+</head><body><h1>AuthKit — Métricas</h1><p>Atualizado: ${snapshot.updatedAt ? new Date(snapshot.updatedAt).toISOString() : '—'}</p>
+<h2>Counters</h2><table><thead><tr><th>Métrica</th><th>Total</th></tr></thead><tbody>${counters || '<tr><td colspan="2">—</td></tr>'}</tbody></table>
+<h2>Histograms</h2><table><thead><tr><th>Métrica</th><th>Count</th><th>Sum</th><th>Min</th><th>Max</th></tr></thead><tbody>${histograms || '<tr><td colspan="5">—</td></tr>'}</tbody></table>
+</body></html>`;
+}
+export default class MetricsController {
+    async json(ctx) {
+        const recorder = await ctx.containerResolver.make('authkit.metrics');
+        return recorder.snapshot();
+    }
+    async dashboard(ctx) {
+        const recorder = await ctx.containerResolver.make('authkit.metrics');
+        return ctx.response.type('html').send(renderDashboardHtml(recorder.snapshot()));
+    }
+}

package/build/src/observability/metrics_service.d.ts

@@ -0,0 +1,2 @@
+import { type MetricsRecorder, type ObservabilityConfig } from '@dudousxd/adonis-authkit-core';
+export declare function createMetricsRecorder(observability: ObservabilityConfig, meterName: string): Promise<MetricsRecorder>;

package/build/src/observability/metrics_service.js

@@ -0,0 +1,7 @@
+import { NoopRecorder } from '@dudousxd/adonis-authkit-core';
+import { OtelRecorder } from './otel_recorder.js';
+export async function createMetricsRecorder(observability, meterName) {
+    if (!observability.metrics)
+        return new NoopRecorder();
+    return OtelRecorder.create(meterName);
+}

package/build/src/observability/otel_recorder.d.ts

@@ -0,0 +1,10 @@
+import { type AuthkitMetricName, type MetricsRecorder, type MetricsSnapshot } from '@dudousxd/adonis-authkit-core';
+/** Recorder que (best-effort) emite via @opentelemetry/api e SEMPRE agrega em memória. */
+export declare class OtelRecorder implements MetricsRecorder {
+    #private;
+    private constructor();
+    static create(name: string): Promise<OtelRecorder>;
+    increment(name: AuthkitMetricName, attributes?: Record<string, string | number>): void;
+    record(name: AuthkitMetricName, value: number, attributes?: Record<string, string | number>): void;
+    snapshot(): MetricsSnapshot;
+}

package/build/src/observability/otel_recorder.js

@@ -0,0 +1,59 @@
+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;
+};
+import { InMemorySnapshot, } from '@dudousxd/adonis-authkit-core';
+/** Recorder que (best-effort) emite via @opentelemetry/api e SEMPRE agrega em memória. */
+export class OtelRecorder {
+    #snapshot = new InMemorySnapshot();
+    #counters = new Map();
+    #histograms = new Map();
+    #meter;
+    constructor(meter) {
+        this.#meter = meter;
+    }
+    static async create(name) {
+        let meter = null;
+        try {
+            // Specifier dinâmico (não-estático) para que o TS não tente resolver o
+            // peer opcional @opentelemetry/api em tempo de compilação. Em runtime,
+            // se o pacote não estiver instalado, caímos no catch e ficamos no-op.
+            const moduleName = '@opentelemetry/api';
+            const otel = await import(__rewriteRelativeImportExtension(moduleName));
+            meter = otel.metrics.getMeter(name);
+        }
+        catch {
+            meter = null;
+        }
+        return new OtelRecorder(meter);
+    }
+    increment(name, attributes) {
+        this.#snapshot.bump(name);
+        if (!this.#meter)
+            return;
+        let c = this.#counters.get(name);
+        if (!c) {
+            c = this.#meter.createCounter(name);
+            this.#counters.set(name, c);
+        }
+        c.add(1, attributes);
+    }
+    record(name, value, attributes) {
+        this.#snapshot.observe(name, value);
+        if (!this.#meter)
+            return;
+        let h = this.#histograms.get(name);
+        if (!h) {
+            h = this.#meter.createHistogram(name);
+            this.#histograms.set(name, h);
+        }
+        h.record(value, attributes);
+    }
+    snapshot() {
+        return this.#snapshot.read();
+    }
+}

package/build/src/observability/wire_provider_events.d.ts

@@ -0,0 +1,12 @@
+import { type MetricsRecorder } from '@dudousxd/adonis-authkit-core';
+/**
+ * Liga eventos do oidc-provider aos counters do recorder. Usa só eventos reais
+ * do v9 (verificados em node_modules/oidc-provider/lib):
+ * - `grant.success`        (actions/token.js)              -> loginSuccess
+ * - `server_error`         (shared/error_handler.js)        -> loginFailure
+ * - `access_token.saved`   (models/base_model.js: <kind>.saved)   -> tokenIssued
+ * - `access_token.issued`  (models/base_model.js: <kind>.issued)  -> tokenIssued
+ * - `refresh_token.saved`  (models/base_model.js: <kind>.saved)   -> refreshRotated
+ * - `grant.revoked`        (helpers/revoke.js)              -> grantRevoked
+ */
+export declare function wireProviderEvents(provider: any, recorder: MetricsRecorder): void;

package/build/src/observability/wire_provider_events.js

@@ -0,0 +1,19 @@
+import { AUTHKIT_METRICS } from '@dudousxd/adonis-authkit-core';
+/**
+ * Liga eventos do oidc-provider aos counters do recorder. Usa só eventos reais
+ * do v9 (verificados em node_modules/oidc-provider/lib):
+ * - `grant.success`        (actions/token.js)              -> loginSuccess
+ * - `server_error`         (shared/error_handler.js)        -> loginFailure
+ * - `access_token.saved`   (models/base_model.js: <kind>.saved)   -> tokenIssued
+ * - `access_token.issued`  (models/base_model.js: <kind>.issued)  -> tokenIssued
+ * - `refresh_token.saved`  (models/base_model.js: <kind>.saved)   -> refreshRotated
+ * - `grant.revoked`        (helpers/revoke.js)              -> grantRevoked
+ */
+export function wireProviderEvents(provider, recorder) {
+    provider.on('grant.success', () => recorder.increment(AUTHKIT_METRICS.loginSuccess));
+    provider.on('server_error', () => recorder.increment(AUTHKIT_METRICS.loginFailure));
+    provider.on('access_token.saved', () => recorder.increment(AUTHKIT_METRICS.tokenIssued));
+    provider.on('access_token.issued', () => recorder.increment(AUTHKIT_METRICS.tokenIssued));
+    provider.on('refresh_token.saved', () => recorder.increment(AUTHKIT_METRICS.refreshRotated));
+    provider.on('grant.revoked', () => recorder.increment(AUTHKIT_METRICS.grantRevoked));
+}

package/build/src/pat/lucid_pat_store.d.ts

@@ -0,0 +1,6 @@
+import type { PatStore } from './pat_store.js';
+/**
+ * Implementação default do {@link PatStore} sobre um model Lucid composto de
+ * `withPersonalAccessToken()`. A coluna DB `user_id` é mapeada de `accountId`.
+ */
+export declare function lucidPatStore(Model: any): PatStore;

package/build/src/pat/lucid_pat_store.js

@@ -0,0 +1,62 @@
+import { DateTime } from 'luxon';
+import { generatePatToken, hashPatToken } from './pat_tokens.js';
+/**
+ * Implementação default do {@link PatStore} sobre um model Lucid composto de
+ * `withPersonalAccessToken()`. A coluna DB `user_id` é mapeada de `accountId`.
+ */
+export function lucidPatStore(Model) {
+    const toRecord = (row) => ({
+        id: row.id,
+        name: row.name,
+        scopes: row.scopes ?? [],
+        audience: row.audience ?? null,
+        createdAt: row.createdAt ? row.createdAt.toISO() : '',
+        lastUsedAt: row.lastUsedAt ? row.lastUsedAt.toISO() : null,
+        expiresAt: row.expiresAt ? row.expiresAt.toISO() : null,
+    });
+    return {
+        async issue(input) {
+            const token = generatePatToken();
+            const row = await Model.create({
+                userId: input.accountId,
+                name: input.name,
+                tokenHash: hashPatToken(token),
+                scopes: input.scopes ?? [],
+                audience: input.audience ?? null,
+                expiresAt: input.expiresInDays
+                    ? DateTime.now().plus({ days: input.expiresInDays })
+                    : null,
+            });
+            return { token, pat: toRecord(row) };
+        },
+        async listForAccount(accountId) {
+            const rows = await Model.query()
+                .where('user_id', accountId)
+                .orderBy('created_at', 'desc');
+            return rows.map(toRecord);
+        },
+        async revoke(accountId, id) {
+            const row = await Model.query().where('id', id).where('user_id', accountId).first();
+            if (!row)
+                return false;
+            await row.delete();
+            return true;
+        },
+        async findActiveByToken(token) {
+            const hash = hashPatToken(token);
+            const row = await Model.query().where('token_hash', hash).first();
+            if (!row)
+                return null;
+            if (row.expiresAt && row.expiresAt < DateTime.now())
+                return null;
+            row.lastUsedAt = DateTime.now();
+            await row.save();
+            return {
+                accountId: row.userId,
+                scopes: row.scopes ?? [],
+                audience: row.audience ?? null,
+                exp: row.expiresAt ? Math.floor(row.expiresAt.toSeconds()) : null,
+            };
+        },
+    };
+}

package/build/src/pat/pat_store.d.ts

@@ -0,0 +1,31 @@
+/** DTO seguro do PAT — sem o hash do token. */
+export interface PatRecord {
+    id: string;
+    name: string;
+    scopes: string[];
+    audience: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+}
+export interface IssuePatInput {
+    accountId: string;
+    name: string;
+    scopes?: string[];
+    audience?: string | null;
+    expiresInDays?: number | null;
+}
+export interface PatStore {
+    issue(input: IssuePatInput): Promise<{
+        token: string;
+        pat: PatRecord;
+    }>;
+    listForAccount(accountId: string): Promise<PatRecord[]>;
+    revoke(accountId: string, id: string): Promise<boolean>;
+    findActiveByToken(token: string): Promise<{
+        accountId: string;
+        scopes: string[];
+        audience: string | null;
+        exp: number | null;
+    } | null>;
+}

package/build/src/pat/pat_store.js

@@ -0,0 +1 @@
+export {};

package/build/src/pat/pat_tokens.d.ts

@@ -0,0 +1,4 @@
+/** Gera um Personal Access Token opaco no formato `pat_<base64url>`. */
+export declare function generatePatToken(): string;
+/** SHA-256 (hex) do token — é o que se persiste; o token cru nunca é guardado. */
+export declare function hashPatToken(token: string): string;

package/build/src/pat/pat_tokens.js

@@ -0,0 +1,9 @@
+import { createHash, randomBytes } from 'node:crypto';
+/** Gera um Personal Access Token opaco no formato `pat_<base64url>`. */
+export function generatePatToken() {
+    return 'pat_' + randomBytes(32).toString('base64url');
+}
+/** SHA-256 (hex) do token — é o que se persiste; o token cru nunca é guardado. */
+export function hashPatToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}

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

@@ -0,0 +1,8 @@
+import * as oidc from 'oidc-provider';
+import type { ResolvedServerConfig } from '../define_config.js';
+export interface BuildProviderOptions {
+    /** APP_KEY do consumidor; usado p/ derivar cookies.keys se não houver. */
+    appKey: string;
+    findAccount: (ctx: any, sub: string, token?: any) => Promise<any>;
+}
+export declare function buildProvider(config: ResolvedServerConfig, options: BuildProviderOptions): oidc.Provider;

package/build/src/provider/build_provider.js

@@ -0,0 +1,101 @@
+import * as oidc from 'oidc-provider';
+export function buildProvider(config, options) {
+    const cookieKeys = config.cookieKeys.length ? config.cookieKeys : [options.appKey];
+    // OIDC Dynamic Client Registration (RFC 7591/7592). Só montamos as chaves de feature
+    // quando habilitado — desligado (default), o oidc-provider não expõe o endpoint /reg.
+    // O `initialAccessToken`: string => valida o bearer contra esse valor estático; ausente
+    // => `false` (registro ABERTO; raramente desejável em prod). Clients registrados aqui
+    // são persistidos automaticamente pelo MESMO AdapterClass, coexistindo com os estáticos.
+    const dynReg = config.dynamicRegistration;
+    const registrationFeatures = dynReg.enabled
+        ? {
+            registration: {
+                enabled: true,
+                initialAccessToken: dynReg.initialAccessToken ?? false,
+            },
+            ...(dynReg.management ? { registrationManagement: { enabled: true } } : {}),
+        }
+        : {};
+    const provider = new oidc.Provider(config.issuer, {
+        adapter: config.AdapterClass,
+        clients: config.clients.map((c) => ({
+            client_id: c.clientId,
+            client_secret: c.clientSecret,
+            redirect_uris: c.redirectUris,
+            post_logout_redirect_uris: c.postLogoutRedirectUris ?? [],
+            grant_types: c.grants ?? ['authorization_code', 'refresh_token'],
+            response_types: (c.grants ?? ['authorization_code']).includes('authorization_code')
+                ? ['code']
+                : [],
+            token_endpoint_auth_method: c.tokenEndpointAuthMethod ?? (c.clientSecret ? 'client_secret_basic' : 'none'),
+            // OIDC Back-Channel Logout: só envia as chaves quando o client as declara,
+            // p/ não forçar metadata vazio em clients que não usam o recurso.
+            ...(c.backchannelLogoutUri ? { backchannel_logout_uri: c.backchannelLogoutUri } : {}),
+            ...(c.backchannelLogoutSessionRequired !== undefined
+                ? { backchannel_logout_session_required: c.backchannelLogoutSessionRequired }
+                : {}),
+        })),
+        findAccount: options.findAccount,
+        jwks: config.jwks,
+        cookies: {
+            keys: cookieKeys,
+            // O oidc-provider define o path do cookie _interaction como
+            // `/auth/interaction/<uid>` (exato) via `...cookieOptions` que
+            // SOBRESCREVE o path explícito. Sem `path: '/'` o cookie ficaria
+            // restrito ao path exato da tela de interaction e NÃO seria enviado
+            // pelo browser no POST de subpaths como `.../consent` ou `.../login`.
+            // Definir path: '/' na família "short" garante que os cookies de
+            // interaction e resume sejam enviados em todos os endpoints OIDC/auth.
+            short: { path: '/' },
+            long: { path: '/' },
+        },
+        // conformIdTokenClaims=false: caso contrário (default v9), no fluxo Authorization Code
+        // — onde também é emitido um Access Token — o oidc-provider mascara o ID token para
+        // apenas o escopo `openid` (só `sub`), removendo email/profile/roles do ID token.
+        // O client valida o ID TOKEN, então precisamos que as claims configuradas cheguem nele.
+        conformIdTokenClaims: false,
+        // A claim de roles globais é atrelada ao escopo `profile` (sempre concedido pelos
+        // scopes padrão do client: openid profile email offline_access). Assim as roles chegam
+        // no ID token sem exigir um escopo `roles` customizado. Mantemos também o mapeamento
+        // do escopo `roles` para quem optar por solicitá-lo explicitamente.
+        claims: {
+            openid: ['sub'],
+            profile: ['name', 'picture', config.globalRolesClaim],
+            email: ['email', 'email_verified'],
+            roles: [config.globalRolesClaim],
+        },
+        scopes: ['openid', 'profile', 'email', 'offline_access', 'roles'],
+        // Permite que o parametro `audience` (hint de intencao do client, ex.: 'advisor')
+        // sobreviva ao authorize e fique disponivel em interactionDetails().params.audience.
+        extraParams: ['audience'],
+        pkce: { methods: ['S256'], required: () => true },
+        rotateRefreshToken: true,
+        features: {
+            devInteractions: { enabled: false },
+            rpInitiatedLogout: { enabled: true },
+            // OIDC Back-Channel Logout: o oidc-provider POSTa um logout_token para o
+            // `backchannel_logout_uri` de cada RP quando a sessão/grant é encerrada.
+            backchannelLogout: { enabled: true },
+            revocation: { enabled: true },
+            introspection: { enabled: true },
+            ...registrationFeatures,
+        },
+        ttl: {
+            AccessToken: config.ttl.accessToken,
+            RefreshToken: config.ttl.refreshToken,
+            IdToken: config.ttl.idToken,
+            Session: config.ttl.session,
+            Interaction: 3600,
+            Grant: config.ttl.refreshToken,
+        },
+        interactions: {
+            // Telas de interaction são servidas pelo CONSUMIDOR na RAIZ (fora do koa-mount do
+            // provider sob /oidc), evitando colisão com o catch-all /oidc/*. O provider redireciona
+            // o browser para cá; o consumidor chama interactionFinished, que devolve ao resume do
+            // provider em /oidc/auth/:uid (já corretamente prefixado pelo koa-mount).
+            url: (_ctx, interaction) => `/auth/interaction/${interaction.uid}`,
+        },
+    });
+    provider.proxy = true;
+    return provider;
+}

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

@@ -0,0 +1,21 @@
+import type { HttpContext } from '@adonisjs/core/http';
+export interface InteractionDeps {
+    verifyCredentials?: (email: string, password: string) => Promise<{
+        id: string;
+    } | null>;
+}
+export interface InteractionActions {
+    details(ctx: HttpContext): Promise<any>;
+    login(ctx: HttpContext, input: {
+        email: string;
+        password: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    completeLogin(ctx: HttpContext, accountId: string): Promise<{
+        ok: boolean;
+    }>;
+    consent(ctx: HttpContext): Promise<unknown>;
+}
+/** Lógica de interaction (login/consent) sobre o provider. Testável com um provider fake. */
+export declare function createInteractionActions(provider: any, deps: InteractionDeps): InteractionActions;

package/build/src/provider/interaction_actions.js

@@ -0,0 +1,32 @@
+/** Lógica de interaction (login/consent) sobre o provider. Testável com um provider fake. */
+export function createInteractionActions(provider, deps) {
+    return {
+        async details(ctx) {
+            return provider.interactionDetails(ctx.request.request, ctx.response.response);
+        },
+        async login(ctx, { email, password }) {
+            if (!deps.verifyCredentials) {
+                throw new Error('authkit: defina `verifyCredentials` no config/authkit.ts para usar o login das interactions.');
+            }
+            const account = await deps.verifyCredentials(email, password);
+            if (!account)
+                return { ok: false };
+            await provider.interactionFinished(ctx.request.request, ctx.response.response, { login: { accountId: account.id } }, { mergeWithLastSubmission: false });
+            return { ok: true };
+        },
+        async completeLogin(ctx, accountId) {
+            await provider.interactionFinished(ctx.request.request, ctx.response.response, { login: { accountId } }, { mergeWithLastSubmission: false });
+            return { ok: true };
+        },
+        async consent(ctx) {
+            const details = await provider.interactionDetails(ctx.request.request, ctx.response.response);
+            const grant = new provider.Grant({
+                accountId: details.session.accountId,
+                clientId: details.params.client_id,
+            });
+            grant.addOIDCScope(String(details.params.scope ?? 'openid'));
+            const grantId = await grant.save();
+            return provider.interactionFinished(ctx.request.request, ctx.response.response, { consent: { grantId } }, { mergeWithLastSubmission: true });
+        },
+    };
+}

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

@@ -0,0 +1,17 @@
+import { type MetricsRecorder } from '@dudousxd/adonis-authkit-core';
+import type { ResolvedServerConfig } from '../define_config.js';
+import { buildProvider } from './build_provider.js';
+import { type InteractionActions } from './interaction_actions.js';
+export declare class OidcService {
+    #private;
+    readonly provider: ReturnType<typeof buildProvider>;
+    readonly callback: (req: any, res: any) => void;
+    /** Pathname do issuer sem barra final (ex.: `/oidc`). Vazio quando montado na raiz. */
+    readonly mountPath: string;
+    readonly recorder: MetricsRecorder;
+    readonly interactions: InteractionActions;
+    get config(): ResolvedServerConfig;
+    constructor(config: ResolvedServerConfig, appKey: string, recorder?: MetricsRecorder);
+    /** 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,84 @@
+import { timingSafeEqual } from 'node:crypto';
+import { NoopRecorder } from '@dudousxd/adonis-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';
+export class OidcService {
+    provider;
+    callback;
+    /** Pathname do issuer sem barra final (ex.: `/oidc`). Vazio quando montado na raiz. */
+    mountPath;
+    recorder;
+    interactions;
+    #clients;
+    #config;
+    get config() {
+        return this.#config;
+    }
+    constructor(config, appKey, recorder = new NoopRecorder()) {
+        this.#config = config;
+        this.#clients = config.clients ?? [];
+        this.recorder = recorder;
+        this.provider = buildProvider(config, {
+            appKey,
+            findAccount: async (_ctx, sub) => {
+                const user = await config.findAccount(sub);
+                if (!user)
+                    return undefined;
+                return {
+                    accountId: user.id,
+                    claims: async (_use, _scope) => ({
+                        sub: user.id,
+                        email: user.email,
+                        email_verified: true,
+                        name: user.name,
+                        picture: user.avatarUrl,
+                        [config.globalRolesClaim]: user.globalRoles ?? [],
+                    }),
+                };
+            },
+        });
+        wireProviderEvents(this.provider, recorder);
+        registerTokenExchange(this.provider, {
+            findAccount: config.findAccount,
+            globalRolesClaim: config.globalRolesClaim,
+            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.
+        this.mountPath = new URL(this.provider.issuer).pathname.replace(/\/+$/, '');
+        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 = this.provider.keys;
+            koa.proxy = this.provider.proxy;
+            koa.use(mount(this.mountPath, this.provider));
+            this.callback = koa.callback();
+        }
+        else {
+            this.callback = this.provider.callback();
+        }
+        this.interactions = createInteractionActions(this.provider, { verifyCredentials: config.verifyCredentials });
+    }
+    /** 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/token_exchange.d.ts

@@ -0,0 +1,15 @@
+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;
+    /** Sink de auditoria (best-effort). Quando presente, registra `impersonation`. */
+    audit?: AuditSink;
+}
+export declare function registerTokenExchange(provider: any, deps: TokenExchangeDeps): void;