@adonis-agora/authkit-server 0.74.0 → 0.76.0

package/build/src/agents/delegation_store.js

@@ -0,0 +1,222 @@
+/**
+ * Persistência da delegação de personal agents — três tabelas LIB-OWNED (ver
+ * `schema/ensure.ts`): pedidos de device flow, grants e refresh tokens.
+ *
+ * Query builder puro (sem model Lucid): as tabelas são da lib, o host não as
+ * estende. Comparações de data acontecem em JS depois de buscar a linha pela
+ * chave — timestamp em SQL compara diferente em sqlite/pg/mysql; status e
+ * chaves únicas, não.
+ */
+export const DEVICE_TABLE = 'auth_agent_device_codes';
+export const GRANT_TABLE = 'auth_agent_grants';
+export const REFRESH_TABLE = 'auth_agent_refresh_tokens';
+/** sqlite devolve epoch-ms, mysql/pg devolvem Date, alguns drivers string. */
+function toDate(value) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === 'number')
+        return new Date(value);
+    if (typeof value === 'string' && /^\d+$/.test(value))
+        return new Date(Number(value));
+    return new Date(String(value));
+}
+function toDateOrNull(value) {
+    return value === null || value === undefined ? null : toDate(value);
+}
+function toDevice(row) {
+    return {
+        id: row.id,
+        deviceCodeHash: row.device_code_hash,
+        userCode: row.user_code,
+        clientId: row.client_id,
+        agentSub: row.agent_sub,
+        requestedScope: row.requested_scope,
+        status: row.status,
+        accountId: row.account_id ?? null,
+        grantId: row.grant_id ?? null,
+        intervalSeconds: Number(row.interval_seconds),
+        lastPolledAt: toDateOrNull(row.last_polled_at),
+        expiresAt: toDate(row.expires_at),
+        createdAt: toDate(row.created_at),
+    };
+}
+function toGrant(row) {
+    return {
+        id: row.id,
+        accountId: row.account_id,
+        clientId: row.client_id,
+        agentSub: row.agent_sub,
+        scope: row.scope,
+        expiresAt: toDate(row.expires_at),
+        revokedAt: toDateOrNull(row.revoked_at),
+        createdAt: toDate(row.created_at),
+        updatedAt: toDate(row.updated_at),
+    };
+}
+function affected(result) {
+    // knex devolve o número de linhas; alguns drivers, um array.
+    if (typeof result === 'number')
+        return result;
+    if (Array.isArray(result))
+        return result.length;
+    return 0;
+}
+export class DelegationStore {
+    conn;
+    /** `conn` = uma conexão Lucid (`db.connection(name?)`) — ou uma transação. */
+    constructor(conn) {
+        this.conn = conn;
+    }
+    // ─── device codes ─────────────────────────────────────────────────────────
+    async insertDevice(row) {
+        await this.conn().table(DEVICE_TABLE).insert({
+            id: row.id,
+            device_code_hash: row.deviceCodeHash,
+            user_code: row.userCode,
+            client_id: row.clientId,
+            agent_sub: row.agentSub,
+            requested_scope: row.requestedScope,
+            status: row.status,
+            interval_seconds: row.intervalSeconds,
+            expires_at: row.expiresAt,
+            created_at: row.createdAt,
+        });
+    }
+    async findDeviceByCodeHash(hash) {
+        const row = await this.conn().from(DEVICE_TABLE).where('device_code_hash', hash).first();
+        return row ? toDevice(row) : null;
+    }
+    async findDeviceByUserCode(userCode) {
+        const row = await this.conn().from(DEVICE_TABLE).where('user_code', userCode).first();
+        return row ? toDevice(row) : null;
+    }
+    /** Liga o pedido aprovado ao grant — a partir daqui o polling do agente recebe o token. */
+    async setDeviceGrant(id, grantId) {
+        await this.conn().from(DEVICE_TABLE).where('id', id).update({ grant_id: grantId });
+    }
+    async markPolled(id, at) {
+        await this.conn().from(DEVICE_TABLE).where('id', id).update({ last_polled_at: at });
+    }
+    /**
+     * Transição de estado ATÔMICA: só aplica se o pedido ainda está em `from`.
+     * `false` = outra request chegou antes (aprovação dupla, poll concorrente).
+     */
+    async transitionDevice(id, from, patch) {
+        const update = { status: patch.status };
+        if (patch.accountId !== undefined)
+            update.account_id = patch.accountId;
+        if (patch.grantId !== undefined)
+            update.grant_id = patch.grantId;
+        const result = await this.conn()
+            .from(DEVICE_TABLE)
+            .where('id', id)
+            .where('status', from)
+            .update(update);
+        return affected(result) > 0;
+    }
+    /**
+     * Housekeeping: apaga pedidos que expiraram antes de `before`. O parâmetro
+     * vai pelo mesmo binding do INSERT, então a comparação é coerente no dialeto.
+     */
+    async deleteDevicesExpiredBefore(before) {
+        await this.conn().from(DEVICE_TABLE).where('expires_at', '<', before).delete();
+    }
+    // ─── grants ───────────────────────────────────────────────────────────────
+    async insertGrant(row) {
+        await this.conn().table(GRANT_TABLE).insert({
+            id: row.id,
+            account_id: row.accountId,
+            client_id: row.clientId,
+            agent_sub: row.agentSub,
+            scope: row.scope,
+            expires_at: row.expiresAt,
+            created_at: row.createdAt,
+            updated_at: row.updatedAt,
+        });
+    }
+    async findGrant(id) {
+        const row = await this.conn().from(GRANT_TABLE).where('id', id).first();
+        return row ? toGrant(row) : null;
+    }
+    /** Grants NÃO revogados da tripla (conta, agente, usuário do agente). */
+    async findGrantsFor(accountId, clientId, agentSub) {
+        const rows = await this.conn()
+            .from(GRANT_TABLE)
+            .where('account_id', accountId)
+            .where('client_id', clientId)
+            .where('agent_sub', agentSub)
+            .whereNull('revoked_at');
+        return rows.map(toGrant);
+    }
+    /** Atualiza um grant NÃO revogado. `false` = revogado (ou sumiu) nesse meio-tempo. */
+    async updateGrant(id, patch) {
+        const result = await this.conn()
+            .from(GRANT_TABLE)
+            .where('id', id)
+            .whereNull('revoked_at')
+            .update({ scope: patch.scope, expires_at: patch.expiresAt, updated_at: patch.updatedAt });
+        return affected(result) > 0;
+    }
+    async listGrants(accountId) {
+        const rows = await this.conn()
+            .from(GRANT_TABLE)
+            .where('account_id', accountId)
+            .whereNull('revoked_at')
+            .orderBy('created_at', 'desc');
+        return rows.map(toGrant);
+    }
+    /** Revoga um grant DA CONTA. `false` = não existe, é de outra conta ou já revogado. */
+    async revokeGrant(accountId, id, at) {
+        const result = await this.conn()
+            .from(GRANT_TABLE)
+            .where('id', id)
+            .where('account_id', accountId)
+            .whereNull('revoked_at')
+            .update({ revoked_at: at, updated_at: at });
+        return affected(result) > 0;
+    }
+    async revokeAllGrants(accountId, at) {
+        const result = await this.conn()
+            .from(GRANT_TABLE)
+            .where('account_id', accountId)
+            .whereNull('revoked_at')
+            .update({ revoked_at: at, updated_at: at });
+        return affected(result);
+    }
+    /** Revoga um grant sem checar a conta — reação a reuso de refresh token. */
+    async revokeGrantById(id, at) {
+        await this.conn()
+            .from(GRANT_TABLE)
+            .where('id', id)
+            .whereNull('revoked_at')
+            .update({ revoked_at: at, updated_at: at });
+    }
+    // ─── refresh tokens ───────────────────────────────────────────────────────
+    async insertRefreshToken(row) {
+        await this.conn().table(REFRESH_TABLE).insert({
+            token_hash: row.tokenHash,
+            grant_id: row.grantId,
+            expires_at: row.expiresAt,
+            created_at: row.createdAt,
+        });
+    }
+    async findRefreshToken(tokenHash) {
+        const row = await this.conn().from(REFRESH_TABLE).where('token_hash', tokenHash).first();
+        return row
+            ? {
+                grantId: row.grant_id,
+                expiresAt: toDate(row.expires_at),
+                usedAt: toDateOrNull(row.used_at),
+            }
+            : null;
+    }
+    /** Marca o refresh como usado (uso único, atômico). `false` = já tinha sido usado. */
+    async useRefreshToken(tokenHash, at) {
+        const result = await this.conn()
+            .from(REFRESH_TABLE)
+            .where('token_hash', tokenHash)
+            .whereNull('used_at')
+            .update({ used_at: at });
+        return affected(result) > 0;
+    }
+}

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

