@adonis-agora/authkit-server 0.77.0 → 0.78.0

package/build/src/agents/runtime.js

@@ -1,7 +1,13 @@
 import { supportsAccountStatus } from '../accounts/account_store.js';
+import { findMcpResource } from '../mcp/mcp_oauth.js';
 import { PersonalAgentVerifier } from './agent_identity.js';
 import { PersonalAgentDelegation } from './delegation_service.js';
 import { DelegationStore } from './delegation_store.js';
+import { PoppyClientRegistry } from './poppy/client_registry.js';
+import { hmacNonceSource } from './poppy/dpop.js';
+import { databaseReplayStore, memoryLimiter, memoryReplayStore, redisReplayStore, } from './poppy/replay.js';
+import { PoppyService, poppyUrls } from './poppy/service.js';
+import { PoppyStore } from './poppy/store.js';
 import { keystoreSigner } from './signer.js';
 /**
  * Deriva as URLs da ORIGEM do issuer configurado — nunca do Host da request
@@ -20,11 +26,77 @@ export function personalAgentUrls(oidcIssuer, prefix) {
     };
 }
 const runtimes = new WeakMap();
+/** Ponte Poppy → oidc-provider: Bearer de MCP de Sessions logadas viram access tokens dele. */
+function mcpBridge(service, poppyApis) {
+    return {
+        isMcpResource(url) {
+            try {
+                return findMcpResource(url, service.config.issuer, service.config.mcp) !== null;
+            }
+            catch {
+                return false;
+            }
+        },
+        async mint(input) {
+            const provider = service.provider;
+            if (!provider?.AccessToken || !provider?.Grant)
+                return null;
+            // Só faz sentido quando a integração MCP do authkit está ligada, ou o MCP é de `apis`.
+            if (!service.config.mcp?.enabled &&
+                !poppyApis.some((a) => a.type === 'mcp' && a.url.replace(/\/+$/, '') === input.resource.replace(/\/+$/, ''))) {
+                return null;
+            }
+            const remaining = Math.max(60, Math.floor((input.grantExpiresAt.getTime() - Date.now()) / 1000));
+            let grant = await provider.Grant.find(input.grantId);
+            if (!grant) {
+                grant = new provider.Grant({
+                    jti: input.grantId,
+                    accountId: input.accountId,
+                    clientId: input.clientId,
+                    expiresIn: remaining,
+                });
+                await grant.save();
+            }
+            const at = new provider.AccessToken({
+                accountId: input.accountId,
+                clientId: input.clientId,
+                grantId: input.grantId,
+                scope: input.scope,
+                gty: 'poppy',
+                expiresIn: input.expiresIn,
+            });
+            at.aud = input.resource;
+            return at.save();
+        },
+        async revoke(grantId) {
+            const provider = service.provider;
+            if (!provider?.Grant)
+                return;
+            await provider.AccessToken?.revokeByGrantId?.(grantId);
+            const grant = await provider.Grant.find(grantId);
+            if (grant)
+                await grant.destroy();
+        },
+    };
+}
+async function resolveReplay(replay, conn, make) {
+    if (replay === 'memory')
+        return memoryReplayStore();
+    if (replay === 'database')
+        return databaseReplayStore(conn);
+    if (typeof replay.claim === 'function')
+        return replay;
+    const name = replay.redis;
+    if (!make)
+        throw new Error('authkit: personalAgents.poppy.replay { redis } exige o container.');
+    const redis = await make('redis');
+    return redisReplayStore(redis.connection(name));
+}
 /**
  * Monta (uma vez por `OidcService`) o runtime de personal agents. `null` quando
  * `personalAgents` não está no config — as rotas respondem 404.
  */
