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

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

@@ -1,158 +0,0 @@
-/**
- * Verificação de provas DPoP (RFC 9449) — utilitário genérico para o token
- * endpoint e para resource servers (§4.5 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.3 — 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.3 — 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/email_code_sign_in.d.ts

@@ -1,27 +0,0 @@
-import { type AuthAccount } from '../../accounts/account_store.js';
-import type { PoppyMediatedConfigInput } from './config.js';
-export interface PoppyEmailCodeSignInOptions {
-    /** Scopes que este sign-in pode conceder. */
-    scopes: string[];
-    /** Validade do código, em segundos. Default: 600. */
-    codeTtl?: number;
-    /** Tentativas de código antes de `invalid_grant`. Default: 5. */
-    maxCodeAttempts?: number;
-    /**
-     * Quem pode entrar por aqui (ex.: só pacientes, não profissionais). `false` = recebe a
-     * resposta de conta inexistente. Default: toda conta ativa.
-     */
-    eligible?: (account: AuthAccount) => boolean | Promise<boolean>;
-    /**
-     * Códigos por e-mail por hora, nesta instância — impede um agente de lotar a caixa de
-     * alguém. Acima disso a resposta é a mesma, sem e-mail. Default: 5.
-     */
-    maxPerHour?: number;
-    /** Rótulo do campo que o agente mostra ao usuário. Default: `'Email address'`. */
-    label?: string;
-    /** Texto de `sentTo` a partir do e-mail mascarado. Default: `` `Email to ${masked}` ``. */
-    sentTo?: (masked: string) => string;
-}
-/** `ana.souza@gmail.com` → `a***@gmail.com`: o bastante para a pessoa reconhecer. */
-export declare function maskEmail(email: string): string;
-export declare function poppyEmailCodeSignIn(options: PoppyEmailCodeSignInOptions): PoppyMediatedConfigInput;

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

@@ -1,140 +0,0 @@
-/**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
- *
- * Mediated Sign-In pronto (extensão `mediated-sign-in`): o agente pede o e-mail da conta, o authkit manda
- * um código de 6 dígitos para ele e o agente devolve o código. Usa as contas
- * (`accountStore`) e o e-mail (hook `mail.onPoppySignInCode` ou o mailer default)
- * do próprio authkit — o app só liga:
- *
- * ```ts
- * personalAgents: {
- *   poppy: { signIn: { mediated: poppyEmailCodeSignIn({ scopes: ['orders:read'] }) } },
- * }
- * ```
- *
- * Sem enumeração de contas: e-mail sem conta, conta desativada, conta recusada
- * por `eligible` ou e-mail acima do limite recebem a MESMA resposta, sem código
- * (`accountId: null`) — a lib recusa qualquer código como errado. O envio não é
- * esperado, então o tempo de resposta também não denuncia.
- */
-import { randomInt } from 'node:crypto';
-import { supportsAccountStatus } from '../../accounts/account_store.js';
-import { sendPoppySignInCodeEmail } from '../../host/default_mailer.js';
-import { personalAgentsFor } from '../runtime.js';
-/** `ana.souza@gmail.com` → `a***@gmail.com`: o bastante para a pessoa reconhecer. */
-export function maskEmail(email) {
-    const at = email.lastIndexOf('@');
-    const user = at > 0 ? email.slice(0, at) : '';
-    const domain = at > 0 ? email.slice(at + 1) : '';
-    if (!user || !domain)
-        return '***';
-    return `${user[0]}***@${domain}`;
-}
-const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-const HOUR_MS = 3600 * 1000;
-const MAX_TRACKED = 10_000;
-export function poppyEmailCodeSignIn(options) {
-    const positive = (value, fallback, what) => {
-        if (value === undefined)
-            return fallback;
-        if (!Number.isFinite(value) || value < 1) {
-            throw new Error(`authkit: poppyEmailCodeSignIn ${what} precisa ser um número >= 1.`);
-        }
-        return Math.floor(value);
-    };
-    const codeTtl = positive(options.codeTtl, 600, 'codeTtl');
-    const maxPerHour = positive(options.maxPerHour, 5, 'maxPerHour');
-    const maxCodeAttempts = positive(options.maxCodeAttempts, 5, 'maxCodeAttempts');
-    const sentToText = options.sentTo ?? ((masked) => `Email to ${masked}`);
-    const sends = new Map();
-    /** `true` = ainda cabe um envio para este e-mail na última hora (e conta este). */
-    const claim = (email) => {
-        const now = Date.now();
-        const recent = (sends.get(email) ?? []).filter((t) => now - t < HOUR_MS);
-        if (recent.length >= maxPerHour) {
-            sends.set(email, recent);
-            return false;
-        }
-        recent.push(now);
-        sends.delete(email);
-        sends.set(email, recent);
-        if (sends.size > MAX_TRACKED)
-            sends.delete(sends.keys().next().value);
-        return true;
-    };
-    const eligibleAccount = async (ctx, email) => {
-        const service = await ctx.containerResolver.make('authkit.server');
-        const store = service.config.accountStore;
-        const account = await store.findByEmail(email);
-        if (!account)
-            return null;
-        if (supportsAccountStatus(store) && (await store.isDisabled(account.id)))
-            return null;
-        if (options.eligible) {
-            // Um `eligible` que lança vira "não elegível": um 500 só para algumas contas as denunciaria.
-            try {
-                if (!(await options.eligible(account)))
-                    return null;
-            }
-            catch (error) {
-                ctx.logger.error({ err: error }, 'authkit: poppyEmailCodeSignIn eligible lançou');
-                return null;
-            }
-        }
-        return account;
-    };
-    return {
-        fields: [{ name: 'email', label: options.label ?? 'Email address', secret: false }],
-        scopes: options.scopes,
-        codeTtl,
-        maxCodeAttempts,
-        async verify({ credentials, clientId, ctx }) {
-            const email = (credentials.email ?? '').trim().toLowerCase();
-            if (!EMAIL.test(email))
-                return { status: 'failed' };
-            const sentTo = sentToText(maskEmail(email));
-            const decoy = { status: 'code_required', accountId: null, sentTo };
-            // O limite conta para qualquer e-mail — com ou sem conta, a resposta não muda.
-            if (!claim(email))
-                return decoy;
-            const account = await eligibleAccount(ctx, email);
-            if (!account)
-                return decoy;
-            const code = String(randomInt(0, 1_000_000)).padStart(6, '0');
-            // Sem `await`: o caminho com conta não pode demorar mais que o sem conta.
-            void deliver(ctx, { email, code, clientId, expiresInMinutes: Math.ceil(codeTtl / 60) });
-            return { status: 'code_required', accountId: account.id, sentTo, code };
-        },
-    };
-}
-function hostOf(clientId) {
-    try {
-        return new URL(clientId).host;
-    }
-    catch {
-        return clientId;
-    }
-}
-async function deliver(ctx, data) {
-    try {
-        const runtime = await personalAgentsFor(ctx);
-        const agentName = runtime?.poppy
-            ? await runtime.poppy.registry.displayName(data.clientId)
-            : hostOf(data.clientId);
-        const service = await ctx.containerResolver.make('authkit.server');
-        const hook = service.config.mail?.onPoppySignInCode;
-        const input = {
-            email: data.email,
-            code: data.code,
-            agentName,
-            expiresInMinutes: data.expiresInMinutes,
-        };
-        if (hook)
-            await hook(input);
-        else
-            await sendPoppySignInCodeEmail(ctx, input);
-    }
-    catch (error) {
-        ctx.logger.error({ err: error }, 'authkit: o código do Poppy Mediated Sign-In não saiu');
-    }
-}

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