@@ -0,0 +1,73 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { PersonalAgentIdentity } from './agent_identity.js';
+import type { DelegationContext } from './delegation_service.js';
+import type { PersonalAgentProtocol } from './protocol.js';
+/** 401 sem corpo, só o challenge do protocolo (PACT §3.4/§5.5). */
+export declare function personalAgentUnauthorized(ctx: HttpContext, protocol: PersonalAgentProtocol, error?: 'invalid_token'): void;
+/** O que o middleware anexa à request. */
+export interface PersonalAgentRequestContext extends PersonalAgentIdentity {
+    /** Delegação válida enviada junto, ou `null` (o agente fala só com identidade). */
+    delegation: DelegationContext | null;
+}
+/**
+ * O agente que chamou e a delegação dele — preenchido por
+ * {@link personalAgentAuth}. `null` numa rota sem o middleware.
+ */
+export declare function personalAgentOf(ctx: HttpContext): PersonalAgentRequestContext | null;
+export interface PersonalAgentAuthOptions {
+    /**
+     * - `'optional'` (default): valida a delegação SE vier; sem ela, segue só
+     *   com identidade. É o que o PACT pede no endpoint do agente — falta de
+     *   scope vira step-up, não erro.
+     * - `'required'`: sem delegação válida, 401 `invalid_token` (APIs que só
+     *   fazem sentido agindo na conta).
+     */
+    delegation?: 'optional' | 'required';
+}
+/**
+ * Middleware das rotas que os personal agents chamam (o endpoint de agente do
+ * app, ou uma API exposta a eles). Verifica o JWT do agente e, se vier, o token
+ * de delegação no header do protocolo — falhas respondem 401 sem corpo. Em
+ * sucesso, {@link personalAgentOf} devolve o agente e a delegação.
+ *
+ * ```ts
+ * import { personalAgentAuth } from '@adonis-agora/authkit-server'
+ * router.post('/a2a/message:send', [A2aController, 'send']).use(personalAgentAuth())
+ * ```
+ *
+ * Lembre de isentar essas rotas do CSRF (são server-to-server).
+ */
+export declare function personalAgentAuth(options?: PersonalAgentAuthOptions): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * Bloco de segurança da descoberta do app — no PACT, os `securitySchemes` e
+ * `securityRequirements` do Agent Card (§2.1, §5.1). Faça spread no documento
+ * que o app serve.
+ */
+export declare function personalAgentSecurity(ctx: HttpContext, options?: {
+    /**
+     * A interface URL do card. Um app com vários agentes serve um card por agente, mas a delegação
+     * vale para UMA interface (`delegation.interfaceUrl`): os demais cards anunciam só identidade.
+     */
+    interfaceUrl?: string;
+}): Promise<Record<string, unknown>>;
+/**
+ * Step-up: o turno precisa de scopes que o token não tem. Devolve o `metadata`
+ * da resposta que pede autorização ao usuário (no PACT, a task
+ * `TASK_STATE_AUTH_REQUIRED` de §5.5) — os scopes faltantes e um link de
+ * consentimento pedindo só eles. Aprovar por esse link SOMA os scopes ao grant
+ * existente; o agente obtém o token novo repetindo o device flow, ou com um
+ * refresh, que já sai com o grant atualizado.
+ */
+export declare function personalAgentStepUp(ctx: HttpContext, missingScopes: string[]): Promise<Record<string, unknown>>;
+/**
+ * Recibo assinado de uma resposta servida sob delegação, já no `metadata` do
+ * protocolo (no PACT, `pact.receipt` — §5.6). O PACT exige um em TODA resposta
+ * com delegação.
+ */
+export declare function personalAgentReceipt(ctx: HttpContext, input: {
+    scopesUsed: string[];
+    actions?: {
+        tool: string;
+        argsHash?: string;
+    }[];
+}): Promise<Record<string, unknown>>;

