@cero-base/core 0.8.9 → 1.0.1

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@cero-base/core",
-  "version": "0.8.9",
+  "version": "1.0.1",
   "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lekinox/cero-base.git",
+    "directory": "packages/core"
+  },
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "files": [
@@ -39,6 +48,12 @@
       "types": "./types/blobs/index.d.ts",
       "default": "./src/blobs/index.js"
     },
+    "./blobs/codec": {
+      "default": "./src/blobs/codec.js"
+    },
+    "./blobs/server": {
+      "default": "./src/blobs/server.js"
+    },
     "./rpc": {
       "types": "./types/rpc/index.d.ts",
       "default": "./src/rpc/index.js"
@@ -106,22 +121,23 @@
     "test": "brittle-node test/*.test.js"
   },
   "dependencies": {
-    "autobee": "^1.0.7",
+    "autobee": "^1.0.9",
     "b4a": "^1.8.1",
-    "bare-crypto": "^1.14.1",
+    "bare-crypto": "^1.15.3",
     "bare-fs": "^4.7.2",
     "bare-path": "^3.0.1",
     "bip39-mnemonic": "^2.5.0",
     "blind-pairing": "^2.3.1",
-    "compact-encoding": "^3.1.0",
-    "corestore": "^7.10.0",
+    "compact-encoding": "^3.2.0",
+    "corestore": "^7.10.1",
     "framed-stream": "^1.0.1",
     "hrpc": "^4.3.0",
-    "hyperblobs": "^2.12.0",
+    "hyperblobs": "^2.12.1",
+    "hypercore-blob-server": "^1.12.0",
     "hypercore": "^11.33.1",
     "hypercore-crypto": "^3.7.0",
     "hypercore-id-encoding": "^1.3.0",
-    "hypercore-storage": "^3.0.2",
+    "hypercore-storage": "^3.1.1",
     "hyperdb": "^6.7.0",
     "hyperdispatch": "^1.6.0",
     "hyperschema": "^1.21.0",
@@ -131,12 +147,12 @@
     "ready-resource": "^1.2.0",
     "safety-catch": "^1.0.3",
     "sodium-universal": "^5.0.1",
-    "streamx": "^2.26.0",
+    "streamx": "^2.28.0",
     "z32": "^1.1.0"
   },
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
-    "brittle": "^4.0.0",
+    "brittle": "^4.0.2",
     "typescript": "^5.9.3"
   },
   "license": "Apache-2.0"

package/src/blobs/codec.js

@@ -0,0 +1,52 @@
+import c from 'compact-encoding'
+import z32 from 'z32'
+
+import { getEncoding } from '../lib/spec/index.js'
+import { CeroError } from '../lib/errors.js'
+
+/**
+ * @typedef {object} RawBlobId
+ * @property {number} blockOffset
+ * @property {number} blockLength
+ * @property {number} byteOffset
+ * @property {number} byteLength
+ */
+
+const BlobId = getEncoding('@cero/blob-id')
+
+/**
+ * Encode a coreKey + raw hyperblobs blobId + type into a durable string id.
+ *
+ * @param {Uint8Array} coreKey
+ * @param {RawBlobId} blobId
+ * @param {string} type
+ * @returns {string}
+ */
+export function encodeId(coreKey, blobId, type) {
+  return z32.encode(c.encode(BlobId, { coreKey, ...blobId, type }))
+}
+
+/**
+ * Decode a string id back into its coreKey, raw blobId and type.
+ *
+ * @param {string} id
+ * @returns {{ coreKey: Uint8Array, blobId: RawBlobId, type: string }}
+ */
+export function decodeId(id) {
+  if (typeof id !== 'string' || id.length === 0)
+    throw CeroError.INVALID('id must be a non-empty string')
+  let buf
+  try {
+    buf = z32.decode(id)
+  } catch {
+    throw CeroError.INVALID('id must be valid z32')
+  }
+  let v
+  try {
+    v = c.decode(BlobId, buf)
+  } catch {
+    throw CeroError.INVALID('id is malformed')
+  }
+  const { coreKey, blockOffset, blockLength, byteOffset, byteLength, type } = v
+  return { coreKey, blobId: { blockOffset, blockLength, byteOffset, byteLength }, type }
+}

package/src/blobs/index.js

@@ -1,41 +1,26 @@
 import Hyperblobs from 'hyperblobs'
 import ReadyResource from 'ready-resource'
-import sodium from 'sodium-universal'
 import b4a from 'b4a'
-import z32 from 'z32'
 
 import { NAMESPACE } from '../lib/constants.js'
 import { toId } from '../lib/utils.js'
 import { CeroError } from '../lib/errors.js'
