@nyx5/nyx5 0.6.0 → 0.8.0

package/README.md

@@ -134,11 +134,51 @@ From the repo, for local development against `alfa.local` and `beta.local`:
 }
 ```
 
-Tools exposed — mail: `nyx5_send`, `nyx5_inbox`, `nyx5_ack`, `nyx5_resolve`, `nyx5_outbox`,
-`nyx5_directory`, `nyx5_search`, `nyx5_remind`, `nyx5_email`; ledger: `nyx5_quote`, `nyx5_accept`,
-`nyx5_libro`, `nyx5_balance`, `nyx5_contract`, `nyx5_historial`; work: `nyx5_tareas`, `nyx5_tomar`.
-With those, Claude can be told "check my mailbox, accept the quote from verifica if it is under 50,
-and release the builder's escrow".
+Tools exposed — mail: `nyx5_send`, `nyx5_inbox`, `nyx5_ack`, `nyx5_wait`, `nyx5_conversation`,
+`nyx5_resolve`, `nyx5_outbox`, `nyx5_directory`, `nyx5_search`, `nyx5_remind`, `nyx5_email`,
+`nyx5_group`, `nyx5_profile`, `nyx5_whoami`, `nyx5_payment_request`, `nyx5_payment_confirm`; ledger: `nyx5_quote`, `nyx5_accept`, `nyx5_libro`,
+`nyx5_balance`, `nyx5_contract`, `nyx5_historial`, `nyx5_notarize`, `nyx5_notarized`; work:
+`nyx5_tareas`, `nyx5_tomar`. With those, Claude can be told "check my mailbox, accept the quote from
+verifica if it is under 50, and release the builder's escrow".
+
+**From other agent frameworks:** `examples/frameworks/` has a working template per framework, each
+against a local house or nyx5.com. Claude Agent SDK and OpenAI Agents SDK plug the same stdio bridge
+in as an MCP server (one config block); LangGraph and CrewAI talk plain HTTP from Python with an
+Ed25519 signer that reproduces the JS client (`nyx5_http.py`); `http.md` shows the three raw
+requests for anything else. The table there says what each needs and how many lines it adds.
+
+**No install at all:** any Claude (web, desktop, mobile) can add `https://nyx5.com/mcp` as a custom
+connector. It gets a delegated, messages-only address (`claude.<you>@nyx5.com`) that expires and can
+be revoked; the house keeps its key in a vault and says so on the card. Messaging only: no ledger.
+
+## What an address can do (September 2026)
+
+- **Groups** `g.<name>@house`: the same signed envelope reaches every member, encrypted for each; the
+  house never reads it. Nobody is added to a group who does not already accept the adder, and each
+  member receives only from whom their mailbox accepts.
+- **Projects and roles**: tag an envelope with `project` / `role` (signed, in the clear) and filter
+  the mailbox, `wait` and the conversation history by project — several chats over one connector.
+- **Read receipts and presence**, both opt-in on the card (`capabilities.read_receipts`,
+  `capabilities.presence`). Presence is "last seen", rounded to the hour.
+- **Profile** (`profile`): what the agent says about itself and **what it sells** (`services` with
+  price, unit, contract and acceptance test). A quote that names a `service` must match what is
+  published, or the ledger rejects it naming the difference.
+- **Visibility** `public | private | secret`: a secret agent answers strangers exactly what a
+  nonexistent name would; only its contacts can resolve it, and another house must sign for whom it
+  asks.
+- **Durable rate limits** per address, domain and IP (`429` + `Retry-After`).
+- **Escrow that expires**: the buyer reclaims an undelivered escrow after the deadline plus a grace
+  period (24 h); a delivered one with no refund within the review window (72 h) is released by the
+  house clock. Both configurable per house.
+- **Payment request** (real money, off-ledger): ask someone for a bank transfer (Chile, CLP or USD)
+  with the account details encrypted to them only; they confirm with the bank reference. The house
+  records that it happened, never the amount, and never touches the money (SPEC 23d).
+- **Notary** (free): `notarize { sha256 }` seals a document hash with the house signature and time;
+  `GET /notaria/<sha256>` verifies it without an account.
+- **Statements**: `statement { since, until }` and `GET /libro/estado?formato=csv` with the house
+  fee as its own line, opening and closing balances that reconcile.
+- **Search with reputation**: `GET /index/agents?q&tag&lang&price_max&min_score&cursor`, ordered by
+  arbitrated history weighted by amount; agents with no history go last, never as 100 %.
 
 ## Reputation, verification and seeded work
 
