@dotrino/content 0.3.13

package/src/db.js

@@ -0,0 +1,237 @@
+/**
+ * Índice de metadatos (Fase 1, DISENO.md §3): SQLite embebido de Node
+ * (`node:sqlite`, sin dependencias). Los bytes viven en el BlobStore;
+ * aquí solo `cid, size, mime, createdAt, owner, enc, acl, ttl, pinned…`.
+ */
+import { DatabaseSync } from 'node:sqlite'
+import path from 'node:path'
+
+export class Index {
+  /** @param {string} root directorio raíz de datos */
+  constructor (root) {
+    this.db = new DatabaseSync(path.join(root, 'index.db'))
+    this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE IF NOT EXISTS blobs (
+        cid          TEXT PRIMARY KEY,
+        size         INTEGER NOT NULL,
+        mime         TEXT NOT NULL DEFAULT 'application/octet-stream',
+        createdAt    INTEGER NOT NULL,
+        owner        TEXT,
+        enc          INTEGER NOT NULL DEFAULT 0,
+        acl          TEXT,
+        ttl          INTEGER,            -- epoch ms de expiración (NULL = no expira)
+        pinned       INTEGER NOT NULL DEFAULT 0,
+        thumbnailCid TEXT,
+        meta         TEXT               -- JSON de presentación: { name, title, description }
+      );
+      CREATE TABLE IF NOT EXISTS egress (
+        day   TEXT PRIMARY KEY,         -- YYYY-MM-DD (UTC)
+        bytes INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE INDEX IF NOT EXISTS idx_blobs_ttl ON blobs (ttl) WHERE ttl IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_blobs_gc  ON blobs (pinned, createdAt);
+      CREATE INDEX IF NOT EXISTS idx_blobs_acl ON blobs (acl, createdAt);
+    `)
+    // Migración de un índice creado antes de que existiera `meta`: añadir la
+    // columna a una base ya escrita en disco. `ADD COLUMN` con default NULL es
+    // barato y no reescribe la tabla; si ya está, SQLite tira y se ignora.
+    try { this.db.exec('ALTER TABLE blobs ADD COLUMN meta TEXT') } catch (_) { /* ya existía */ }
+
+    // Columnas de la CACHÉ (DISENO.md §15.11). Existen aunque no haya bucket: sin
+    // él, `remote` se queda en 0 y `cached` en 1 para siempre, y nada cambia.
+    //
+    //  · `remote`   — el bucket YA CONFIRMÓ estos bytes. Se pone a 1 con la
+    //                 confirmación, nunca al lanzar la subida: es el cerrojo que
+    //                 impide desalojar algo cuya única copia sigue siendo esta.
+    //  · `cached`   — los bytes están en el disco de esta máquina. Al desalojar se
+    //                 pone a 0 y la FILA SE QUEDA: si se fuera con los bytes, el
+    //                 blob quedaría en el bucket sin dueño, sin ACL y sin tipo.
+    //  · `lastRead` — para desalojar por último acceso y no por antigüedad. Un
+    //                 almacén ordena por edad; una caché, por uso.
+    for (const col of [
+      'remote INTEGER NOT NULL DEFAULT 0',
+      'cached INTEGER NOT NULL DEFAULT 1',
+      'lastRead INTEGER'
+    ]) {
+      try { this.db.exec(`ALTER TABLE blobs ADD COLUMN ${col}`) } catch (_) { /* ya existía */ }
+    }
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_blobs_evict ON blobs (pinned, cached, remote, lastRead)')
+  }
+
+  upsert ({ cid, size, mime, owner = null, enc = 0, acl = null, ttl = null, meta = null }) {
+    this.db.prepare(`
+      INSERT INTO blobs (cid, size, mime, createdAt, owner, enc, acl, ttl, meta)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (cid) DO UPDATE SET
+        mime = excluded.mime,
+        ttl  = excluded.ttl,
+        -- Volver a subir los mismos bytes NO borra la presentación que ya tenían.
+        meta = COALESCE(excluded.meta, blobs.meta)
+    `).run(cid, size, mime, Date.now(), owner, enc ? 1 : 0, acl, ttl, meta ? JSON.stringify(meta) : null)
+  }
+
+  get (cid) {
+    return this.db.prepare('SELECT * FROM blobs WHERE cid = ?').get(cid) ?? null
+  }
+
+  list () {
+    return this.db.prepare(
+      'SELECT cid, size, mime, createdAt, owner, enc, acl, ttl, pinned, meta FROM blobs ORDER BY createdAt DESC'
+    ).all()
+  }
+
+  /**
+   * Cambia el `acl` de un blob (`public` | `private`). Devuelve false si no existe.
+   * Se cambia aparte del `upsert` a propósito: volver a subir los mismos bytes NO
+   * debe reabrir ni cerrar un blob por accidente.
+   */
+  setAcl (cid, acl) {
+    const { changes } = this.db.prepare('UPDATE blobs SET acl = ? WHERE cid = ?').run(acl, cid)
+    return changes > 0
+  }
+
+  remove (cid) {
+    this.db.prepare('DELETE FROM blobs WHERE cid = ?').run(cid)
+  }
+
+  setPinned (cid, pinned) {
+    const { changes } = this.db.prepare('UPDATE blobs SET pinned = ? WHERE cid = ?')
+      .run(pinned ? 1 : 0, cid)
+    return changes > 0
+  }
+
+  /** Suma de bytes indexados. @returns {number} */
+  totalBytes () {
+    return Number(this.db.prepare('SELECT COALESCE(SUM(size), 0) AS n FROM blobs').get().n)
+  }
+
+  /** @returns {number} */
+  count () {
+    return Number(this.db.prepare('SELECT COUNT(*) AS n FROM blobs').get().n)
+  }
+
+  /**
+   * Blobs con ttl vencido (candidatos a GC incondicional, aunque estén sin pin).
+   * @returns {{ cid: string, size: number }[]}
+   */
+  expired (now = Date.now()) {
+    return /** @type {{ cid: string, size: number }[]} */ (this.db.prepare(
+      'SELECT cid, size FROM blobs WHERE ttl IS NOT NULL AND ttl <= ? AND pinned = 0'
+    ).all(now))
+  }
+
+  /**
+   * Candidatos a liberar espacio por cuota: no pineados, con bytes en disco, y
+   * **el menos usado primero** (DISENO.md §15.11). `COALESCE(lastRead, createdAt)`
+   * porque lo que nunca se ha leído cuenta por su fecha de subida.
+   *
+   * @param {{ requireRemote?: boolean }} [opts] `requireRemote` lo pone el backend
+   *   con bucket: entonces solo se desaloja lo que el bucket YA confirmó, porque
+   *   desalojar es tirar una copia caliente y sin la otra copia sería destruir.
+   * @returns {{ cid: string, size: number }[]}
+   */
+  evictable ({ requireRemote = false } = {}) {
+    return /** @type {{ cid: string, size: number }[]} */ (this.db.prepare(`
+      SELECT cid, size FROM blobs
+      WHERE pinned = 0 AND cached = 1 ${requireRemote ? 'AND remote = 1' : ''}
+      ORDER BY COALESCE(lastRead, createdAt) ASC
+    `).all())
+  }
+
+  /** Marca que estos bytes ya están confirmados en el bucket. */
+  setRemote (cid, remote = true) {
+    const { changes } = this.db.prepare('UPDATE blobs SET remote = ? WHERE cid = ?')
+      .run(remote ? 1 : 0, cid)
+    return changes > 0
+  }
+
+  /** Marca si los bytes están (o ya no) en el disco de esta máquina. */
+  setCached (cid, cached = true) {
+    const { changes } = this.db.prepare('UPDATE blobs SET cached = ? WHERE cid = ?')
+      .run(cached ? 1 : 0, cid)
+    return changes > 0
+  }
+
+  /** Anota que este blob se acaba de leer (es lo que ordena el desalojo). */
+  touch (cid, now = Date.now()) {
+    this.db.prepare('UPDATE blobs SET lastRead = ? WHERE cid = ?').run(now, cid)
+  }
+
+  /**
+   * Lo que aún NO está confirmado en el bucket: la cola de subida pendiente. Que
+   * esto sea una consulta y no una lista en memoria es a propósito — un reinicio
+   * a media subida no debe perder el pendiente.
+   */
+  pendingUpload (limit = 100) {
+    return /** @type {{ cid: string, size: number }[]} */ (this.db.prepare(
+      'SELECT cid, size FROM blobs WHERE remote = 0 AND cached = 1 ORDER BY createdAt ASC LIMIT ?'
+    ).all(limit))
+  }
+
+  /** Bytes que ocupan disco AQUÍ (la cuota es de la caché, no del inventario). */
+  cachedBytes () {
+    return Number(this.db.prepare('SELECT COALESCE(SUM(size), 0) AS n FROM blobs WHERE cached = 1').get().n)
+  }
+
+  /**
+   * Metadatos de PRESENTACIÓN de un blob (nombre, título, descripción): lo único
+   * que la vista previa pública (§7.3) tiene para armar la tarjeta. Se guarda
+   * aparte de los bytes porque no forma parte del `cid` — dos nombres distintos
+   * para el mismo archivo son el mismo blob.
+   * @param {string} cid
+   * @param {{name?:string,title?:string,description?:string}|null} meta
+   */
+  setMeta (cid, meta) {
+    const { changes } = this.db.prepare('UPDATE blobs SET meta = ? WHERE cid = ?')
+      .run(meta ? JSON.stringify(meta) : null, cid)
+    return changes > 0
+  }
+
+  /**
+   * Enlaza la MINIATURA de un blob (otro blob, con su propio `cid`). El node no
+   * genera miniaturas: las hace la app al subir —el aparato pone el trabajo, que
+   * es el patrón del ecosistema— y aquí solo se anota cuál es.
+   */
+  setThumbnail (cid, thumbnailCid) {
+    const { changes } = this.db.prepare('UPDATE blobs SET thumbnailCid = ? WHERE cid = ?')
+      .run(thumbnailCid, cid)
+    return changes > 0
+  }
+
+  /**
+   * Blobs servibles al mundo: `acl = public` y EN CLARO. Un blob cifrado no sale
+   * por aquí ni marcado público (ops.js ya lo impide al marcarlo, esto es el
+   * segundo cerrojo, en el sitio donde los bytes de verdad salen).
+   */
+  listPublic ({ limit = 100, offset = 0 } = {}) {
+    return this.db.prepare(`
+      SELECT cid, size, mime, createdAt, meta FROM blobs
+      WHERE acl = 'public' AND enc = 0
+      ORDER BY createdAt DESC LIMIT ? OFFSET ?
+    `).all(limit, offset)
+  }
+
+  /**
+   * Contabilidad de EGRESS del modo público (§7.2), por día UTC y persistida: un
+   * techo que se reinicia con el proceso no es un techo — el reinicio es
+   * exactamente lo que pasa cuando algo se descontrola.
+   * @param {number} bytes @param {string} day YYYY-MM-DD
+   */
+  addEgress (bytes, day) {
+    if (!(bytes > 0)) return
+    this.db.prepare(`
+      INSERT INTO egress (day, bytes) VALUES (?, ?)
+      ON CONFLICT (day) DO UPDATE SET bytes = bytes + excluded.bytes
+    `).run(day, Math.round(bytes))
+  }
+
+  /** Bytes servidos ese día. @returns {number} */
+  egressOn (day) {
+    return Number(this.db.prepare('SELECT COALESCE(bytes, 0) AS n FROM egress WHERE day = ?').get(day)?.n || 0)
+  }
+
+  close () {
+    this.db.close()
+  }
+}

package/src/fetch.js

@@ -0,0 +1,89 @@
+/**
+ * fetch.js — el node ATIENDE a terceros (DISENO.md §16).
+ *
+ * Un aparato del acta entra por sesión cifrada (`ops.js`). Cualquier otro —quien
+ * recibió un enlace— no tiene sesión ni la tendrá: manda un mensaje suelto por el
+ * proxio, `content.fetch { cid }`, y recibe el blob si y solo si está marcado
+ * `public` y en claro. Es la misma regla que el modo HTTP (§7.2): sin `public`
+ * explícito, no sale nada, y un 'not-found' nunca distingue «no existe» de «no es
+ * público» para no confirmar qué guarda el node.
+ *
+ * Lo que va en la respuesta:
+ *  - `url`: el atajo del bucket (§15.13) si el node lo tiene y el bucket ya confirmó
+ *    esos bytes. La app la usa para un `<img>`; si falla, vuelve a pedir por aquí.
+ *  - `data`: los bytes en base64, salvo `head` o si no caben en un mensaje. Lo que no
+ *    cabe se sirve solo por URL; sin bucket, 'too-large' — lo grande es P2P (§13).
+ *
+ * Límite por remitente (token) para que un enlace viral no convierta el node en un
+ * CDN por el proxio: el proxio ya tiene el suyo, y este es el del node.
+ */
+
+import { isValidCid } from '../lib/ref.js'
+import { MSG, FETCH_MAX_BYTES } from '../lib/public.js'
+
+export { MSG, FETCH_MAX_BYTES }
+
+/**
+ * @param {{ client: any, node: import('./node.js').ContentNode, ratePerMin?: number, quiet?: boolean }} opts
+ *   client: el `WebSocketProxyClient` YA conectado del agente (no se abre otro).
+ * @returns {{ close: () => void, served: () => number }}
+ */
+export function startPublicFetch ({ client, node, ratePerMin = 60, quiet = false }) {
+  if (!client || !node) throw new Error('startPublicFetch: client and node are required')
+  /** token → { n, windowStart } */
+  const buckets = new Map()
+  let served = 0
+
+  const allowed = (from) => {
+    const now = Date.now()
+    const b = buckets.get(from) || { n: 0, windowStart: now }
+    if (now - b.windowStart >= 60_000) { b.n = 0; b.windowStart = now }
+    b.n++
+    buckets.set(from, b)
+    if (buckets.size > 5000) buckets.clear()   // que la tabla no crezca sin techo
+    return b.n <= ratePerMin
+  }
+
+  const send = (to, obj) => { try { client.send(to, obj) } catch (e) { if (!quiet) console.error('[content] fetch reply:', e.message) } }
+  const fail = (to, rid, code, error) => send(to, { type: MSG.FETCH_ERR, rid, code, error })
+
+  const handle = async (from, p) => {
+    const rid = typeof p.rid === 'string' ? p.rid : null
+    if (!rid) return
+    if (!quiet) console.log(`[content] fetch ${String(p.cid).slice(0, 20)}… from ${String(from).slice(0, 16)}${p.head ? ' (head)' : ''}`)
+    if (!allowed(from)) return fail(from, rid, 'rate-limited', 'too many requests')
+    if (!isValidCid(p.cid)) return fail(from, rid, 'bad-input', 'invalid cid')
+    const meta = node.stat(p.cid)
+    // Mismo 'not-found' para «no existe» y «no es público»: el mismo motivo que §7.2.
+    if (!meta || meta.acl !== 'public' || meta.enc) return fail(from, rid, 'not-found', 'no such public cid')
+    const url = node.publicUrl(p.cid)
+    const out = { type: MSG.FETCH_OK, rid, cid: p.cid, mime: meta.mime, size: meta.size, url }
+    // Con atajo, los bytes NO viajan por el proxio salvo que el que pide insista
+    // (`full`): cargar por URL es gratis para el node y para la red, y la app ya
+    // sabe volver aquí si la URL le falla. Sin atajo, van en el mensaje si caben.
+    if (!p.head && (!url || p.full)) {
+      if (meta.size > FETCH_MAX_BYTES) {
+        if (!url) return fail(from, rid, 'too-large', `${meta.size} bytes do not fit in a message and this node has no public bucket`)
+        // Cabe solo por URL: se contesta sin bytes y la app carga por ahí.
+      } else {
+        const chunks = []
+        for await (const c of node.read(p.cid)) chunks.push(c)
+        out.data = Buffer.concat(chunks).toString('base64')
+      }
+    }
+    served++
+    send(from, out)
+  }
+
+  const off = client.on('message', (from, p) => {
+    if (!p || p.type !== MSG.FETCH) return
+    handle(from, p).catch((e) => fail(from, p.rid, 'failed', e.message))
+  })
+
+  return {
+    served: () => served,
+    close () { try { off?.() } catch (_) {} }
+  }
+}
+
+export default { startPublicFetch, MSG, FETCH_MAX_BYTES }

package/src/index.js

@@ -0,0 +1,3 @@
+export { ContentNode, isValidCid } from './node.js'
+export { BlobStore } from './blobstore.js'
+export { createServer, parseRange } from './server.js'

package/src/node.js

@@ -0,0 +1,262 @@
+/**
+ * ContentNode = BlobStore (bytes) + Index (metadatos) + cuota/GC (Fase 1).
+ *
+ * Sigue sin saber de red: quien la pone es `agent.js` (Fase 2), que además le dice
+ * qué `owner` representa —la huella de la maestra del vault, la mitad izquierda de
+ * la referencia compartible `ownerId + cid` (DISENO.md §3)— y usa el `acl` para
+ * decidir qué puede salir del node cuando llegue el modo público (§7.2).
+ */
+import { mkdir } from 'node:fs/promises'
+import { BlobStore, isValidCid } from './blobstore.js'
+import { Index } from './db.js'
+
+export { isValidCid }
+
+export class ContentNode {
+  /**
+   * @param {{ dir: string, maxBytes?: number, maxBlobBytes?: number, owner?: string|null,
+   *           store?: any, log?: (m:string)=>void }} opts
+   *   dir: raíz de datos · maxBytes: cuota total de disco (0 = sin límite)
+   *   maxBlobBytes: tamaño máximo por blob (0 = sin límite)
+   *   owner: `ownerId` de la maestra (lo pone el agente al enlazar; null sin vault)
+   *   store: almacén ya montado (`storage.js`); por defecto, disco
+   */
+  constructor (opts) {
+    if (!opts?.dir) throw new Error('opts.dir is required')
+    this.dir = opts.dir
+    this.maxBytes = opts.maxBytes || 0
+    this.maxBlobBytes = opts.maxBlobBytes || 0
+    this.owner = opts.owner || null
+    // El almacén se puede INYECTAR (`storage.js` monta el de bucket cuando toca). Por
+    // defecto, disco: sin configuración, un node funciona con lo que hay en la máquina.
+    this.store = opts.store || new BlobStore(opts.dir)
+    // Base de la URL pública del bucket (§15.13). Sin bucket público es null y lo
+    // público viaja por la red, que es el camino que SIEMPRE existe.
+    this.publicBase = opts.publicBase || null
+    this.index = null
+    /** Subidas al bucket en curso, por cid: para no lanzar dos veces la misma. */
+    this._uploading = new Map()
+    this.log = opts.log || (() => {})
+  }
+
+  async init () {
+    await mkdir(this.dir, { recursive: true })
+    await this.store.init()
+    this.index = new Index(this.dir)
+    return this
+  }
+
+  /**
+   * Sube un stream. Si la cuota no alcanza, intenta GC de no-pineados; si aun
+   * así no cabe, rechaza con code ENOSPC (no borra pineados jamás).
+   */
+  async put (readable, { mime = 'application/octet-stream', enc = 0, ttl = null, acl = null, meta = null } = {}) {
+    const { cid, size, existed } = await this.store.put(readable, {
+      maxBytes: this.maxBlobBytes || undefined
+    })
+    if (this.maxBytes && !existed) {
+      // La cuota es del DISCO, así que cuenta lo que está cacheado aquí, no el
+      // inventario: con bucket detrás, lo desalojado sigue existiendo (§15.11)
+      // pero ya no ocupa nada — contarlo dejaría la cuota excedida para siempre.
+      const over = (this.index.cachedBytes() + size) - this.maxBytes
+      if (over > 0 && this.gc({ needBytes: over }).freed < over) {
+        await this.store.remove(cid)
+        throw Object.assign(new Error('disk quota exceeded'), { code: 'ENOSPC' })
+      }
+    }
+    this.index.upsert({ cid, size, mime, owner: this.owner, enc, acl, ttl, meta })
+    // Con bucket detrás, la subida va DESPUÉS de responder: quien sube no espera a la
+    // red. Hasta que el bucket confirme, este blob no es desalojable (§15.11).
+    if (!existed) this.backup(cid, { size, mime, public: acl === 'public' })
+    return { cid, size, mime, existed }
+  }
+
+  /** Metadatos de un blob (o null). */
+  stat (cid) {
+    return isValidCid(cid) ? this.index.get(cid) : null
+  }
+
+  /**
+   * La URL pública de un blob, o null. Es un ATAJO (§15.13), nunca el enlace: solo
+   * existe si hay bucket público, el blob está marcado público y en claro, y el
+   * bucket YA confirmó esos bytes (`remote`) — una URL que todavía da 404 no ayuda.
+   */
+  publicUrl (cid) {
+    if (!this.publicBase || !this.store.backed || typeof this.store.urlFor !== 'function') return null
+    const m = this.stat(cid)
+    if (!m || m.acl !== 'public' || m.enc || !m.remote) return null
+    return this.store.urlFor(cid, this.publicBase)
+  }
+
+  /**
+   * Marca un blob como público o privado (`acl`). Es lo único que autoriza a que
+   * los bytes salgan del node cuando esté encendido el modo público (DISENO.md
+   * §7.2); sin `public` explícito, no sale.
+   */
+  setAcl (cid, acl) {
+    const ok = this.index.setAcl(cid, acl)
+    // Publicar mueve los bytes al bucket público, que es OTRO bucket (§15.1). Sin esto
+    // el blob quedaría marcado público y sin estar donde se sirve lo público.
+    if (ok && acl === 'public' && this.store.backed) {
+      const m = this.index.get(cid)
+      if (m && !m.enc) this.backup(cid, { size: m.size, mime: m.mime, public: true })
+    }
+    return ok
+  }
+
+  /**
+   * Sube un blob a su bucket y lo marca `remote` **solo cuando el bucket confirma**.
+   * Marcar al lanzar la subida es exactamente el error que deja perder contenido: un
+   * GC oportuno se llevaría la única copia que existe.
+   *
+   * No espera nadie a esto (se lanza y se olvida), pero un fallo se REPORTA: lo que no
+   * subió sigue siendo la cola pendiente del índice, y se reintenta al arrancar.
+   */
+  backup (cid, meta) {
+    if (!this.store.backed) return null
+    // Si ya hay una subida en curso (la privada, típicamente), esta va DETRÁS, no se
+    // descarta: publicar a mitad de la subida tiene que terminar en el bucket público.
+    const prev = this._uploading.get(cid)
+    const p = (prev ? prev.catch(() => {}) : Promise.resolve())
+      .then(() => this.store.upload(cid, meta))
+      .then(() => { this.index.setRemote(cid, true) })
+      .catch((e) => { this.log(`[storage] could not upload ${cid.slice(0, 14)}…: ${e.message}`) })
+      .finally(() => this._uploading.delete(cid))
+    this._uploading.set(cid, p)
+    return p
+  }
+
+  /**
+   * Reintenta lo que quedó sin subir. Se llama al arrancar: un reinicio a media subida
+   * no debe perder el pendiente, y por eso la cola es una consulta al índice y no una
+   * lista en memoria.
+   */
+  async backupPending (limit = 100) {
+    if (!this.store.backed) return { pending: 0 }
+    const rows = this.index.pendingUpload(limit)
+    for (const r of rows) {
+      const m = this.index.get(r.cid)
+      if (m) await this.backup(r.cid, { size: m.size, mime: m.mime, public: m.acl === 'public' })
+    }
+    return { pending: rows.length }
+  }
+
+  /**
+   * Metadatos de presentación (nombre/título/descripción). Es lo único con lo que
+   * el permalink público arma su tarjeta (DISENO.md §7.3): sin esto una vista
+   * previa solo puede decir el tipo y el tamaño.
+   */
+  setMeta (cid, meta) {
+    return this.index.setMeta(cid, meta)
+  }
+
+  /** Enlaza la miniatura pública de un blob (la genera la app, no el node). */
+  setThumbnail (cid, thumbnailCid) {
+    return this.index.setThumbnail(cid, thumbnailCid)
+  }
+
+  /** Índice de lo servible al mundo (público y en claro). */
+  listPublic (opts) {
+    return this.index.listPublic(opts)
+  }
+
+  /**
+   * ¿Puede este blob salir del node por el HTTP público? Dos condiciones, y las
+   * dos se comprueban aquí —en el único sitio por donde salen los bytes— aunque
+   * `ops.acl` ya impida marcar público lo cifrado: un índice traído de otra
+   * versión, o tocado a mano, no debe poder abrir una puerta.
+   * @returns {any|null} los metadatos si es servible, null si no.
+   */
+  publicStat (cid) {
+    const meta = this.stat(cid)
+    if (!meta || meta.acl !== 'public' || meta.enc) return null
+    return meta
+  }
+
+  /**
+   * ReadStream del blob; range = { start, end } inclusivo.
+   *
+   * Anota el acceso (`lastRead`), que es lo que ordena el desalojo de la caché
+   * (§15.11): sin esto, el GC tira lo más antiguo, y lo antiguo y muy pedido es
+   * justo lo que hay que conservar.
+   */
+  read (cid, range) {
+    this.index.touch(cid)
+    return this.store.read(cid, range)
+  }
+
+  async remove (cid) {
+    await this.store.remove(cid)
+    this.index.remove(cid)
+  }
+
+  list () {
+    return this.index.list()
+  }
+
+  pin (cid, pinned = true) {
+    return this.index.setPinned(cid, pinned)
+  }
+
+  stats () {
+    const cached = this.index.cachedBytes()
+    return {
+      blobs: this.index.count(),
+      // `bytes` es lo que ocupa el disco (lo que mira la cuota); `totalBytes` es
+      // el inventario entero, que con bucket es mayor porque incluye lo desalojado.
+      bytes: cached,
+      totalBytes: this.index.totalBytes(),
+      maxBytes: this.maxBytes || null,
+      backed: this.store.backed === true,
+      dir: this.dir
+    }
+  }
+
+  /**
+   * GC: borra vencidos (ttl) siempre; si `needBytes`, además desaloja
+   * no-pineados más viejos hasta liberar esa cantidad.
+   * Síncrono sobre el índice; el borrado de disco es fire-and-forget seguro
+   * (los bytes huérfanos se re-borran en el próximo GC vía índice… el índice
+   * es la fuente de verdad de qué existe).
+   */
+  /**
+   * Libera espacio. Hace DOS cosas distintas y conviene no confundirlas (§15.11):
+   *
+   *  · **Caducar** (`ttl` vencido) es borrar de verdad: se va la fila, los bytes
+   *    locales y —si hay bucket— también los de allí. Es lo que se pidió al subir.
+   *  · **Desalojar** por cuota es tirar una copia caliente. Con bucket detrás solo
+   *    toca lo que el bucket YA confirmó (`remote = 1`) y **la fila se queda** con
+   *    `cached = 0`: si se fuera, el blob quedaría en el bucket sin ACL, sin dueño
+   *    y sin tipo. Sin bucket no hay segunda copia, así que desalojar ES destruir
+   *    y se comporta como hasta ahora.
+   */
+  gc ({ needBytes = 0, now = Date.now() } = {}) {
+    let freed = 0
+    const backed = this.store.backed === true
+
+    const destroy = ({ cid, size }) => {
+      this.index.remove(cid)
+      this.store.remove(cid).catch(() => {})
+      freed += size
+    }
+    const evict = ({ cid, size }) => {
+      if (!backed) return destroy({ cid, size })
+      this.store.evict(cid).catch(() => {})
+      this.index.setCached(cid, false)
+      freed += size
+    }
+
+    for (const b of this.index.expired(now)) destroy(b)
+    if (needBytes > freed) {
+      for (const b of this.index.evictable({ requireRemote: backed })) {
+        if (freed >= needBytes) break
+        evict(b)
+      }
+    }
+    return { freed }
+  }
+
+  close () {
+    this.index?.close()
+  }
+}