@cero-base/cero 0.8.10 → 1.1.0

package/src/handle/index.js

@@ -1,4 +1,4 @@
-import AbortController from 'abort-controller'
+import AbortController from 'bare-abort-controller'
 import b4a from 'b4a'
 import Hypercore from 'hypercore'
 import { discoveryKey } from 'hypercore-crypto'
@@ -9,8 +9,10 @@ import z32 from 'z32'
 import { Identity } from '@cero-base/core/identity'
 import { Database } from '@cero-base/core/database'
 import { Pairing } from '@cero-base/core/pairing'
-import { toId } from '@cero-base/core/utils'
+import { toId, grants } from '@cero-base/core/utils'
 import { CeroError } from '@cero-base/core/errors'
+import { Blobs } from '@cero-base/core/blobs'
+import { FileServer } from '@cero-base/core/blobs/server'
 
 import { NS, TIMEOUT } from '../lib/constants.js'
 
@@ -63,7 +65,7 @@ export { Ref } from '../lib/utils.js'
  * @property {number} [timeout]
  *
  * @typedef {object} AcceptOpts
- * @property {string} [role]   Role to grant the joining peer. Falls back to the invite's role, then `'write'`.
+ * @property {string} [role]   Role to grant the joining peer. Falls back to the invite's role, then `'member'`.
  * @property {string | null} [name]
  *
  * @typedef {object} RecoverOpts
@@ -75,6 +77,8 @@ export { Ref } from '../lib/utils.js'
  * @property {import('../lib/utils.js').Ref} [members]    `members` ref, attached dynamically when the schema declares one.
  *
  * @typedef {Handle & HandleExtra} Child  A child handle plus its dynamically-attached refs.
