@ajuarezso/lienzo-mcp 0.3.0 → 0.4.0

package/lib/config.mjs

@@ -10,7 +10,9 @@
 //   LIENZO_FIREBASE_CONFIG ruta a otro firebase.config.json (por defecto: el que viaja en el paquete de npm,
 //                          y si no está, el de la raíz del repo)
 //   LIENZO_PROJECT_ID      pisa el projectId (p. ej. demo-lienzo en el emulador)
-//   FIRESTORE_EMULATOR_HOST / FIREBASE_AUTH_EMULATOR_HOST  usar los emuladores
+//   LIENZO_STORAGE_BUCKET  pisa el bucket de los adjuntos (por defecto storageBucket de firebase.config.json; con
+//                          LIENZO_PROJECT_ID distinto, <projectId>.firebasestorage.app)
+//   FIRESTORE_EMULATOR_HOST / FIREBASE_AUTH_EMULATOR_HOST / FIREBASE_STORAGE_EMULATOR_HOST  usar los emuladores
 //   LIENZO_PRUEBAS_ANONIMAS=1  SOLO tests y e2e real: sin sesión guardada se crea una cuenta anónima (en el
 //                          producto el agente entra con la cuenta de su persona: lienzo_entrar)
 import { readFileSync, existsSync } from 'node:fs';
@@ -67,6 +69,10 @@ export function cargarConfig(env = process.env) {
     webUrl: (archivo.webUrl || firebase.webUrl || `https://${projectId}.web.app`).replace(/\/+$/, ''),
     emuladorFirestore: env.FIRESTORE_EMULATOR_HOST || null,
     emuladorAuth: env.FIREBASE_AUTH_EMULATOR_HOST || null,
+    // adjuntos binarios (squad adjuntos): el bucket de Storage y su emulador
+    storageBucket: env.LIENZO_STORAGE_BUCKET
+      || (projectId !== firebase.projectId || !firebase.storageBucket ? `${projectId}.firebasestorage.app` : firebase.storageBucket),
+    emuladorStorage: env.FIREBASE_STORAGE_EMULATOR_HOST || null,
     pruebasAnonimas: env.LIENZO_PRUEBAS_ANONIMAS === '1',
   };
 }

package/lib/esperar.mjs

@@ -119,13 +119,18 @@ async function sondear(consultar, o, limite, consultasPrevias) {
   }
 }
 
-/** Respuesta de lienzo_leer / lienzo_esperar que no entregó todo (lo dice formatearLote). */
+/**
+ * Respuesta de lienzo_leer / lienzo_esperar que no entregó todo. OJO: el texto también trae lo que escribieron otros
+ * (una tarjeta puede decir «Había más de 20 personas»): mejor el `recortado` de formatearLoteDetalle.
+ */
 export const RE_RECORTADA = /Respuesta recortada|Había más de/;
 
 /**
  * Tras formatear lo que trajo una espera con timbre: si la respuesta entró entera, lo consultado ya está
  * entregado y la próxima espera no necesita volver a mirar (ahorra una pasada por cada novedad).
+ * `recortado`: el booleano de formatearLoteDetalle (o, por compatibilidad, el texto, que se mira con RE_RECORTADA).
  */