+import { encodeId, decodeId } from './codec.js'
 
 const NS = `${NAMESPACE}/blobs`
 
 /**
  * @typedef {object} BlobsOpts
- * @property {any} store                                              Corestore (or compatible) used to host the blob core.
+ * @property {object} store                                           Corestore (or compatible) used to host the blob core.
  * @property {import('../identity/index.js').Identity} [identity]     Identity supplying the default encryption key.
  * @property {import('../network/index.js').Network} [network]        Optional network used to announce + replicate the core.
  * @property {Uint8Array} [key]                                       Pre-existing blob core key — joins an existing blob feed.
  * @property {Uint8Array} [encryptionKey]                             Explicit encryption key, overrides `identity.encryptionKey`.
  *
- * @typedef {object} BlobEntry
- * @property {string} id                                              Opaque z32 id used by `get`/`info`/`delete`.
- * @property {string} hash                                            Content hash (z32-encoded blake2b of the bytes).
- * @property {number} size                                            Logical byte length recorded at put-time.
- * @property {any} meta                                               Caller-provided metadata, stored verbatim.
- * @property {number} createdAt                                       Wall-clock timestamp of the put.
- *
- * @typedef {object} PutOpts
- * @property {any} [meta]                                             Arbitrary metadata persisted alongside the blob.
- * @property {number} [size]                                          Override the recorded size (defaults to byte length).
+ * @typedef {import('./codec.js').RawBlobId} RawBlobId
  */
 
