@adonis-agora/authkit-server 0.77.0 → 0.79.0

package/README.md

@@ -14,6 +14,10 @@ wrapper around [`oidc-provider`](https://github.com/panva/node-oidc-provider).
 - **Personal agents** — AI assistants acting for your users: agent identity by signed JWT
   (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
+  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`
   guards `oidcRpGuard` (session) and `oidcBearerGuard` (`Authorization: Bearer` access tokens,

package/build/host/views/agents/consent.edge

@@ -8,7 +8,16 @@
     @if(request)
       <form method="POST" action="{{ action }}">
         <input type="hidden" name="_csrf" value="{{ csrfToken }}">
-        <input type="hidden" name="user_code" value="{{ request.userCode }}">
+        @if(request.hidden)
+          @each(field in request.hidden)
+            <input type="hidden" name="{{ field.name }}" value="{{ field.value }}">
+          @end
+        @else
+          <input type="hidden" name="user_code" value="{{ request.userCode }}">
+        @end
+        @if(request.logoUri)
+          <img src="{{ request.logoUri }}" alt="" class="mb-4 h-12 w-12 rounded-lg" referrerpolicy="no-referrer">
+        @end
         <h1 class="text-xl font-semibold text-gray-900">{{ t('agents.consent.title', { agent: request.agentName }) }}</h1>
         <p class="mt-2 text-sm text-gray-600">{{ t('agents.consent.body', { origin: request.agentOrigin }) }}</p>
         @if(account && account.email)
@@ -25,7 +34,9 @@
           @end
         </fieldset>
 
-        <p class="mt-4 text-xs text-gray-500">{{ t('agents.consent.code', { code: request.userCode }) }}</p>
+        @if(request.userCode)
+          <p class="mt-4 text-xs text-gray-500">{{ t('agents.consent.code', { code: request.userCode }) }}</p>
+        @end
 
         <div class="mt-6 flex gap-3">
           <button type="submit" name="decision" value="deny"

package/build/host/views/agents/done.edge

@@ -16,6 +16,9 @@
     @elseif(status === 'denied')
       <h1 class="text-xl font-semibold text-gray-900">{{ t('agents.done.denied_title') }}</h1>
       <p class="mt-2 text-sm text-gray-600">{{ t('agents.done.return') }}</p>
+    @elseif(status === 'invalid')
+      <h1 class="text-xl font-semibold text-gray-900">{{ t('agents.done.invalid_title') }}</h1>
+      <p class="mt-2 text-sm text-gray-600">{{ t('agents.done.invalid_body') }}</p>
     @else
       <h1 class="text-xl font-semibold text-gray-900">{{ t('agents.done.expired_title') }}</h1>
       <p class="mt-2 text-sm text-gray-600">{{ t('agents.done.expired_body') }}</p>

package/build/index.d.ts

@@ -16,6 +16,15 @@ 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 { accessTokenHash, type DpopNonceSource, type DpopResult, hmacNonceSource, type VerifyDpopInput, verifyDpopProof, } from './src/agents/poppy/dpop.js';
+export { PoppyError, type PoppyErrorCode } from './src/agents/poppy/errors.js';
+export { databaseReplayStore, memoryReplayStore, redisReplayStore, } from './src/agents/poppy/replay.js';
+export { installPoppySlots, POPPY_AUTHENTICATE_SLOT, type PoppyAuthenticate, type PoppyAuthResult, type PoppyPrincipal, type PoppySlotRequest, poppyAuth, poppyOf, verifyPoppyRequest, writePoppyAuthError, } from './src/agents/poppy/resource.js';
+export { isBlockedAddress, SafeFetchError, safeFetchJson, } from './src/agents/poppy/safe_fetch.js';
+export type { PoppyAuthError, PoppyGrantSummary, PoppySessionState, PoppyTokenResponse, PoppyVerifyOptions, } from './src/agents/poppy/service.js';
+export { type PoppyWebSessionMarker, poppyWebSession, poppyWebSessionOf, } from './src/agents/poppy/web_session.js';
 export type { BuiltinProtocolId, PactOptions, PersonalAgentProtocol, } from './src/agents/protocol.js';
 export { pact, pactProtocol } from './src/agents/protocol.js';
 export type { AuditEvent, AuditEventType, AuditPage, AuditSink, ListAuditParams, StoredAuditEvent, } from './src/audit/audit_sink.js';
@@ -99,6 +108,7 @@ export { OidcRpGuard, oidcRpGuard } from './src/host/oidc_rp_guard.js';
 export { evaluateLoginOtp, generateOtpCode, OTP_LOGIN_DEFAULTS, type OtpLoginConfigInput, type OtpVerifyOutcome, type ResolvedOtpLoginConfig, resolveOtpLoginConfig, } from './src/host/otp_login.js';
 export type { PersistentRpOptions } from './src/host/persistent_rp_session.js';
 export { endRpSession } from './src/host/persistent_rp_session.js';
+export { POPPY_WEB_SESSION_KEY } from './src/host/poppy_session_key.js';
 export type { AuthThrottles, ThrottleMiddleware } from './src/host/rate_limit.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 export type { AccountScreensOptions, AuthHostOptions, AuthHostRouteMap, } from './src/host/register_auth_host.js';

package/build/index.js

@@ -9,6 +9,13 @@ 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 { PoppyError } from './src/agents/poppy/errors.js';
+export { databaseReplayStore, memoryReplayStore, redisReplayStore, } from './src/agents/poppy/replay.js';
+export { installPoppySlots, POPPY_AUTHENTICATE_SLOT, poppyAuth, poppyOf, verifyPoppyRequest, writePoppyAuthError, } from './src/agents/poppy/resource.js';
+export { isBlockedAddress, SafeFetchError, safeFetchJson, } from './src/agents/poppy/safe_fetch.js';
+export { poppyWebSession, poppyWebSessionOf, } from './src/agents/poppy/web_session.js';
 export { pact, pactProtocol } from './src/agents/protocol.js';
 export { lucidAuditSink } from './src/audit/lucid_audit_sink.js';
 export { adapters, defineConfig, resolveAdmin, resolveAdminApi, resolveAuthMethodsConfig, resolveDynamicRegistration, resolveLogin, resolveNotifications, resolveOrganizations, resolvePasswordless, resolveRateLimit, resolveRegistration, resolveWebauthn, toSeconds, } from './src/define_config.js';
@@ -80,6 +87,7 @@ export { OidcRpGuard, oidcRpGuard } from './src/host/oidc_rp_guard.js';
 // Login por OTP (código digitável): config + helpers puros.
 export { evaluateLoginOtp, generateOtpCode, OTP_LOGIN_DEFAULTS, resolveOtpLoginConfig, } from './src/host/otp_login.js';
 export { endRpSession } from './src/host/persistent_rp_session.js';
+export { POPPY_WEB_SESSION_KEY } from './src/host/poppy_session_key.js';
 export { createAuthThrottles } from './src/host/rate_limit.js';
 export { registerAuthHost } from './src/host/register_auth_host.js';
 export { edgeRenderer } from './src/host/renderers/edge_renderer.js';

package/build/providers/authkit_server_provider.js

@@ -130,7 +130,14 @@ export default class AuthkitServerProvider {
             // Defaults estruturais de `config.routes` (o argumento ainda vence).
             routes: typeof config.routes === 'object' ? config.routes : undefined,
             lockedRouteOptions: config.lockedRouteOptions,
-            personalAgents: config.personalAgents ? { prefix: config.personalAgents.prefix } : undefined,
+            personalAgents: config.personalAgents
+                ? {
+                    prefix: config.personalAgents.prefix,
+                    ...(config.personalAgents.poppy
+                        ? { poppyPrefix: config.personalAgents.poppy.prefix }
+                        : {}),
+                }
+                : undefined,
             // API headless — repassa pro registerAuthHost montar as rotas.
             headless: config.headless
                 ? {
@@ -139,6 +146,13 @@ export default class AuthkitServerProvider {
                 }
                 : undefined,
         });
+        // Poppy: o slot global que o `@adonis-agora/agent` usa para autenticar o endpoint de
+        // conversas (e o MCP) sem importar este pacote — o contrato é o símbolo.
+        if (config.personalAgents?.poppy) {
+            const { installPoppySlots } = await import('../src/agents/poppy/resource.js');
+            const { poppyUrls } = await import('../src/agents/poppy/service.js');
+            installPoppySlots(poppyUrls(config.issuer, config.personalAgents.poppy.prefix).issuer);
+        }
         // Auto-montagem das rotas (`config.routes`). Chama a MESMA função exportada que o
         // `start/routes.ts` chamaria; não há segunda implementação. "As rotas não subiram" não pode
         // degradar em silêncio: uma falha aqui propaga.

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

@@ -12,6 +12,7 @@
  * recibos) não depende de protocolo; o formato do fio vem do adapter em
  * `protocol` (default: PACT — https://openpactprotocol.org). Ver `protocol.ts`.
  */
+import { type PoppyConfigInput, type ResolvedPoppyConfig } from './poppy/config.js';
 import { type BuiltinProtocolId, type PersonalAgentProtocol } from './protocol.js';
 /** Registro de um personal agent conhecido (PACT §3.1). */
 export interface PersonalAgentRegistration {
@@ -55,10 +56,12 @@ export interface PersonalAgentsConfigInput {
      */
     protocol?: BuiltinProtocolId | PersonalAgentProtocol;
     /**
-     * Valor que os personal agents põem no `aud` do JWT deles. Opaco e atribuído
-     * por ESTE app no registro do agente — um valor por app, não derivado de URL.
+     * Valor que os personal agents põem no `aud` do JWT deles (PACT). Opaco e
+     * atribuído por ESTE app no registro do agente — um valor por app, não
+     * derivado de URL. Liga o PACT; obrigatório, a não ser num app só-Poppy
+     * (`poppy` sem `audience`).
      */
-    audience: string;
+    audience?: string;
     /**
      * Agentes aceitos: uma lista estática, ou uma função que resolve pelo `iss`
      * (para quem guarda o registro no banco). Default: nenhum.
@@ -75,6 +78,15 @@ export interface PersonalAgentsConfigInput {
     delegation?: PersonalAgentDelegationConfigInput;
     /** Prefixo das rotas (`{prefix}/oauth/*`, `{prefix}/consent`). Default: `/agents`. */
     prefix?: string;
+    /**
+     * Personal Agent Protocol ("Poppy", https://personalagentprotocol.org) — o
+     * 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
+     *   de forma incompatível fora de majors enquanto ela for draft.
+     */
+    poppy?: PoppyConfigInput;
 }
 export interface ResolvedPersonalAgentDelegationConfig {
     interfaceUrl: string;
@@ -85,12 +97,19 @@ export interface ResolvedPersonalAgentDelegationConfig {
     pollInterval: number;
 }
 export interface ResolvedPersonalAgentsConfig {
+    /** PACT ligado (`audience` configurado). */
+    pact: boolean;
     protocol: PersonalAgentProtocol;
+    /** `''` quando o PACT está desligado. */
     audience: string;
     resolveAgent: PersonalAgentResolver;
+    /** A lista `agents` do config quando é um array (o console mostra); `null` = resolver do host. */
+    staticAgents: PersonalAgentRegistration[] | null;
     open: boolean;
     delegation?: ResolvedPersonalAgentDelegationConfig;
     prefix: string;
+    /** Poppy resolvido (undefined = desligado). */
+    poppy?: ResolvedPoppyConfig;
 }
 export declare function normalizePersonalAgentsPrefix(prefix: string | undefined): string;
 export declare function resolvePersonalAgentsConfig(input: PersonalAgentsConfigInput | undefined): ResolvedPersonalAgentsConfig | undefined;

package/build/src/agents/config.js

@@ -12,6 +12,7 @@
  * recibos) não depende de protocolo; o formato do fio vem do adapter em
  * `protocol` (default: PACT — https://openpactprotocol.org). Ver `protocol.ts`.
  */
+import { resolvePoppyConfig, } from './poppy/config.js';
 import { BUILTIN_PROTOCOLS, } from './protocol.js';
 const SCOPE_ID = /^[\x21\x23-\x5B\x5D-\x7E]+$/; // RFC 6749 §3.3 scope-token
 function assertUrl(value, what) {
@@ -39,14 +40,23 @@ export function normalizePersonalAgentsPrefix(prefix) {
 export function resolvePersonalAgentsConfig(input) {
     if (!input)
         return undefined;
-    if (!input.audience?.trim()) {
-        throw new Error('authkit: personalAgents.audience é obrigatório (o `aud` dos JWTs dos agentes).');
+    const pact = !!input.audience?.trim();
+    if (!pact && !input.poppy) {
+        throw new Error('authkit: personalAgents.audience é obrigatório (o `aud` dos JWTs dos agentes PACT) — ou configure só `personalAgents.poppy`.');
+    }
+    if (!pact && input.delegation) {
+        throw new Error('authkit: personalAgents.delegation é do PACT e exige `personalAgents.audience`.');
+    }
+    if (input.protocol === 'poppy') {
+        throw new Error('authkit: o Poppy não é um `protocol` do PACT — configure-o em `personalAgents.poppy` (os dois convivem).');
     }
     let resolveAgent;
+    let staticAgents = null;
     if (typeof input.agents === 'function') {
         resolveAgent = input.agents;
     }
     else {
+        staticAgents = [...(input.agents ?? [])];
         const byIssuer = new Map();
         for (const agent of input.agents ?? []) {
             assertUrl(agent.issuer, `agents[].issuer`);
@@ -83,13 +93,21 @@ export function resolvePersonalAgentsConfig(input) {
     if (!protocol) {
         throw new Error(`authkit: personalAgents.protocol "${String(input.protocol)}" desconhecido (embutidos: ${Object.keys(BUILTIN_PROTOCOLS).join(', ')}).`);
     }
+    const prefix = normalizePersonalAgentsPrefix(input.prefix);
+    const poppy = resolvePoppyConfig(input.poppy, input.delegation?.scopes);
+    if (poppy && pact && (poppy.prefix === prefix || poppy.prefix.startsWith(`${prefix}/`))) {
+        throw new Error(`authkit: personalAgents.poppy.prefix "${poppy.prefix}" não pode ficar debaixo de personalAgents.prefix ("${prefix}").`);
+    }
     return {
+        pact,
         protocol,
-        audience: input.audience,
+        audience: pact ? input.audience : '',
         resolveAgent,
+        staticAgents,
         open: input.open === true,
         delegation,
-        prefix: normalizePersonalAgentsPrefix(input.prefix),
+        prefix,
+        poppy,
     };
 }
 /** `"a b  c"` → `['a','b','c']` sem duplicatas, na ordem. */

package/build/src/agents/delegation_service.js

@@ -30,6 +30,13 @@ function newUserCode() {
         code += USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)];
     return `${code.slice(0, 4)}-${code.slice(4)}`;
 }
+/**
+ * A tabela de grants é compartilhada com o Poppy (Account Tokens, `pgrant_`):
+ * o PACT só enxerga os dele.
+ */
+function isPactGrant(id) {
+    return !id.startsWith('pgrant_');
+}
 /** Aceita o código como o usuário digitar: minúsculas, sem hífen, com espaços. */
 export function normalizeUserCode(input) {
     if (typeof input !== 'string')
@@ -183,7 +190,7 @@ export class PersonalAgentDelegation {
         if (!userCode)
             return null;
         const row = await this.#store.findDeviceByUserCode(userCode);
-        if (!row || row.status !== 'pending' || row.expiresAt <= this.#now())
+        if (row?.status !== 'pending' || row.expiresAt <= this.#now())
             return null;
         return {
             userCode: row.userCode,
@@ -201,7 +208,7 @@ export class PersonalAgentDelegation {
         const userCode = normalizeUserCode(input.userCode);
         const row = userCode ? await this.#store.findDeviceByUserCode(userCode) : null;
         const now = this.#now();
-        if (!row || row.status !== 'pending' || row.expiresAt <= now)
+        if (row?.status !== 'pending' || row.expiresAt <= now)
             return null;
         const requested = parseScope(row.requestedScope);
         const granted = requested.filter((id) => input.scopes.includes(id));
@@ -217,7 +224,7 @@ export class PersonalAgentDelegation {
             return null;
         const expiresAt = new Date(now.getTime() + this.#cfg.grantTtl * 1000);
         const existing = (await this.#store.findGrantsFor(input.accountId, row.clientId, row.agentSub))
-            .filter((g) => g.expiresAt > now)
+            .filter((g) => isPactGrant(g.id) && g.expiresAt > now)
             .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime())[0];
         let result = null;
         if (existing) {
@@ -248,7 +255,7 @@ export class PersonalAgentDelegation {
     async deny(input) {
         const userCode = normalizeUserCode(input.userCode);
         const row = userCode ? await this.#store.findDeviceByUserCode(userCode) : null;
-        if (!row || row.status !== 'pending')
+        if (row?.status !== 'pending')
             return false;
         return this.#store.transitionDevice(row.id, 'pending', {
             status: 'denied',
@@ -259,7 +266,7 @@ export class PersonalAgentDelegation {
     async listGrants(accountId) {
         const now = this.#now();
         return (await this.#store.listGrants(accountId))
-            .filter((g) => g.expiresAt > now)
+            .filter((g) => isPactGrant(g.id) && g.expiresAt > now)
             .map((g) => ({
             id: g.id,
             clientId: g.clientId,
@@ -270,7 +277,9 @@ export class PersonalAgentDelegation {
         }));
     }
     /** Revoga na hora: tokens já emitidos param de valer na próxima request. */
-    revokeGrant(accountId, grantId) {
+    async revokeGrant(accountId, grantId) {
+        if (!isPactGrant(grantId))
+            return false;
         return this.#store.revokeGrant(accountId, grantId, this.#now());
     }
     /** Revoga TODAS as delegações da conta. Devolve quantas estavam vivas. */
@@ -340,7 +349,7 @@ export class PersonalAgentDelegation {
      */
     async #converge(accountId, clientId, agentSub, now) {
         const live = (await this.#store.findGrantsFor(accountId, clientId, agentSub))
-            .filter((g) => g.expiresAt > now)
+            .filter((g) => isPactGrant(g.id) && g.expiresAt > now)
             .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
         const [survivor, ...extras] = live;
         if (!survivor)
@@ -355,7 +364,8 @@ export class PersonalAgentDelegation {
         return { grantId: survivor.id, scopes: parseScope(scope) };
     }
     async #grantUsable(grant, agent, now) {
-        return (grant.revokedAt === null &&
+        return (isPactGrant(grant.id) &&
+            grant.revokedAt === null &&
             grant.expiresAt > now &&
             grant.clientId === agent.issuer &&
             grant.agentSub === agent.sub &&

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

@@ -37,7 +37,13 @@ export interface GrantRow {
     createdAt: Date;
     updatedAt: Date;
 }
+export interface LiveGrantFilter {
+    protocol?: 'pact' | 'poppy';
+    clientId?: string;
+    accountId?: string;
+}
 export declare class DelegationStore {
+    #private;
     private conn;
     /** `conn` = uma conexão Lucid (`db.connection(name?)`) — ou uma transação. */
     constructor(conn: () => any);
@@ -75,6 +81,16 @@ export declare class DelegationStore {
     /** Revoga um grant DA CONTA. `false` = não existe, é de outra conta ou já revogado. */
     revokeGrant(accountId: string, id: string, at: Date): Promise<boolean>;
     revokeAllGrants(accountId: string, at: Date): Promise<number>;
+    listLiveGrants(input: LiveGrantFilter & {
+        now: Date;
+        offset: number;
+        limit: number;
+    }): Promise<GrantRow[]>;
+    countLiveGrants(now: Date, filter?: LiveGrantFilter): Promise<number>;
+    /** Conexões vivas de um protocolo por agente: `client_id` → número de grants. */
+    countLiveGrantsByClient(now: Date, protocol: 'pact' | 'poppy'): Promise<Map<string, number>>;
+    /** Ids dos grants não revogados de um agente (vivos ou não) — para revogar todos. */
+    unrevokedGrantIdsOfClient(clientId: string): Promise<string[]>;
     /** Revoga um grant sem checar a conta — reação a reuso de refresh token. */
     revokeGrantById(id: string, at: Date): Promise<void>;
     insertRefreshToken(row: {

package/build/src/agents/delegation_store.js

@@ -183,6 +183,50 @@ export class DelegationStore {
             .update({ revoked_at: at, updated_at: at });
         return affected(result);
     }
+    // ─── console admin (todas as contas) ──────────────────────────────────────
+    /**
+     * Grants vivos (não revogados nem expirados em `now`), de todas as contas. O
+     * protocolo sai do prefixo do id: `agrant_` (PACT) ou `pgrant_` (Poppy).
+     */
+    #live(now, filter = {}) {
+        let q = this.conn().from(GRANT_TABLE).whereNull('revoked_at').where('expires_at', '>', now);
+        if (filter.protocol)
+            q = q.where('id', 'like', filter.protocol === 'poppy' ? 'pgrant_%' : 'agrant_%');
+        if (filter.clientId)
+            q = q.where('client_id', filter.clientId);
+        if (filter.accountId)
+            q = q.where('account_id', filter.accountId);
+        return q;
+    }
+    async listLiveGrants(input) {
+        const rows = await this.#live(input.now, input)
+            .orderBy('created_at', 'desc')
+            .orderBy('id', 'asc')
+            .offset(input.offset)
+            .limit(input.limit);
+        return rows.map(toGrant);
+    }
+    async countLiveGrants(now, filter = {}) {
+        const row = await this.#live(now, filter).count('* as total').first();
+        return Number(row?.total ?? 0);
+    }
+    /** Conexões vivas de um protocolo por agente: `client_id` → número de grants. */
+    async countLiveGrantsByClient(now, protocol) {
+        const rows = await this.#live(now, { protocol })
+            .select('client_id')
+            .count('* as total')
+            .groupBy('client_id');
+        return new Map(rows.map((r) => [r.client_id, Number(r.total)]));
+    }
+    /** Ids dos grants não revogados de um agente (vivos ou não) — para revogar todos. */
+    async unrevokedGrantIdsOfClient(clientId) {
+        const rows = await this.conn()
+            .from(GRANT_TABLE)
+            .where('client_id', clientId)
+            .whereNull('revoked_at')
+            .select('id');
+        return rows.map((r) => r.id);
+    }
     /** Revoga um grant sem checar a conta — reação a reuso de refresh token. */
     async revokeGrantById(id, at) {
         await this.conn()

package/build/src/agents/middleware.js

@@ -40,7 +40,8 @@ export function personalAgentAuth(options = {}) {
     const mode = options.delegation ?? 'optional';
     return async (ctx, next) => {
         const runtime = await personalAgentsFor(ctx);
-        if (!runtime)
+        // Sem PACT (app só-Poppy) não há JWT de agente para verificar.
+        if (!runtime?.config.pact)
             return ctx.response.notFound();
         const { protocol } = runtime.config;
         // Autentica ANTES de ler o corpo (PACT §3.4).

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

@@ -0,0 +1,45 @@
+/**
+ * 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 { type JWTVerifyGetKey } from 'jose';
+import type { ResolvedPoppyConfig } from './config.js';
+import { type JsonFetcher } from './safe_fetch.js';
+export interface PoppyClient {
+    clientId: string;
+    /** `client_name`, ou o host do `client_id`. */
+    name: string;
+    logoUri: string | null;
+    jwksUri: string;
+    redirectUris: string[];
+    extensions: Record<string, unknown>;
+    /** Chaves públicas do `jwks_uri`. */
+    keys: JWTVerifyGetKey;
+}
+/** 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;
+}): Omit<PoppyClient, 'keys'>;
+export interface PoppyClientRegistryOptions {
+    /** Busca de JSON. Default: {@link safeFetchJson}. */
+    fetchJson?: JsonFetcher;
+    now?: () => number;
+}
+/**
+ * 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 declare class PoppyClientRegistry {
+    #private;
+    constructor(cfg: ResolvedPoppyConfig, options?: PoppyClientRegistryOptions);
+    /**
+     * O agente, ou `invalid_client`: `client_id` não é HTTPS, bloqueado, não
+     * registrado (quando o app exige registro), metadata inválida/inalcançável.
+     */
+    resolve(clientId: unknown): Promise<PoppyClient>;
+    /** Nome de exibição sem falhar (console de conta): metadata em cache/buscada, ou o host. */
+    displayName(clientId: string): Promise<string>;
+}