@cero-base/core 0.2.0 → 0.4.1

package/package.json

@@ -1,48 +1,143 @@
 {
   "name": "@cero-base/core",
-  "version": "0.2.0",
-  "description": "P2P database with collection-based CRUD and RPC",
+  "version": "0.4.1",
+  "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "files": [
     "src",
-    "README.md"
+    "types",
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
-  "main": "src/index.js",
   "exports": {
-    ".": "./src/index.js",
-    "./schema": "./src/lib/schema.js",
-    "./builder": "./src/lib/builder.js",
-    "./constants": "./src/lib/constants.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./identity": {
+      "types": "./types/identity/index.d.ts",
+      "default": "./src/identity/index.js"
+    },
+    "./storage": {
+      "types": "./types/storage/index.d.ts",
+      "default": "./src/storage/index.js"
+    },
+    "./network": {
+      "types": "./types/network/index.d.ts",
+      "default": "./src/network/index.js"
+    },
+    "./database": {
+      "types": "./types/database/index.d.ts",
+      "default": "./src/database/index.js"
+    },
+    "./blobs": {
+      "types": "./types/blobs/index.d.ts",
+      "default": "./src/blobs/index.js"
+    },
+    "./rpc": {
+      "types": "./types/rpc/index.d.ts",
+      "default": "./src/rpc/index.js"
+    },
+    "./pairing": {
+      "types": "./types/pairing/index.d.ts",
+      "default": "./src/pairing/index.js"
+    },
+    "./invite": {
+      "types": "./types/pairing/invite.d.ts",
+      "default": "./src/pairing/invite.js"
+    },
+    "./schema": {
+      "types": "./types/lib/schema.d.ts",
+      "default": "./src/lib/schema.js"
+    },
+    "./utils": {
+      "types": "./types/lib/utils.d.ts",
+      "default": "./src/lib/utils.js"
+    },
+    "./errors": {
+      "types": "./types/lib/errors.d.ts",
+      "default": "./src/lib/errors.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "invite": [
+        "types/pairing/invite.d.ts"
+      ],
+      "schema": [
+        "types/lib/schema.d.ts"
+      ],
+      "utils": [
+        "types/lib/utils.d.ts"
+      ],
+      "errors": [
+        "types/lib/errors.d.ts"
+      ],
+      "*": [
+        "types/*/index.d.ts"
+      ]
+    }
+  },
+  "imports": {
+    "fs": {
+      "bare": "bare-fs",
+      "default": "fs"
+    },
+    "path": {
+      "bare": "bare-path",
+      "default": "path"
+    },
+    "crypto": {
+      "bare": "bare-crypto",
+      "default": "crypto"
+    }
   },
   "scripts": {
+    "build": "node schema/build.js",
     "build:test": "rm -rf test/fixture/spec && node test/fixture/build.js",
+    "build:types": "rm -rf types && tsc -p .",
     "pretest": "npm run build:test",
-    "test": "brittle test/*.js"
+    "prepublishOnly": "npm run build:types",
+    "test": "brittle-node test/*.test.js"
   },
   "dependencies": {
-    "@lekinox/cero": "^1.3.1",
-    "compact-encoding": "^2.19.1",
-    "ready-resource": "^1.0.2",
-    "safety-catch": "^1.0.2"
+    "autobee": "^1.0.3",
+    "b4a": "^1.8.1",
+    "bare-crypto": "^1.13.7",
+    "bare-fs": "^4.7.1",
+    "bare-path": "^3.0.0",
+    "bip39-mnemonic": "^2.5.0",
+    "blind-pairing": "^2.3.1",
+    "compact-encoding": "^3.1.0",
+    "corestore": "^7.9.2",
+    "framed-stream": "^1.0.1",
+    "hrpc": "^4.3.0",
+    "hyperblobs": "^2.12.0",
+    "hypercore": "^11.30.2",
+    "hypercore-crypto": "^3.7.0",
+    "hypercore-id-encoding": "^1.3.0",
+    "hypercore-storage": "^3.0.2",
+    "hyperdb": "^6.7.0",
+    "hyperdispatch": "^1.6.0",
+    "hyperschema": "^1.21.0",
+    "hyperswarm": "^4.17.0",
+    "keet-identity-key": "^3.2.0",
+    "protomux-wakeup": "^2.9.0",
+    "ready-resource": "^1.2.0",
+    "safety-catch": "^1.0.3",
+    "sodium-universal": "^5.0.1",
+    "streamx": "^2.26.0",
+    "z32": "^1.1.0"
   },
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
-    "autobase-test-helpers": "^3.1.0",
-    "brittle": "^3.7.0",
-    "corestore": "^7.9.1",
-    "duplex-through": "^1.0.2",
-    "hrpc": "^4.3.0",
-    "hyperdb": "^6.3.0",
-    "hyperdispatch": "^1.5.1",
-    "hyperschema": "^1.20.1"
+    "brittle": "^4.0.0",
+    "typescript": "^5.7.0"
   },
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/lekinox/cero-base.git",
-    "directory": "packages/core"
-  }
+  "license": "Apache-2.0"
 }

package/src/blobs/index.js

