dotrino-content 0.2.0

package/src/server.js

@@ -0,0 +1,142 @@
+/**
+ * API HTTP local (Fase 1, DISENO.md §6). SOLO localhost: sin auth todavía
+ * (la auth por vault llega en Fase 2; la exposición al mundo en Fase 3).
+ *
+ *   POST   /c            subir (streaming; Content-Type = mime; ?ttl=<ms>)
+ *   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
+ *   POST   /pin/<cid>    retención (evita GC)     POST /unpin/<cid>
+ *   POST   /public/<cid>  publicar (al bucket público si lo hay)  POST /private/<cid>
+ *   GET    /stats        uso de disco, nº blobs
+ */
+import http from 'node:http'
+import { pipeline } from 'node:stream/promises'
+import { isValidCid } from './node.js'
+
+/** Parsea `Range: bytes=a-b|a-|-n` contra `size`. null = sin rango; false = inválido. */
+export function parseRange (header, size) {
+  if (!header) return null
+  const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim())
+  if (!m || (m[1] === '' && m[2] === '')) return false
+  let start, end
+  if (m[1] === '') { // sufijo: últimos n bytes
+    const n = Number(m[2])
+    if (n === 0) return false
+    start = Math.max(0, size - n)
+    end = size - 1
+  } else {
+    start = Number(m[1])
+    end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1)
+  }
+  if (start >= size || start > end) return false
+  return { start, end }
+}
+
+const json = (res, code, obj) => {
+  const body = JSON.stringify(obj)
+  res.writeHead(code, { 'content-type': 'application/json' }).end(body)
+}
+
+/**
+ * @param {import('./node.js').ContentNode} node
+ * @returns {http.Server}
+ */
+export function createServer (node) {
+  return http.createServer(async (req, res) => {
+    try {
+      await route(node, req, res)
+    } catch (err) {
+      if (res.headersSent) { res.destroy(); return }
+      if (err.code === 'ETOOBIG') return json(res, 413, { error: 'blob demasiado grande' })
+      if (err.code === 'ENOSPC') return json(res, 507, { error: 'cuota de disco excedida' })
+      json(res, 500, { error: err.message })
+    }
+  })
+}
+
+async function route (node, req, res) {
+  const url = new URL(req.url, 'http://localhost')
+  const [, top, cid] = url.pathname.split('/')
+
+  if (req.method === 'POST' && top === 'c' && !cid) {
+    const ttlMs = Number(url.searchParams.get('ttl')) || 0
+    const out = await node.put(req, {
+      mime: req.headers['content-type'] || 'application/octet-stream',
+      enc: url.searchParams.get('enc') === '1' ? 1 : 0,
+      ttl: ttlMs > 0 ? Date.now() + ttlMs : null
+    })
+    return json(res, out.existed ? 200 : 201, out)
+  }
+
+  if (top === 'c' && cid) {
+    if (!isValidCid(cid)) return json(res, 400, { error: 'cid inválido' })
+    const meta = node.stat(cid)
+    if (!meta) return json(res, 404, { error: 'no existe' })
+
+    if (req.method === 'DELETE') {
+      await node.remove(cid)
+      return json(res, 200, { ok: true })
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      return json(res, 405, { error: 'método no permitido' })
+    }
+
+    const headers = {
+      'content-type': meta.mime,
+      etag: `"${cid}"`,
+      'cache-control': 'public, max-age=31536000, immutable',
+      'accept-ranges': 'bytes'
+    }
+    if (req.headers['if-none-match'] === `"${cid}"`) {
+      res.writeHead(304, headers).end()
+      return
+    }
+    const range = parseRange(req.headers.range, meta.size)
+    if (range === false) {
+      res.writeHead(416, { 'content-range': `bytes */${meta.size}` }).end()
+      return
+    }
+    if (range) {
+      headers['content-range'] = `bytes ${range.start}-${range.end}/${meta.size}`
+      headers['content-length'] = range.end - range.start + 1
+      res.writeHead(206, headers)
+    } else {
+      headers['content-length'] = meta.size
+      res.writeHead(200, headers)
+    }
+    if (req.method === 'HEAD') return res.end()
+    await pipeline(node.read(cid, range ?? undefined), res)
+    return
+  }
+
+  if (req.method === 'GET' && top === 'list') return json(res, 200, node.list())
+  if (req.method === 'GET' && top === 'stats') return json(res, 200, node.stats())
+
+  if (req.method === 'POST' && (top === 'pin' || top === 'unpin') && cid) {
+    if (!isValidCid(cid)) return json(res, 400, { error: 'cid inválido' })
+    const ok = node.pin(cid, top === 'pin')
+    return ok ? json(res, 200, { ok: true }) : json(res, 404, { error: 'no existe' })
+  }
+
+  // PUBLICAR / despublicar. Existía solo por el plano de control, y eso dejaba sin poder
+  // publicar a las herramientas de la propia máquina —que es donde vive el dueño—, y sin
+  // poder probar el camino público sin montar medio ecosistema.
+  //
+  // Con bucket detrás, marcar público MUEVE los bytes al bucket público, que es otro
+  // (§15.1): por eso pasa por `node.setAcl` y no por el índice a secas.
+  if (req.method === 'POST' && (top === 'public' || top === 'private') && cid) {
+    if (!isValidCid(cid)) return json(res, 400, { error: 'cid inválido' })
+    const meta = node.stat(cid)
+    if (!meta) return json(res, 404, { error: 'no existe' })
+    // Un blob CIFRADO no puede ser público, y se rechaza aquí además de en el índice:
+    // es la misma frontera del §7.2, y una frontera que solo se comprueba en un sitio
+    // acaba teniendo un camino que no pasa por ese sitio.
+    if (top === 'public' && meta.enc) return json(res, 400, { error: 'un blob cifrado no puede ser público' })
+    const ok = node.setAcl(cid, top === 'public' ? 'public' : null)
+    return ok ? json(res, 200, { ok: true, acl: top === 'public' ? 'public' : null }) : json(res, 404, { error: 'no existe' })
+  }
+
+  json(res, 404, { error: 'ruta desconocida' })
+}

