@nyx5/nyx5 0.6.0 → 0.8.0

package/src/correo/politica.js

@@ -8,9 +8,212 @@
 
 import { checkPow } from '../nucleo/crypto.js';
 import { parseAddress } from './resolver.js';
+import { PRUEBAS } from '../libro/verifica.js';
+import { CONTRATOS } from '../libro/contratos.js';
 
 export const TYPES = new Set(['message', 'task', 'result', 'receipt', 'intro']);
 
+// Proyecto y rol de un sobre (13-sep-2026): un mismo dueño con varios chats sobre un solo conector
+// distingue «Sigo Main» de «Rosetta Lab» con una extensión firmada dentro del sobre, y el buzón
+// filtra por ella. Va en claro (las extensiones no se cifran): el nombre de un proyecto no es secreto.
+export const EXT_PROYECTO = 'urn:nyx5:ext:proyecto';
+// Revisión del 13-sep-2026: un `project` de 200.000 caracteres o un `role` con escapes de terminal
+// llegaban tal cual a la herramienta del Claude remoto. Se limpian y acotan como la ficha, y el
+// proyecto se normaliza (NFKC, sin invisibles) para que un homógrafo no esconda un mensaje del filtro.
+export const proyectoDe = (env) => { const p = env?.extensions?.[EXT_PROYECTO]?.project; return typeof p === 'string' ? nombreDeProyecto(p) : null; };
+// Devuelve null cuando lo que queda no es un nombre: vacío tras limpiar, o un nombre que es
+// propiedad propia de Object.prototype (`__proto__`, `constructor`). Revisión del 14-sep-2026:
+// `pending_by_project` viaja como objeto JSON y un lector que haga `mapa[p]` con ese nombre ausente
+// recibe una función en vez de un número (o, al armar el objeto, pisa el prototipo). Es UNA función
+// para las dos puertas: el cliente rechaza al enviar y la casa lee «sin proyecto» si llega de fuera.
+export const nombreDeProyecto = (p) => { const n = limpio(String(p).normalize('NFKC'), 40).toLowerCase(); return n && !Object.hasOwn(Object.prototype, n) ? n : null; };
+export const rolDe = (env) => { const r = env?.extensions?.[EXT_PROYECTO]?.role; return typeof r === 'string' ? (limpio(r, 40) || null) : null; };
+
+// El RESUMEN EN CLARO (29-oct-2026, decisión de Nicholas). El aviso por correo sólo podía decir
+// QUIÉN le escribió, nunca QUÉ: el contenido va cifrado y la casa no lo lee (invariante 8). Un
+// timbre que no dice quién está en la puerta es ruido, y él tiene que abrir la app para saber si
+// algo le toca. Ahora el REMITENTE puede adjuntar una línea que viaja SIN CIFRAR, y la casa la
+// pone en el asunto del aviso.
+//
+// Quién decide qué se expone: el que escribe, no la casa. Por eso la línea es opcional y por eso
+// la descripción de la herramienta dice, con todas sus letras, que la leen la casa y el correo.
+// Nunca va ahí lo que el sobre protege: va de qué se trata, no lo que dice.
+//
+// Se limpia como el proyecto y se acota a UNA línea: `limpio` cambia los controles por espacios y
+// colapsa, así que un salto de línea no puede partir el asunto de un correo en dos.
+export const EXT_RESUMEN = 'urn:nyx5:ext:resumen';
+export const RESUMEN_MAX = 140;
+export const resumenDe = (env) => {
+  const r = env?.extensions?.[EXT_RESUMEN]?.text;
+  return typeof r === 'string' ? (limpio(r, RESUMEN_MAX) || null) : null;
+};
+
+// Ficha pública del agente (13-sep-2026): qué hace, en qué idiomas, de quién es, con qué etiquetas.
+// Va DENTRO de la tarjeta certificada, la firma el dueño al declararla y la casa al certificarla.
+// Vocabulario CERRADO, como el alcance de un mandato: una clave desconocida se rechaza nombrándola,
+// porque una ficha es lo que otros agentes leen antes de contratar, y no puede llevar de todo.
+// Lo declarado NO está verificado (eso es el sello de dueño, otra pieza): es lo que el dueño dice.
+const PERFIL_CLAVES = ['display_name', 'summary', 'description', 'languages', 'tags', 'owner', 'links', 'services'];
+// Fuera: controles C0 y C1, invisibles de ancho cero, y las marcas bidi que voltean el texto en
+// pantalla (un nombre que se lee al revés es una suplantación). Los espacios se colapsan.
+// Los controles pasan a espacio (separaban algo); los invisibles se quitan (no separaban nada, y
+// "sig<ancho cero>o" tiene que quedar "sigo", no "sig o").
+const CONTROLES = /[\x00-\x1f\x7f-\x9f]/g;
+const INVISIBLES = /[\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g;
+export const limpio = (s, max) => String(s).replace(INVISIBLES, '').replace(CONTROLES, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+export function validarPerfil(p) {
+  if (p === null) return { perfil: null };
+  if (typeof p !== 'object' || Array.isArray(p)) return { error: 'profile must be an object' };
+  const ajenas = Object.keys(p).filter((k) => !PERFIL_CLAVES.includes(k));
+  if (ajenas.length) return { error: `profile carries ${ajenas.map((k) => JSON.stringify(k)).join(', ')}, which this house does not publish; it accepts: ${PERFIL_CLAVES.join(', ')}` };
+  const out = {};
+  for (const [k, max] of [['display_name', 80], ['summary', 280], ['description', 2000]]) {
+    if (p[k] == null) continue;
+    if (typeof p[k] !== 'string') return { error: `profile.${k} must be a string` };
+    const v = limpio(p[k], max); if (v) out[k] = v;
+  }
+  if (p.languages != null) {
+    // Tope por etiqueta (35, el máximo razonable de BCP 47): sin él, diez etiquetas de 180 KB
+    // hacían una tarjeta de 1,8 MB firmada por la casa (revisión del 13-sep-2026).
+    if (!Array.isArray(p.languages) || p.languages.length > 10 || !p.languages.every((l) => typeof l === 'string' && l.length <= 35 && /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(l))) return { error: 'profile.languages must be up to 10 language tags like "es", "en-US"' };
+    out.languages = [...new Set(p.languages)];
+  }
+  if (p.tags != null) {
+    if (!Array.isArray(p.tags) || p.tags.length > 20 || !p.tags.every((t) => typeof t === 'string' && /^[a-z0-9-]{1,32}$/.test(t))) return { error: 'profile.tags must be up to 20 tags of lowercase letters, digits and dashes' };
+    out.tags = [...new Set(p.tags)];
+  }
+  if (p.owner != null) {
+    const o = p.owner;
+    if (typeof o !== 'object' || Array.isArray(o) || !['person', 'org'].includes(o.kind) || typeof o.name !== 'string' || Object.keys(o).some((k) => !['kind', 'name'].includes(k))) return { error: 'profile.owner must be { kind: person|org, name }' };
+    out.owner = { kind: o.kind, name: limpio(o.name, 120) };
+  }
+  if (p.links != null) {
+    if (!Array.isArray(p.links) || p.links.length > 5) return { error: 'profile.links must be up to 5 https URLs' };
+    // Sin usuario ni clave en la URL: `https://nyx5.com@evil.example/` se lee como nyx5.com y va a evil.
+    for (const l of p.links) { let u; try { u = new URL(String(l)); } catch { u = null; } if (!u || u.protocol !== 'https:' || u.username || u.password || String(l).length > 200) return { error: `profile.links: not a plain https URL: ${String(l).slice(0, 60)}` }; }
+    out.links = [...new Set(p.links.map(String))];
+  }
+  if (p.services != null) {
+    if (!Array.isArray(p.services) || p.services.length > SERVICIOS_MAX) return { error: `profile.services must be a list of up to ${SERVICIOS_MAX} services` };
+    const ids = new Set(), lista = [];
+    for (const s of p.services) {
+      const v = validarServicio(s);
+      if (v.error) return { error: v.error };
+      if (ids.has(v.servicio.id)) return { error: `profile.services: the id "${v.servicio.id}" appears twice` };
+      ids.add(v.servicio.id); lista.push(v.servicio);
+    }
+    if (lista.length) out.services = lista;
+  }
+  return { perfil: out };
+}
+
+// Catálogo de servicios en la ficha (NX-301): lo que el agente vende, con precio y contrato
+// publicados. Una cotización que nombre un `service` se compara contra ESTO al aceptar
+// (`Libro.verifyQuote`): el precio y el contrato de la cotización tienen que ser los publicados,
+// igual que una tarea sembrada se cotiza con los términos del catálogo tal cual.
+// Vocabulario cerrado por servicio, como el resto de la ficha. `acceptance.kind` sólo puede ser una
+// prueba que verifica@ sabe correr (la lista es la de verifica.js, importada, no copiada) y
+// `contract` sólo un tipo cotizable (la lista es la de contratos.js). `template` es texto para
+// quien va a cotizar: no es la prueba concreta, ésa va en `terms.verify` de cada cotización.
+// `price.usd` es un decimal en texto (no flotante) y SÓLO tiene sentido si la tarjeta declara
+// billetera: eso lo comprueba `usdSinBilletera` en la ruta, porque este validador no ve la tarjeta.
+const SERVICIOS_MAX = 20;
+const SERVICIO_CLAVES = ['id', 'name', 'summary', 'price', 'unit', 'contract', 'acceptance'];
+const UNIDADES = ['job', 'call', 'hour'];
+const contratosCotizables = () => Object.keys(CONTRATOS).filter((k) => CONTRATOS[k]?.quoteable);
+export function validarServicio(s) {
+  if (typeof s !== 'object' || s === null || Array.isArray(s)) return { error: 'profile.services: each service must be an object' };
+  const ajenas = Object.keys(s).filter((k) => !SERVICIO_CLAVES.includes(k));
+  if (ajenas.length) return { error: `profile.services carries ${ajenas.map((k) => JSON.stringify(k)).join(', ')}, which this house does not publish; a service accepts: ${SERVICIO_CLAVES.join(', ')}` };
+  if (typeof s.id !== 'string' || !/^[a-z0-9-]{1,40}$/.test(s.id)) return { error: 'profile.services[].id must be 1-40 lowercase letters, digits and dashes' };
+  const donde = `profile.services[${s.id}]`;
+  if (typeof s.name !== 'string' || !limpio(s.name, 80)) return { error: `${donde}.name must be a non-empty string` };
+  const out = { id: s.id, name: limpio(s.name, 80) };
+  if (s.summary != null) { if (typeof s.summary !== 'string') return { error: `${donde}.summary must be a string` }; const v = limpio(s.summary, 280); if (v) out.summary = v; }
+  const pr = s.price;
+  if (typeof pr !== 'object' || pr === null || Array.isArray(pr) || Object.keys(pr).some((k) => !['tokens', 'usd'].includes(k))) return { error: `${donde}.price must be { tokens, usd? }` };
+  if (!Number.isInteger(pr.tokens) || pr.tokens <= 0) return { error: `${donde}.price.tokens must be a positive integer` };
+  out.price = { tokens: pr.tokens };
+  if (pr.usd != null) {
+    // Decimal en texto con hasta 6 decimales (los de USDC), mayor que cero. Nunca un número: 0.1+0.2.
+    if (typeof pr.usd !== 'string' || !/^\d{1,9}(\.\d{1,6})?$/.test(pr.usd) || Number(pr.usd) <= 0) return { error: `${donde}.price.usd must be a positive decimal string like "1.50"` };
+    out.price.usd = pr.usd;
+  }
+  if (!UNIDADES.includes(s.unit)) return { error: `${donde}.unit must be one of ${UNIDADES.join(', ')}` };
+  out.unit = s.unit;
+  const cotizables = contratosCotizables();
+  if (!cotizables.includes(s.contract)) return { error: `${donde}.contract must be one of ${cotizables.join(', ')}` };
+  out.contract = s.contract;
+  if (s.acceptance != null) {
+    const a = s.acceptance;
+    if (typeof a !== 'object' || a === null || Array.isArray(a) || Object.keys(a).some((k) => !['kind', 'template'].includes(k))) return { error: `${donde}.acceptance must be { kind, template }` };
+    if (!PRUEBAS.includes(a.kind)) return { error: `${donde}.acceptance.kind must be a test verifica@ can run: ${PRUEBAS.join(', ')}` };
+    if (typeof a.template !== 'string' || !limpio(a.template, 280)) return { error: `${donde}.acceptance.template must be a non-empty string` };
+    out.acceptance = { kind: a.kind, template: limpio(a.template, 280) };
+  }
+  return { servicio: out };
+}
+// Un precio en dólares sólo se publica si hay a dónde cobrarlo. La comprobación vive aparte de
+// validarPerfil porque la billetera está en la tarjeta, no en la ficha. Devuelve el error o null.
+export function usdSinBilletera(perfil, wallets) {
+  const con = (perfil?.services || []).filter((s) => s.price?.usd != null);
+  if (!con.length || (Array.isArray(wallets) && wallets.length)) return null;
+  return `service "${con[0].id}" declares a usd price but the card has no wallet; declare wallets first`;
+}
+
+// ---------- adjuntos (NX-413) ----------
+// El archivo NO viaja en el sobre: viaja cifrado al almacén de objetos de la casa del remitente y
+// el sobre lleva la referencia. Esta validación es la que decide qué puede verse desde afuera.
+//
+// En un sobre CIFRADO el array de afuera lleva SÓLO `blob` y `bytes`, y el vocabulario es CERRADO:
+// una clave de más se RECHAZA con nombre, no se ignora. Contradice el invariante 7 a propósito, por
+// la misma razón que `ALCANCE_MANDATO` (9-sep-2026): ese invariante es para extender mensajes sin
+// romper nada, y aquí ignorar un campo de más NO es neutro — `name: "balance-despido-javier.pdf"`
+// afuera del cifrado le cuenta a la casa y a cualquier estafeta del camino casi todo el contenido.
+// Si alguien "arregla" esta inconsistencia para que sea permisiva, reabre la fuga.
+//
+// En un sobre EN CLARO el array lleva la ficha completa, `key` incluida: el adjunto sigue cifrado
+// en el almacén, pero la llave viaja a la vista y la casa SÍ puede abrirlo. Se permite (hay usos
+// legítimos: un adjunto público) y la herramienta lo advierte antes de que un agente lo elija.
+export const ADJUNTO_CIFRADO = ['blob', 'bytes'];
+export const ADJUNTO_CLARO = ['blob', 'bytes', 'name', 'media', 'sha256', 'key'];
+export const ADJUNTOS = { max: 10, bytesPorSobre: 25 * 1024 * 1024, bytesPorAdjunto: 10 * 1024 * 1024, nombreMax: 120, mediaMax: 100 };
+const UUID_BLOB = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MEDIA_TIPO = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i;
+const ENTERO = (v, max) => Number.isSafeInteger(v) && v > 0 && v <= max;
+
+// Devuelve el motivo del rechazo (string) o null si los adjuntos están bien.
+export function validarAdjuntos(attachments, { cifrado = true } = {}) {
+  if (!Array.isArray(attachments)) return 'attachments must be a list';
+  if (attachments.length > ADJUNTOS.max) return `an envelope carries at most ${ADJUNTOS.max} attachments, not ${attachments.length}`;
+  const permitidas = cifrado ? ADJUNTO_CIFRADO : ADJUNTO_CLARO;
+  const vistos = new Set();
+  let total = 0;
+  for (const [i, a] of attachments.entries()) {
+    const donde = `attachments[${i}]`;
+    if (!a || typeof a !== 'object' || Array.isArray(a)) return `${donde} must be an object`;
+    for (const k of Object.keys(a)) {
+      if (!permitidas.includes(k)) {
+        return cifrado
+          ? `${donde}.${k} must not travel outside the encrypted block (an attachment of an encrypted envelope carries only ${ADJUNTO_CIFRADO.join(' and ')}; name, media, sha256 and key go inside)`
+          : `${donde}.${k} is not an attachment field (${ADJUNTO_CLARO.join(', ')})`;
+      }
+    }
+    if (!UUID_BLOB.test(String(a.blob || ''))) return `${donde}.blob must be the uuid of an uploaded object`;
+    if (vistos.has(String(a.blob).toLowerCase())) return `${donde}.blob repeats an attachment of this same envelope`;
+    vistos.add(String(a.blob).toLowerCase());
+    if (!ENTERO(a.bytes, ADJUNTOS.bytesPorAdjunto)) return `${donde}.bytes must be an integer between 1 and ${ADJUNTOS.bytesPorAdjunto} (${Math.round(ADJUNTOS.bytesPorAdjunto / 1024 / 1024)} MB per attachment)`;
+    total += a.bytes;
+    if (cifrado) continue;
+    if (typeof a.name !== 'string' || !limpio(a.name, ADJUNTOS.nombreMax)) return `${donde}.name must be a non-empty string of at most ${ADJUNTOS.nombreMax} characters`;
+    if (typeof a.media !== 'string' || a.media.length > ADJUNTOS.mediaMax || !MEDIA_TIPO.test(a.media)) return `${donde}.media must be a media type like application/pdf`;
+    if (typeof a.sha256 !== 'string' || !/^[0-9a-f]{64}$/i.test(a.sha256)) return `${donde}.sha256 must be the hex sha256 of the plaintext (64 characters)`;
+    if (a.key != null && (typeof a.key !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(a.key))) return `${donde}.key must be the base64url of a 32-byte key`;
+  }
+  if (total > ADJUNTOS.bytesPorSobre) return `the attachments of one envelope add up to ${total} bytes and the maximum is ${ADJUNTOS.bytesPorSobre} (${Math.round(ADJUNTOS.bytesPorSobre / 1024 / 1024)} MB)`;
+  return null;
+}
+
 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');
@@ -34,8 +237,13 @@ export function validateEnvelope(env, { maxBytes = 1_048_576 } = {}) {
   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)');
+    // `!!hasEnc` y no `hasEnc`: para un sobre en claro `hasEnc` vale undefined, no false, y un
+    // undefined ACTIVA el valor por defecto del parámetro (`cifrado = true`), así que los adjuntos
+    // de un sobre EN CLARO se validaban con las reglas del cifrado y se rechazaban todos. Se vio
+    // al probar el caso en claro con un adjunto real. El defecto caía del lado estricto, que es el
+    // que corresponde si hay que equivocarse, pero era el branch equivocado igual.
+    const e = validarAdjuntos(env.attachments, { cifrado: !!hasEnc });
+    if (e) return fail(e);
   }
   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));