-export function buildPersonalAgentsRuntime(service, makeDb) {
+export function buildPersonalAgentsRuntime(service, makeDb, options = {}) {
     let runtime = runtimes.get(service);
     if (!runtime) {
         runtime = (async () => {
@@ -32,25 +104,76 @@ export function buildPersonalAgentsRuntime(service, makeDb) {
             if (!config)
                 return null;
             const urls = personalAgentUrls(service.config.issuer, config.prefix);
-            let delegation = null;
-            if (config.delegation) {
+            // Conta apagada ou suspensa corta a delegação na hora.
+            const isAccountActive = async (accountId) => {
+                const store = service.config.accountStore;
+                if (!(await store.findById(accountId)))
+                    return false;
+                return !(supportsAccountStatus(store) && (await store.isDisabled(accountId)));
+            };
+            let conn = null;
+            if (config.delegation || config.poppy) {
                 const db = await makeDb();
                 const connection = service.config.schema.connection;
+                conn = () => (connection ? db.connection(connection) : db.connection());
+            }
+            const store = conn ? new DelegationStore(conn) : null;
+            let delegation = null;
+            if (config.delegation && store) {
                 delegation = new PersonalAgentDelegation({
                     cfg: config.delegation,
-                    store: new DelegationStore(() => connection ? db.connection(connection) : db.connection()),
+                    store,
                     signer: keystoreSigner(service),
                     urls: { issuer: urls.issuer, consent: urls.consent },
-                    // Conta apagada ou suspensa corta a delegação na hora.
-                    isAccountActive: async (accountId) => {
-                        const store = service.config.accountStore;
-                        if (!(await store.findById(accountId)))
-                            return false;
-                        return !(supportsAccountStatus(store) && (await store.isDisabled(accountId)));
-                    },
+                    isAccountActive,
+                });
+            }
+            let poppy = null;
+            if (config.poppy && store && conn) {
+                const cfg = config.poppy;
+                const limiter = cfg.rateLimit === false
+                    ? null
+                    : typeof cfg.rateLimit === 'function'
+                        ? cfg.rateLimit
+                        : memoryLimiter(cfg.rateLimit);
+                const secret = service.deriveSecret('poppy-dpop-nonce');
+                poppy = new PoppyService({
+                    cfg,
+                    urls: poppyUrls(service.config.issuer, cfg.prefix),
+                    store: new PoppyStore(conn),
+                    grants: store,
+                    registry: new PoppyClientRegistry(cfg, { fetchJson: options.fetchJson }),
+                    replay: await resolveReplay(cfg.replay, conn, options.make),
+                    limiter,
+                    nonces: hmacNonceSource(secret),
+                    isAccountActive,
+                    mcp: mcpBridge(service, cfg.apis),
+                    now: options.now,
                 });
             }
-            return { config, urls, verifier: new PersonalAgentVerifier(config), delegation };
+            const revokeAgentGrant = async (accountId, grantId) => {
+                if (grantId.startsWith('pgrant_')) {
+                    return poppy ? poppy.revokeAccountGrant(accountId, grantId) : false;
+                }
+                return delegation ? delegation.revokeGrant(accountId, grantId) : false;
+            };
+            const revokeAllAgentGrants = async (accountId) => {
+                let count = 0;
+                if (poppy)
+                    count += await poppy.revokeAllAccountGrants(accountId);
+                if (delegation)
+                    count += await delegation.revokeAllGrants(accountId);
+                return count;
+            };
+            return {
+                config,
+                urls,
+                verifier: new PersonalAgentVerifier(config),
+                delegation,
+                poppy,
+                revokeAgentGrant,
+                revokeAllAgentGrants,
+            };
         })();
         // Falha (DB indisponível) não fica em cache — a próxima request tenta de novo.
         runtime.catch(() => runtimes.delete(service));
@@ -61,5 +184,7 @@ export function buildPersonalAgentsRuntime(service, makeDb) {
 /** Runtime a partir de uma request. */
 export async function personalAgentsFor(ctx) {
     const service = await ctx.containerResolver.make('authkit.server');
-    return buildPersonalAgentsRuntime(service, () => ctx.containerResolver.make('lucid.db'));
+    return buildPersonalAgentsRuntime(service, () => ctx.containerResolver.make('lucid.db'), {
+        make: (binding) => ctx.containerResolver.make(binding),
+    });
 }

package/build/src/define_config.js

@@ -353,6 +353,12 @@ export function defineConfig(config) {
             (personalAgents.prefix === oidcMount || personalAgents.prefix.startsWith(`${oidcMount}/`))) {
             throw new Error(`authkit: personalAgents.prefix "${personalAgents.prefix}" não pode ficar debaixo do mountPath do OIDC ("${oidcMount}").`);
         }
+        const poppyPrefix = personalAgents?.poppy?.prefix;
+        if (poppyPrefix &&
+            oidcMount &&
+            (poppyPrefix === oidcMount || poppyPrefix.startsWith(`${oidcMount}/`))) {
+            throw new Error(`authkit: personalAgents.poppy.prefix "${poppyPrefix}" não pode ficar debaixo do mountPath do OIDC ("${oidcMount}").`);
+        }
         // BACKSTOP DE SUDO. Um host cujo `sudo.methods` não tem um único método
         // satisfazível por conta sem senha fica bricado para TODA operação sob
         // `requireSudo` — e hoje isso só se descobre quando um usuário não consegue

package/build/src/host/account_api/account_api_controller.d.ts

@@ -159,7 +159,18 @@ export default class AccountApiController {
     }>;
     /** Personal agents com delegação ativa na conta (scopes aprovados). */
     listAgents(ctx: HttpContext): Promise<void | {
-        agents: import("../../agents/delegation_service.ts").DelegationGrantSummary[];
+        agents: {
+            id: string;
+            clientId: string;
+            scopes: {
+                id: string;
+                description: string;
+            }[];
+            createdAt: Date;
+            updatedAt: Date;
+            expiresAt: Date;
+            protocol: string;
+        }[];
     }>;
     /** Revoga a delegação de um personal agent (efeito imediato nos tokens). */
     revokeAgent(ctx: HttpContext): Promise<void | {

package/build/src/host/account_api/account_api_controller.js

@@ -617,20 +617,25 @@ export default class AccountApiController {
     /** Personal agents com delegação ativa na conta (scopes aprovados). */
     async listAgents(ctx) {
         const runtime = await personalAgentsFor(ctx);
-        if (!runtime?.delegation) {
+        if (!runtime?.delegation && !runtime?.poppy) {
             return ctx.response
                 .status(404)
                 .send(apiErr('capability_unsupported', 'Personal agent delegation is not enabled.'));
         }
         const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
-        const grants = await runtime.delegation.listGrants(userId);
-        return { agents: grants };
+        const pact = runtime.delegation
+            ? (await runtime.delegation.listGrants(userId)).map((g) => ({ ...g, protocol: 'pact' }))
+            : [];
+        const poppy = runtime.poppy
+            ? (await runtime.poppy.listGrants(userId)).map((g) => ({ ...g, protocol: 'poppy' }))
+            : [];
+        return { agents: [...pact, ...poppy] };
     }
     // ─── DELETE /account/api/agents/:id ──────────────────────────────────────
     /** Revoga a delegação de um personal agent (efeito imediato nos tokens). */
     async revokeAgent(ctx) {
         const runtime = await personalAgentsFor(ctx);
-        if (!runtime?.delegation) {
+        if (!runtime?.delegation && !runtime?.poppy) {
             return ctx.response
                 .status(404)
                 .send(apiErr('capability_unsupported', 'Personal agent delegation is not enabled.'));
@@ -638,7 +643,7 @@ export default class AccountApiController {
         const service = await ctx.containerResolver.make('authkit.server');
         const userId = ctx.session.get(ACCOUNT_SESSION_KEY);
         const grantId = ctx.request.param('id');
-        if (!(await runtime.delegation.revokeGrant(userId, grantId))) {
+        if (!(await runtime.revokeAgentGrant(userId, grantId))) {
             return ctx.response.status(404).send(apiErr('not_found', 'Grant not found.'));
         }
         await service.config.audit?.record({

package/build/src/host/admin_sessions_service.js

@@ -87,13 +87,14 @@ export class AdminSessionsService {
     /**
      * Revogação total também corta os personal agents: "sair de todas as sessões",
      * reset de senha, a ação do admin e a exclusão de conta não podem deixar um
-     * agente agindo na conta. Sem `personalAgents.delegation` é no-op — e aí nem
-     * resolve o banco. Diferente do `recordSubRevocation`, uma falha AQUI propaga:
-     * não há outra camada que corte esses tokens.
+     * agente agindo na conta (delegações do PACT e Account Tokens do Poppy). Sem
+     * `personalAgents` é no-op — e aí nem resolve o banco. Diferente do
+     * `recordSubRevocation`, uma falha AQUI propaga: não há outra camada que corte
+     * esses tokens.
      */
     async #revokeAgentGrants(accountId) {
         const runtime = await buildPersonalAgentsRuntime(this.#oidc, () => getBootedApp().container.make('lucid.db'));
-        return runtime?.delegation ? runtime.delegation.revokeAllGrants(accountId) : 0;
+        return runtime ? runtime.revokeAllAgentGrants(accountId) : 0;
     }
     /**
      * Loga (best-effort, sem nunca lançar) a falha de {@link recordSubRevocation}. Prefere o
@@ -183,7 +184,9 @@ export class AdminSessionsService {
      */
     async listGrants(accountId) {
         const rows = await this.#listModel('Grant');
-        const grants = rows.filter((r) => r.payload.accountId === accountId);
+        // Os grants `pgrant_` são o espelho de um Account Token do Poppy (Bearer de MCP) — aparecem e
+        // são revogados como personal agent, não como app OIDC.
+        const grants = rows.filter((r) => r.payload.accountId === accountId && !r.id.startsWith('pgrant_'));
         if (grants.length === 0)
             return [];
         const atByGrant = await this.#countByGrant('AccessToken');

package/build/src/host/auth_host_config.d.ts

@@ -35,9 +35,10 @@ export interface AuthHostRuntimeConfig {
      * Ver `deriveLockedRouteOptions`.
      */
     lockedRouteOptions?: PolicyRouteOption[];
-    /** Personal agents ligados → prefixo das rotas deles (`/agents`). */
+    /** Personal agents ligados → prefixo das rotas deles (`/agents`) e do Poppy (`/poppy`). */
     personalAgents?: {
         prefix: string;
+        poppyPrefix?: string;
     };
     /**
      * API headless (Clerk-style). Presente quando o host a declarou — o provider o

package/build/src/host/controllers/account_apps_controller.js

@@ -28,7 +28,7 @@ export default class AccountAppsController {
         const revoked = ctx.session.flashMessages.get('appRevoked');
         // Personal agents com delegação ativa (só quando a feature está ligada).
         const agentsRuntime = await personalAgentsFor(ctx);
-        const agents = agentsRuntime?.delegation
+        const pactAgents = agentsRuntime?.delegation
             ? await Promise.all((await agentsRuntime.delegation.listGrants(accountId)).map(async (g) => ({
                 id: g.id,
                 name: displayNameFor((await agentsRuntime.config.resolveAgent(g.clientId)) ?? {
@@ -38,6 +38,16 @@ export default class AccountAppsController {
                 scopes: g.scopes,
             })))
             : null;
+        // Account Tokens do Poppy: o agente é desconectado pela mesma lista (§4.9).
+        const poppy = agentsRuntime?.poppy;
+        const poppyAgents = poppy
+            ? await Promise.all((await poppy.listGrants(accountId)).map(async (g) => ({
+                id: g.id,
+                name: await poppy.registry.displayName(g.clientId),
+                scopes: g.scopes,
+            })))
+            : null;
+        const agents = pactAgents || poppyAgents ? [...(pactAgents ?? []), ...(poppyAgents ?? [])] : null;
         return render(ctx, 'account/apps', {
             csrfToken: ctx.request.csrfToken,
             supported,
@@ -78,13 +88,13 @@ export default class AccountAppsController {
     /** POST /account/apps/agents/:grantId/revoke — revoga a delegação de um personal agent. */
     async revokeAgent(ctx) {
         const runtime = await personalAgentsFor(ctx);
-        if (!runtime?.delegation)
+        if (!runtime?.delegation && !runtime?.poppy)
             return ctx.response.notFound();
         const service = await ctx.containerResolver.make('authkit.server');
         const cfg = service.config;
         const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
         const grantId = ctx.request.param('grantId');
-        if (await runtime.delegation.revokeGrant(accountId, grantId)) {
+        if (await runtime.revokeAgentGrant(accountId, grantId)) {
             await cfg.audit?.record({
                 type: 'agent.grant_revoked',
                 accountId,

package/build/src/host/controllers/poppy_consent_controller.d.ts

@@ -0,0 +1,19 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Telas do usuário no Poppy: o consentimento do Direct Sign-In (o
+ * `authorization_endpoint`, §4.5) e a do Device Sign-In (o `verification_uri`,
+ * §4.6). Montadas atrás do `accountGuard`: sem sessão, o usuário passa pelo login
+ * DESTE app e volta. Abrir o link nunca aprova sozinho — a aprovação é um POST
+ * com CSRF. Recusadas durante impersonation.
+ */
+export default class PoppyConsentController {
+    /** GET {prefix}/oauth/authorize */
+    authorize(ctx: HttpContext): Promise<any>;
+    /** POST {prefix}/oauth/authorize — `request_id`, `decision=allow|deny`, `scope[]`. */
+    decideAuthorization(ctx: HttpContext): Promise<any>;
+    /** GET {prefix}/device?user_code=XXXX-XXXX */
+    device(ctx: HttpContext): Promise<any>;
+    /** POST {prefix}/device — `user_code`, `decision`, `scope[]`. */
+    decideDevice(ctx: HttpContext): Promise<any>;
+}

package/build/src/host/controllers/poppy_consent_controller.js

@@ -0,0 +1,173 @@
+import '../augmentations.js';
+import { personalAgentsFor } from '../../agents/runtime.js';
+import { ACCOUNT_SESSION_KEY } from '../account_session_key.js';
+import { impersonationState } from '../impersonation_session.js';
+import { redirectExact } from '../redirect_exact.js';
+/** A tela nunca pode ser emoldurada (clickjacking — ver `agent_consent_controller.ts`). */
+function denyFraming(ctx) {
+    ctx.response.header('X-Frame-Options', 'DENY');
+    ctx.response.header('Content-Security-Policy', "frame-ancestors 'none'");
+}
+function chosenScopes(ctx) {
+    const raw = ctx.request.input('scope');
+    return (Array.isArray(raw) ? raw : raw ? [raw] : []).map(String);
+}
+/**
+ * Telas do usuário no Poppy: o consentimento do Direct Sign-In (o
+ * `authorization_endpoint`, §4.5) e a do Device Sign-In (o `verification_uri`,
+ * §4.6). Montadas atrás do `accountGuard`: sem sessão, o usuário passa pelo login
+ * DESTE app e volta. Abrir o link nunca aprova sozinho — a aprovação é um POST
+ * com CSRF. Recusadas durante impersonation.
+ */
+export default class PoppyConsentController {
+    /** GET {prefix}/oauth/authorize */
+    async authorize(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.direct)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const render = service.config.render;
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/consent', {
+                csrfToken: ctx.request.csrfToken,
+                action: poppy.urls.authorization,
+                request: null,
+                account: null,
+                error: 'agents.consent.impersonating',
+            });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const outcome = await poppy.startAuthorization(ctx.request.qs(), accountId);
+        if (outcome.kind === 'redirect')
+            return redirectExact(ctx.response, outcome.url);
+        if (outcome.kind === 'error') {
+            ctx.response.status(400);
+            return render(ctx, 'agents/done', { status: 'invalid', agentName: null, scopes: [] });
+        }
+        const account = await service.config.accountStore.findById(accountId);
+        return render(ctx, 'agents/consent', {
+            csrfToken: ctx.request.csrfToken,
+            action: poppy.urls.authorization,
+            request: {
+                agentName: outcome.request.agentName,
+                agentOrigin: outcome.request.agentOrigin,
+                logoUri: outcome.request.logoUri,
+                scopes: outcome.request.scopes,
+                hidden: [{ name: 'request_id', value: outcome.request.id }],
+            },
+            account: { email: account?.email ?? null },
+            error: null,
+        });
+    }
+    /** POST {prefix}/oauth/authorize — `request_id`, `decision=allow|deny`, `scope[]`. */
+    async decideAuthorization(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.direct)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const decided = await poppy.decideAuthorization({
+            requestId: String(ctx.request.input('request_id') ?? ''),
+            accountId,
+            allow: ctx.request.input('decision') === 'allow',
+            scopes: chosenScopes(ctx),
+        });
+        if (!decided) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        await cfg.audit?.record({
+            type: decided.approved ? 'agent.delegation_approved' : 'agent.delegation_denied',
+            accountId,
+            clientId: decided.clientId,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { protocol: 'poppy', signIn: 'direct', scopes: decided.approved ?? [] },
+        });
+        return redirectExact(ctx.response, decided.url);
+    }
+    /** GET {prefix}/device?user_code=XXXX-XXXX */
+    async device(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.device)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const render = service.config.render;
+        const base = {
+            csrfToken: ctx.request.csrfToken,
+            action: poppy.urls.device,
+            request: null,
+            account: null,
+            error: null,
+        };
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/consent', { ...base, error: 'agents.consent.impersonating' });
+        }
+        const input = ctx.request.input('user_code');
+        if (!input)
+            return render(ctx, 'agents/consent', base);
+        const pending = await poppy.pendingDevice(input);
+        if (!pending) {
+            return render(ctx, 'agents/consent', { ...base, error: 'agents.consent.invalid_code' });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const account = await service.config.accountStore.findById(accountId);
+        return render(ctx, 'agents/consent', {
+            ...base,
+            request: {
+                userCode: pending.userCode,
+                agentName: pending.agentName,
+                agentOrigin: pending.agentOrigin,
+                scopes: pending.scopes,
+            },
+            account: { email: account?.email ?? null },
+        });
+    }
+    /** POST {prefix}/device — `user_code`, `decision`, `scope[]`. */
+    async decideDevice(ctx) {
+        const runtime = await personalAgentsFor(ctx);
+        const poppy = runtime?.poppy;
+        if (!poppy?.cfg.signIn.device)
+            return ctx.response.notFound();
+        denyFraming(ctx);
+        const service = await ctx.containerResolver.make('authkit.server');
+        const cfg = service.config;
+        const render = cfg.render;
+        if (impersonationState(ctx).active) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        const accountId = ctx.session.get(ACCOUNT_SESSION_KEY);
+        const userCode = String(ctx.request.input('user_code') ?? '');
+        const pending = await poppy.pendingDevice(userCode);
+        const decided = await poppy.decideDevice({
+            userCode,
+            accountId,
+            allow: ctx.request.input('decision') === 'allow',
+            scopes: chosenScopes(ctx),
+        });
+        if (!decided || !pending) {
+            return render(ctx, 'agents/done', { status: 'expired', agentName: null, scopes: [] });
+        }
+        await cfg.audit?.record({
+            type: decided.approved ? 'agent.delegation_approved' : 'agent.delegation_denied',
+            accountId,
+            clientId: decided.clientId,
+            ip: ctx.request.ip?.() ?? null,
+            metadata: { protocol: 'poppy', signIn: 'device', scopes: decided.approved ?? [] },
+        });
+        return render(ctx, 'agents/done', {
+            status: decided.approved ? 'approved' : 'denied',
+            agentName: pending.agentName,
+            scopes: decided.approved ? poppy.describe(decided.approved) : [],
+        });
+    }
+}

package/build/src/host/controllers/poppy_controller.d.ts

@@ -0,0 +1,25 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Endpoints server-to-server do Poppy (§3, §4): descoberta, metadata RFC 8414,
+ * token, revogação, device authorization, Mediated Sign-In e a sessão de
+ * navegador (§5). Todos isentos de CSRF — ver `authkitCsrfExceptions`.
+ */
+export default class PoppyController {
+    /** `GET /.well-known/poppy.json` — só no domínio da empresa (ignorando `www.`). */
+    discovery(ctx: HttpContext): Promise<void>;
+    /** `GET /.well-known/oauth-authorization-server{prefix}` (RFC 8414 + `poppy_domains`). */
+    metadata(ctx: HttpContext): Promise<void>;
+    token(ctx: HttpContext): Promise<void>;
+    deviceAuthorization(ctx: HttpContext): Promise<void>;
+    /** RFC 7009: 200 também para token desconhecido. */
+    revoke(ctx: HttpContext): Promise<void>;
+    /** `POST auth.mediated.endpoint` (§4.7) — com o Session Token (DPoP). */
+    mediatedStart(ctx: HttpContext): Promise<void>;
+    /** `POST {mediated}/{sign_in_id}` (§4.7). */
+    mediatedCode(ctx: HttpContext): Promise<void>;
+    /**
+     * `POST web.browser_session_endpoint` (§5): asserção no corpo → cookie do app
+     * para a Session e 303 para `return_to`; qualquer falha → 400, sem cookie.
+     */
+    browserSession(ctx: HttpContext): Promise<void>;
+}