@adonis-agora/authkit-server 0.86.0 → 0.87.0

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

@@ -4,10 +4,11 @@ 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 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 BROWSER_ASSERTION_TYP = "poppy-browser+jwt";
+export declare const POPPY_PROTOCOL_VERSION = "0.3";
 /** URLs públicas do authorization server Poppy. */
 export interface PoppyUrls {
     origin: string;
@@ -20,29 +21,25 @@ export interface PoppyUrls {
     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). */
+/** 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;
-    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). */
+/** 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 uma Session LOGADA como access token do oidc-provider,
+     * 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).
      */
@@ -79,9 +76,9 @@ export interface PoppyRequestInput {
     headers: Record<string, string | string[] | undefined>;
 }
 export interface PoppyVerifyOptions {
-    /** Scopes exigidos (todos). Faltando: `sign_in_required` (deslogado) ou `insufficient_scope`. */
+    /** Scopes exigidos (todos). Sem access token: challenge 401; sem o scope: `insufficient_scope`. */
     scopes?: string[];
-    /** Exige Session logada. */
+    /** Exige acesso à conta (um access token). */
     signedIn?: boolean;
     /**
      * `resource` exigido por este endpoint. Default: derivado da URL contra
@@ -89,19 +86,22 @@ export interface PoppyVerifyOptions {
      */
     resource?: string | null;
 }
-export type PoppyAuthError = 'invalid_token' | 'sign_in_required' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce';
+export type PoppyAuthError = 'invalid_session' | 'invalid_token' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce';
 export type PoppyVerifyResult = {
     ok: true;
     principal: PoppyPrincipalBase;
-    jkt: string | null;
+    /** Grant (refresh token) do access token — `null` deslogado. */
+    grantId: string | null;
 } | {
     ok: false;
-    status: 401 | 403;
-    error: PoppyAuthError;
+    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;
-    wwwAuthenticate: string;
-    /** Headers extras (`DPoP-Nonce`). */
+    /** `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. */
@@ -138,29 +138,17 @@ export interface PoppyGrantSummary {
     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 {
+/** 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[];
-    returnTo: string;
 }
-/** Estado atual de uma Session (para o cookie do site acompanhar — §5). */
+/** Estado atual de um navegador que entrou numa Session (§6, "The cookie"). */
 export interface PoppySessionState {
     active: boolean;
     sessionId: string;
@@ -182,10 +170,10 @@ export declare const POPPY_ENDPOINTS_SLOT: unique symbol;
 export declare function registeredConversationProtocols(): {
     type: string;
     endpoint: string;
-    resource?: string;
+    access?: 'session' | 'signed_in';
 }[];
 /**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
  */
 export declare class PoppyService {
     #private;
@@ -202,25 +190,28 @@ export declare class PoppyService {
         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;
-    /** RFC 8414 com `poppy_domains` (§3.2). */
+    /** `/.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` (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.
+     * `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>, 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>;
+    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.9, RFC 7009). */
+    /** `POST revocation_endpoint` (§4.6, 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.
+     * 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>;
     /**
@@ -255,31 +246,47 @@ export declare class PoppyService {
         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).
+     * 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;
+    }>;
     /**
-     * Confere a asserção de navegador (`typ` `poppy-browser+jwt`). `requestOrigin`
-     * é a origem em que o POST chegou — o cookie precisa nascer nela.
+     * 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).
      */
-    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>;
+    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 (§4.9): revoga um Account Token DA CONTA. */
+    /** Desconectar o agente pela conta (§5.5): revoga um refresh token DA CONTA. */
     revokeAccountGrant(accountId: string, grantId: string): Promise<boolean>;
-    /** Revoga todos os Account Tokens da conta (sair de tudo, conta suspensa…). */
+    /** Revoga todos os refresh 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.
+     * 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>;
 }