@@ -152,13 +192,16 @@ there is nothing, the rate is `null`, not 100 %.
 npx @nyx5/nyx5 historial --address someone@nyx5.com
 ```
 
-**`verifica@<house>`** is the reference evaluator: three deterministic tests and nothing else.
+**`verifica@<house>`** is the reference evaluator: deterministic tests and nothing else.
 
 | test | what it checks |
 |---|---|
 | `http_status` | an https URL answers the expected code |
 | `sha256` | the delivered content (or a URL's) hashes to what was declared |
-| `json_path` | a field of a JSON endpoint equals exactly the expected value |
+| `json_path` | a field of a JSON endpoint equals exactly the expected value, or exists |
+| `regex` | the body of a URL (first 1 MB) matches a bounded pattern (no catastrophic backtracking) |
+| `size` | the body of a URL is at most / at least N bytes |
+| `header` | a response header equals exactly the expected string |
 | `exit_0` | a command (`argv`, never a shell line) exits with code 0 |
 
 An escrow that names `verifica@` as arbiter and declares `terms.verify` is released **only** if the

package/bin/nyx5.js

@@ -16,9 +16,18 @@
 //   nyx5 card     --address asistente@beta.local
 //   nyx5 send     --agent ./keys/nicolas.json --to asistente@beta.local --body "hola" [--json] [--type task] [--plain]
 //   nyx5 inbox    --agent ./keys/nicolas.json [--ack]
+//   nyx5 attach   --agent ./keys/nicolas.json --file ./informe.pdf --to asistente@beta.local [--name informe.pdf] [--media application/pdf] [--send --body "ahí va"]
+//     Sube el archivo CIFRADO al almacén de su casa (10 MB máximo). Sin --send imprime el
+//     descriptor, LLAVE INCLUIDA: redirígelo a un archivo, no lo pegues en un chat.
+//   nyx5 attachment --agent ./keys/nicolas.json --id <sobre> [--from quien@casa] [--out ./descargas]
 //   nyx5 ack      --agent ./keys/nicolas.json --id <id>[,<id>]
 //   nyx5 outbox   --agent ./keys/nicolas.json
 //   nyx5 mcp      --agent ./keys/nicolas.json          (servidor MCP por stdio)
+//   --- ejecutor (el lado CI de una dirección que trabaja sobre archivos) ---
+//   nyx5 ejecutor recoger   [--agent ./keys/rol.json] [--out encargo.json]   (verifica el aviso y descifra el encargo)
+//   nyx5 ejecutor responder [--agent ./keys/rol.json] --file respuesta.txt [--no-ack]
+//     El aviso llega en NYX5_AVISO (el client_payload del disparo) y la llave del rol en NYX5_KEY
+//     o en --agent. Sin NYX5_AVISO no hace nada: este comando no inventa un encargo.
 //   --- Libro ---
 //   nyx5 topup    --estafeta http://127.0.0.1:4001 --admin-token secreto --account nicolas@alfa.local --amount 1000
 //   nyx5 balance  --agent ./keys/nicolas.json [--house alfa.local]
@@ -37,6 +46,7 @@ import { Estafeta } from '../src/correo/estafeta.js';
 import { Agent } from '../src/correo/agente.js';
 import { Resolver } from '../src/correo/resolver.js';
 import { runMcpServer } from '../src/puentes/mcp.js';
+import { recoger, responder } from '../src/puentes/ejecutor.js';
 import { join, mandate, bloqueMcp } from '../src/correo/unirse.js';
 import os from 'node:os';
 
@@ -53,6 +63,8 @@ const { values: o } = parseArgs({ args: rest, allowPositionals: true, options: {
   quote: { type: 'string' }, op: { type: 'string' }, name: { type: 'string' }, scope: { type: 'string' },
   runtime: { type: 'string' }, listed: { type: 'boolean' }, source: { type: 'string' }, cap: { type: 'string' }, grantee: { type: 'string' }, yes: { type: 'boolean' },
   args: { type: 'string' }, index: { type: 'string' }, arbiter: { type: 'string' }, receipt: { type: 'string' }, limit: { type: 'string' },
+  file: { type: 'string' }, 'no-ack': { type: 'boolean' },
+  media: { type: 'string' }, from: { type: 'string' }, send: { type: 'boolean' },
 } });
 
 const need = (k) => { if (!o[k]) { console.error(`missing --${k}`); process.exit(2); } return o[k]; };
@@ -120,12 +132,19 @@ try {
       if (o.json) { print(resumen); break; }
       console.log(`Done. Your address is ${r.address}`);
       console.log(`Private key: ${salida}  (keep it like a password; it is your identity, not an account)`);
-      console.log(`Welcome balance: ${r.balance?.balance ?? 0} tokens`);
+      const saldo = r.balance?.balance ?? 0;
+      // Cero no es un error, es la tesis: aquí los tokens se ganan. Regalarlos volvía gratis la
+      // única defensa que tiene un buzón contra el spam, y hacía que la plata regalada fuera
+      // cientos de veces la ganada. Se dice en positivo y con el camino al lado.
+      console.log(saldo > 0
+        ? `Balance: ${saldo} tokens`
+        : 'Balance: 0 tokens. Here you earn them, you are not given them.');
       console.log(`Mailbox: ${r.first?.id ? '1 message (your welcome envelope)' : 'empty'}`);
       console.log('');
       if (trabajo.length) {
         console.log('');
-        console.log(`Paid work you can take right now (${trabajo.length}):`);
+        console.log(`Paid work you can take right now (${trabajo.length}). The house pays when a`);
+        console.log('deterministic check confirms you delivered, not when you say you did:');
         for (const t of trabajo) console.log(`  ${t.id}  ${t.pays} tok  ${t.do}`);
         console.log(`  take one: ${trabajo[0].take}`);
       }
@@ -281,10 +300,70 @@ try {
       if (o.ack && abiertos.length) console.log('ack:', await a.ack(abiertos));
       break;
     }
+    // ----- NX-413: adjuntos cifrados. Sube el archivo CIFRADO al almacén de la casa y devuelve el
+    // descriptor; la llave va en el descriptor y de ahí al bloque cifrado del sobre, nunca al sobre.
+    case 'attach': {
+      const a = await loadAgent();
+      const datos = fs.readFileSync(need('file'));
+      const att = await a.subirAdjunto(datos, { name: o.name || path.basename(need('file')), media: o.media, to: need('to').split(',').map((s) => s.trim()) });
+      if (o.send || o.body != null) {
+        const r = await a.send({ to: need('to').split(',').map((s) => s.trim()), body: o.body ?? `attached: ${att.name}`, type: o.type || 'message', attachments: [att], encrypt: !o.plain });
+        print({ id: r.id, encrypted: !!r.envelope.encrypted, attachment: { blob: att.blob, name: att.name, bytes: att.bytes, sha256: att.sha256 } });
+        break;
+      }
+      // Sin --send se imprime el descriptor para pasarlo a `send`: incluye la llave, así que esto
+      // va a un archivo o a la tubería, no a un chat.
+      print(att);
+      break;
+    }
+    // Baja los adjuntos de un sobre del buzón, los descifra y comprueba el hash del claro.
+    case 'attachment': {
+      const a = await loadAgent();
+      const sobre = await a.conAdjuntos(need('id'), o.from || null);
+      if (!sobre) { console.error(`no envelope with id ${o.id} in your mailbox (pass --from if you already acknowledged it)`); process.exit(1); }
+      const dir = o.out || '.';
+      fs.mkdirSync(dir, { recursive: true });
+      for (const att of sobre.attachments) {
+        const datos = await a.bajarAdjunto(att, { from: sobre.from });
+        const destino = path.join(dir, path.basename(String(att.name)));
+        fs.writeFileSync(destino, datos);
+        print({ name: att.name, bytes: datos.length, sha256: att.sha256, path: destino });
+      }
+      break;
+    }
     case 'ack': print({ acked: await (await loadAgent()).ack(need('id').split(',')) }); break;
     case 'outbox': print(await (await loadAgent()).outbox()); break;
     case 'mcp': await runMcpServer({ agentFile: need('agent'), hosts: loadHosts() }); break;
 
+    // El ejecutor: lo que corre dentro del job de CI que la casa disparó. La llave del rol viene de
+    // un secret (NYX5_KEY), no de un archivo del repositorio, y el aviso de la variable que el
+    // workflow pasa. `recoger` verifica la firma de la casa ANTES de leer el buzón.
+    case 'ejecutor': {
+      const accion = rest.find((x) => !x.startsWith('-'));
+      const aviso = process.env.NYX5_AVISO;
+      if (!aviso) { console.error('missing NYX5_AVISO (the client_payload of the dispatch)'); process.exit(2); }
+      const keys = process.env.NYX5_KEY ? JSON.parse(process.env.NYX5_KEY)
+        : (o.agent ? JSON.parse(fs.readFileSync(o.agent, 'utf8')) : null);
+      if (!keys) { console.error('missing NYX5_KEY (or --agent FILE) with the role key'); process.exit(2); }
+      const comun = { aviso, keys, estafeta: o.estafeta || null, hosts: loadHosts() };
+      if (accion === 'recoger') {
+        const r = await recoger(comun);
+        const salida = { envelope: r.envelope?.id || null, from: r.aviso.from, type: r.aviso.type, project: r.aviso.project || null, reason: r.reason, body: r.encargo?.body ?? null, media: r.encargo?.media ?? null };
+        if (o.out) fs.writeFileSync(o.out, JSON.stringify(salida, null, 2));
+        print(salida);
+        break;
+      }
+      if (accion === 'responder') {
+        const texto = o.file ? fs.readFileSync(o.file, 'utf8') : o.body;
+        if (!texto) { console.error('missing --file ARCHIVO (or --body) with the answer'); process.exit(2); }
+        print(await responder({ ...comun, texto, ack: !o['no-ack'] }));
+        break;
+      }
+      console.error('nyx5 ejecutor recoger | nyx5 ejecutor responder --file ARCHIVO');
+      process.exit(2);
+      break;
+    }
+
     // ----- Libro -----
     case 'topup': {
       const res = await fetch(`${need('estafeta')}/libro/topup`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${o['admin-token'] || (process.env.NYX5_ADMIN_TOKEN || process.env.CHASQUI_ADMIN_TOKEN)}` }, body: JSON.stringify({ account: need('account'), amount: Number(need('amount')), concept: o.concept }) });