package/build/src/agents/middleware.js

@@ -0,0 +1,113 @@
+import { personalAgentsFor } from './runtime.js';
+/** 401 sem corpo, só o challenge do protocolo (PACT §3.4/§5.5). */
+export function personalAgentUnauthorized(ctx, protocol, error) {
+    ctx.response.header('WWW-Authenticate', protocol.challenge(error));
+    return ctx.response.status(401).send('');
+}
+/**
+ * Guardado fora do `HttpContext` de propósito: uma augmentation alcançável
+ * pelo barrel vazaria para os tipos de todo host (ver
+ * `augmentation_isolation.spec.ts`).
+ */
+const requestContexts = new WeakMap();
+/**
+ * O agente que chamou e a delegação dele — preenchido por
+ * {@link personalAgentAuth}. `null` numa rota sem o middleware.
+ */
+export function personalAgentOf(ctx) {
+    return requestContexts.get(ctx) ?? null;
+}
+async function requireRuntime(ctx, helper) {
+    const runtime = await personalAgentsFor(ctx);
+    if (!runtime)
+        throw new Error(`authkit: ${helper} exige \`personalAgents\` no config.`);
+    return runtime;
+}
+/**
+ * Middleware das rotas que os personal agents chamam (o endpoint de agente do
+ * app, ou uma API exposta a eles). Verifica o JWT do agente e, se vier, o token
+ * de delegação no header do protocolo — falhas respondem 401 sem corpo. Em
+ * sucesso, {@link personalAgentOf} devolve o agente e a delegação.
+ *
+ * ```ts
+ * import { personalAgentAuth } from '@adonis-agora/authkit-server'
+ * router.post('/a2a/message:send', [A2aController, 'send']).use(personalAgentAuth())
+ * ```
+ *
+ * Lembre de isentar essas rotas do CSRF (são server-to-server).
+ */
+export function personalAgentAuth(options = {}) {
+    const mode = options.delegation ?? 'optional';
+    return async (ctx, next) => {
+        const runtime = await personalAgentsFor(ctx);
+        if (!runtime)
+            return ctx.response.notFound();
+        const { protocol } = runtime.config;
+        // Autentica ANTES de ler o corpo (PACT §3.4).
+        const agent = await runtime.verifier.verify(ctx.request.header('authorization'));
+        if (!agent)
+            return personalAgentUnauthorized(ctx, protocol);
+        let delegation = null;
+        const header = ctx.request.header(protocol.delegationHeader);
+        if (header) {
+            delegation = runtime.delegation ? await runtime.delegation.verify(agent, header) : null;
+            if (!delegation)
+                return personalAgentUnauthorized(ctx, protocol, 'invalid_token');
+        }
+        else if (mode === 'required') {
+            return personalAgentUnauthorized(ctx, protocol, 'invalid_token');
+        }
+        requestContexts.set(ctx, { ...agent, delegation });
+        return next();
+    };
+}
+/**
+ * Bloco de segurança da descoberta do app — no PACT, os `securitySchemes` e
+ * `securityRequirements` do Agent Card (§2.1, §5.1). Faça spread no documento
+ * que o app serve.
+ */
+export async function personalAgentSecurity(ctx, options = {}) {
+    const runtime = await requireRuntime(ctx, 'personalAgentSecurity');
+    const delegates = runtime.delegation !== null &&
+        (options.interfaceUrl === undefined ||
+            options.interfaceUrl === runtime.delegation.interfaceUrl);
+    return runtime.config.protocol.discovery({
+        deviceAuthorizationUrl: runtime.urls.deviceAuthorization,
+        tokenUrl: runtime.urls.token,
+        metadataUrl: runtime.urls.metadata,
+        scopes: delegates ? runtime.delegation.scopes : null,
+    });
+}
+/**
+ * Step-up: o turno precisa de scopes que o token não tem. Devolve o `metadata`
+ * da resposta que pede autorização ao usuário (no PACT, a task
+ * `TASK_STATE_AUTH_REQUIRED` de §5.5) — os scopes faltantes e um link de
+ * consentimento pedindo só eles. Aprovar por esse link SOMA os scopes ao grant
+ * existente; o agente obtém o token novo repetindo o device flow, ou com um
+ * refresh, que já sai com o grant atualizado.
+ */
+export async function personalAgentStepUp(ctx, missingScopes) {
+    const runtime = await requireRuntime(ctx, 'personalAgentStepUp');
+    const agent = personalAgentOf(ctx);
+    if (!runtime.delegation || !agent) {
+        throw new Error('authkit: personalAgentStepUp exige `personalAgents.delegation` e o personalAgentAuth() na rota.');
+    }
+    const link = await runtime.delegation.requestDevice(agent, missingScopes.join(' '));
+    return runtime.config.protocol.stepUp({
+        missingScopes,
+        verificationUriComplete: link.verification_uri_complete,
+    });
+}
+/**
+ * Recibo assinado de uma resposta servida sob delegação, já no `metadata` do
+ * protocolo (no PACT, `pact.receipt` — §5.6). O PACT exige um em TODA resposta
+ * com delegação.
+ */
+export async function personalAgentReceipt(ctx, input) {
+    const runtime = await requireRuntime(ctx, 'personalAgentReceipt');
+    const delegation = personalAgentOf(ctx)?.delegation;
+    if (!runtime.delegation || !delegation) {
+        throw new Error('authkit: personalAgentReceipt só vale numa request com delegação válida.');
+    }
+    return runtime.config.protocol.receipt(await runtime.delegation.receipt(delegation, input));
+}