@@ -43,6 +251,41 @@ export function validateEnvelope(env, { maxBytes = 1_048_576 } = {}) {
   return { ok: true };
 }
 
+// ---------- la puerta del correo ----------
+// Un correo entra al buzón SIN firma y sin cuenta en el Libro. Durante un tiempo entró además sin
+// pasar por ninguna política: un buzón que cobraba 500 y otro con lista blanca cerrada aceptaban
+// los dos un correo de cualquier desconocido, gratis. O sea que la estampilla, la lista y la
+// prueba de trabajo defendían una puerta mientras la de al lado quedaba abierta, y el precio que
+// la casa anuncia por x402 era evitable escribiendo un correo.
+//
+// Esta función es esa puerta. Falla CERRADO: si la política del buzón no se puede expresar sobre
+// correo, no se deja pasar. Un mecanismo que no existe en este canal no es un permiso.
+//
+// Se compara contra el remitente REAL del correo, no contra `email@<casa>`, que es la pasarela y
+// sería la misma para todo el mundo.
+export function applyEmailPolicy(agentRecord, emailFrom) {
+  const inbox = agentRecord.inbox || { policy: 'open' };
+  const dominio = String(emailFrom).slice(String(emailFrom).lastIndexOf('@') + 1).toLowerCase();
+  const de = String(emailFrom).toLowerCase();
+  switch (inbox.policy) {
+    case undefined:
+    case 'open':
+      return { ok: true };
+    case 'allowlist': {
+      const ok = inbox.allowlist?.some((x) => String(x).toLowerCase() === de || String(x).toLowerCase() === dominio);
+      // El "intro" y el aval del canal firmado NO tienen equivalente aquí: uno se apoya en el tipo
+      // de sobre y el otro en una fianza del Libro, y un correo no trae ninguno de los dos.
+      return ok ? { ok: true } : { ok: false, code: 403, reason: 'this mailbox only accepts listed senders' };
+    }
+    case 'pow':
+      return { ok: false, code: 403, reason: `this mailbox requires proof-of-work, which an email cannot carry; write to ${agentRecord.address} with the protocol instead` };
+    case 'stamp':
+      return { ok: false, code: 402, reason: `this mailbox charges ${inbox.price ?? 1} tok for delivery, and an email carries no payment; join the house and send a signed envelope with a stamp` };
+    default:
+      return { ok: false, code: 403, reason: `unknown mailbox policy (${inbox.policy})` };
+  }
+}
+
 // Limitador de tasa por clave (dominio emisor), ventana deslizante simple.
 export class RateLimiter {
   constructor({ perMinute = 120 } = {}) { this.perMinute = perMinute; this.hits = new Map(); }
@@ -52,6 +295,34 @@ export class RateLimiter {
     if (arr.length >= this.perMinute) { this.hits.set(key, arr); return false; }
     arr.push(now); this.hits.set(key, arr); return true;
   }
+  retryAfter() { return 60; }
+}
+
+// Límite de tasa DURABLE (13-sep-2026, NX-901): el contador vive en el almacén, no en la memoria del
+// proceso. En el edge cada isolate contaba por su lado, así que el límite real era N veces el
+// declarado y nadie sabía cuánto era N. Ventana fija de un minuto por clave: una fila por clave y
+// minuto, que vence sola dos minutos después. La misma interfaz que el de memoria (`allow` se
+// espera con await en los dos: en el de memoria el await no cuesta nada).
+// Si el almacén falla, DEJA PASAR y lo anota: un límite de tasa caído no puede tumbar el correo de
+// todos. Precisión sobre cobertura: retener trabajo bueno es peor que dejar pasar un minuto.
+export class RateLimiterDurable {
+  constructor({ store, perMinute = 120, ns = 'tasa', log = () => {} } = {}) {
+    if (!store?.kvIncrement) throw new Error('RateLimiterDurable needs a store with kvIncrement');
+    this.store = store; this.perMinute = perMinute; this.ns = ns; this.log = log;
+    this.cerradas = new Map(); // clave -> ventana ya agotada, por proceso: un flood no escribe una fila por golpe
+  }
+  static ventana(nowMs = Date.now()) { return Math.floor(nowMs / 60_000); }
+  async allow(key, nowMs = Date.now()) {
+    const v = RateLimiterDurable.ventana(nowMs);
+    if (this.cerradas.get(key) === v) return false;
+    try {
+      const n = await this.store.kvIncrement(this.ns, `${key}:${v}`, (v + 2) * 60_000, nowMs);
+      if (n > this.perMinute) { if (this.cerradas.size > 10_000) this.cerradas.clear(); this.cerradas.set(key, v); return false; }
+      return true;
+    } catch (e) { this.log(`tasa: el almacén no contó (${e.message}); se deja pasar`); return true; }
+  }
+  // Segundos hasta que abra la ventana siguiente: es lo que va en Retry-After.
+  retryAfter(nowMs = Date.now()) { return Math.max(1, 60 - Math.floor((nowMs % 60_000) / 1000)); }
 }
 
 // Política del agente destino sobre un sobre ya verificado criptográficamente.