package/src/storage.js

@@ -0,0 +1,175 @@
+/**
+ * Qué almacén usa este node, y las comprobaciones antes de fiarse de él
+ * (DISENO.md §15.14 y §15.15).
+ *
+ * Una variable pública manda —`CONTENT_STORAGE`— y las demás solo tienen sentido si
+ * nombra un proveedor. El valor nombra a QUIÉN está detrás (`r2`, `b2`, `hetzner`,
+ * `storj`, `s3`), no al protocolo: todos hablan S3 y usan el mismo backend, pero
+ * saberlo permite poner sus valores por omisión y, sobre todo, que quien mire la
+ * consola entienda lo que lee.
+ *
+ * **Nunca arranca a medias.** Si falta algo o una comprobación falla, se queda en
+ * `local` y lo DICE. Un almacén mal configurado que parece funcionar es la peor de las
+ * tres opciones: se descubre el día que hace falta lo que se creía guardado.
+ */
+import { createHash } from 'node:crypto'
+import { BlobStore } from './blobstore.js'
+import { S3BlobStore } from './blobstore-s3.js'
+import { S3Bucket } from './s3.js'
+
+/** Proveedores que hablan S3. Solo cambian el endpoint y algún valor por omisión. */
+export const PROVIDERS = Object.freeze({
+  r2: { region: 'auto' },
+  b2: { region: 'us-west-004' },
+  hetzner: { region: 'eu-central' },
+  storj: { region: 'us-east-1' },
+  s3: { region: 'us-east-1' }
+})
+
+/** La sonda del camino público: nueve bytes que se suben y se leen por el dominio. */
+const PROBE = 'dotrino!'
+
+/** Lo que hace falta para hablar con un bucket, más lo que hace falta para el público. */
+const REQUIRED = ['CONTENT_S3_ENDPOINT', 'CONTENT_S3_BUCKET_PRIVATE', 'CONTENT_S3_KEY_ID', 'CONTENT_S3_SECRET']
+const REQUIRED_PUBLIC = ['CONTENT_S3_PUBLIC_KEY_ID', 'CONTENT_S3_PUBLIC_SECRET', 'CONTENT_PUBLIC_BASE_URL']
+
+/**
+ * Lee la configuración del entorno (que la sirve el vault, §15.14).
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {{ kind: string, provider: string|null, missing: string[], region: string,
+ *             endpoint: string, priv: string, pub: string|null, baseUrl: string|null,
+ *             keyId: string, secret: string, pubKeyId: string, pubSecret: string }}
+ */
+export function storageConfig (env = process.env) {
+  const kind = (env.CONTENT_STORAGE || 'local').trim().toLowerCase()
+  if (kind === 'local') return { kind: 'local', provider: null, missing: [] , region: '', endpoint: '', priv: '', pub: null, baseUrl: null, keyId: '', secret: '', pubKeyId: '', pubSecret: '' }
+
+  const provider = PROVIDERS[kind] ? kind : null
+  const missing = REQUIRED.filter((k) => !env[k])
+
+  // El bucket público es OPCIONAL a propósito: un node puede tener bucket solo para lo
+  // privado (durabilidad) y seguir sirviendo lo público por la red (§15.3). Pero si lo
+  // declara a medias, eso sí es un error — no se publica «casi».
+  const wantsPublic = !!env.CONTENT_S3_BUCKET_PUBLIC
+  if (wantsPublic) missing.push(...REQUIRED_PUBLIC.filter((k) => !env[k]))
+
+  return {
+    kind,
+    provider,
+    missing,
+    region: env.CONTENT_S3_REGION || PROVIDERS[kind]?.region || 'us-east-1',
+    endpoint: env.CONTENT_S3_ENDPOINT || '',
+    priv: env.CONTENT_S3_BUCKET_PRIVATE || '',
+    pub: wantsPublic ? env.CONTENT_S3_BUCKET_PUBLIC : null,
+    baseUrl: env.CONTENT_PUBLIC_BASE_URL || null,
+    keyId: env.CONTENT_S3_KEY_ID || '',
+    secret: env.CONTENT_S3_SECRET || '',
+    pubKeyId: env.CONTENT_S3_PUBLIC_KEY_ID || '',
+    pubSecret: env.CONTENT_S3_PUBLIC_SECRET || ''
+  }
+}
+
+/**
+ * Las tres comprobaciones del §15.15, las que se rompen SIN DAR ERROR.
+ *
+ * @param {ReturnType<typeof storageConfig>} cfg
+ * @param {{ priv: S3Bucket, pub: S3Bucket|null }} buckets
+ * @param {typeof fetch} [f]
+ * @returns {Promise<{ ok: boolean, fatal: string[], warn: string[] }>}
+ */
+export async function checkBuckets (cfg, { priv, pub }, f = fetch) {
+  const fatal = []
+  const warn = []
+
+  // 1. El mismo bucket para las dos cosas: lo privado acabaría en el que tiene dominio.
+  if (cfg.pub && cfg.pub === cfg.priv) {
+    fatal.push('el bucket privado y el público son el mismo: lo cifrado acabaría en el que tiene dominio')
+  }
+
+  // 2. El privado NO puede responder sin credenciales. Se pide un objeto que no existe:
+  //    un bucket cerrado contesta 400/401/403 (falta la firma o no autoriza), y uno
+  //    ABIERTO contesta 404 (no está) — que es lo que delata que cualquiera puede leer
+  //    los que sí están.
+  //
+  //    LO QUE ESTO NO VE, y hay que decirlo: si alguien conecta un DOMINIO al bucket
+  //    privado, este sondeo no se entera — pregunta al endpoint de S3, que sigue
+  //    exigiendo firma aunque el bucket tenga dominio público. Contra eso no hay API:
+  //    es responsabilidad de quien crea los buckets (§15.15).
+  try {
+    const r = await f(priv.urlFor('sha256-' + '0'.repeat(64)), { method: 'GET' })
+    if (r.status === 404 || r.ok) {
+      fatal.push(`el bucket privado «${cfg.priv}» responde sin credenciales (HTTP ${r.status}): está abierto al mundo`)
+    }
+  } catch (e) {
+    warn.push(`no se pudo comprobar si el bucket privado está cerrado: ${e.message}`)
+  }
+
+  // 3. El dominio del público tiene que servir DE VERDAD, y eso no se deduce mirando
+  //    una respuesta de error: se comprueba subiendo algo y leyéndolo por el dominio.
+  //
+  //    Se intentó antes por las malas —«si el 404 viene en HTML, el dominio no es el
+  //    bucket»— y se cayó sola: GitHub Pages contesta un 404 en HTML, pero R2 TAMBIÉN
+  //    contesta el suyo en HTML. Dos cosas indistinguibles por su página de error.
+  //
+  //    La sonda es un objeto de nueve bytes, siempre el mismo (su nombre es su hash, así
+  //    que subirla dos veces no ensucia nada) y su presencia documenta que el enlace
+  //    funciona. Cuesta dos peticiones al arrancar.
+  if (pub && cfg.baseUrl) {
+    try {
+      const bytes = Buffer.from(PROBE)
+      const cid = 'sha256-' + createHash('sha256').update(bytes).digest('hex')
+      await pub.put(cid, bytes, { sha256: cid.slice(7), size: bytes.length, contentType: 'text/plain' })
+      const r = await f(`${cfg.baseUrl.replace(/\/+$/, '')}/${cid}`, { method: 'GET' })
+      const cuerpo = r.ok ? (await r.text()).trim() : ''
+      if (cuerpo !== PROBE) {
+        warn.push(`${cfg.baseUrl} no sirve lo que hay en «${cfg.pub}» (HTTP ${r.status}): revisa que el dominio esté conectado AL BUCKET desde el panel`)
+      }
+    } catch (e) {
+      warn.push(`no se pudo comprobar el camino público: ${e.message}`)
+    }
+  }
+
+  return { ok: fatal.length === 0, fatal, warn }
+}
+
+/**
+ * Monta el almacén que toca. Devuelve SIEMPRE algo utilizable: si el bucket no está o
+ * no pasa las comprobaciones, devuelve el de disco y explica por qué.
+ *
+ * @param {{ dir: string, env?: any, log?: (m:string)=>void, check?: boolean, fetch?: typeof fetch }} o
+ */
+export async function openStore ({ dir, env = process.env, log = () => {}, check = true, fetch: f = fetch }) {
+  const cfg = storageConfig(env)
+  if (cfg.kind === 'local') return { store: await new BlobStore(dir).init(), cfg }
+
+  if (!cfg.provider) {
+    log(`[almacén] CONTENT_STORAGE=«${cfg.kind}» no es un proveedor conocido (${Object.keys(PROVIDERS).join(', ')}); sigo en local`)
+    return { store: await new BlobStore(dir).init(), cfg }
+  }
+  if (cfg.missing.length) {
+    log(`[almacén] ${cfg.kind} pedido pero faltan variables: ${cfg.missing.join(', ')}`)
+    log('[almacén] sigo en LOCAL: un almacén a medio configurar es peor que ninguno')
+    return { store: await new BlobStore(dir).init(), cfg }
+  }
+
+  const common = { endpoint: cfg.endpoint, region: cfg.region, fetch: f }
+  const priv = new S3Bucket({ ...common, bucket: cfg.priv, accessKeyId: cfg.keyId, secretAccessKey: cfg.secret })
+  const pub = cfg.pub
+    ? new S3Bucket({ ...common, bucket: cfg.pub, accessKeyId: cfg.pubKeyId, secretAccessKey: cfg.pubSecret })
+    : null
+
+  if (check) {
+    const { ok, fatal, warn } = await checkBuckets(cfg, { priv, pub }, f)
+    for (const w of warn) log(`[almacén] ⚠ ${w}`)
+    if (!ok) {
+      for (const e of fatal) log(`[almacén] ✖ ${e}`)
+      log('[almacén] sigo en LOCAL hasta que eso se arregle')
+      return { store: await new BlobStore(dir).init(), cfg }
+    }
+  }
+
+  log(`[almacén] ${cfg.kind}: privado «${cfg.priv}»${cfg.pub ? `, público «${cfg.pub}» en ${cfg.baseUrl}` : ' (sin bucket público: lo público viaja por la red)'}`)
+  return { store: await new S3BlobStore({ root: dir, priv, pub, log }).init(), cfg }
+}
+
+export default { storageConfig, checkBuckets, openStore, PROVIDERS }