package/build/src/agents/protocol.d.ts

@@ -0,0 +1,62 @@
+import type { DelegationReceipt } from './delegation_service.js';
+/**
+ * Adapter de PROTOCOLO dos personal agents. O núcleo (identidade do agente por
+ * JWT/JWKS, device flow, grants, tokens de delegação, recibos) é o mesmo em
+ * qualquer protocolo; o que muda é o "fio": regras do JWT do agente, nome do
+ * header de delegação, challenge do 401, bloco de descoberta, formato do
+ * step-up e do recibo.
+ *
+ * Embutido hoje: `'pact'` (https://openpactprotocol.org, v1.0). Outro protocolo
+ * (ex.: o Personal Agent Protocol da Sierra, quando sair a spec) entra como
+ * mais um objeto desta interface — passado direto em `personalAgents.protocol`
+ * enquanto não for embutido.
+ */
+export interface PersonalAgentProtocol {
+    /** Identificador estável (`'pact'`). */
+    readonly id: string;
+    /** Regras do JWT com que o agente se identifica. */
+    readonly identity: {
+        /** Algoritmos aceitos; os demais são rejeitados antes de buscar chave. */
+        algorithms: string[];
+        /** Vida máxima (`exp - iat`), em segundos. */
+        maxLifetimeSeconds: number;
+        /** Tolerância de relógio, em segundos. */
+        clockSkewSeconds: number;
+    };
+    /** Header (minúsculo) que carrega o token de delegação junto do JWT do agente. */
+    readonly delegationHeader: string;
+    /** Valor do `WWW-Authenticate` nos 401. `invalid_token` = delegação inválida. */
+    challenge(error?: 'invalid_token'): string;
+    /** Bloco de segurança que o app publica na descoberta (Agent Card, no PACT). */
+    discovery(input: {
+        deviceAuthorizationUrl: string;
+        tokenUrl: string;
+        metadataUrl: string;
+        /** `null` = delegação desligada (só identidade). */
+        scopes: Record<string, string> | null;
+    }): Record<string, unknown>;
+    /** Metadata da resposta que pede mais scopes ao usuário (step-up). */
+    stepUp(input: {
+        missingScopes: string[];
+        verificationUriComplete: string;
+    }): Record<string, unknown>;
+    /** Metadata que carrega o recibo de uma resposta servida sob delegação. */
+    receipt(receipt: DelegationReceipt): Record<string, unknown>;
+}
+export interface PactOptions {
+    /**
+     * Nome do esquema de identidade no Agent Card. Default `'platformJwt'`, o da implementação de
+     * referência e da suíte de conformidade do PACT — o texto da spec diz `'paJwt'`. Os clientes
+     * escolhem o esquema pelo tipo, não pelo nome, então os dois interoperam.
+     */
+    identitySchemeName?: string;
+}
+/** PACT 1.0 — §3.2 (JWT do agente), §2.1/§5.1 (Agent Card), §5.5 (step-up), §5.6 (recibo). */
+export declare function pact(options?: PactOptions): PersonalAgentProtocol;
+/** O adapter PACT com os defaults da spec. */
+export declare const pactProtocol: PersonalAgentProtocol;
+/** Protocolos embutidos, pelo id aceito em `personalAgents.protocol`. */
+export declare const BUILTIN_PROTOCOLS: {
+    readonly pact: PersonalAgentProtocol;
+};
+export type BuiltinProtocolId = keyof typeof BUILTIN_PROTOCOLS;