@@ -67,6 +338,13 @@ export function applyInboxPolicy(env, agentRecord, senderDomain) {
   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');
 
+  // Un sobre de una dirección a SÍ MISMA pasa su propia política (26-oct-2026). Es lo que sostiene
+  // `recordar`, la memoria entre sesiones: un sobre diferido al propio buzón. Antes rebotaba contra
+  // su propia lista blanca — `nyx5_remind` quedaba decorativo en todo buzón por lista — y en un buzón
+  // con estampilla se cobraba a sí mismo. Una lista, una prueba de trabajo o una estampilla defienden
+  // de OTROS; no abren nada, porque sólo quien tiene esa llave puede firmar como esa dirección.
+  if (env.from === agentRecord.address) return { ok: true };
+
   switch (inbox.policy) {
     case 'open':
       break;

package/src/correo/resolver.js

@@ -27,7 +27,10 @@ export function parseTxtRecord(txt) {
 }
 
 export class Resolver {
-  constructor({ hosts = {}, fetchImpl = globalThis.fetch, cacheTtlMs = 5 * 60 * 1000, pins = {}, timeoutMs = 5000, onPin = null, self = null } = {}) {
+  constructor({ hosts = {}, fetchImpl = globalThis.fetch, cacheTtlMs = 5 * 60 * 1000, pins = {}, timeoutMs = 5000, onPin = null, self = null, auth = null } = {}) {
+    // auth = { domain, header(method, path) }: un CLIENTE (Agent) firma la petición a su propia casa
+    // cuando una tarjeta no aparece sin autenticar; así un contacto resuelve a un agente secreto.
+    this.auth = auth;
     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;
@@ -42,7 +45,8 @@ export class Resolver {
   }
 
   setHost(domain, entry) { this.hosts[domain] = entry; this.cache.clear(); }
-  invalidate(key) { if (key) this.cache.delete(key); else this.cache.clear(); }
+  // Invalidar `agent:x@casa` borra también lo recordado «para» alguien de esa misma tarjeta.
+  invalidate(key) { if (!key) { this.cache.clear(); return; } for (const k of this.cache.keys()) if (k === key || k.startsWith(`${key}|for:`)) this.cache.delete(k); }
 
   _cached(key) {
     const hit = this.cache.get(key);
@@ -51,8 +55,8 @@ export class Resolver {
   }
   _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) });
+  async _get(url, headers = {}) {
+    const res = await this.fetch(url, { headers, 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();
   }
@@ -111,7 +115,10 @@ export class Resolver {
   }
 
   // Tarjeta del agente, certificada por la clave del dominio.
-  async agentCard(address) {
+  // `onBehalfOf` (NX-202): para quién se pide. Un agente SECRETO sólo se sirve a quien está en su
+  // lista, así que la casa que pregunta firma «lo pido para bob@mi-casa» con su llave de dominio, y
+  // un cliente firma con la suya ante su propia casa. Sin eso, un secreto se ve como inexistente.
+  async agentCard(address, { onBehalfOf = null } = {}) {
     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.
@@ -122,13 +129,29 @@ export class Resolver {
       return this._verifyAgentCard(card, dc, address, local, domain);
     }
     const key = `agent:${local}@${domain}`;
-    const cached = this._cached(key);
+    // Una tarjeta secreta se recuerda SÓLO para quien la pidió: servida a otro, sería una fuga.
+    const keyPara = onBehalfOf ? `${key}|for:${String(onBehalfOf).toLowerCase()}` : null;
+    const cached = this._cached(key) || (keyPara && this._cached(keyPara));
     if (cached) return cached;
 
     const dc = await this.domainCard(domain);
-    const card = await this._get(`${dc._estafeta}/agents/${encodeURIComponent(local)}`);
+    const url = `${dc._estafeta}/agents/${encodeURIComponent(local)}`;
+    const headers = {};
+    let paraDom = null; try { paraDom = onBehalfOf ? parseAddress(onBehalfOf).domain : null; } catch { paraDom = null; }
+    if (onBehalfOf && this.self?.firmarPara && paraDom === this.self.domain) headers['x-nyx5-for'] = this.self.firmarPara(String(onBehalfOf).toLowerCase(), domain);
+    let card;
+    try { card = await this._get(url, headers); }
+    catch (e) {
+      // Un cliente que no la ve sin autenticar la vuelve a pedir firmando: a su propia casa si el
+      // agente es de ahí; si es de otra casa, le pide a la suya que resuelva «para» él (la casa
+      // firma con su llave de dominio y la otra decide). La tarjeta se verifica igual al llegar.
+      if (!(e.permanent && this.auth)) throw e;
+      if (domain === this.auth.domain) card = await this._get(url, { authorization: this.auth.header('GET', `/agents/${encodeURIComponent(local)}`) });
+      else if (this.auth.url) { const p = `/resolve/${encodeURIComponent(`${local}@${domain}`)}`; const { presence: _p, ...c } = await this._get(`${this.auth.url}${p}`, { authorization: this.auth.header('GET', p) }); card = c; }
+      else throw e;
+    }
     const value = await this._verifyAgentCard(card, dc, address, local, domain);
-    this._remember(key, value);
+    this._remember(value.visibility === 'secret' ? (keyPara || `${key}|for:${this.auth?.domain || 'self'}`) : key, value);
     return value;
   }
 
@@ -161,12 +184,13 @@ export class Resolver {
 
   // 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);
+  async agentCardForKid(address, kid, opts = {}) {
+    let card = await this.agentCard(address, opts);
     if (!Resolver.acceptedKids(card).includes(kid)) {
       const { local, domain } = parseAddress(address);
       this.invalidate(`agent:${local}@${domain}`);
-      card = await this.agentCard(address);
+      if (opts.onBehalfOf) this.invalidate(`agent:${local}@${domain}|for:${String(opts.onBehalfOf).toLowerCase()}`);
+      card = await this.agentCard(address, opts);
     }
     return card;
   }

package/src/libro/contratos.js

@@ -13,8 +13,11 @@
 
 import { sha256hex, canonical, uuid } from '../nucleo/crypto.js';
 import { parseAddress } from '../correo/resolver.js';
+import { applyInboxPolicy } from '../correo/politica.js';
 
 import { LibroError } from './errores.js';
+import { estadoDeCuenta } from './estado.js';
+import { notarize } from './notaria.js';
 
 const iso = () => new Date().toISOString();
 const fail = (code, msg) => { throw new LibroError(code, msg); };
@@ -33,6 +36,36 @@ function scopeCap(ctx, amount, what) {
   if (cap != null && amount > cap) fail(403, `${what}: ${amount} tok exceeds the subagent cap of ${cap}`);
 }
 function must(cond, code, msg) { if (!cond) fail(code, msg); }
+
+// ---------- alcance de un mandato: vocabulario CERRADO, y se falla cerrado ----------
+// Un mandato es autoridad de gasto. Si el mandante escribe una restricción que el Libro no sabe
+// aplicar, la opción segura NO es guardarla y seguir: es negarse.
+//
+// Nació de un defecto real (9-sep-2026): un mandato con `max_per_charge: 500` y una lista de
+// destinatarios permitidos guardó las dos, las FIRMÓ, y después dejó pasar un cobro único de
+// 90.000. La restricción se veía al leer el mandato de vuelta y no hacía nada. Un instrumento que
+// falla hacia el ruido es peor que uno que no existe: te deja construir encima.
+//
+// Esto contradice a propósito el invariante 7 (los campos desconocidos se conservan y se ignoran).
+// Ese invariante es para MENSAJES, donde ignorar lo que no entiendes es lo que permite extender el
+// protocolo sin romperlo. Para autoridad de gasto es lo contrario: ignorar una restricción
+// autoriza MÁS de lo que el mandante quiso.
+export const ALCANCE_MANDATO = Object.freeze(['concepts', 'max_per_charge']);
+
+function validarAlcance(scope, cap) {
+  if (scope == null) return {};
+  must(typeof scope === 'object' && !Array.isArray(scope), 400, 'scope must be an object');
+  const ajenas = Object.keys(scope).filter((k) => !ALCANCE_MANDATO.includes(k));
+  must(!ajenas.length, 400, `this ledger cannot enforce ${ajenas.map((k) => JSON.stringify(k)).join(', ')} in a mandate scope, so it refuses to store it as if it could. It enforces: ${ALCANCE_MANDATO.join(', ')}`);
+  if (scope.concepts != null) {
+    must(Array.isArray(scope.concepts) && scope.concepts.every((c) => typeof c === 'string'), 400, 'scope.concepts must be a list of strings');
+  }
+  if (scope.max_per_charge != null) {
+    must(Number.isInteger(scope.max_per_charge) && scope.max_per_charge > 0, 400, 'scope.max_per_charge must be a positive integer');
+    must(cap == null || scope.max_per_charge <= cap, 400, `scope.max_per_charge (${scope.max_per_charge}) cannot exceed the mandate cap (${cap})`);
+  }
+  return scope;
+}
 const parties = (c) => [c.seller, c.buyer, c.verifier, c.arbiter].filter(Boolean);
 
 // ============ Operaciones ============
@@ -48,7 +81,7 @@ const ops = {
     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,
+      quote_id: q.id, quote_sha256: sha256hex(canonical(q)), accept_sha256: ctx.opHash, ...(q.service ? { service: q.service } : {}),
       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 };
@@ -112,6 +145,43 @@ const ops = {
     return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento } }] };
   },
 
+  // --- escrow que vence (NX-503): el comprador recupera; una entrega sin objeción se libera ---
+  // Antes un contrato vencido sólo mandaba un aviso y la plata quedaba retenida para siempre.
+  // reclaim: sólo el comprador, sólo sin entrega, y sólo pasado el plazo más la gracia de la casa.
+  async reclaim(ctx) {
+    const { libro, from, body } = ctx;
+    const c = await getContract(libro, body.contract);
+    must(c.kind === 'escrow', 409, 'reclaim only applies to escrow');
+    must(from === c.buyer, 403, 'only the buyer reclaims an expired escrow');
+    must(c.state === 'held', 409, c.state === 'delivered' ? 'the seller already delivered: refund needs the seller or the arbiter, or the review window' : `state ${c.state}`);
+    const plazo = Date.parse(c.terms?.deadline || '');
+    must(!Number.isNaN(plazo), 409, 'this escrow has no deadline: only the seller or the arbiter can refund it');
+    const desde = plazo + libro.reclaimGraceMs;
+    must(Date.now() >= desde, 409, `the deadline plus the grace period has not passed yet (reclaimable from ${new Date(desde).toISOString()})`);
+    const asiento = await libro.refund(c.id, c.buyer, c.amount, `escrow vencido ${c.id}: ${c.concept}`, { contract: c.id, kind: 'reclaim' }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    c.state = 'refunded';
+    record(libro, c, 'reclaim', from, { asiento: asiento.id, deadline: c.terms.deadline });
+    return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento } }] };
+  },
+  // expire: lo firma la CASA (libro@) desde el reloj, nunca una parte. Entregado, con plazo vencido,
+  // y pasada la ventana de revisión sin que nadie devolviera ni liberara: se libera al vendedor.
+  // «Sin disputa» quiere decir que ni el comprador ni el árbitro hicieron refund en la ventana.
+  async expire(ctx) {
+    const { libro, from, body } = ctx;
+    must(from === libro.address, 403, 'only the house settles an expired escrow');
+    const c = await getContract(libro, body.contract);
+    must(c.kind === 'escrow' && c.state === 'delivered', 409, `state ${c.state}, expected a delivered escrow`);
+    const plazo = Date.parse(c.terms?.deadline || '');
+    must(!Number.isNaN(plazo), 409, 'no deadline: a delivery without a deadline waits for the buyer or the arbiter');
+    const entregado = Date.parse(c.history.findLast?.((h) => h.op === 'deliver')?.at || c.history.filter((h) => h.op === 'deliver').at(-1)?.at || '');
+    const desde = Math.max(plazo, entregado || 0) + libro.reviewWindowMs;
+    must(Date.now() >= desde, 409, `the review window is still open (until ${new Date(desde).toISOString()})`);
+    const asiento = await libro.release(c.id, c.seller, c.amount, `liberación por ventana vencida ${c.id}: ${c.concept}`, { contract: c.id, kind: 'expire' }, { op: ctx.env.id, op_sha256: ctx.opHash }, c.referrer);
+    c.state = 'released';
+    record(libro, c, 'expire', from, { asiento: asiento.id, review_until: new Date(desde).toISOString() });
+    return { result: { contract: c, asiento }, recibos: [{ to: parties(c), thread: c.id, body: { contract: c, asiento, note: 'delivered, deadline passed, not refunded within the review window: released by the house clock' } }] };
+  },
+
   // --- fianza: el que afirma deposita; si la verificación lo derriba, la pierde ---
   async bond(ctx) {
     const { libro, from, body } = ctx;
@@ -161,7 +231,7 @@ const ops = {
       must(body.cap <= parent.cap - parent.spent, 403, `the sub-mandate (${body.cap}) exceeds what the parent has left (${parent.cap - parent.spent})`);
       if (parent.expires) must(!body.expires || Date.parse(body.expires) <= Date.parse(parent.expires), 403, 'the sub-mandate cannot outlast its parent');
     }
-    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,
+    const m = { id: uuid(), house: libro.domain, grantor: from, grantee: body.grantee, cap: body.cap, spent: 0, scope: validarAlcance(body.scope, body.cap), 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);
@@ -180,7 +250,14 @@ const ops = {
       must(cur.state === 'active', 409, `mandate ${cur.id} is not active`);
       must(!cur.expires || Date.parse(cur.expires) > Date.now(), 410, `mandato ${cur.id} vencido`);
       must(cur.cap - cur.spent >= body.amount, 402, `mandate ${cur.id}: ${cur.cap - cur.spent} left, ${body.amount} requested`);
+      // Fallar cerrado: un mandato guardado ANTES de este candado puede llevar una restricción que
+      // no sabemos aplicar. No se cobra contra él hasta que su mandante lo rehaga.
+      const ajenas = Object.keys(cur.scope || {}).filter((k) => !ALCANCE_MANDATO.includes(k));
+      must(!ajenas.length, 403, `mandate ${cur.id} carries ${ajenas.map((k) => JSON.stringify(k)).join(', ')} in its scope, which this ledger cannot enforce; it refuses to charge against a limit it cannot apply`);
       if (cur.scope?.concepts?.length) must(cur.scope.concepts.includes(body.concept), 403, `concept "${body.concept}" is outside the mandate scope`);
+      // Tope por cobro: el total ya no se puede vaciar de un solo golpe. Se comprueba en CADA
+      // eslabón, así que el tope del padre acota lo que cobra el nieto.
+      if (cur.scope?.max_per_charge != null) must(body.amount <= cur.scope.max_per_charge, 403, `mandate ${cur.id} caps a single charge at ${cur.scope.max_per_charge}, and ${body.amount} was requested`);
       chain.push(cur);
     }
     // El descuento de la cadena y el asiento van en la MISMA transacción: si el commit falla,
@@ -202,22 +279,54 @@ const ops = {
     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 } }] };
   },
 