@@ -1,25 +0,0 @@
-/**
- * Erros OAuth do Poppy (§4.7, RFC 6749 §5.2, RFC 8628 §3.5, RFC 9449, extensão Mediated Sign-In)
- * — viram `{ error, error_description }` com o status da spec.
- */
-export type PoppyErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'invalid_session' | 'invalid_dpop_proof' | 'use_dpop_nonce'
-/** Interno: HTTP 429 com `Retry-After`, sem corpo (§5.6). */
- | 'too_many_requests' | 'code_required' | '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>;
-    /** Campos extras do corpo (`sign_in_id`, `sent_to`, `expires_in` do `code_required`). */
-    readonly extra: Record<string, unknown>;
-    constructor(code: PoppyErrorCode, description: string, options?: {
-        status?: number;
-        headers?: Record<string, string>;
-        extra?: Record<string, unknown>;
-    });
-    toJSON(): {
-        error: PoppyErrorCode;
-        error_description: string;
-    };
-}

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

@@ -1,25 +0,0 @@
-const STATUS = {
-    invalid_client: 401,
-    too_many_requests: 429,
-};
-export class PoppyError extends Error {
-    code;
-    description;
-    status;
-    /** Headers extras da resposta (`DPoP-Nonce`, `Retry-After`). */
-    headers;
-    /** Campos extras do corpo (`sign_in_id`, `sent_to`, `expires_in` do `code_required`). */
-    extra;
-    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 ?? {};
-        this.extra = options.extra ?? {};
-    }
-    toJSON() {
-        return { error: this.code, error_description: this.description, ...this.extra };
-    }
-}

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

@@ -1,25 +0,0 @@
-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

@@ -1,106 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-/**
- * Lado resource server do Poppy (§4.5, §5.3, §7): verificar o header `Poppy-Session` e o access
- * 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 uma request verificada.
- *
- * @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 PoppyPrincipal extends PoppyPrincipalBase {
-    /** O que `personalAgents.poppy.toActor` devolveu, quando configurado. */
-    actor?: unknown;
-}
-/**
- * @experimental Poppy (Personal Agent Protocol) Draft 0.3 — pode mudar de forma incompatível enquanto a spec for draft.
- */
-export type PoppyAuthResult = {
-    ok: true;
-    principal: PoppyPrincipal;
-} | {
-    ok: false;
-    status: 400 | 401 | 403 | 429;
-    /** `null`: challenge sem código (falta o access token, §7) ou limite de taxa (§5.6). */
-    error: PoppyAuthError | null;
-    /** Scopes exigidos (challenge e `insufficient_scope`). */
-    scope?: string;
-    /** Valor pronto do header `WWW-Authenticate`; `null` em `invalid_session` e no 429. */
-    wwwAuthenticate: string | null;
-    /** Texto para logs/corpo — nunca contém o token. */
-    description: string;
-    /** Headers extras a devolver (`DPoP-Nonce`, `Retry-After`). */
-    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 header `Poppy-Session` de uma request e, se houver, o access token. Aceita o
- * `HttpContext` ou `{ method, url, headers }`.
- *
- * @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 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}.
- *
- * @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 declare function poppyOf(ctx: HttpContext): PoppyPrincipal | null;
-/**
- * Middleware das APIs/rotas que usam a Session Poppy.
- *
- * ```ts
- * router.post('/orders/:id/exchanges', [Orders, 'exchange'])
- *   .use(poppyAuth({ scopes: ['orders:write'] }))
- * ```
- *
- * Isente essas rotas do CSRF (são chamadas por agentes, sem navegador).
- *
- * @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 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.3 — 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;