@adonis-agora/authkit-server 0.76.0 → 0.78.0

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

@@ -0,0 +1,158 @@
+/**
+ * Verificação de provas DPoP (RFC 9449) — utilitário genérico para o token
+ * endpoint e para resource servers (§4.3 do Poppy).
+ *
+ * Confere: um único header `DPoP`; `typ` `dpop+jwt`; algoritmo permitido; `jwk`
+ * público no header e a assinatura com ele; `jti`, `htm`, `htu` (sem query nem
+ * fragmento), `iat` dentro da janela; `ath` = SHA-256 do access token; o
+ * `nonce` quando exigido; replay do `jti` na janela; e, num resource server, que
+ * a chave é a do token (`cnf.jkt`).
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { calculateJwkThumbprint, decodeProtectedHeader, EmbeddedJWK, jwtVerify, } from 'jose';
+import { replayKey } from './replay.js';
+/**
+ * Nonces sem estado: `base64url(ts).base64url(hmac(ts))`, válidos por
+ * `ttlSeconds` (default 300). Qualquer instância com o mesmo segredo valida.
+ *
+ * @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.
+ */
+export function hmacNonceSource(secret, options = {}) {
+    const ttl = (options.ttlSeconds ?? 300) * 1000;
+    const now = options.now ?? Date.now;
+    const mac = (ts) => createHmac('sha256', secret).update(`dpop-nonce:${ts}`).digest('base64url');
+    return {
+        issue() {
+            const ts = Buffer.from(String(now())).toString('base64url');
+            return `${ts}.${mac(ts)}`;
+        },
+        valid(nonce) {
+            const [ts, sig] = nonce.split('.');
+            if (!ts || !sig)
+                return false;
+            const expected = Buffer.from(mac(ts));
+            const given = Buffer.from(sig);
+            if (expected.length !== given.length || !timingSafeEqual(expected, given))
+                return false;
+            const issuedAt = Number(Buffer.from(ts, 'base64url').toString());
+            const t = now();
+            return Number.isFinite(issuedAt) && issuedAt <= t + 5000 && t - issuedAt <= ttl;
+        },
+    };
+}
+/** `ath`: base64url(SHA-256(access token)). */
+export function accessTokenHash(token) {
+    return createHash('sha256').update(token).digest('base64url');
+}
+/**
+ * `htu` normalizado para comparação: esquema e host minúsculos, sem porta
+ * default, sem query nem fragmento. `null` se não for URL http(s).
+ */
+export function normalizeHtu(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return null;
+        url.hash = '';
+        url.search = '';
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+function failure(error, description) {
+    return { ok: false, error, description };
+}
+/**
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ */
+export async function verifyDpopProof(input) {
+    const raw = input.proof;
+    if (raw === undefined || raw === null || raw === '') {
+        return failure('invalid_dpop_proof', 'DPoP proof is missing');
+    }
+    if (Array.isArray(raw) ? raw.length !== 1 : raw.includes(',')) {
+        return failure('invalid_dpop_proof', 'Exactly one DPoP proof is allowed');
+    }
+    const proof = Array.isArray(raw) ? raw[0] : raw;
+    let header;
+    try {
+        header = decodeProtectedHeader(proof);
+    }
+    catch {
+        return failure('invalid_dpop_proof', 'Malformed DPoP proof');
+    }
+    if (header.typ !== 'dpop+jwt')
+        return failure('invalid_dpop_proof', 'typ must be dpop+jwt');
+    if (!header.alg || !input.algorithms.includes(header.alg)) {
+        return failure('invalid_dpop_proof', 'Unsupported DPoP algorithm');
+    }
+    const jwk = header.jwk;
+    if (!jwk || typeof jwk !== 'object')
+        return failure('invalid_dpop_proof', 'jwk header is required');
+    if ('d' in jwk || jwk.kty === 'oct') {
+        return failure('invalid_dpop_proof', 'jwk must be a public key');
+    }
+    const nowMs = (input.now ?? Date.now)();
+    let payload;
+    try {
+        ({ payload } = await jwtVerify(proof, EmbeddedJWK, {
+            algorithms: input.algorithms,
+            typ: 'dpop+jwt',
+            currentDate: new Date(nowMs),
+        }));
+    }
+    catch {
+        return failure('invalid_dpop_proof', 'DPoP proof signature is invalid');
+    }
+    const { jti, htm, htu, iat, ath, nonce } = payload;
+    if (typeof jti !== 'string' || jti.length < 8 || jti.length > 256) {
+        return failure('invalid_dpop_proof', 'jti is required');
+    }
+    if (typeof htm !== 'string' || htm !== input.method.toUpperCase()) {
+        return failure('invalid_dpop_proof', 'htm does not match the request method');
+    }
+    const expectedHtu = normalizeHtu(input.url);
+    if (typeof htu !== 'string' || !expectedHtu || normalizeHtu(htu) !== expectedHtu) {
+        return failure('invalid_dpop_proof', 'htu does not match the request URL');
+    }
+    const nowS = Math.floor(nowMs / 1000);
+    const skew = input.clockSkew ?? 5;
+    if (typeof iat !== 'number' || iat > nowS + skew || iat < nowS - input.maxAge) {
+        return failure('invalid_dpop_proof', 'iat is outside the acceptance window');
+    }
+    if (input.accessToken !== undefined) {
+        if (typeof ath !== 'string' || ath !== accessTokenHash(input.accessToken)) {
+            return failure('invalid_dpop_proof', 'ath does not match the access token');
+        }
+    }
+    let jkt;
+    try {
+        jkt = await calculateJwkThumbprint(jwk, 'sha256');
+    }
+    catch {
+        return failure('invalid_dpop_proof', 'Invalid jwk');
+    }
+    if (input.expectedJkt !== undefined && jkt !== input.expectedJkt) {
+        return failure('invalid_dpop_proof', 'DPoP key does not match the token binding');
+    }
+    if (input.nonce?.required) {
+        if (typeof nonce !== 'string' || !input.nonce.source.valid(nonce)) {
+            return failure('use_dpop_nonce', 'A DPoP nonce issued by the server is required');
+        }
+    }
+    else if (nonce !== undefined && input.nonce && typeof nonce === 'string') {
+        // Nonce mandado sem ser exigido: se vier, tem de ser um nosso e válido.
+        if (!input.nonce.source.valid(nonce)) {
+            return failure('use_dpop_nonce', 'The DPoP nonce is invalid or expired');
+        }
+    }
+    // Replay por último: uma prova inválida não queima o `jti`.
+    const expiresAt = new Date((iat + input.maxAge + skew) * 1000);
+    if (!(await input.replay.claim(replayKey('dpop', jkt, jti), expiresAt))) {
+        return failure('invalid_dpop_proof', 'DPoP proof was already used');
+    }
+    return { ok: true, jkt, jti };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Erros OAuth do Poppy (§4.2, §4.4, §4.6, RFC 6749 §5.2, RFC 8628 §3.5, RFC 9449)
+ * — viram `{ error, error_description }` com o status da spec.
+ */
+export type PoppyErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_session' | 'account_mismatch' | 'invalid_dpop_proof' | 'use_dpop_nonce' | 'rate_limited' | 'invalid_scope' | 'invalid_target' | 'unsupported_grant_type' | 'unsupported_token_type' | 'unauthorized_client' | 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token';
+export declare class PoppyError extends Error {
+    readonly code: PoppyErrorCode;
+    readonly description: string;
+    readonly status: number;
+    /** Headers extras da resposta (`DPoP-Nonce`, `Retry-After`). */
+    readonly headers: Record<string, string>;
+    constructor(code: PoppyErrorCode, description: string, options?: {
+        status?: number;
+        headers?: Record<string, string>;
+    });
+    toJSON(): {
+        error: PoppyErrorCode;
+        error_description: string;
+    };
+}

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

@@ -0,0 +1,22 @@
+const STATUS = {
+    invalid_client: 401,
+    rate_limited: 429,
+};
+export class PoppyError extends Error {
+    code;
+    description;
+    status;
+    /** Headers extras da resposta (`DPoP-Nonce`, `Retry-After`). */
+    headers;
+    constructor(code, description, options = {}) {
+        super(description);
+        this.code = code;
+        this.description = description;
+        this.name = 'PoppyError';
+        this.status = options.status ?? STATUS[code] ?? 400;
+        this.headers = options.headers ?? {};
+    }
+    toJSON() {
+        return { error: this.code, error_description: this.description };
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { PoppyLimiter, PoppyReplayStore } from './config.js';
+export declare const JTI_TABLE = "auth_poppy_jtis";
+/** Chave curta e de tamanho fixo para um `jti` de um tipo/agente. */
+export declare function replayKey(kind: string, ...parts: string[]): string;
+/** Em memória, por processo. Só serve com uma instância. */
+export declare function memoryReplayStore(options?: {
+    max?: number;
+    now?: () => number;
+}): PoppyReplayStore;
+/**
+ * Na tabela lib-owned `auth_poppy_jtis` (PK = chave): o INSERT de uma chave que
+ * já existe falha — atômico entre instâncias. Linhas vencidas saem aos poucos.
+ */
+export declare function databaseReplayStore(conn: () => any, options?: {
+    now?: () => Date;
+}): PoppyReplayStore;
+/** Numa conexão Redis (`SET key 1 PX ttl NX`). */
+export declare function redisReplayStore(redis: {
+    set: (...args: any[]) => Promise<unknown>;
+}): PoppyReplayStore;
+/** Janelas fixas em memória, por processo: `sessionsPerMinute` por agente, `mediatedPerHour` por (agente, usuário). */
+export declare function memoryLimiter(limits: {
+    sessionsPerMinute: number;
+    mediatedPerHour: number;
+}, now?: () => number): PoppyLimiter;

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

@@ -0,0 +1,106 @@
+/**
+ * Proteção contra replay (`jti` de asserções, client assertions, provas DPoP e
+ * asserções de navegador) e limites de taxa do Poppy.
+ */
+import { createHash } from 'node:crypto';
+export const JTI_TABLE = 'auth_poppy_jtis';
+/** Chave curta e de tamanho fixo para um `jti` de um tipo/agente. */
+export function replayKey(kind, ...parts) {
+    return `${kind}:${createHash('sha256').update(parts.join('\u0000')).digest('base64url')}`;
+}
+/** Em memória, por processo. Só serve com uma instância. */
+export function memoryReplayStore(options = {}) {
+    const seen = new Map();
+    const max = options.max ?? 100_000;
+    const now = options.now ?? Date.now;
+    let claims = 0;
+    return {
+        async claim(key, expiresAt) {
+            const t = now();
+            if (++claims % 1000 === 0 || seen.size >= max) {
+                for (const [k, exp] of seen)
+                    if (exp <= t)
+                        seen.delete(k);
+            }
+            const existing = seen.get(key);
+            if (existing !== undefined && existing > t)
+                return false;
+            if (seen.size >= max)
+                seen.delete(seen.keys().next().value);
+            seen.set(key, expiresAt.getTime());
+            return true;
+        },
+    };
+}
+/**
+ * Na tabela lib-owned `auth_poppy_jtis` (PK = chave): o INSERT de uma chave que
+ * já existe falha — atômico entre instâncias. Linhas vencidas saem aos poucos.
+ */
+export function databaseReplayStore(conn, options = {}) {
+    const now = options.now ?? (() => new Date());
+    let claims = 0;
+    return {
+        async claim(key, expiresAt) {
+            const t = now();
+            if (++claims % 200 === 1) {
+                await conn().from(JTI_TABLE).where('expires_at', '<', t).delete();
+            }
+            try {
+                await conn().table(JTI_TABLE).insert({ key, expires_at: expiresAt });
+                return true;
+            }
+            catch (error) {
+                // Chave já usada — a não ser que a linha vencida ainda não tenha saído.
+                const row = await conn().from(JTI_TABLE).where('key', key).first();
+                if (!row)
+                    throw error;
+                const exp = row.expires_at instanceof Date
+                    ? row.expires_at
+                    : new Date(Number(row.expires_at) || row.expires_at);
+                if (exp.getTime() > t.getTime())
+                    return false;
+                const updated = await conn()
+                    .from(JTI_TABLE)
+                    .where('key', key)
+                    .where('expires_at', '<=', t)
+                    .update({ expires_at: expiresAt });
+                return ((typeof updated === 'number' ? updated : Array.isArray(updated) ? updated.length : 0) > 0);
+            }
+        },
+    };
+}
+/** Numa conexão Redis (`SET key 1 PX ttl NX`). */
+export function redisReplayStore(redis) {
+    return {
+        async claim(key, expiresAt) {
+            const ttl = Math.max(1000, expiresAt.getTime() - Date.now());
+            const result = await redis.set(`authkit:poppy:jti:${key}`, '1', 'PX', ttl, 'NX');
+            return result === 'OK';
+        },
+    };
+}
+/** Janelas fixas em memória, por processo: `sessionsPerMinute` por agente, `mediatedPerHour` por (agente, usuário). */
+export function memoryLimiter(limits, now = Date.now) {
+    const windows = new Map();
+    return async ({ action, key }) => {
+        const [limit, windowMs] = action === 'session'
+            ? [limits.sessionsPerMinute, 60_000]
+            : [limits.mediatedPerHour, 3_600_000];
+        const t = now();
+        const id = `${action}:${key}`;
+        let w = windows.get(id);
+        if (!w || t - w.start >= windowMs) {
+            w = { start: t, count: 0 };
+            windows.set(id, w);
+            if (windows.size > 50_000) {
+                for (const [k, v] of windows)
+                    if (t - v.start >= 3_600_000)
+                        windows.delete(k);
+            }
+        }
+        if (w.count >= limit)
+            return Math.ceil((w.start + windowMs - t) / 1000);
+        w.count++;
+        return null;
+    };
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Lado resource server do Poppy (§4.3, §6): verificar o Session Token de uma
+ * request às APIs/conversas do app — e o slot GLOBAL que o `@adonis-agora/agent`
+ * usa para autenticar o endpoint de conversas sem importar este pacote.
+ *
+ * Contrato do slot (o mesmo padrão do `Symbol.for('@adonis-agora/oauth:resources')`):
+ *
+ * ```ts
+ * const authenticate = globalThis[Symbol.for('@adonis-agora/poppy:authenticate')]
+ * const result = await authenticate({ method, url, headers }, { scopes?, signedIn?, resource? })
+ * // { ok: true, principal } | { ok: false, status, error, scope?, wwwAuthenticate, headers }
+ * ```
+ */
+import type { HttpContext } from '@adonisjs/core/http';
+import type { PoppyPrincipalBase } from './config.js';
+import type { PoppyAuthError, PoppyService, PoppyVerifyOptions } from './service.js';
+/** Símbolo do slot global de autenticação Poppy. */
+export declare const POPPY_AUTHENTICATE_SLOT: unique symbol;
+/** O principal de um Session Token válido. *
+/** O principal de um Session Token válido. * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+/** O principal de um Session Token válido. *   de forma incompatível fora de majors enquanto ela for draft.
+/** O principal de um Session Token válido. */
+export interface PoppyPrincipal extends PoppyPrincipalBase {
+    /** O que `personalAgents.poppy.toActor` devolveu, quando configurado. */
+    actor?: unknown;
+}
+/**
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ */
+export type PoppyAuthResult = {
+    ok: true;
+    principal: PoppyPrincipal;
+} | {
+    ok: false;
+    status: 401 | 403;
+    error: PoppyAuthError;
+    /** Scopes exigidos (`insufficient_scope`). */
+    scope?: string;
+    /** Valor pronto do header `WWW-Authenticate`. */
+    wwwAuthenticate: string;
+    /** Texto para logs/corpo — nunca contém o token. */
+    description: string;
+    /** Headers extras a devolver (`DPoP-Nonce`). */
+    headers: Record<string, string>;
+};
+/** Request no formato do slot (sem `HttpContext`). */
+export interface PoppySlotRequest {
+    method: string;
+    /** URL pública completa da request (a query é ignorada). */
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+export type PoppyAuthenticate = (request: PoppySlotRequest, options?: PoppyVerifyOptions) => Promise<PoppyAuthResult>;
+/** URL pública da request: atrás de proxy TLS, o esquema segue o do issuer. */
+export declare function publicRequestUrl(ctx: HttpContext, poppy: PoppyService): string;
+/**
+ * Verifica o Session Token de uma request (DPoP; Bearer só no MCP para o qual
+ * foi emitido). Aceita o `HttpContext` ou `{ method, url, headers }`.
+ *
+ * @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.
+ */
+export declare function verifyPoppyRequest(input: HttpContext | PoppySlotRequest, options?: PoppyVerifyOptions): Promise<PoppyAuthResult>;
+/** Escreve a resposta de erro de um {@link PoppyAuthResult} recusado. */
+export declare function writePoppyAuthError(ctx: HttpContext, result: Extract<PoppyAuthResult, {
+    ok: false;
+}>): void;
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. *
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. *   de forma incompatível fora de majors enquanto ela for draft.
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. */
+export declare function poppyOf(ctx: HttpContext): PoppyPrincipal | null;
+/**
+ * Middleware das APIs/rotas que aceitam Session Tokens Poppy.
+ *
+ * ```ts
+ * router.post('/orders/:id/exchanges', [Orders, 'exchange'])
+ *   .use(poppyAuth({ scopes: ['poppy:write'] }))
+ * ```
+ *
+ * Isente essas rotas do CSRF (são chamadas por agentes, sem navegador).
+ *
+ * @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.
+ */
+export declare function poppyAuth(options?: PoppyVerifyOptions): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * Publica o slot global `Symbol.for('@adonis-agora/poppy:authenticate')` (e
+ * `Symbol.for('@adonis-agora/poppy:issuer')`). Chamado no boot do provider
+ * quando `personalAgents.poppy` está no config.
+ *
+ * @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.
+ */
+export declare function installPoppySlots(issuer: string): void;

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

@@ -0,0 +1,125 @@
+import { getBootedApp } from '../../../services/booted_app.js';
+import { buildPersonalAgentsRuntime, personalAgentsFor } from '../runtime.js';
+/** Símbolo do slot global de autenticação Poppy. */
+export const POPPY_AUTHENTICATE_SLOT = Symbol.for('@adonis-agora/poppy:authenticate');
+/** URL pública da request: atrás de proxy TLS, o esquema segue o do issuer. */
+export function publicRequestUrl(ctx, poppy) {
+    const url = new URL(ctx.request.completeUrl(false));
+    if (new URL(poppy.urls.origin).protocol === 'https:' && url.protocol === 'http:') {
+        url.protocol = 'https:';
+    }
+    return url.toString();
+}
+function requestFromCtx(ctx, poppy) {
+    return {
+        method: ctx.request.method(),
+        url: publicRequestUrl(ctx, poppy),
+        headers: ctx.request.headers(),
+    };
+}
+const NOT_ENABLED = {
+    ok: false,
+    status: 401,
+    error: 'invalid_token',
+    description: 'Poppy is not enabled',
+    wwwAuthenticate: 'DPoP error="invalid_token"',
+    headers: {},
+};
+async function verifyWith(poppy, input, options) {
+    const result = await poppy.verifyAccess(input, options);
+    if (!result.ok) {
+        const { ok: _ok, ...rest } = result;
+        return { ok: false, ...rest };
+    }
+    const principal = { ...result.principal };
+    if (poppy.cfg.toActor)
+        principal.actor = await poppy.cfg.toActor(result.principal);
+    return { ok: true, principal };
+}
+async function poppyFromBootedApp() {
+    const app = getBootedApp();
+    const service = await app.container.make('authkit.server');
+    const runtime = await buildPersonalAgentsRuntime(service, () => app.container.make('lucid.db'), { make: (binding) => app.container.make(binding) });
+    return runtime?.poppy ?? null;
+}
+/**
+ * Verifica o Session Token de uma request (DPoP; Bearer só no MCP para o qual
+ * foi emitido). Aceita o `HttpContext` ou `{ method, url, headers }`.
+ *
+ * @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.
+ */
+export async function verifyPoppyRequest(input, options = {}) {
+    if ('request' in input && typeof input.request?.method === 'function') {
+        const ctx = input;
+        const poppy = (await personalAgentsFor(ctx))?.poppy;
+        if (!poppy)
+            return NOT_ENABLED;
+        return verifyWith(poppy, requestFromCtx(ctx, poppy), options);
+    }
+    const poppy = await poppyFromBootedApp();
+    if (!poppy)
+        return NOT_ENABLED;
+    return verifyWith(poppy, input, options);
+}
+/** Escreve a resposta de erro de um {@link PoppyAuthResult} recusado. */
+export function writePoppyAuthError(ctx, result) {
+    ctx.response.header('WWW-Authenticate', result.wwwAuthenticate);
+    for (const [k, v] of Object.entries(result.headers))
+        ctx.response.header(k, v);
+    ctx.response.header('Cache-Control', 'no-store');
+    return ctx.response.status(result.status).json({
+        error: result.error,
+        error_description: result.description,
+        ...(result.scope ? { scope: result.scope } : {}),
+    });
+}
+/** Guardado fora do `HttpContext` (sem augmentation — ver `augmentation_isolation.spec.ts`). */
+const principals = new WeakMap();
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. *
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — acompanha a spec em desenvolvimento e PODE MUDAR
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. *   de forma incompatível fora de majors enquanto ela for draft.
+/** O principal Poppy da request — preenchido por {@link poppyAuth}. */
+export function poppyOf(ctx) {
+    return principals.get(ctx) ?? null;
+}
+/**
+ * Middleware das APIs/rotas que aceitam Session Tokens Poppy.
+ *
+ * ```ts
+ * router.post('/orders/:id/exchanges', [Orders, 'exchange'])
+ *   .use(poppyAuth({ scopes: ['poppy:write'] }))
+ * ```
+ *
+ * Isente essas rotas do CSRF (são chamadas por agentes, sem navegador).
+ *
+ * @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.
+ */
+export function poppyAuth(options = {}) {
+    return async (ctx, next) => {
+        const result = await verifyPoppyRequest(ctx, options);
+        if (!result.ok)
+            return writePoppyAuthError(ctx, result);
+        principals.set(ctx, result.principal);
+        return next();
+    };
+}
+/**
+ * Publica o slot global `Symbol.for('@adonis-agora/poppy:authenticate')` (e
+ * `Symbol.for('@adonis-agora/poppy:issuer')`). Chamado no boot do provider
+ * quando `personalAgents.poppy` está no config.
+ *
+ * @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.
+ */
+export function installPoppySlots(issuer) {
+    const slot = globalThis;
+    const authenticate = (request, options) => verifyPoppyRequest({
+        method: request.method,
+        url: request.url,
+        headers: request.headers ?? {},
+    }, options);
+    slot[POPPY_AUTHENTICATE_SLOT] = authenticate;
+    slot[Symbol.for('@adonis-agora/poppy:issuer')] = issuer;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * `fetch` de documentos JSON de terceiros à prova de SSRF.
+ *
+ * O `client_id` de um agente Poppy é uma URL que QUALQUER um escolhe — buscá-la
+ * sem cuidado faria deste app um proxy para a rede interna. Regras:
+ *  - só `https:`; sem credenciais na URL; porta qualquer;
+ *  - o IP é conferido NA CONEXÃO (o `lookup` do socket), não num DNS separado —
+ *    sem janela para DNS rebinding; loopback, privados, link-local, CGNAT,
+ *    multicast, reservados e os equivalentes IPv6 são recusados;
+ *  - IP literal na URL passa pela mesma regra;
+ *  - sem redirects (o `client_id` tem de ser exatamente a URL buscada);
+ *  - teto de tempo e de bytes.
+ */
+import { type LookupAddress } from 'node:dns';
+export declare class SafeFetchError extends Error {
+    constructor(message: string);
+}
+export interface FetchedJson {
+    status: number;
+    body: unknown;
+    /** `max-age` do `Cache-Control`, em segundos, quando há. */
+    maxAge: number | null;
+}
+/** Busca um JSON (GET). Lança {@link SafeFetchError} em qualquer recusa. */
+export type JsonFetcher = (url: string) => Promise<FetchedJson>;
+export type LookupFn = (hostname: string, options: {
+    all: true;
+}, callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void) => void;
+export interface SafeFetchOptions {
+    timeoutMs?: number;
+    maxBytes?: number;
+    /** Resolução de nomes — injetável nos testes. Default: `dns.lookup`. */
+    lookup?: LookupFn;
+}
+/** `true` quando o IP não pode ser alvo de uma busca de saída. */
+export declare function isBlockedAddress(ip: string): boolean;
+/**
+ * Busca `url` e devolve o JSON. Só HTTPS, sem redirect, IP público conferido na
+ * conexão, `timeoutMs` (default 5 s) e `maxBytes` (default 64 KiB).
+ */
+export declare function safeFetchJson(url: string, options?: SafeFetchOptions): Promise<FetchedJson>;
+/**
+ * SÓ DEV/TESTE (`personalAgents.poppy.allowInsecureClientIds`): busca um JSON por
+ * `http:` ou `https:` SEM a guarda de SSRF — loopback e rede privada liberados,
+ * para um agente local (`http://localhost:7777/agent.json`). Mantém sem redirect,
+ * teto de tempo e de bytes. Nunca use em produção (a config recusa).
+ */
+export declare function insecureDevFetchJson(url: string, options?: Omit<SafeFetchOptions, 'lookup'>): Promise<FetchedJson>;