@cero-base/cero 1.18.2 → 2.0.0

package/src/index.js

@@ -2,6 +2,7 @@ import Hypercore from 'hypercore'
 import HypercoreStorage from 'hypercore-storage'
 import Corestore from 'corestore'
 import safetyCatch from 'safety-catch'
+import c from 'compact-encoding'
 import fs from 'fs'
 
 import { Identity } from '@cero-base/core/identity'
@@ -29,8 +30,8 @@ import {
 } from './lib/operators.js'
 import { peek } from './lib/peek.js'
 import { t, schema } from './lib/spec.js'
-import { FLUSH } from './lib/constants.js'
-import { internal } from './lib/internal.js'
+import { FLUSH, TIMEOUT } from './lib/constants.js'
+import { registry } from './extensions/index.js'
 
 export { Handle, Ref, Local }
 export {
@@ -68,21 +69,18 @@ export { t, schema } from './lib/spec.js'
  * @property {number[]} [backoffs]                     Swarm reconnect backoff tiers in ms (testing/tuning).
  * @property {string} [channel]                        Optional network-isolation label; only same-channel peers connect.
  * @property {Array<string | Uint8Array>} [mirrors]    Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
- * @property {Uint8Array} [key]                        Pre-existing database key (skip bootstrap).
+ * @property {Uint8Array} [key]                        Existing database key to recover into, skipping the pointer lookup.
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
  * @property {(err: any) => void} [onerror]            Background-task error handler.
- * @property {boolean} [recovery]                      Recovery flow — wipe local state and re-claim a writer slot.
- * @property {number} [recoveryTimeout]                Max wait for peer data + writer capability during recovery.
+ * @property {number} [recoveryTimeout]                Max wait to find another device and be admitted, in ms. Defaults to 30000.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
  * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number, pipe?: 'l2cap' | 'gatt' }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
  */
 
 /**
- * Open (or create) a cero handle at `dir`. Sets up storage, network and
- * identity, then returns a ready root `Handle` with all schema refs
- * attached as properties.
+ * Open (or create) a cero handle at `dir`.
  *
  * @param {string} dir       Data directory.
  * @param {any} spec         Built spec — output of `cero/build`.
@@ -99,9 +97,7 @@ export async function cero(dir, spec, opts = {}) {
   let network = null
   let discovery = null
   let me = null
-  // Any failure during open (bad phrase, network/bootstrap error, recovery
-  // timeout, extension setup) must close whatever opened — else the corestore
-  // lock leaks and a retry in the same process hits locked storage.
+  // any failure during open must close what opened, or the storage lock leaks
   try {
     await storage.ready()
     await fs.promises.chmod(`${dir}/main`, 0o700)
@@ -115,10 +111,11 @@ export async function cero(dir, spec, opts = {}) {
 
     const { identity, fresh } = await resolveIdentity(opts, local)
     const writer = local ? (await local.store.get('keypair')).data : null
+    // a supplied identity on a device with no writer recovers; only a cero-minted identity creates
+    const recovering = !writer && (!!opts.key || !fresh)
+    const timeout = opts.recoveryTimeout || TIMEOUT
 
-    // Channel stamp: a storage remembers its channel; reopening it under a different channel —
-    // including no channel at all, which would silently rejoin the global network — is a
-    // misconfiguration that could leak data across networks, so reject it.
+    // a storage remembers its channel; reopening under another would silently rejoin the global network
     if (local) {
       const stored = (await local.store.get('environment')).data?.channel ?? null
       const wanted = opts.channel ?? null
@@ -136,10 +133,21 @@ export async function cero(dir, spec, opts = {}) {
     })
     await network.ready()
     discovery = network.join(identity.topic)
-    // a freshly minted identity has no peers yet — flushing the announce
-    // before proceeding only delays first onboarding
+    // a fresh identity has no peers yet, flushing the announce would only delay onboarding
     if (!fresh) await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, FLUSH))])
 
+    // the pointer core: identity-signed, written once by the creating device, holds the root key
+    const manifest = pointerManifest(store, identity)
+    const pointer = store.get(
+      !writer && !recovering
+        ? { keyPair: { publicKey: identity.publicKey, secretKey: identity.secretKey }, manifest }
+        : { key: Hypercore.key(manifest) }
+    )
+    await pointer.ready()
+    network.attach(pointer)
+
+    const key = opts.key || (recovering ? await readPointer(pointer, timeout) : undefined)
+
     me = new Handle({
       storage,
       store,
@@ -151,57 +159,31 @@ export async function cero(dir, spec, opts = {}) {
       opts,
       dir,
       routes: opts.routes,
-      key: opts.key,
+      key,
       encryptionKey: opts.encryptionKey,
       keyPair: writer ? { publicKey: writer.publicKey, secretKey: writer.secretKey } : undefined,
       pair: false
     })
     await me.ready()
+    me.once('close', () => {
+      network.detach(pointer)
+      pointer.close().catch(safetyCatch)
+    })
 
-    // a supplied or stored identity may already have history elsewhere —
-    // authoring genesis twice forks the seed-derived writer core (a writable
-    // core has one author, ever). Ask the peers directly with a plain session
-    // on the genesis core: the base never replicates an empty local core.
-    // Offline reuse is undetectable — this catches the reachable-peer case.
-    if (!writer && !opts.key && !opts.recovery && !fresh) {
-      const genesis = store.get({
-        key: Hypercore.key({
-          version: store.manifestVersion,
-          signers: [{ publicKey: identity.publicKey }]
-        })
-      })
-      await genesis.ready()
-      network.attach(genesis)
-      try {
-        const until = Date.now() + 1500
-        while (Date.now() < until) {
-          if (genesis.length > 0 || genesis.peers.some((p) => p.remoteLength > 0)) {
-            throw CeroError.CONFLICT('identity already has history — open with { recovery: true }')
-          }
-          await new Promise((r) => setTimeout(r, 100))
-        }
-      } finally {
-        network.detach(genesis)
-        await genesis.close()
-      }
-    }
-    // decided by the stored writer and the caller's intent, never by the local
-    // core's length: a same-identity device opens on the genesis core, which
-    // fills with the first device's blocks as soon as a peer connects
-    if (!writer && (!opts.key || opts.recovery)) {
+    if (!writer) {
       const result = await me.bootstrap({
         name: opts.name || null,
         isMobile: opts.isMobile === true,
-        recovering: opts.recovery === true,
-        ...(opts.recoveryTimeout ? { timeout: opts.recoveryTimeout } : {})
+        recovering,
+        timeout
       })
-      if (local && result?.writer) {
+      if (local) {
         await local.store.set('keypair', {
           publicKey: result.writer.publicKey,
           secretKey: result.writer.secretKey
         })
       }
-      if (!opts.recovery) {
+      if (!recovering) {
         const ts = Date.now()
         await me.store.call('add-member', {
           id: identity.id,
@@ -211,29 +193,20 @@ export async function cero(dir, spec, opts = {}) {
           createdAt: ts,
           updatedAt: ts
         })
+        if (pointer.length === 0) await pointer.append(c.encode(c.fixed32, me.store.key))
       }
     }
-    if (opts.recovery) await me.recover({ timeout: opts.recoveryTimeout })
 
-    for (const ext of internal.extensions) {
+    for (const ext of registry) {
       if (ext.bundled && opts.extensions === false) continue
       const off = await ext.setup?.(me)
       if (typeof off === 'function') me.once('close', off)
     }
 
     if (opts.bluetooth) {
-      // `true` → defaults; `{ autoStart, backend }` → options. A bare backend
-      // object (pre-1.3 shape, has Central/Server) is still accepted.
-      const bt =
-        opts.bluetooth === true
-          ? {}
-          : opts.bluetooth.Central
-            ? { backend: opts.bluetooth }
-            : opts.bluetooth
+      const bt = opts.bluetooth === true ? {} : opts.bluetooth
       me.bluetooth = new Bluetooth(me, {
-        // pass the backend through untouched: `|| null` turned an omitted
-        // backend (= lazy-load bare-bluetooth) into an explicit null
-        // (= disabled), leaving BLE 'unsupported' on every platform
+        // an omitted backend lazy-loads bare-bluetooth, null disables it
         backend: bt.backend,
         autoStart: bt.autoStart !== false,
         maxOutbound: bt.maxOutbound,
@@ -247,8 +220,7 @@ export async function cero(dir, spec, opts = {}) {
     bind(me, null)
     return me
   } catch (err) {
-    // once the root Handle exists it owns (and closes) everything; before that,
-    // tear the raw resources down in reverse order.
+    // before the root Handle exists, tear the raw resources down in reverse order
     if (me) await me.close().catch(safetyCatch)
     else {
       await discovery?.destroy().catch(safetyCatch)
@@ -262,9 +234,7 @@ export async function cero(dir, spec, opts = {}) {
 }
 
 /**
- * Restore a cero instance from a mnemonic phrase. Closes the running
- * instance, wipes the on-disk `main/` tree and re-opens with `recovery: true`
- * so the writer slot is re-claimed.
+ * Restore a cero instance from a mnemonic phrase.
  *
  * @param {Handle} me   Existing root handle to restore.
  * @param {string} phrase   BIP-39 mnemonic phrase.
@@ -274,48 +244,23 @@ export async function restore(me, phrase) {
   if (!me?._dir) throw CeroError.INVALID('me must be a cero instance')
   if (!phrase || typeof phrase !== 'string') throw CeroError.INVALID('phrase must be a string')
 
-  // Already this identity? Nothing to restore — return the running instance.
   const current = await Identity.fromSeed(Identity.toSeed(phrase))
   if (current.id === me.identity.id) return me
 
-  const { _dir: dir, spec, _opts: opts } = me
-  // channel must carry over — without it the recovered instance rejoins the
-  // global identity topic and never meets its channeled peers (recovery timeout).
+  // everything carries over except the identity, the channel above all
   const {
-    name,
-    bootstrap,
-    isMobile,
-    onerror,
-    routes,
-    recoveryTimeout,
-    channel,
-    mirrors,
-    storageKey,
-    extensions
-  } = opts
+    _dir: dir,
+    spec,
+    _opts: { seed, identity, key, keyPair, ...opts }
+  } = me
 
   await me.close()
   await fs.promises.rm(`${dir}/main`, { recursive: true, force: true })
 
-  return cero(dir, spec, {
-    name,
-    bootstrap,
-    isMobile,
-    onerror,
-    routes,
-    recoveryTimeout,
-    channel,
-    mirrors,
-    storageKey,
-    extensions,
-    phrase,
-    recovery: true
-  })
+  return cero(dir, spec, { ...opts, phrase })
 }
 
-// Facade: expose the operators + helpers as properties on `cero` too, so both
-// `import { define }` and `cero.define(...)` work. Explicit assignments (not
-// `Object.assign`) so tsc reflects them onto the `cero` namespace in the .d.ts.
+// the facade: cero.put and import { put } are the same function
 cero.t = t
 cero.put = put
 cero.set = set
@@ -334,18 +279,26 @@ cero.restore = restore
 cero.schema = schema
 cero.bind = bind
 cero.define = define
-// test-only escape hatch (cross-package tests reset/seed the registry)
-cero._internal = internal
-// A bare function is shorthand for a behavior-only extension: `{ setup: fn }`.
-// Accepts both `use(a, b)` and `use([a, b])` (and a mix) for easier composition.
-// A named extension replaces any registered one with the same name — so
-// `use(profileSync({ fields }))` reconfigures the bundled default instead of
-// doubling it.
+// test-only
+cero._registry = registry
+// a bare function is shorthand for { setup }; a named extension replaces one of the same name
 cero.use = (...exts) => {
   for (const e of exts.flat().map((e) => (typeof e === 'function' ? { setup: e } : e))) {
-    const i = e.name ? internal.extensions.findIndex((x) => x.name === e.name) : -1
-    if (i >= 0) internal.extensions[i] = e
-    else internal.extensions.push(e)
+    const i = e.name ? registry.findIndex((x) => x.name === e.name) : -1
+    if (i >= 0) registry[i] = e
+    else registry.push(e)
+  }
+}
+
+function pointerManifest(store, identity) {
+  return { version: store.manifestVersion, signers: [{ publicKey: identity.publicKey }] }
+}
+
+async function readPointer(pointer, timeout) {
+  try {
+    return c.decode(c.fixed32, await pointer.get(0, { timeout }))
+  } catch {
+    throw CeroError.TIMED_OUT('recovery: finding a device of this identity')
   }
 }
 

package/src/lib/bluetooth.js

@@ -8,19 +8,8 @@ import { Pairing } from '@cero-base/core/pairing'
 import { Invite } from '@cero-base/core/invite'
 
 /**
- * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin
- * facade over ble-swarm. Bluetooth only changes how peers meet and carry
- * bytes; capability-gated replication still decides what syncs. Discovery is
- * one topic-derived service UUID at a time (tag `cero-ble`) — the data service
- * sits on a fixed per-tag UUID, so switching topics only retunes the radio.
- *
- * ```js
- * const me = await cero(dir, spec, { channel, bluetooth: true })
- * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'starting' | 'on'
- * await me.bluetooth.start()
- * me.bluetooth.peers          // Map of live BLE links
- * me.bluetooth.on('update', () => {})
- * ```
+ * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin facade over
+ * ble-swarm.
  *
  * @extends ReadyResource
  */