-/**
- * Content-addressable blob store backed by a single Hyperblobs core.
- * Writes dedupe locally by content hash, reads/streams are positional
- * descriptors, and the underlying core is attached to the supplied
- * network for replication.
- */
+/** Thin wrapper over a single Hyperblobs core; deals only in raw blobIds. */
 export class Blobs extends ReadyResource {
   /** @param {BlobsOpts} [opts] */
   constructor({ store, identity, network, key, encryptionKey } = {}) {
@@ -51,12 +36,7 @@ export class Blobs extends ReadyResource {
     this._coreKey = key || null
     this.core = null
     this.hyperblobs = null
-
     this._discovery = null
-    /** @type {Map<string, BlobEntry>} contentHash → entry */
-    this._index = new Map()
-    /** @type {Map<string, BlobEntry>} id → entry (so info/has/delete by id work) */
-    this._byId = new Map()
   }
 
   /**
@@ -94,7 +74,8 @@ export class Blobs extends ReadyResource {
     if (this._coreKey) opts.key = this._coreKey
     else opts.name = 'blobs'
 
-    this.core = this.store.namespace(NS).get(opts)
+    const ns = this.store.namespace(NS)
+    this.core = ns.get(opts)
     await this.core.ready()
 
     this.hyperblobs = new Hyperblobs(this.core)
@@ -114,130 +95,67 @@ export class Blobs extends ReadyResource {
   }
 
   /**
-   * Store a buffer or readable stream, returning its opaque id. Identical
-   * content from the same writer is deduplicated locally.
+   * Store a buffer or readable stream, returning its raw hyperblobs blobId.
    *
    * @param {Uint8Array | import('streamx').Readable} input
-   * @param {PutOpts} [opts]
-   * @returns {Promise<string>}
+   * @returns {Promise<RawBlobId>}
    */
-  async put(input, { meta = null, size = null } = {}) {
+  async put(input) {
     this._guard()
     if (input == null) throw CeroError.REQUIRED('input')
-
-    let bytes
-    if (isBufferLike(input)) {
-      bytes = b4a.from(input)
-    } else if (isReadable(input)) {
-      bytes = await readAll(input)
-    } else {
-      throw CeroError.INVALID('input must be a buffer or a Readable stream')
-    }
-
-    const hashBuf = contentHash(bytes)
-    const hash = toId(hashBuf)
-
-    // Local dedup: same writer putting same bytes returns the existing id.
-    const existing = this._index.get(hash)
-    if (existing) return existing.id
-
-    const raw = await this.hyperblobs.put(bytes)
-    const id = encodeId(raw)
-    const entry = {
-      id,
-      hash,
-      size: size ?? bytes.byteLength,
-      meta,
-      createdAt: Date.now()
-    }
-    this._index.set(hash, entry)
-    this._byId.set(id, entry)
-    return id
+    if (b4a.isBuffer(input)) return this.hyperblobs.put(b4a.from(input))
+    if (isReadable(input)) return this._putStream(input)
+    throw CeroError.INVALID('input must be a buffer or a Readable stream')
   }
 
   /**
-   * Delete the blob with the given id and forget its local index entry.
-   *
-   * @param {string} id
-   * @returns {Promise<void>}
+   * @param {import('streamx').Readable} input
+   * @returns {Promise<RawBlobId>}
    */
-  async delete(id) {
-    this._guard()
-    const raw = decodeId(id)
-    await this.hyperblobs.clear(raw)
-    const entry = this._byId.get(id)
-    if (entry) {
-      this._byId.delete(id)
-      this._index.delete(entry.hash)
-    }
+  async _putStream(input) {
+    const ws = this.hyperblobs.createWriteStream()
+    await new Promise((resolve, reject) => {
+      input.on('error', reject)
+      ws.on('error', reject)
+      ws.on('close', resolve)
+      input.pipe(ws)
+    })
+    return ws.id
   }
 
   /**
-   * Resolve the blob bytes for an id. Fetches from peers if not local.
+   * Resolve the blob bytes for a raw blobId. Fetches from peers if not local.
    *
-   * @param {string} id
-   * @param {any} [opts]
+   * @param {RawBlobId} blobId
+   * @param {object} [opts]
    * @returns {Promise<Uint8Array>}
    */
-  async get(id, opts) {
+  async get(blobId, opts) {
     this._guard()
-    const raw = decodeId(id)
-    return this.hyperblobs.get(raw, opts)
+    return this.hyperblobs.get(blobId, opts)
   }
 
   /**
-   * Streaming counterpart of `get` — returns a Readable over the blob bytes.
+   * Streaming counterpart of `get` — a Readable over the blob bytes.
    *
-   * @param {string} id
-   * @param {any} [opts]
+   * @param {RawBlobId} blobId
+   * @param {object} [opts]
    * @returns {import('streamx').Readable}
    */
-  read(id, opts) {
-    this._guard()
-    const raw = decodeId(id)
-    return this.hyperblobs.createReadStream(raw, opts)
-  }
-
-  /**
-   * Look up the locally-cached metadata for a blob id, or `null` if absent.
-   *
-   * @param {string} id
-   * @returns {Promise<BlobEntry | null>}
-   */
-  async info(id) {
+  createReadStream(blobId, opts) {
     this._guard()
-    decodeId(id) // validate id shape
-    return this._byId.get(id) || null
+    return this.hyperblobs.createReadStream(blobId, opts)
   }
 
   /**
-   * Whether the underlying blocks for the blob are present in the local core.
+   * Clear the blocks backing a raw blobId from the local core.
    *
-   * @param {string} id
-   * @returns {Promise<boolean>}
-   */
-  async has(id) {
-    this._guard()
-    const raw = decodeId(id)
-    const len = raw.blockOffset + raw.blockLength
-    if (this.core.length < len) return false
-    return this.core.has(raw.blockOffset, len)
-  }
-
-  /**
-   * Pre-fetch the blocks for `id` from peers without reading the bytes.
-   *
-   * @param {string} id
-   * @param {any} [opts]
+   * @param {RawBlobId} blobId
    * @returns {Promise<void>}
    */
-  async fetch(id, opts) {
+  async clear(blobId) {
     this._guard()
-    const raw = decodeId(id)
-    const start = raw.blockOffset
-    const end = raw.blockOffset + raw.blockLength
-    const range = this.core.download({ start, end, ...opts })
-    await range.done()
+    await this.hyperblobs.clear(blobId)
   }
 
   _guard() {
@@ -246,52 +164,12 @@ export class Blobs extends ReadyResource {
   }
 }
 
-function contentHash(bytes) {
-  const out = b4a.alloc(32)
-  sodium.crypto_generichash(out, bytes)
-  return out
-}
-
-function isBufferLike(x) {
-  return b4a.isBuffer(x) || x instanceof Uint8Array
-}
-
+/**
+ * @param {unknown} x
+ * @returns {x is import('streamx').Readable}
+ */
 function isReadable(x) {
   return x && typeof x.pipe === 'function' && typeof x.on === 'function'
 }
 
-async function readAll(stream) {
-  const chunks = []
-  for await (const chunk of stream) chunks.push(chunk)
-  return b4a.concat(chunks)
-}
-
-// id <-> raw hyperblobs descriptor (positional inside the core)
-// 16-byte packed: 4 uint32-BE = blockOffset, blockLength, byteOffset, byteLength
-
-function encodeId(raw) {
-  const buf = b4a.alloc(16)
-  buf.writeUInt32BE(raw.blockOffset, 0)
-  buf.writeUInt32BE(raw.blockLength, 4)
-  buf.writeUInt32BE(raw.byteOffset, 8)
-  buf.writeUInt32BE(raw.byteLength, 12)
-  return z32.encode(buf)
-}
-
-function decodeId(id) {
-  if (typeof id !== 'string') throw CeroError.INVALID('id must be a string')
-  if (id.length === 0) throw CeroError.INVALID('id must be a non-empty string')
-  let buf
-  try {
-    buf = z32.decode(id)
-  } catch {
-    throw CeroError.INVALID('id must be valid z32')
-  }
-  if (buf.length !== 16) throw CeroError.INVALID('id must be 16 bytes when decoded')
-  return {
-    blockOffset: buf.readUInt32BE(0),
-    blockLength: buf.readUInt32BE(4),
-    byteOffset: buf.readUInt32BE(8),
-    byteLength: buf.readUInt32BE(12)
-  }
-}
+export { encodeId, decodeId }

package/src/blobs/server.js

@@ -0,0 +1,48 @@
+import BlobServer from 'hypercore-blob-server'
+import { decodeId } from './index.js'
+
+/**
+ * @typedef {{ key: Buffer, encryptionKey: Buffer | null }} Resolved
+ */
+
+/**
+ * HTTP server that turns a string file id into a renderable localhost URL.
+ * Wraps hypercore-blob-server; the underlying store session is owned by
+ * BlobServer and closed when `close()` is called.
+ */
+export class FileServer {
+  /**
+   * @param {object} opts
+   * @param {import('corestore')} opts.store
+   * @param {(coreKey: Buffer, info: object) => Resolved | null | Promise<Resolved | null>} opts.resolve
+   */
+  constructor({ store, resolve }) {
+    this.resolve = resolve
+    this.server = new BlobServer(store.session(), {
+      resolve: (key, info) => this.resolve(key, info)
+    })
+  }
+
+  get port() {
+    return this.server.port
+  }
+
+  async listen() {
+    await this.server.listen()
+  }
+
+  /**
+   * Build a renderable localhost URL for a string file id.
+   *
+   * @param {string} id
+   * @returns {string}
+   */
+  getLink(id) {
+    const { coreKey, blobId, type } = decodeId(id)
+    return this.server.getLink(coreKey, { blob: blobId, type })
+  }
+
+  async close() {
+    await this.server.close()
+  }
+}

package/src/database/bootstrap.js

@@ -1,5 +1,7 @@
+import b4a from 'b4a'
 import Hypercore from 'hypercore'
 import { Identity } from '../identity/index.js'
+import { CeroError } from '../lib/errors.js'
 import { toId } from '../lib/utils.js'
 
 /**
@@ -11,7 +13,7 @@ import { toId } from '../lib/utils.js'
  * @param {{ name?: string | null, isMobile?: boolean, recovering?: boolean }} [opts]
  * @returns {Promise<{ id: Uint8Array, writer: import('../identity/index.js').KeyPair }>}
  */
-export async function bootstrap(db, { name, isMobile, recovering = false } = {}) {
+export async function bootstrap(db, { name, isMobile, recovering = false, timeout = 30000 } = {}) {
   const keyPair = Identity.randomKeyPair()
   const manifest = {
     version: db.store.manifestVersion,
@@ -19,22 +21,36 @@ export async function bootstrap(db, { name, isMobile, recovering = false } = {})
   }
   const writerKey = Hypercore.key(manifest)
 
-  if (recovering) await waitForFirstPeerAppend(db)
+  if (recovering) await waitForFirstPeerAppend(db, timeout)
   await saveWriter(db, writerKey, { name, isMobile })
   await swapWriter(db, keyPair, manifest)
 
   return { id: writerKey, writer: keyPair }
 }
 
-async function waitForFirstPeerAppend(db) {
+async function waitForFirstPeerAppend(db, timeout = 30000) {
   if (db.bee.local.length > 0 || !db.network?.swarm) return
-  await new Promise((resolve) => {
-    const onAppend = () => {
-      if (db.bee.local.length === 0) return
+  await new Promise((resolve, reject) => {
+    let done = false
+    const finish = (err) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
       db.bee.local.off('append', onAppend)
-      resolve()
+      db.off('close', onClose)
+      if (err) reject(err)
+      else resolve()
     }
+    // timeout + close handling so a peer that never replicates can't hang the
+    // recovery forever, and the append listener is always removed.
+    const onAppend = () => db.bee.local.length > 0 && finish()
+    const onClose = () => finish(CeroError.CLOSED('Database'))
+    const timer = setTimeout(
+      () => finish(CeroError.TIMED_OUT('recovery — no peer append')),
+      timeout
+    )
     db.bee.local.on('append', onAppend)
+    db.on('close', onClose)
   })
   await db.bee.update()
 }
@@ -46,7 +62,7 @@ async function saveWriter(db, writerKey, { name, isMobile }) {
       {
         master: db.identity.publicKey,
         writer: writerKey,
-        sig: db.identity.sign(writerKey)
+        sig: db.identity.sign(b4a.concat([writerKey, db.writerKey]))
       }
     ],
     [
@@ -65,10 +81,6 @@ async function swapWriter(db, keyPair, manifest) {
   const enc = await db.bee.local.getUserData('autobee/encryption')
 
   if (db.network) db.network.detach(db.bee)
-  if (db.onLocalAppend && db.bee.local) {
-    db.bee.local.off('append', db.onLocalAppend)
-    db.onLocalAppend = null
-  }
   await db.bee.close()
   db.bee = null