@adonis-agora/authkit-server 0.77.0 → 0.79.0

package/build/src/agents/poppy/service.d.ts

@@ -0,0 +1,286 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { DelegationStore } from '../delegation_store.js';
+import type { PoppyClient, PoppyClientRegistry } from './client_registry.js';
+import type { PoppyLimiter, PoppyPrincipalBase, PoppyReplayStore, ResolvedPoppyConfig } from './config.js';
+import { type DpopNonceSource } from './dpop.js';
+import type { PoppyStore, RequestRow } from './store.js';
+export declare const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export declare const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+export declare const BROWSER_ASSERTION_TYP = "poppy-browser+jwt";
+/** URLs públicas do authorization server Poppy. */
+export interface PoppyUrls {
+    origin: string;
+    issuer: string;
+    /** RFC 8414 §3.1: `/.well-known/oauth-authorization-server{issuer path}`. */
+    metadata: string;
+    token: string;
+    revocation: string;
+    authorization: string;
+    deviceAuthorization: string;
+    /** Tela do device flow (`verification_uri`). */
+    device: string;
+    mediated: string;
+    browserSession: string;
+    discovery: string;
+}
+/** Deriva as URLs da ORIGEM do issuer configurado — nunca do Host da request. */
+export declare function poppyUrls(oidcIssuer: string, prefix: string): PoppyUrls;
+/** Resposta do token endpoint (§4.2, §4.4). */
+export interface PoppyTokenResponse {
+    access_token: string;
+    token_type: 'DPoP' | 'Bearer';
+    expires_in: number;
+    scope: string;
+    session_id: string;
+    signed_in: boolean;
+    refresh_token?: string;
+    refresh_token_expires_in?: number;
+}
+/** Ponte com o oidc-provider para os tokens Bearer de MCP (§4.3, §6). */
+export interface PoppyMcpBridge {
+    /** `url` é um servidor MCP deste app (de `apis` ou do registro de resources)? */
+    isMcpResource(url: string): boolean;
+    /**
+     * Emite o Bearer de uma Session LOGADA como access token do oidc-provider,
+     * para que a integração MCP existente (`AccessToken.find`) o aceite. `null` =
+     * sem ponte (o token fica só no store do Poppy).
+     */
+    mint?(input: {
+        grantId: string;
+        accountId: string;
+        clientId: string;
+        scope: string;
+        resource: string;
+        expiresIn: number;
+        grantExpiresAt: Date;
+    }): Promise<string | null>;
+    /** Revoga o grant (e os tokens) no oidc-provider. */
+    revoke?(grantId: string): Promise<void>;
+}
+export interface PoppyServiceDeps {
+    cfg: ResolvedPoppyConfig;
+    urls: PoppyUrls;
+    store: PoppyStore;
+    grants: DelegationStore;
+    registry: PoppyClientRegistry;
+    replay: PoppyReplayStore;
+    limiter: PoppyLimiter | null;
+    nonces: DpopNonceSource;
+    /** A conta ainda pode agir? (existe e não está desabilitada). Default: sempre. */
+    isAccountActive?: (accountId: string) => Promise<boolean>;
+    mcp?: PoppyMcpBridge;
+    now?: () => Date;
+}
+/** Entrada de uma request para {@link PoppyService.verifyAccess}. */
+export interface PoppyRequestInput {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+export interface PoppyVerifyOptions {
+    /** Scopes exigidos (todos). Faltando: `sign_in_required` (deslogado) ou `insufficient_scope`. */
+    scopes?: string[];
+    /** Exige Session logada. */
+    signedIn?: boolean;
+    /**
+     * `resource` exigido por este endpoint. Default: derivado da URL contra
+     * `apis`/`agent.protocols` do config (entradas com `resource`) e os MCP.
+     */
+    resource?: string | null;
+}
+export type PoppyAuthError = 'invalid_token' | 'sign_in_required' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce';
+export type PoppyVerifyResult = {
+    ok: true;
+    principal: PoppyPrincipalBase;
+    jkt: string | null;
+} | {
+    ok: false;
+    status: 401 | 403;
+    error: PoppyAuthError;
+    description: string;
+    scope?: string;
+    wwwAuthenticate: string;
+    /** Headers extras (`DPoP-Nonce`). */
+    headers: Record<string, string>;
+};
+/** Pedido Direct aguardando o usuário na tela de consentimento. */
+export interface PoppyConsentRequest {
+    id: string;
+    clientId: string;
+    agentName: string;
+    agentOrigin: string;
+    logoUri: string | null;
+    scopes: {
+        id: string;
+        description: string;
+    }[];
+    userCode?: string;
+}
+export type PoppyAuthorizeOutcome = {
+    kind: 'consent';
+    request: PoppyConsentRequest;
+} | {
+    kind: 'redirect';
+    url: string;
+} | {
+    kind: 'error';
+    description: string;
+};
+export interface PoppyGrantSummary {
+    id: string;
+    clientId: string;
+    scopes: {
+        id: string;
+        description: string;
+    }[];
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date;
+}
+export type PoppyMediatedResponse = ({
+    status: 'complete';
+} & PoppyTokenResponse) | {
+    status: 'code_required';
+    sign_in_id: string;
+    code: {
+        sent_to: string;
+    };
+    expires_at: string;
+} | {
+    status: 'failed';
+} | {
+    status: 'expired';
+};
+export interface PoppyBrowserSessionResult {
+    sessionId: string;
+    clientId: string;
+    userId: string;
+    accountId: string | null;
+    scopes: string[];
+    returnTo: string;
+}
+/** Estado atual de uma Session (para o cookie do site acompanhar — §5). */
+export interface PoppySessionState {
+    active: boolean;
+    sessionId: string;
+    clientId: string;
+    userId: string;
+    accountId: string | null;
+    signedIn: boolean;
+    scopes: string[];
+}
+/** Aceita o código como o usuário digitar: minúsculas, sem hífen, com espaços. */
+export declare function normalizePoppyUserCode(input: unknown): string | null;
+/** Slot global onde o `@adonis-agora/agent` registra o endpoint de conversas Poppy. */
+export declare const POPPY_ENDPOINTS_SLOT: unique symbol;
+/**
+ * `agent.protocols` vindo do slot `Symbol.for('@adonis-agora/poppy:endpoints')`
+ * (`{ conversations: 'https://…' }`), usado quando o config não declara
+ * `agent.protocols` — o mesmo padrão do slot de resources do MCP.
+ */
+export declare function registeredConversationProtocols(): {
+    type: string;
+    endpoint: string;
+    resource?: string;
+}[];
+/**
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ */
+export declare class PoppyService {
+    #private;
+    readonly cfg: ResolvedPoppyConfig;
+    readonly urls: PoppyUrls;
+    readonly registry: PoppyClientRegistry;
+    constructor(deps: PoppyServiceDeps);
+    /** Um nonce DPoP novo (header `DPoP-Nonce`), quando o app exige nonces. */
+    nonce(): string | null;
+    /** Domínios da empresa (o principal + aliases). */
+    get domains(): string[];
+    /** Descrição de um scope para o usuário. */
+    describe(ids: string[]): {
+        id: string;
+        description: string;
+    }[];
+    /** `/.well-known/poppy.json` (§3) para o domínio pedido; `null` = domínio que não é nosso. */
+    discoveryDocument(requestHost: string): Record<string, unknown> | null;
+    /** RFC 8414 com `poppy_domains` (§3.2). */
+    authorizationServerMetadata(): Record<string, unknown>;
+    /**
+     * `private_key_jwt` (RFC 7523 §2.2, §3): `client_assertion` assinada por uma
+     * chave do `jwks_uri`, `iss` = `sub` = `client_id`, `aud` = o endpoint
+     * chamado (ou o token endpoint/issuer), `exp` curto, `jti` único.
+     */
+    authenticateClient(form: Record<string, unknown>, endpoint: string): Promise<PoppyClient>;
+    /** `POST token_endpoint` (§4.2, §4.3, §4.5, §4.6, §4.8). */
+    token(form: Record<string, unknown>, dpopHeader: string | string[] | undefined): Promise<PoppyTokenResponse>;
+    /** `POST device_authorization_endpoint` (§4.6). */
+    deviceAuthorization(form: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** `POST revocation_endpoint` (§4.9, RFC 7009). */
+    revoke(form: Record<string, unknown>): Promise<void>;
+    /**
+     * Revoga um Account Token (grant): as Sessions logadas com ele continuam
+     * deslogadas (§4.9) e os Bearer de MCP no oidc-provider morrem junto.
+     */
+    revokeGrant(grantId: string): Promise<void>;
+    /**
+     * `GET authorization_endpoint` com o usuário já logado neste app. Erros no
+     * `client_id`/`redirect_uri` não redirecionam (RFC 6749 §4.1.2.1); os demais
+     * voltam ao agente com `error`, `state` e `iss`.
+     */
+    startAuthorization(params: Record<string, unknown>, accountId: string): Promise<PoppyAuthorizeOutcome>;
+    /**
+     * `POST` da tela de consentimento Direct. Devolve para onde mandar o
+     * navegador (`code`/`error`, `state`, `iss`), ou `null` quando o pedido não
+     * vale mais (expirou, decidido em outra aba, de outra conta).
+     */
+    decideAuthorization(input: {
+        requestId: string;
+        accountId: string;
+        allow: boolean;
+        scopes: string[];
+    }): Promise<{
+        url: string;
+        approved: string[] | null;
+        clientId: string;
+    } | null>;
+    pendingDevice(userCodeInput: unknown): Promise<PoppyConsentRequest | null>;
+    /** Aprova (scopes marcados) ou nega um device code. `null` = não está mais pendente. */
+    decideDevice(input: {
+        userCode: string;
+        accountId: string;
+        allow: boolean;
+        scopes: string[];
+    }): Promise<{
+        approved: string[] | null;
+        clientId: string;
+    } | null>;
+    /** `POST auth.mediated.endpoint` — já autenticado pelo Session Token (DPoP). */
+    mediatedStart(principal: PoppyPrincipalBase, jkt: string | null, body: unknown, ctx: HttpContext): Promise<PoppyMediatedResponse>;
+    /** `POST {mediated}/{sign_in_id}` com o código de uso único. */
+    mediatedCode(principal: PoppyPrincipalBase, jkt: string | null, signInId: string, body: unknown): Promise<PoppyMediatedResponse | null>;
+    /**
+     * Verifica `Authorization: DPoP|Bearer` (+ prova DPoP) de uma request a uma API
+     * ou conversa do app. Nunca lê token da URL (§4.3).
+     */
+    verifyAccess(input: PoppyRequestInput, options?: PoppyVerifyOptions): Promise<PoppyVerifyResult>;
+    /**
+     * Confere a asserção de navegador (`typ` `poppy-browser+jwt`). `requestOrigin`
+     * é a origem em que o POST chegou — o cookie precisa nascer nela.
+     */
+    verifyBrowserAssertion(assertion: unknown, requestOrigin: string): Promise<PoppyBrowserSessionResult>;
+    /** Estado atual da Session (ativa? logada? scopes) — o cookie do site segue isto. */
+    sessionState(sessionId: string): Promise<PoppySessionState | null>;
+    listGrants(accountId: string): Promise<PoppyGrantSummary[]>;
+    /** Desconectar o agente pela conta (§4.9): revoga um Account Token DA CONTA. */
+    revokeAccountGrant(accountId: string, grantId: string): Promise<boolean>;
+    /** Revoga todos os Account Tokens da conta (sair de tudo, conta suspensa…). */
+    revokeAllAccountGrants(accountId: string): Promise<number>;
+    /**
+     * Bloqueio pelo console admin: revoga todos os Account Tokens do agente (todas as
+     * contas) e encerra as Sessions dele — os Session Tokens param na próxima request.
+     * Devolve quantos Account Tokens estavam vivos.
+     */
+    disconnectClient(clientId: string): Promise<number>;
+}
+export type { RequestRow };