@adonis-agora/authkit-server 0.85.1 → 0.87.0

package/README.md

@@ -17,8 +17,8 @@ wrapper around [`oidc-provider`](https://github.com/panva/node-oidc-provider).
   (JWKS, no shared secrets) and user-approved, revocable delegation with scopes you define,
   over a pluggable protocol adapter ([PACT](https://openpactprotocol.org) built in).
   Plus the [Personal Agent Protocol ("Poppy")](https://personalagentprotocol.org/docs/spec):
-  discovery, DPoP-bound agent sessions, Direct/Device/Mediated sign-in, MCP and browser sessions.
-  ⚠️ **Experimental** — tracks the spec's Draft 0.1 and will change (possibly breaking, outside
+  discovery, signed `Poppy-Session` agent sessions, Direct/Device/Mediated sign-in, MCP and browser sessions.
+  ⚠️ **Experimental** — tracks the spec's Draft 0.3 and will change (possibly breaking, outside
   semver majors) while the spec is a draft.
 - **Native apps** — RFC 8252 native clients (`authkit:clients:create --native`: private-use
   scheme / claimed https / loopback redirects, always public + PKCE) and the `@adonisjs/auth`

package/build/index.d.ts

@@ -16,8 +16,7 @@ export type { PersonalAgentDelegationConfigInput, PersonalAgentRegistration, Per
 export type { DelegationContext, DelegationGrantSummary, DelegationReceipt, } from './src/agents/delegation_service.js';
 export type { PersonalAgentAuthOptions, PersonalAgentRequestContext, } from './src/agents/middleware.js';
 export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgentSecurity, personalAgentStepUp, } from './src/agents/middleware.js';
-export type { PoppyAgentProtocolEntry, PoppyApiEntry, PoppyBrowserLogin, PoppyClientsConfigInput, PoppyConfigInput, PoppyLimiter, PoppyMediatedConfigInput, PoppyMediatedField, PoppyMediatedResult, PoppyMediatedVerifyInput, PoppyPrincipalBase, PoppyReplayStore, ResolvedPoppyConfig, } from './src/agents/poppy/config.js';
-export { POPPY_READ, POPPY_WRITE } from './src/agents/poppy/config.js';
+export type { PoppyAgentProtocolEntry, PoppyApiEntry, PoppyBrowserLogin, PoppyClientsConfigInput, PoppyConfigInput, PoppyLimiter, PoppyMediatedConfigInput, PoppyMediatedField, PoppyMediatedResult, PoppyMediatedVerifyInput, PoppyPrincipalBase, PoppyReplayStore, PoppyScopeHint, ResolvedPoppyConfig, } from './src/agents/poppy/config.js';
 export { accessTokenHash, type DpopNonceSource, type DpopResult, hmacNonceSource, type VerifyDpopInput, verifyDpopProof, } from './src/agents/poppy/dpop.js';
 export { maskEmail, type PoppyEmailCodeSignInOptions, poppyEmailCodeSignIn, } from './src/agents/poppy/email_code_sign_in.js';
 export { PoppyError, type PoppyErrorCode } from './src/agents/poppy/errors.js';

package/build/index.js

@@ -9,7 +9,6 @@ export { AuthOrganization, AuthOrganizationInvitation, AuthOrganizationMember, d
 export { lucidStores } from './src/accounts/lucid_stores.js';
 export { PersonalAgentVerifier } from './src/agents/agent_identity.js';
 export { personalAgentAuth, personalAgentOf, personalAgentReceipt, personalAgentSecurity, personalAgentStepUp, } from './src/agents/middleware.js';
-export { POPPY_READ, POPPY_WRITE } from './src/agents/poppy/config.js';
 export { accessTokenHash, hmacNonceSource, verifyDpopProof, } from './src/agents/poppy/dpop.js';
 export { maskEmail, poppyEmailCodeSignIn, } from './src/agents/poppy/email_code_sign_in.js';
 export { PoppyError } from './src/agents/poppy/errors.js';

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

@@ -83,7 +83,7 @@ export interface PersonalAgentsConfigInput {
      * segundo protocolo, ao lado do PACT. Um app pode servir os dois. Ver
      * `poppy/config.ts`.
      *
-     * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+     * @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.
      */
     poppy?: PoppyConfigInput;

package/build/src/agents/delegation_service.js

@@ -31,7 +31,7 @@ function newUserCode() {
     return `${code.slice(0, 4)}-${code.slice(4)}`;
 }
 /**
- * A tabela de grants é compartilhada com o Poppy (Account Tokens, `pgrant_`):
+ * A tabela de grants é compartilhada com o Poppy (refresh tokens, `pgrant_`):
  * o PACT só enxerga os dele.
  */
 function isPactGrant(id) {

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

@@ -18,6 +18,11 @@ export interface PoppyClient {
     /** Chaves públicas do `jwks_uri`. */
     keys: JWTVerifyGetKey;
 }
+/**
+ * `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 declare function redirectUriAllowed(registered: string[], redirectUri: string): boolean;
 /** Valida um documento de metadata e devolve os campos usados. Lança `invalid_client`. */
 export declare function validateClientMetadata(fetchedFrom: string, doc: unknown, options?: {
     allowHttp?: boolean;

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

@@ -34,6 +34,38 @@ function isHttpsUrl(value, allowHttp = false) {
         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;
@@ -62,8 +94,10 @@ export function validateClientMetadata(fetchedFrom, doc, options = {}) {
     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');
+            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') {

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

@@ -1,33 +1,26 @@
 /**
- * @experimental Draft 0.1 da spec (https://personalagentprotocol.org/docs/spec) — pode mudar de forma
+ * @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.1 — https://personalagentprotocol.org) — config.
+ * Personal Agent Protocol ("Poppy", Draft 0.3 — https://personalagentprotocol.org) — config.
  *
- * Poppy é o segundo protocolo de personal agents ao lado do PACT. O modelo é
- * outro: em vez de um JWT do agente em cada request + um token de delegação, a
- * empresa (este app) roda um authorization server OAuth com SESSÕES — o agente
- * se identifica pelo `client_id` (uma URL HTTPS com o documento de metadata
- * dele), começa uma Session deslogada com uma asserção JWT, e o usuário entra
- * na conta por Direct (código + PKCE), Device (RFC 8628) ou Mediated Sign-In.
- * Os tokens de sessão são opacos e presos a uma chave por DPoP (RFC 9449);
- * Bearer só no MCP.
+ * 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 Account 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>`).
+ * 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';
-/** Scopes amplos definidos pelo protocolo (§4.4). */
-export declare const POPPY_READ = "poppy:read";
-export declare const POPPY_WRITE = "poppy:write";
-/** Descrições default dos scopes do protocolo — o que a tela de consentimento mostra. */
-export declare const POPPY_SCOPE_DESCRIPTIONS: Record<string, string>;
 export type PoppySignInType = 'direct' | 'device' | 'mediated';
-/** Um campo de credencial do Mediated Sign-In (§4.7). */
+/** Um campo de credencial do Mediated Sign-In (extensão Mediated Sign-In). */
 export interface PoppyMediatedField {
-    /** Chave que o agente manda em `credentials`. */
+    /** Parâmetro que o agente manda no token endpoint. */
     name: string;
     /** O que pedir ao usuário. */
     label: string;
@@ -41,27 +34,25 @@ export interface PoppyMediatedVerifyInput {
     scopes: string[];
     /** `client_id` do personal agent. */
     clientId: string;
-    /** User ID que o agente deu ao usuário (opaco). */
-    userId: string;
-    sessionId: string;
     ctx: HttpContext;
 }
 /**
  * Resultado do callback de credenciais. Nunca devolva as credenciais.
  *
- * - `complete`: credenciais certas, nada mais a fazer — a Session entra na conta.
+ * - `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, conta bloqueada…
+ * - `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 `failed` no fim). Faça o mesmo trabalho nos dois caminhos (ex.: enfileire o
+ * 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 = {
@@ -77,15 +68,17 @@ export type PoppyMediatedResult = {
     state?: unknown;
 } | {
     status: 'failed';
+} | {
+    status: 'denied';
 };
 /**
- * @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 interface PoppyMediatedConfigInput {
-    /** Campos pedidos (§4.7). Ex.: `[{ name: 'email', … }, { name: 'password', secret: true, … }]`. */
+    /** Campos pedidos (extensão Mediated Sign-In). Ex.: `[{ name: 'email', … }, { name: 'password', secret: true, … }]`. */
     fields: PoppyMediatedField[];
-    /** Scopes que o Mediated Sign-In pode conceder. Default: `['poppy:read']`. */
-    scopes?: string[];
+    /** 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>;
     /**
@@ -97,45 +90,54 @@ export interface PoppyMediatedConfigInput {
         accountId: string;
         state: unknown;
         clientId: string;
-        userId: string;
     }) => Promise<boolean>;
     /** Validade do sign-in pendente de código, em segundos. Default: 600. */
     codeTtl?: number;
-    /** Tentativas de código antes de `failed`. Default: 5. */
+    /** Tentativas de código antes de `invalid_grant`. Default: 5. */
     maxCodeAttempts?: number;
 }
-/** Uma entrada de `agent.protocols` (§3.1, §7.1). */
+/** Uma entrada de `agent.protocols` (§3.1, §8.1). */
 export interface PoppyAgentProtocolEntry {
-    /** `'poppy'` para as conversas deste protocolo (§7). */
+    /** `'poppy'` para as conversas deste protocolo (§8). */
     type: string;
     /** URL HTTPS do endpoint de conversas. */
     endpoint: string;
-    /** Exige tokens emitidos para este `resource` (§4.3). */
+    /** 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;
 }
-/** Uma entrada de `apis` (§3.1, §6). */
+/** 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;
-    /** Exige tokens emitidos para este `resource` (§4.3). MCP sempre exige o próprio `url`. */
+    /** Como em `agent.protocols`. MCP sempre exige o próprio `url` (§7). */
     resource?: string;
 }
-/** Hook de login do navegador do agente (§5) para apps com sessão de login própria. */
+/** 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 da Session quando ela está logada; `null` = Session deslogada. */
+    /** 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 (asserções, client assertions,
- * provas DPoP, asserções de navegador) até expirarem. `claim` devolve `true` na
+ * 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.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+ * @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 {
@@ -148,8 +150,8 @@ export type PoppyLimiter = (input: {
 }) => Promise<number | null>;
 export interface PoppyClientsConfigInput {
     /**
-     * `true` = só agentes registrados (`registered`) iniciam Sessions; os demais
-     * levam `invalid_client` (§4.1). Default: false — qualquer `client_id` com um
+     * `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;
@@ -159,29 +161,27 @@ export interface PoppyClientsConfigInput {
     blocked?: string[] | ((clientId: string) => boolean | Promise<boolean>);
 }
 /**
- * @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 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 (ignorando `www.`). */
+        /** 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 `poppy_domains`. */
+        /** 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 próprios do app (`custom_scopes`), `id → descrição para o usuário`.
-     * Default: os de `personalAgents.delegation.scopes`, quando houver — um
-     * catálogo só para os dois protocolos. Não podem começar com `poppy:`.
+     * 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>;
-    /** Oferece os scopes amplos `poppy:read`/`poppy:write`. Default: true. */
-    broadScopes?: boolean;
-    /** Descrições próprias para `poppy:read`/`poppy:write` na tela de consentimento. */
-    broadScopeDescriptions?: Partial<Record<'poppy:read' | 'poppy:write', 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. */
@@ -195,19 +195,29 @@ export interface PoppyConfigInput {
         /** Desligado por default: o app precisa conferir as credenciais. */
         mediated?: PoppyMediatedConfigInput;
     };
-    /** Company Agent (§7) — o endpoint de conversas é implementado pelo `@adonis-agora/agent`. */
+    /** Company Agent (§8) — o endpoint de conversas é implementado pelo `@adonis-agora/agent`. */
     agent?: {
         protocols: PoppyAgentProtocolEntry[];
     };
-    /** APIs do app que aceitam Session Tokens (§6). */
+    /** 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 (§5). Default: liga o `browser_session_endpoint`. `false` desliga. `login`
-     * substitui o login default (sessão de conta do authkit + `adonisAuth.guard`).
+     * 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, {
@@ -223,10 +233,10 @@ export interface PoppyConfigInput {
      * `NODE_ENV=production`. Default: false.
      */
     allowInsecureClientIds?: boolean;
-    /** Vida do Session Token, em segundos. Default: 3600 (a spec pede horas, não dias). */
-    sessionTokenTtl?: number;
-    /** Vida do Account Token (`refresh_token_expires_in`), em segundos. Default: 30 dias. */
-    accountTokenTtl?: number;
+    /** 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. */
@@ -235,10 +245,17 @@ export interface PoppyConfigInput {
     deviceCodeTtl?: number;
     /** Intervalo mínimo de polling do device flow, em segundos. Default: 5. */
     pollInterval?: number;
-    /** Vida máxima das asserções do agente (`exp - iat`), em segundos. Default: 300. */
+    /** Vida máxima das client assertions (`exp - iat`), em segundos. Default: 300. */
     assertionMaxLifetime?: number;
-    /** DPoP (§4.3). */
+    /** 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. */
@@ -257,7 +274,7 @@ export interface PoppyConfigInput {
     /**
      * 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, usuário).
+     * de Mediated Sign-In/hora por (agente, identificador).
      */
     rateLimit?: false | {
         sessionsPerMinute?: number;
@@ -270,24 +287,30 @@ export interface PoppyConfigInput {
      */
     toActor?: (principal: PoppyPrincipalBase) => unknown | Promise<unknown>;
 }
-/** O que um Session Token válido autoriza — sem o `actor`. *
-/** O que um Session Token válido autoriza — sem o `actor`. * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
-/** O que um Session Token válido autoriza — sem o `actor`. *   de forma incompatível fora de majors enquanto ela for draft.
-/** O que um Session Token válido autoriza — sem o `actor`. */
+/**
+ * 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;
-    /** Conta deste app quando a Session está logada; `null` deslogada. */
+    /** 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 token (`poppy:read`, `poppy:write`, próprios). Vazio deslogado. */
+    /** 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;
-    tokenType: 'DPoP' | 'Bearer';
+    /** Esquema do access token; `null` deslogado. */
+    tokenType: 'DPoP' | 'Bearer' | null;
 }
 export interface ResolvedPoppyMediatedConfig {
     fields: PoppyMediatedField[];
@@ -304,10 +327,9 @@ export interface ResolvedPoppyConfig {
         aliases: string[];
     };
     prefix: string;
-    /** Todos os scopes oferecidos, `id → descrição`. */
+    /** Os scopes oferecidos, `id → descrição`. */
     scopes: Record<string, string>;
-    /** Só os próprios do app (o `custom_scopes`). */
-    customScopes: Record<string, string>;
+    scopeHints: Record<string, PoppyScopeHint>;
     signIn: {
         direct: {
             scopes: string[];
@@ -321,9 +343,16 @@ export interface ResolvedPoppyConfig {
         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;
@@ -338,14 +367,18 @@ export interface ResolvedPoppyConfig {
     };
     /** Dev/teste: `client_id` http e busca sem guarda de SSRF (ver o input). */
     allowInsecureClientIds: boolean;
-    sessionTokenTtl: number;
-    accountTokenTtl: number;
+    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[];
@@ -359,7 +392,5 @@ export interface ResolvedPoppyConfig {
     } | PoppyLimiter;
     toActor?: PoppyConfigInput['toActor'];
 }
-/** `www.example.com` → `example.com`, minúsculo. */
-export declare function stripWww(host: string): string;
 export declare function normalizePoppyPrefix(prefix: string | undefined): string;
 export declare function resolvePoppyConfig(input: PoppyConfigInput | undefined, fallbackScopes: Record<string, string> | undefined): ResolvedPoppyConfig | undefined;