@adonis-agora/authkit-server 0.76.0 → 0.78.0

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

@@ -0,0 +1,256 @@
+/**
+ * `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 { lookup as dnsLookup } from 'node:dns';
+import { request as httpsRequest } from 'node:https';
+import { isIP } from 'node:net';
+export class SafeFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SafeFetchError';
+    }
+}
+function ipv4ToInt(ip) {
+    return ip.split('.').reduce((acc, part) => (acc << 8) + Number(part), 0) >>> 0;
+}
+function inV4(ip, cidr) {
+    const [base, bits] = cidr.split('/');
+    const mask = Number(bits) === 0 ? 0 : (~0 << (32 - Number(bits))) >>> 0;
+    return (ip & mask) === (ipv4ToInt(base) & mask);
+}
+const BLOCKED_V4 = [
+    '0.0.0.0/8',
+    '10.0.0.0/8',
+    '100.64.0.0/10',
+    '127.0.0.0/8',
+    '169.254.0.0/16',
+    '172.16.0.0/12',
+    '192.0.0.0/24',
+    '192.0.2.0/24',
+    '192.88.99.0/24',
+    '192.168.0.0/16',
+    '198.18.0.0/15',
+    '198.51.100.0/24',
+    '203.0.113.0/24',
+    '224.0.0.0/4',
+    '240.0.0.0/4',
+];
+/** Expande um IPv6 em 8 grupos de 16 bits. */
+function ipv6Groups(ip) {
+    let addr = ip.toLowerCase().split('%')[0];
+    // Sufixo IPv4 (::ffff:1.2.3.4).
+    const v4 = /(\d+\.\d+\.\d+\.\d+)$/.exec(addr);
+    if (v4) {
+        const n = ipv4ToInt(v4[1]);
+        addr = `${addr.slice(0, -v4[1].length)}${(n >>> 16).toString(16)}:${(n & 0xffff).toString(16)}`;
+    }
+    const [head, tail] = addr.split('::');
+    const h = head ? head.split(':') : [];
+    const t = tail !== undefined ? (tail ? tail.split(':') : []) : [];
+    const fill = addr.includes('::') ? 8 - h.length - t.length : 0;
+    const groups = [...h, ...Array(fill).fill('0'), ...t].map((g) => Number.parseInt(g || '0', 16));
+    return groups.length === 8 && groups.every((g) => g >= 0 && g <= 0xffff) ? groups : null;
+}
+/** `true` quando o IP não pode ser alvo de uma busca de saída. */
+export function isBlockedAddress(ip) {
+    const family = isIP(ip);
+    if (family === 4) {
+        const n = ipv4ToInt(ip);
+        return BLOCKED_V4.some((cidr) => inV4(n, cidr));
+    }
+    if (family !== 6)
+        return true;
+    const g = ipv6Groups(ip);
+    if (!g)
+        return true;
+    if (g.every((x) => x === 0))
+        return true; // ::
+    if (g.slice(0, 7).every((x) => x === 0) && g[7] === 1)
+        return true; // ::1
+    // IPv4-mapped (::ffff:a.b.c.d) e IPv4-compatible: decide pelo IPv4.
+    if (g.slice(0, 5).every((x) => x === 0) && (g[5] === 0xffff || g[5] === 0)) {
+        const v4 = `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
+        return isBlockedAddress(v4);
+    }
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 (ULA)
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 (link-local)
+    if ((g[0] & 0xffc0) === 0xfec0)
+        return true; // fec0::/10 (site-local)
+    if ((g[0] & 0xff00) === 0xff00)
+        return true; // ff00::/8 (multicast)
+    if (g[0] === 0x2001 && g[1] === 0x0db8)
+        return true; // 2001:db8::/32 (doc)
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return true; // 64:ff9b::/96 (NAT64)
+    if (g[0] === 0x2002) {
+        // 6to4: o IPv4 embutido.
+        return isBlockedAddress(`${g[1] >> 8}.${g[1] & 255}.${g[2] >> 8}.${g[2] & 255}`);
+    }
+    return false;
+}
+function parseMaxAge(header) {
+    const value = Array.isArray(header) ? header.join(',') : header;
+    if (!value)
+        return null;
+    if (/\bno-store\b|\bno-cache\b/i.test(value))
+        return 0;
+    const match = /\bmax-age=(\d+)/i.exec(value);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * 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 function safeFetchJson(url, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const maxBytes = options.maxBytes ?? 64 * 1024;
+    const resolve = options.lookup ?? dnsLookup;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return Promise.reject(new SafeFetchError('invalid URL'));
+    }
+    if (parsed.protocol !== 'https:')
+        return Promise.reject(new SafeFetchError('only https URLs'));
+    if (parsed.username || parsed.password) {
+        return Promise.reject(new SafeFetchError('credentials in URL'));
+    }
+    const host = parsed.hostname.replace(/^\[|\]$/g, '');
+    if (isIP(host) && isBlockedAddress(host)) {
+        return Promise.reject(new SafeFetchError('blocked address'));
+    }
+    // `lookup` do socket: resolve e recusa se QUALQUER endereço for interno.
+    const guardedLookup = (hostname, opts, callback) => {
+        resolve(hostname, { all: true }, (err, addresses) => {
+            if (err)
+                return callback(err);
+            const list = addresses ?? [];
+            if (list.length === 0)
+                return callback(new SafeFetchError('no address'));
+            if (list.some((a) => isBlockedAddress(a.address))) {
+                return callback(new SafeFetchError('blocked address'));
+            }
+            if (opts?.all)
+                return callback(null, list);
+            return callback(null, list[0].address, list[0].family);
+        });
+    };
+    return new Promise((done, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const req = httpsRequest(parsed, {
+            method: 'GET',
+            headers: { accept: 'application/json', 'user-agent': 'authkit-poppy/0.1' },
+            lookup: guardedLookup,
+            // IP literal: o `lookup` não roda — já conferido acima.
+        }, (res) => {
+            const status = res.statusCode ?? 0;
+            if (status >= 300 && status < 400) {
+                res.resume();
+                return finish(() => reject(new SafeFetchError('redirects are not followed')));
+            }
+            const chunks = [];
+            let size = 0;
+            res.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > maxBytes) {
+                    req.destroy();
+                    finish(() => reject(new SafeFetchError('response too large')));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('end', () => finish(() => {
+                if (status !== 200)
+                    return reject(new SafeFetchError(`HTTP ${status}`));
+                try {
+                    done({
+                        status,
+                        body: JSON.parse(Buffer.concat(chunks).toString('utf8')),
+                        maxAge: parseMaxAge(res.headers['cache-control']),
+                    });
+                }
+                catch {
+                    reject(new SafeFetchError('invalid JSON'));
+                }
+            }));
+            res.on('error', (e) => finish(() => reject(new SafeFetchError(e.message))));
+        });
+        const timer = setTimeout(() => {
+            req.destroy();
+            finish(() => reject(new SafeFetchError('timeout')));
+        }, timeoutMs);
+        req.on('error', (e) => finish(() => reject(e instanceof SafeFetchError ? e : new SafeFetchError(e.message))));
+        req.end();
+    });
+}
+/**
+ * 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 async function insecureDevFetchJson(url, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const maxBytes = options.maxBytes ?? 64 * 1024;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new SafeFetchError('invalid URL');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new SafeFetchError('only http(s) URLs');
+    }
+    if (parsed.username || parsed.password)
+        throw new SafeFetchError('credentials in URL');
+    let res;
+    try {
+        res = await fetch(parsed, {
+            redirect: 'manual',
+            headers: { accept: 'application/json', 'user-agent': 'authkit-poppy/0.1 (insecure-dev)' },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (error) {
+        throw new SafeFetchError(error.name === 'TimeoutError' ? 'timeout' : 'unreachable');
+    }
+    if (res.status >= 300 && res.status < 400)
+        throw new SafeFetchError('redirects are not followed');
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > maxBytes)
+        throw new SafeFetchError('response too large');
+    if (res.status !== 200)
+        throw new SafeFetchError(`HTTP ${res.status}`);
+    try {
+        return {
+            status: res.status,
+            body: JSON.parse(buf.toString('utf8')),
+            maxAge: parseMaxAge(res.headers.get('cache-control') ?? undefined),
+        };
+    }
+    catch {
+        throw new SafeFetchError('invalid JSON');
+    }
+}

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

@@ -0,0 +1,280 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { DelegationStore } from '../delegation_store.js';
+import type { PoppyClient, PoppyClientRegistry } from './client_registry.js';
+import type { PoppyLimiter, PoppyPrincipalBase, PoppyReplayStore, ResolvedPoppyConfig } from './config.js';
+import { type DpopNonceSource } from './dpop.js';
+import type { PoppyStore, RequestRow } from './store.js';
+export declare const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export declare const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+export declare const BROWSER_ASSERTION_TYP = "poppy-browser+jwt";
+/** URLs públicas do authorization server Poppy. */
+export interface PoppyUrls {
+    origin: string;
+    issuer: string;
+    /** RFC 8414 §3.1: `/.well-known/oauth-authorization-server{issuer path}`. */
+    metadata: string;
+    token: string;
+    revocation: string;
+    authorization: string;
+    deviceAuthorization: string;
+    /** Tela do device flow (`verification_uri`). */
+    device: string;
+    mediated: string;
+    browserSession: string;
+    discovery: string;
+}
+/** Deriva as URLs da ORIGEM do issuer configurado — nunca do Host da request. */
+export declare function poppyUrls(oidcIssuer: string, prefix: string): PoppyUrls;
+/** Resposta do token endpoint (§4.2, §4.4). */
+export interface PoppyTokenResponse {
+    access_token: string;
+    token_type: 'DPoP' | 'Bearer';
+    expires_in: number;
+    scope: string;
+    session_id: string;
+    signed_in: boolean;
+    refresh_token?: string;
+    refresh_token_expires_in?: number;
+}
+/** Ponte com o oidc-provider para os tokens Bearer de MCP (§4.3, §6). */
+export interface PoppyMcpBridge {
+    /** `url` é um servidor MCP deste app (de `apis` ou do registro de resources)? */
+    isMcpResource(url: string): boolean;
+    /**
+     * Emite o Bearer de uma Session LOGADA como access token do oidc-provider,
+     * para que a integração MCP existente (`AccessToken.find`) o aceite. `null` =
+     * sem ponte (o token fica só no store do Poppy).
+     */
+    mint?(input: {
+        grantId: string;
+        accountId: string;
+        clientId: string;
+        scope: string;
+        resource: string;
+        expiresIn: number;
+        grantExpiresAt: Date;
+    }): Promise<string | null>;
+    /** Revoga o grant (e os tokens) no oidc-provider. */
+    revoke?(grantId: string): Promise<void>;
+}
+export interface PoppyServiceDeps {
+    cfg: ResolvedPoppyConfig;
+    urls: PoppyUrls;
+    store: PoppyStore;
+    grants: DelegationStore;
+    registry: PoppyClientRegistry;
+    replay: PoppyReplayStore;
+    limiter: PoppyLimiter | null;
+    nonces: DpopNonceSource;
+    /** A conta ainda pode agir? (existe e não está desabilitada). Default: sempre. */
+    isAccountActive?: (accountId: string) => Promise<boolean>;
+    mcp?: PoppyMcpBridge;
+    now?: () => Date;
+}
+/** Entrada de uma request para {@link PoppyService.verifyAccess}. */
+export interface PoppyRequestInput {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+export interface PoppyVerifyOptions {
+    /** Scopes exigidos (todos). Faltando: `sign_in_required` (deslogado) ou `insufficient_scope`. */
+    scopes?: string[];
+    /** Exige Session logada. */
+    signedIn?: boolean;
+    /**
+     * `resource` exigido por este endpoint. Default: derivado da URL contra
+     * `apis`/`agent.protocols` do config (entradas com `resource`) e os MCP.
+     */
+    resource?: string | null;
+}
+export type PoppyAuthError = 'invalid_token' | 'sign_in_required' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce';
+export type PoppyVerifyResult = {
+    ok: true;
+    principal: PoppyPrincipalBase;
+    jkt: string | null;
+} | {
+    ok: false;
+    status: 401 | 403;
+    error: PoppyAuthError;
+    description: string;
+    scope?: string;
+    wwwAuthenticate: string;
+    /** Headers extras (`DPoP-Nonce`). */
+    headers: Record<string, string>;
+};
+/** Pedido Direct aguardando o usuário na tela de consentimento. */
+export interface PoppyConsentRequest {
+    id: string;
+    clientId: string;
+    agentName: string;
+    agentOrigin: string;
+    logoUri: string | null;
+    scopes: {
+        id: string;
+        description: string;
+    }[];
+    userCode?: string;
+}
+export type PoppyAuthorizeOutcome = {
+    kind: 'consent';
+    request: PoppyConsentRequest;
+} | {
+    kind: 'redirect';
+    url: string;
+} | {
+    kind: 'error';
+    description: string;
+};
+export interface PoppyGrantSummary {
+    id: string;
+    clientId: string;
+    scopes: {
+        id: string;
+        description: string;
+    }[];
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date;
+}
+export type PoppyMediatedResponse = ({
+    status: 'complete';
+} & PoppyTokenResponse) | {
+    status: 'code_required';
+    sign_in_id: string;
+    code: {
+        sent_to: string;
+    };
+    expires_at: string;
+} | {
+    status: 'failed';
+} | {
+    status: 'expired';
+};
+export interface PoppyBrowserSessionResult {
+    sessionId: string;
+    clientId: string;
+    userId: string;
+    accountId: string | null;
+    scopes: string[];
+    returnTo: string;
+}
+/** Estado atual de uma Session (para o cookie do site acompanhar — §5). */
+export interface PoppySessionState {
+    active: boolean;
+    sessionId: string;
+    clientId: string;
+    userId: string;
+    accountId: string | null;
+    signedIn: boolean;
+    scopes: string[];
+}
+/** Aceita o código como o usuário digitar: minúsculas, sem hífen, com espaços. */
+export declare function normalizePoppyUserCode(input: unknown): string | null;
+/** Slot global onde o `@adonis-agora/agent` registra o endpoint de conversas Poppy. */
+export declare const POPPY_ENDPOINTS_SLOT: unique symbol;
+/**
+ * `agent.protocols` vindo do slot `Symbol.for('@adonis-agora/poppy:endpoints')`
+ * (`{ conversations: 'https://…' }`), usado quando o config não declara
+ * `agent.protocols` — o mesmo padrão do slot de resources do MCP.
+ */
+export declare function registeredConversationProtocols(): {
+    type: string;
+    endpoint: string;
+    resource?: string;
+}[];
+/**
+ * @experimental Poppy (Personal Agent Protocol) Draft 0.1 — pode mudar de forma incompatível enquanto a spec for draft.
+ */
+export declare class PoppyService {
+    #private;
+    readonly cfg: ResolvedPoppyConfig;
+    readonly urls: PoppyUrls;
+    readonly registry: PoppyClientRegistry;
+    constructor(deps: PoppyServiceDeps);
+    /** Um nonce DPoP novo (header `DPoP-Nonce`), quando o app exige nonces. */
+    nonce(): string | null;
+    /** Domínios da empresa (o principal + aliases). */
+    get domains(): string[];
+    /** Descrição de um scope para o usuário. */
+    describe(ids: string[]): {
+        id: string;
+        description: string;
+    }[];
+    /** `/.well-known/poppy.json` (§3) para o domínio pedido; `null` = domínio que não é nosso. */
+    discoveryDocument(requestHost: string): Record<string, unknown> | null;
+    /** RFC 8414 com `poppy_domains` (§3.2). */
+    authorizationServerMetadata(): Record<string, unknown>;
+    /**
+     * `private_key_jwt` (RFC 7523 §2.2, §3): `client_assertion` assinada por uma
+     * chave do `jwks_uri`, `iss` = `sub` = `client_id`, `aud` = o endpoint
+     * chamado (ou o token endpoint/issuer), `exp` curto, `jti` único.
+     */
+    authenticateClient(form: Record<string, unknown>, endpoint: string): Promise<PoppyClient>;
+    /** `POST token_endpoint` (§4.2, §4.3, §4.5, §4.6, §4.8). */
+    token(form: Record<string, unknown>, dpopHeader: string | string[] | undefined): Promise<PoppyTokenResponse>;
+    /** `POST device_authorization_endpoint` (§4.6). */
+    deviceAuthorization(form: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** `POST revocation_endpoint` (§4.9, RFC 7009). */
+    revoke(form: Record<string, unknown>): Promise<void>;
+    /**
+     * Revoga um Account Token (grant): as Sessions logadas com ele continuam
+     * deslogadas (§4.9) e os Bearer de MCP no oidc-provider morrem junto.
+     */
+    revokeGrant(grantId: string): Promise<void>;
+    /**
+     * `GET authorization_endpoint` com o usuário já logado neste app. Erros no
+     * `client_id`/`redirect_uri` não redirecionam (RFC 6749 §4.1.2.1); os demais
+     * voltam ao agente com `error`, `state` e `iss`.
+     */
+    startAuthorization(params: Record<string, unknown>, accountId: string): Promise<PoppyAuthorizeOutcome>;
+    /**
+     * `POST` da tela de consentimento Direct. Devolve para onde mandar o
+     * navegador (`code`/`error`, `state`, `iss`), ou `null` quando o pedido não
+     * vale mais (expirou, decidido em outra aba, de outra conta).
+     */
+    decideAuthorization(input: {
+        requestId: string;
+        accountId: string;
+        allow: boolean;
+        scopes: string[];
+    }): Promise<{
+        url: string;
+        approved: string[] | null;
+        clientId: string;
+    } | null>;
+    pendingDevice(userCodeInput: unknown): Promise<PoppyConsentRequest | null>;
+    /** Aprova (scopes marcados) ou nega um device code. `null` = não está mais pendente. */
+    decideDevice(input: {
+        userCode: string;
+        accountId: string;
+        allow: boolean;
+        scopes: string[];
+    }): Promise<{
+        approved: string[] | null;
+        clientId: string;
+    } | null>;
+    /** `POST auth.mediated.endpoint` — já autenticado pelo Session Token (DPoP). */
+    mediatedStart(principal: PoppyPrincipalBase, jkt: string | null, body: unknown, ctx: HttpContext): Promise<PoppyMediatedResponse>;
+    /** `POST {mediated}/{sign_in_id}` com o código de uso único. */
+    mediatedCode(principal: PoppyPrincipalBase, jkt: string | null, signInId: string, body: unknown): Promise<PoppyMediatedResponse | null>;
+    /**
+     * Verifica `Authorization: DPoP|Bearer` (+ prova DPoP) de uma request a uma API
+     * ou conversa do app. Nunca lê token da URL (§4.3).
+     */
+    verifyAccess(input: PoppyRequestInput, options?: PoppyVerifyOptions): Promise<PoppyVerifyResult>;
+    /**
+     * Confere a asserção de navegador (`typ` `poppy-browser+jwt`). `requestOrigin`
+     * é a origem em que o POST chegou — o cookie precisa nascer nela.
+     */
+    verifyBrowserAssertion(assertion: unknown, requestOrigin: string): Promise<PoppyBrowserSessionResult>;
+    /** Estado atual da Session (ativa? logada? scopes) — o cookie do site segue isto. */
+    sessionState(sessionId: string): Promise<PoppySessionState | null>;
+    listGrants(accountId: string): Promise<PoppyGrantSummary[]>;
+    /** Desconectar o agente pela conta (§4.9): revoga um Account Token DA CONTA. */
+    revokeAccountGrant(accountId: string, grantId: string): Promise<boolean>;
+    /** Revoga todos os Account Tokens da conta (sair de tudo, conta suspensa…). */
+    revokeAllAccountGrants(accountId: string): Promise<number>;
+}
+export type { RequestRow };