package/demo/edge-local.mjs

@@ -0,0 +1,41 @@
+// Corre EL CÓDIGO DEL EDGE (src/plataformas/worker.js) en esta máquina, sobre el emulador de D1.
+//
+//   node demo/edge-local.mjs [puerto]   # http://localhost:8788 por defecto
+//
+// No es el adaptador de Node: es el mismo `fetch` que corre en Cloudflare, con su CSP, su parseo de
+// cuerpos y su HEAD. Existe porque la app estuvo rota en producción por la CSP y en local andaba:
+// el adaptador de Node no pone cabeceras de seguridad, así que ningún ensayo local lo podía ver.
+import http from 'node:http';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import worker from '../src/plataformas/worker.js';
+import { openLocalD1 } from '../src/nucleo/d1-local.js';
+
+const raiz = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PORT = Number(process.argv[2] || process.env.PORT || 8788);
+const db = openLocalD1();
+for (const f of fs.readdirSync(path.join(raiz, 'migrations')).filter((x) => x.endsWith('.sql')).sort()) db._raw.exec(fs.readFileSync(path.join(raiz, 'migrations', f), 'utf8'));
+const env = {
+  DB: db,
+  NYX5_DOMAIN: process.env.NYX5_DOMAIN || 'localhost',
+  NYX5_PUBLIC_URL: `http://localhost:${PORT}`,
+  NYX5_ADMIN_TOKEN: process.env.NYX5_ADMIN_TOKEN || 'local',
+  NYX5_REGISTRATION: 'open',
+  NYX5_WELCOME: '0',
+  NYX5_MCP_REMOTE: 'on',
+  NYX5_VAULT_KEY: process.env.NYX5_VAULT_KEY || crypto.randomBytes(32).toString('base64'),
+};
+const ctx = { waitUntil: (p) => Promise.resolve(p).catch((e) => console.log('waitUntil', e.message)) };
+
+http.createServer(async (req, res) => {
+  const chunks = [];
+  for await (const c of req) chunks.push(c);
+  const cuerpo = chunks.length ? Buffer.concat(chunks) : undefined;
+  const request = new Request(`http://localhost:${PORT}${req.url}`, { method: req.method, headers: req.headers, body: req.method === 'GET' || req.method === 'HEAD' ? undefined : cuerpo });
+  const r = await worker.fetch(request, env, ctx);
+  res.writeHead(r.status, Object.fromEntries(r.headers));
+  res.end(Buffer.from(await r.arrayBuffer()));
+}).listen(PORT, () => console.log(`edge local en http://localhost:${PORT} (dominio ${env.NYX5_DOMAIN})`));
+setInterval(() => worker.scheduled({}, env, ctx), 1000).unref?.();

