@adonis-agora/authkit-server 1.0.0-rc.1 → 1.0.0-rc.10

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

@@ -1,293 +0,0 @@
-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 DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
-export declare const MEDIATED_SIGN_IN_GRANT = "https://personalagentprotocol.org/grant/mediated-sign-in";
-export declare const MEDIATED_SIGN_IN_EXTENSION = "mediated-sign-in";
-export declare const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
-export declare const POPPY_PROTOCOL_VERSION = "0.3";
-/** 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;
-    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.7, RFC 6749 §5.1). */
-export interface PoppyTokenResponse {
-    access_token: string;
-    token_type: 'DPoP' | 'Bearer';
-    expires_in: number;
-    scope: string;
-    refresh_token?: string;
-}
-/** Ponte com o oidc-provider para os tokens Bearer de MCP (§7). */
-export interface PoppyMcpBridge {
-    /** `url` é um servidor MCP deste app (de `apis` ou do registro de resources)? */
-    isMcpResource(url: string): boolean;
-    /**
-     * Emite o Bearer de um sign-in 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). Sem access token: challenge 401; sem o scope: `insufficient_scope`. */
-    scopes?: string[];
-    /** Exige acesso à conta (um access token). */
-    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_session' | 'invalid_token' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce';
-export type PoppyVerifyResult = {
-    ok: true;
-    principal: PoppyPrincipalBase;
-    /** Grant (refresh token) do access token — `null` deslogado. */
-    grantId: string | null;
-} | {
-    ok: false;
-    status: 400 | 401 | 403 | 429;
-    /** `null`: challenge sem código (§7, falta o access token) ou limite de taxa (§5.6). */
-    error: PoppyAuthError | null;
-    description: string;
-    scope?: string;
-    /** `null` nos erros que vão no corpo (`invalid_session`) e no 429. */
-    wwwAuthenticate: string | null;
-    /** Headers extras (`DPoP-Nonce`, `Retry-After`). */
-    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;
-}
-/** O que a entrada de um navegador autorizou (§6, passo 3). */
-export interface PoppyBrowserJoin {
-    sessionId: string;
-    clientId: string;
-    userId: string;
-    /** Conta autorizada no passo 2; `null` = entrada sem access token. */
-    accountId: string | null;
-    grantId: string | null;
-    scopes: string[];
-}
-/** Estado atual de um navegador que entrou numa Session (§6, "The cookie"). */
-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;
-    access?: 'session' | 'signed_in';
-}[];
-/**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — 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;
-    }[];
-    /** `www.{domínio}` não é a empresa (§3.1): a descoberta redireciona para o domínio (§3). */
-    discoveryRedirect(requestHost: string): string | null;
-    /** `/.well-known/poppy.json` (§3) para o domínio pedido; `null` = domínio que não é nosso. */
-    discoveryDocument(requestHost: string): Record<string, unknown> | null;
-    /** `/.well-known/oauth-protected-resource` do domínio (§3.2, RFC 9728): aponta o issuer. */
-    protectedResourceMetadata(requestHost: string): Record<string, unknown> | null;
-    /** RFC 8414 com `protected_resources` (§3.2). */
-    authorizationServerMetadata(): Record<string, unknown>;
-    /**
-     * `private_key_jwt` (§4.1, RFC 7523): `client_assertion` assinada por uma chave do `jwks_uri`,
-     * `iss` = `sub` = `client_id`, `aud` = o issuer como UMA string, curta, com `iat` e `jti` únicos.
-     */
-    authenticateClient(form: Record<string, unknown>): Promise<PoppyClient>;
-    /** `POST token_endpoint` (§4.2–§4.4, §4.7, extensão Mediated Sign-In). */
-    token(form: Record<string, unknown>, dpopHeader: string | string[] | undefined, ctx?: HttpContext): Promise<PoppyTokenResponse>;
-    /** `POST device_authorization_endpoint` (§4.6). */
-    deviceAuthorization(form: Record<string, unknown>): Promise<Record<string, unknown>>;
-    /** `POST revocation_endpoint` (§4.6, RFC 7009). */
-    revoke(form: Record<string, unknown>): Promise<void>;
-    /**
-     * Revoga um refresh token (grant): os access tokens dele morrem junto (RFC 7009 §2.1), as
-     * Sessions continuam deslogadas (§5.5) e os Bearer de MCP no oidc-provider também caem.
-     */
-    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>;
-    /**
-     * Verifica uma request às APIs/conversas do app: o header `Poppy-Session` (§5.3) e, se houver, o
-     * access token (`Authorization: Bearer|DPoP`, com a prova DPoP). Um `sid` novo começa uma Session
-     * deslogada; a request é logada só quando traz access token. Nunca lê token da URL (§5.6).
-     */
-    verifyAccess(input: PoppyRequestInput, options?: PoppyVerifyOptions): Promise<PoppyVerifyResult>;
-    /** Passo 1: gera o código de uso único e o valor do cookie que o prende a este navegador. */
-    startBrowserJoin(): Promise<{
-        code: string;
-        cookie: string;
-        maxAge: number;
-    }>;
-    /**
-     * Passo 2: o agente autoriza o código, com o header da Session e, se logado, o access token.
-     * `{ ok: true }` = 204; um código inválido lança `invalid_request`.
-     */
-    authorizeBrowserJoin(input: PoppyRequestInput, code: unknown): Promise<Extract<PoppyVerifyResult, {
-        ok: false;
-    }> | {
-        ok: true;
-    }>;
-    /**
-     * Passo 3: o navegador submete o código. O primeiro envio o consome, qualquer que seja o
-     * resultado; `null` = sem cookie para a Session (página de erro).
-     */
-    completeBrowserJoin(code: unknown, cookie: unknown): Promise<PoppyBrowserJoin | null>;
-    /** O cookie age pela conta e pelos scopes do passo 2, enquanto o refresh token viver (§6). */
-    browserState(marker: {
-        sessionId: string;
-        accountId?: string | null;
-        grantId?: string | null;
-        scopes?: string[];
-    }): Promise<PoppySessionState | null>;
-    listGrants(accountId: string): Promise<PoppyGrantSummary[]>;
-    /** Desconectar o agente pela conta (§5.5): revoga um refresh token DA CONTA. */
-    revokeAccountGrant(accountId: string, grantId: string): Promise<boolean>;
-    /** Revoga todos os refresh tokens da conta (sair de tudo, conta suspensa…). */
-    revokeAllAccountGrants(accountId: string): Promise<number>;
-    /**
-     * Bloqueio pelo console admin: revoga todos os refresh tokens do agente (todas as contas) e
-     * encerra as Sessions dele — param na próxima request. Devolve quantos estavam vivos.
-     */
-    disconnectClient(clientId: string): Promise<number>;
-}
-export type { RequestRow };