@cero-base/cero 0.4.0

package/src/handle/index.js

@@ -0,0 +1,600 @@
+import b4a from 'b4a'
+import Hypercore from 'hypercore'
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+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 { CeroError } from '@cero-base/core/errors'
+
+import { attachRefs } from '../lib/utils.js'
+
+export { Ref } from '../lib/utils.js'
+
+/**
+ * @typedef {import('@cero-base/core/network').Network} Network
+ * @typedef {import('../local/index.js').Local} Local
+ * @typedef {import('@cero-base/core/identity').KeyPair} KeyPair
+ *
+ * @typedef {object} HandleOpts
+ * @property {Handle} [parent]                 Parent handle when this is a child slot.
+ * @property {Identity} [identity]             Long-lived user identity. Inherited from `parent` if omitted.
+ * @property {Network} [network]               Shared swarm. Inherited from `parent` if omitted.
+ * @property {any} [store]                     Pre-existing Corestore. Falls back to `parent.store.store`.
+ * @property {any} [spec]                      Built cero spec.
+ * @property {Local} [local]                   Local store for per-handle keypairs.
+ * @property {any} [storage]                   Owned HypercoreStorage to close on shutdown.
+ * @property {any} [discovery]                 Owned identity Discovery to destroy on shutdown.
+ * @property {string} [dir]                    Data directory (root handles only).
+ * @property {any} [opts]                      Pass-through cero(...) options.
+ * @property {Record<string, Function>} [routes]
+ * @property {Uint8Array} [key]                Existing database key.
+ * @property {Uint8Array} [encryptionKey]      Existing encryption key.
+ * @property {string} [namespace]              Corestore namespace.
+ * @property {KeyPair} [keyPair]               Writer keypair.
+ * @property {boolean} [pair]                  When `false`, skips creating a `Pairing` session.
+ *
+ * @typedef {object} CreateChildOpts
+ * @property {string | null} [name]
+ * @property {Record<string, Function>} [routes]
+ * @property {string} [role]
+ * @property {boolean} [accept]
+ *
+ * @typedef {object} JoinChildOpts
+ * @property {Record<string, Function>} [routes]
+ * @property {number} [timeout]
+ *
+ * @typedef {object} StaticJoinOpts
+ * @property {Handle} [parent]
+ * @property {Network} [network]
+ * @property {Identity} [identity]
+ * @property {any} [store]
+ * @property {any} [spec]
+ * @property {string} [namespace]
+ * @property {Record<string, Function>} [routes]
+ * @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 | null} [name]
+ *
+ * @typedef {object} RecoverOpts
+ * @property {number} [timeout]
+ * @property {string | null} [name]
+ * @property {boolean} [isMobile]
+ *
+ * @typedef {object} HandleExtra
+ * @property {string | null} [name]                       Display name; set on child handles by the owner flow.
+ * @property {import('../lib/utils.js').Ref} [profile]    `profile` ref, attached dynamically when the schema declares one.
+ * @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.
+ */
+
+/**
+ * A cero handle — a single writable database session attached to a swarm.
+ * The "root" handle is the user's facade; child handles (created via
+ * `_create`/`_join`/`_load`) live under it and share the same identity,
+ * network and corestore. Ref properties (`profile`, `members`, ...) are
+ * attached dynamically per the schema; child handles also carry a `name`.
+ */
+export class Handle extends ReadyResource {
+  /** @param {HandleOpts} [opts] */
+  constructor(opts = {}) {
+    super()
+
+    const { parent = null } = opts
+    const identity = opts.identity || parent?.identity
+    const network = opts.network || parent?.network
+    const store = opts.store || parent?.store?.store
+    const spec = opts.spec
+
+    if (!identity) throw CeroError.REQUIRED('identity')
+    if (!network) throw CeroError.REQUIRED('network')
+    if (!store) throw CeroError.REQUIRED('store')
+    if (!spec) throw CeroError.REQUIRED('spec')
+
+    this.identity = identity
+    this.network = network
+    this.spec = spec
+    this.parent = parent
+
+    this.local = opts.local || null
+    this._storage = opts.storage || null
+    this._discovery = opts.discovery || null
+    this._dir = opts.dir || null
+    this._opts = opts.opts || {}
+    this._onerror = this._opts.onerror || safetyCatch
+    this.children = parent ? null : new Set()
+
+    this.store = new Database({
+      store: store,
+      identity,
+      network,
+      spec,
+      routes: opts.routes,
+      key: opts.key,
+      encryptionKey: opts.encryptionKey,
+      namespace: opts.namespace,
+      keyPair: opts.keyPair
+    })
+    this.pair = null
+    this._wantsPair = opts.pair !== false
+  }
+
+  async _open() {
+    await this.store.ready()
+    if (this._wantsPair) {
+      this.pair = new Pairing({
+        network: this.network,
+        identity: this.identity,
+        topic: this.store.key
+      })
+      await this.pair.ready()
+    }
+    attachRefs(this, this.store.refs)
+    if (!this.children) return
+
+    this._offUpdate = this.store.onUpdate(() => {
+      if (this.closing || this.closed) return
+      for (const c of this.children) this._syncMember(c).catch(this._onerror)
+    })
+  }
+
+  async _close() {
+    this._offUpdate?.()
+    if (this.children) {
+      for (const c of [...this.children]) await c.close()
+      this.children.clear()
+    }
+    if (this.pair) await this.pair.close()
+
+    if (this.parent) {
+      this.parent.children?.delete(this)
+      await this.store.close()
+      return
+    }
+
+    if (this.local) await this.local.close()
+    const store = this.store.store
+    await this.store.close()
+    if (this._discovery) await this._discovery.destroy()
+    await this.network.close()
+    await store.close()
+    if (this._storage) await this._storage.close()
+  }
+
+  /** Canonical id — identity id for the root handle, store key for children. */
+  get id() {
+    if (!this.parent) return this.identity.id
+    return this.store?.key ? toId(this.store.key) : null
+  }
+
+  /** This device's id + name. `null` on child handles. */
+  get device() {
+    if (this.parent) return null
+    const k = this.store?.writerKey
+    return k ? { id: toId(k), name: this._opts.name || null } : null
+  }
+
+  get suspended() {
+    return this._suspended === true
+  }
+
+  /**
+   * Initialise a fresh database: write the genesis claim, derive the writer.
+   * Forwards to `Database.bootstrap`.
+   *
+   * @param {any} [opts]
+   * @returns {Promise<any>}
+   */
+  bootstrap(opts) {
+    return this.store.bootstrap(opts)
+  }
+
+  /**
+   * 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 + wait until this peer becomes a writer + bring the bee up to date.
+   * Used by `restore()` after wiping local state.
+   *
+   * @param {RecoverOpts} [opts]
+   * @returns {Promise<void>}
+   */
+  async recover({ timeout = 30000, name = null, isMobile = false } = {}) {
+    if (this.store.writable) return
+    await this.store.claim({ name, isMobile })
+    await this.store.whenWritable({ timeout })
+    await this.store.bee.update()
+  }
+
+  /**
+   * Mint a pairing invite for this handle.
+   *
+   * @param {{ role?: string, expiresIn?: number, data?: any }} [opts]
+   * @returns {Promise<string>}  Z32-encoded invite string.
+   */
+  invite(opts) {
+    return this.pair.createInvite(opts)
+  }
+
+  /**
+   * Revoke a previously-minted invite by its string form.
+   *
+   * @param {string} invite
+   * @returns {boolean}  `true` if the invite was found and removed.
+   */
+  revoke(invite) {
+    return this.pair.revoke(invite)
+  }
+
+  /**
+   * Accept a paired candidate — adds them as a writer (or read-only member)
+   * and confirms the pairing so they receive this handle's keys.
+   *
+   * @param {any} candidate
+   * @param {AcceptOpts} [opts]
+   * @returns {Promise<void>}
+   */
+  async accept(candidate, { role, name } = {}) {
+    const data = candidate.userData
+    if (!b4a.isBuffer(data) || data.length !== 64) {
+      throw CeroError.INVALID(
+        'candidate userData must be a 64-byte buffer (identity + writer pubkey)'
+      )
+    }
+    role = role || candidate.invite.role || 'write'
+
+    await candidate.confirm({ key: this.store.key, encryptionKey: this.store.encryptionKey })
+
+    const ts = Date.now()
+    const writerKey = Hypercore.key({ version: 2, signers: [{ publicKey: data.subarray(32, 64) }] })
+    const member = {
+      id: toId(data.subarray(0, 32)),
+      key: writerKey,
+      role,
+      name: name || null,
+      createdAt: ts,
+      updatedAt: ts
+    }
+
+    if (role === 'read') {
+      await this.store.call('add-member', member)
+      return
+    }
+
+    const sig = this.identity.sign(writerKey)
+    await this.store.tx(async () => {
+      await this.store.call('add-writer', {
+        sig,
+        master: this.identity.publicKey,
+        writer: writerKey,
+        name: name || null,
+        isMobile: false
+      })
+      await this.store.call('add-member', member)
+    })
+  }
+
+  /**
+   * Leave a child handle — removes it from the parent's `handles` collection
+   * and closes the session. No-op on root handles.
+   *
+   * @returns {Promise<void>}
+   */
+  async leave() {
+    if (!this.parent) return
+    await this.parent.store.call('del-handle', { id: toId(this.store.key) })
+    await this.close()
+  }
+
+  /**
+   * Create a new child handle of `type`. Owner-flow — generates a fresh
+   * writer, adds it as a writer + member, and registers the child on the
+   * parent's `handles` collection.
+   *
+   * @param {string} type
+   * @param {CreateChildOpts} [opts]
+   * @returns {Promise<Handle>}
+   */
+  async _create(type, { name = null, routes, role, accept } = {}) {
+    const writer = Identity.randomKeyPair()
+    const child = /** @type {Child} */ (
+      new Handle({
+        parent: this,
+        spec: pickHandle(this.spec, type),
+        namespace: `cero/handle/${type}/${writer.id}`,
+        routes,
+        keyPair: writer
+      })
+    )
+    await child.ready()
+    child.name = name
+
+    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),
+      name,
+      isMobile: false
+    })
+    await child.store.call('add-member', {
+      id: this.identity.id,
+      key: writerKey,
+      role: 'owner',
+      name: null,
+      createdAt: ts,
+      updatedAt: ts
+    })
+    if (name && child.profile) await child.store.set('profile', { name })
+    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 })
+    this.children.add(child)
+    await this._syncMember(child)
+    return child
+  }
+
+  /**
+   * Join a child handle by invite (joiner-flow). Waits for writer
+   * capability and registers the child on the parent's `handles`
+   * collection.
+   *
+   * @param {string} invite
+   * @param {string} type
+   * @param {JoinChildOpts} [opts]
+   * @returns {Promise<Handle>}
+   */
+  async _join(invite, type, { routes, timeout } = {}) {
+    const deadline = timeout || 30000
+    const child = /** @type {Child} */ (
+      await Handle.join(invite, {
+        parent: this,
+        spec: pickHandle(this.spec, type),
+        namespace: `cero/handle/${type}/${randomNs()}`,
+        routes,
+        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 name = child.profile ? await waitForProfileName(child, deadline) : null
+    const ts = Date.now()
+    await this.store.call('add-handle', {
+      id,
+      type,
+      key: child.store.key,
+      encryptionKey: child.store.encryptionKey,
+      name,
+      createdAt: ts,
+      updatedAt: ts
+    })
+    this._wireAccept(child)
+    this.children.add(child)
+    await this._syncMember(child)
+    return child
+  }
+
+  /**
+   * Re-open an existing child handle by id. Reuses the stored writer
+   * keypair if available; otherwise generates a fresh one and claims
+   * writer capability.
+   *
+   * @param {string} type
+   * @param {string} id
+   * @returns {Promise<Handle>}
+   */
+  async _load(type, id) {
+    for (const c of this.children) if (c.id === id) return c
+    const { data } = await this.store.get('handles', id)
+    if (!data) throw CeroError.UNKNOWN('handle', id)
+    if (data.type !== type) throw new Error(`handle ${id} is type ${data.type}, not ${type}`)
+    let writer = await this._loadKeyPair(id)
+    const firstTime = !writer
+    if (firstTime) {
+      writer = Identity.randomKeyPair()
+    }
+    const child = new Handle({
+      parent: this,
+      spec: pickHandle(this.spec, type),
+      namespace: `cero/handle/${type}/${id}`,
+      key: data.key,
+      encryptionKey: data.encryptionKey,
+      keyPair: /** @type {KeyPair} */ (writer)
+    })
+    await child.ready()
+    if (firstTime && !child.store.writable) {
+      await child.store.claim({
+        name: this._opts.name || null,
+        isMobile: this._opts.isMobile === true
+      })
+    }
+    if (firstTime) {
+      await this._saveKeyPair(id, writer)
+    }
+    this._wireAccept(child)
+    this.children.add(child)
+    return child
+  }
+
+  /**
+   * Pause networking + storage. Idempotent; no-op on child handles.
+   *
+   * @returns {Promise<void>}
+   */
+  async suspend() {
+    if (this.parent || this.closing || this.closed || this._suspended) return
+    this._suspended = true
+    for (const c of this.children) if (c.pair) await c.pair.suspend()
+    await this.network.suspend()
+    try {
+      await this.store.store.suspend()
+    } catch (err) {
+      this._onerror(err)
+    }
+  }
+
+  /**
+   * Resume a suspended root handle. Idempotent; no-op on child handles.
+   *
+   * @returns {Promise<void>}
+   */
+  async resume() {
+    if (this.parent || this.closing || this.closed || !this._suspended) return
+    this._suspended = false
+    try {
+      await this.store.store.resume()
+    } catch (err) {
+      this._onerror(err)
+    }
+    await this.network.resume()
+    await Promise.all([...this.children].map((child) => child.pair?.resume()))
+  }
+
+  /**
+   * Pair into an existing handle via an invite, returning a brand-new
+   * `Handle` already configured with the resolved key + encryption key.
+   *
+   * @param {string} invite
+   * @param {StaticJoinOpts} [opts]
+   * @returns {Promise<Handle>}
+   */
+  static async join(
+    invite,
+    { parent, network, identity, store, spec, namespace, routes, timeout = 30000 } = {}
+  ) {
+    const net = network || parent?.network
+    const id = identity || parent?.identity
+    if (!net) throw new TypeError('network is required')
+    if (!id) throw new TypeError('identity is required')
+    if (!store && !parent) throw new TypeError('store is required')
+    if (!spec) throw new TypeError('spec is required')
+
+    const writer = Identity.randomKeyPair()
+    const pair = new Pairing({ network: net, identity: id })
+    await pair.ready()
+
+    let key, encryptionKey
+    try {
+      const userData = b4a.concat([id.publicKey, writer.publicKey])
+      ;({ key, encryptionKey } = await pair.join(invite, { userData, timeout }))
+    } finally {
+      await pair.close()
+    }
+
+    return new Handle({
+      parent,
+      store,
+      identity: id,
+      network: net,
+      spec,
+      namespace,
+      routes,
+      key,
+      encryptionKey,
+      keyPair: writer
+    })
+  }
+
+  async _syncMember(child) {
+    if (!child.store.writable) return
+    const { data: profile } = await this.store.get('profile')
+    if (!profile) return
+    const { data: existing } = await child.store.get('members', this.identity.id)
+    if (!existing) return
+    await child.store.call('set-member', {
+      ...existing,
+      ...profile,
+      id: existing.id,
+      updatedAt: Date.now()
+    })
+  }
+
+  /**
+   * @param {Handle} child
+   * @param {{ role?: string }} [opts]
+   */
+  _wireAccept(child, { role } = {}) {
+    child.pair.on('candidate', (cand) => {
+      if (this.closing || this.closed || child.closing || child.closed) return
+      child.accept(cand, { role }).catch(this._onerror)
+    })
+  }
+
+  /**
+   * @param {string} id
+   * @param {KeyPair | { publicKey: Uint8Array, secretKey: Uint8Array } | null} keyPair
+   * @returns {Promise<void>}
+   */
+  async _saveKeyPair(id, keyPair) {
+    if (!this.local || !keyPair) return
+    await this.local.store.put('handle-keypairs', {
+      id,
+      publicKey: keyPair.publicKey,
+      secretKey: keyPair.secretKey
+    })
+  }
+
+  /**
+   * @param {string} id
+   * @returns {Promise<{ publicKey: Uint8Array, secretKey: Uint8Array } | null>}
+   */
+  async _loadKeyPair(id) {
+    if (!this.local) return null
+    const { data } = await this.local.store.get('handle-keypairs', id)
+    if (!data) return null
+    return {
+      publicKey: data.publicKey,
+      secretKey: data.secretKey
+    }
+  }
+}
+
+function pickHandle(spec, type) {
+  const h = spec.handles?.[type]
+  if (!h) throw CeroError.UNKNOWN('handle type', type)
+  return h
+}
+
+function randomNs() {
+  return z32.encode(Identity.randomBytes(8))
+}
+
+async function waitForProfileName(child, timeout) {
+  const deadline = Date.now() + timeout
+  while (Date.now() < deadline) {
+    const { data } = await child.store.get('profile')
+    if (data?.name) return data.name
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  return null
+}