@nyx5/nyx5 0.1.0

package/src/correo/politica.js

@@ -0,0 +1,107 @@
+// Nyx5/1 — Validación de sobres y política de entrada (anti-spam y anti-abuso).
+//
+// Toda estafeta receptora aplica, en este orden:
+//   1. forma del sobre (schema mínimo) y tamaño
+//   2. vigencia (expires) y duplicados (id)
+//   3. cadena de firma: dominio -> agente -> sobre   (obligatoria; sin firma no hay entrega)
+//   4. política del agente destino: open | allowlist | pow | stamp (+ límite de tasa por dominio emisor)
+
+import { checkPow } from '../nucleo/crypto.js';
+import { parseAddress } from './resolver.js';
+
+export const TYPES = new Set(['message', 'task', 'result', 'receipt', 'intro']);
+
+export function validateEnvelope(env, { maxBytes = 1_048_576 } = {}) {
+  const fail = (reason) => ({ ok: false, code: 400, reason });
+  if (!env || typeof env !== 'object') return fail('sobre no es un objeto');
+  if (env.nyx5 !== '1') return fail('versión no soportada (se espera nyx5="1")');
+  // Charset acotado: el id viaja como clave al almacenamiento (dedupe, buzones); nada de traversal.
+  if (typeof env.id !== 'string' || !/^[A-Za-z0-9._:-]{8,128}$/.test(env.id)) return fail('id inválido (se espera [A-Za-z0-9._:-]{8,128})');
+  try { parseAddress(env.from); } catch { return fail('from inválido'); }
+  if (!Array.isArray(env.to) || env.to.length < 1 || env.to.length > 50) return fail('to debe ser una lista de 1 a 50 direcciones');
+  for (const t of env.to) { try { parseAddress(t); } catch { return fail(`destinatario inválido: ${t}`); } }
+  if (!TYPES.has(env.type)) return fail(`type inválido: ${env.type}`);
+  if (Number.isNaN(Date.parse(env.created))) return fail('created debe ser ISO-8601');
+  if (env.expires != null && Number.isNaN(Date.parse(env.expires))) return fail('expires debe ser ISO-8601');
+  // Entrega diferida: el sobre espera en la cola hasta esta fecha (la cola ya programa por next_attempt).
+  if (env.deliver_after != null) {
+    if (Number.isNaN(Date.parse(env.deliver_after))) return fail('deliver_after debe ser ISO-8601');
+    // Un sobre que vence antes de la fecha en que debe entregarse jamás llegaría: se rechaza al enviar.
+    if (env.expires != null && Date.parse(env.expires) <= Date.parse(env.deliver_after)) return fail('deliver_after es posterior a expires: el sobre vencería antes de entregarse');
+  }
+  const hasPlain = env.content && typeof env.content === 'object' && typeof env.content.media === 'string';
+  const hasEnc = env.encrypted && typeof env.encrypted === 'object' && typeof env.encrypted.ct === 'string';
+  if (!hasPlain && !hasEnc) return fail('el sobre necesita content o encrypted');
+  if (hasPlain && hasEnc) return fail('content y encrypted son excluyentes');
+  if (env.attachments != null) {
+    if (!Array.isArray(env.attachments)) return fail('attachments debe ser lista');
+    for (const a of env.attachments) if (!a?.name || !a?.media || !a?.sha256 || !a?.url) return fail('adjunto incompleto (name, media, sha256, url)');
+  }
+  if (!env.signature || env.signature.alg !== 'Ed25519' || !env.signature.kid || !env.signature.value) return fail('sobre sin firma');
+  const bytes = Buffer.byteLength(JSON.stringify(env));
+  if (bytes > maxBytes) return { ok: false, code: 413, reason: `sobre de ${bytes} bytes supera el máximo ${maxBytes}` };
+  return { ok: true };
+}
+
+// Limitador de tasa por clave (dominio emisor), ventana deslizante simple.
+export class RateLimiter {
+  constructor({ perMinute = 120 } = {}) { this.perMinute = perMinute; this.hits = new Map(); }
+  allow(key) {
+    const now = Date.now();
+    const arr = (this.hits.get(key) || []).filter((t) => now - t < 60_000);
+    if (arr.length >= this.perMinute) { this.hits.set(key, arr); return false; }
+    arr.push(now); this.hits.set(key, arr); return true;
+  }
+}
+
+// Política del agente destino sobre un sobre ya verificado criptográficamente.
+export function applyInboxPolicy(env, agentRecord, senderDomain) {
+  const inbox = agentRecord.inbox || { policy: 'open' };
+  const { domain: fromDomain } = parseAddress(env.from);
+  const permanent = (reason) => ({ ok: false, code: 403, reason });
+
+  if (inbox.blocklist?.some((x) => x === env.from || x === fromDomain)) return permanent('remitente bloqueado');
+  // La promesa "sealed" del dominio emisor se hace cumplir ANTES de cualquier política:
+  // si fuera después, la rama stamp (que retorna temprano) la saltaría — y justo en los buzones pagados.
+  // Única excepción: sobres a libro@ (operaciones del Libro), que exigen claro por diseño (la casa debe leerlos).
+  const esLibro = String(agentRecord.address || '').startsWith('libro@');
+  if (!esLibro && senderDomain?.policy?.outbound === 'sealed' && !env.encrypted) return permanent('el dominio emisor exige cifrado y el sobre viene en claro');
+
+  switch (inbox.policy) {
+    case 'open':
+      break;
+    case 'allowlist': {
+      const ok = inbox.allowlist?.some((x) => x === env.from || x === fromDomain);
+      if (ok) break;
+      // Un desconocido puede presentarse con un "intro" pequeño.
+      if (env.type === 'intro' && Buffer.byteLength(JSON.stringify(env)) <= 4096) break;
+      // O con un AVAL: un tercero de la allowlist lo respalda con una fianza en la casa del receptor.
+      // Aquí solo comprobamos que el avalador esté en la allowlist; la estafeta verifica la fianza
+      // contra su Libro (existe, activa, avala a este remitente, con el receptor como beneficiario).
+      const aval = env.extensions?.['urn:nyx5:ext:aval'];
+      if (aval && aval.voucher && aval.bond) {
+        let voucherDomain; try { voucherDomain = parseAddress(aval.voucher).domain; } catch { voucherDomain = null; }
+        if (inbox.allowlist?.some((x) => x === aval.voucher || x === voucherDomain)) {
+          return { ok: true, vouch: { voucher: aval.voucher, bond: aval.bond, vouchee: env.from, beneficiary: agentRecord.address } };
+        }
+        return permanent('el avalador de la presentación no está en la allowlist');
+      }
+      return permanent('remitente no está en la allowlist (se acepta un intro ≤4 KB o un aval con fianza de un avalador de la allowlist)');
+    }
+    case 'pow': {
+      const bits = inbox.pow_bits ?? 16;
+      const exempt = inbox.allowlist?.some((x) => x === env.from || x === fromDomain);
+      if (!exempt && !checkPow(env.id, env.pow, bits)) return { ok: false, code: 402, reason: `se requiere proof-of-work de ${bits} bits`, pow_bits: bits };
+      break;
+    }
+    case 'stamp': {
+      // Estampilla pagada en el Libro de la casa del receptor. La cobra la estafeta al aceptar.
+      const exempt = inbox.allowlist?.some((x) => x === env.from || x === fromDomain);
+      if (!exempt) return { ok: true, stamp: { price: inbox.price ?? 1, house: inbox.house } };
+      break;
+    }
+    default:
+      return permanent(`política de buzón desconocida: ${inbox.policy}`);
+  }
+  return { ok: true };
+}

