@nyx5/nyx5 0.6.0 → 0.8.0

package/src/puentes/x402-pagador.js

@@ -0,0 +1,248 @@
+// Nyx5/1 — Pagador x402: que un agente PAGUE un recurso que cobra en USDC sobre una red EVM.
+//
+// La casa ya sabía cobrar (src/puentes/x402.js): anunciar el precio en un 402, preguntarle al
+// facilitador si la firma sirve y pedir que liquide. Eso no necesita criptografía de cadena.
+// Pagar sí: el pagador firma una autorización EIP-3009 (`TransferWithAuthorization`) sobre el
+// contrato del token, con tipado EIP-712, y esa firma exige keccak256 y secp256k1 con
+// recuperación, que Node no trae. Ahora están en src/nucleo/keccak.js y src/nucleo/secp256k1.js.
+//
+// Cómo se protege el que paga, porque una firma es dinero:
+//   - `tope` es OBLIGATORIO y va en unidades atómicas. Si el 402 pide más, no se firma. Es el
+//     `max_per_charge` de un mandato, pero del lado de la cadena: el agente no decide cuánto vale
+//     el recurso, decide cuánto está dispuesto a perder si el servidor miente.
+//   - El nonce son 32 bytes aleatorios por autorización. El contrato de USDC rechaza un nonce
+//     repetido, así que una autorización sólo puede liquidarse UNA vez, aunque el servidor la
+//     reintente o la filtre.
+//   - `validBefore` nunca pasa de ahora + 5 minutos. Una autorización firmada es un cheque al
+//     portador hasta que vence; cuanto menos viva, menos vale robarla.
+//   - El dominio EIP-712 (name, version, chainId, contrato) sale de `TOKEN_USD`, la tabla que ya
+//     está LEÍDA de cada contrato. No se copia ni se acepta lo que diga el 402: si el servidor
+//     anuncia un `asset` o un `name` que no coincide con el USDC de esa red, se rechaza ANTES de
+//     firmar. Firmar contra un dominio que dicta el cobrador es firmar lo que él quiera.
+//   - `from` tiene que ser la dirección de la llave. Firmar una autorización con otro `from` no
+//     mueve la plata del otro; sólo produce una firma inválida, y el error no diría por qué.
+//
+// Este módulo NO habla con ninguna red ni facilitador: firma y manda cabeceras HTTP al servidor
+// del recurso. Quien difunde la transacción y paga el gas es el facilitador del cobrador.
+
+import { randomBytes } from 'node:crypto';
+import { keccak256, aHex, deHex } from '../nucleo/keccak.js';
+import { firmar, direccionDe, recuperarDireccion } from '../nucleo/secp256k1.js';
+import { TOKEN_USD, X402_VERSION } from './x402.js';
+
+export const TIPO_DOMINIO = 'EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)';
+export const TIPO_TRANSFER = 'TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)';
+export const VIGENCIA_MAX_S = 300;   // validBefore ≤ ahora + 5 min
+export const TOLERANCIA_RELOJ_S = 600; // validAfter = ahora − 10 min, como el cliente de referencia de x402
+
+const DIRECCION = /^0x[0-9a-fA-F]{40}$/;
+const NONCE = /^0x[0-9a-fA-F]{64}$/;
+const ENTERO = /^\d+$/;
+
+// ---- codificación EIP-712 ----
+const concat = (...partes) => {
+  const total = partes.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(total);
+  let i = 0;
+  for (const p of partes) { out.set(p, i); i += p.length; }
+  return out;
+};
+const uint256 = (n) => deHex(BigInt(n).toString(16).padStart(64, '0'));
+const direccion32 = (a) => {
+  if (!DIRECCION.test(String(a))) throw new Error(`x402 pagador: dirección inválida "${String(a).slice(0, 20)}"`);
+  return deHex(String(a).slice(2).padStart(64, '0'));
+};
+const entero = (v, nombre) => {
+  const s = typeof v === 'bigint' ? v.toString() : String(v);
+  if (!ENTERO.test(s)) throw new Error(`x402 pagador: ${nombre} debe ser un entero sin signo en unidades atómicas`);
+  return s;
+};
+
+// La entrada de TOKEN_USD para una red, o null. `Object.hasOwn`: una red llamada `constructor` o
+// `__proto__` no es una red, y `TOKEN_USD[red]` la encontraría en el prototipo.
+const tokenDe = (network) => (typeof network === 'string' && Object.hasOwn(TOKEN_USD, network)) ? TOKEN_USD[network] : null;
+
+// El dominio EIP-712 del contrato de USDC en una red. Sale de la tabla leída de los contratos.
+export function dominioDe(network) {
+  const t = tokenDe(network);
+  if (!t) throw new Error(`x402 pagador: no sé pagar en ${network}; conozco: ${Object.keys(TOKEN_USD).join(', ')}`);
+  const m = /^eip155:(\d+)$/.exec(network);
+  if (!m) throw new Error(`x402 pagador: ${network} no es una red EVM`);
+  return { name: t.name, version: t.version, chainId: BigInt(m[1]), verifyingContract: t.asset };
+}
+
+export function separadorDeDominio({ name, version, chainId, verifyingContract }) {
+  return keccak256(concat(
+    keccak256(TIPO_DOMINIO),
+    keccak256(String(name)),
+    keccak256(String(version)),
+    uint256(chainId),
+    direccion32(verifyingContract),
+  ));
+}
+
+export function hashAutorizacion({ from, to, value, validAfter, validBefore, nonce }) {
+  if (!NONCE.test(String(nonce))) throw new Error('x402 pagador: nonce debe ser 0x + 32 bytes en hex');
+  return keccak256(concat(
+    keccak256(TIPO_TRANSFER),
+    direccion32(from),
+    direccion32(to),
+    uint256(entero(value, 'value')),
+    uint256(entero(validAfter, 'validAfter')),
+    uint256(entero(validBefore, 'validBefore')),
+    deHex(nonce),
+  ));
+}
+
+// El digest que firma el pagador: keccak256(0x19 0x01 ‖ dominio ‖ hashStruct(mensaje)).
+export function digestAutorizacion({ network, dominio, ...auth }) {
+  const dom = dominio || dominioDe(network);
+  return keccak256(concat(new Uint8Array([0x19, 0x01]), separadorDeDominio(dom), hashAutorizacion(auth)));
+}
+
+// ---- firmar ----
+// Devuelve { authorization, signature, digest }, con `authorization` en el formato exacto que el
+// esquema `exact` de x402 sobre EVM pone en `payload.authorization` (todo cadenas).
+export function firmarAutorizacion({ network, from, to, value, validAfter, validBefore, nonce, privKey }) {
+  if (!privKey) throw new Error('x402 pagador: falta privKey');
+  const propia = direccionDe(privKey);
+  if (String(from).toLowerCase() !== propia.toLowerCase()) throw new Error(`x402 pagador: from (${from}) no es la dirección de la llave (${propia})`);
+  const authorization = {
+    from: propia, to: String(to),
+    value: entero(value, 'value'),
+    validAfter: entero(validAfter, 'validAfter'),
+    validBefore: entero(validBefore, 'validBefore'),
+    nonce: String(nonce).toLowerCase(),
+  };
+  if (BigInt(authorization.validBefore) <= BigInt(authorization.validAfter)) throw new Error('x402 pagador: validBefore debe ser mayor que validAfter');
+  const digest = digestAutorizacion({ network, ...authorization });
+  const { firmaHex } = firmar(digest, privKey);
+  return { authorization, signature: firmaHex, digest: '0x' + aHex(digest) };
+}
+
+// La contraparte de firmar: qué dirección produjo esta autorización en esta red. Es lo que hace
+// un facilitador en `/verify`, y lo que usa la prueba para demostrar que la firma es de `from`.
+export function recuperarPagador({ network, authorization, signature }) {
+  return recuperarDireccion(digestAutorizacion({ network, ...authorization }), signature);
+}
+
+// ---- elegir qué pagar ----
+// De un PAYMENT-REQUIRED, la primera entrada `exact` en una red EVM que sabemos pagar (y que esté
+// en `redes`, si se acotó). Se comprueba que el 402 describa el USDC REAL de esa red: `asset` y el
+// dominio del token (`extra.name`/`extra.version`) tienen que coincidir con la tabla leída de los
+// contratos. Un servidor que anuncie otro contrato u otro nombre no consigue una firma.
+export function elegirRequisito(pr, { redes } = {}) {
+  if (pr?.x402Version !== X402_VERSION) throw new Error(`x402 pagador: x402Version ${pr?.x402Version}, se esperaba ${X402_VERSION}`);
+  if (!Array.isArray(pr.accepts) || !pr.accepts.length) throw new Error('x402 pagador: el 402 no trae accepts');
+  const permitidas = redes ? new Set(redes) : null;
+  const motivos = [];
+  for (const a of pr.accepts) {
+    if (a?.scheme !== 'exact') { motivos.push(`${a?.network}: scheme ${a?.scheme}`); continue; }
+    const t = tokenDe(a.network);
+    if (!t) { motivos.push(`${a.network}: red que no sé pagar`); continue; }
+    if (permitidas && !permitidas.has(a.network)) { motivos.push(`${a.network}: fuera de las redes permitidas`); continue; }
+    if (String(a.asset).toLowerCase() !== t.asset.toLowerCase()) { motivos.push(`${a.network}: asset ${a.asset} no es el USDC de esa red`); continue; }
+    const nombre = a.extra?.name, version = a.extra?.version;
+    if ((nombre != null && nombre !== t.name) || (version != null && String(version) !== t.version)) { motivos.push(`${a.network}: dominio del token ${nombre}/${version} no es ${t.name}/${t.version}`); continue; }
+    if (!DIRECCION.test(String(a.payTo))) { motivos.push(`${a.network}: payTo no es una dirección EVM`); continue; }
+    if (typeof a.amount !== 'string' || !ENTERO.test(a.amount)) { motivos.push(`${a.network}: amount no es una cadena de unidades atómicas`); continue; }
+    return a;
+  }
+  throw new Error(`x402 pagador: ninguna forma de pago sirve: ${motivos.join('; ') || 'accepts vacío'}`);
+}
+
+// ---- armar el PAYMENT-SIGNATURE ----
+// `tope` es obligatorio: la decisión de cuánto se está dispuesto a pagar es del agente, no del 402.
+export function armarPago({ requisito, privKey, tope, ahora = Math.floor(Date.now() / 1000), nonce }) {
+  if (tope == null) throw new Error('x402 pagador: tope (unidades atómicas) es obligatorio');
+  const limite = BigInt(entero(tope, 'tope'));
+  const monto = BigInt(entero(requisito?.amount, 'amount'));
+  if (monto > limite) throw new Error(`x402 pagador: el precio (${monto}) supera el tope (${limite}); no se firma`);
+  if (!tokenDe(requisito.network)) throw new Error(`x402 pagador: no sé pagar en ${requisito.network}`);
+  // La vigencia que pide el servidor sólo puede ACORTAR los 5 minutos: un `maxTimeoutSeconds`
+  // negativo, no numérico o fraccionario no se obedece (un negativo firmaba un cheque ya vencido).
+  const pedida = Number(requisito.maxTimeoutSeconds);
+  const vigencia = Number.isFinite(pedida) && pedida >= 1 ? Math.min(Math.floor(pedida), VIGENCIA_MAX_S) : VIGENCIA_MAX_S;
+  const from = direccionDe(privKey);
+  const { authorization, signature } = firmarAutorizacion({
+    network: requisito.network,
+    from, to: requisito.payTo, value: monto,
+    validAfter: Math.max(0, ahora - TOLERANCIA_RELOJ_S),
+    validBefore: ahora + vigencia,
+    nonce: nonce || '0x' + randomBytes(32).toString('hex'),
+    privKey,
+  });
+  // `accepted` viaja tal cual llegó: el servidor compara contra lo que publicó.
+  return { x402Version: X402_VERSION, accepted: requisito, payload: { signature, authorization } };
+}
+
+const b64 = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64');
+// El mismo pago con la forma de la v1 de x402 (scheme y network en la raíz): lo que leen los servidores
+// que sólo miran X-PAYMENT. `accepted` viaja igual: un lector v2 lo encuentra donde lo espera.
+export const cabeceraV1 = (pago) => ({ x402Version: 1, scheme: pago.accepted.scheme, network: pago.accepted.network, payload: pago.payload, accepted: pago.accepted });
+const deB64 = (s) => JSON.parse(Buffer.from(String(s), 'base64').toString('utf8'));
+
+async function leerCuerpo(r) {
+  const txt = await r.text();
+  try { return JSON.parse(txt); } catch { return txt; }
+}
+
+// ---- pagar ----
+// GET url → 402 con PAYMENT-REQUIRED → elegir → firmar → GET con PAYMENT-SIGNATURE → cuerpo y
+// PAYMENT-RESPONSE. Si la primera respuesta no es 402, se devuelve tal cual sin firmar nada.
+//
+// Se firma UNA vez, contra el primer 402. Si el servidor contesta con otro 402 (otro `payTo`, otro
+// precio, "sin fondos"), no se vuelve a firmar: se lanza. Y como la firma ya salió del proceso, es
+// un cheque que el servidor puede cobrar hasta que venza aunque haya dicho que no: todo error que
+// ocurra DESPUÉS de entregarla lleva `firmado: true`, `nonce`, `red`, `monto`, `destinatario` y
+// `pagador`, para que quien paga lo anote y concilie. `alFirmar(entregado)` se llama ANTES de
+// mandar la firma: es el sitio para escribir el registro antes del paso, no después.
+export async function pagar({ url, privKey, tope, fetch: fetchImpl = globalThis.fetch, redes, method = 'GET', headers = {}, body, timeoutMs = 30_000, alFirmar = null }) {
+  if (!url) throw new Error('x402 pagador: falta url');
+  if (tope == null) throw new Error('x402 pagador: tope (unidades atómicas) es obligatorio');
+  const pedir = (extra = {}) => fetchImpl(url, { method, headers: { ...headers, ...extra }, body, signal: AbortSignal.timeout(timeoutMs) });
+
+  const primera = await pedir();
+  if (primera.status !== 402) return { pagado: false, status: primera.status, body: await leerCuerpo(primera) };
+
+  const cabecera = primera.headers.get('payment-required');
+  if (!cabecera) throw new Error('x402 pagador: 402 sin cabecera PAYMENT-REQUIRED');
+  let pr;
+  try { pr = deB64(cabecera); } catch { throw new Error('x402 pagador: PAYMENT-REQUIRED no es JSON en base64'); }
+  const requisito = elegirRequisito(pr, { redes });
+  const pago = armarPago({ requisito, privKey, tope });
+  const entregado = {
+    firmado: true,
+    red: requisito.network,
+    monto: requisito.amount,
+    destinatario: requisito.payTo,
+    pagador: pago.payload.authorization.from,
+    nonce: pago.payload.authorization.nonce,
+    validBefore: pago.payload.authorization.validBefore,
+  };
+  if (alFirmar) await alFirmar(entregado);
+
+  try {
+    // Dos cabeceras con el mismo cheque: PAYMENT-SIGNATURE (v2, con accepted) y X-PAYMENT con el cuerpo de
+    // la v1 (scheme y network arriba). Medido el 14-sep-2026 contra 402milly: un servidor que lee X-PAYMENT
+    // contesta el MISMO 402 sin motivo si sólo va la v2. Mandar las dos no cuesta nada y la firma es una.
+    const segunda = await pedir({ 'PAYMENT-SIGNATURE': b64(pago), 'X-PAYMENT': b64(cabeceraV1(pago)) });
+    const cuerpo = await leerCuerpo(segunda);
+    let liquidacion = null;
+    const respuesta = segunda.headers.get('payment-response');
+    if (respuesta) { try { liquidacion = deB64(respuesta); } catch { liquidacion = null; } }
+    if (segunda.status === 402) {
+      let motivo = '';
+      try { motivo = deB64(segunda.headers.get('payment-required') || '').error || ''; } catch { /* sin motivo */ }
+      // El motivo puede venir en el cuerpo JSON (details/error), no en la cabecera: 402milly lo hace así.
+      // El cuerpo con `details` manda: la cabecera suele repetir el genérico «Payment required».
+      const detalle = cuerpo && typeof cuerpo === 'object' ? [cuerpo.error, cuerpo.details].filter((x) => typeof x === 'string' && x).join(': ') : '';
+      if (detalle && (typeof cuerpo.details === 'string' || !motivo)) motivo = detalle;
+      throw new Error(`x402 pagador: el servidor rechazó el pago${motivo ? `: ${motivo}` : ''}`);
+    }
+    return { pagado: true, status: segunda.status, body: cuerpo, liquidacion, ...entregado };
+  } catch (e) {
+    const err = e instanceof Error ? e : new Error(String(e));
+    throw Object.assign(err, entregado);
+  }
+}