+ *
+ * @typedef {Handle & Record<string, import('../lib/utils.js').Ref>} CeroHandle  A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
  */
 
 /**
@@ -113,6 +117,9 @@ export class Handle extends ReadyResource {
     this._onerror = this._opts.onerror || safetyCatch
     this.children = parent ? null : new Set()
     this._loading = parent ? null : new Map()
+    this._coreKeys = parent ? null : new Map()
+    this._fileServer = null
+    this._blobs = null
     this._owned = new Set()
 
     this.store = new Database({
@@ -124,7 +131,8 @@ export class Handle extends ReadyResource {
       key: opts.key,
       encryptionKey: opts.encryptionKey,
       namespace: opts.namespace,
-      keyPair: opts.keyPair
+      keyPair: opts.keyPair,
+      onerror: this._onerror
     })
     this.pair = null
     this._wantsPair = opts.pair !== false
@@ -136,16 +144,21 @@ export class Handle extends ReadyResource {
       this.pair = new Pairing({
         network: this.network,
         identity: this.identity,
-        topic: this.store.key
+        topic: this.store.key,
+        onerror: this._onerror
       })
       await this.pair.ready()
     }
     attachRefs(this, this.store.refs)
+    this.root._coreKeys.set(b4a.toString(this.store.key, 'hex'), this.store.encryptionKey)
+    if (!this.parent) await this.fileServer.listen()
   }
 
   async _close() {
+    this.root._coreKeys.delete(b4a.toString(this.store.key, 'hex'))
     for (const r of [...this._owned]) r.destroy?.()
     this._owned.clear()
+    if (this._blobs) await this._blobs.close()
     if (this.children) {
       for (const c of [...this.children]) await c.close()
       this.children.clear()
@@ -159,6 +172,10 @@ export class Handle extends ReadyResource {
     }
 
     if (this.local) await this.local.close()
+    if (this._fileServer) {
+      await this._fileServer.close()
+      this._fileServer = null
+    }
     const store = this.store.store
     await this.store.close()
     if (this._discovery) await this._discovery.destroy()
@@ -217,6 +234,79 @@ export class Handle extends ReadyResource {
     return this
   }
 
+  /** The top-most handle in the parent chain — itself for a root handle. */
+  get root() {
+    let h = this
+    while (h.parent) h = h.parent
+    return h
+  }
+
+  /**
+   * Lazily-built file server for this identity. Root-only — child handles
+   * reach it through `this.root.fileServer`.
+   *
+   * @returns {FileServer}
+   */
+  get fileServer() {
+    if (this.parent) return this.root.fileServer
+    if (!this._fileServer) {
+      this._fileServer = new FileServer({
+        store: this.store.store,
+        resolve: (coreKey, info) => this._resolveCore(coreKey, info)
+      })
+    }
+    return this._fileServer
+  }
+
+  /**
+   * @param {Uint8Array} coreKey
+   * @param {object} info
+   * @returns {{ key: Uint8Array, encryptionKey: Uint8Array } | null}
+   */
+  _resolveCore(coreKey, info) {
+    const hex = b4a.toString(coreKey, 'hex')
+    const encryptionKey = this.root._coreKeys.get(hex)
+    if (encryptionKey !== undefined) return { key: coreKey, encryptionKey }
+    return null
+  }
+
+  /**
+   * Resolve a durable file id to an ephemeral download url via this identity's
+   * file server.
+   *
+   * @param {string} id
+   * @returns {string}
+   */
+  getLink(id) {
+    return this.root.fileServer.getLink(id)
+  }
+
+  /**
+   * Lazily-built blob store for THIS handle's writing device. One core per
+   * writer, encrypted with the handle's encryptionKey and attached to the
+   * shared network for replication.
+   *
+   * @returns {Blobs}
+   */
+  get blobs() {
+    if (!this._blobs) {
+      this._blobs = new Blobs({
+        store: this.store.store,
+        network: this.network,
+        encryptionKey: this.store.encryptionKey
+      })
+      this._blobs
+        .ready()
+        .then(() => {
+          if (this._blobs && this._blobs.key) {
+            this.root._coreKeys.set(b4a.toString(this._blobs.key, 'hex'), this.store.encryptionKey)
+          }
+        })
+        .catch(() => {})
+    }
+    return this._blobs
+  }
+
   /** Canonical id — identity id for the root handle, store key for children. */
   get id() {
     if (!this.parent) return this.identity.id
@@ -249,11 +339,10 @@ export class Handle extends ReadyResource {
    * Claim writer capability on an existing database (paired-device flow).
    * Forwards to `Database.claim`.
    *
-   * @param {{ name?: string | null, isMobile?: boolean }} [opts]
    * @returns {Promise<void>}
    */
-  claim(opts) {
-    return this.store.claim(opts)
+  claim() {
+    return this.store.claim()
   }
 
   /**
@@ -277,6 +366,10 @@ export class Handle extends ReadyResource {
    * @returns {Promise<string>}  Z32-encoded invite string.
    */
   invite(opts) {
+    if (!this.pair)
+      throw CeroError.INVALID(
+        'invite() is not available on the root handle — open a child handle first'
+      )
     return this.pair.createInvite(opts)
   }
 
@@ -287,6 +380,7 @@ export class Handle extends ReadyResource {
    * @returns {boolean}  `true` if the invite was found and removed.
    */
   revoke(invite) {
+    if (!this.pair) throw CeroError.INVALID('revoke() is not available on the root handle')
     return this.pair.revoke(invite)
   }
 
@@ -305,7 +399,11 @@ export class Handle extends ReadyResource {
         'candidate userData must be a 64-byte buffer (identity + writer pubkey)'
       )
     }
-    role = role || candidate.invite.role || 'write'
+    if (candidate.invite.expired) throw CeroError.EXPIRED()
+    role = role || candidate.invite.role || 'member'
+    if (candidate.invite.role && !grants(candidate.invite.role, role)) {
+      throw CeroError.INVALID(`role '${role}' exceeds the invite role '${candidate.invite.role}'`)
+    }
 
     await candidate.confirm({ key: this.store.key, encryptionKey: this.store.encryptionKey })
 
@@ -320,12 +418,12 @@ export class Handle extends ReadyResource {
       updatedAt: ts
     }
 
-    if (role === 'read') {
+    if (role === 'reader') {
       await this.store.call('add-member', member)
       return
     }
 
-    const sig = this.identity.sign(writerKey)
+    const sig = this.identity.sign(b4a.concat([writerKey, this.store.writerKey]))
     await this.store.tx(async () => {
       await this.store.call('add-writer', {
         sig,
@@ -368,42 +466,49 @@ export class Handle extends ReadyResource {
         keyPair: writer
       })
     )
-    await child.ready()
-    child.name = name
+    // a failure after the child opens must close it — else it leaks its Database,
+    // swarm session and attached bee, never reaped by the parent (not yet a child)
+    try {
+      await child.ready()
+      child.name = name
 
-    const id = toId(child.store.key)
-    await this._saveKeyPair(id, writer)
+      const id = toId(child.store.key)
+      await this._saveKeyPair(id, writer)
 
-    const ts = Date.now()
-    const writerKey = child.store.writerKey
-    await child.store.call('add-writer', {
-      master: this.identity.publicKey,
-      writer: writerKey,
-      sig: this.identity.sign(writerKey)
-    })
-    await child.store.call('add-member', {
-      id: this.identity.id,
-      key: writerKey,
-      role: 'owner',
-      name: null,
-      createdAt: ts,
-      updatedAt: ts
-    })
-    await this.store.call('add-handle', {
-      id,
-      type,
-      key: child.store.key,
-      encryptionKey: child.store.encryptionKey,
-      name,
-      createdAt: ts,
-      updatedAt: ts
-    })
+      const ts = Date.now()
+      const writerKey = child.store.writerKey
+      await child.store.call('add-writer', {
+        master: this.identity.publicKey,
+        writer: writerKey,
+        sig: this.identity.sign(b4a.concat([writerKey, child.store.writerKey]))
+      })
+      await child.store.call('add-member', {
+        id: this.identity.id,
+        key: writerKey,
+        role: 'owner',
+        name: null,
+        createdAt: ts,
+        updatedAt: ts
+      })
+      await this.store.call('add-handle', {
+        id,
+        type,
+        key: child.store.key,
+        encryptionKey: child.store.encryptionKey,
+        name,
+        createdAt: ts,
+        updatedAt: ts
+      })
 
-    if (accept !== false) this._wireAccept(child, { role })
-    bind(child, type)
-    this.children.add(child)
-    this.emit('handle', child, { name, role })
-    return child
+      if (accept !== false) this._wireAccept(child, { role })
+      bind(child, type)
+      this.children.add(child)
+      this.emit('handle', child, { name, role })
+      return child
+    } catch (err) {
+      await child.close().catch(safetyCatch)
+      throw err
+    }
   }
 
   /**
@@ -439,27 +544,34 @@ export class Handle extends ReadyResource {
         timeout
       })
     )
-    await child.ready()
-    if (!child.store.writable) await child.store.whenWritable({ timeout: deadline })
-
-    const id = toId(child.store.key)
-    await this._saveKeyPair(id, child.store.keyPair)
-
-    const ts = Date.now()
-    await this.store.call('add-handle', {
-      id,
-      type,
-      key: child.store.key,
-      encryptionKey: child.store.encryptionKey,
-      name: null,
-      createdAt: ts,
-      updatedAt: ts
-    })
-    this._wireAccept(child)
-    bind(child, type)
-    this.children.add(child)
-    this.emit('handle', child, {})
-    return child
+    // whenWritable timing out (host offline) is a normal failure — close the
+    // fully-opened child rather than leak its Database/pairing/swarm session
+    try {
+      await child.ready()
+      if (!child.store.writable) await child.store.whenWritable({ timeout: deadline })
+
+      const id = toId(child.store.key)
+      await this._saveKeyPair(id, child.store.keyPair)
+
+      const ts = Date.now()
+      await this.store.call('add-handle', {
+        id,
+        type,
+        key: child.store.key,
+        encryptionKey: child.store.encryptionKey,
+        name: null,
+        createdAt: ts,
+        updatedAt: ts
+      })
+      this._wireAccept(child)
+      bind(child, type)
+      this.children.add(child)
+      this.emit('handle', child, {})
+      return child
+    } catch (err) {
+      await child.close().catch(safetyCatch)
+      throw err
+    }
   }
 
   /**
@@ -511,10 +623,7 @@ export class Handle extends ReadyResource {
     })
     await child.ready()
     if (firstTime && !child.store.writable) {
-      await child.store.claim({
-        name: this._opts.name || null,
-        isMobile: this._opts.isMobile === true
-      })
+      await child.store.claim()
     }
     if (firstTime) {
       await this._saveKeyPair(id, writer)

package/src/index.js

@@ -1,5 +1,6 @@
 import HypercoreStorage from 'hypercore-storage'
 import Corestore from 'corestore'
+import safetyCatch from 'safety-catch'
 import fs from 'fs'
 
 import { Identity } from '@cero-base/core/identity'
@@ -20,9 +21,9 @@ import {
   before,
   after,
   bind,
-  define,
-  peek
+  define
 } 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'
@@ -40,11 +41,15 @@ export {
   before,
   after,
   bind,
-  define,
-  peek
+  define
 } from './lib/operators.js'
+export { peek } from './lib/peek.js'
 export { t, schema } from './lib/spec.js'
 
+/**
+ * @typedef {import('./handle/index.js').CeroHandle} CeroHandle
+ */
+
 /**
  * @typedef {object} CeroOpts
  * @property {Identity} [identity]                     Pre-resolved identity. If absent, derived from `seed`/`phrase` or generated.
@@ -54,6 +59,7 @@ export { t, schema } from './lib/spec.js'
  * @property {string | null} [name]                    Friendly device name persisted on the identity claim.
  * @property {boolean} [isMobile]                      Marks this device as mobile.
  * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap nodes.
+ * @property {string} [channel]                        Optional network-isolation label; only same-channel peers connect.
  * @property {Uint8Array} [key]                        Pre-existing database key (skip bootstrap).
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
@@ -70,87 +76,112 @@ export { t, schema } from './lib/spec.js'
  * @param {string} dir       Data directory.
  * @param {any} spec         Built spec — output of `cero/build`.
  * @param {CeroOpts} [opts]
- * @returns {Promise<Handle>}
+ * @returns {Promise<CeroHandle>}
  */
 export async function cero(dir, spec, opts = {}) {
   if (typeof dir !== 'string' || !dir) throw CeroError.INVALID('dir must be a non-empty string')
   if (!spec) throw CeroError.REQUIRED('spec')
 
   const storage = new HypercoreStorage(`${dir}/main`)
-  await storage.ready()
-  const store = new Corestore(storage, { manifestVersion: 2 })
-  await store.ready()
-
+  let store = null
   let local = null
-  if (spec.local && spec.meta?.local) {
-    local = new Local(null, spec, { store })
-    await local.ready()
-  }
+  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.
+  try {
+    await storage.ready()
+    store = new Corestore(storage, { manifestVersion: 2 })
+    await store.ready()
 
-  const identity = await resolveIdentity(opts, local)
-  const writer = local ? (await local.store.get('keypair')).data : null
-
-  const network = new Network({ bootstrap: opts.bootstrap })
-  await network.ready()
-  const discovery = network.join(identity.topic)
-  await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, FLUSH))])
-
-  const me = new Handle({
-    storage,
-    store,
-    local,
-    discovery,
-    identity,
-    network,
-    spec,
-    opts,
-    dir,
-    routes: opts.routes,
-    key: opts.key,
-    encryptionKey: opts.encryptionKey,
-    keyPair: writer ? { publicKey: writer.publicKey, secretKey: writer.secretKey } : undefined,
-    pair: false
-  })
-  await me.ready()
+    if (spec.local && spec.meta?.local) {
+      local = new Local(null, spec, { store })
+      await local.ready()
+    }
 
-  if (!writer && me.store.length === 0 && (!opts.key || opts.recovery)) {
-    const result = await me.bootstrap({
-      name: opts.name || null,
-      isMobile: opts.isMobile === true,
-      recovering: opts.recovery === true
-    })
-    if (local && result?.writer) {
-      await local.store.set('keypair', {
-        publicKey: result.writer.publicKey,
-        secretKey: result.writer.secretKey
-      })
+    const identity = await resolveIdentity(opts, local)
+    const writer = local ? (await local.store.get('keypair')).data : null
+
+    // Channel stamp: a storage remembers its channel; reopening it under a different channel is a
+    // misconfiguration that could leak data across networks, so reject it. Only when a channel is
+    // set (no channel = global, no stamp, unchanged).
+    if (local && opts.channel) {
+      const stored = (await local.store.get('environment')).data?.channel
+      if (stored == null) await local.store.set('environment', { channel: opts.channel })
+      else if (stored !== opts.channel) throw CeroError.CHANNEL_MISMATCH()
     }
-    if (!opts.recovery) {
-      const ts = Date.now()
-      await me.store.call('add-member', {
-        id: identity.id,
-        key: me.store.writerKey,
-        role: 'owner',
+
+    network = new Network({ bootstrap: opts.bootstrap, channel: opts.channel })
+    await network.ready()
+    discovery = network.join(identity.topic)
+    await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, FLUSH))])
+
+    me = new Handle({
+      storage,
+      store,
+      local,
+      discovery,
+      identity,
+      network,
+      spec,
+      opts,
+      dir,
+      routes: opts.routes,
+      key: opts.key,
+      encryptionKey: opts.encryptionKey,
+      keyPair: writer ? { publicKey: writer.publicKey, secretKey: writer.secretKey } : undefined,
+      pair: false
+    })
+    await me.ready()
+
+    if (!writer && me.store.length === 0 && (!opts.key || opts.recovery)) {
+      const result = await me.bootstrap({
         name: opts.name || null,
-        createdAt: ts,
-        updatedAt: ts
+        isMobile: opts.isMobile === true,
+        recovering: opts.recovery === true
       })
+      if (local && result?.writer) {
+        await local.store.set('keypair', {
+          publicKey: result.writer.publicKey,
+          secretKey: result.writer.secretKey
+        })
+      }
+      if (!opts.recovery) {
+        const ts = Date.now()
+        await me.store.call('add-member', {
+          id: identity.id,
+          key: me.store.writerKey,
+          role: 'owner',
+          name: opts.name || null,
+          createdAt: ts,
+          updatedAt: ts
+        })
+      }
     }
-  }
-  if (opts.recovery) await me.recover({ timeout: opts.recoveryTimeout })
+    if (opts.recovery) await me.recover({ timeout: opts.recoveryTimeout })
 
-  try {
     for (const ext of internal.extensions) {
       const off = await ext.setup?.(me)
       if (typeof off === 'function') me.once('close', off)
     }
+
+    bind(me, null)
+    return me
   } catch (err) {
-    await me.close().catch(() => {}) // a failed setup must not leak the half-built instance
+    // once the root Handle exists it owns (and closes) everything; before that,
+    // tear the raw resources down in reverse order.
+    if (me) await me.close().catch(safetyCatch)
+    else {
+      await discovery?.destroy().catch(safetyCatch)
+      await network?.close().catch(safetyCatch)
+      await local?.close().catch(safetyCatch)
+      await store?.close().catch(safetyCatch)
+      await storage.close().catch(safetyCatch)
+    }
     throw err
   }
-
-  bind(me, null)
-  return me
 }
 
 /**

package/src/lib/constants.js

@@ -16,5 +16,6 @@ export const DB_TYPE = {
   bytes: 'buffer',
   json: 'json',
   fixed32: 'fixed32',
-  fixed64: 'fixed64'
+  fixed64: 'fixed64',
+  file: 'string'
 }