@adonis-agora/authkit-server 0.74.0 → 0.76.0

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

@@ -0,0 +1,99 @@
+/**
+ * Personal agents — config.
+ *
+ * Um PERSONAL AGENT é uma plataforma de agente (ChatGPT, Meta AI, um assistente
+ * próprio…) que fala com este app EM NOME de um usuário. Ele se identifica com um
+ * JWT assinado pela própria chave (publicada num JWKS) — sem segredo
+ * compartilhado — e, opcionalmente, recebe do usuário uma DELEGAÇÃO: o usuário
+ * loga aqui, aprova scopes definidos pelo app, e o agente passa a agir na conta
+ * dele só dentro desses scopes.
+ *
+ * O núcleo (identidade do agente, device flow, grants, tokens de delegação,
+ * recibos) não depende de protocolo; o formato do fio vem do adapter em
+ * `protocol` (default: PACT — https://openpactprotocol.org). Ver `protocol.ts`.
+ */
+import { type BuiltinProtocolId, type PersonalAgentProtocol } from './protocol.js';
+/** Registro de um personal agent conhecido (PACT §3.1). */
+export interface PersonalAgentRegistration {
+    /** Valor exato que o agente põe no `iss` do JWT. Também é o `client_id` OAuth dele. */
+    issuer: string;
+    /** URL HTTPS do JWKS do agente. Estável — a rotação acontece dentro do JWKS. */
+    jwksUri: string;
+    /** Nome exibido na tela de consentimento. Default: o host do `issuer`. */
+    name?: string;
+    /** `false` desabilita o agente: as requests dele passam a receber 401. Default: true. */
+    enabled?: boolean;
+}
+/** Resolve um agente pelo `iss`. `null` = desconhecido (401). */
+export type PersonalAgentResolver = (issuer: string) => PersonalAgentRegistration | null | Promise<PersonalAgentRegistration | null>;
+export interface PersonalAgentDelegationConfigInput {
+    /**
+     * URL do endpoint do agente DESTE app que os personal agents chamam (a
+     * "interface URL" do Agent Card). Vira o `aud` dos tokens de delegação — um
+     * token só vale para ela.
+     */
+    interfaceUrl: string;
+    /**
+     * Scopes que o app oferece, `id → descrição`. A descrição aparece VERBATIM na
+     * tela de consentimento, então escreva para o usuário final
+     * (`{ 'orders:read': 'Ver seus pedidos e o status deles' }`).
+     */
+    scopes: Record<string, string>;
+    /** TTL do token de delegação, em segundos. Default: 3600 (o PACT recomenda ≤ 1h). */
+    accessTokenTtl?: number;
+    /** Validade do grant (e dos refresh tokens dele), em segundos. Default: 30 dias. */
+    grantTtl?: number;
+    /** Validade do `device_code`/`user_code`, em segundos. Default: 600. */
+    deviceCodeTtl?: number;
+    /** Intervalo mínimo de polling do token endpoint, em segundos. Default: 5. */
+    pollInterval?: number;
+}
+export interface PersonalAgentsConfigInput {
+    /**
+     * Protocolo do fio: um embutido pelo id (`'pact'`) ou um adapter próprio
+     * (ver {@link PersonalAgentProtocol}). Default: `'pact'`.
+     */
+    protocol?: BuiltinProtocolId | PersonalAgentProtocol;
+    /**
+     * Valor que os personal agents põem no `aud` do JWT deles. Opaco e atribuído
+     * por ESTE app no registro do agente — um valor por app, não derivado de URL.
+     */
+    audience: string;
+    /**
+     * Agentes aceitos: uma lista estática, ou uma função que resolve pelo `iss`
+     * (para quem guarda o registro no banco). Default: nenhum.
+     */
+    agents?: PersonalAgentRegistration[] | PersonalAgentResolver;
+    /**
+     * `true` aceita QUALQUER agente cujo `iss` publique um JWKS via OIDC discovery
+     * (`{iss}/.well-known/openid-configuration`), além dos registrados. A
+     * verificação do JWT continua completa; só a lista de permitidos some.
+     * Default: false.
+     */
+    open?: boolean;
+    /** Delegação (PACT §5). Ausente = só identidade (o agente fala, mas não age na conta). */
+    delegation?: PersonalAgentDelegationConfigInput;
+    /** Prefixo das rotas (`{prefix}/oauth/*`, `{prefix}/consent`). Default: `/agents`. */
+    prefix?: string;
+}
+export interface ResolvedPersonalAgentDelegationConfig {
+    interfaceUrl: string;
+    scopes: Record<string, string>;
+    accessTokenTtl: number;
+    grantTtl: number;
+    deviceCodeTtl: number;
+    pollInterval: number;
+}
+export interface ResolvedPersonalAgentsConfig {
+    protocol: PersonalAgentProtocol;
+    audience: string;
+    resolveAgent: PersonalAgentResolver;
+    open: boolean;
+    delegation?: ResolvedPersonalAgentDelegationConfig;
+    prefix: string;
+}
+export declare function normalizePersonalAgentsPrefix(prefix: string | undefined): string;
+export declare function resolvePersonalAgentsConfig(input: PersonalAgentsConfigInput | undefined): ResolvedPersonalAgentsConfig | undefined;
+/** `"a b  c"` → `['a','b','c']` sem duplicatas, na ordem. */
+export declare function parseScope(value: string | null | undefined): string[];
+export declare function formatScope(scopes: Iterable<string>): string;