@@ -43,14 +32,11 @@ export class Bluetooth extends ReadyResource {
     this._restorePending = false
 
     const identity = handle.identity
-    // the mesh topic: one per channel, or a fixed global topic when
-    // channelless — any nearby cero device links (global nearby; strangers
-    // still sync zero bytes, replication is capability-gated)
+    // one mesh topic per channel, or a global one when channelless; strangers still sync nothing
     this._topic = crypto.hash(b4a.from(handle.network.channel || 'cero-ble'))
     this.swarm = new BluetoothSwarm({
       backend,
-      // injected links authenticate with the same long-lived identity as the
-      // swarm, so one person reached over Wi-Fi and BLE dedupes to one peer
+      // the swarm identity, so one person over Wi-Fi and BLE dedupes to one peer
       keyPair: { publicKey: identity.publicKey, secretKey: identity.secretKey },
       topic: this._topic,
       tag: 'cero-ble',
@@ -59,9 +45,7 @@ export class Bluetooth extends ReadyResource {
       maxInbound
     })
     this.swarm.on('update', () => {
-      // an ended rendezvous retunes back to the mesh only once its links
-      // drain — retuning drops links, and the pairing link still carries
-      // the joiner's initial replication
+      // retune to the mesh only once the pairing link's initial replication drained
       if (this._restorePending && this.swarm.peers.size === 0) {
         this._restorePending = false
         this.swarm.setTopic(this._topic).catch(safetyCatch)
@@ -69,7 +53,6 @@ export class Bluetooth extends ReadyResource {
       this.emit('update')
     })
     this.swarm.on('connection', (conn) => {
-      // the same treatment as any transport: wakeup, replication, pairing
       this._handle.network.inject(conn)
     })
   }
@@ -88,6 +71,11 @@ export class Bluetooth extends ReadyResource {
     if (this._autoStart) await this.start()
   }
 
+  async _close() {
+    this._clearAnnounce()
+    await this.swarm.destroy()
+  }
+
   /**
    * Begin advertising + scanning. Idempotent; no-op when unsupported.
    *
@@ -98,34 +86,20 @@ export class Bluetooth extends ReadyResource {
   }
 
   /**
-   * Stop advertising/scanning and drop links; open invite rendezvous end with
-   * the radio. Idempotent. Local data and the rest of the network (DHT) are
-   * untouched.
+   * Stop advertising/scanning and drop links; open invite rendezvous end with the radio.
    *
    * @returns {Promise<void>}
    */
   async stop() {
     this._clearAnnounce()
     await this.swarm.stop()
-    // while stopped setTopic just sticks — the next start() is back on the
-    // mesh. A start() + announce() that landed during the await wins.
+    // while stopped setTopic sticks; a start() + announce() during the await wins
     if (!this._announce) await this.swarm.setTopic(this._topic)
   }
 
   /**
-   * Offline join rendezvous: retune the radio to the invite-derived topic so
-   * holder and joiner find each other with zero DHT. One topic at a time —
-   * announcing a new invite replaces the previous rendezvous. Returns a stop
-   * function — closing the QR must stop the rendezvous so a photographed
-   * invite doesn't stay an ambient discovery beacon (admission itself is
-   * always gated by blind-pairing verifying the invite). The retune back to
-   * the mesh topic waits for live links to drain: the link a join just
-   * established survives and carries the joiner's initial replication.
-   * Auto-stops at the invite's expiry, on `stop()`, and on close.
-   *
-   * Only active while nearby sync is on: before `start()` (and after `stop()`)
-   * this is a no-op — the user controls the radio, and a join must not touch
-   * Bluetooth (OS permissions, GATT server) they never enabled.
+   * Offline join rendezvous: retune the radio to the invite-derived topic so holder and
+   * joiner find each other with zero DHT.
    *
    * @param {string} invite  Z32 invite string.
    * @returns {() => void}
@@ -161,20 +135,6 @@ export class Bluetooth extends ReadyResource {
     }
   }
 
-  _stopAnnounce() {
-    this._clearAnnounce()
-    if (this.swarm.peers.size > 0) this._restorePending = true
-    else this.swarm.setTopic(this._topic).catch(safetyCatch)
-  }
-
-  _clearAnnounce() {
-    const e = this._announce
-    if (!e) return
-    if (e.timer) clearTimeout(e.timer)
-    this._announce = null
-    this._restorePending = false
-  }
-
   /**
    * Host-lifecycle pause (app backgrounded): radio down, user intent kept.
    *
@@ -193,8 +153,17 @@ export class Bluetooth extends ReadyResource {
     await this.swarm.resume()
   }
 
-  async _close() {
+  _stopAnnounce() {
     this._clearAnnounce()
-    await this.swarm.destroy()
+    if (this.swarm.peers.size > 0) this._restorePending = true
+    else this.swarm.setTopic(this._topic).catch(safetyCatch)
+  }
+
+  _clearAnnounce() {
+    const e = this._announce
+    if (!e) return
+    if (e.timer) clearTimeout(e.timer)
+    this._announce = null
+    this._restorePending = false
   }
 }

package/src/lib/constants.js

@@ -1,5 +1,3 @@
-// Shared cero constants.
-
 export const NS = 'cero'
 export const COUNTERS = 'counters'
 export const EPOCHS = 'epochs'
@@ -7,16 +5,3 @@ export const EPOCHS = 'epochs'
 // Writer-admission / pairing timeout (ms), and the initial discovery-flush wait (ms).
 export const TIMEOUT = 30000
 export const FLUSH = 500
-
-// schema-DSL primitive → HyperDB type (used by the builder).
-export const DB_TYPE = {
-  string: 'string',
-  uint: 'uint',
-  int: 'int',
-  bool: 'bool',
-  bytes: 'buffer',
-  json: 'json',
-  fixed32: 'fixed32',
-  fixed64: 'fixed64',
-  file: 'string'
-}