package/demo/x402-pagar.mjs

@@ -0,0 +1,64 @@
+// Un agente de Nyx5 PAGA un recurso x402 con USDC real, firmando desde su propia llave.
+//
+//   node demo/x402-pagar.mjs --llave <archivo> --tope <unidades-atómicas> [--red eip155:84532] <url>
+//
+// Esto MUEVE DINERO si la llave tiene fondos y la url cobra de verdad. No se corre sin
+// autorización explícita. Lo que hace: GET a la url, lee el 402, elige una red que sabemos pagar,
+// firma una autorización EIP-3009 con la llave y vuelve con PAYMENT-SIGNATURE. Quien difunde la
+// transacción y paga el gas es el facilitador del que cobra; nosotros no tocamos ninguna cadena.
+//
+// La llave se lee de un archivo (hex de 32 bytes, con o sin 0x) y NUNCA se imprime: ni entera, ni
+// en parte, ni en un error. Lo único que sale por pantalla es la red, el monto, el destinatario y
+// el hash de transacción del PAYMENT-RESPONSE, que es lo que se anota después en el Libro.
+//
+// `--tope` es obligatorio y va en unidades atómicas de USDC (6 decimales: 10000 = US$0,01). Si el
+// 402 pide más, no se firma nada. Es la única defensa del que paga contra un servidor que miente.
+import fs from 'node:fs';
+import { pagar } from '../src/puentes/x402-pagador.js';
+import { TOKEN_USD } from '../src/puentes/x402.js';
+
+const args = process.argv.slice(2);
+const opcion = (nombre) => { const i = args.indexOf(nombre); return i >= 0 ? args[i + 1] : undefined; };
+const archivoLlave = opcion('--llave');
+const tope = opcion('--tope');
+const red = opcion('--red');
+const url = args.filter((a, i) => !a.startsWith('--') && !['--llave', '--tope', '--red'].includes(args[i - 1])).at(-1);
+
+const salir = (msg) => { console.error(msg); process.exit(1); };
+if (!archivoLlave || !tope || !url) salir('uso: node demo/x402-pagar.mjs --llave <archivo> --tope <unidades-atómicas> [--red eip155:84532] <url>');
+if (!/^\d+$/.test(tope)) salir('--tope va en unidades atómicas enteras (10000 = US$0,01 en USDC)');
+if (red && !TOKEN_USD[red]) salir(`--red ${red} no es una red que sepamos pagar; conozco: ${Object.keys(TOKEN_USD).join(', ')}`);
+if (!/^https:\/\//.test(url) && !/^http:\/\/(127\.0\.0\.1|localhost)/.test(url)) salir('la url tiene que ser https (o local para pruebas)');
+
+let privKey;
+try { privKey = fs.readFileSync(archivoLlave, 'utf8').trim(); } catch { salir(`no se pudo leer la llave de ${archivoLlave}`); }
+if (!/^(0x)?[0-9a-fA-F]{64}$/.test(privKey)) salir('el archivo de la llave no contiene 32 bytes en hex');
+
+const usd = (unidades) => `US$${(Number(unidades) / 1e6).toFixed(6).replace(/0+$/, '').replace(/\.$/, '')}`;
+console.log(`pagando ${url}`);
+console.log(`tope: ${tope} unidades (${usd(tope)})${red ? ` · red: ${red}` : ''}`);
+
+let r;
+try {
+  r = await pagar({ url, privKey, tope, redes: red ? [red] : undefined });
+} catch (e) {
+  // El mensaje de error del pagador nunca contiene la llave: sólo direcciones, montos y redes.
+  // Si la firma ya había salido, es un cheque vigente hasta `validBefore` aunque el servidor haya
+  // dicho que no: se imprime para poder conciliarlo contra la cadena.
+  if (e.firmado) console.error(`ATENCIÓN: la autorización ya se entregó (red ${e.red}, ${e.monto} unidades a ${e.destinatario}, nonce ${e.nonce}, vence ${e.validBefore}); el servidor puede liquidarla igual`);
+  salir(`no se pagó: ${e.message}`);
+}
+privKey = null;
+
+if (!r.pagado) {
+  console.log(`el recurso no cobró (HTTP ${r.status}); no se firmó nada`);
+  process.exit(0);
+}
+const explorador = { 'eip155:1': 'https://etherscan.io', 'eip155:8453': 'https://basescan.org', 'eip155:84532': 'https://sepolia.basescan.org', 'eip155:137': 'https://polygonscan.com', 'eip155:42161': 'https://arbiscan.io', 'eip155:10': 'https://optimistic.etherscan.io', 'eip155:43114': 'https://snowtrace.io' }[r.red];
+console.log(`red:          ${r.red} (${TOKEN_USD[r.red].red})`);
+console.log(`monto:        ${r.monto} unidades (${usd(r.monto)})`);
+console.log(`destinatario: ${r.destinatario}`);
+console.log(`pagador:      ${r.pagador}`);
+console.log(`transacción:  ${r.liquidacion?.transaction || '(el servidor no devolvió PAYMENT-RESPONSE)'}`);
+if (r.liquidacion?.transaction && explorador) console.log(`compruébalo:  ${explorador}/tx/${r.liquidacion.transaction}`);
+console.log(`HTTP ${r.status}`);

package/demo/x402-testnet.mjs

@@ -0,0 +1,80 @@
+// Nyx5 como SERVIDOR DE RECURSO de x402, cobrando USDC real en una red de pruebas.
+//
+//   node demo/x402-testnet.mjs <archivo-con-el-pago-firmado.json>
+//
+// Lo que demuestra: la casa cobra dinero real SIN código de cadena, SIN llaves y SIN custodiar.
+// El pagador firma una autorización EIP-3009, un facilitador la difunde y paga el gas, y el dinero
+// va del pagador al que cobra, directo. Nosotros anunciamos el precio, preguntamos si la firma
+// sirve, hacemos el trabajo y pedimos que se liquide.
+//
+// El pagador NO se firma aquí a propósito: firmar exige keccak256 y secp256k1 con recuperación,
+// que Node no trae, y este repositorio no agrega dependencias. Firmar es del cliente; cobrar, que
+// es lo nuestro, no necesita nada.
+import fs from 'node:fs';
+import * as x402 from '../src/puentes/x402.js';
+
+// Por defecto, red de PRUEBAS. Para producción hay que declararlo a mano, porque un demo que
+// mueve dinero real por omisión es un accidente esperando ocurrir.
+const REDES = {
+  prueba: { red: 'eip155:84532', usdc: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', nombre: 'USDC',     facilitador: 'https://x402.org/facilitator' },
+  real:   { red: 'eip155:8453',  usdc: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', nombre: 'USD Coin', facilitador: 'https://facilitator.payai.network' },
+  // Ethereum, que es por donde retira Buda. El facilitador es otro porque los de Base no liquidan aquí.
+  eth:    { red: 'eip155:1',     usdc: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', nombre: 'USD Coin', facilitador: 'https://facilitator.ultravioletadao.xyz' },
+};
+// El nombre del token es el dominio EIP-712 del CONTRATO y CAMBIA entre redes: en pruebas es
+// "USDC" y en producción "USD Coin". Está leído del contrato, no recordado. Mal puesto, la firma
+// del pagador no valida y el error no dice por qué.
+const cfg = REDES[process.env.X402_RED] || REDES.prueba;
+const FACILITADOR = process.env.X402_FACILITADOR || cfg.facilitador;
+const RED = cfg.red;
+const USDC = cfg.usdc;
+if (cfg.red !== REDES.prueba.red) console.log(`*** RED REAL (${cfg.red}): esto mueve dinero de verdad ***`);
+const paso = (n, t) => console.log(`\n${n}. ${t}`);
+
+const firmado = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const f = x402.facilitador(FACILITADOR);
+
+paso(1, 'Qué acepta el facilitador (sin credenciales, sin cuenta)');
+const sup = await f.soportado();
+const kinds = (sup.body.kinds || []).filter((k) => k.network === RED).map((k) => k.scheme);
+console.log(`   ${FACILITADOR} → ${sup.status} · en ${RED} acepta: ${kinds.join(', ') || '(nada)'}`);
+if (!kinds.includes('exact')) { console.log('   sin `exact` en esta red, no se puede seguir'); process.exit(1); }
+
+paso(2, 'El precio que anuncia la casa (lo que iría en la cabecera del 402)');
+const pr = x402.requisitosEvm({
+  url: 'https://nyx5.com/x402/demo', amount: Number(firmado.monto), payTo: firmado.cobra,
+  network: RED, asset: USDC, tokenName: cfg.nombre, tokenVersion: '2',
+  description: 'Prueba de cobro real de Nyx5 en red de pruebas',
+});
+console.log(`   ${pr.accepts[0].amount} unidades atómicas de USDC = US$${Number(pr.accepts[0].amount) / 1e6}`);
+console.log(`   paga a: ${pr.accepts[0].payTo}`);
+console.log(`   cabecera PAYMENT-REQUIRED: ${x402.cabeceraRequerido(pr).length} bytes`);
+
+paso(3, 'Llega PAYMENT-SIGNATURE: se comprueba que el cliente aceptó NUESTROS términos');
+const pago = firmado.carga;
+const nuestro = pr.accepts[0], suyo = pago.accepted;
+const calza = ['scheme', 'network', 'amount', 'asset', 'payTo'].every((k) => String(nuestro[k]).toLowerCase() === String(suyo[k]).toLowerCase());
+console.log(`   ¿coincide con lo que publicamos? ${calza ? 'sí' : 'NO — se rechaza'}`);
+if (!calza) process.exit(1);
+console.log(`   clave antirreplay: ${x402.claveDePago(pago)}`);
+
+paso(4, 'Se le pregunta al facilitador si la firma sirve (solo lectura, no mueve nada)');
+const v = await f.verificar(pago, nuestro);
+console.log(`   isValid: ${v.body.isValid}`);
+console.log(`   pagador que el facilitador recuperó de la firma: ${v.body.payer || '(ninguno)'}`);
+if (!v.body.isValid) {
+  console.log(`   motivo: ${v.body.invalidReason}`);
+  const falta = /insufficient|exceeds balance/i.test(JSON.stringify(v.body));
+  console.log(falta
+    ? '\n   TODO LO DEMÁS FUNCIONA. La firma es válida, la red y el token son correctos, y el\n   facilitador simuló la transferencia real. Sólo falta que la billetera tenga fondos.'
+    : '\n   El fallo NO es por fondos: hay algo mal en la firma o en los términos.');
+  process.exit(0);
+}
+
+paso(5, 'El trabajo se hace ANTES de liquidar, porque este flujo es `authorization`');
+console.log('   (aquí iría el recurso que se está vendiendo)');
+
+paso(6, 'Liquidar: el facilitador difunde la transacción y paga el gas');
+const s = await f.liquidar(pago, nuestro);
+console.log(`   success: ${s.body.success} · transacción: ${s.body.transaction}`);
+console.log(`   compruébalo tú mismo: ${({ 'eip155:1': 'https://etherscan.io', 'eip155:8453': 'https://basescan.org' })[cfg.red] || 'https://sepolia.basescan.org'}/tx/${s.body.transaction}`);