package/src/puentes/x402.js

@@ -0,0 +1,266 @@
+// Nyx5/1 — Adaptador x402 (transporte HTTP v2).
+//
+// x402 es el estándar de "402 Payment Required" para agentes: el servidor responde 402 con lo que
+// cuesta el recurso, el cliente vuelve con la prueba de pago, el servidor responde 200 con el
+// recibo de liquidación. Todo el protocolo viaja en CABECERAS, en base64; el cuerpo es asunto de
+// cada implementación.
+//
+// Qué hace este módulo y qué NO hace:
+//   SÍ  habla el cable de x402 v2: arma `PAYMENT-REQUIRED`, lee `PAYMENT-SIGNATURE`, arma
+//       `PAYMENT-RESPONSE`, y declara capacidades en /x402/supported.
+//   NO  inventa dinero nuevo. El pago sigue ocurriendo en el Libro, con un sobre firmado, como
+//       siempre. x402 es el ANUNCIO del precio y el RECIBO de la liquidación, no una vía paralela
+//       para mover tokens sin firma (eso rompería el invariante 2).
+//
+// Por qué `nyx5:1` y no `nyx5:<casa>`: CAIP-2 exige `namespace:reference` con
+// namespace [-a-z0-9]{3,8} y reference [-_a-zA-Z0-9]{1,32}. Un dominio lleva puntos, y el punto
+// NO es legal en una reference. Así que la red es el protocolo y la casa viaja en `payTo`, que ya
+// es `agente@dominio`. Poner `nyx5:nyx5-com` sería una reference inventada que nadie sabe deshacer.
+//
+// Precedente de que esto es conforme sin blockchain: `cloudflare:402` en el repo oficial de x402
+// liquida en fiat, firma con Ed25519, no emite hash de transacción y no usa facilitador externo.
+// Ver docs/interop/x402.md, que dice también qué NO reclamamos.
+
+export const X402_VERSION = 2;
+export const RED = 'nyx5:1';
+export const ACTIVO = 'NYX';           // el token de la casa: ni contrato ni ISO-4217, y se dice
+export const CAIP2 = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/;
+
+const b64 = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64');
+const deB64 = (s) => JSON.parse(Buffer.from(String(s), 'base64').toString('utf8'));
+
+// El importe va como CADENA de unidades atómicas. Un number aquí es un defecto: 2^53 y los
+// decimales de coma flotante no son opinables cuando lo que se transporta es plata.
+const monto = (n) => {
+  if (!Number.isInteger(n) || n < 0) throw new Error(`x402: amount must be a non-negative integer, got ${n}`);
+  return String(n);
+};
+
+// ---- lo que el servidor anuncia: 402 + PAYMENT-REQUIRED ----
+export function requisitos({ url, amount, payTo, description, mimeType = 'application/json', flow = 'authorization', method = 'nyx5-envelope', error, serviceName, tags }) {
+  if (!url) throw new Error('x402: resource.url is required');
+  if (!payTo) throw new Error('x402: payTo is required');
+  const pr = {
+    x402Version: X402_VERSION,
+    error: error || 'PAYMENT-SIGNATURE header is required',
+    resource: { url, mimeType, ...(description ? { description } : {}), ...(serviceName ? { serviceName: serviceName.slice(0, 32) } : {}), ...(tags?.length ? { tags: tags.slice(0, 5).map((t) => String(t).slice(0, 32)) } : {}) },
+    accepts: [{
+      scheme: 'exact',
+      network: RED,
+      amount: monto(amount),
+      asset: ACTIVO,
+      payTo,
+      maxTimeoutSeconds: 60,
+      // `paymentFlow` y `assetTransferMethod` son claves RESERVADAS por el protocolo dentro de
+      // `extra`; el resto de `extra` es del scheme. No inventar ahí.
+      extra: { paymentFlow: flow, assetTransferMethod: method, house: payTo.split('@')[1] || null },
+    }],
+    extensions: {},
+  };
+  validarRequisitos(pr);
+  return pr;
+}
+
+// Falla cerrado: si el objeto que vamos a publicar no cumple las reglas duras del spec, mejor
+// romper aquí que emitir un 402 que un cliente conforme rechaza sin decir por qué.
+export function validarRequisitos(pr) {
+  if (pr.x402Version !== X402_VERSION) throw new Error(`x402: x402Version must be ${X402_VERSION}`);
+  if (!pr.resource?.url) throw new Error('x402: resource.url is required');
+  if (!Array.isArray(pr.accepts) || !pr.accepts.length) throw new Error('x402: accepts must be a non-empty array');
+  for (const a of pr.accepts) {
+    for (const campo of ['scheme', 'network', 'amount', 'asset', 'payTo']) if (!a[campo]) throw new Error(`x402: accepts[].${campo} is required`);
+    if (typeof a.amount !== 'string' || !/^\d+$/.test(a.amount)) throw new Error('x402: amount must be a string of atomic units');
+    if (!CAIP2.test(a.network)) throw new Error(`x402: network "${a.network}" is not a CAIP-2 identifier`);
+    if (!Number.isFinite(a.maxTimeoutSeconds)) throw new Error('x402: maxTimeoutSeconds is required');
+  }
+  return pr;
+}
+
+export const cabeceraRequerido = (pr) => b64(validarRequisitos(pr));
+
+// ---- lo que el cliente manda: PAYMENT-SIGNATURE ----
+// Devuelve { ok, payload } o { ok:false, code, reason }. 400 (no 402) cuando el sobre x402 está
+// malformado: el spec separa "no pagaste" de "lo que mandaste no se entiende".
+export function leerPago(cabecera) {
+  if (!cabecera) return { ok: false, code: 402, reason: 'PAYMENT-SIGNATURE header is required' };
+  let p;
+  try { p = deB64(cabecera); } catch { return { ok: false, code: 400, reason: 'PAYMENT-SIGNATURE is not base64-encoded JSON' }; }
+  if (p?.x402Version !== X402_VERSION) return { ok: false, code: 400, reason: `unsupported x402Version (this house speaks ${X402_VERSION})` };
+  if (!p.accepted || typeof p.accepted !== 'object') return { ok: false, code: 400, reason: 'accepted (the chosen PaymentRequirements) is required' };
+  if (!p.payload || typeof p.payload !== 'object') return { ok: false, code: 400, reason: 'payload is required' };
+  if (p.accepted.network !== RED) return { ok: false, code: 400, reason: `this house settles on ${RED}, not ${p.accepted.network}` };
+  return { ok: true, payload: p };
+}
+
+// ---- lo que el servidor devuelve al liquidar: PAYMENT-RESPONSE ----
+// `transaction` y `network` son OBLIGATORIOS aunque no haya cadena: cuando no hay hash, va cadena
+// vacía. Aquí sí hay algo mejor que una cadena vacía — el id del asiento del Libro, que cualquiera
+// puede pedir. Es la pieza que un explorador on-chain resuelve por hash.
+export function liquidacion({ success = true, transaction = '', payer, amount, errorReason }) {
+  const s = { success: !!success, transaction: String(transaction || ''), network: RED };
+  if (payer) s.payer = payer;
+  if (amount != null) s.amount = monto(amount);
+  if (errorReason) s.errorReason = String(errorReason);
+  return s;
+}
+export const cabeceraLiquidacion = (s) => b64(s);
+
+// ---- declaración de capacidades (el `GET /supported` del facilitador, auto-alojado) ----
+// La casa es su propio facilitador: verifica y liquida contra su propio Libro. El spec lo permite
+// explícitamente ("or host the endpoints themselves").
+export function soportado(dominio, clavesCasa = []) {
+  return {
+    x402Version: X402_VERSION,
+    kinds: [{ x402Version: X402_VERSION, scheme: 'exact', network: RED, extra: { asset: ACTIVO, house: dominio, assetTransferMethod: 'nyx5-envelope' } }],
+    extensions: [],
+    signers: { [RED]: clavesCasa },
+  };
+}
+
+// ---------- red real: USDC sobre una cadena EVM ----------
+// La casa NO custodia nada. En el esquema `exact` el pagador firma una autorización EIP-3009 y el
+// facilitador la difunde: el dinero va del pagador al que cobra, directo, y el facilitador ni
+// siquiera puede cambiar el monto ni el destino. Nosotros sólo anunciamos el precio, preguntamos
+// si la firma sirve, y pedimos que se liquide. Cero criptografía de cadena de nuestro lado.
+//
+// Por eso esto cabe en un módulo sin dependencias: todo lo que hace falta es base64, JSON y fetch.
+export function requisitosEvm({ url, amount, payTo, network, asset, tokenName, tokenVersion, description, flow = 'authorization' }) {
+  for (const [k, v] of Object.entries({ url, payTo, network, asset, tokenName, tokenVersion })) {
+    if (!v) throw new Error(`x402 evm: falta ${k}`);
+  }
+  const pr = {
+    x402Version: X402_VERSION,
+    error: 'PAYMENT-SIGNATURE header is required',
+    resource: { url, mimeType: 'application/json', ...(description ? { description } : {}) },
+    accepts: [{
+      scheme: 'exact', network, amount: monto(amount), asset, payTo, maxTimeoutSeconds: 60,
+      // `name` y `version` son el dominio EIP-712 del CONTRATO del token, y cambian entre redes:
+      // en Base Sepolia el USDC de Circle se llama "USDC" y en Base mainnet "USD Coin". Ponerlo
+      // mal hace que la firma del pagador no valide, y el error no dice por qué.
+      extra: { paymentFlow: flow, assetTransferMethod: 'eip3009', name: tokenName, version: tokenVersion },
+    }],
+    extensions: {},
+  };
+  validarRequisitos(pr);
+  return pr;
+}
+
+// Cliente del facilitador. Es todo el "código de cadena" que necesita un servidor de recurso.
+export function facilitador(base, { fetchImpl = globalThis.fetch, timeoutMs = 20_000 } = {}) {
+  const raiz = String(base).replace(/\/$/, '');
+  const llamar = async (ruta, cuerpo) => {
+    const r = await fetchImpl(`${raiz}${ruta}`, {
+      method: cuerpo ? 'POST' : 'GET',
+      headers: cuerpo ? { 'content-type': 'application/json' } : {},
+      body: cuerpo ? JSON.stringify(cuerpo) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const txt = await r.text();
+    let json; try { json = JSON.parse(txt); } catch { json = { _raw: txt.slice(0, 300) }; }
+    return { status: r.status, body: json };
+  };
+  const sobre = (paymentPayload, paymentRequirements) => ({ x402Version: X402_VERSION, paymentPayload, paymentRequirements });
+  return {
+    soportado: () => llamar('/supported'),
+    // `verify` es SOLO LECTURA por el spec: un isValid:true NO es dinero. Entre verificar y
+    // liquidar el saldo puede gastarse. Se usa para rechazar temprano, nunca como garantía.
+    verificar: (pago, req) => llamar('/verify', sobre(pago, req)),
+    liquidar: (pago, req) => llamar('/settle', sobre(pago, req)),
+  };
+}
+
+// Clave de deduplicación de un pago. El servidor de referencia de x402 NO deduplica: dos
+// peticiones simultáneas con la MISMA firma pasan las dos por `verify` (que es de solo lectura),
+// ejecutan las dos el trabajo, y sólo una liquida. O sea, entregas dos veces y cobras una.
+// Aquí ya tenemos el candado que hace falta (`markSeenIfNew`, invariante 4); esto sólo nombra la
+// clave. La red pone el nonce justamente para esto: es único por autorización.
+export function claveDePago(pago) {
+  const a = pago?.payload?.authorization;
+  const red = pago?.accepted?.network;
+  if (!red) return null;
+  if (a?.nonce) return `x402:${red}:${String(a.nonce).toLowerCase()}`;
+  // Sin nonce no hay antirreplay posible: mejor decirlo que fingir que se dedujo algo.
+  return null;
+}
+
+// Dónde vive el dólar digital en cada red. Los valores de `name`/`version` son el dominio EIP-712
+// del CONTRATO y NO se recuerdan: están leídos del contrato (`name()` y `version()`), porque
+// cambian entre redes y equivocarse hace que ninguna firma valide sin decir por qué.
+// Comprobado el 9-sep-2026 contra ambas cadenas.
+export const TOKEN_USD = Object.freeze({
+  'eip155:1':     { asset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', name: 'USD Coin', version: '2', decimals: 6, red: 'Ethereum',  facilitador: 'https://facilitator.ultravioletadao.xyz' },
+  'eip155:8453':  { asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', name: 'USD Coin', version: '2', decimals: 6, red: 'Base',      facilitador: 'https://x402.dexter.cash' },
+  'eip155:137':   { asset: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359', name: 'USD Coin', version: '2', decimals: 6, red: 'Polygon',   facilitador: 'https://x402.dexter.cash' },
+  'eip155:42161': { asset: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', name: 'USD Coin', version: '2', decimals: 6, red: 'Arbitrum',  facilitador: 'https://x402.dexter.cash' },
+  'eip155:10':    { asset: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85', name: 'USD Coin', version: '2', decimals: 6, red: 'Optimism',  facilitador: 'https://x402.dexter.cash' },
+  'eip155:43114': { asset: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E', name: 'USD Coin', version: '2', decimals: 6, red: 'Avalanche', facilitador: 'https://x402.dexter.cash' },
+  'eip155:84532': { asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', name: 'USDC',     version: '2', decimals: 6, red: 'Base Sepolia', facilitador: 'https://x402.org/facilitator' },
+});
+
+// Una billetera declarada en una tarjeta. Es sólo una dirección a la que cobrar: la casa no la
+// controla, no la custodia y no puede mover nada de ella. Falla cerrado ante una red que no
+// conocemos, porque anunciar un precio en una red que no sabemos liquidar es prometer de gratis.
+// Varias billeteras: una por red. El estándar dice que `accepts` es una LISTA de formas de pago
+// aceptables y que el cliente elige, así que ofrecer una sola red es desperdiciar el mecanismo.
+// Se rechazan los duplicados de red: dos precios para la misma red es una ambigüedad, no una opción.
+export function validarBilleteras(ws) {
+  if (ws == null) return null;
+  const lista = Array.isArray(ws) ? ws : [ws];
+  if (!lista.length) return null;
+  if (lista.length > 8) throw new Error('at most 8 wallets');
+  const vistas = new Set(), out = [];
+  for (const w of lista) {
+    const v = validarBilletera(w);
+    if (!v) continue;
+    if (vistas.has(v.network)) throw new Error(`two wallets for the same network (${v.network}); pick one`);
+    vistas.add(v.network); out.push(v);
+  }
+  return out.length ? out : null;
+}
+
+export function validarBilletera(w) {
+  if (w == null) return null;
+  if (typeof w !== 'object' || Array.isArray(w)) throw new Error('wallet must be an object');
+  const { network, address } = w;
+  if (!TOKEN_USD[network]) throw new Error(`this house cannot settle on ${network}; it knows: ${Object.keys(TOKEN_USD).join(', ')}`);
+  if (typeof address !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(address)) throw new Error('wallet.address must be a 0x EVM address');
+  return { network, address };
+}
+
+// ---------- extensión `bazaar`: quedar catalogado donde un agente busca ----------
+// Un agente no navega: consulta directorios. La extensión `bazaar` deja que un servidor describa
+// cómo se le llama, y el facilitador lo cataloga y lo expone en su `/discovery/resources`.
+//
+// Lo que se declara tiene que ser lo que de verdad se vende. Aquí es la entrega de un sobre en un
+// buzón que cobra: se paga, el sobre entra. Describir algo más grande de lo que hacemos sería
+// exactamente la afirmación gratis que este protocolo existe para encarecer.
+export function bazaarBuzon({ url, direccion }) {
+  return {
+    info: {
+      input: {
+        type: 'http', method: 'POST', bodyType: 'json',
+        // El sobre va firmado; el cuerpo es el sobre Nyx5 tal cual.
+        body: { nyx5: '1', to: [direccion], type: 'message', content: { media: 'text/plain', body: '…' } },
+      },
+      output: { type: 'json', example: { ok: true, code: 202, accepted: [direccion] } },
+    },
+    schema: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        input: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', const: 'http' },
+            method: { type: 'string', const: 'POST' },
+            bodyType: { type: 'string', const: 'json' },
+            body: { type: 'object' },
+          },
+          required: ['type', 'method', 'body'],
+        },
+        output: { type: 'object' },
+      },
+      required: ['input', 'output'],
+    },
+  };
+}

package/src/version.js

@@ -0,0 +1,4 @@
+// La versión que el servidor declara de sí mismo. Un literal y no una lectura de package.json
+// porque este módulo también corre en el edge, donde no hay sistema de archivos. Que no se
+// desincronice lo cuida test/documentacion.test.js: si package.json cambia y esto no, falla.
+export const VERSION = '0.8.0';