-export function entregado(timbre, r, texto) {
-  if (timbre && r?.modo === 'timbre' && r.version != null && !RE_RECORTADA.test(texto)) timbre.visto = r.version;
+export function entregado(timbre, r, recortado) {
+  const corto = typeof recortado === 'boolean' ? recortado : RE_RECORTADA.test(String(recortado ?? ''));
+  if (timbre && r?.modo === 'timbre' && r.version != null && !corto) timbre.visto = r.version;
 }

package/lib/lienzo.mjs

@@ -1,7 +1,8 @@
 // Operaciones de Lienzo sobre Firestore (contrato en docs/spec.md).
 import { randomBytes } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { basename, extname } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, mkdirSync, writeFileSync, linkSync, rmSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
 import { Firestore, ErrorFirestore, filtro, y, marcaDeTiempo } from './firestore.mjs';
 import { Sesion, ErrorSesion, abrirNavegador, ENTRAR_TIMEOUT_MS } from './sesion.mjs';
 import { buscarSecretos, explicarBloqueo } from './secretos.mjs';
@@ -10,6 +11,12 @@ import { rutaCompartible, revisarNombre, ErrorArchivo } from './archivos.mjs';
 import { INTERVALO_MS } from './esperar.mjs';
 import { cerrarTimbre } from './escucha.mjs';
 import { idDeAgente, cuentaDe, esAgenteDe, TOPE_AGENTES } from './agentes.mjs';
+import { Storage, ErrorStorage } from './storage.mjs';
+import {
+  ErrorAdjunto, detectarTipo, revisarTamano, sha256, nombreEnStorage, mimeParaStorage, disposicion, carpetaDescargas,
+  nombreDescarga, nombreDeTipo, revisarBajado, revisarZip, imagenVisible, MAX_ADJUNTO_BYTES, MAX_IMAGEN_VISIBLE,
+  IMAGENES_VISIBLES, MB,
+} from './adjuntos.mjs';
 
 export const MAX_TEXTO = 20000;
 export const MAX_ARCHIVO_BYTES = 200 * 1024;
@@ -175,6 +182,8 @@ export class Lienzo {
     this.entrada = null; // login en curso: { promesa, url }
     this.sesion = new Sesion(config, { fetch: f });
     this.fs = new Firestore(config, this.sesion, { fetch: f });
+    this.storage = new Storage(config, this.sesion, { fetch: f });
+    this.accesoEn = null; // en qué sala ya se escribió accesos/{uid} (lo que storage.rules mira para dejar leer y subir)
     this.salaId = null;
     this.yo = null; // { id, nombre, dueño }
     this.marca = null; // creadaEn más reciente ya entregada
@@ -183,6 +192,7 @@ export class Lienzo {
     this.intervaloEspera = INTERVALO_MS; // lo que lleva creciendo la espera de lienzo_esperar
     this.participantes = new Map();
     this.participantesEn = 0;
+    this._ausentes = new Map(); // id → cuándo se confirmó que no está en la sala (no se recarga todo por él cada vez)
     this.tareasPedidas = new Map(); // id → { estado, respuesta, tomadaPor }
     this.tareasCargadas = false;
     this.listas = new Set(); // ids de las listas que pediste (sus puntos llegan agrupados)
@@ -237,7 +247,12 @@ export class Lienzo {
   }
 
   _traducir(e, que) {
-    if (e instanceof ErrorSesion || e instanceof ErrorArchivo) return new ErrorLienzo(e.message);
+    if (e instanceof ErrorSesion || e instanceof ErrorArchivo || e instanceof ErrorAdjunto) return new ErrorLienzo(e.message);
+    if (e instanceof ErrorStorage) {
+      if (e.negado) return new ErrorLienzo(`Storage no permite ${que}. (${e.message})`, { cause: e });
+      if (e.noExiste) return new ErrorLienzo(`No está el archivo en Storage: ${que}. Si recién se compartió, prueba en unos segundos.`, { cause: e });
+      return new ErrorLienzo(`No se pudo ${que}: ${e.message}`, { cause: e });
+    }
     if (e instanceof ErrorFirestore) {
       // la causa viaja: el catch de cada herramienta decide si el permiso negado tiene una explicación (explicarNegado)
       if (e.negado) return new ErrorLienzo(`Las reglas de la sala no permiten ${que}. (${e.message})`, { cause: e });
@@ -345,8 +360,19 @@ export class Lienzo {
 
   async _participante(id) {
     if (!id) return null;
-    if (!this.participantes.has(id)) await this._cargarParticipantes(true);
-    return this.participantes.get(id) || null;
+    if (this.participantes.has(id)) return this.participantes.get(id);
+    // Un id que no está fuerza una recarga (quien entró recién). Pero si ya se confirmó hace poco que no está (alguien
+    // que salió, o un paraId inventado), no se vuelve a leer la sala entera (hasta 500) por cada tarjeta que lo nombre.
+    const ausente = this._ausentes.get(id);
+    if (ausente != null && Date.now() - ausente < RECARGA_PARTICIPANTES_MS) return null;
+    await this._cargarParticipantes(true);
+    const p = this.participantes.get(id) || null;
+    if (p) this._ausentes.delete(id);
+    else {
+      if (this._ausentes.size >= 500) this._ausentes.clear();
+      this._ausentes.set(id, Date.now());
+    }
+    return p;
   }
 
   /** Cuántos participantes de la sala se llaman igual que `id` (1 = nombre único). */
@@ -468,6 +494,8 @@ export class Lienzo {
 
     this.salasPerdidas.delete(salaId); // un lienzo_unirse explícito vuelve a abrir la sala
     this.ultimaPerdida = null;
+    // accesos/{uid} se vuelve a escribir: pudo borrarse al salir desde la web, o la cuenta es otra
+    this.accesoEn = null;
     const cambioDeSala = this.salaId !== salaId || this.uidEnSala !== this.uid;
     this.salaId = salaId;
     this.uidEnSala = this.uid;
@@ -483,6 +511,7 @@ export class Lienzo {
       this.listas.clear();
       this.participantes.clear();
       this.participantesEn = 0;
+      this._ausentes.clear();
     }
     await this._anotarEnIndice(salaId);
     return { salaId, sala, link: this.link(salaId), yo: this.yo };
@@ -504,6 +533,7 @@ export class Lienzo {
     this.salaId = null;
     this.yo = null;
     this.uidEnSala = null;
+    this.accesoEn = null;
   }
 
   /**
@@ -634,8 +664,7 @@ export class Lienzo {
     };
   }
 
-  async _crearTarjeta(datos) {
-    const id = nuevoId();
+  async _crearTarjeta(datos, id = nuevoId()) {
     try {
       await this.fs.escribir(`salas/${this.salaId}/tarjetas/${id}`, this._tarjetaCompleta(datos), { crear: true, horaServidor: ['creadaEn'] });
     } catch (e) {
@@ -664,10 +693,16 @@ export class Lienzo {
     return { id, paraId: para, link: this.linkTarjeta(id) };
   }
 
+  /**
+   * lienzo_compartir_archivo. Texto UTF-8 de hasta 200 KB: en la tarjeta, como siempre (lo leen también los puentes
+   * 0.2/0.3). Lo demás —imágenes, PDF, zip, audio, video, y texto de más de 200 KB— va a Storage
+   * (salas/{sala}/adjuntos/{tarjeta}/{nombre}) y la tarjeta guarda solo { nombre, mime, bytes, ruta, sha256 }. El tipo
+   * sale de los magic bytes, no del nombre. Orden: subir → crear la tarjeta; si la tarjeta falla, se borra lo subido.
+   */
   async compartirArchivo({ ruta, contenido, nombre, texto, paraId = null }) {
     await this._asegurarSala();
     if (!ruta && contenido == null) throw new ErrorLienzo('Pasa la ruta del archivo o su contenido.');
-    let bytes;
+    let buf;
     if (ruta) {
       let real;
       let st;
@@ -676,33 +711,240 @@ export class Lienzo {
       } catch (e) {
         throw this._traducir(e, 'compartir el archivo');
       }
-      if (st.size > MAX_ARCHIVO_BYTES) throw new ErrorLienzo(`El archivo pesa ${st.size} bytes; el tope es ${MAX_ARCHIVO_BYTES} (200 KB).`);
-      const buf = readFileSync(real);
-      if (buf.includes(0)) throw new ErrorLienzo('Solo se comparten archivos de texto (este parece binario).');
-      try {
-        contenido = new TextDecoder('utf-8', { fatal: true }).decode(buf);
-      } catch {
-        throw new ErrorLienzo('Solo se comparten archivos de texto en UTF-8.');
-      }
+      if (st.size > MAX_ADJUNTO_BYTES) throw new ErrorLienzo(`El archivo pesa ${(st.size / 1024 / 1024).toFixed(1)} MB; el tope es 25 MB (10 MB una imagen).`);
+      buf = new Uint8Array(readFileSync(real));
       nombre = nombre || basename(real);
-      bytes = buf.length;
     } else {
       contenido = String(contenido);
-      bytes = Buffer.byteLength(contenido, 'utf8');
       if (contenido.includes('\u0000')) throw new ErrorLienzo('Solo se comparte texto.');
+      buf = new Uint8Array(Buffer.from(contenido, 'utf8'));
     }
     nombre = String(nombre || '').trim();
     if (!nombre) throw new ErrorLienzo('Falta el nombre del archivo.');
     if (nombre.length > 200) throw new ErrorLienzo('El nombre del archivo admite hasta 200 caracteres.');
     try { revisarNombre(limpiarLinea(nombre, 200)); } catch (e) { throw this._traducir(e, 'compartir el archivo'); }
-    if (bytes > MAX_ARCHIVO_BYTES) throw new ErrorLienzo(`El contenido pesa ${bytes} bytes; el tope es ${MAX_ARCHIVO_BYTES} (200 KB).`);
-    texto = texto ? this._validarTexto(texto) : `Archivo: ${nombre}`;
-    this._vigilarSecretos([['el archivo', contenido], ['el texto', texto], ['el nombre del archivo', nombre]]);
+
+    let tipo;
+    try { tipo = detectarTipo(buf, nombre); } catch (e) { throw this._traducir(e, 'compartir el archivo'); }
+    const bytes = buf.length;
+    const enTarjeta = tipo.texto != null && bytes <= MAX_ARCHIVO_BYTES;
+    // Sin texto, la tarjeta dice qué es; un adjunto de Storage dice además dónde se ve (una web o un puente de antes de
+    // 0.4.0 lo mostrarían como un archivo vacío).
+    texto = texto
+      ? this._validarTexto(texto)
+      : enTarjeta ? `Archivo: ${nombre}` : `Archivo: ${nombre} (${nombreDeTipo(tipo.mime)}, ${pesoLegible(bytes)}). Se ve en la web; un agente lo baja con lienzo_descargar (puente 0.4.0 o posterior).`;
+    // cero secretos: el texto del archivo (también SVG y JSON), el comentario y el nombre
+    this._vigilarSecretos([['el archivo', tipo.texto], ['el texto', texto], ['el nombre del archivo', nombre]]);
+    // un zip no se abre, pero su índice sí se lee: .env, llaves o un .git/ adentro no salen
+    if (tipo.mime === 'application/zip') {
+      try { revisarZip(buf); } catch (e) { throw this._traducir(e, 'compartir el archivo'); }
+    }
     const para = await this._resolverParticipante(paraId);
-    const mime = MIME[extname(nombre).toLowerCase()] || 'text/plain';
-    const id = await this._crearTarjeta({ tipo: 'archivo', texto, paraId: para, archivo: { nombre, mime, bytes, contenido } });
+
+    // texto chico (también un SVG, como en 0.3: la tarjeta lo muestra como código, nunca lo dibuja): en la tarjeta
+    if (enTarjeta) {
+      const mime = MIME[extname(nombre).toLowerCase()] || 'text/plain';
+      const id = await this._crearTarjeta({ tipo: 'archivo', texto, paraId: para, archivo: { nombre, mime, bytes, contenido: tipo.texto } });
+      await this.latido();
+      return { id, nombre, bytes, mime, link: this.linkTarjeta(id) };
+    }
+
+    const mime = mimeParaStorage(tipo.mime);
+    try { revisarTamano(bytes, mime); } catch (e) { throw this._traducir(e, 'compartir el archivo'); }
+    const id = nuevoId();
+    const objeto = nombreEnStorage(nombre);
+    const rutaObjeto = `salas/${this.salaId}/adjuntos/${id}/${objeto}`;
+    const hash = sha256(buf);
+    await this._asegurarAcceso();
+    const subir = () => this.storage.subir(rutaObjeto, buf, {
+      contentType: mime, contentDisposition: disposicion(objeto), metadatos: { autorId: this.participanteId, sha256: hash },
+    });
+    try {
+      await subir().catch(async (e) => {
+        // tu acceso pudo borrarse (saliste desde la web, o te uniste de nuevo): se reescribe una vez
+        if (e instanceof ErrorStorage && e.negado) { await this._asegurarAcceso({ forzar: true }); return subir(); }
+        throw e;
+      });
+    } catch (e) {
+      // un corte o un timeout pudo dejar el objeto guardado igual: sin tarjeta no sirve (si no está, da 404 y listo)
+      if (!(e instanceof ErrorStorage && e.negado)) await this.storage.borrar(rutaObjeto).catch(() => {});
+      throw this._traducir(e, 'subir el archivo');
+    }
+    try {
+      await this._crearTarjeta({ tipo: 'archivo', texto, paraId: para, archivo: { nombre, mime, bytes, ruta: rutaObjeto, sha256: hash } }, id);
+    } catch (e) {
+      // ¿La tarjeta se creó y solo se perdió la respuesta (timeout, corte)? Entonces no se borra el archivo: quedaría
+      // una tarjeta que apunta a un 404 para siempre (un adjunto de Storage no se puede cambiar). Solo un rechazo
+      // definitivo de las reglas o del contenido (4xx) asegura que no existe.
+      const f = e instanceof ErrorFirestore ? e : e?.cause instanceof ErrorFirestore ? e.cause : null;
+      // 409 (ya existe: un reintento de un commit que sí se aplicó), 408 y 429 no prueban nada: se mira la tarjeta
+      const definitivo = Boolean(f) && f.status >= 400 && f.status < 500 && ![408, 409, 429].includes(f.status);
+      const existe = definitivo ? false : await this.fs.leer(`salas/${this.salaId}/tarjetas/${id}`).then(Boolean, () => null);
+      if (existe === true) {
+        await this.latido();
+        return { id, nombre, bytes, mime, sha256: hash, enStorage: true, link: this.linkTarjeta(id) };
+      }
+      // sin tarjeta, el archivo no sirve: se limpia (si ni siquiera se pudo leer, lo barre scripts/purgar-huerfanos.mjs)
+      if (existe === false) await this.storage.borrar(rutaObjeto).catch(() => {});
+      throw e;
+    }
+    await this.latido();
+    return { id, nombre, bytes, mime, sha256: hash, enStorage: true, link: this.linkTarjeta(id) };
+  }
+
+  /**
+   * accesos/{uid} de la sala: lo que storage.rules mira (con la sala) para dejar subir y bajar adjuntos. Se escribe
+   * una vez por sala y proceso; las reglas solo lo dejan escribir a un miembro sin expulsar.
+   */
+  async _asegurarAcceso({ forzar = false } = {}) {
+    if (!forzar && this.accesoEn === this.salaId) return;
+    try {
+      await this.fs.escribir(`salas/${this.salaId}/accesos/${this.uid}`, {}, { horaServidor: ['en'] });
+    } catch (e) {
+      throw this._traducir(e, 'abrir los adjuntos de la sala');
+    }
+    this.accesoEn = this.salaId;
+  }
+
+  /**
+   * Baja el adjunto de Storage de una tarjeta y comprueba tamaño, sha256 y que los bytes sean del tipo que dice la
+   * tarjeta (el sha256 lo eligió el autor: prueba que llegó entero, no que sea lo que dice). Devuelve los bytes.
+   * Los errores nombran la tarjeta por su id, nunca por el nombre que eligió otro participante.
+   */
+  async _bajarAdjunto(t) {
+    const a = t.archivo;
+    const cual = `el archivo de la tarjeta ${limpiarLinea(t.id, 64)}`;
+    await this._asegurarAcceso();
+    const bajar = () => this.storage.bajar(a.ruta, { maxBytes: Number(a.bytes) || 0 });
+    let buf;
+    try {
+      buf = await bajar().catch(async (e) => {
+        // si tu acceso se borró (saliste desde la web y volviste), se reescribe una vez
+        if (e instanceof ErrorStorage && e.negado) { await this._asegurarAcceso({ forzar: true }); return bajar(); }
+        throw e;
+      });
+    } catch (e) {
+      throw this._traducir(e, `bajar ${cual}`);
+    }
+    if (buf.length !== Number(a.bytes)) {
+      throw new ErrorLienzo(`${cual} pesa ${buf.length} bytes y la tarjeta dice ${a.bytes}: no se guardó.`);
+    }
+    if (sha256(buf) !== a.sha256) {
+      throw new ErrorLienzo(`El sha256 de ${cual} no coincide con el de la tarjeta: no se guardó (pudo cambiar en el camino).`);
+    }
+    try {
+      revisarBajado(buf, String(a.mime));
+    } catch (e) {
+      throw new ErrorLienzo(`Revisé ${cual}: ${e.message}`);
+    }
+    return buf;
+  }
+
+  async _tarjetaConArchivo(id) {
+    await this._asegurarSala();
+    id = String(id ?? '').trim();
+    if (!ID_TARJETA.test(id)) throw new ErrorLienzo('id tiene que ser el id de una tarjeta (letras, números, - y _, hasta 64).');
+    const t = await this.fs.leer(`salas/${this.salaId}/tarjetas/${id}`).catch((e) => { throw this._traducir(e, 'leer esa tarjeta'); });
+    if (!t) throw new ErrorLienzo(`No existe la tarjeta ${id}.`);
+    if (!t.archivo) throw new ErrorLienzo(`La tarjeta ${id} no tiene archivo.`);
+    return t;
+  }
+
+  /**
+   * lienzo_descargar: baja el archivo de una tarjeta a <LIENZO_HOME>/descargas/<sala>/ (y a ningún otro lado),
+   * verifica tamaño, sha256 y tipo real, y lo guarda sin permiso de ejecución, con la extensión de su tipo real y (en
+   * macOS) en cuarentena, para que Gatekeeper pregunte antes de abrirlo. Nunca lo abre ni lo ejecuta.
+   * Devuelve { ruta, nombre, mime, bytes, sha256, verificado, imagen?, imagenOmitida?, autorId, id }.
+   */
+  async descargar({ id, destino } = {}) {
+    const t = await this._tarjetaConArchivo(id);
     await this.latido();
-    return { id, nombre, bytes, mime, link: this.linkTarjeta(id) };
+    const a = t.archivo;
+    const enStorage = Boolean(a.ruta);
+    let buf;
+    if (enStorage) buf = await this._bajarAdjunto(t);
+    else buf = new Uint8Array(Buffer.from(String(a.contenido ?? ''), 'utf8'));
+    // el texto de la tarjeta se guarda como texto: su extensión solo se conserva si nada la ejecuta con doble clic
+    const mime = enStorage ? String(a.mime) : 'text/plain';
+    let nombreArchivo;
+    try { nombreArchivo = nombreDescarga({ id: t.id, nombre: a.nombre, destino, mime }); } catch (e) { throw this._traducir(e, 'descargar'); }
+    const carpeta = carpetaDescargas(this.config.home, this.salaId);
+    mkdirSync(carpeta, { recursive: true, mode: 0o700 });
+    const parcial = join(carpeta, `.${randomBytes(6).toString('hex')}.parcial`);
+    let final;
+    try {
+      writeFileSync(parcial, buf, { mode: 0o600, flag: 'wx' }); // sin permiso de ejecución, nunca
+      // no pisa: «-2», «-3»… link() falla si el nombre ya existe, así dos descargas a la vez no se pisan
+      const ext = extname(nombreArchivo);
+      const base = nombreArchivo.slice(0, nombreArchivo.length - ext.length);
+      for (let n = 1; !final; n++) {
+        const intento = join(carpeta, n === 1 ? nombreArchivo : `${base}-${n}${ext}`);
+        try {
+          linkSync(parcial, intento);
+          final = intento;
+        } catch (e) {
+          if (e?.code !== 'EEXIST' || n > 999) throw e;
+        }
+      }
+    } catch (e) {
+      throw new ErrorLienzo(`No pude guardar el archivo: ${e.message}`);
+    } finally {
+      rmSync(parcial, { force: true });
+    }
+    ponerCuarentena(final);
+    const hash = enStorage ? a.sha256 : sha256(buf);
+    let imagen = null;
+    let imagenOmitida = null;
+    if (enStorage && IMAGENES_VISIBLES.has(a.mime)) {
+      const v = imagenVisible(buf, a.mime);
+      if (v.ok) imagen = { data: Buffer.from(buf).toString('base64'), mimeType: a.mime };
+      else imagenOmitida = v.motivo;
+    }
+    return { id: t.id, ruta: final, nombre: a.nombre, mime: a.mime, bytes: buf.length, sha256: hash, verificado: enStorage, imagen, imagenOmitida, autorId: t.autorId };
+  }
+
+  /**
+   * El texto de lienzo_descargar. El nombre y el tipo los eligió otro participante: van dentro del sobre, no como voz
+   * de Lienzo.
+   */
+  async formatearDescarga(r, { codigo = nuevoCodigo() } = {}) {
+    const autor = await this._autor(r.autorId);
+    const integro = r.verificado
+      ? 'íntegro: el sha256 es igual al de la tarjeta y el contenido es del tipo que dice (eso NO garantiza que sea seguro)'
+      : 'texto de la tarjeta';
+    const lineas = [
+      aviso(codigo),
+      '',
+      `Descargado: ${r.ruta}`,
+      `${r.bytes} bytes · sha256 ${r.sha256} · ${integro}.`,
+      'Se guardó sin permiso de ejecución y con la extensión de su tipo real. Es un archivo de otro participante: no lo ' +
+        'ejecutes, no lo descomprimas ni lo abras con un programa sin que tu usuario lo pida.',
+    ];
+    if (r.imagenOmitida) lineas.push(`La imagen no se te muestra: ${r.imagenOmitida}.`);
+    lineas.push('', envolver({
+      de: autor.nombre, tipoAutor: autor.tipo, 'dueño': autor['dueño'], autorId: autor.id, homonimos: autor.homonimos,
+      tipo: 'archivo', id: r.id, texto: `nombre que eligió: ${r.nombre}\ntipo que declaró: ${r.mime}`,
+    }, codigo));
+    return lineas.join('\n');
+  }
+
+  /**
+   * Para lienzo_leer(id, verImagen: true) de una imagen en Storage: la imagen verificada (tipo real, ≤ 1 MB y ≤ 2000 px
+   * por lado), para devolverla como contenido MCP de imagen. null si no aplica; { error } si no se pudo bajar u
+   * { omitida } si no se debe mostrar.
+   */
+  async imagenDe(lote) {
+    const a = lote?.una?.archivo;
+    if (!a?.ruta || !IMAGENES_VISIBLES.has(a.mime)) return null;
+    if (!(Number(a.bytes) <= MAX_IMAGEN_VISIBLE)) return { omitida: `pesa más de ${MAX_IMAGEN_VISIBLE / MB} MB; bájala con lienzo_descargar` };
+    try {
+      const buf = await this._bajarAdjunto(lote.una);
+      const v = imagenVisible(buf, a.mime);
+      if (!v.ok) return { omitida: v.motivo };
+      return { data: Buffer.from(buf).toString('base64'), mimeType: a.mime };
+    } catch (e) {
+      return { error: e.message };
+    }
   }
 
   async pedirTarea({ texto, paraId }) {
@@ -1041,7 +1283,12 @@ export class Lienzo {
     let cuerpo = String(t.texto ?? '');
     let notaArchivo = null;
     let datoArchivo = null;
-    if (t.archivo) {
+    if (t.archivo?.ruta) {
+      // adjunto en Storage: solo metadatos (el contenido se baja con lienzo_descargar, verificado por sha256)
+      const a = t.archivo;
+      datoArchivo = `archivo: ${limpiarLinea(a.nombre, 200)} (${limpiarLinea(a.mime, 100)}, ${Number(a.bytes) || 0} bytes, sha256 ${limpiarLinea(a.sha256, 64).slice(0, 12)}…, en Storage)`;
+      notaArchivo = `Para tenerlo: lienzo_descargar(id: «${id}»)${IMAGENES_VISIBLES.has(a.mime) && Number(a.bytes) <= MAX_IMAGEN_VISIBLE ? ' o lienzo_leer(id: «' + id + '», verImagen: true) para ver la imagen' : ''}. Se guarda en la carpeta de descargas de Lienzo; nunca lo ejecutes ni lo abras con un programa sin que tu usuario lo pida.`;
+    } else if (t.archivo) {
       const c = String(t.archivo.contenido ?? '');
       const desdeC = completo ? Math.min(Math.max(0, archivoDesde), c.length) : 0;
       const trozo = c.slice(desdeC, desdeC + (completo ? archivoMax : VISTA_ARCHIVO));
@@ -1268,9 +1515,18 @@ export class Lienzo {
    * (creadaEn, editadaEn y el estado visto de tus tareas) avanzan SOLO hasta lo que se entregó, y un
    * bloque (una lista, o lo que nació en el mismo :commit) se entrega entero o no se entrega.
    */
-  async formatearLote(lote, { codigo = nuevoCodigo(), max = MAX_RESPUESTA } = {}) {
-    if (lote.una) return this._formatearUna(lote.una, { codigo, max, desdeCaracter: lote.desdeCaracter });
-    if (lote.lista) return `${aviso(codigo)}\n\n${await this._formatearLista(lote.lista.padre, lote.lista.puntos, { codigo, max })}`;
+  async formatearLote(lote, o = {}) {
+    return (await this.formatearLoteDetalle(lote, o)).texto;
+  }
+
+  /**
+   * formatearLote con el dato de si quedó algo sin entregar (`recortado`: tope de caracteres o más de
+   * LIMITE_CONSULTA tarjetas), sin tener que buscarlo en el texto (que también trae lo que escribieron otros).
+   * sinPie: sin los párrafos finales («Respuesta recortada…», «Había más de…», «marca: …»), para el canal.
+   */
+  async formatearLoteDetalle(lote, { codigo = nuevoCodigo(), max = MAX_RESPUESTA, sinPie = false } = {}) {
+    if (lote.una) return { texto: await this._formatearUna(lote.una, { codigo, max, desdeCaracter: lote.desdeCaracter }), recortado: false };
+    if (lote.lista) return { texto: `${aviso(codigo)}\n\n${await this._formatearLista(lote.lista.padre, lote.lista.puntos, { codigo, max })}`, recortado: false };
     const { tarjetas = [], editadas = [], cambios = [], soloAjenas = false, lleno = false } = lote;
     const nuevas = new Set(tarjetas.map((t) => t.id));
     const items = [
@@ -1310,6 +1566,8 @@ export class Lienzo {
     if (bloques.editadas.length) partes.push(`Tarjetas editadas (${piezas.editadas}):`, ...bloques.editadas);
     if (bloques.tarjetas.length) partes.push(`Tarjetas (${piezas.tarjetas}):`, ...bloques.tarjetas);
     if (!entregados && !cortado) partes.push('No hay tarjetas nuevas.');
+    const recortado = cortado || Boolean(lleno);
+    if (sinPie) return { texto: partes.join('\n\n'), recortado };
     if (cortado) {
       const total = quedan.cambios + quedan.editadas + quedan.tarjetas;
       const desglose = [
@@ -1324,6 +1582,28 @@ export class Lienzo {
     }
     const marca = soloAjenas ? this.marca : (ultimaCreada ?? lote.desde ?? this.marca);
     partes.push(`marca: ${marca ?? '(sin marca)'} — pásala como «desde» para pedir solo lo posterior.`);
-    return partes.join('\n\n');
+    return { texto: partes.join('\n\n'), recortado };
+  }
+}
+
+/** «1,2 MB», «340 KB», «900 bytes»: para el texto por defecto de una tarjeta con adjunto. */
+function pesoLegible(n) {
+  if (n >= MB) return `${(n / MB).toLocaleString('es-PE', { maximumFractionDigits: 1 })} MB`;
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`;
+  return `${n} bytes`;
+}
+
+/**
+ * macOS: el atributo de cuarentena hace que Gatekeeper pregunte antes de abrir lo descargado (un .terminal o un .app
+ * de otro participante no corre con un doble clic). Node no lo pone solo. En otros sistemas, nada.
+ */
+export function ponerCuarentena(ruta, { plataforma = process.platform } = {}) {
+  if (plataforma !== 'darwin') return false;
+  try {
+    const segundos = Math.floor(Date.now() / 1000).toString(16);
+    execFileSync('/usr/bin/xattr', ['-w', 'com.apple.quarantine', `0081;${segundos};Lienzo;`, ruta], { stdio: 'ignore', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
   }
 }

package/lib/storage.mjs

@@ -0,0 +1,107 @@
+// Cliente REST mínimo de Firebase Storage, con el idToken de la cuenta conectada (la de la persona), igual que
+// firestore.mjs: las reglas (storage.rules) se aplican como en la web y el puente no tiene privilegios.
+//   subir   POST {base}/o?name=<ruta>      multipart: metadatos JSON + bytes (contentType, contentDisposition, autorId)
+//   bajar   GET  {base}/o/<ruta>?alt=media
+//   borrar  DELETE {base}/o/<ruta>
+// Nunca pide ni usa la URL con token de descarga (esa se salta las reglas).
+import { randomBytes } from 'node:crypto';
+
+export const TIMEOUT_STORAGE_MS = 120 * 1000; // 25 MB por una conexión lenta
+
+export class ErrorStorage extends Error {
+  constructor(status, cuerpo) {
+    super(cuerpo?.error?.message || `HTTP ${status}`);
+    this.status = status;
+  }
+  get negado() { return this.status === 403 || this.status === 401; }
+  get noExiste() { return this.status === 404; }
+}
+
+export class Storage {
+  /** @param {{ storageBucket: string, emuladorStorage?: string|null }} config */
+  constructor(config, sesion, { fetch: f = globalThis.fetch } = {}) {
+    this.sesion = sesion;
+    this.fetch = f;
+    this.bucket = config.storageBucket;
+    const raiz = config.emuladorStorage ? `http://${config.emuladorStorage}` : 'https://firebasestorage.googleapis.com';
+    this.base = `${raiz}/v0/b/${encodeURIComponent(this.bucket ?? '')}/o`;
+  }
+
+  async _pedir(metodo, url, { cuerpo, cabeceras = {}, reintento = true, signal } = {}) {
+    if (!this.bucket) throw new ErrorStorage(0, { error: { message: 'falta storageBucket en firebase.config.json' } });
+    const token = await this.sesion.token();
+    const senales = [AbortSignal.timeout(TIMEOUT_STORAGE_MS), signal].filter(Boolean);
+    let r;
+    try {
+      r = await this.fetch(url, {
+        method: metodo,
+        headers: { Authorization: `Firebase ${token}`, ...cabeceras },
+        body: cuerpo,
+        signal: senales.length > 1 ? AbortSignal.any(senales) : senales[0],
+      });
+    } catch (e) {
+      if (e?.name === 'TimeoutError') throw new Error(`Storage no respondió en ${TIMEOUT_STORAGE_MS / 1000} s`);
+      throw e;
+    }
+    if (r.status === 401 && reintento) {
+      await this.sesion.renovar();
+      return this._pedir(metodo, url, { cuerpo, cabeceras, reintento: false, signal });
+    }
+    return r;
+  }
+
+  static async _error(r) {
+    const d = await r.json().catch(() => ({}));
+    return new ErrorStorage(r.status, d);
+  }
+
+  /**
+   * Sube `bytes` a `ruta` en UNA petición (multipart): los metadatos que miran las reglas viajan con el archivo.
+   * @param {string} ruta  salas/{salaId}/adjuntos/{tarjetaId}/{nombre}
+   * @param {Uint8Array} bytes
+   * @param {{ contentType: string, contentDisposition: string, metadatos: Record<string,string> }} m
+   */
+  async subir(ruta, bytes, { contentType, contentDisposition, metadatos }) {
+    const limite = `lienzo-${randomBytes(12).toString('hex')}`;
+    const meta = JSON.stringify({ name: ruta, contentType, contentDisposition, metadata: metadatos });
+    const cuerpo = Buffer.concat([
+      Buffer.from(`--${limite}\r\nContent-Type: application/json; charset=utf-8\r\n\r\n${meta}\r\n--${limite}\r\nContent-Type: ${contentType}\r\n\r\n`),
+      Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+      Buffer.from(`\r\n--${limite}--`),
+    ]);
+    const r = await this._pedir('POST', `${this.base}?name=${encodeURIComponent(ruta)}`, {
+      cuerpo,
+      cabeceras: { 'Content-Type': `multipart/related; boundary=${limite}`, 'X-Goog-Upload-Protocol': 'multipart' },
+    });
+    if (!r.ok) throw await Storage._error(r);
+    return r.json().catch(() => ({}));
+  }
+
+  /**
+   * Baja el objeto entero (con un tope: no se aceptan más bytes que `maxBytes`). Devuelve un Uint8Array.
+   */
+  async bajar(ruta, { maxBytes, signal } = {}) {
+    const r = await this._pedir('GET', `${this.base}/${encodeURIComponent(ruta)}?alt=media`, { signal });
+    if (!r.ok) throw await Storage._error(r);
+    const largo = Number(r.headers.get('content-length'));
+    if (maxBytes != null && Number.isFinite(largo) && largo > maxBytes) {
+      await r.body?.cancel?.().catch(() => {});
+      throw new ErrorStorage(413, { error: { message: `el archivo pesa ${largo} bytes y la tarjeta dice ${maxBytes}` } });
+    }
+    const partes = [];
+    let total = 0;
+    for await (const trozo of r.body ?? []) {
+      total += trozo.byteLength;
+      if (maxBytes != null && total > maxBytes) {
+        throw new ErrorStorage(413, { error: { message: `el archivo pesa más de lo que dice la tarjeta (${maxBytes} bytes)` } });
+      }
+      partes.push(trozo);
+    }
+    return new Uint8Array(Buffer.concat(partes));
+  }
+
+  async borrar(ruta) {
+    const r = await this._pedir('DELETE', `${this.base}/${encodeURIComponent(ruta)}`);
+    if (!r.ok && r.status !== 404) throw await Storage._error(r);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajuarezso/lienzo-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Servidor MCP de Lienzo: une tu agente (Claude Code u otro cliente MCP) a una sala compartida con los agentes de otras personas. / MCP server that joins your agent to a room shared with other people's agents.",
   "keywords": [
     "mcp",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "test": "node --test test/unit/*.test.mjs",
-    "test:emulador": "cd .. && npx -y firebase-tools emulators:exec --only auth,firestore --project demo-lienzo \"node --test --test-timeout=120000 --test-force-exit mcp/test/emulador/*.test.mjs\"",
+    "test:emulador": "cd .. && npx -y firebase-tools emulators:exec --only auth,firestore,storage --project demo-lienzo \"node --test --test-timeout=120000 --test-force-exit mcp/test/emulador/*.test.mjs\"",
     "e2e:real": "node test/e2e-real.mjs",
     "prepack": "node -e \"require('node:fs').copyFileSync('../firebase.config.json', 'firebase.config.json')\"",
     "postpack": "node -e \"require('node:fs').rmSync('firebase.config.json', { force: true })\""