@panal/sdk 0.5.0 → 0.6.0

package/dist/files.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Panal SDK — entregar archivos sin renunciar a la garantía de la cadena.
+ *
+ * El escrow ancla `keccak256(texto de la entrega)` y nada más. Eso funciona
+ * para un informe escrito, pero no para un PDF, un audio o un vídeo: no caben
+ * en un string y meterlos en la cadena costaría más que el trabajo.
+ *
+ * La salida fácil sería entregar un enlace. Es una trampa: el hash anclado
+ * cubriría el enlace, no el archivo. Quien lo aloja puede cambiar el PDF
+ * después de cobrar y el cliente no tiene con qué demostrar nada. Un enlace
+ * pelado convierte el escrow en una promesa.
+ *
+ * Lo que se hace aquí es anclar el HASH DEL ARCHIVO dentro del texto:
+ *
+ *     Aquí tienes el informe que pediste.
+ *
+ *     [panal-files/1]
+ *     name: informe.pdf
+ *     size: 184320
+ *     mime: application/pdf
+ *     hash: 0x8f3a…
+ *     path: /files/31/informe.pdf
+ *
+ * Ese texto entero es lo que se ancla. La cadena de custodia queda cerrada:
+ *
+ *     resultHash on-chain → texto de la entrega → hash del archivo → bytes
+ *
+ * Cada eslabón se comprueba sin fiarse de nadie. El servidor que sirve el
+ * archivo deja de ser de confianza: puede ser el agente, un S3 o un CDN, y si
+ * los bytes no dan el hash pactado, la descarga falla.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente tiene REGISTRADO
+ * on-chain, no contra algo que venga en el texto. Así un agente no puede
+ * mandar a su cliente a un tercero. `url` absoluta existe para quien aloja
+ * fuera, y es igual de segura porque la garantía la da el hash, no el sitio.
+ */
+import type { Hex } from 'viem';
+import { type UrlGuardOptions } from './net.js';
+/** Cabecera del bloque. Lleva versión porque el formato se ancla en la cadena. */
+export declare const FILES_BLOCK = "[panal-files/1]";
+/** Tope por defecto de una descarga: 25 MB. */
+export declare const MAX_FILE_BYTES: number;
+/** Un archivo anunciado en la entrega. */
+export interface DeliveredFile {
+    /** Nombre del archivo, sin rutas. */
+    name: string;
+    /** Tamaño en bytes. Se comprueba junto al hash. */
+    size: number;
+    /** Tipo MIME, si el agente lo declaró. */
+    mime?: string;
+    /** keccak256 de los bytes. Es la garantía; todo lo demás es logística. */
+    hash: Hex;
+    /** Ruta relativa, a resolver contra el botUrl registrado del agente. */
+    path?: string;
+    /** URL absoluta, para quien aloja fuera de su propio servidor. */
+    url?: string;
+}
+export declare class FileVerificationError extends Error {
+    readonly file: string;
+    constructor(message: string, file: string);
+}
+/**
+ * Limpia un nombre de archivo para que no pueda salirse de su carpeta.
+ *
+ * El nombre viaja en el texto de la entrega y acaba usado como ruta en disco y
+ * en una URL. Sin esto, un `../../.env` como nombre convierte una entrega en
+ * una lectura arbitraria del servidor del agente.
+ */
+export declare function sanitizeFileName(name: string): string;
+/**
+ * Construye el bloque del manifiesto.
+ *
+ * El orden de las claves es fijo y las líneas van con `\n`: este texto se
+ * anclará en la cadena, así que dos ejecuciones con los mismos archivos tienen
+ * que dar exactamente los mismos bytes.
+ */
+export declare function buildFilesManifest(files: DeliveredFile[]): string;
+/** El texto de la entrega con el manifiesto pegado al final. */
+export declare function appendFilesManifest(text: string, files: DeliveredFile[]): string;
+/**
+ * Lee los archivos anunciados en el texto de una entrega.
+ *
+ * Nunca lanza por un bloque mal formado: devuelve los que sí se entienden. Un
+ * manifiesto roto no puede impedirle al cliente leer la parte escrita de su
+ * entrega, que ya pagó.
+ */
+export declare function parseFilesManifest(text: string): DeliveredFile[];
+/**
+ * El texto de la entrega sin los bloques del manifiesto.
+ *
+ * Para enseñárselo a una persona: el manifiesto es para la máquina, y en un
+ * chat de Telegram no aporta más que ruido.
+ */
+export declare function stripFilesManifest(text: string): string;
+/** Comprueba unos bytes contra lo que el manifiesto prometía. Lanza si no cuadra. */
+export declare function verifyFileBytes(file: DeliveredFile, bytes: Uint8Array): void;
+/**
+ * De dónde se baja un archivo.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente publica EN EL REGISTRY,
+ * no contra nada que venga en el texto: si el agente pudiera elegir el host, un
+ * agente comprometido mandaría a su cliente donde quisiera. La URL absoluta se
+ * permite porque el hash la vigila igual, pero pasa por el guardia de SSRF.
+ */
+export declare function fileUrl(file: DeliveredFile, baseUrl: string | undefined): string;
+export interface DownloadOptions extends UrlGuardOptions {
+    /** Base para las rutas relativas: el botUrl registrado del agente. */
+    baseUrl?: string;
+    /** Wallet del cliente; el agente solo entrega a quien pagó. */
+    address?: string;
+    /** Firma de `Panal resultado #<taskId>`, la misma que abre `/result/:id`. */
+    signature?: string;
+    maxBytes?: number;
+    timeoutMs?: number;
+}
+/**
+ * Baja un archivo de una entrega y lo verifica contra el hash anclado.
+ *
+ * Si los bytes no dan el hash, lanza en vez de devolverlos. Devolver un archivo
+ * que no cuadra "avisando" no serviría de nada: quien llama lo guardaría igual.
+ */
+export declare function downloadDeliveredFile(file: DeliveredFile, options?: DownloadOptions): Promise<Uint8Array>;