+  // --- pagar directo: sin cotización ni contrato. Lo firma el que paga; el que recibe no hace nada.
+  // Es el "te mando plata" entre dos personas. Sólo dentro de la casa: aquí no hay cómo comprobar
+  // que una dirección de otra casa existe, y un pago a nadie deja tokens varados para siempre.
+  async pay(ctx) {
+    const { libro, from, body } = ctx;
+    let to; try { to = parseAddress(body.to); } catch { fail(400, 'pay needs "to": the address that receives'); }
+    const address = `${to.local}@${to.domain}`;
+    must(to.domain === libro.domain, 400, `pay moves tokens inside ${libro.domain}; ${to.domain} keeps its own ledger`);
+    must(address !== from, 400, 'paying yourself moves nothing');
+    must(Number.isSafeInteger(body.amount) && body.amount > 0, 400, 'amount must be a positive integer');
+    scopeCap(ctx, body.amount, 'paying');
+    const rec = await libro.store.getAgent(to.local);
+    must(rec && !rec.revoked, 404, `${address} does not exist in this house`);
+    // Un subagente de sólo mensajes nunca podrá gastar: lo que le llegue quedaría varado. Se le paga al dueño.
+    must(!rec.delegation?.scope?.messages_only, 400, `${address} only carries messages and could never spend this; pay its owner, ${rec.delegation?.by}`);
+    const concept = typeof body.concept === 'string' && body.concept.trim() ? body.concept.trim().slice(0, 200) : `pago de ${from}`;
+    // Sin fee (decidido por Nicholas el 11-sep-2026): mandarle tokens a una persona es gratis, como un
+    // mensaje. El fee de la casa (0,5%) es para el trabajo que alguien encarga: spot, escrow, mandatos.
+    const asiento = await libro.post(concept, [{ account: from, delta: -body.amount }, { account: address, delta: body.amount }], { kind: 'pay', to: address, fee: 0 }, { op: ctx.env.id, op_sha256: ctx.opHash });
+    // El aviso al que recibe obedece a su buzón, como si el pagador le escribiera. Defecto real
+    // (revisión del 11-sep-2026): con pay sin fee, un pago de 1 token dejaba un sobre de libro@ en un
+    // buzón que cobra 500 por mensaje. El pago ocurre igual y el saldo lo muestra; el aviso no pasa.
+    const p = applyInboxPolicy({ from, to: [address], type: 'receipt' }, rec, null);
+    const avisar = p.ok === true && (!p.stamp || body.amount >= p.stamp.price);
+    return { result: { asiento, notified: avisar }, recibos: [{ to: avisar ? [from, address] : [from], body: { asiento, pay: { from, to: address, amount: body.amount, concept } } }] };
+  },
+
   // --- 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 } }] };
   },