@@ -0,0 +1,297 @@
+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'
+
+const NS = `${NAMESPACE}/blobs`
+
+/**
+ * @typedef {object} BlobsOpts
+ * @property {any} 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).
+ */
+
+/**
+ * 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.
+ */
+export class Blobs extends ReadyResource {
+  /** @param {BlobsOpts} [opts] */
+  constructor({ store, identity, network, key, encryptionKey } = {}) {
+    super()
+    if (!store) throw CeroError.REQUIRED('store')
+    if (!identity && !encryptionKey) throw CeroError.REQUIRED('identity or encryptionKey')
+
+    this.store = store
+    this.identity = identity || null
+    this.network = network || null
+    this.encryptionKey = encryptionKey || (identity && identity.encryptionKey) || null
+
+    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()
+  }
+
+  /**
+   * Canonical z32 id of the underlying core (null until ready).
+   *
+   * @returns {string | null}
+   */
+  get id() {
+    return this.key ? toId(this.key) : null
+  }
+
+  /**
+   * Public key of the underlying core.
+   *
+   * @returns {Uint8Array | null}
+   */
+  get key() {
+    return this.core ? this.core.key : null
+  }
+
+  /**
+   * Discovery key derived from the core key, used for swarm topics.
+   *
+   * @returns {Uint8Array | null}
+   */
+  get discoveryKey() {
+    return this.core ? this.core.discoveryKey : null
+  }
+
+  async _open() {
+    await this.store.ready()
+    if (this.network) await this.network.ready()
+
+    const opts = { encryptionKey: this.encryptionKey }
+    if (this._coreKey) opts.key = this._coreKey
+    else opts.name = 'blobs'
+
+    this.core = this.store.namespace(NS).get(opts)
+    await this.core.ready()
+
+    this.hyperblobs = new Hyperblobs(this.core)
+    await this.hyperblobs.ready()
+
+    if (this.network) {
+      this.network.attach(this.core)
+      this._discovery = this.network.join(this.core.discoveryKey)
+    }
+  }
+
+  async _close() {
+    if (this._discovery) await this._discovery.destroy()
+    if (this.network && this.core) this.network.detach(this.core)
+    if (this.hyperblobs) await this.hyperblobs.close()
+    if (this.core) await this.core.close()
+  }
+
+  /**
+   * Store a buffer or readable stream, returning its opaque id. Identical
+   * content from the same writer is deduplicated locally.
+   *
+   * @param {Uint8Array | import('streamx').Readable} input
+   * @param {PutOpts} [opts]
+   * @returns {Promise<string>}
+   */
+  async put(input, { meta = null, size = null } = {}) {
+    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
+  }
+
+  /**
+   * Delete the blob with the given id and forget its local index entry.
+   *
+   * @param {string} id
+   * @returns {Promise<void>}
+   */
+  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)
+    }
+  }
+
+  /**
+   * Resolve the blob bytes for an id. Fetches from peers if not local.
+   *
+   * @param {string} id
+   * @param {any} [opts]
+   * @returns {Promise<Uint8Array>}
+   */
+  async get(id, opts) {
+    this._guard()
+    const raw = decodeId(id)
+    return this.hyperblobs.get(raw, opts)
+  }
+
+  /**
+   * Streaming counterpart of `get` — returns a Readable over the blob bytes.
+   *
+   * @param {string} id
+   * @param {any} [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) {
+    this._guard()
+    decodeId(id) // validate id shape
+    return this._byId.get(id) || null
+  }
+
+  /**
+   * Whether the underlying blocks for the blob are present in 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]
+   * @returns {Promise<void>}
+   */
+  async fetch(id, opts) {
+    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()
+  }
+
+  _guard() {
+    if (this.closed) throw CeroError.CLOSED('Blobs')
+    if (!this.opened) throw CeroError.NOT_READY('Blobs', 'blobs')
+  }
+}
+
+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
+}
+
+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)
+  }
+}

package/src/database/CLAUDE.md

@@ -0,0 +1,3 @@
+<claude-mem-context>
+
+</claude-mem-context>

package/src/database/bootstrap.js

@@ -0,0 +1,76 @@
+import Hypercore from 'hypercore'
+import { Identity } from '../identity/index.js'
+
+/**
+ * First-run device provisioning: mint a device writer keypair, persist it as a
+ * writer, then swap the autobee's local core over to it. With `recovering`,
+ * waits for the first peer-replicated append before swapping.
+ *
+ * @param {import('./index.js').Database} db
+ * @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 } = {}) {
+  const keyPair = Identity.randomKeyPair()
+  const manifest = {
+    version: db.store.manifestVersion,
+    signers: [{ publicKey: keyPair.publicKey }]
+  }
+  const writerKey = Hypercore.key(manifest)
+
+  if (recovering) await waitForFirstPeerAppend(db)
+  await saveWriter(db, writerKey, { name, isMobile })
+  await swapWriter(db, keyPair, manifest)
+
+  return { id: writerKey, writer: keyPair }
+}
+
+async function waitForFirstPeerAppend(db) {
+  if (db.bee.local.length > 0 || !db.network?.swarm) return
+  await new Promise((resolve) => {
+    const onAppend = () => {
+      if (db.bee.local.length === 0) return
+      db.bee.local.off('append', onAppend)
+      resolve()
+    }
+    db.bee.local.on('append', onAppend)
+  })
+  await db.bee.update()
+}
+
+async function saveWriter(db, writerKey, { name, isMobile }) {
+  await db.write([
+    [
+      'add-writer',
+      {
+        master: db.identity.publicKey,
+        writer: writerKey,
+        sig: db.identity.sign(writerKey),
+        name: name || null,
+        isMobile: isMobile === true
+      }
+    ]
+  ])
+}
+
+async function swapWriter(db, keyPair, manifest) {
+  const head = await db.bee.local.getUserData('autobee/head')
+  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
+
+  const deviceCore = db.store.namespace(db.namespace).get({ keyPair, manifest })
+  await deviceCore.ready()
+  if (head) await deviceCore.setUserData('autobee/head', head)
+  if (enc) await deviceCore.setUserData('autobee/encryption', enc)
+  await deviceCore.close()
+
+  db.keyPair = keyPair
+  await db.openBee()
+}