package/src/correo/resolver.js

@@ -0,0 +1,173 @@
+// Nyx5/1 — Resolver: de una dirección agente@dominio a una tarjeta verificada.
+//
+// Orden de resolución del dominio (equivalente al registro MX del correo):
+//   1. Override local (hosts.json / opción hosts)    -> pruebas y redes privadas
+//   2. DNS TXT en _nyx5.<dominio>                  -> ancla pública de confianza
+//   3. https://<dominio>/.well-known/nyx5.json     -> fallback sin DNS
+//
+// Cadena de confianza: clave del dominio (anclada en DNS o pineada) -> certifica la tarjeta
+// del agente -> la clave del agente firma cada sobre.
+
+import dns from 'node:dns/promises';
+import { verifyObject } from '../nucleo/crypto.js';
+
+export function parseAddress(address) {
+  const m = /^([a-z0-9][a-z0-9._-]{0,63})@([a-z0-9.-]+)$/i.exec(String(address || ''));
+  if (!m) throw new Error(`dirección inválida: ${address}`);
+  return { local: m[1].toLowerCase(), domain: m[2].toLowerCase() };
+}
+
+export function parseTxtRecord(txt) {
+  const out = {};
+  for (const part of txt.split(';')) {
+    const [k, ...rest] = part.trim().split('=');
+    if (k && rest.length) out[k.trim()] = rest.join('=').trim();
+  }
+  return out;
+}
+
+export class Resolver {
+  constructor({ hosts = {}, fetchImpl = globalThis.fetch, cacheTtlMs = 5 * 60 * 1000, pins = {}, timeoutMs = 5000, onPin = null, self = null } = {}) {
+    this.hosts = { ...hosts };          // { "beta.local": { url: "http://localhost:4002", sig?: "<pub>" } }
+    this.fetch = (...a) => fetchImpl(...a); // envuelto: workerd exige fetch con this=globalThis
+    this.cacheTtlMs = cacheTtlMs;
+    this.pins = { ...pins };            // dominio -> clave pública pineada (TOFU o DNS)
+    this.timeoutMs = timeoutMs;
+    this.onPin = onPin;                 // callback(pins) para PERSISTIR un pin nuevo: un pin solo en memoria no protege entre procesos/isolates
+    // La propia casa se sirve sin red: un Worker no puede pedirse su propia URL pública
+    // (Cloudflare corta la conexión: 522) y en cualquier runtime sería una vuelta inútil.
+    // self = { domain, estafeta, domainCard(), agentCard(local) }
+    this.self = self;
+    this.cache = new Map();
+  }
+
+  setHost(domain, entry) { this.hosts[domain] = entry; this.cache.clear(); }
+  invalidate(key) { if (key) this.cache.delete(key); else this.cache.clear(); }
+
+  _cached(key) {
+    const hit = this.cache.get(key);
+    if (hit && hit.until > Date.now()) return hit.value;
+    return null;
+  }
+  _remember(key, value) { this.cache.set(key, { value, until: Date.now() + this.cacheTtlMs }); }
+
+  async _get(url) {
+    const res = await this.fetch(url, { signal: AbortSignal.timeout(this.timeoutMs) });
+    if (!res.ok) throw Object.assign(new Error(`GET ${url} -> ${res.status}`), { permanent: res.status === 404 || res.status === 410 });
+    return res.json();
+  }
+
+  // Devuelve { url, sig? } donde vive la estafeta del dominio.
+  async locate(domain) {
+    domain = domain.toLowerCase();
+    if (this.hosts[domain]) return { source: 'override', ...this.hosts[domain] };
+    try {
+      const records = await dns.resolveTxt(`_nyx5.${domain}`);
+      for (const chunks of records) {
+        const rec = parseTxtRecord(chunks.join(''));
+        if (rec.v === 'nyx51' && rec.url) return { source: 'dns', url: rec.url, sig: rec.sig };
+      }
+    } catch (e) {
+      // "No existe el registro" (NXDOMAIN/sin datos) es el fallback legítimo a well-known.
+      // Cualquier OTRA falla de DNS (red, timeout, servfail) NO degrada el ancla en silencio:
+      // un atacante que bloquee la respuesta DNS no puede empujarnos a well-known + TOFU.
+      if (e.code !== 'ENOTFOUND' && e.code !== 'ENODATA') {
+        throw Object.assign(new Error(`DNS no disponible para ${domain}: ${e.message}`), { permanent: false });
+      }
+    }
+    return { source: 'well-known', url: `https://${domain}` };
+  }
+
+  // Tarjeta del dominio, verificada y (si corresponde) contrastada con la clave anclada.
+  async domainCard(domain) {
+    domain = domain.toLowerCase();
+    if (this.self && domain === this.self.domain) {
+      const card = await this.self.domainCard();
+      return { ...card, _estafeta: this.self.estafeta, _source: 'local' };
+    }
+    const cached = this._cached(`domain:${domain}`);
+    if (cached) return cached;
+
+    const loc = await this.locate(domain);
+    const card = await this._get(`${loc.url.replace(/\/$/, '')}/.well-known/nyx5.json`);
+    if (card.nyx5 !== '1' || card.domain !== domain) throw Object.assign(new Error(`tarjeta de dominio inválida para ${domain}`), { permanent: true });
+    const keyIds = (card.keys || []).map((k) => k.sig);
+    if (!keyIds.includes(card.signature?.kid) || !verifyObject(card, card.signature.kid)) {
+      throw Object.assign(new Error(`firma de dominio inválida para ${domain}`), { permanent: true });
+    }
+    // Ancla: DNS/override dice qué clave debe tener el dominio. Si no hay ancla, TOFU (pin en primer uso).
+    const anchor = loc.sig || this.pins[domain];
+    if (anchor && !keyIds.includes(anchor)) throw Object.assign(new Error(`la clave del dominio ${domain} no coincide con la anclada`), { permanent: true });
+    if (!anchor) {
+      this.pins[domain] = card.signature.kid;
+      // Se persiste ESE pin, no el mapa entero: escribir el mapa desde la memoria de un proceso
+      // borraba los pines que otro había aprendido.
+      try { await this.onPin?.(domain, card.signature.kid); } catch { /* mejor-esfuerzo; el pin en memoria ya rige */ }
+    }
+
+    const value = { ...card, _estafeta: loc.url.replace(/\/$/, ''), _source: loc.source };
+    this._remember(`domain:${domain}`, value);
+    return value;
+  }
+
+  // Tarjeta del agente, certificada por la clave del dominio.
+  async agentCard(address) {
+    const { local, domain } = parseAddress(address);
+    // La propia casa sirve la tarjeta sin red, pero pasa por la MISMA verificación que una ajena:
+    // venir de casa no la exime de estar certificada por el dominio y firmada por su padre.
+    if (this.self && domain === this.self.domain) {
+      const card = await this.self.agentCard(local);
+      if (!card) throw Object.assign(new Error(`agente inexistente: ${address}`), { permanent: true });
+      const dc = await this.domainCard(domain);
+      return this._verifyAgentCard(card, dc, address, local, domain);
+    }
+    const key = `agent:${local}@${domain}`;
+    const cached = this._cached(key);
+    if (cached) return cached;
+
+    const dc = await this.domainCard(domain);
+    const card = await this._get(`${dc._estafeta}/agents/${encodeURIComponent(local)}`);
+    const value = await this._verifyAgentCard(card, dc, address, local, domain);
+    this._remember(key, value);
+    return value;
+  }
+
+  // La verificación de una tarjeta de agente, en un solo lugar: certificación del dominio,
+  // vigencia y cadena de delegación. La usan el camino local y el remoto por igual.
+  async _verifyAgentCard(card, dc, address, local, domain) {
+    if (card.nyx5 !== '1' || card.address !== `${local}@${domain}`) throw Object.assign(new Error(`tarjeta de agente inválida: ${address}`), { permanent: true });
+    const domainKeys = dc.keys.map((k) => k.sig);
+    if (!domainKeys.includes(card.certification?.kid) || !verifyObject(card, card.certification.kid, 'certification')) {
+      throw Object.assign(new Error(`certificación inválida para ${address}`), { permanent: true });
+    }
+    if (card.valid_until && Date.parse(card.valid_until) < Date.now()) throw Object.assign(new Error(`tarjeta vencida: ${address}`), { permanent: true });
+    if (card.delegation) {
+      // Cadena de delegación: el padre (ya certificado por el dominio) firmó esta tarjeta.
+      const d = card.delegation;
+      const { local: parentLocal, domain: parentDomain } = parseAddress(d.by);
+      if (parentDomain !== domain || !local.endsWith(`.${parentLocal}`) || d.address !== card.address || d.sig !== card.sig) throw Object.assign(new Error(`delegación inconsistente en ${address}`), { permanent: true });
+      const parent = await this.agentCard(d.by);
+      if (!Resolver.acceptedKids(parent).includes(d.signature?.kid) || !verifyObject(d, d.signature.kid)) throw Object.assign(new Error(`delegación no firmada por ${d.by}`), { permanent: true });
+      card = { ...card, delegation: { ...d, _parent: parent } };
+    }
+    return { ...card, _estafeta: dc._estafeta, _domain: dc };
+  }
+
+  // Claves aceptables de una tarjeta: la vigente más las anteriores dentro del período de gracia.
+  // Una clave previa SIN vencimiento no cuenta: la gracia es acotada o no es gracia (falla cerrado).
+  static acceptedKids(card) {
+    return [card.sig, ...(card.previous || []).filter((p) => p.until && Date.parse(p.until) > Date.now()).map((p) => p.sig)];
+  }
+
+  // Igual que agentCard, pero si el sobre viene firmado con una clave que la tarjeta en caché no
+  // reconoce (rotación reciente), refresca la tarjeta una vez antes de rechazar.
+  async agentCardForKid(address, kid) {
+    let card = await this.agentCard(address);
+    if (!Resolver.acceptedKids(card).includes(kid)) {
+      const { local, domain } = parseAddress(address);
+      this.invalidate(`agent:${local}@${domain}`);
+      card = await this.agentCard(address);
+    }
+    return card;
+  }
+}