package/src/vaultEnv.js

@@ -0,0 +1,144 @@
+/**
+ * La CONFIGURACIÓN del node, servida por el vault (DISENO.md §15.14).
+ *
+ * Este node es un servicio del ecosistema como cualquier otro: no lleva su
+ * configuración en un `.env`, se la cede la bóveda del dueño **sellada para su llave**
+ * (`ns:content`). De ahí salen `CONTENT_STORAGE` y, si vale `s3`, el endpoint, los
+ * buckets y las credenciales.
+ *
+ * **No se reimplementa nada de eso**: lo resuelve `@dotrino/vault/service`, que es lo
+ * que usan los proxios. Aquí solo está el pegamento y una decisión propia — qué hacer
+ * cuando llega un cambio (abajo).
+ *
+ * Ojo con el enrolamiento, que tiene dos partes y hacen falta las dos:
+ *
+ *  · **La llave de FIRMA** (`device`) — dice quién es este aparato.
+ *  · **La llave de CIFRADO** (`enc`) — es a la que el vault le SELLA cada variable.
+ *    Sin ella el aparato aparece en el acta pero se queda sin configuración, y no da
+ *    error: simplemente no le llega nada. Por eso se enrola por este camino y no por
+ *    el de `@dotrino/remote-agent`, que todavía no la crea.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { linkDir } from './agent.js'
+
+/** El namespace de secretos de esta pieza. Es el mismo que el `pair --service`. */
+export const NS = 'content'
+
+/** Dónde vive la identidad de servicio (llave + cert). Junto al enlace del aparato. */
+export const serviceDir = () =>
+  process.env.DOTRINO_CONTENT_VAULT_DIR || path.join(linkDir(), 'vault-service')
+
+/** ¿Está este node enrolado a un vault? */
+export const isEnrolled = (dir = serviceDir()) =>
+  fs.existsSync(path.join(dir, 'service-identity.json'))
+
+/**
+ * Enrola este node contra el vault del dueño con la invitación de
+ * `dotrino-vault pair --service content`.
+ *
+ * Deja además el enlace que espera el plano de control (`@dotrino/remote-agent`), con
+ * LA MISMA llave: un aparato, una identidad. Si se enrolara dos veces —una por cada
+ * plano— el acta tendría dos filas para la misma máquina y revocar una dejaría viva a
+ * la otra, que es exactamente lo que el modelo de revocación quiere evitar.
+ *
+ * @param {string} qr la invitación (URL, código pegado o JSON)
+ * @param {{ dir?: string, onCode?: (c:{deviceId:string,code:string})=>void,
+ *           onReplace?: (p:any)=>void, label?: string }} [opts]
+ */
+export async function enrollToVault (qr, { dir = serviceDir(), onCode, onReplace, label } = {}) {
+  const { enrollService } = await import('@dotrino/vault/service')
+  const res = await enrollService({ qr, ns: NS, dir, label: label || 'content', onCode, onReplace })
+
+  // El plano de control usa la misma identidad. `saveLink` es de remote-agent, y su
+  // formato es el que lee `startRemoteAgent` al arrancar.
+  const { saveLink } = await import('@dotrino/remote-agent/link')
+  saveLink(linkDir(), {
+    device: res.device,
+    cert: res.cert,
+    iss: res.iss,
+    proxy: res.cert?.proxy || 'wss://proxy.dotrino.com',
+    label: label || 'content',
+    at: Date.now()
+  })
+  return res
+}
+
+/**
+ * Espera la configuración del vault y la vuelca en `process.env`.
+ *
+ * **Qué hace cuando cambia una variable: reiniciar.** Es lo mismo que decidió el
+ * proxio, y por la misma razón: una variable se rota casi siempre PORQUE SE FILTRÓ, y
+ * mientras el proceso siga vivo el valor viejo sigue en su memoria y sigue siendo el
+ * que usa. Aquí además es literal — el backend del almacén se construye al arrancar
+ * con las credenciales de entonces.
+ *
+ * Si el node no está enrolado no hace nada y se calla: sin vault corre en local, que
+ * es el modo normal de quien se lo autohospeda (§15.12).
+ *
+ * @param {{ dir?: string, onSecrets?: (s:any)=>void, log?: (m:string)=>void,
+ *           onChange?: () => void, firstWaitMs?: number }} [opts]
+ */
+export function startVaultConfig ({ dir = serviceDir(), onSecrets, log = console.log, onChange, firstWaitMs = 20000 } = {}) {
+  if (!isEnrolled(dir)) return { enabled: false, ready: Promise.resolve(null), close () {} }
+  let stopped = false
+  let watcher = null
+  /** @type {(v:any)=>void} */
+  let llegaron = () => {}
+  const ready = new Promise((resolve) => { llegaron = resolve })
+
+  // La configuración decide QUÉ ALMACÉN usa este node, así que quien arranca la espera…
+  // pero con plazo. Si la bóveda está apagada, seguir esperando sería dejar al usuario
+  // sin su propio contenido local por una pieza que el ecosistema promete no exigir
+  // (`CLAUDE.md`: ninguna app puede requerir un daemon encendido). Al vencer el plazo se
+  // sigue en local, y cuando la configuración llegue, `watchEnv` reinicia con ella.
+  const plazo = setTimeout(() => {
+    log(`[vault] la bóveda no contestó en ${Math.round(firstWaitMs / 1000)}s: arranco con lo local y sigo esperando`)
+    llegaron(null)
+  }, firstWaitMs)
+  plazo.unref?.()
+
+  ;(async () => {
+    const { waitForSecrets } = await import('@dotrino/vault/service')
+    const { applyEnv, watchEnv } = await import('@dotrino/vault/env')
+    const secrets = await waitForSecrets({
+      dir,
+      ns: NS,
+      onRetry: (e, delay) => log(`[vault] sin configuración todavía (${e.message}); reintento en ${Math.round(delay / 1000)}s`)
+    })
+    if (stopped) return
+
+    const { injected, overridden } = applyEnv(secrets)
+    log(`[vault] ${injected.length} valor(es) del vault aplicados al entorno`)
+    if (overridden.length) log(`[vault] pisaron el entorno de esta máquina: ${overridden.join(', ')}`)
+    clearTimeout(plazo)
+    llegaron(secrets)
+    onSecrets?.(secrets)
+
+    // Sin `onUpdate`, `watchEnv` sale del proceso él mismo (con el código que
+    // corresponda: 0 si cambió la configuración, 1 si revocaron a este agente, para
+    // que un supervisor que lo relance no gire en silencio). Es lo que queremos, así
+    // que solo se le pasa `onUpdate` si la app quiere hacer otra cosa.
+    watcher = await watchEnv({
+      dir,
+      ns: NS,
+      ...(onChange
+        ? {
+            onUpdate: ({ reason }) => {
+              log(`[vault] ${reason === 'revoked' ? 'este aparato fue revocado' : 'llegó configuración nueva'}`)
+              onChange()
+            }
+          }
+        : {})
+    })
+  })().catch((e) => { log(`[vault] no se pudo leer la configuración: ${e.message}`); clearTimeout(plazo); llegaron(null) })
+
+  return {
+    enabled: true,
+    /** Resuelve con la configuración, o con `null` si venció el plazo o falló. */
+    ready,
+    close () { stopped = true; clearTimeout(plazo); try { watcher?.close?.() } catch (_) {} }
+  }
+}
+
+export default { NS, serviceDir, isEnrolled, enrollToVault, startVaultConfig }