package/build/src/agents/protocol.js

@@ -0,0 +1,51 @@
+/** PACT 1.0 — §3.2 (JWT do agente), §2.1/§5.1 (Agent Card), §5.5 (step-up), §5.6 (recibo). */
+export function pact(options = {}) {
+    const identity = options.identitySchemeName ?? 'platformJwt';
+    return {
+        id: 'pact',
+        identity: { algorithms: ['ES256', 'RS256'], maxLifetimeSeconds: 300, clockSkewSeconds: 30 },
+        delegationHeader: 'x-a2a-user-delegation',
+        challenge(error) {
+            return error ? `Bearer realm="a2a", error="${error}"` : 'Bearer realm="a2a"';
+        },
+        discovery({ deviceAuthorizationUrl, tokenUrl, metadataUrl, scopes }) {
+            const identityScheme = { httpAuthSecurityScheme: { scheme: 'Bearer', bearerFormat: 'JWT' } };
+            const identityOnly = { schemes: { [identity]: { list: [] } } };
+            if (!scopes) {
+                return {
+                    securitySchemes: { [identity]: identityScheme },
+                    securityRequirements: [identityOnly],
+                };
+            }
+            return {
+                securitySchemes: {
+                    [identity]: identityScheme,
+                    userDelegation: {
+                        oauth2SecurityScheme: {
+                            flows: { deviceCode: { deviceAuthorizationUrl, tokenUrl, scopes: { ...scopes } } },
+                            oauth2MetadataUrl: metadataUrl,
+                        },
+                    },
+                },
+                // A entrada só-identidade FICA (§5.1): o agente sempre pode falar sem delegação.
+                securityRequirements: [
+                    identityOnly,
+                    { schemes: { [identity]: { list: [] }, userDelegation: { list: [] } } },
+                ],
+            };
+        },
+        stepUp({ missingScopes, verificationUriComplete }) {
+            return {
+                'pact.missingScopes': missingScopes,
+                'pact.verificationUriComplete': verificationUriComplete,
+            };
+        },
+        receipt(receipt) {
+            return { 'pact.receipt': { jws: receipt.jws, claims: receipt.claims } };
+        },
+    };
+}
+/** O adapter PACT com os defaults da spec. */
+export const pactProtocol = pact();
+/** Protocolos embutidos, pelo id aceito em `personalAgents.protocol`. */
+export const BUILTIN_PROTOCOLS = { pact: pactProtocol };