package/src/libro/contratos.js

@@ -0,0 +1,247 @@
+// Nyx5/1 — Contratos: máquinas de estado sobre las primitivas del Libro.
+//
+// Cada operación recibe un contexto { libro, env, from, body, senderCard, opHash, scope } y devuelve
+// { result, recibos: [{ to: [...], thread, body }] }. Los recibos los envía la estafeta desde
+// `libro@<dominio>`, firmados con la clave de la casa: son la verdad compartida entre las partes.
+//
+// Agregar un contrato nuevo = agregar entradas a `ops` y, si se cotiza, a CONTRATOS.<kind>.
+// El kernel (libro.js) no se toca.
+//
+// Las operaciones corren DENTRO de la transacción que abre Libro.handle(): leen con
+// libro.getContract/getMandate (que ven las escrituras pendientes) y escriben con
+// libro.putContract/putMandate (que quedan en la transacción). El commit lo sella handle().
+
+import { sha256hex, canonical, uuid } from '../nucleo/crypto.js';
+import { parseAddress } from '../correo/resolver.js';
+
+import { LibroError } from './errores.js';
+
+const iso = () => new Date().toISOString();
+const fail = (code, msg) => { throw new LibroError(code, msg); };
+
+// --- helpers ---
+async function getContract(libro, id) { const c = await libro.getContract(id); if (!c) fail(404, `contrato inexistente: ${id}`); return c; }
+async function getMandate(libro, id) { const m = await libro.getMandate(id); if (!m) fail(404, `mandato inexistente: ${id}`); return m; }
+function record(libro, c, op, by, extra = {}) {
+  c.history.push({ at: iso(), op, by, ...extra });
+  c.updated = iso();
+  libro.putContract(c);
+  return c;
+}
+function scopeCap(ctx, amount, what) {
+  const cap = ctx.scope?.cap;
+  if (cap != null && amount > cap) fail(403, `${what}: ${amount} tok supera el tope ${cap} del agente delegado`);
+}
+function must(cond, code, msg) { if (!cond) fail(code, msg); }
+const parties = (c) => [c.seller, c.buyer, c.verifier, c.arbiter].filter(Boolean);
+
+// ============ Operaciones ============
+const ops = {
+
+  // --- aceptar una cotización: crea el contrato y ejecuta el primer asiento ---
+  async accept(ctx) {
+    const { libro, from, body } = ctx;
+    const q = body.quote;
+    await libro.verifyQuote(q, from); // valida forma, firma, vigencia, no-reuso y que q.contract sea cotizable
+    scopeCap(ctx, q.price, 'aceptar cotización');
+    const kind = CONTRATOS[q.contract];
+    const c = {
+      id: uuid(), kind: q.contract, house: libro.domain, seller: q.seller, buyer: from, amount: q.price,
+      concept: q.concept, terms: q.terms || {}, arbiter: q.arbiter || null, referrer: q.referrer || null,
+      quote_id: q.id, quote_sha256: sha256hex(canonical(q)), accept_sha256: ctx.opHash,
+      state: 'accepted', created: iso(), history: [],
+    };
+    const refs = { contract: c.id, quote: q.id, quote_sha256: c.quote_sha256, op: ctx.env.id, op_sha256: ctx.opHash };
+    const out = await kind.onAccept({ libro, c, q, refs });
+    record(libro, c, 'accept', from, { asiento: out.asiento?.id, mandate: out.mandate?.id });
+    // Aviso de plazo: si el trato tiene fecha límite, el Libro se programa un sobre a las partes
+    // para ese día. Un escrow que llegó a su deadline sin liberarse deja de quedar mudo.
+    const plazo = c.terms?.deadline;
+    const avisos = plazo && !Number.isNaN(Date.parse(plazo)) ? [{
+      to: parties(c), thread: c.id, deliver_after: new Date(Date.parse(plazo)).toISOString(),
+      body: { aviso: 'plazo', contract: c.id, kind: c.kind, deadline: plazo, mensaje: `El plazo del contrato ${c.id} (${c.concept}) llegó. Estado al programarse: ${c.state}.` },
+    }] : [];
+    return { result: { contract: c, asiento: out.asiento, mandate: out.mandate },
+      recibos: [{ to: [c.buyer, c.seller], thread: c.id, body: { contract: c, asiento: out.asiento, mandate: out.mandate, cotizacion_sha256: c.quote_sha256 } }],
+      avisos };
+  },
+
+  // --- escrow: el vendedor declara entregado, con hash de la evidencia ---
+  async deliver(ctx) {
+    const { libro, from, body } = ctx;
+    const c = await getContract(libro, body.contract);
+    must(c.kind === 'escrow', 409, 'deliver solo aplica a escrow');
+    must(from === c.seller, 403, 'solo el vendedor puede declarar la entrega');
+    must(c.state === 'held', 409, `estado ${c.state}, se esperaba held`);
+    c.state = 'delivered'; c.evidence_sha256 = body.evidence_sha256 || null;
+    record(libro, c, 'deliver', from, { evidence_sha256: c.evidence_sha256, note: body.note });
+    return { result: { contract: c }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c } }] };
+  },
+
+  // --- liberar fondos retenidos: escrow -> vendedor (con fee); fianza -> vuelve al que afianzó ---
+  async release(ctx) {
+    const { libro, from, body } = ctx;
+    const c = await getContract(libro, body.contract);
+    let asiento;
+    if (c.kind === 'escrow') {
+      must([c.buyer, c.arbiter].includes(from), 403, 'solo el comprador o el árbitro liberan el escrow');
+      must(['held', 'delivered'].includes(c.state), 409, `estado ${c.state}`);
+      asiento = await libro.release(c.id, c.seller, c.amount, `liberación escrow ${c.id}: ${c.concept}`, { contract: c.id }, { op: ctx.env.id, op_sha256: ctx.opHash }, c.referrer);
+      c.state = 'released';
+    } else if (c.kind === 'bond') {
+      const expired = c.expires && Date.parse(c.expires) < Date.now();
+      must([c.verifier, c.arbiter].includes(from) || (from === c.seller && expired), 403, 'la fianza la libera el verificador o el árbitro; el afianzado solo cuando vence');
+      must(c.state === 'posted', 409, `estado ${c.state}`);
+      asiento = await libro.refund(c.id, c.seller, c.amount, `fianza liberada ${c.id}: ${c.claim}`, { contract: c.id, kind: 'bond-release' }, { op: ctx.env.id, op_sha256: ctx.opHash });
+      c.state = 'released';
+    } else fail(409, `release no aplica a ${c.kind}`);
+    record(libro, c, 'release', from, { asiento: asiento.id });
+    return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento } }] };
+  },
+
+  // --- devolver escrow al comprador (sin fee) ---
+  async refund(ctx) {
+    const { libro, from, body } = ctx;
+    const c = await getContract(libro, body.contract);
+    must(c.kind === 'escrow', 409, 'refund solo aplica a escrow');
+    must([c.seller, c.arbiter].includes(from) || (from === c.buyer && c.state === 'held'), 403, 'devuelven el vendedor o el árbitro; el comprador solo si aún no hay entrega');
+    must(['held', 'delivered'].includes(c.state), 409, `estado ${c.state}`);
+    const asiento = await libro.refund(c.id, c.buyer, c.amount, `devolución escrow ${c.id}: ${c.concept}`, { contract: c.id }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    c.state = 'refunded';
+    record(libro, c, 'refund', from, { asiento: asiento.id, note: body.note });
+    return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento } }] };
+  },
+
+  // --- fianza: el que afirma deposita; si la verificación lo derriba, la pierde ---
+  async bond(ctx) {
+    const { libro, from, body } = ctx;
+    must(typeof body.claim === 'string' && body.claim.length > 0, 400, 'la fianza necesita claim (la afirmación)');
+    parseAddress(body.verifier); must(body.verifier !== from, 400, 'el verificador no puede ser el mismo afianzado');
+    // beneficiary y arbiter entran a cuentas del ledger: direcciones válidas o nada.
+    if (body.beneficiary) { try { parseAddress(body.beneficiary); } catch { fail(400, 'beneficiary debe ser una dirección de agente válida'); } }
+    if (body.arbiter) { try { parseAddress(body.arbiter); } catch { fail(400, 'arbiter debe ser una dirección de agente válida'); } }
+    // vouchee (avalado): si esta fianza avala a un tercero para presentarse ante un buzón con lista
+    // blanca, nombra a quién avala. La política de entrada exige que coincida con el remitente.
+    if (body.vouchee) { try { parseAddress(body.vouchee); } catch { fail(400, 'vouchee debe ser una dirección de agente válida'); } }
+    scopeCap(ctx, body.amount, 'afianzar');
+    const c = {
+      id: uuid(), kind: 'bond', house: libro.domain, seller: from, verifier: body.verifier, arbiter: body.arbiter || null,
+      beneficiary: body.beneficiary || libro.casa, vouchee: body.vouchee || null, amount: body.amount, claim: body.claim, evidence_sha256: body.evidence_sha256 || null,
+      expires: body.expires || null, claim_sha256: ctx.opHash, state: 'posted', created: iso(), history: [],
+    };
+    const asiento = await libro.hold(from, c.id, c.amount, `fianza ${c.id}: ${c.claim}`, { contract: c.id, kind: 'bond' }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    record(libro, c, 'bond', from, { asiento: asiento.id });
+    return { result: { contract: c, asiento }, recibos: [{ to: [c.seller, c.verifier], thread: c.id, body: { contract: c, asiento } }] };
+  },
+
+  // --- ejecutar la fianza: la afirmación era falsa ---
+  async forfeit(ctx) {
+    const { libro, from, body } = ctx;
+    const c = await getContract(libro, body.contract);
+    must(c.kind === 'bond', 409, 'forfeit solo aplica a fianzas');
+    must([c.verifier, c.arbiter].includes(from), 403, 'solo el verificador o el árbitro ejecutan la fianza');
+    must(c.state === 'posted', 409, `estado ${c.state}`);
+    const asiento = await libro.post(`fianza ejecutada ${c.id}: ${c.claim}`, [{ account: `escrow:${c.id}`, delta: -c.amount }, { account: c.beneficiary, delta: c.amount }], { kind: 'forfeit', contract: c.id, reason: body.reason }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    c.state = 'forfeited';
+    record(libro, c, 'forfeit', from, { asiento: asiento.id, reason: body.reason });
+    return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento } }] };
+  },
+
+  // --- mandato: autoridad de gasto delegada, en cadena ---
+  async mandate(ctx) {
+    const { libro, from, body } = ctx;
+    parseAddress(body.grantee);
+    must(Number.isInteger(body.cap) && body.cap > 0, 400, 'cap debe ser entero positivo');
+    scopeCap(ctx, body.cap, 'otorgar mandato');
+    let parent = null;
+    if (body.parent) {
+      parent = await getMandate(libro, body.parent);
+      must(parent.state === 'active', 409, 'el mandato padre no está activo');
+      must(parent.grantee === from, 403, 'solo el mandatario del padre puede sub-delegar');
+      must(body.cap <= parent.cap - parent.spent, 403, `el sub-mandato (${body.cap}) supera lo disponible del padre (${parent.cap - parent.spent})`);
+      if (parent.expires) must(!body.expires || Date.parse(body.expires) <= Date.parse(parent.expires), 403, 'el sub-mandato no puede durar más que el padre');
+    }
+    const m = { id: uuid(), house: libro.domain, grantor: from, grantee: body.grantee, cap: body.cap, spent: 0, scope: body.scope || {}, expires: body.expires || parent?.expires || null,
+      parent: parent?.id || null, root: parent ? parent.root : from, chain: [], state: 'active', created: iso(), op_sha256: ctx.opHash };
+    m.chain = parent ? [...parent.chain, m.id] : [m.id];
+    libro.putMandate(m);
+    return { result: { mandate: m }, recibos: [{ to: [m.grantor, m.grantee], thread: m.chain[0], body: { mandate: m } }] };
+  },
+
+  // --- cobrar bajo mandato: paga el mandante raíz; toda la cadena descuenta ---
+  async charge(ctx) {
+    const { libro, from, body } = ctx;
+    const m = await getMandate(libro, body.mandate);
+    must(from === m.grantee, 403, 'solo el mandatario cobra bajo el mandato');
+    must(Number.isInteger(body.amount) && body.amount > 0, 400, 'monto inválido');
+    scopeCap(ctx, body.amount, 'cobrar');
+    const chain = [];
+    for (let cur = m; cur; cur = cur.parent ? await getMandate(libro, cur.parent) : null) {
+      must(cur.state === 'active', 409, `mandato ${cur.id} no está activo`);
+      must(!cur.expires || Date.parse(cur.expires) > Date.now(), 410, `mandato ${cur.id} vencido`);
+      must(cur.cap - cur.spent >= body.amount, 402, `mandato ${cur.id}: quedan ${cur.cap - cur.spent}, se piden ${body.amount}`);
+      if (cur.scope?.concepts?.length) must(cur.scope.concepts.includes(body.concept), 403, `concepto "${body.concept}" fuera del ámbito del mandato`);
+      chain.push(cur);
+    }
+    // El descuento de la cadena y el asiento van en la MISMA transacción: si el commit falla,
+    // ni el dinero se movió ni ningún eslabón descontó (nada de sobre-gasto por caída a medias).
+    const asiento = await libro.transfer(m.root, m.grantee, body.amount, body.concept || `cobro bajo mandato ${m.id}`, { mandate: m.id, chain: chain.map((x) => x.id) }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    for (const cur of chain) { cur.spent += body.amount; libro.putMandate(cur); }
+    const everyone = [...new Set(chain.flatMap((x) => [x.grantor, x.grantee]))];
+    return { result: { asiento, mandate: chain[0] }, recibos: [{ to: everyone, thread: chain.at(-1).id, body: { asiento, mandate: chain[0], chain: chain.map((x) => ({ id: x.id, grantor: x.grantor, grantee: x.grantee, cap: x.cap, spent: x.spent })) } }] };
+  },
+
+  // --- revocar un mandato y todo lo que cuelga de él ---
+  async revoke(ctx) {
+    const { libro, from, body } = ctx;
+    const m = await getMandate(libro, body.mandate);
+    const ancestors = []; for (let cur = m; cur; cur = cur.parent ? await getMandate(libro, cur.parent) : null) ancestors.push(cur.grantor);
+    must(ancestors.includes(from), 403, 'solo el mandante o un mandante superior revoca');
+    const affected = (await libro.store.libroListMandates()).filter((x) => x.chain.includes(m.id) && x.state === 'active');
+    for (const x of affected) { x.state = 'revoked'; x.revoked = { at: iso(), by: from }; libro.putMandate(x); }
+    return { result: { revoked: affected.map((x) => x.id) }, recibos: [{ to: [...new Set(affected.flatMap((x) => [x.grantor, x.grantee]))], thread: m.chain[0], body: { revoked: affected.map((x) => x.id), by: from } }] };
+  },
+
+  // --- lecturas: la respuesta vuelve por correo como recibo ---
+  async balance(ctx) {
+    const acc = await ctx.libro.account(ctx.from);
+    return { result: acc, recibos: [{ to: [ctx.from], body: { account: acc.account, balance: acc.balance, contracts: acc.contracts.length, mandates: acc.mandates.length } }] };
+  },
+  async statement(ctx) {
+    const raw = Number(ctx.body.limit);
+    const n = Number.isInteger(raw) && raw > 0 ? Math.min(raw, 200) : 20;
+    const entries = await ctx.libro.store.libroStatement(ctx.from, n);
+    return { result: { entries }, recibos: [{ to: [ctx.from], body: { entries } }] };
+  },
+  async contract(ctx) {
+    const c = await getContract(ctx.libro, ctx.body.contract);
+    must(parties(c).includes(ctx.from), 403, 'no eres parte de este contrato');
+    return { result: { contract: c }, recibos: [{ to: [ctx.from], thread: c.id, body: { contract: c } }] };
+  },
+};
+
+// ============ Tipos de contrato cotizables ============
+export const CONTRATOS = {
+  ops,
+  // Spot: cotizar -> cobrar. Comprar un dato, un informe, una verificación.
+  spot: { quoteable: true, async onAccept({ libro, c, refs }) {
+    c.state = 'settled';
+    return { asiento: await libro.transfer(c.buyer, c.seller, c.amount, `spot ${c.id}: ${c.concept}`, { contract: c.id }, refs, c.referrer) };
+  } },
+  // Escrow: retener al encargar -> liberar si la prueba pasa, devolver si falla. La cajita con dientes.
+  escrow: { quoteable: true, async onAccept({ libro, c, refs }) {
+    c.state = 'held';
+    return { asiento: await libro.hold(c.buyer, c.id, c.amount, `escrow ${c.id}: ${c.concept}`, { contract: c.id }, refs) };
+  } },
+  // Medido: la aceptación crea un mandato del comprador al vendedor con tope = precio cotizado.
+  metered: { quoteable: true, async onAccept({ libro, c, q, refs }) {
+    const m = { id: uuid(), house: libro.domain, grantor: c.buyer, grantee: c.seller, cap: c.amount, spent: 0, scope: q.terms?.scope || {}, expires: q.terms?.expires || q.expires || null,
+      parent: null, root: c.buyer, chain: [], state: 'active', created: iso(), contract: c.id, op_sha256: refs.op_sha256 };
+    m.chain = [m.id];
+    libro.putMandate(m);
+    c.state = 'active'; c.mandate = m.id;
+    return { mandate: m };
+  } },
+  // Bond (fianza) no se cotiza: se deposita directamente con la operación `bond`.
+  bond: { quoteable: false },
+};

package/src/libro/errores.js

@@ -0,0 +1,4 @@
+// Nyx5/1 — Error del Libro con código HTTP-like (402 saldo, 403 parte, 404 inexistente, 409 estado, 410 vencido).
+export class LibroError extends Error {
+  constructor(code, message) { super(message); this.name = 'LibroError'; this.code = code; }
+}