package/build/src/agents/config.js

@@ -0,0 +1,101 @@
+/**
+ * Personal agents — config.
+ *
+ * Um PERSONAL AGENT é uma plataforma de agente (ChatGPT, Meta AI, um assistente
+ * próprio…) que fala com este app EM NOME de um usuário. Ele se identifica com um
+ * JWT assinado pela própria chave (publicada num JWKS) — sem segredo
+ * compartilhado — e, opcionalmente, recebe do usuário uma DELEGAÇÃO: o usuário
+ * loga aqui, aprova scopes definidos pelo app, e o agente passa a agir na conta
+ * dele só dentro desses scopes.
+ *
+ * O núcleo (identidade do agente, device flow, grants, tokens de delegação,
+ * recibos) não depende de protocolo; o formato do fio vem do adapter em
+ * `protocol` (default: PACT — https://openpactprotocol.org). Ver `protocol.ts`.
+ */
+import { BUILTIN_PROTOCOLS, } from './protocol.js';
+const SCOPE_ID = /^[\x21\x23-\x5B\x5D-\x7E]+$/; // RFC 6749 §3.3 scope-token
+function assertUrl(value, what) {
+    try {
+        new URL(value);
+    }
+    catch {
+        throw new Error(`authkit: personalAgents.${what} precisa ser uma URL absoluta (recebeu "${value}").`);
+    }
+}
+function positive(value, fallback, what) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`authkit: personalAgents.delegation.${what} precisa ser > 0.`);
+    }
+    return Math.floor(value);
+}
+export function normalizePersonalAgentsPrefix(prefix) {
+    const trimmed = (prefix ?? '/agents').trim().replace(/\/+$/, '');
+    if (!trimmed)
+        return '/agents';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function resolvePersonalAgentsConfig(input) {
+    if (!input)
+        return undefined;
+    if (!input.audience?.trim()) {
+        throw new Error('authkit: personalAgents.audience é obrigatório (o `aud` dos JWTs dos agentes).');
+    }
+    let resolveAgent;
+    if (typeof input.agents === 'function') {
+        resolveAgent = input.agents;
+    }
+    else {
+        const byIssuer = new Map();
+        for (const agent of input.agents ?? []) {
+            assertUrl(agent.issuer, `agents[].issuer`);
+            assertUrl(agent.jwksUri, `agents[].jwksUri`);
+            byIssuer.set(agent.issuer, agent);
+        }
+        resolveAgent = (issuer) => byIssuer.get(issuer) ?? null;
+    }
+    let delegation;
+    if (input.delegation) {
+        const d = input.delegation;
+        assertUrl(d.interfaceUrl, 'delegation.interfaceUrl');
+        const ids = Object.keys(d.scopes ?? {});
+        if (ids.length === 0) {
+            throw new Error('authkit: personalAgents.delegation.scopes precisa de pelo menos um scope.');
+        }
+        for (const id of ids) {
+            if (!SCOPE_ID.test(id)) {
+                throw new Error(`authkit: personalAgents.delegation.scopes — id inválido "${id}" (sem espaços/aspas).`);
+            }
+        }
+        delegation = {
+            interfaceUrl: d.interfaceUrl,
+            scopes: { ...d.scopes },
+            accessTokenTtl: positive(d.accessTokenTtl, 3600, 'accessTokenTtl'),
+            grantTtl: positive(d.grantTtl, 30 * 24 * 3600, 'grantTtl'),
+            deviceCodeTtl: positive(d.deviceCodeTtl, 600, 'deviceCodeTtl'),
+            pollInterval: positive(d.pollInterval, 5, 'pollInterval'),
+        };
+    }
+    const protocol = typeof input.protocol === 'object'
+        ? input.protocol
+        : BUILTIN_PROTOCOLS[input.protocol ?? 'pact'];
+    if (!protocol) {
+        throw new Error(`authkit: personalAgents.protocol "${String(input.protocol)}" desconhecido (embutidos: ${Object.keys(BUILTIN_PROTOCOLS).join(', ')}).`);
+    }
+    return {
+        protocol,
+        audience: input.audience,
+        resolveAgent,
+        open: input.open === true,
+        delegation,
+        prefix: normalizePersonalAgentsPrefix(input.prefix),
+    };
+}
+/** `"a b  c"` → `['a','b','c']` sem duplicatas, na ordem. */
+export function parseScope(value) {
+    return [...new Set((value ?? '').split(' ').filter(Boolean))];
+}
+export function formatScope(scopes) {
+    return [...scopes].join(' ');
+}

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

@@ -0,0 +1,154 @@
+import type { PersonalAgentIdentity } from './agent_identity.js';
+import { type ResolvedPersonalAgentDelegationConfig } from './config.js';
+import type { DelegationStore } from './delegation_store.js';
+import type { AgentSigner } from './signer.js';
+export declare const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+export declare const REFRESH_TOKEN_GRANT_TYPE = "refresh_token";
+/** Erro OAuth (RFC 6749 §5.2 / RFC 8628 §3.5) — vira `{ error, error_description }`. */
+export declare class AgentOAuthError extends Error {
+    readonly code: 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_scope' | 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token' | 'unsupported_grant_type';
+    readonly description: string;
+    readonly status: number;
+    constructor(code: 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_scope' | 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token' | 'unsupported_grant_type', description: string, status?: number);
+}
+export interface DeviceAuthorizationResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DelegationTokenResponse {
+    token_type: 'Bearer';
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    scope: string;
+}
+/** Um pedido aguardando o usuário na tela de consentimento. */
+export interface PendingDelegationRequest {
+    userCode: string;
+    /** `iss` do agente que pediu. */
+    clientId: string;
+    scopes: {
+        id: string;
+        description: string;
+    }[];
+    expiresAt: Date;
+}
+/** O que um token de delegação válido autoriza (PACT §5.5). */
+export interface DelegationContext {
+    /** Conta NESTE app em nome da qual o agente age (`sub` do token). */
+    accountId: string;
+    scopes: string[];
+    grantId: string;
+    /** `iss` do agente. */
+    clientId: string;
+}
+export interface DelegationGrantSummary {
+    id: string;
+    clientId: string;
+    scopes: {
+        id: string;
+        description: string;
+    }[];
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date;
+}
+/** Recibo de uma ação feita sob delegação (PACT §5.6). */
+export interface DelegationReceipt {
+    jws: string;
+    claims: {
+        grantId: string;
+        user: string;
+        pa: string;
+        brand: string;
+        scopesUsed: string[];
+        actions: {
+            tool: string;
+            argsHash?: string;
+        }[];
+        ts: string;
+    };
+}
+export interface PersonalAgentDelegationDeps {
+    cfg: ResolvedPersonalAgentDelegationConfig;
+    store: DelegationStore;
+    signer: AgentSigner;
+    /** `issuer` do authorization server de delegação e URL da tela de consentimento. */
+    urls: {
+        issuer: string;
+        consent: string;
+    };
+    /**
+     * A conta ainda pode agir? (existe e não está desabilitada). Checado em cada
+     * uso do grant: apagar ou suspender a conta corta a delegação na hora.
+     * Default: sempre ativa.
+     */
+    isAccountActive?: (accountId: string) => Promise<boolean>;
+    now?: () => Date;
+}
+/** Aceita o código como o usuário digitar: minúsculas, sem hífen, com espaços. */
+export declare function normalizeUserCode(input: unknown): string | null;
+/**
+ * Delegação de personal agents: RFC 8628 (device code) em que o cliente OAuth é
+ * o agente — autenticado pelo JWT dele, não por client secret — e o login é o
+ * login deste app. O usuário aprova scopes definidos pelo app; o agente recebe
+ * um token assinado pelo keystore do IdP, com vida curta e refresh rotativo,
+ * revogável a qualquer momento no console de conta.
+ *
+ * Um grant por (conta, agente, usuário do agente): aprovar de novo — o step-up
+ * de um scope que faltava — SOMA scopes ao grant existente em vez de criar outro.
+ */
+export declare class PersonalAgentDelegation {
+    #private;
+    constructor(deps: PersonalAgentDelegationDeps);
+    get scopes(): Record<string, string>;
+    get interfaceUrl(): string;
+    /** `POST device_authorization` (PACT §5.3). */
+    requestDevice(agent: PersonalAgentIdentity, scopeParam: unknown): Promise<DeviceAuthorizationResponse>;
+    /** `POST token` com `grant_type=device_code` (RFC 8628 §3.4/§3.5). */
+    exchangeDeviceCode(agent: PersonalAgentIdentity, deviceCode: unknown): Promise<DelegationTokenResponse>;
+    /** `POST token` com `grant_type=refresh_token`. Rotativo: o refresh usado morre. */
+    refresh(agent: PersonalAgentIdentity, refreshToken: unknown): Promise<DelegationTokenResponse>;
+    /** O pedido por trás de um `user_code`, se ainda está aguardando. */
+    pendingRequest(userCodeInput: unknown): Promise<PendingDelegationRequest | null>;
+    /**
+     * O usuário aprovou `scopes` (só o que estava no pedido conta). `null` = nada
+     * foi aprovado: nenhum scope do pedido marcado, ou o pedido não está mais
+     * pendente — o chamador decide se nega.
+     */
+    approve(input: {
+        userCode: string;
+        accountId: string;
+        scopes: string[];
+    }): Promise<{
+        grantId: string;
+        scopes: string[];
+    } | null>;
+    deny(input: {
+        userCode: string;
+        accountId: string;
+    }): Promise<boolean>;
+    listGrants(accountId: string): Promise<DelegationGrantSummary[]>;
+    /** Revoga na hora: tokens já emitidos param de valer na próxima request. */
+    revokeGrant(accountId: string, grantId: string): Promise<boolean>;
+    /** Revoga TODAS as delegações da conta. Devolve quantas estavam vivas. */
+    revokeAllGrants(accountId: string): Promise<number>;
+    /**
+     * Valida o header `X-A2A-User-Delegation: Bearer <token>` de uma request que
+     * JÁ passou pela verificação do JWT do agente (PACT §5.5). `null` = inválido
+     * (o chamador responde 401 `invalid_token`).
+     */
+    verify(agent: PersonalAgentIdentity, header: string | null | undefined): Promise<DelegationContext | null>;
+    /** Recibo assinado de uma resposta servida sob delegação (PACT §5.6). */
+    receipt(delegation: DelegationContext, input: {
+        scopesUsed: string[];
+        actions?: {
+            tool: string;
+            argsHash?: string;
+        }[];
+    }): Promise<DelegationReceipt>;
+}