+  // Estado de cuenta (NX-501): `since`/`until` ISO-8601 acotan el rango, `limit` cuántos asientos
+  // (tope 200 por correo: el recibo viaja en un sobre). Devuelve saldo inicial, filas (fee y
+  // comisión como filas propias), saldo final y totales que cuadran. Ver estado.js.
   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 } }] };
+    const { since, until, limit } = ctx.body;
+    const estado = await estadoDeCuenta(ctx.libro, ctx.from, { since, until, limit, max: 200 });
+    return { result: estado, recibos: [{ to: [ctx.from], body: estado }] };
   },
   async contract(ctx) {
     const c = await getContract(ctx.libro, ctx.body.contract);
     must(parties(c).includes(ctx.from), 403, 'you are not a party to this contract');
     return { result: { contract: c }, recibos: [{ to: [ctx.from], thread: c.id, body: { contract: c } }] };
   },
+
+  // --- notaría (NX-601): sellar el hash de un documento con fecha y firma de la casa. Sin dinero.
+  notarize,
 };
 
 // ============ Tipos de contrato cotizables ============
@@ -235,7 +344,7 @@ export const CONTRATOS = {
   } },
   // 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,
+    const m = { id: uuid(), house: libro.domain, grantor: c.buyer, grantee: c.seller, cap: c.amount, spent: 0, scope: validarAlcance(q.terms?.scope, c.amount), 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);