@cero-base/cero 1.19.0 → 2.0.0

package/src/handle/index.js

@@ -87,10 +87,6 @@ export { Ref } from '../lib/refs.js'
 
 /**
  * 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] */
@@ -150,6 +146,78 @@ export class Handle extends ReadyResource {
     this._wantsPair = opts.pair !== false
   }
 
+  /**
+   * An `AbortSignal` that fires when this handle closes.
+   *
+   * @returns {AbortSignal}
+   */
+  get signal() {
+    if (!this._ac) {
+      this._ac = new AbortController()
+      if (this.closed) this._ac.abort()
+      else this.once('close', () => this._ac.abort())
+    }
+    return this._ac.signal
+  }
+
+  /** 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
+  }
+
+  /**
+   * Lazily-built blob store for THIS handle's writing device, at the current rotation epoch.
+   *
+   * @returns {Blobs}
+   */
+  get blobs() {
+    const stamp = this.store.keyring.current
+    if (!stamp) return this._baseBlobs()
+    let blobs = this._epochBlobs?.get(stamp)
+    if (!blobs) {
+      const entropy = this.store.keyring.entropy(stamp)
+      blobs = this._makeBlobs(`blobs-${stamp}`, blobEpochKey(entropy), stamp)
+      ;(this._epochBlobs ??= new Map()).set(stamp, blobs)
+    }
+    return blobs
+  }
+
+  /** 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 ? hid.encode(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: hid.encode(k), name: this._opts.name || null } : null
+  }
+
+  get suspended() {
+    return this._sus?.suspended === true
+  }
+
   async _open() {
     await this.store.ready()
     if (this._wantsPair) {
@@ -163,8 +231,7 @@ export class Handle extends ReadyResource {
         }
       })
       await this.pair.ready()
-      // serve invites persisted by any member, and keep the set in step as rows
-      // replicate in or disappear (minted, revoked or consumed elsewhere)
+      // serve invites persisted by any member, in step with the rows
       await this._syncInvites().catch(safetyCatch)
       this._invitesSync = () => this._syncInvites().catch(safetyCatch)
       this.store.on('update', this._invitesSync)
@@ -216,9 +283,9 @@ export class Handle extends ReadyResource {
   }
 
   /**
-   * Tie a destroyable resource (a `watch` stream, a timer, any `{ destroy }`)
-   * to this handle's lifecycle — it's destroyed automatically on close, so
-   * callers don't track cleanup. De-registers itself if destroyed earlier.
+   * Tie a destroyable resource (a `watch` stream, a timer, any `{ destroy }`) to this
+   * handle's lifecycle — it's destroyed automatically on close, so callers don't track
+   * cleanup.
    *
    * @template {{ destroy?: Function, once?: Function }} T
    * @param {T} resource
@@ -234,22 +301,6 @@ export class Handle extends ReadyResource {
     return resource
   }
 
-  /**
-   * An `AbortSignal` that fires when this handle closes. Pass it as
-   * `{ signal }` to `on`/`after`/`before`/`watch` to drop a subscription on
-   * close — or use your own `AbortController` for a finer scope.
-   *
-   * @returns {AbortSignal}
-   */
-  get signal() {
-    if (!this._ac) {
-      this._ac = new AbortController()
-      if (this.closed) this._ac.abort()
-      else this.once('close', () => this._ac.abort())
-    }
-    return this._ac.signal
-  }
-
   /**
    * `EventEmitter.on` plus an optional `{ signal }` that removes the listener
    * when the signal aborts — e.g. `me.on('handle', fn, { signal: me.signal })`.
@@ -265,42 +316,6 @@ 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.
@@ -312,112 +327,6 @@ export class Handle extends ReadyResource {
     return this.root.fileServer.getLink(id)
   }
 
-  /**
-   * Lazily-built blob store for THIS handle's writing device, at the current
-   * rotation epoch. One core per writer per epoch that writes files: the base
-   * era uses the handle's encryptionKey, rotated epochs use a key derived
-   * from the epoch entropy — so a removed member cannot decrypt files added
-   * after the rotation. Instances carry `.stamp` so the file row records
-   * which era its core belongs to.
-   *
-   * @returns {Blobs}
-   */
-  get blobs() {
-    const stamp = this.store.keyring.current
-    if (!stamp) return this._baseBlobs()
-    let blobs = this._epochBlobs?.get(stamp)
-    if (!blobs) {
-      const entropy = this.store.keyring.entropy(stamp)
-      blobs = this._makeBlobs(`blobs-${stamp}`, blobEpochKey(entropy), stamp)
-      ;(this._epochBlobs ??= new Map()).set(stamp, blobs)
-    }
-    return blobs
-  }
-
-  _baseBlobs() {
-    if (!this._blobs) this._blobs = this._makeBlobs('blobs', this.store.encryptionKey, 0)
-    return this._blobs
-  }
-
-  _makeBlobs(name, encryptionKey, stamp) {
-    const blobs = new Blobs({
-      store: this.store.store,
-      network: this.network,
-      encryptionKey,
-      name
-    })
-    blobs.stamp = stamp
-    blobs
-      .ready()
-      .then(() => {
-        // close prunes _coreKeys first, a late ready() must not re-insert the entry
-        if (this.closing || this.closed || !blobs.key) return
-        this.root._coreKeys.set(b4a.toString(blobs.key, 'hex'), encryptionKey)
-      })
-      .catch(this._onerror)
-    return blobs
-  }
-
-  /**
-   * Remember the blob-core key a file id points at so the file server can
-   * open the core. Lives on the Handle (not the shared operators) because the
-   * epoch-key derivation pulls native crypto — the RPC client must stay
-   * bundleable without it.
-   *
-   * @param {string} id
-   * @param {number} [stamp]
-   */
-  _registerBlobCore(id, stamp) {
-    if (!id || !this.root?._coreKeys) return
-    try {
-      const { coreKey } = decodeId(id)
-      const hex = b4a.toString(coreKey, 'hex')
-      if (!this.root._coreKeys.has(hex)) {
-        // no stamp on a file-field value, look it up (fire-and-forget, idempotent)
-        if (stamp === undefined) {
-          this.store
-            .get('files', id)
-            .then(({ data }) => {
-              if (data && !this.closing && !this.closed) this._registerBlobCore(id, data.stamp || 0)
-            })
-            .catch(safetyCatch)
-          return
-        }
-        const key = this._blobCoreKey(stamp)
-        if (!key) return // unknown epoch — this device is not entitled to the core
-        this.root._coreKeys.set(hex, key)
-      }
-      // remember which handle read it, so close prunes the entry
-      if (this !== this.root) (this._blobKeys ??= new Set()).add(hex)
-    } catch {
-      // ignore invalid ids
-    }
-  }
-
-  // base-era cores use the OWNING handle's key, rooms have their own
-  _blobCoreKey(stamp) {
-    if (!stamp) return this.store.encryptionKey
-    const entropy = this.store.keyring.entropy(stamp)
-    return entropy ? blobEpochKey(entropy) : null
-  }
-
-  /** 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 ? hid.encode(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: hid.encode(k), name: this._opts.name || null } : null
-  }
-
-  get suspended() {
-    return this._sus?.suspended === true
-  }
-
   /**
    * Initialise a fresh database: write the genesis claim, derive the writer.
    * Forwards to `Database.bootstrap`.
@@ -440,9 +349,9 @@ export class Handle extends ReadyResource {
   }
 
   /**
-   * Flip this handle's swarm announce mode — `setActive(false)` demotes an
-   * idle/background room to server-only (still reachable, stops searching);
-   * `setActive(true)` promotes it back on focus. Cheap, safe to call often.
+   * Flip this handle's swarm announce mode — `setActive(false)` demotes an idle/background
+   * room to server-only (still reachable, stops searching); `setActive(true)` promotes it
+   * back on focus.
    *
    * @param {boolean} active
    * @returns {Promise<void>}
@@ -485,12 +394,6 @@ export class Handle extends ReadyResource {
     return str
   }
 
-  async _syncInvites() {
-    if (!this.pair) return
-    const { data } = await this.store.get('invites')
-    this.pair.syncRows(data || [])
-  }
-
   /**
    * Revoke a previously-minted invite by its string form.
    *
@@ -538,10 +441,8 @@ export class Handle extends ReadyResource {
       throw CeroError.INVALID(`role '${role}' is not a rank (owner, admin, member, reader)`)
     }
 
-    // confirm must answer within the pairing request's lifetime, any await before
-    // it (even ~100ms) drops the response. So the key is revealed before the
-    // membership writes land, and a failure there is recoverable by re-pairing.
-    // Epoch secrets ride along so a post-rotation joiner reads full history.
+    // confirm must answer within the request's lifetime, so the key goes out before the membership
+    // writes land; epoch secrets ride along so a post-rotation joiner reads full history
     const epochs = this.store.keyring.all()
     await candidate.confirm({
       key: this.store.key,
@@ -579,6 +480,118 @@ export class Handle extends ReadyResource {
     })
   }
 
+  /**
+   * 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: hid.encode(this.store.key) })
+    await this.close()
+  }
+
+  /**
+   * Pause networking + storage. Idempotent; no-op on child handles.
+   *
+   * @returns {Promise<void>}
+   */
+  async suspend() {
+    if (this._sus) await this._sus.suspend()
+  }
+
+  /**
+   * Resume a suspended root handle. Idempotent; no-op on child handles.
+   *
+   * @returns {Promise<void>}
+   */
+  async resume() {
+    if (this._sus) await this._sus.resume()
+  }
+
+  /**
+   * @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
+  }
+
+  _baseBlobs() {
+    if (!this._blobs) this._blobs = this._makeBlobs('blobs', this.store.encryptionKey, 0)
+    return this._blobs
+  }
+
+  _makeBlobs(name, encryptionKey, stamp) {
+    const blobs = new Blobs({
+      store: this.store.store,
+      network: this.network,
+      encryptionKey,
+      name
+    })
+    blobs.stamp = stamp
+    blobs
+      .ready()
+      .then(() => {
+        // close prunes _coreKeys first, a late ready() must not re-insert the entry
+        if (this.closing || this.closed || !blobs.key) return
+        this.root._coreKeys.set(b4a.toString(blobs.key, 'hex'), encryptionKey)
+      })
+      .catch(this._onerror)
+    return blobs
+  }
+
+  /**
+   * Remember the blob-core key a file id points at so the file server can open the core.
+   *
+   * @param {string} id
+   * @param {number} [stamp]
+   */
+  _registerBlobCore(id, stamp) {
+    if (!id || !this.root?._coreKeys) return
+    try {
+      const { coreKey } = decodeId(id)
+      const hex = b4a.toString(coreKey, 'hex')
+      if (!this.root._coreKeys.has(hex)) {
+        // no stamp on a file-field value, look it up (fire-and-forget, idempotent)
+        if (stamp === undefined) {
+          this.store
+            .get('files', id)
+            .then(({ data }) => {
+              if (data && !this.closing && !this.closed) this._registerBlobCore(id, data.stamp || 0)
+            })
+            .catch(safetyCatch)
+          return
+        }
+        const key = this._blobCoreKey(stamp)
+        if (!key) return // unknown epoch — this device is not entitled to the core
+        this.root._coreKeys.set(hex, key)
+      }
+      // remember which handle read it, so close prunes the entry
+      if (this !== this.root) (this._blobKeys ??= new Set()).add(hex)
+    } catch {
+      // ignore invalid ids
+    }
+  }
+
+  // base-era cores use the OWNING handle's key, rooms have their own
+  _blobCoreKey(stamp) {
+    if (!stamp) return this.store.encryptionKey
+    const entropy = this.store.keyring.entropy(stamp)
+    return entropy ? blobEpochKey(entropy) : null
+  }
+
+  async _syncInvites() {
+    if (!this.pair) return
+    const { data } = await this.store.get('invites')
+    this.pair.syncRows(data || [])
+  }
+
   // `grants` treats an unknown role as "no", so an app role name must fail loudly
   async _checkGrant(role) {
     if (!isRank(role)) {
@@ -593,21 +606,8 @@ export class Handle extends ReadyResource {
   }
 
   /**
-   * 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: hid.encode(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.
+   * 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]
@@ -635,8 +635,7 @@ export class Handle extends ReadyResource {
       child.name = name
 
       const id = hid.encode(child.store.key)
-      // add-handle makes the row visible before this create finishes, and a
-      // duplicate Handle over the same core deadlocks in ready()
+      // add-handle makes the row visible before create finishes; a second Handle on the same core deadlocks
       const inflight = new Promise((resolve, reject) => {
         publish = resolve
         abort = reject
@@ -691,9 +690,7 @@ export class Handle extends ReadyResource {
   }
 
   /**
-   * Join a child handle by invite (joiner-flow). Waits for writer
-   * capability and registers the child on the parent's `handles`
-   * collection.
+   * Join a child handle by invite (joiner-flow).
    *
    * @param {string} invite
    * @param {string} type
@@ -726,10 +723,8 @@ export class Handle extends ReadyResource {
   async _pair(invite, type, { routes, timeout } = {}, target = null) {
     const deadline = timeout || TIMEOUT
 
-    // idempotent while our stored writer is still admitted, so no waiting on a
-    // peer to confirm. A removed writer's core is frozen and reusing its keypair
-    // only gets it re-removed, so fall through to a real pairing, which mints a
-    // fresh keypair. A member row outlives a revoked device, so test the device.
+    // a stored writer still admitted reopens without waiting; a removed writer's core is
+    // frozen, so fall through to a real pairing and a fresh keypair
     if (target) {
       const { data: joined } = await this.store.get('handles')
       const existing = joined.find(
@@ -801,9 +796,8 @@ export class Handle extends ReadyResource {
   }
 
   /**
-   * Get an open child by id, or re-open it. Concurrent calls for the same id
-   * share one in-flight load, so the child is built — and `handle` emitted —
-   * exactly once.
+   * Get an open child by id, or re-open it. Concurrent calls for the same id share one
+   * in-flight load, so the child is built — and `handle` emitted — exactly once.
    *
    * @param {string} type
    * @param {string} id
@@ -864,15 +858,6 @@ export class Handle extends ReadyResource {
     return child
   }
 
-  /**
-   * Pause networking + storage. Idempotent; no-op on child handles.
-   *
-   * @returns {Promise<void>}
-   */
-  async suspend() {
-    if (this._sus) await this._sus.suspend()
-  }
-
   async _suspend() {
     if (this.closing || this.closed) return
     await Promise.all([...this.children].map((c) => c.pair?.suspend()))
@@ -885,15 +870,6 @@ export class Handle extends ReadyResource {
     }
   }
 
-  /**
-   * Resume a suspended root handle. Idempotent; no-op on child handles.
-   *
-   * @returns {Promise<void>}
-   */
-  async resume() {
-    if (this._sus) await this._sus.resume()
-  }
-
   async _resume() {
     if (this.closing || this.closed) return
     try {
@@ -906,6 +882,45 @@ export class Handle extends ReadyResource {
     await Promise.all([...this.children].map((child) => child.pair?.resume()))
   }
 
+  /**
+   * @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
+    }
+  }
+
   /**
    * Pair into an existing handle via an invite, returning a brand-new
    * `Handle` already configured with the resolved key + encryption key.
@@ -926,8 +941,7 @@ export class Handle extends ReadyResource {
     if (!spec) throw CeroError.REQUIRED('spec')
 
     const writer = Identity.randomKeyPair()
-    // join-only: no member listener, so concurrent joins never collide on the
-    // identity-derived default topic ('Active member already exist')
+    // join-only: a member listener here would collide with concurrent joins on the identity topic
     const pair = new Pairing({ network: net, identity: id, host: false })
     await pair.ready()
 
@@ -963,45 +977,6 @@ export class Handle extends ReadyResource {
       keyPair: writer
     })
   }
-
-  /**
-   * @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) {