@dotrino/content 0.3.13

package/README.md

@@ -0,0 +1,183 @@
+# dotrino-content
+
+Nodo de contenido del ecosistema **Dotrino**: guarda y sirve **media pesada**
+(video/imagen/audio/archivos) direccionada por **hash de contenido** (`cid`),
+autohospedado por el usuario. Diseño completo en
+[`docs/DISENO.md`](./docs/DISENO.md); estado/continuación en
+[`docs/HANDOFF.md`](./docs/HANDOFF.md).
+
+> **Estado: Fase 2 (aparato del vault) + vistas previas públicas.** Al core local se
+> le suma la identidad: el node se enrola a tu bóveda y se puede administrar desde tus
+> apps por el proxy, sin abrir puertos. El HTTP de administración sigue escuchando
+> **solo en `127.0.0.1`**; con `--public` se abre, aparte, un puerto que sirve
+> **únicamente vistas previas** para que un enlace compartido tenga tarjeta en las
+> redes. El transporte P2P entre aparatos es lo que queda de la Fase 3.
+
+## Uso
+
+> **El paquete se llama `@dotrino/content` desde la 0.3.13.** Hasta la 0.3.12 se publicó
+> como `dotrino-content`, fuera del scope, y era el único del ecosistema así — el resto de
+> los daemons (`@dotrino/vaultd`, `@dotrino/sealers`, `@dotrino/terminal-agent`,
+> `@dotrino/tunnel`) siempre lo llevaron. No había ninguna razón detrás: nació así y nadie
+> lo revisó. **El comando no cambia**, sigue siendo `dotrino-content`; lo que cambia es lo
+> que se instala. Quien lo tenga puesto por el nombre viejo, reinstálelo:
+> `npm i -g @dotrino/content`.
+
+
+```sh
+# una vez: enlazar este node a tu bóveda (saca el código de `dotrino-vault pair`)
+npx @dotrino/content enroll <código>
+
+npx @dotrino/content start [--port 3777] [--dir ~/.dotrino-content] \
+  [--max-gb 50] [--max-blob-mb 512] [--gc-min 60] [--no-agent]
+
+# con vistas previas públicas (ver más abajo antes de encenderlo)
+npx @dotrino/content start --public --public-port 3778 --public-egress-gb 5 \
+  --public-url https://content.tudominio.com
+```
+
+Al enrolar, el node genera **su propia llave** y muestra un código que tienes que
+tipear en la bóveda para aprobarlo: ese código no viaja por la red, así que aprobar
+exige tener delante esta máquina. La **clave maestra nunca llega aquí** — solo un
+certificado con caducidad, que el node renueva solo y que puedes revocar
+(`dotrino-vault revoke <deviceId>`) sin tocar el resto de tus aparatos.
+
+Env: `DOTRINO_CONTENT_DIR` (datos), `DOTRINO_CONTENT_LINK_DIR` (enlace), `PORT`.
+Requiere **Node ≥ 22.5**. El core usa solo `node:crypto` y `node:sqlite`; la
+identidad viene de los pilares del ecosistema (`@dotrino/remote-agent`,
+`@dotrino/identity`).
+
+## Plano de control (Fase 2, por el proxy, cifrado)
+
+Con el node enlazado, tus propias apps —cualquier aparato con un certificado de **la
+misma** bóveda— pueden administrarlo a distancia dentro de una sesión cifrada:
+
+```
+hello                    quién es el node (owner, versión, uso de disco, tope)
+put {data,mime,…}        guardar algo pequeño desde otro aparato tuyo (≤ 256 KB)
+get <cid>                leerlo de vuelta (≤ 256 KB)
+list · stat <cid> · stats  qué guarda
+pin <cid> · unpin <cid>  retener / soltar
+remove <cid>             borrar
+acl <cid> public|private abrir o cerrar un blob (público es opt-in explícito)
+meta <cid> {…}           nombre/título/descripción para la tarjeta de la vista previa
+thumb <cid> <thumbCid>   enlazar la miniatura (otro blob, público por su cuenta)
+gc                       recolectar vencidos ahora
+```
+
+**`put` y `get` tienen un tope duro de 256 KB, y eso NO es un límite a subir: es la
+frontera.** El plano de control es el proxy del ecosistema —trama de 1 MB, cola de
+mensajes, no un almacén—, así que por aquí pasa lo que **es** un mensaje: un post (un
+eco pesa cientos de bytes) y una miniatura (decenas de KB). Por eso **no hay subida
+por partes**: trocear sería disimular la frontera y acabar usando la infraestructura
+del ecosistema como transporte. Los originales suben en local por HTTP y, entre
+aparatos, por P2P.
+
+## Vistas previas públicas (`--public`, apagado por defecto)
+
+**Para qué es: para que un enlace que compartes tenga TARJETA** en X, LinkedIn,
+WhatsApp o Telegram. No es para servir tu contenido — eso se sigue abriendo en la app,
+con la referencia en el `#fragment`, que nunca llega a ningún servidor. Lo que sale por
+este puerto es la **miniatura** que tú marcaste pública, no el archivo.
+
+```
+GET|HEAD /c/<cid>   los bytes, si pasan TODOS los cerrojos de abajo
+GET      /p/<cid>   permalink: tarjeta (og:*) + botón "Abrir" hacia la app
+GET      /robots.txt · /health
+```
+
+Cinco cerrojos, y ninguno se puede saltar desde fuera:
+
+| | |
+|---|---|
+| **Solo lo público y en claro** | lo cifrado no sale ni marcado público a mano en el índice |
+| **Solo imágenes de mapa de bits** | JPEG, PNG, GIF, WebP, AVIF. **SVG no**: es un documento que ejecuta scripts |
+| **El tipo se comprueba en los bytes** | el `Content-Type` lo declara quien sube, así que no se cree: un HTML subido como `image/png` responde 404 |
+| **Tope de tamaño** (`--public-max-kb`, 512) | es lo que hace que esto sea un servidor de miniaturas y no un CDN. `0` lo quita y entonces sirve originales: el ancho de banda lo pagas tú |
+| **Límite por IP + techo diario** | `--public-rate` (60/min) y `--public-egress-gb`, que se **persiste** y corta antes de mandar una respuesta que no quepa |
+
+Lo privado responde **404, nunca 403**: un 403 confirmaría que ese `cid` está aquí. Y
+`robots.txt` prohíbe todo (las tarjetas funcionan igual: los rastreadores de las redes
+piden la página cuando alguien pega el enlace, no indexan). `--public-index` lo levanta.
+
+**La miniatura la genera tu app al subir** (con un canvas) y se sube como **otro
+blob**, que se enlaza con la op `thumb`. El node no decodifica imágenes: así no
+arrastra dependencias nativas. Enlazar una miniatura **no** la publica — se marca
+pública por su cuenta.
+
+## API HTTP (localhost)
+
+```
+POST   /c?ttl=<ms>&enc=1   subir (streaming; Content-Type = mime) → { cid, size, mime, existed }
+GET    /c/<cid>            descargar/streamear (Range → 206; ETag = cid, immutable)
+HEAD   /c/<cid>            size/mime/etag sin cuerpo
+DELETE /c/<cid>            borrar
+GET    /list               índice de blobs
+POST   /pin/<cid>          retención (excluye del GC)     POST /unpin/<cid>
+GET    /stats              nº de blobs, bytes usados, cuota
+```
+
+- `cid = sha256-<hex>` (prefijo de algoritmo → extensible a BLAKE3 después; se
+  usa SHA-256 de `node:crypto` porque no exige dependencias nativas y el
+  `.npmrc` del ecosistema bloquea build scripts de npm).
+- Disco: `blobs/<aa>/<bb>/<cid>` (sharding); índice en SQLite (`index.db`).
+- Dedup por contenido: re-subir el mismo archivo devuelve `existed: true`.
+- **Cuota** (`--max-gb`): al no caber, el GC desaloja no-pineados más viejos;
+  los **pineados jamás se borran** (si solo quedan pineados → `507`).
+- **TTL** opcional por blob (`?ttl=<ms>`): vencido = candidato a GC.
+- El cifrado E2E es **del lado del cliente** (el node solo ve ciphertext si
+  subes cifrado y marcas `enc=1`); la llave viaja en el `#fragment` del enlace.
+- **`owner` y `acl`:** con el node enlazado, todo lo que se sube queda estampado con
+  el `ownerId` de tu bóveda (la mitad izquierda de la referencia compartible
+  `ownerId + cid`). El `acl` nace privado: lo que no se marca `public` a mano no sale
+  del node cuando llegue el modo público, y un blob cifrado no puede marcarse
+  público (nadie sin la llave podría leerlo).
+
+## `@dotrino/content-client` (lo que usa una app)
+
+El cliente de navegador vive en [`lib/`](./lib) y se publica desde este mismo repo,
+igual que `dotrino-vault` publica su lib. Está aquí a propósito: el protocolo —los
+nombres de las ops, el tope de 256 KB, el formato de la referencia— es de las dos
+puntas, y separarlas en dos repos es la forma de que acaben diciendo cosas distintas.
+
+```js
+import { ContentClient, buildUrl } from '@dotrino/content-client'
+
+const cc = await ContentClient.connect({ link })   // link del vault: { id, cert, iss }
+const ref = await cc.put(bytes, { mime: 'image/png' })   // cifra por defecto
+const url = buildUrl(ref)      // https://eco.dotrino.com/#<owner>/<cid>/<llave>
+const back = await cc.get(ref) // comprueba el hash antes de devolver nada
+```
+
+- **Cifra por defecto** (§4): el node guarda ciphertext y la llave sale en la
+  referencia, para el `#fragment`. Con `encrypt: false` queda en claro, que es lo que
+  hace falta para poder marcarlo `public` y que tenga tarjeta.
+- **`connect()` falla con `code: 'no-node'`** si no tienes ninguno encendido, en vez
+  de esperar. Es lo esperable y **la app tiene que saber seguir sin node**: al
+  `@dotrino/store` va lo que debe estar siempre disponible; aquí van los bytes.
+- **`get()` comprueba el hash** de lo que llega: el `cid` **es** el hash, así que unos
+  bytes que no cuadren se rechazan vengan de donde vengan.
+- **Miniaturas** (`@dotrino/content-client/thumb`): `makeThumbnail()` en canvas y
+  `putImageWithThumbnail()`, que sube el original **cifrado y privado** y la miniatura
+  **en claro y pública** — que es el reparto que hace que haya tarjeta sin publicar el
+  archivo.
+- **Lo PÚBLICO de otro usuario ya se lee por la red** (`fetchPublic` en la lib,
+  DISENO §16): un tercero con tu enlace encuentra tu node por el proxio y le pide el
+  `cid`; el node contesta solo lo marcado público y en claro, y los bytes se
+  verifican contra el `cid`. Lo privado sigue siendo de tus aparatos.
+
+## Tests
+
+```sh
+npm test
+```
+
+## Fases
+
+1. ✅ **Core local**: blobs por `cid`, Range/206, índice, cuota+GC.
+2. ✅ **Aparato del vault** (este estado): enrolamiento, plano de control cifrado,
+   `owner` + `acl`.
+3. Exposición: P2P/swarm por WebRTC + modo público HTTP opt-in + sembrador 24/7.
+4. Integración con **eco** (la app que resuelve el `#fragment`) + catálogo.
+
+Licencia MIT.