package/dist/files.js

@@ -0,0 +1,225 @@
+/**
+ * Panal SDK — entregar archivos sin renunciar a la garantía de la cadena.
+ *
+ * El escrow ancla `keccak256(texto de la entrega)` y nada más. Eso funciona
+ * para un informe escrito, pero no para un PDF, un audio o un vídeo: no caben
+ * en un string y meterlos en la cadena costaría más que el trabajo.
+ *
+ * La salida fácil sería entregar un enlace. Es una trampa: el hash anclado
+ * cubriría el enlace, no el archivo. Quien lo aloja puede cambiar el PDF
+ * después de cobrar y el cliente no tiene con qué demostrar nada. Un enlace
+ * pelado convierte el escrow en una promesa.
+ *
+ * Lo que se hace aquí es anclar el HASH DEL ARCHIVO dentro del texto:
+ *
+ *     Aquí tienes el informe que pediste.
+ *
+ *     [panal-files/1]
+ *     name: informe.pdf
+ *     size: 184320
+ *     mime: application/pdf
+ *     hash: 0x8f3a…
+ *     path: /files/31/informe.pdf
+ *
+ * Ese texto entero es lo que se ancla. La cadena de custodia queda cerrada:
+ *
+ *     resultHash on-chain → texto de la entrega → hash del archivo → bytes
+ *
+ * Cada eslabón se comprueba sin fiarse de nadie. El servidor que sirve el
+ * archivo deja de ser de confianza: puede ser el agente, un S3 o un CDN, y si
+ * los bytes no dan el hash pactado, la descarga falla.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente tiene REGISTRADO
+ * on-chain, no contra algo que venga en el texto. Así un agente no puede
+ * mandar a su cliente a un tercero. `url` absoluta existe para quien aloja
+ * fuera, y es igual de segura porque la garantía la da el hash, no el sitio.
+ */
+import { keccak256 } from 'viem';
+import { assertPublicUrl, fetchBytesLimited } from './net.js';
+/** Cabecera del bloque. Lleva versión porque el formato se ancla en la cadena. */
+export const FILES_BLOCK = '[panal-files/1]';
+/** Tope por defecto de una descarga: 25 MB. */
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+export class FileVerificationError extends Error {
+    file;
+    constructor(message, file) {
+        super(message);
+        this.file = file;
+        this.name = 'FileVerificationError';
+    }
+}
+/**
+ * Limpia un nombre de archivo para que no pueda salirse de su carpeta.
+ *
+ * El nombre viaja en el texto de la entrega y acaba usado como ruta en disco y
+ * en una URL. Sin esto, un `../../.env` como nombre convierte una entrega en
+ * una lectura arbitraria del servidor del agente.
+ */
+export function sanitizeFileName(name) {
+    // Se corta por cualquier separador y se coge el último tramo: así `a/b/c.pdf`
+    // y `..\\..\\c.pdf` acaban los dos en `c.pdf`.
+    const base = name.split(/[/\\]/).pop() ?? '';
+    const limpio = base
+        .replace(/[\u0000-\u001f\u007f]/g, '') // caracteres de control
+        .replace(/^\.+/, '') // nada de nombres que empiezan por punto: '..' incluido
+        .trim();
+    if (!limpio)
+        throw new Error(`Nombre de archivo inservible: "${name}"`);
+    return limpio.slice(0, 120);
+}
+/**
+ * Construye el bloque del manifiesto.
+ *
+ * El orden de las claves es fijo y las líneas van con `\n`: este texto se
+ * anclará en la cadena, así que dos ejecuciones con los mismos archivos tienen
+ * que dar exactamente los mismos bytes.
+ */
+export function buildFilesManifest(files) {
+    return files
+        .map((f) => {
+        const lineas = [FILES_BLOCK, `name: ${sanitizeFileName(f.name)}`, `size: ${f.size}`];
+        if (f.mime)
+            lineas.push(`mime: ${f.mime}`);
+        lineas.push(`hash: ${f.hash}`);
+        if (f.path)
+            lineas.push(`path: ${f.path}`);
+        if (f.url)
+            lineas.push(`url: ${f.url}`);
+        return lineas.join('\n');
+    })
+        .join('\n\n');
+}
+/** El texto de la entrega con el manifiesto pegado al final. */
+export function appendFilesManifest(text, files) {
+    if (files.length === 0)
+        return text;
+    const cuerpo = text.trimEnd();
+    return `${cuerpo}\n\n${buildFilesManifest(files)}\n`;
+}
+/**
+ * Lee los archivos anunciados en el texto de una entrega.
+ *
+ * Nunca lanza por un bloque mal formado: devuelve los que sí se entienden. Un
+ * manifiesto roto no puede impedirle al cliente leer la parte escrita de su
+ * entrega, que ya pagó.
+ */
+export function parseFilesManifest(text) {
+    const out = [];
+    const lineas = text.split(/\r?\n/);
+    for (let i = 0; i < lineas.length; i++) {
+        if (lineas[i].trim() !== FILES_BLOCK)
+            continue;
+        const campos = {};
+        for (let j = i + 1; j < lineas.length; j++) {
+            const linea = lineas[j];
+            if (!linea.trim() || linea.trim() === FILES_BLOCK)
+                break;
+            const sep = linea.indexOf(':');
+            if (sep === -1)
+                break;
+            campos[linea.slice(0, sep).trim().toLowerCase()] = linea.slice(sep + 1).trim();
+        }
+        const { name, size, hash, mime, path, url } = campos;
+        if (!name || !hash || !/^0x[0-9a-fA-F]{64}$/.test(hash))
+            continue;
+        const bytes = Number(size);
+        if (!Number.isInteger(bytes) || bytes < 0)
+            continue;
+        if (!path && !url)
+            continue;
+        try {
+            out.push({
+                name: sanitizeFileName(name),
+                size: bytes,
+                hash: hash.toLowerCase(),
+                ...(mime ? { mime } : {}),
+                ...(path ? { path } : {}),
+                ...(url ? { url } : {}),
+            });
+        }
+        catch {
+            // Nombre inservible: se descarta ese archivo, no la entrega entera.
+        }
+    }
+    return out;
+}
+/**
+ * El texto de la entrega sin los bloques del manifiesto.
+ *
+ * Para enseñárselo a una persona: el manifiesto es para la máquina, y en un
+ * chat de Telegram no aporta más que ruido.
+ */
+export function stripFilesManifest(text) {
+    const lineas = text.split(/\r?\n/);
+    const fuera = [];
+    let dentro = false;
+    for (const linea of lineas) {
+        if (linea.trim() === FILES_BLOCK) {
+            dentro = true;
+            continue;
+        }
+        if (dentro) {
+            // El bloque termina en la primera línea que ya no es `clave: valor`.
+            if (linea.trim() && linea.includes(':'))
+                continue;
+            dentro = false;
+        }
+        fuera.push(linea);
+    }
+    return fuera.join('\n').trimEnd();
+}
+/** Comprueba unos bytes contra lo que el manifiesto prometía. Lanza si no cuadra. */
+export function verifyFileBytes(file, bytes) {
+    if (bytes.byteLength !== file.size) {
+        throw new FileVerificationError(`"${file.name}" mide ${bytes.byteLength} bytes y la entrega anunciaba ${file.size}.`, file.name);
+    }
+    const real = keccak256(bytes);
+    if (real.toLowerCase() !== file.hash.toLowerCase()) {
+        throw new FileVerificationError(`"${file.name}" no es el archivo que se entregó: su hash es ${real}, y el anclado en la cadena es ${file.hash}.`, file.name);
+    }
+}
+/**
+ * De dónde se baja un archivo.
+ *
+ * `path` se resuelve contra el `botUrl` que el agente publica EN EL REGISTRY,
+ * no contra nada que venga en el texto: si el agente pudiera elegir el host, un
+ * agente comprometido mandaría a su cliente donde quisiera. La URL absoluta se
+ * permite porque el hash la vigila igual, pero pasa por el guardia de SSRF.
+ */
+export function fileUrl(file, baseUrl) {
+    if (file.url)
+        return file.url;
+    if (!file.path)
+        throw new Error(`La entrega anuncia "${file.name}" sin decir de dónde bajarlo.`);
+    if (!baseUrl) {
+        throw new Error(`"${file.name}" viene con una ruta relativa y el agente no publica endpoint en el registry: no hay contra qué resolverla.`);
+    }
+    return new URL(file.path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).toString();
+}
+/**
+ * Baja un archivo de una entrega y lo verifica contra el hash anclado.
+ *
+ * Si los bytes no dan el hash, lanza en vez de devolverlos. Devolver un archivo
+ * que no cuadra "avisando" no serviría de nada: quien llama lo guardaría igual.
+ */
+export async function downloadDeliveredFile(file, options = {}) {
+    const destino = new URL(fileUrl(file, options.baseUrl));
+    if (options.address)
+        destino.searchParams.set('address', options.address);
+    if (options.signature)
+        destino.searchParams.set('signature', options.signature);
+    await assertPublicUrl(destino.toString(), options);
+    // El tope se ata al tamaño ANUNCIADO, no al de por defecto: si el manifiesto
+    // dice 2 MB, no hay razón para dejar que lleguen 25.
+    const tope = Math.min(options.maxBytes ?? MAX_FILE_BYTES, Math.max(file.size, 1) + 1024);
+    const { status, bytes } = await fetchBytesLimited(destino, {
+        maxBytes: tope,
+        timeoutMs: options.timeoutMs ?? 120_000,
+        redirect: 'error',
+    });
+    if (status !== 200) {
+        throw new FileVerificationError(`El agente respondió ${status} al pedirle "${file.name}".`, file.name);
+    }
+    verifyFileBytes(file, bytes);
+    return bytes;
+}

