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

package/build/src/agents/poppy/client_registry.js

@@ -1,260 +0,0 @@
-/**
- * Identidade do personal agent no Poppy (§4.1): o `client_id` é uma URL HTTPS
- * que devolve o documento de metadata do agente (OAuth Client ID Metadata
- * Document). Buscamos (à prova de SSRF), validamos, guardamos em cache e
- * importamos as chaves públicas do `jwks_uri`.
- */
-import { createLocalJWKSet } from 'jose';
-import { PoppyError } from './errors.js';
-import { insecureDevFetchJson, SafeFetchError, safeFetchJson, } from './safe_fetch.js';
-const MIN_TTL_MS = 60 * 1000;
-const MAX_TTL_MS = 24 * 3600 * 1000;
-const DEFAULT_TTL_MS = 3600 * 1000;
-const FAILURE_TTL_MS = 60 * 1000;
-const MAX_CACHED = 1000;
-/** Releitura do JWKS quando o `kid` não está no conjunto em cache — no máximo a cada 30 s. */
-const JWKS_REFRESH_COOLDOWN_MS = 30 * 1000;
-function hostOf(url) {
-    try {
-        return new URL(url).host.toLowerCase();
-    }
-    catch {
-        return null;
-    }
-}
-function isHttpsUrl(value, allowHttp = false) {
-    if (typeof value !== 'string')
-        return false;
-    try {
-        const url = new URL(value);
-        const schemeOk = url.protocol === 'https:' || (allowHttp && url.protocol === 'http:');
-        return schemeOk && !url.username && !url.password && !url.hash;
-    }
-    catch {
-        return false;
-    }
-}
-/** Loopback redirect URI (RFC 8252 §7.3): `http`, IP de loopback literal, sem fragmento. */
-function isLoopbackRedirect(value) {
-    if (typeof value !== 'string')
-        return false;
-    try {
-        const url = new URL(value);
-        return (url.protocol === 'http:' &&
-            (url.hostname === '127.0.0.1' || url.hostname === '[::1]') &&
-            !url.username &&
-            !url.password &&
-            !url.hash);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * `redirect_uri` igual a uma entrada de `redirect_uris`; numa loopback redirect URI a porta não
- * conta (§4.2, RFC 8252 §7.3).
- */
-export function redirectUriAllowed(registered, redirectUri) {
-    if (registered.includes(redirectUri))
-        return true;
-    if (!isLoopbackRedirect(redirectUri))
-        return false;
-    const withoutPort = (value) => {
-        const url = new URL(value);
-        url.port = '';
-        return url.toString();
-    };
-    return registered.some((r) => isLoopbackRedirect(r) && withoutPort(r) === withoutPort(redirectUri));
-}
-function ttlFrom(maxAge) {
-    if (maxAge === null)
-        return DEFAULT_TTL_MS;
-    return Math.min(MAX_TTL_MS, Math.max(MIN_TTL_MS, maxAge * 1000));
-}
-function setBounded(map, key, value) {
-    map.delete(key);
-    map.set(key, value);
-    if (map.size > MAX_CACHED)
-        map.delete(map.keys().next().value);
-}
-/** Valida um documento de metadata e devolve os campos usados. Lança `invalid_client`. */
-export function validateClientMetadata(fetchedFrom, doc, options = {}) {
-    const allowHttp = options.allowHttp === true;
-    const bad = (why) => new PoppyError('invalid_client', `client metadata: ${why}`);
-    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
-        throw bad('not a JSON object');
-    const d = doc;
-    if (d.client_id !== fetchedFrom)
-        throw bad('client_id must equal the URL it was fetched from');
-    const host = hostOf(fetchedFrom);
-    if (!isHttpsUrl(d.jwks_uri, allowHttp) || hostOf(d.jwks_uri) !== host) {
-        throw bad('jwks_uri must be an HTTPS URL on the same domain as client_id');
-    }
-    const redirects = d.redirect_uris ?? [];
-    if (!Array.isArray(redirects))
-        throw bad('redirect_uris must be an array');
-    for (const uri of redirects) {
-        if (isLoopbackRedirect(uri))
-            continue;
-        if (!isHttpsUrl(uri, allowHttp) || hostOf(uri) !== host) {
-            throw bad('every redirect_uri must be an HTTPS URL on the same domain as client_id, or a loopback URI');
-        }
-    }
-    if (d.token_endpoint_auth_method !== 'private_key_jwt') {
-        throw bad('token_endpoint_auth_method must be private_key_jwt');
-    }
-    if (d.jwks !== undefined)
-        throw bad('keys are published at jwks_uri only');
-    const name = typeof d.client_name === 'string' && d.client_name.trim() ? d.client_name : host;
-    const extensions = d.extensions && typeof d.extensions === 'object' && !Array.isArray(d.extensions)
-        ? d.extensions
-        : {};
-    return {
-        clientId: fetchedFrom,
-        name: name.slice(0, 200),
-        logoUri: isHttpsUrl(d.logo_uri, allowHttp) ? d.logo_uri : null,
-        jwksUri: d.jwks_uri,
-        redirectUris: redirects,
-        extensions,
-    };
-}
-/** Só chaves públicas (§4.1) e pelo menos uma. */
-function validateJwks(doc) {
-    const keys = doc?.keys;
-    if (!Array.isArray(keys) || keys.length === 0) {
-        throw new PoppyError('invalid_client', 'jwks_uri must serve a non-empty JWK set');
-    }
-    for (const key of keys) {
-        if (!key || typeof key !== 'object')
-            throw new PoppyError('invalid_client', 'invalid JWK');
-        const k = key;
-        if ('d' in k || 'p' in k || 'q' in k || k.kty === 'oct') {
-            throw new PoppyError('invalid_client', 'jwks_uri must contain only public keys');
-        }
-    }
-    return { keys: keys };
-}
-/**
- * Resolve e valida agentes pelo `client_id`, com cache (respeita `max-age`,
- * entre 1 min e 24 h; falhas ficam 1 min em cache para que o mesmo `client_id`
- * não vire uma busca de saída por request).
- */
-export class PoppyClientRegistry {
-    #cfg;
-    #fetch;
-    #now;
-    #clients = new Map();
-    #jwks = new Map();
-    constructor(cfg, options = {}) {
-        this.#cfg = cfg;
-        this.#fetch =
-            options.fetchJson ??
-                (cfg.allowInsecureClientIds
-                    ? (url) => insecureDevFetchJson(url)
-                    : (url) => safeFetchJson(url));
-        this.#now = options.now ?? Date.now;
-    }
-    /**
-     * O agente, ou `invalid_client`: `client_id` não é HTTPS, bloqueado, não
-     * registrado (quando o app exige registro), metadata inválida/inalcançável.
-     */
-    async resolve(clientId) {
-        if (!isHttpsUrl(clientId, this.#cfg.allowInsecureClientIds)) {
-            throw new PoppyError('invalid_client', 'client_id must be an HTTPS URL');
-        }
-        if (await this.#cfg.clients.isBlocked(clientId)) {
-            throw new PoppyError('invalid_client', 'client_id is blocked');
-        }
-        if (this.#cfg.clients.requireRegistration &&
-            !(await this.#cfg.clients.isRegistered(clientId))) {
-            throw new PoppyError('invalid_client', 'client_id is not registered');
-        }
-        const meta = await this.#metadata(clientId);
-        return { ...meta, keys: this.#keySet(meta.jwksUri) };
-    }
-    /** Nome de exibição sem falhar (console de conta): metadata em cache/buscada, ou o host. */
-    async displayName(clientId) {
-        try {
-            return (await this.#metadata(clientId)).name;
-        }
-        catch {
-            return hostOf(clientId) ?? clientId;
-        }
-    }
-    #metadata(clientId) {
-        const now = this.#now();
-        const cached = this.#clients.get(clientId);
-        if (cached && cached.expiresAt > now)
-            return cached.value;
-        const entry = {
-            value: Promise.resolve(null),
-            expiresAt: now + FAILURE_TTL_MS,
-        };
-        entry.value = (async () => {
-            let fetched;
-            try {
-                fetched = await this.#fetch(clientId);
-            }
-            catch (error) {
-                const why = error instanceof SafeFetchError ? error.message : 'unreachable';
-                throw new PoppyError('invalid_client', `client metadata: ${why}`);
-            }
-            const meta = validateClientMetadata(clientId, fetched.body, {
-                allowHttp: this.#cfg.allowInsecureClientIds,
-            });
-            entry.expiresAt = this.#now() + ttlFrom(fetched.maxAge);
-            return meta;
-        })();
-        entry.value.catch(() => {
-            entry.expiresAt = this.#now() + FAILURE_TTL_MS;
-        });
-        setBounded(this.#clients, clientId, entry);
-        return entry.value;
-    }
-    #fetchJwks(jwksUri, force) {
-        const now = this.#now();
-        const cached = this.#jwks.get(jwksUri);
-        if (cached && cached.expiresAt > now && !force)
-            return cached.value;
-        if (cached && force && now - cached.fetchedAt < JWKS_REFRESH_COOLDOWN_MS)
-            return cached.value;
-        const entry = {
-            value: Promise.resolve({ keys: [] }),
-            expiresAt: now + FAILURE_TTL_MS,
-            fetchedAt: now,
-        };
-        entry.value = (async () => {
-            let fetched;
-            try {
-                fetched = await this.#fetch(jwksUri);
-            }
-            catch (error) {
-                const why = error instanceof SafeFetchError ? error.message : 'unreachable';
-                throw new PoppyError('invalid_client', `jwks_uri: ${why}`);
-            }
-            const jwks = validateJwks(fetched.body);
-            entry.expiresAt = this.#now() + ttlFrom(fetched.maxAge);
-            return jwks;
-        })();
-        entry.value.catch(() => {
-            entry.expiresAt = this.#now() + FAILURE_TTL_MS;
-        });
-        setBounded(this.#jwks, jwksUri, entry);
-        return entry.value;
-    }
-    /** `JWTVerifyGetKey` que relê o JWKS uma vez quando o `kid` é desconhecido (rotação). */
-    #keySet(jwksUri) {
-        return async (header, token) => {
-            const jwks = await this.#fetchJwks(jwksUri, false);
-            try {
-                return await createLocalJWKSet(jwks)(header, token);
-            }
-            catch (error) {
-                const refreshed = await this.#fetchJwks(jwksUri, true);
-                if (refreshed === jwks)
-                    throw error;
-                return createLocalJWKSet(refreshed)(header, token);
-            }
-        };
-    }
-}

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

@@ -1,396 +0,0 @@
-/**
- * @experimental Draft 0.3 da spec (https://personalagentprotocol.org/docs/spec) — pode mudar de forma
- *   incompatível fora de majors enquanto a spec for draft.
- *
- * Personal Agent Protocol ("Poppy", Draft 0.3 — https://personalagentprotocol.org) — config.
- *
- * Poppy é o segundo protocolo de personal agents ao lado do PACT. O agente se identifica pelo
- * `client_id` (uma URL HTTPS com o documento de metadata dele) e declara a Session em cada request
- * com o header `Poppy-Session`, um JWT assinado com uma chave delegada. O acesso à conta é OAuth
- * puro e separado: este app roda o authorization server, e o usuário entra por Direct (código +
- * PKCE), Device (RFC 8628) ou pela extensão Mediated Sign-In. Prender os access tokens com DPoP é
- * opcional (RFC 9449).
- *
- * Reaproveita o núcleo de delegação: o refresh token é um grant na tabela de grants de personal
- * agents (`auth_agent_grants`) — lista e revogação no console de conta são as mesmas do PACT — e os
- * scopes aprovados viram os `scopes` do principal (que o `@adonis-agora/agent` mapeia para roles
- * `scope:<id>`).
- */
-import type { HttpContext } from '@adonisjs/core/http';
-export type PoppySignInType = 'direct' | 'device' | 'mediated';
-/** Um campo de credencial do Mediated Sign-In (extensão Mediated Sign-In). */
-export interface PoppyMediatedField {
-    /** Parâmetro que o agente manda no token endpoint. */
-    name: string;
-    /** O que pedir ao usuário. */
-    label: string;
-    /** Valor que o agente precisa proteger (senha, PIN). */
-    secret: boolean;
-}
-/** Entrada do callback que verifica as credenciais do Mediated Sign-In. */
-export interface PoppyMediatedVerifyInput {
-    credentials: Record<string, string>;
-    /** Scopes pedidos (já validados contra os do tipo mediated). */
-    scopes: string[];
-    /** `client_id` do personal agent. */
-    clientId: string;
-    ctx: HttpContext;
-}
-/**
- * Resultado do callback de credenciais. Nunca devolva as credenciais.
- *
- * - `complete`: credenciais certas, nada mais a fazer — o agente recebe os tokens.
- * - `code_required`: o app MANDOU um código de uso único (SMS, e-mail, WhatsApp…)
- *   e o agente precisa submetê-lo. Ou devolve o `code` que mandou (a lib guarda
- *   só o hash e confere), ou deixa sem `code` e implementa `verifyCode` (ex.: um
- *   serviço de OTP que confere do lado dele). `state` é opaco e volta no
- *   `verifyCode`.
- * - `failed`: senha errada… (`invalid_grant`).
- * - `denied`: a empresa recusa este sign-in (`access_denied`).
- *
- * **Sem enumeração de contas.** Num fluxo só de identificador (e-mail/telefone + código), `failed`
- * para um identificador desconhecido conta ao agente quem tem conta. Devolva então `code_required`
- * com `accountId: null` (e o mesmo `sentTo` que uma conta real teria) e NÃO mande código: a lib
- * responde igual a uma conta real e recusa qualquer código como um código errado (mesmas
- * tentativas, mesmo `invalid_grant` no fim). Faça o mesmo trabalho nos dois caminhos (ex.: enfileire o
- * e-mail em vez de mandar na hora) para o tempo de resposta não denunciar.
- */
-export type PoppyMediatedResult = {
-    status: 'complete';
-    accountId: string;
-} | {
-    status: 'code_required';
-    /** `null` = identificador sem conta elegível: nenhum código vale (ver acima). */
-    accountId: string | null;
-    /** Texto para o usuário: "Text to the phone number ending in 71". */
-    sentTo: string;
-    code?: string;
-    state?: unknown;
-} | {
-    status: 'failed';
-} | {
-    status: 'denied';
-};
-/**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
- */
-export interface PoppyMediatedConfigInput {
-    /** Campos pedidos (extensão Mediated Sign-In). Ex.: `[{ name: 'email', … }, { name: 'password', secret: true, … }]`. */
-    fields: PoppyMediatedField[];
-    /** Scopes que o Mediated Sign-In pode conceder (`scopes` da extensão). */
-    scopes: string[];
-    /** Confere as credenciais (e, se for o caso, manda o código). */
-    verify: (input: PoppyMediatedVerifyInput) => Promise<PoppyMediatedResult>;
-    /**
-     * Confere um código quando `verify` devolveu `code_required` SEM `code`.
-     * `true` = código certo.
-     */
-    verifyCode?: (input: {
-        code: string;
-        accountId: string;
-        state: unknown;
-        clientId: string;
-    }) => Promise<boolean>;
-    /** Validade do sign-in pendente de código, em segundos. Default: 600. */
-    codeTtl?: number;
-    /** Tentativas de código antes de `invalid_grant`. Default: 5. */
-    maxCodeAttempts?: number;
-}
-/** Uma entrada de `agent.protocols` (§3.1, §8.1). */
-export interface PoppyAgentProtocolEntry {
-    /** `'poppy'` para as conversas deste protocolo (§8). */
-    type: string;
-    /** URL HTTPS do endpoint de conversas. */
-    endpoint: string;
-    /** A interface precisa da conta desde o início (§3.2). Default: `session`. */
-    access?: 'session' | 'signed_in';
-    /**
-     * Só aceita tokens emitidos para este `resource` (§4.5). Não sai no `poppy.json`: publique a
-     * protected resource metadata do serviço (RFC 9728) com este `resource`.
-     */
-    resource?: string;
-}
-/** Hints de um scope (§4.7): a ação de maior consequência que o exige. */
-export interface PoppyScopeHint {
-    changes: 'none' | 'reversible' | 'irreversible';
-    personal_data: boolean;
-}
-/** Uma entrada de `apis` (§3.1, §7). */
-export interface PoppyApiEntry {
-    type: 'openapi' | 'mcp' | (string & {});
-    url: string;
-    description: string;
-    /** Como em `agent.protocols`. MCP sempre exige o próprio `url` (§7). */
-    resource?: string;
-}
-/** Hook de login do navegador do agente (§6) para apps com sessão de login própria. */
-export type PoppyBrowserLogin = (ctx: HttpContext, input: {
-    sessionId: string;
-    clientId: string;
-    userId: string;
-    /** Conta autorizada na entrada do navegador; `null` = entrada sem access token. */
-    accountId: string | null;
-    scopes: string[];
-}) => Promise<void>;
-/**
- * Onde o protocolo guarda os `jti` já vistos (client assertions, Session JWTs,
- * provas DPoP) até expirarem. `claim` devolve `true` na
- * primeira vez que vê a chave e `false` num replay.
- *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — acompanha a spec em desenvolvimento e PODE MUDAR
- *   de forma incompatível fora de majors enquanto ela for draft.
- */
-export interface PoppyReplayStore {
-    claim(key: string, expiresAt: Date): Promise<boolean>;
-}
-/** Limitador de taxa: `null` = passa; número = segundos até tentar de novo (429). */
-export type PoppyLimiter = (input: {
-    action: 'session' | 'mediated';
-    key: string;
-}) => Promise<number | null>;
-export interface PoppyClientsConfigInput {
-    /**
-     * `true` = só agentes registrados (`registered`) são aceitos; os demais levam
-     * `invalid_client` ou `invalid_session` (§4.1). Default: false — qualquer `client_id` com um
-     * documento de metadata válido.
-     */
-    requireRegistration?: boolean;
-    /** `client_id`s registrados fora de banda (lista ou função, para quem guarda no banco). */
-    registered?: string[] | ((clientId: string) => boolean | Promise<boolean>);
-    /** `client_id`s bloqueados (revogados por mau uso). */
-    blocked?: string[] | ((clientId: string) => boolean | Promise<boolean>);
-}
-/**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
- */
-export interface PoppyConfigInput {
-    /** Nome exibido e domínio (`organization` do poppy.json). */
-    organization: {
-        name: string;
-        /** Domínio da empresa (sem esquema). O poppy.json só é servido nele; `www.` redireciona. */
-        domain: string;
-        /** Outros domínios da mesma empresa (um por país…) — também vão para `protected_resources`. */
-        aliases?: string[];
-    };
-    /** Prefixo das rotas e path do issuer. Default: `/poppy`. */
-    prefix?: string;
-    /**
-     * Scopes do app (`auth.scopes`), `id → descrição`. O protocolo não define nenhum (§4.7).
-     * Default: os de `personalAgents.delegation.scopes`, quando houver — um catálogo só para os
-     * dois protocolos.
-     */
-    scopes?: Record<string, string>;
-    /** Hints de cada scope (`auth.scope_hints`, §4.7). */
-    scopeHints?: Record<string, PoppyScopeHint>;
-    /** Tipos de sign-in. `false` desliga; um array restringe os scopes do tipo. */
-    signIn?: {
-        /** Default: todos os scopes. */
-        direct?: boolean | {
-            scopes?: string[];
-        };
-        /** Default: todos os scopes. */
-        device?: boolean | {
-            scopes?: string[];
-        };
-        /** Desligado por default: o app precisa conferir as credenciais. */
-        mediated?: PoppyMediatedConfigInput;
-    };
-    /** Company Agent (§8) — o endpoint de conversas é implementado pelo `@adonis-agora/agent`. */
-    agent?: {
-        protocols: PoppyAgentProtocolEntry[];
-    };
-    /** APIs do app que aceitam o header da Session (§7). */
-    apis?: PoppyApiEntry[];
-    /** Endpoint de feedback que o app implementa (§9.3). */
-    feedback?: {
-        endpoint: string;
-    };
-    /** Documento público das tarefas que a empresa não oferece (§9.1). */
-    excludedTasks?: {
-        url: string;
-    };
-    /**
-     * Site (§6). Default: liga o `browser_session_endpoint`. `false` desliga. `login`
-     * substitui o login default (sessão de conta do authkit + `adonisAuth.guard`). `redirectTo` é
-     * a página do site para onde o navegador vai depois de entrar (path). Default: `/`.
-     */
-    web?: false | {
-        browserSession?: boolean;
-        login?: PoppyBrowserLogin;
-        redirectTo?: string;
-    };
-    /** Extensões suportadas (§3.3), publicadas como estão. */
-    extensions?: Record<string, {
-        version: string;
-    } & Record<string, unknown>>;
-    /** Registro/allowlist/blocklist de agentes. */
-    clients?: PoppyClientsConfigInput;
-    /**
-     * SÓ DESENVOLVIMENTO/TESTE — NÃO conforme à spec. Aceita `client_id` (e o
-     * `jwks_uri`/`redirect_uris` do agente) em `http://` e busca o documento sem a
-     * proteção de SSRF (loopback e rede privada liberados), para testar com um
-     * agente local (`poppy-agent --insecure-dev`). Lança no boot com
-     * `NODE_ENV=production`. Default: false.
-     */
-    allowInsecureClientIds?: boolean;
-    /** Vida do access token, em segundos. Default: 3600. */
-    accessTokenTtl?: number;
-    /** Vida do refresh token, em segundos. Default: 30 dias. */
-    refreshTokenTtl?: number;
-    /** Uma Session sem uso por este tempo termina (`invalid_session`). Default: 30 dias. */
-    sessionTtl?: number;
-    /** Vida do código de autorização (Direct), em segundos. Default: 60. */
-    authorizationCodeTtl?: number;
-    /** Validade do `device_code`, em segundos. Default: 600. */
-    deviceCodeTtl?: number;
-    /** Intervalo mínimo de polling do device flow, em segundos. Default: 5. */
-    pollInterval?: number;
-    /** Vida máxima das client assertions (`exp - iat`), em segundos. Default: 300. */
-    assertionMaxLifetime?: number;
-    /** Session JWT (§5.3). */
-    sessionJwt?: {
-        /** Janela de aceitação do `iat`, em segundos. Default: 60. */
-        maxAge?: number;
-    };
-    /** DPoP (§4.5): prender os access tokens é escolha da empresa. */
-    dpop?: {
-        /** Recusa pedidos de token sem prova: nenhum access token sai Bearer (MCP à parte). Default: false. */
-        required?: boolean;
-        /** Exige `nonce` emitido pelo servidor nas provas (RFC 9449 §8). Default: false. */
-        requireNonce?: boolean;
-        /** Janela de aceitação do `iat` da prova, em segundos. Default: 60. */
-        maxAge?: number;
-        /** Algoritmos aceitos na prova. Default: `['ES256']`. */
-        algorithms?: string[];
-    };
-    /**
-     * Onde guardar os `jti` vistos. Default: `'database'` (tabela lib-owned
-     * `auth_poppy_jtis` — vale entre instâncias). `'memory'` só serve com uma
-     * instância. `{ redis: 'main' }` usa uma conexão do `@adonisjs/redis`.
-     */
-    replay?: 'database' | 'memory' | {
-        redis: string;
-    } | PoppyReplayStore;
-    /**
-     * Limites por `client_id` (in-memory, por processo) ou um limitador próprio.
-     * `false` desliga. Default: 120 Sessions novas/min por agente; 10 tentativas
-     * de Mediated Sign-In/hora por (agente, identificador).
-     */
-    rateLimit?: false | {
-        sessionsPerMinute?: number;
-        mediatedPerHour?: number;
-    } | PoppyLimiter;
-    /**
-     * Mapeia o principal verificado para o `actor` do app (ex.: o Actor do Agora
-     * com roles `scope:<id>`). Quando definido, `verifyPoppyRequest` e o slot
-     * global devolvem `actor`.
-     */
-    toActor?: (principal: PoppyPrincipalBase) => unknown | Promise<unknown>;
-}
-/**
- * O que uma request verificada autoriza — sem o `actor`.
- *
- * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — acompanha a spec em desenvolvimento e PODE MUDAR
- *   de forma incompatível fora de majors enquanto ela for draft.
- */
-export interface PoppyPrincipalBase {
-    /** User ID que o personal agent deu ao usuário NESTE app (opaco, estável). */
-    userId: string;
-    /** Agent ID opcional (§5.1): qual dos agentes do usuário é esta Session. */
-    agentId: string | null;
-    /** Conta deste app quando a request traz access token; `null` deslogada. */
-    accountId: string | null;
-    /** `client_id` do personal agent (URL do documento de metadata). */
-    clientId: string;
-    /** Scopes do access token. Vazio deslogado. */
-    scopes: string[];
-    /** A Session, única por `client_id` + `sid`. */
-    sessionId: string;
-    signedIn: boolean;
-    /** `resource` para o qual o token foi emitido (RFC 8707), ou `null`. */
-    resource: string | null;
-    /** Esquema do access token; `null` deslogado. */
-    tokenType: 'DPoP' | 'Bearer' | null;
-}
-export interface ResolvedPoppyMediatedConfig {
-    fields: PoppyMediatedField[];
-    scopes: string[];
-    verify: PoppyMediatedConfigInput['verify'];
-    verifyCode?: PoppyMediatedConfigInput['verifyCode'];
-    codeTtl: number;
-    maxCodeAttempts: number;
-}
-export interface ResolvedPoppyConfig {
-    organization: {
-        name: string;
-        domain: string;
-        aliases: string[];
-    };
-    prefix: string;
-    /** Os scopes oferecidos, `id → descrição`. */
-    scopes: Record<string, string>;
-    scopeHints: Record<string, PoppyScopeHint>;
-    signIn: {
-        direct: {
-            scopes: string[];
-        } | null;
-        device: {
-            scopes: string[];
-        } | null;
-        mediated: ResolvedPoppyMediatedConfig | null;
-    };
-    agent: {
-        protocols: PoppyAgentProtocolEntry[];
-    } | null;
-    apis: PoppyApiEntry[];
-    feedback: {
-        endpoint: string;
-    } | null;
-    excludedTasks: {
-        url: string;
-    } | null;
-    web: {
-        browserSession: boolean;
-        login?: PoppyBrowserLogin;
-        redirectTo: string;
-    } | null;
-    extensions: Record<string, {
-        version: string;
-    } & Record<string, unknown>>;
-    clients: {
-        requireRegistration: boolean;
-        isRegistered: (clientId: string) => Promise<boolean>;
-        isBlocked: (clientId: string) => Promise<boolean>;
-        /** As listas do config quando são arrays (o console mostra); `null` = função do host. */
-        registeredList: string[] | null;
-        blockedList: string[] | null;
-    };
-    /** Dev/teste: `client_id` http e busca sem guarda de SSRF (ver o input). */
-    allowInsecureClientIds: boolean;
-    accessTokenTtl: number;
-    refreshTokenTtl: number;
-    sessionTtl: number;
-    authorizationCodeTtl: number;
-    deviceCodeTtl: number;
-    pollInterval: number;
-    assertionMaxLifetime: number;
-    sessionJwt: {
-        maxAge: number;
-    };
-    dpop: {
-        required: boolean;
-        requireNonce: boolean;
-        maxAge: number;
-        algorithms: string[];
-    };
-    replay: 'database' | 'memory' | {
-        redis: string;
-    } | PoppyReplayStore;
-    rateLimit: false | {
-        sessionsPerMinute: number;
-        mediatedPerHour: number;
-    } | PoppyLimiter;
-    toActor?: PoppyConfigInput['toActor'];
-}
-export declare function normalizePoppyPrefix(prefix: string | undefined): string;
-export declare function resolvePoppyConfig(input: PoppyConfigInput | undefined, fallbackScopes: Record<string, string> | undefined): ResolvedPoppyConfig | undefined;