package/build/src/agents/runtime.d.ts

@@ -0,0 +1,36 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { OidcService } from '../provider/oidc_service.js';
+import { PersonalAgentVerifier } from './agent_identity.js';
+import type { ResolvedPersonalAgentsConfig } from './config.js';
+import { PersonalAgentDelegation } from './delegation_service.js';
+/** URLs públicas do authorization server de delegação. */
+export interface PersonalAgentUrls {
+    /** `issuer` (RFC 8414) — também o `iss` dos tokens de delegação. */
+    issuer: string;
+    metadata: string;
+    jwks: string;
+    deviceAuthorization: string;
+    token: string;
+    /** Tela de consentimento — o `verification_uri` do device flow. */
+    consent: string;
+}
+/**
+ * Deriva as URLs da ORIGEM do issuer configurado — nunca do Host da request
+ * (mesma regra dos links de e-mail: um Host forjado não pode virar o `iss`).
+ */
+export declare function personalAgentUrls(oidcIssuer: string, prefix: string): PersonalAgentUrls;
+/** Tudo que as rotas e o middleware de personal agents usam, já montado. */
+export interface PersonalAgentsRuntime {
+    config: ResolvedPersonalAgentsConfig;
+    urls: PersonalAgentUrls;
+    verifier: PersonalAgentVerifier;
+    /** `null` quando o app não configurou `personalAgents.delegation`. */
+    delegation: PersonalAgentDelegation | null;
+}
+/**
+ * Monta (uma vez por `OidcService`) o runtime de personal agents. `null` quando
+ * `personalAgents` não está no config — as rotas respondem 404.
+ */
+export declare function buildPersonalAgentsRuntime(service: OidcService, makeDb: () => Promise<any>): Promise<PersonalAgentsRuntime | null>;
+/** Runtime a partir de uma request. */
+export declare function personalAgentsFor(ctx: HttpContext): Promise<PersonalAgentsRuntime | null>;

package/build/src/agents/runtime.js

