dotrino-content 0.2.0

package/README.md

@@ -0,0 +1,173 @@
+# 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
+
+```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.
+- **Todavía NO lee el contenido de otro usuario**: hoy solo se abre sesión con un
+  aparato de tu misma acta. Un tercero con tu enlace ve la vista previa (si la
+  encendiste) y podrá pedir los bytes cuando exista el transporte P2P.
+
+## 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,203 @@
+#!/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' }
+  }
+})
+
+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ú)')
+      }
+    })
+    const days = Math.round((res.cert.exp - Date.now()) / 86400000)
+    console.log(`\nlisto: node enlazado. Certificado válido ${days} días (se renueva solo).`)
+    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 } = await openStore({ dir, log })
+
+const node = await new ContentNode({ dir, maxBytes, maxBlobBytes, store, log }).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/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "dotrino-content",
+  "version": "0.2.0",
+  "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.55.0",
+    "@dotrino/remote-agent": "0.4.1",
+    "@dotrino/vault": "0.27.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",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.js

@@ -0,0 +1,104 @@
+/**
+ * agent.js — Fase 2 (DISENO.md §5, §11): este node deja de ser una pieza local y
+ * pasa a ser un APARATO DEL VAULT, administrable a distancia desde tus propias apps
+ * sin abrir un solo puerto.
+ *
+ * NO IMPLEMENTA NADA DE ESO: lo hace `@dotrino/remote-agent`, el middleware que ya
+ * usan `dotrino-terminal` y `dotrino-ia`. De ahí salen, y por eso no se reescriben
+ * aquí: el enrolamiento contra el vault (llave `D` propia + cert `D ← maestra`, la
+ * maestra nunca vive aquí), el `identify` firmado en el proxy, el canal cifrado por
+ * sesión, el refresco de la lista de revocados, la RENOVACIÓN del cert antes de que
+ * venza y el auto-borrado cuando llega un `vault.revoked` firmado por la maestra.
+ *
+ * Lo único de este archivo es el pegamento: cada payload que llega por una sesión
+ * ya autorizada se despacha en `ops.js`, y la respuesta vuelve por el mismo canal
+ * cifrado. Autorizar = tener un cert de LA MISMA maestra que este node (eso lo
+ * comprueba `verifyChain` dentro del middleware); no hay lista de invitados propia.
+ *
+ * El `owner` del node se deriva de la maestra a la que está enlazado: es el
+ * `ownerId` de la referencia compartible `ownerId + cid` (§3), y se estampa en todo
+ * lo que se suba mientras el node esté enlazado.
+ */
+import { pubkeyId } from '@dotrino/identity/capabilities'
+import { startRemoteAgent } from '@dotrino/remote-agent/agent'
+import { dataDir, loadLink } from '@dotrino/remote-agent/link'
+import { startAnnounce } from './announce.js'
+import { createOps } from './ops.js'
+
+/** Carpeta de datos del enlace (NO es la de los blobs: el enlace es del aparato). */
+export const linkDir = () => process.env.DOTRINO_CONTENT_LINK_DIR || dataDir('dotrino-content')
+
+/** ¿Está este node enlazado a un vault? (sin enlace, Fase 1: solo loopback) */
+export const isLinked = (dir = linkDir()) => {
+  const link = loadLink(dir)
+  return !!(link?.device?.privateJwk && link?.cert && link?.iss)
+}
+
+/**
+ * Arranca el plano de control del node.
+ *
+ * @param {{
+ *   node?: import('./node.js').ContentNode,
+ *   dir?: string, proxyUrl?: string, version?: string|null,
+ *   client?: any, quiet?: boolean, onRevoked?: () => void, announce?: boolean
+ * }} opts
+ *   client: transporte inyectado — SOLO para pruebas (bus en memoria). En
+ *   producción lo levanta el middleware con el proxy del ecosistema.
+ *   announce: publicarse en el canal del dueño para que un TERCERO con el enlace
+ *   pueda encontrar este node (§3.1). Encendido por defecto; se apaga con `false`
+ *   en un node que solo quieras usar desde tus propios aparatos.
+ * @returns {Promise<{ machine: string, machineId: string, owner: string, close: () => void }>}
+ */
+export async function startContentAgent ({
+  node, dir = linkDir(), proxyUrl, version = null, client, quiet = false, onRevoked, announce = true
+} = {}) {
+  if (!node) throw new Error('startContentAgent: falta node')
+  const link = loadLink(dir)
+  if (!link?.iss) {
+    throw new Error('este node no está enlazado a un vault. Ejecuta primero: dotrino-content enroll <código>')
+  }
+
+  // El node representa a la maestra que lo certificó: su huella es el `ownerId`.
+  // Se resuelve ANTES de abrir el transporte, para que la primera sesión que entre
+  // ya encuentre el despachador armado.
+  const owner = await pubkeyId(link.iss)
+  node.owner = owner
+  const dispatch = createOps(node, { owner, version })
+
+  const agent = await startRemoteAgent({
+    dir,
+    proxyUrl,
+    client,
+    quiet,
+    onRevoked,
+    onSession: (session) => {
+      session.on('message', (msg) => {
+        dispatch(msg)
+          .then((reply) => session.send(reply))
+          .catch((e) => session.send({ rid: msg?.rid, ok: false, code: 'failed', error: e.message }))
+      })
+    }
+  })
+
+  if (!quiet) console.log(`[content] control plane ready · owner ${owner.slice(0, 16)}`)
+
+  // ANUNCIO (§3.1): sin esto el node es administrable por sus dueños pero
+  // INVISIBLE para quien recibe un enlace — la referencia nombra al dueño, y hay
+  // que poder pasar de ahí a «qué nodes suyos están vivos». Reusa la conexión del
+  // middleware: nunca se abre una segunda.
+  const beacon = announce && agent.client
+    ? startAnnounce({ client: agent.client, owner, quiet })
+    : null
+
+  return {
+    ...agent,
+    owner,
+    channels: () => beacon?.channels() || [],
+    close () {
+      try { beacon?.close() } catch (_) {}
+      agent.close()
+    }
+  }
+}
+
+export default { startContentAgent, isLinked, linkDir }

package/src/announce.js

@@ -0,0 +1,132 @@
+/**
+ * announce.js — ANUNCIO del node (DISENO.md §3.1). Es lo que hace que se sepa
+ * **dónde** está el contenido de un dueño.
+ *
+ * La referencia compartible nombra al DUEÑO, no a la máquina (`ownerId + cid`), así
+ * que resolverla es contestar «¿qué nodes de este dueño están vivos ahora mismo?».
+ * Hay dos caminos, según quién pregunte, y este archivo es el segundo:
+ *
+ *  - **El dueño** pregunta a su bóveda (`listAgentsByLabel(id, 'content')`): sus
+ *    aparatos y sus direcciones. No necesita ningún anuncio.
+ *  - **Un tercero con el enlace** no puede consultar la bóveda de nadie — ni debe.
+ *    Para él, el node se publica en un **canal del proxy** y cualquiera lista quién
+ *    está dentro. Eso es esto.
+ *
+ * **El nombre del canal lleva el `ownerId`, no el `cid`.** Un canal por contenido
+ * filtraría qué guarda cada quien con solo mirar la lista de canales; y además
+ * serían miles. Con uno por dueño, lo que se sabe al listar es «este dueño tiene
+ * nodes en línea», que es justo lo que hace falta para pedirle algo.
+ *
+ * **Por qué el canal va con id de proxio delante.** Hay dos proxios federados y un
+ * canal SIN prefijo es local a cada uno: el node anunciado en uno sería invisible
+ * para quien esté conectado al otro. Se publica en el canal de **cada nodo
+ * conocido** y se lista en todos, en vez de elegir uno "dueño" por una fórmula: la
+ * lista de nodos de la malla cambia cuando entra o sale un proxio, y una fórmula
+ * que dependa de ella reasigna todos los canales el día que eso pase. Son dos
+ * canales hoy; publicar en los dos cuesta dos mensajes y no se rompe nunca.
+ *
+ * **Anunciarse NO da acceso a nada.** Es una guía de teléfonos: dice a quién
+ * llamar. Quién puede pedir qué lo siguen decidiendo la ACL y el certificado, en
+ * el sitio de siempre.
+ */
+
+/** Nombre del canal de un dueño dentro de un proxio concreto. */
+export const channelFor = (nodeId, ownerId) => `${nodeId}/content_${ownerId}`
+
+/** Cada cuánto se re-publica (el proxio caduca las entradas de canal). */
+export const REPUBLISH_MS = 4 * 60 * 1000
+
+/**
+ * Publica este node en el canal de su dueño, en todos los proxios conocidos, y lo
+ * mantiene publicado. Best-effort a propósito: si el proxy está caído, el node
+ * sigue funcionando —sirve en local y atiende a los aparatos del acta— y el
+ * siguiente tic lo vuelve a intentar. Un anuncio perdido no rompe nada; lo único
+ * que pasa es que un tercero no lo encuentra hasta que vuelva.
+ *
+ * @param {{ client: any, owner: string, quiet?: boolean, intervalMs?: number }} opts
+ *   client: el `WebSocketProxyClient` YA conectado del agente (`ra.client`) — no se
+ *   abre otro: dos conexiones del mismo aparato son dos identidades de transporte.
+ * @returns {{ channels: () => string[], close: () => void }}
+ */
+export function startAnnounce ({ client, owner, quiet = false, intervalMs = REPUBLISH_MS }) {
+  if (!client) throw new Error('startAnnounce: falta client')
+  if (!owner) throw new Error('startAnnounce: falta owner')
+
+  let stopped = false
+  let current = []
+
+  /** Los proxios donde hay que anunciarse: el que nos atiende y los que conoce. */
+  const targets = () => {
+    const known = Array.isArray(client.knownNodes) ? client.knownNodes : []
+    return known.length ? known : (client.node ? [client.node] : [])
+  }
+
+  async function publishAll () {
+    if (stopped) return
+    const names = targets().map((n) => channelFor(n, owner))
+    if (!names.length) return          // aún sin `connected`: el próximo tic
+    const done = []
+    for (const name of names) {
+      try {
+        await client.publish(name, { app: 'content', owner })
+        done.push(name)
+      } catch (e) {
+        if (!quiet) console.error(`[content] no me pude anunciar en ${name}: ${e.message}`)
+      }
+    }
+    const first = !current.length && done.length
+    current = done
+    if (first && !quiet) console.log(`[content] anunciado como node de ${owner.slice(0, 16)} en ${done.length} proxio(s)`)
+  }
+
+  publishAll()
+  // Re-publicar al reconectar: el token cambia y el anuncio viejo apunta a una
+  // conexión que ya no existe. Sin esto, un corte de red deja al node listado y
+  // mudo, que es peor que no estar listado.
+  const offToken = client.on('token', () => { current = []; publishAll() })
+  const timer = setInterval(publishAll, intervalMs)
+  timer.unref?.()
+
+  return {
+    channels: () => [...current],
+    close () {
+      stopped = true
+      clearInterval(timer)
+      try { offToken?.() } catch (_) {}
+      for (const name of current) { try { client.unpublish(name) } catch (_) {} }
+      current = []
+    }
+  }
+}
+
+/**
+ * Lado del que BUSCA: los tokens de los nodes de un dueño que están en línea, en
+ * todos los proxios conocidos, sin repetidos.
+ *
+ * Lo que devuelve son **candidatos, no autoridades**: cualquiera puede publicarse
+ * en el canal de cualquier dueño (el nombre del canal no es un secreto). Quien
+ * pregunte tiene que comprobar las dos cosas de siempre — que el node presenta un
+ * certificado que encadena a ese `ownerId`, y que los bytes que entrega hashean al
+ * `cid` pedido. Con esas dos, un impostor en la lista no consigue nada más que
+ * gastar un intento.
+ *
+ * @param {{ client: any, owner: string }} opts
+ * @returns {Promise<string[]>} tokens (direcciones en el proxy)
+ */
+export async function findNodes ({ client, owner }) {
+  if (!client || !owner) throw new Error('findNodes: faltan client u owner')
+  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 */ }
+  }
+  // El propio que pregunta puede estar en la lista (una PWA que también es node).
+  if (client.token) out.delete(client.token)
+  return [...out]
+}
+
+export default { startAnnounce, findNodes, channelFor, REPUBLISH_MS }