package/dist/index.d.ts

@@ -28,7 +28,9 @@ export type { Agent, AgentMetadata, Task } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
 export type { AskResult, PayAndAskOptions, PermitDomain, X402Accept, X402Quote } from './x402.js';
-export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
+export { FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendFilesManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
+export type { DeliveredFile, DownloadOptions } from './files.js';
 export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';
 export type { SettleDeps, SettleResult, X402Payment, X402ServerAccept, X402ServerQuote, } from './x402-server.js';
 export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';

package/dist/index.js

@@ -25,7 +25,9 @@ export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, parseAgentMetadata,
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 // x402: pagar a otro agente por una consulta, sin escrow y sin humano.
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
-export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
+// Archivos: entregar un PDF o un vídeo anclando SU hash, no el del enlace.
+export { FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendFilesManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
 // x402: la otra mitad, cobrar por llamada. Portada del bot de LexPanal, donde
 // lleva meses cobrando en produccion.
 export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';

package/dist/net.d.ts

@@ -30,9 +30,21 @@ export interface UrlGuardOptions {
  */
 export declare function assertPublicUrl(raw: string, options?: UrlGuardOptions): Promise<URL>;
 /**
- * `fetch` con tope de tamaño y de tiempo. La respuesta viene de un servidor
- * ajeno: sin tope, uno hostil se lleva por delante el proceso.
+ * `fetch` con tope de tamaño y de tiempo, devolviendo los bytes crudos.
+ *
+ * La respuesta viene de un servidor ajeno: sin tope, uno hostil se lleva por
+ * delante el proceso. El tope se aplica MIENTRAS se lee, no al final, para que
+ * un cuerpo infinito se corte en cuanto pasa del límite y no cuando ya no cabe.
  */
+export declare function fetchBytesLimited(url: URL | string, init?: RequestInit & {
+    maxBytes?: number;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    headers: Headers;
+    bytes: Uint8Array;
+}>;
+/** Lo mismo, decodificando el cuerpo como texto UTF-8. */
 export declare function fetchLimited(url: URL | string, init?: RequestInit & {
     maxBytes?: number;
     timeoutMs?: number;

package/dist/net.js

@@ -103,10 +103,13 @@ async function loadDnsLookup() {
     }
 }
 /**
- * `fetch` con tope de tamaño y de tiempo. La respuesta viene de un servidor
- * ajeno: sin tope, uno hostil se lleva por delante el proceso.
+ * `fetch` con tope de tamaño y de tiempo, devolviendo los bytes crudos.
+ *
+ * La respuesta viene de un servidor ajeno: sin tope, uno hostil se lleva por
+ * delante el proceso. El tope se aplica MIENTRAS se lee, no al final, para que
+ * un cuerpo infinito se corte en cuanto pasa del límite y no cuando ya no cabe.
  */
-export async function fetchLimited(url, init = {}) {
+export async function fetchBytesLimited(url, init = {}) {
     const { maxBytes = 512 * 1024, timeoutMs = 30_000, ...rest } = init;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -114,7 +117,7 @@ export async function fetchLimited(url, init = {}) {
         const res = await fetch(url, { ...rest, signal: controller.signal });
         const reader = res.body?.getReader();
         if (!reader)
-            return { status: res.status, headers: res.headers, text: '' };
+            return { status: res.status, headers: res.headers, bytes: new Uint8Array(0) };
         const chunks = [];
         let total = 0;
         for (;;) {
@@ -134,9 +137,14 @@ export async function fetchLimited(url, init = {}) {
             merged.set(c, offset);
             offset += c.byteLength;
         }
-        return { status: res.status, headers: res.headers, text: new TextDecoder().decode(merged) };
+        return { status: res.status, headers: res.headers, bytes: merged };
     }
     finally {
         clearTimeout(timer);
     }
 }
+/** Lo mismo, decodificando el cuerpo como texto UTF-8. */
+export async function fetchLimited(url, init = {}) {
+    const { status, headers, bytes } = await fetchBytesLimited(url, init);
+    return { status, headers, text: new TextDecoder().decode(bytes) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/sdk.test.ts && tsx test/x402.test.ts && tsx test/x402-server.test.ts && tsx test/envelope.test.ts"
+    "test": "tsx test/sdk.test.ts && tsx test/x402.test.ts && tsx test/x402-server.test.ts && tsx test/envelope.test.ts && tsx test/files.test.ts"
   }
 }