package/bin/cli.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * CLI de dotrino-content.
+ *
+ *   dotrino-content enroll <código>     enlaza este node a tu vault (una vez)
+ *   dotrino-content start [--port 3777] [--dir <ruta>] [--max-gb <n>] [--gc-min <min>]
+ *                         [--no-agent]  arranca sin el plano de control
+ *                         [--public]    abre el puerto de VISTAS PREVIAS (§7.2)
+ *
+ * El HTTP de administración sigue escuchando SOLO en loopback: es la vía local
+ * para subir y leer. Lo que añade el enlace es el plano de CONTROL (administrar el
+ * node desde tus apps, por el proxy, sin abrir puertos) — ver DISENO.md §7.
+ *
+ * `--public` levanta un SEGUNDO servidor, aparte y con sus propias reglas
+ * (src/public.js): sirve las **vistas previas** de lo que marcaste público —solo
+ * imágenes comprobadas, con tope de tamaño, límite por IP y techo de salida— para
+ * que un enlace compartido tenga tarjeta en las redes. No es un CDN y no lo va a
+ * ser: el contenido se sigue abriendo en la app.
+ *
+ * Env: DOTRINO_CONTENT_DIR (datos), DOTRINO_CONTENT_LINK_DIR (enlace), PORT.
+ */
+import os from 'node:os'
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+import { ContentNode } from '../src/node.js'
+import { createServer } from '../src/server.js'
+import { createPublicServer, DEFAULT_PUBLIC_PORT, DEFAULT_MAX_BYTES, DEFAULT_RATE_PER_MIN } from '../src/public.js'
+import { isLinked, linkDir, startContentAgent } from '../src/agent.js'
+
+const USAGE = `uso:
+  dotrino-content enroll <código>
+  dotrino-content start [--port 3777] [--dir <ruta>] [--max-gb <n>] [--max-blob-mb <n>] [--gc-min <min>] [--no-agent]
+                        [--public] [--public-port 3778] [--public-host 0.0.0.0] [--public-max-kb 512]
+                        [--public-rate 60] [--public-egress-gb <n>] [--public-url https://…] [--app-url https://…]
+                        [--public-index]`
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    port: { type: 'string' },
+    dir: { type: 'string' },
+    'max-gb': { type: 'string' },
+    'max-blob-mb': { type: 'string' },
+    'gc-min': { type: 'string' },
+    'no-agent': { type: 'boolean' },
+    // --- modo público (§7.2): apagado por defecto, y cada límite es un flag ---
+    public: { type: 'boolean' },
+    'public-port': { type: 'string' },
+    'public-host': { type: 'string' },
+    'public-max-kb': { type: 'string' },
+    'public-rate': { type: 'string' },
+    'public-egress-gb': { type: 'string' },
+    'public-url': { type: 'string' },
+    'app-url': { type: 'string' },
+    'public-index': { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' }
+  }
+})
+
+if (values.help) {
+  console.log(USAGE)
+  process.exit(0)
+}
+
+const cmd = positionals[0] || 'start'
+if (cmd !== 'start' && cmd !== 'enroll') {
+  console.error(`comando desconocido: ${cmd}\n${USAGE}`)
+  process.exit(1)
+}
+
+/**
+ * Enrolamiento: el flujo endurecido del ecosistema, tal cual lo hace la terminal.
+ * Este node genera su llave, MUESTRA un código y espera a que lo apruebes tipeando
+ * ese código en tu bóveda — así aprobar exige tener delante esta máquina. La clave
+ * maestra nunca llega aquí: solo un certificado con fecha de caducidad.
+ */
+if (cmd === 'enroll') {
+  const pairing = positionals[1]
+  if (!pairing) {
+    console.error('falta el código de emparejamiento.\n' +
+      'Sácalo de tu bóveda (dotrino-vault pair, o profile.dotrino.com/#myvault) y pásalo aquí:\n' +
+      '  dotrino-content enroll <código>')
+    process.exit(1)
+  }
+  // Se enrola como SERVICIO (`ns:content`), que es lo que le da además la llave de
+  // CIFRADO a la que el vault le sella sus variables. El enlace del plano de control
+  // queda escrito con la MISMA llave: un aparato, una identidad (ver `vaultEnv.js`).
+  const { enrollToVault, serviceDir, NS } = await import('../src/vaultEnv.js')
+  try {
+    const res = await enrollToVault(pairing, {
+      onReplace: (prev) => {
+        console.log(`\n⚠ este node YA estaba enrolado (aparato ${prev.deviceId}).`)
+        console.log('  Se descarta esa identidad; con ella se va su cajón de variables,')
+        console.log('  que va indexado por su llave. Si solo querías recargar la')
+        console.log('  configuración, NO enroles: reinicia el node.\n')
+      },
+      onCode: ({ deviceId, code }) => {
+        console.log(`\n  este node es el aparato ${deviceId}`)
+        console.log(`  apruébalo en tu bóveda:  dotrino-vault approve ${code}\n`)
+        console.log('  (el código NO viaja por la red: lo tipeas tú)')
+      }
+    })
+    // El papel ya no vence por tiempo: vale mientras el acta lo diga, y se rehace solo
+    // cuando cambias permisos. Decir «válido N días» era describir un reloj que ya no existe.
+    console.log(`\nlisto: node enlazado. El permiso vale mientras lo diga tu bóveda; si se lo quitas, deja de valer en el acto.`)
+    console.log(`identidad en ${serviceDir()}  ·  enlace en ${linkDir()}`)
+    console.log(`\nahora carga su configuración en la bóveda (namespace «${NS}»):`)
+    console.log('  dotrino-vault secret set content CONTENT_STORAGE=local --public')
+  } catch (e) {
+    console.error(`\nno se pudo enlazar: ${e.message}`)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+const dir = values.dir || process.env.DOTRINO_CONTENT_DIR ||
+  path.join(os.homedir(), '.dotrino-content')
+const port = Number(values.port || process.env.PORT || 3777)
+const maxBytes = values['max-gb'] ? Number(values['max-gb']) * 1024 ** 3 : 0
+const maxBlobBytes = values['max-blob-mb'] ? Number(values['max-blob-mb']) * 1024 ** 2 : 0
+const gcMin = Number(values['gc-min'] || 60)
+
+// La configuración la sirve el vault (§15.14). Se pide ANTES de levantar nada: de
+// ahí sale `CONTENT_STORAGE` y, con él, qué almacén usa este node. Sin vault esto no
+// hace nada y el node corre en local, que es el modo normal de un autohospedado.
+const { startVaultConfig, isEnrolled } = await import('../src/vaultEnv.js')
+const log = (m) => console.log(m)
+const vaultConfig = startVaultConfig({ log })
+if (!isEnrolled()) console.log('sin vault: configuración local (enrola con: dotrino-content enroll <código>)')
+// Se ESPERA a la configuración antes de montar el almacén, porque de ella sale cuál es
+// (§15.14). Con plazo: si la bóveda no contesta, se arranca con el disco y ya se
+// reiniciará cuando llegue — un node no puede quedarse sin servir por eso.
+await vaultConfig.ready
+
+const { openStore } = await import('../src/storage.js')
+const { store, cfg } = await openStore({ dir, log })
+
+const node = await new ContentNode({ dir, maxBytes, maxBlobBytes, store, log, publicBase: cfg?.pub ? cfg.baseUrl : null }).init()
+// Lo que quedó sin subir en un arranque anterior. Se lanza y no se espera.
+node.backupPending().then(({ pending }) => { if (pending) log(`[almacén] ${pending} pendiente(s) de subir al bucket`) })
+const server = createServer(node)
+
+// GC periódico de vencidos (ttl); el GC por cuota corre inline en cada put.
+const gcTimer = setInterval(() => node.gc(), gcMin * 60_000)
+gcTimer.unref()
+node.gc()
+
+// Escuchar SOLO en loopback. La exposición al mundo es la Fase 3 (§7.2) y va con su
+// propia ACL, su límite por IP y su techo de salida: no se activa por descuido.
+server.listen(port, '127.0.0.1', () => {
+  const s = node.stats()
+  console.log(`dotrino-content en http://127.0.0.1:${port}  ·  datos: ${dir}`)
+  console.log(`blobs: ${s.blobs}  ·  bytes: ${s.bytes}${maxBytes ? ` / ${maxBytes}` : ''}`)
+})
+
+// Plano de control: solo si este node ya está enlazado a un vault. Sin enlace sigue
+// siendo lo de antes (un node local), y se dice en voz alta para que nadie crea que
+// tiene administración remota cuando no la tiene.
+let agent = null
+if (values['no-agent']) {
+  console.log('plano de control: apagado (--no-agent)')
+} else if (isLinked()) {
+  try {
+    agent = await startContentAgent({ node })
+  } catch (e) {
+    console.error(`plano de control: no arrancó (${e.message})`)
+  }
+} else {
+  console.log('plano de control: sin enlace (corre `dotrino-content enroll <código>` para administrarlo desde tus apps)')
+}
+
+// Modo público (§7.2). Va DESPUÉS del agente a propósito: el `owner` del node lo
+// resuelve el enlace con el vault, y es la mitad izquierda de la referencia
+// `ownerId + cid` que la tarjeta necesita para armar el enlace "Abrir".
+let publicServer = null
+if (values.public) {
+  const maxKb = values['public-max-kb'] !== undefined ? Number(values['public-max-kb']) : DEFAULT_MAX_BYTES / 1024
+  const publicPort = Number(values['public-port'] || DEFAULT_PUBLIC_PORT)
+  const publicHost = values['public-host'] || '0.0.0.0'
+  const egressGb = Number(values['public-egress-gb'] || 0)
+  publicServer = createPublicServer(node, {
+    maxBytes: maxKb * 1024,
+    ratePerMin: Number(values['public-rate'] || DEFAULT_RATE_PER_MIN),
+    maxEgressBytes: egressGb ? egressGb * 1024 ** 3 : 0,
+    publicUrl: values['public-url'] || null,
+    appUrl: values['app-url'] || undefined,
+    index: !!values['public-index'],
+    owner: node.owner
+  })
+  publicServer.listen(publicPort, publicHost, () => {
+    console.log(`vistas previas públicas en http://${publicHost}:${publicPort}  ·  solo imágenes` +
+      `${maxKb ? ` de hasta ${maxKb} KB` : ' (SIN tope de tamaño)'}` +
+      `${egressGb ? `  ·  techo de salida ${egressGb} GB/día` : ''}`)
+    if (!node.owner) {
+      console.log('  ojo: este node no está enlazado a un vault, así que las tarjetas salen sin enlace "Abrir"')
+    }
+    if (!maxKb) {
+      console.log('  ojo: sin tope de tamaño esto sirve originales, no vistas previas — y el ancho de banda lo pagas tú')
+    }
+  })
+}
+
+const shutdown = () => {
+  clearInterval(gcTimer)
+  try { agent?.close() } catch (_) {}
+  try { publicServer?.close() } catch (_) {}
+  server.close(() => { node.close(); process.exit(0) })
+}
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)

package/lib/public.js

@@ -0,0 +1,127 @@
+/**
+ * public.js — leer contenido PÚBLICO de otro dueño por la red de Dotrino.
+ *
+ * Es el camino del tercero (DISENO.md §16): quien recibe una referencia
+ * `ownerId + cid` no tiene sesión con ese node ni la va a tener —las sesiones son de
+ * los aparatos del acta—. Lo que sí puede hacer es lo mismo que con un teléfono:
+ * buscar al dueño en la guía (el canal `content_<owner>` del proxio, §3.1) y
+ * pedirle el `cid` en un mensaje suelto. El node contesta SOLO lo marcado público y
+ * en claro, y el que pide comprueba que los bytes cuadren con el `cid`: el node no
+ * es autoridad de nada, el hash sí.
+ *
+ * Si el node tiene bucket, contesta además la URL pública (§15.13): es un ATAJO
+ * para cargar la imagen con un `<img>` sin mover los bytes por el proxio. Nunca es
+ * el enlace —el enlace sigue siendo `app/#owner/cid`— y si la URL falla, se vuelve
+ * a pedir por la red.
+ *
+ * Isomórfico: el `client` es un `WebSocketProxyClient` ya conectado (el que la app
+ * ya tiene; no se abre otro). Sin dependencias.
+ */
+
+import { isValidCid } from './ref.js'
+
+/** Nombre del canal de un dueño dentro de un proxio (espejo de src/announce.js). */
+export const channelFor = (nodeId, ownerId) => `${nodeId}/content_${ownerId}`
+
+export const MSG = Object.freeze({
+  FETCH: 'content.fetch',
+  FETCH_OK: 'content.fetch.ok',
+  FETCH_ERR: 'content.fetch.err'
+})
+
+/** Lo que cabe en un mensaje del proxio: el mismo tope que el plano de control. */
+export const FETCH_MAX_BYTES = 256 * 1024
+
+const b64ToBytes = (s) => /** @type {Uint8Array<ArrayBuffer>} */ (Uint8Array.from(atob(s), (c) => c.charCodeAt(0)))
+
+async function cidOf (bytes) {
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  return 'sha256-' + [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+const err = (code, msg) => Object.assign(new Error(msg), { code })
+
+/**
+ * Los nodes de un dueño que están en línea ahora mismo, como tokens del proxio.
+ * Se mira en todos los proxios de la malla: un canal sin prefijo es local a cada
+ * uno, y el node se anuncia en todos. Quitarse a uno mismo evita que una app con
+ * node propio se pregunte a sí misma.
+ * @param {{ client: any, owner: string }} opts
+ * @returns {Promise<string[]>}
+ */
+export async function findNodes ({ client, owner }) {
+  if (!client || !owner) throw new Error('findNodes: client and owner are required')
+  const known = Array.isArray(client.knownNodes) && client.knownNodes.length
+    ? client.knownNodes
+    : (client.node ? [client.node] : [])
+  const out = new Set()
+  for (const nodeId of known) {
+    try {
+      for (const token of await client.list(channelFor(nodeId, owner))) out.add(token)
+    } catch (_) { /* un proxio que no contesta no invalida al otro */ }
+  }
+  if (client.token) out.delete(client.token)
+  return [...out]
+}
+
+let rid = 0
+
+/**
+ * Pide un `cid` público a un node concreto (por su token) y espera la respuesta.
+ * @returns {Promise<{ cid: string, mime: string, size: number, url: string|null, bytes: Uint8Array<ArrayBuffer>|null }>}
+ */
+export async function fetchFrom ({ client, token, cid, head = false, full = false, timeoutMs = 8000 }) {
+  const id = `f${++rid}`
+  const reply = new Promise((resolve, reject) => {
+    const done = (fn, v) => { off(); clearTimeout(t); fn(v) }
+    const off = client.on('message', (_from, p) => {
+      if (!p || p.rid !== id) return
+      if (p.type === MSG.FETCH_OK) done(resolve, p)
+      else if (p.type === MSG.FETCH_ERR) done(reject, err(p.code || 'failed', p.error || 'fetch failed'))
+    })
+    const t = setTimeout(() => done(reject, err('timeout', 'the node did not answer')), timeoutMs)
+  })
+  client.send(token, { type: MSG.FETCH, rid: id, cid, head: !!head, full: !!full })
+  const p = await reply
+  let bytes = null
+  if (typeof p.data === 'string') {
+    bytes = b64ToBytes(p.data)
+    // El node no es autoridad: lo que diga que es el cid tiene que SERLO.
+    if (await cidOf(bytes) !== cid) throw err('corrupt', 'the bytes do not match the cid')
+  }
+  return { cid, mime: p.mime || 'application/octet-stream', size: Number(p.size) || (bytes?.length ?? 0), url: p.url || null, bytes }
+}
+
+/**
+ * Resuelve una referencia pública `ownerId + cid` por la red: encuentra un node
+ * vivo del dueño y le pide el blob. Prueba los que haya hasta que uno conteste.
+ *
+ * @param {{ client: any, owner: string, cid: string, head?: boolean, full?: boolean, timeoutMs?: number }} opts
+ *   head: solo metadatos y URL, sin bytes.
+ *   full: los bytes aunque haya URL (por defecto, con URL el node no los manda:
+ *   cargas por la URL y solo vuelves aquí con `full` si te falló).
+ * @throws {Error & {code:'no-node'|'not-found'|'private'|'too-large'|'corrupt'|'timeout'}}
+ */
+export async function fetchPublic ({ client, owner, cid, head = false, full = false, timeoutMs = 8000 }) {
+  if (!isValidCid(cid)) throw err('bad-input', 'invalid cid')
+  const tokens = await findNodes({ client, owner })
+  if (!tokens.length) throw err('no-node', 'no node of that owner is online')
+  // A TODOS a la vez, y se queda con el primero que conteste bien. En serie, cada
+  // token de un node ya apagado —el proxio los conserva un rato— costaba un timeout
+  // entero antes de llegar al que sí está vivo. Un `not-found` es una respuesta de
+  // verdad (otro node del mismo dueño diría lo mismo) y gana sobre los silencios.
+  return new Promise((resolve, reject) => {
+    let pending = tokens.length
+    let answered = null   // el primer error "de verdad" (el node contestó que no)
+    let noise = null      // timeout / corrupt: no dicen nada del contenido
+    for (const token of tokens) {
+      fetchFrom({ client, token, cid, head, full, timeoutMs }).then(resolve, (e) => {
+        if (e.code && e.code !== 'timeout' && e.code !== 'corrupt') answered = answered || e
+        else noise = noise || e
+        if (--pending === 0) reject(answered || noise || err('no-node', 'no node answered'))
+      })
+    }
+  })
+}
+
+export default { channelFor, findNodes, fetchFrom, fetchPublic, MSG, FETCH_MAX_BYTES }

package/lib/ref.js

@@ -0,0 +1,69 @@
+/**
+ * ref.js — la REFERENCIA compartible (DISENO.md §3 y §7). Isomórfico y sin
+ * dependencias: lo usan las apps, el node y las pruebas.
+ *
+ * Una referencia es `ownerId + cid` y, si el contenido va cifrado, la LLAVE:
+ *
+ *     https://eco.dotrino.com/#<ownerId>/<cid>/<llave>
+ *                             └──────── el #fragment ────────┘
+ *
+ * Las dos mitades hacen falta y ninguna sobra:
+ *  - el **`cid`** es el hash del contenido: lo vuelve inmutable, deduplicable y
+ *    **verificable** (quien lo recibe comprueba que los bytes son los pedidos);
+ *  - el **`ownerId`** es la huella de la maestra del dueño, y es lo que permite
+ *    **rutear** (`ownerId` → sus nodes) y comprobar que quien sirvió los bytes es
+ *    un aparato suyo. Un `cid` suelto es ambiguo: cualquiera podría reclamarlo.
+ *
+ * **La llave va en el fragmento y por eso NUNCA llega a un servidor**: el
+ * navegador no manda el `#` en la petición. Es lo mismo que hace el resto del
+ * ecosistema, y es lo que permite compartir un enlace de contenido cifrado sin
+ * que quien lo hospeda pueda leerlo.
+ */
+
+const CID_RE = /^sha256-[0-9a-f]{64}$/
+
+/** ¿Tiene forma de cid? (no dice si existe, solo si es un cid) */
+export const isValidCid = (cid) => typeof cid === 'string' && CID_RE.test(cid)
+
+/**
+ * Arma la parte de fragmento de una referencia (sin el `#`).
+ * @param {{ owner: string, cid: string, key?: string|null }} ref
+ * @returns {string} `<owner>/<cid>` o `<owner>/<cid>/<llave>`
+ */
+export function buildRef ({ owner, cid, key = null }) {
+  if (!owner) throw new Error('buildRef: owner is required')
+  if (!isValidCid(cid)) throw new Error(`buildRef: invalid cid: ${cid}`)
+  return key ? `${owner}/${cid}/${key}` : `${owner}/${cid}`
+}
+
+/**
+ * Arma el enlace completo hacia una app del ecosistema.
+ * @param {{ owner: string, cid: string, key?: string|null }} ref
+ * @param {string} [appUrl]
+ */
+export function buildUrl (ref, appUrl = 'https://eco.dotrino.com/') {
+  return `${appUrl.replace(/\/+$/, '')}/#${buildRef(ref)}`
+}
+
+/**
+ * Lee una referencia de un fragmento, una URL o la barra de direcciones.
+ * Devuelve `null` si eso no es una referencia — que es lo normal: las apps del
+ * ecosistema usan el fragmento para muchas cosas (`#room=`, `#vault`…), así que
+ * esto tiene que poder decir "no es mío" sin ruido.
+ * @param {string} input
+ * @returns {{ owner: string, cid: string, key: string|null }|null}
+ */
+export function parseRef (input) {
+  if (typeof input !== 'string' || !input) return null
+  let frag = input
+  const hash = frag.indexOf('#')
+  if (hash >= 0) frag = frag.slice(hash + 1)
+  frag = frag.replace(/^\/+/, '')
+  const parts = frag.split('/')
+  if (parts.length < 2 || parts.length > 3) return null
+  const [owner, cid, key = null] = parts
+  if (!owner || !isValidCid(cid)) return null
+  return { owner, cid, key: key || null }
+}
+
+export default { buildRef, buildUrl, parseRef, isValidCid }

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@dotrino/content",
+  "version": "0.3.13",
+  "description": "Nodo de contenido del ecosistema Dotrino: guarda los bytes del usuario direccionados por su hash (cid), en su propia maquina y, si el dueno quiere, respaldados en su propio bucket (R2, Backblaze, Hetzner, Storj o S3). Lo publico sale por URL directa; lo privado, cifrado y solo por la red Dotrino.",
+  "type": "module",
+  "bin": {
+    "dotrino-content": "bin/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js start",
+    "test": "node --test 'test/**/*.test.js'",
+    "type-check": "tsc --noEmit && tsc --noEmit -p lib"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@dotrino/identity": "0.78.0",
+    "@dotrino/remote-agent": "0.9.2",
+    "@dotrino/vault": "0.52.0"
+  },
+  "keywords": [
+    "dotrino",
+    "content-addressed",
+    "cid",
+    "self-hosted",
+    "privacy",
+    "s3",
+    "r2",
+    "blob-storage"
+  ],
+  "homepage": "https://github.com/imdotrino/dotrino-content#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imdotrino/dotrino-content.git"
+  },
+  "bugs": {
+    "url": "https://github.com/imdotrino/dotrino-content/issues"
+  },
+  "author": "Dotrino",
+  "files": [
+    "bin",
+    "src",
+    "lib/public.js",
+    "lib/ref.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}