@@ -0,0 +1,65 @@
+import { supportsAccountStatus } from '../accounts/account_store.js';
+import { PersonalAgentVerifier } from './agent_identity.js';
+import { PersonalAgentDelegation } from './delegation_service.js';
+import { DelegationStore } from './delegation_store.js';
+import { keystoreSigner } from './signer.js';
+/**
+ * Deriva as URLs da ORIGEM do issuer configurado — nunca do Host da request
+ * (mesma regra dos links de e-mail: um Host forjado não pode virar o `iss`).
+ */
+export function personalAgentUrls(oidcIssuer, prefix) {
+    const origin = new URL(oidcIssuer).origin;
+    const issuer = `${origin}${prefix}/oauth`;
+    return {
+        issuer,
+        metadata: `${issuer}/.well-known/oauth-authorization-server`,
+        jwks: `${issuer}/jwks.json`,
+        deviceAuthorization: `${issuer}/device_authorization`,
+        token: `${issuer}/token`,
+        consent: `${origin}${prefix}/consent`,
+    };
+}
+const runtimes = new WeakMap();
+/**
+ * Monta (uma vez por `OidcService`) o runtime de personal agents. `null` quando
+ * `personalAgents` não está no config — as rotas respondem 404.
+ */
+export function buildPersonalAgentsRuntime(service, makeDb) {
+    let runtime = runtimes.get(service);
+    if (!runtime) {
+        runtime = (async () => {
+            const config = service.config.personalAgents;
+            if (!config)
+                return null;
+            const urls = personalAgentUrls(service.config.issuer, config.prefix);
+            let delegation = null;
+            if (config.delegation) {
+                const db = await makeDb();
+                const connection = service.config.schema.connection;
+                delegation = new PersonalAgentDelegation({
+                    cfg: config.delegation,
+                    store: new DelegationStore(() => connection ? db.connection(connection) : db.connection()),
+                    signer: keystoreSigner(service),
+                    urls: { issuer: urls.issuer, consent: urls.consent },
+                    // Conta apagada ou suspensa corta a delegação na hora.
+                    isAccountActive: async (accountId) => {
+                        const store = service.config.accountStore;
+                        if (!(await store.findById(accountId)))
+                            return false;
+                        return !(supportsAccountStatus(store) && (await store.isDisabled(accountId)));
+                    },
+                });
+            }
+            return { config, urls, verifier: new PersonalAgentVerifier(config), delegation };
+        })();
+        // Falha (DB indisponível) não fica em cache — a próxima request tenta de novo.
+        runtime.catch(() => runtimes.delete(service));
+        runtimes.set(service, runtime);
+    }
+    return runtime;
+}
+/** Runtime a partir de uma request. */
+export async function personalAgentsFor(ctx) {
+    const service = await ctx.containerResolver.make('authkit.server');
+    return buildPersonalAgentsRuntime(service, () => ctx.containerResolver.make('lucid.db'));
+}

package/build/src/agents/signer.d.ts

@@ -0,0 +1,34 @@
+import { type JWTPayload, type JWTVerifyGetKey } from 'jose';
+/** Fonte das chaves — o `OidcService` (troca de objeto numa rotação). */
+export interface SigningKeySource {
+    readonly signingJwks: {
+        keys: Record<string, any>[];
+    };
+    readonly publicJwks: {
+        keys: Record<string, any>[];
+    };
+}
+export interface AgentSigner {
+    /** Assina um JWT (token de delegação). */
+    signJwt(payload: JWTPayload, options: {
+        issuedAt: Date;
+        expiresIn: number;
+    }): Promise<string>;
+    /** JWS compacto de um objeto JSON arbitrário (recibo, PACT §5.6). */
+    signJson(value: unknown): Promise<string>;
+    /** Chaves públicas para verificar o que este signer assinou. */
+    keySet(): JWTVerifyGetKey;
+    /** Algoritmos que este signer pode ter usado (para o `jwtVerify`). */
+    readonly algorithms: string[];
+}
+/** Lança quando o JWKS não tem nenhuma chave que possa assinar tokens de delegação. */
+export declare function assertDelegationSigningKey(jwks: {
+    keys: Record<string, any>[];
+}): void;
+/**
+ * Signer sobre o keystore do IdP: a primeira chave ES256/RS256 do JWKS assina
+ * (a primeira é a corrente após uma rotação); o JWKS público inteiro verifica,
+ * então tokens assinados antes de uma rotação continuam válidos no período de
+ * graça. Lê a fonte a cada chamada — rotação ao vivo não exige restart.
+ */
+export declare function keystoreSigner(source: SigningKeySource): AgentSigner;